cowboy_http(3)

Name

cowboy_http - HTTP/1.1

Description

The module cowboy_http implements HTTP/1.1 and HTTP/1.0 as a Ranch protocol.

Options

opts() :: #{
    active_n                   => pos_integer(),
    alpn_default_protocol      => http | http2,
    chunked                    => boolean(),
    connection_type            => worker | supervisor,
    dynamic_buffer             => false | {pos_integer(), pos_integer()},
    hibernate                  => boolean(),
    http10_keepalive           => boolean(),
    idle_timeout               => timeout(),
    inactivity_timeout         => timeout(),
    initial_stream_flow_size   => non_neg_integer(),
    linger_timeout             => timeout(),
    logger                     => module(),
    max_empty_lines            => non_neg_integer(),
    max_header_name_length     => non_neg_integer(),
    max_header_value_length    => non_neg_integer(),
    max_headers                => non_neg_integer(),
    max_keepalive              => non_neg_integer(),
    max_method_length          => non_neg_integer(),
    max_request_line_length    => non_neg_integer(),
    max_skip_body_length       => non_neg_integer(),
    protocols                  => [http | http2],
    proxy_header               => boolean(),
    request_timeout            => timeout(),
    reset_idle_timeout_on_send => boolean(),
    sendfile                   => boolean(),
    stream_handlers            => [module()]
}

Configuration for the HTTP/1.1 protocol.

This configuration is passed to Cowboy when starting listeners using cowboy:start_clear/3 or cowboy:start_tls/3 functions.

It can be updated without restarting listeners using the Ranch functions ranch:get_protocol_options/1 and ranch:set_protocol_options/2.

The default value is given next to the option name:

active_n (1)

The number of packets Cowboy will request from the socket at once. This can be used to tweak the performance of the server. Higher values reduce the number of times Cowboy need to request more packets from the port driver at the expense of potentially higher memory being used.

alpn_default_protocol (http)

Default protocol to use when the client connects over TLS without ALPN. Can be set to http2 to disable HTTP/1.1 entirely.

chunked (true)

Whether chunked transfer-encoding is enabled for HTTP/1.1 connections. Note that a response streamed to the client without the chunked transfer-encoding and without a content-length header will result in the connection being closed at the end of the response body.

This option can be updated at any time using the set_options stream handler command.

connection_type (supervisor)

Whether the connection process also acts as a supervisor.

dynamic_buffer ({1024, 131072})

Cowboy will dynamically change the socket's buffer size depending on the size of the data it receives from the socket. This lets Cowboy use the optimal buffer size for the current workload.

The dynamic buffer size functionality can be disabled by setting this option to false. Cowboy will also disable it by default when the buffer transport option is configured.

hibernate (false)

Whether the connection process will hibernate automatically.

http10_keepalive (true)

Whether keep-alive is enabled for HTTP/1.0 connections.

idle_timeout (60000)

Time in ms with no data received before Cowboy closes the connection.

This option can be updated at any time using the set_options stream handler command.

inactivity_timeout (300000)

DEPRECATED** Time in ms with nothing received at all before Cowboy closes the connection.

initial_stream_flow_size (65535)

Amount of data in bytes Cowboy will read from the socket right after a request was fully received. This is a soft limit.

linger_timeout (1000)

Time in ms that Cowboy will wait when closing the connection. This is necessary to avoid the TCP reset problem as described in the section 6.6 of RFC7230.

logger (error_logger)

The module that will be used to write log messages.

max_empty_lines (5)

Maximum number of empty lines before a request.

max_header_name_length (64)

Maximum length of header names.

max_header_value_length (4096)

Maximum length of header values.

max_headers (100)

Maximum number of headers allowed per request.

max_keepalive (1000)

Maximum number of requests allowed per connection.

max_method_length (32)

Maximum length of the method.

max_request_line_length (8000)

Maximum length of the request line.

max_skip_body_length (1000000)

Maximum length Cowboy is willing to skip when the user code did not read the body fully. When the remaining length is too large or unknown Cowboy will close the connection.

protocols ([http2, http])

Protocols that may be used when the client connects over cleartext TCP. The default is to allow both HTTP/1.1 and HTTP/2. HTTP/1.1 and HTTP/2 can be disabled entirely by omitting them from the list.

proxy_header (false)

Whether incoming connections have a PROXY protocol header. The proxy information will be passed forward via the proxy_header key of the Req object.

request_timeout (5000)

Time in ms with no requests before Cowboy closes the connection.

reset_idle_timeout_on_send (false)

Whether the idle_timeout gets reset when sending data to the socket.

sendfile (true)

Whether the sendfile syscall may be used. It can be useful to disable it on systems where the syscall has a buggy implementation, for example under VirtualBox when using shared folders.

stream_handlers ([cowboy_stream_h])

Ordered list of stream handlers that will handle all stream events.

Changelog

• 2.13: The inactivity_timeout option was deprecated.
• 2.13: The active_n default value was changed to 1.
• 2.13: The dynamic_buffer and hibernate options were added.
• 2.11: The reset_idle_timeout_on_send option was added.
• 2.8: The active_n option was added.
• 2.7: The initial_stream_flow_size and logger options were added.
• 2.6: The chunked, http10_keepalive, proxy_header and sendfile options were added.
• 2.5: The linger_timeout option was added.
• 2.2: The max_skip_body_length option was added.
• 2.0: The timeout option was renamed request_timeout.
• 2.0: The idle_timeout, inactivity_timeout and shutdown_timeout options were added.
• 2.0: The max_method_length option was added.
• 2.0: The max_request_line_length default was increased from 4096 to 8000.
• 2.0: The connection_type option was added.
• 2.0: The env option is now a map instead of a proplist.
• 2.0: The stream_handlers option was added.
• 2.0: The compress option was removed in favor of the cowboy_compress_h stream handler.
• 2.0: Options are now a map instead of a proplist.
• 2.0: Protocol introduced. Replaces cowboy_protocol.

See also

cowboy(7), cowboy_http2(3), cowboy_websocket(3)