= 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

// @todo Might be worth moving cowboy_clear/tls options
// to their respective manual, when they are added.

[source,erlang]
----
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(),
    invalid_response_headers   => error_terminate | ignore,
    linger_timeout             => timeout(),
    logger                     => module(),
    max_authorization_header_value_length => non_neg_integer(),
    max_cookie_header_value_length        => non_neg_integer(),
    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.

invalid_response_headers (error_terminate)::

Prevent sending HTTP responses with invalid response headers.
The default `error_terminate` will result in an HTTP 500
response sent when invalid response headers are detected,
except when the invalid headers are trailer headers: in that
case the connection is dropped. When set to `ignore` the
check is not performed at all: use at your own risk.

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
https://tools.ietf.org/html/rfc7230#section-6.6[section 6.6 of RFC7230].

logger (error_logger)::

The module that will be used to write log messages.

max_authorization_header_value_length::

Maximum length of the `authorization` header value.
Defaults to the value of the option `max_header_value_length`.

max_cookie_header_value_length::

Maximum length of the `cookie` header value.
Defaults to the value of the option `max_header_value_length`.

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.16*: The `invalid_response_headers` option was added.
* *2.15*: The `max_authorization_header_value_length` and `max_cookie_header_value_length` options were added.
* *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

link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_http2(3)[cowboy_http2(3)],
link:man:cowboy_websocket(3)[cowboy_websocket(3)]
