cowboy_stream_h(3)

Name

cowboy_stream_h - Default stream handler

Description

The module cowboy_stream_h is Cowboy's default stream handler and defines much of its behavior. It is responsible for managing the request process, sending it the request body and translating its messages into commands that Cowboy understands.

Options

opts() :: #{
    env              => cowboy_middleware:env(),
    middlewares      => [module()],
    shutdown_timeout => timeout()
}

Configuration for the default stream handler.

The default value is given next to the option name:

env (#{})

Middleware environment.

middlewares ([cowboy_router, cowboy_handler])

Middlewares to run for every request.

shutdown_timeout (5000)

Time in ms Cowboy will wait for child processes to shut down before killing them.

Events

The default stream handler spawns the request process and receives its exit signal when it terminates. It will stop the stream once its receives it.

Because this stream handler converts events from the request process into commands, other stream handlers may not work properly if they are executed after the default stream handler. Always be mindful of in which order stream handlers will get executed.

Request body

The default stream handler implements the read_body mechanism. In addition to reading the body, the handler will automatically handle the expect: 100-continue header and send a 100 Continue response.

Normally one would use cowboy_req:read_body(3) to read the request body. The default stream handler will buffer data until the amount gets larger than the requested length before sending it. Alternatively, it will send whatever data it has when the period timeout triggers. Depending on the protocol, the flow control window is updated to allow receiving data for the requested length.

The default stream handler also comes with an automatic mode for reading the request body. This can be used by sending the event message {read_body, Pid, Ref, auto, infinity} using cowboy_req:cast(3). The default stream handler will then send data as soon as some becomes available using one of these two messages depending on whether body reading was completed:

• {request_body, Ref, nofin, Data}
• {request_body, Ref, fin, BodyLen, Data}

Depending on the protocol, Cowboy will update the flow control window using the size of the data that was read.

Auto mode automatically gets disabled after data has been sent to the handler. Therefore in order to continue reading data a read_body event message must be sent after each request_body message.

Response

In addition it returns a command for any event message looking like one of the following commands: inform, response, headers, data, trailers, push, switch_protocol. This is what allows the request process to send a response.

Changelog

• 2.11: Introduce body reading using auto mode.
• 2.0: Module introduced.

See also

cowboy(7), cowboy_stream(3), cowboy_compress_h(3), cowboy_decompress_h(3), cowboy_metrics_h(3), cowboy_tracer_h(3), cowboy_req:cast(3)