From 8459bebceb9533948193774371cbd9fd571b78ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 16 Oct 2019 09:48:31 +0200 Subject: Cowboy 2.7.0 --- .../en/cowboy/2.7/manual/cowboy.set_env/index.html | 211 +++++++ .../2.7/manual/cowboy.start_clear/index.html | 229 +++++++ .../cowboy/2.7/manual/cowboy.start_tls/index.html | 234 ++++++++ .../2.7/manual/cowboy.stop_listener/index.html | 194 ++++++ docs/en/cowboy/2.7/manual/cowboy/index.html | 228 +++++++ docs/en/cowboy/2.7/manual/cowboy_app/index.html | 239 ++++++++ .../cowboy/2.7/manual/cowboy_compress_h/index.html | 195 ++++++ .../2.7/manual/cowboy_constraints.int/index.html | 204 +++++++ .../manual/cowboy_constraints.nonempty/index.html | 203 +++++++ .../2.7/manual/cowboy_constraints/index.html | 195 ++++++ .../2.7/manual/cowboy_handler.terminate/index.html | 206 +++++++ .../en/cowboy/2.7/manual/cowboy_handler/index.html | 198 +++++++ docs/en/cowboy/2.7/manual/cowboy_http/index.html | 292 +++++++++ docs/en/cowboy/2.7/manual/cowboy_http2/index.html | 308 ++++++++++ docs/en/cowboy/2.7/manual/cowboy_loop/index.html | 212 +++++++ .../cowboy/2.7/manual/cowboy_metrics_h/index.html | 289 +++++++++ .../cowboy/2.7/manual/cowboy_middleware/index.html | 209 +++++++ .../2.7/manual/cowboy_req.binding/index.html | 212 +++++++ .../2.7/manual/cowboy_req.bindings/index.html | 192 ++++++ .../2.7/manual/cowboy_req.body_length/index.html | 193 ++++++ .../cowboy/2.7/manual/cowboy_req.cast/index.html | 204 +++++++ .../cowboy/2.7/manual/cowboy_req.cert/index.html | 212 +++++++ .../cowboy_req.delete_resp_header/index.html | 197 ++++++ .../manual/cowboy_req.filter_cookies/index.html | 200 +++++++ .../2.7/manual/cowboy_req.has_body/index.html | 190 ++++++ .../2.7/manual/cowboy_req.has_resp_body/index.html | 195 ++++++ .../manual/cowboy_req.has_resp_header/index.html | 198 +++++++ .../cowboy/2.7/manual/cowboy_req.header/index.html | 219 +++++++ .../2.7/manual/cowboy_req.headers/index.html | 199 +++++++ .../cowboy/2.7/manual/cowboy_req.host/index.html | 199 +++++++ .../2.7/manual/cowboy_req.host_info/index.html | 193 ++++++ .../cowboy/2.7/manual/cowboy_req.inform/index.html | 217 +++++++ .../2.7/manual/cowboy_req.match_cookies/index.html | 220 +++++++ .../2.7/manual/cowboy_req.match_qs/index.html | 219 +++++++ .../cowboy/2.7/manual/cowboy_req.method/index.html | 210 +++++++ .../2.7/manual/cowboy_req.parse_cookies/index.html | 218 +++++++ .../2.7/manual/cowboy_req.parse_header/index.html | 370 ++++++++++++ .../2.7/manual/cowboy_req.parse_qs/index.html | 207 +++++++ .../cowboy/2.7/manual/cowboy_req.path/index.html | 199 +++++++ .../2.7/manual/cowboy_req.path_info/index.html | 193 ++++++ .../cowboy/2.7/manual/cowboy_req.peer/index.html | 203 +++++++ .../cowboy/2.7/manual/cowboy_req.port/index.html | 200 +++++++ .../cowboy/2.7/manual/cowboy_req.push/index.html | 226 +++++++ docs/en/cowboy/2.7/manual/cowboy_req.qs/index.html | 199 +++++++ .../index.html | 250 ++++++++ .../2.7/manual/cowboy_req.read_body/index.html | 224 +++++++ .../2.7/manual/cowboy_req.read_part/index.html | 246 ++++++++ .../manual/cowboy_req.read_part_body/index.html | 222 +++++++ .../cowboy_req.read_urlencoded_body/index.html | 216 +++++++ .../cowboy/2.7/manual/cowboy_req.reply/index.html | 238 ++++++++ .../2.7/manual/cowboy_req.resp_header/index.html | 210 +++++++ .../2.7/manual/cowboy_req.resp_headers/index.html | 190 ++++++ .../cowboy/2.7/manual/cowboy_req.scheme/index.html | 204 +++++++ .../2.7/manual/cowboy_req.set_resp_body/index.html | 231 ++++++++ .../manual/cowboy_req.set_resp_cookie/index.html | 256 ++++++++ .../manual/cowboy_req.set_resp_header/index.html | 212 +++++++ .../manual/cowboy_req.set_resp_headers/index.html | 203 +++++++ .../cowboy/2.7/manual/cowboy_req.sock/index.html | 199 +++++++ .../2.7/manual/cowboy_req.stream_body/index.html | 210 +++++++ .../2.7/manual/cowboy_req.stream_events/index.html | 224 +++++++ .../2.7/manual/cowboy_req.stream_reply/index.html | 227 +++++++ .../manual/cowboy_req.stream_trailers/index.html | 207 +++++++ .../en/cowboy/2.7/manual/cowboy_req.uri/index.html | 258 ++++++++ .../2.7/manual/cowboy_req.version/index.html | 199 +++++++ docs/en/cowboy/2.7/manual/cowboy_req/index.html | 380 ++++++++++++ docs/en/cowboy/2.7/manual/cowboy_rest/index.html | 658 +++++++++++++++++++++ .../2.7/manual/cowboy_router.compile/index.html | 200 +++++++ docs/en/cowboy/2.7/manual/cowboy_router/index.html | 217 +++++++ docs/en/cowboy/2.7/manual/cowboy_static/index.html | 275 +++++++++ docs/en/cowboy/2.7/manual/cowboy_stream/index.html | 435 ++++++++++++++ .../cowboy/2.7/manual/cowboy_stream_h/index.html | 199 +++++++ .../cowboy/2.7/manual/cowboy_tracer_h/index.html | 212 +++++++ .../cowboy/2.7/manual/cowboy_websocket/index.html | 353 +++++++++++ .../cowboy/2.7/manual/http_status_codes/index.html | 244 ++++++++ docs/en/cowboy/2.7/manual/index.html | 239 ++++++++ 75 files changed, 17368 insertions(+) create mode 100644 docs/en/cowboy/2.7/manual/cowboy.set_env/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy.start_clear/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy.start_tls/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy.stop_listener/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_app/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_compress_h/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_constraints.int/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_constraints.nonempty/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_constraints/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_handler.terminate/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_handler/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_http/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_http2/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_loop/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_metrics_h/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_middleware/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.binding/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.bindings/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.body_length/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.cast/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.cert/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.delete_resp_header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.filter_cookies/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.has_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.has_resp_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.has_resp_header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.headers/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.host/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.host_info/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.inform/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.match_cookies/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.match_qs/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.method/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.parse_cookies/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.parse_header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.parse_qs/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.path/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.path_info/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.peer/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.port/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.push/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.qs/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.read_and_match_urlencoded_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.read_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.read_part/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.read_part_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.read_urlencoded_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.reply/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.resp_header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.resp_headers/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.scheme/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.set_resp_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.set_resp_cookie/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.set_resp_header/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.set_resp_headers/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.sock/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.stream_body/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.stream_events/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.stream_reply/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.stream_trailers/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.uri/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req.version/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_req/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_rest/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_router.compile/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_router/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_static/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_stream/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_stream_h/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_tracer_h/index.html create mode 100644 docs/en/cowboy/2.7/manual/cowboy_websocket/index.html create mode 100644 docs/en/cowboy/2.7/manual/http_status_codes/index.html create mode 100644 docs/en/cowboy/2.7/manual/index.html (limited to 'docs/en/cowboy/2.7/manual') diff --git a/docs/en/cowboy/2.7/manual/cowboy.set_env/index.html b/docs/en/cowboy/2.7/manual/cowboy.set_env/index.html new file mode 100644 index 00000000..82ebddd5 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy.set_env/index.html @@ -0,0 +1,211 @@ + + + + + + + + + + Nine Nines: cowboy:set_env(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy:set_env(3)

+ +

Name

+

cowboy:set_env - Update a listener's environment value

+

Description

+
+
set_env(Name  :: ranch:ref(),
+        Key   :: atom(),
+        Value :: any())
+    -> ok
+
+

Set or update an environment value for a previously started listener.

+

This is most useful for updating the routes dynamically, without having to restart the listener.

+

The new value will only be available to new connections. Pre-existing connections will still use the old value.

+

Arguments

+
Name
+

The name of the listener to update.

+

The name of the listener is the first argument given to the cowboy:start_clear(3), cowboy:start_tls(3) or ranch:start_listener(3) function.

+
+
Key
+

The key in the environment map. Common keys include dispatch and middlewares.

+
+
Value
+

The new value.

+

The type of the value differs depending on the key.

+
+
+

Return value

+

The atom ok is returned on success.

+

An exit:badarg exception is thrown when the listener does not exist.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Update a listener's routes
+
+
Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []},
+        {"/ws", websocket_h, []}
+    ]}
+]),
+
+cowboy:set_env(example, dispatch, Dispatch).
+
+

See also

+

cowboy(3), cowboy:start_clear(3), cowboy:start_tls(3), ranch:set_protocol_options(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy.start_clear/index.html b/docs/en/cowboy/2.7/manual/cowboy.start_clear/index.html new file mode 100644 index 00000000..0e4ad510 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy.start_clear/index.html @@ -0,0 +1,229 @@ + + + + + + + + + + Nine Nines: cowboy:start_clear(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy:start_clear(3)

+ +

Name

+

cowboy:start_clear - Listen for connections using plain TCP

+

Description

+
+
start_clear(Name          :: ranch:ref(),
+            TransportOpts :: ranch_tcp:opts(),
+            ProtocolOpts  :: opts())
+    -> {ok, ListenerPid :: pid()}
+     | {error, any()}
+
+

Start listening for connections over a clear TCP channel.

+

Both HTTP/1.1 and HTTP/2 are supported on this listener. HTTP/2 has two methods of establishing a connection over a clear TCP channel. Both the upgrade and the prior knowledge methods are supported.

+

Arguments

+
Name
+

The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined.

+

It can be any Erlang term. An atom is generally good enough, for example api, my_app_clear or my_app_tls.

+
+
TransportOpts
+

The transport options are where the TCP options, including the listener's port number, are defined. Transport options are provided as a list of keys and values, for example [{port, 8080}].

+

The available options are documented in the ranch_tcp(3) manual.

+
+
ProtocolOpts
+

The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2.

+

The HTTP/1.1 options are documented in the cowboy_http(3) manual; and the HTTP/2 options in cowboy_http2(3).

+
+
+

Return value

+

An ok tuple is returned on success. It contains the pid of the top-level supervisor for the listener.

+

An error tuple is returned on error. The error reason may be any Erlang term.

+

A common error is eaddrinuse. It indicates that the port configured for Cowboy is already in use.

+

Changelog

+
  • 2.0: HTTP/2 support added. +
    • +
  • 2.0: Function introduced. Replaces cowboy:start_http/4. +
    • +
+

Examples

+
Start a listener
+
+
Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []}
+    ]}
+]),
+
+{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{
+    env => #{dispatch => Dispatch}
+}).
+
+
Start a listener on a random port
+
+
Name = example,
+
+{ok, _} = cowboy:start_clear(Name, [], #{
+    env => #{dispatch => Dispatch}
+}),
+
+Port = ranch:get_port(Name).
+
+

See also

+

cowboy(3), cowboy:start_tls(3), cowboy:stop_listener(3), ranch(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy.start_tls/index.html b/docs/en/cowboy/2.7/manual/cowboy.start_tls/index.html new file mode 100644 index 00000000..6dd8fd08 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy.start_tls/index.html @@ -0,0 +1,234 @@ + + + + + + + + + + Nine Nines: cowboy:start_tls(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy:start_tls(3)

+ +

Name

+

cowboy:start_tls - Listen for connections using TLS

+

Description

+
+
start_tls(Name          :: ranch:ref(),
+          TransportOpts :: ranch_ssl:opts(),
+          ProtocolOpts  :: opts())
+    -> {ok, ListenerPid :: pid()}
+     | {error, any()}
+
+

Start listening for connections over a secure TLS channel.

+

Both HTTP/1.1 and HTTP/2 are supported on this listener. The ALPN TLS extension must be used to initiate an HTTP/2 connection.

+

Arguments

+
Name
+

The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined.

+

It can be any Erlang term. An atom is generally good enough, for example api, my_app_clear or my_app_tls.

+
+
TransportOpts
+

The transport options are where the TCP options, including the listener's port number, are defined. They also contain the TLS options, like the server's certificate. Transport options are provided as a list of keys and values, for example [{port, 8443}, {certfile, "path/to/cert.pem"}].

+

The available options are documented in the ranch_ssl(3) manual.

+
+
ProtocolOpts
+

The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2.

+

The HTTP/1.1 options are documented in the cowboy_http(3) manual; and the HTTP/2 options in cowboy_http2(3).

+
+
+

Return value

+

An ok tuple is returned on success. It contains the pid of the top-level supervisor for the listener.

+

An error tuple is returned on error. The error reason may be any Erlang term.

+

A common error is eaddrinuse. It indicates that the port configured for Cowboy is already in use.

+

Changelog

+
  • 2.0: HTTP/2 support added. +
    • +
  • 2.0: Function introduced. Replaces cowboy:start_https/4. +
    • +
+

Examples

+
Start a listener
+
+
Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []}
+    ]}
+]),
+
+{ok, _} = cowboy:start_tls(example, [
+    {port, 8443},
+    {certfile, "path/to/cert.pem"}
+], #{
+    env => #{dispatch => Dispatch}
+}).
+
+
Start a listener on a random port
+
+
Name = example,
+
+{ok, _} = cowboy:start_tls(Name, [
+    {certfile, "path/to/cert.pem"}
+], #{
+    env => #{dispatch => Dispatch}
+}),
+
+Port = ranch:get_port(Name).
+
+

See also

+

cowboy(3), cowboy:start_clear(3), cowboy:stop_listener(3), ranch(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy.stop_listener/index.html b/docs/en/cowboy/2.7/manual/cowboy.stop_listener/index.html new file mode 100644 index 00000000..eb5959de --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy.stop_listener/index.html @@ -0,0 +1,194 @@ + + + + + + + + + + Nine Nines: cowboy:stop_listener(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy:stop_listener(3)

+ +

Name

+

cowboy:stop_listener - Stop the given listener

+

Description

+
+
stop_listener(Name :: ranch:ref())
+    -> ok | {error, not_found}.
+
+

Stop a previously started listener.

+

Alias of ranch:stop_listener(3).

+

Arguments

+
Name
+

The name of the listener to be stopped.

+

The name of the listener is the first argument given to the cowboy:start_clear(3), cowboy:start_tls(3) or ranch:start_listener(3) function.

+
+
+

Return value

+

The atom ok is returned on success.

+

The {error, not_found} tuple is returned when the listener does not exist.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Stop a listener
+
+
ok = cowboy:stop_listener(example).
+
+

See also

+

cowboy(3), cowboy:start_clear(3), cowboy:start_tls(3), ranch(3), ranch:start_listener(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy/index.html b/docs/en/cowboy/2.7/manual/cowboy/index.html new file mode 100644 index 00000000..df3031e1 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy/index.html @@ -0,0 +1,228 @@ + + + + + + + + + + Nine Nines: cowboy(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy(3)

+ +

Name

+

cowboy - HTTP server

+

Description

+

The module cowboy provides convenience functions for manipulating Ranch listeners.

+

Exports

+ +

Types

+

fields()

+
+
fields() :: [Name
+           | {Name, Constraints}
+           | {Name, Constraints, Default}]
+
+Name        :: atom()
+Constraints :: Constraint | [Constraint]
+Constraint  :: cowboy_constraints:constraint()
+Default     :: any()
+
+

Fields description for match operations.

+

This type is used in cowboy_router(3) for matching bindings and in the match functions found in cowboy_req(3).

+

http_headers()

+
+
http_headers() :: #{binary() => iodata()}
+
+

HTTP headers.

+

http_status()

+
+
http_status() :: non_neg_integer() | binary()
+
+

HTTP response status.

+

A binary status can be used to set a reason phrase. Note however that HTTP/2 only sends the status code and drops the reason phrase entirely.

+

http_version()

+
+
http_version() :: 'HTTP/2' | 'HTTP/1.1' | 'HTTP/1.0'
+
+

HTTP version.

+

Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.

+

opts()

+
+
opts() :: map()
+
+

Options for the HTTP/1.1, HTTP/2 and Websocket protocols.

+

The protocol options are in a map containing all the options for the different protocols that may be involved when connecting to the listener, including HTTP/1.1 and HTTP/2.

+

The HTTP/1.1 options are documented in the cowboy_http(3) manual and the HTTP/2 options in cowboy_http2(3).

+

See also

+

cowboy(7), ranch(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_app/index.html b/docs/en/cowboy/2.7/manual/cowboy_app/index.html new file mode 100644 index 00000000..01f26e78 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_app/index.html @@ -0,0 +1,239 @@ + + + + + + + + + + Nine Nines: cowboy(7) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy(7)

+ +

Name

+

cowboy - Small, fast, modern HTTP server for Erlang/OTP

+

Description

+

Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols.

+

Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events.

+

Modules

+

Functions:

+ +

Protocols:

+ +

Handlers:

+ +

Stream handlers:

+ +

Behaviors:

+ +

Middlewares:

+ + +

Dependencies

+
  • ranch(7) - Socket acceptor pool for TCP protocols +
    • +
  • cowlib(7) - Support library for manipulating Web protocols +
    • +
  • ssl - Secure communication over sockets +
    • +
  • crypto - Crypto functions +
    • +
+

All these applications must be started before the cowboy application. To start Cowboy and all dependencies at once:

+
+
{ok, _} = application:ensure_all_started(cowboy).
+
+

Environment

+

The cowboy application does not define any application environment configuration parameters.

+

See also

+

ranch(7), cowlib(7)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_compress_h/index.html b/docs/en/cowboy/2.7/manual/cowboy_compress_h/index.html new file mode 100644 index 00000000..b1a508d9 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_compress_h/index.html @@ -0,0 +1,195 @@ + + + + + + + + + + Nine Nines: cowboy_compress_h(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_compress_h(3)

+ +

Name

+

cowboy_compress_h - Compress stream handler

+

Description

+

The module cowboy_compress_h compresses response bodies automatically when the client supports it. It will not try to compress responses that already have a content encoding.

+

Normal responses will only be compressed when their size is lower than the configured threshold. Streamed responses are always compressed, including when the sendfile command is used. Because the file must be read in memory to be compressed, this module is not suitable for automatically compressing large files.

+

Options

+
+
opts() :: #{
+    compress_buffering => boolean(),
+    compress_threshold => non_neg_integer()
+}
+
+

Configuration for the compress stream handler.

+

The default value is given next to the option name:

+
compress_buffering (false)
+

Whether the output will be buffered. By default no buffering is done to provide maximum compatibility at the cost of a lower compression rate.

+

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

+
+
compress_threshold (300)
+

How large the response body must be to be compressed when the response isn't streamed.

+

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

+
+
+

Events

+

The compress stream handler does not produce any event.

+

Changelog

+
  • 2.6: The options compress_buffering and compress_threshold were added. +
    • +
  • 2.0: Module introduced. +
    • +
+

See also

+

cowboy(7), cowboy_stream(3), cowboy_metrics_h(3), cowboy_stream_h(3), cowboy_tracer_h(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_constraints.int/index.html b/docs/en/cowboy/2.7/manual/cowboy_constraints.int/index.html new file mode 100644 index 00000000..7e307d73 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_constraints.int/index.html @@ -0,0 +1,204 @@ + + + + + + + + + + Nine Nines: cowboy_constraints:int(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_constraints:int(3)

+ +

Name

+

cowboy_constraints:int - Integer constraint

+

Description

+

Constraint functions implement a number of different operations.

+
+
int(forward, Bin) -> {ok, Int} | {error, not_an_integer}
+
+Bin :: binary()
+Int :: integer()
+
+

Validate and convert the text representation of an integer.

+
+
int(reverse, Int) -> {ok, Bin} | {error, not_an_integer}
+
+

Convert an integer back to its text representation.

+
+
int(format_error, Error) -> HumanReadable
+
+Error         :: {not_an_integer, Bin | Int}
+HumanReadable :: iolist()
+
+

Generate a human-readable error message.

+

Arguments

+

Arguments vary depending on the operation. Constraint functions always take the operation type as first argument, and the value as second argument.

+

Return value

+

The return value varies depending on the operation.

+

Changelog

+
  • 2.0: Interface modified to allow for a variety of operations. +
    • +
  • 1.0: Constraint introduced. +
    • +
+

Examples

+

This function is not meant to be called directly.

+

See also

+

cowboy_constraints(3), cowboy_constraints:nonempty(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_constraints.nonempty/index.html b/docs/en/cowboy/2.7/manual/cowboy_constraints.nonempty/index.html new file mode 100644 index 00000000..e91fa9a2 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_constraints.nonempty/index.html @@ -0,0 +1,203 @@ + + + + + + + + + + Nine Nines: cowboy_constraints:nonempty(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_constraints:nonempty(3)

+ +

Name

+

cowboy_constraints:nonempty - Non-empty constraint

+

Description

+

Constraint functions implement a number of different operations.

+
+
nonempty(forward | reverse, <<>>) -> {error, empty}
+
+

Reject empty values.

+
+
nonempty(forward | reverse, Bin) -> {ok, Bin}
+
+Bin :: binary()
+
+

Accept any other binary values.

+
+
nonempty(format_error, Error) -> HumanReadable
+
+Error         :: {empty, Bin}
+HumanReadable :: iolist()
+
+

Generate a human-readable error message.

+

Arguments

+

Arguments vary depending on the operation. Constraint functions always take the operation type as first argument, and the value as second argument.

+

Return value

+

The return value varies depending on the operation.

+

Changelog

+
  • 2.0: Interface modified to allow for a variety of operations. +
    • +
  • 1.0: Constraint introduced. +
    • +
+

Examples

+

This function is not meant to be called directly.

+

See also

+

cowboy_constraints(3), cowboy_constraints:int(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_constraints/index.html b/docs/en/cowboy/2.7/manual/cowboy_constraints/index.html new file mode 100644 index 00000000..c09719be --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_constraints/index.html @@ -0,0 +1,195 @@ + + + + + + + + + + Nine Nines: cowboy_constraints(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_constraints(3)

+ +

Name

+

cowboy_constraints - Constraints

+

Description

+

The module cowboy_constraints defines the built-in constraints in Cowboy and provides an interface for manipulating these constraints.

+

Constraints are functions that define what type of input is allowed. They are used throughout Cowboy, from the router to query strings to cookies.

+

Exports

+

Built-in constraints:

+ +

Types

+

constraint()

+
+
constraint() :: int | nonempty | fun()
+
+

A constraint function.

+

The atom constraints are built-in, see the corresponding function in the exports list above.

+

reason()

+
+
reason() :: {constraint(), Reason, Value}
+
+Reason :: any()
+Value  :: any()
+
+

Reason for the constraint failure.

+

It includes the constraint function in question, a machine-readable error reason and the value that made the constraint fail.

+

See also

+

cowboy(7), cowboy(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_handler.terminate/index.html b/docs/en/cowboy/2.7/manual/cowboy_handler.terminate/index.html new file mode 100644 index 00000000..01417052 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_handler.terminate/index.html @@ -0,0 +1,206 @@ + + + + + + + + + + Nine Nines: cowboy_handler:terminate(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_handler:terminate(3)

+ +

Name

+

cowboy_handler:terminate - Terminate the handler

+

Description

+
+
terminate(Reason, PartialReq, State, Handler) -> ok
+
+Reason     :: any()
+PartialReq :: map()
+State      :: any()
+Handler    :: module()
+
+

Call the optional terminate callback if it is defined.

+

Make sure to use this function at the end of the execution of modules that implement custom handler behaviors.

+

Arguments

+
Reason
+

Reason for termination.

+
+
PartialReq
+

The Req object.

+

It is possible to remove fields from the Req object to save memory when the handler has no concept of requests/responses. The only requirement is that a map is provided.

+
+
State
+

Handler state.

+
+
Handler
+

Handler module.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Terminate a handler normally
+
+
cowboy_handler:terminate(normal, Req, State, Handler).
+
+

See also

+

cowboy_handler(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_handler/index.html b/docs/en/cowboy/2.7/manual/cowboy_handler/index.html new file mode 100644 index 00000000..8c16fc6e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_handler/index.html @@ -0,0 +1,198 @@ + + + + + + + + + + Nine Nines: cowboy_handler(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_handler(3)

+ +

Name

+

cowboy_handler - Plain HTTP handlers

+

Description

+

The cowboy_handler middleware executes the handler selected by the router or any other preceding middleware.

+

This middleware takes the handler module and initial state from the handler and handler_opts environment values, respectively. On completion, it adds a result value to the middleware environment, containing the return value of the terminate/3 callback (if defined) and ok otherwise.

+

This module also defines a callback interface for handling HTTP requests.

+

Callbacks

+

Plain HTTP handlers implement the following interface:

+
+
init(Req, State) -> {ok, Req, State}
+
+terminate(Reason, Req, State) -> ok  %% optional
+
+Req    :: cowboy_req:req()
+State  :: any()
+Reason :: normal
+        | {crash, error | exit | throw, any()}
+
+

These two callbacks are common to all handlers.

+

Plain HTTP handlers do all their work in the init/2 callback. Returning ok terminates the handler. If no response is sent, Cowboy will send a 204 No Content.

+

The optional terminate/3 callback will ultimately be called with the reason for the termination of the handler. Cowboy will terminate the process right after this. There is no need to perform any cleanup in this callback.

+

The following terminate reasons are defined for plain HTTP handlers:

+
normal
+

The connection was closed normally.

+
+
{crash, Class, Reason}
+

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

+
+
+

Exports

+

The following function should be called by modules implementing custom handlers to execute the optional terminate callback:

+ +

See also

+

cowboy(7)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_http/index.html b/docs/en/cowboy/2.7/manual/cowboy_http/index.html new file mode 100644 index 00000000..b0bf56c3 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_http/index.html @@ -0,0 +1,292 @@ + + + + + + + + + + Nine Nines: cowboy_http(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

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() :: #{
+    chunked                  => boolean(),
+    connection_type          => worker | supervisor,
+    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(),
+    proxy_header             => boolean(),
+    request_timeout          => timeout(),
+    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:

+
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.

+
+
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)
+

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 (100)
+

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.

+
+
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.

+
+
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.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)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_http2/index.html b/docs/en/cowboy/2.7/manual/cowboy_http2/index.html new file mode 100644 index 00000000..5dff43ef --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_http2/index.html @@ -0,0 +1,308 @@ + + + + + + + + + + Nine Nines: cowboy_http2(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_http2(3)

+ +

Name

+

cowboy_http2 - HTTP/2

+

Description

+

The module cowboy_http2 implements HTTP/2 as a Ranch protocol.

+

Options

+ + +
+
opts() :: #{
+    connection_type                => worker | supervisor,
+    connection_window_margin_size  => 0..16#7fffffff,
+    connection_window_update_threshold => 0..16#7fffffff,
+    enable_connect_protocol        => boolean(),
+    idle_timeout                   => timeout(),
+    inactivity_timeout             => timeout(),
+    initial_connection_window_size => 65535..16#7fffffff,
+    initial_stream_window_size     => 0..16#7fffffff,
+    logger                         => module(),
+    max_concurrent_streams         => non_neg_integer() | infinity,
+    max_connection_buffer_size     => non_neg_integer(),
+    max_connection_window_size     => 0..16#7fffffff,
+    max_decode_table_size          => non_neg_integer(),
+    max_encode_table_size          => non_neg_integer(),
+    max_frame_size_received        => 16384..16777215,
+    max_frame_size_sent            => 16384..16777215 | infinity,
+    max_received_frame_rate        => {pos_integer(), timeout()},
+    max_reset_stream_rate          => {pos_integer(), timeout()},
+    max_stream_buffer_size         => non_neg_integer(),
+    max_stream_window_size         => 0..16#7fffffff,
+    preface_timeout                => timeout(),
+    proxy_header                   => boolean(),
+    sendfile                       => boolean(),
+    settings_timeout               => timeout(),
+    stream_handlers                => [module()],
+    stream_window_data_threshold   => 0..16#7fffffff,
+    stream_window_margin_size      => 0..16#7fffffff,
+    stream_window_update_threshold => 0..16#7fffffff
+}
+
+

Configuration for the HTTP/2 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:

+
connection_type (supervisor)
+

Whether the connection process also acts as a supervisor.

+
+
connection_window_margin_size (65535)
+

Extra amount in bytes to be added to the window size when updating the connection window. This is used to ensure that there is always some space available in the window.

+
+
connection_window_update_threshold (163840)
+

The connection window will only get updated when its size becomes lower than this threshold, in bytes. This is to avoid sending too many WINDOW_UPDATE frames.

+
+
enable_connect_protocol (false)
+

Whether to enable the extended CONNECT method to allow protocols like Websocket to be used over an HTTP/2 stream. This option is experimental and disabled by default.

+
+
idle_timeout (60000)
+

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

+
+
inactivity_timeout (300000)
+

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

+
+
initial_connection_window_size (65535)
+

Initial window size in bytes for the connection. This is the total amount of data (from request bodies for example) that may be buffered by the connection across all streams before the user code explicitly requests it.

+

Note that this value cannot be lower than the default.

+
+
initial_stream_window_size (65535)
+

Initial window size in bytes for new streams. This is the total amount of data (from request bodies for example) that may be buffered by a single stream before the user code explicitly requests it.

+
+
logger (error_logger)
+

The module that will be used to write log messages.

+
+
max_concurrent_streams (infinity)
+

Maximum number of concurrent streams allowed on the connection.

+
+
max_connection_buffer_size (16000000)
+

Maximum size of all stream buffers for this connection, in bytes. This is a soft limit used to apply backpressure to handlers that send data faster than the HTTP/2 connection allows.

+
+
max_connection_window_size (16#7fffffff)
+

Maximum connection window size in bytes. This is used as an upper bound when calculating the window size, either when reading the request body or receiving said body.

+
+
max_decode_table_size (4096)
+

Maximum header table size in bytes used by the decoder. This is the value advertised to the client. The client can then choose a header table size equal or lower to the advertised value.

+
+
max_encode_table_size (4096)
+

Maximum header table size in bytes used by the encoder. The server will compare this value to what the client advertises and choose the smallest one as the encoder's header table size.

+
+
max_frame_size_received (16384)
+

Maximum size in bytes of the frames received by the server. This value is advertised to the remote endpoint which can then decide to use any value lower or equal for its frame sizes.

+
+
max_frame_size_sent (infinity)
+

Maximum size in bytes of the frames sent by the server. This option allows setting an upper limit to the frame sizes instead of blindly following the client's advertised maximum.

+

Note that actual frame sizes may be lower than the limit when there is not enough space left in the flow control window.

+
+
max_received_frame_rate ({1000, 10000})
+

Maximum frame rate allowed per connection. The rate is expressed as a tuple {NumFrames, TimeMs} indicating how many frames are allowed over the given time period. This is similar to a supervisor restart intensity/period.

+
+
max_reset_stream_rate ({10, 10000})
+

Maximum reset stream rate per connection. This can be used to protect against misbehaving or malicious peers that do not follow the protocol, leading to the server resetting streams, by limiting the number of streams that can be reset over a certain time period. The rate is expressed as a tuple {NumResets, TimeMs}. This is similar to a supervisor restart intensity/period.

+
+
max_stream_buffer_size (8000000)
+

Maximum stream buffer size in bytes. This is a soft limit used to apply backpressure to handlers that send data faster than the HTTP/2 connection allows.

+
+
max_stream_window_size (16#7fffffff)
+

Maximum stream window size in bytes. This is used as an upper bound when calculating the window size, either when reading the request body or receiving said body.

+
+
preface_timeout (5000)
+

Time in ms Cowboy is willing to wait for the connection preface.

+
+
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.

+
+
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.

+
+
settings_timeout (5000)
+

Time in ms Cowboy is willing to wait for a SETTINGS ack.

+
+
stream_handlers ([cowboy_stream_h])
+

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

+
+
stream_window_data_threshold (16384)
+

Window threshold in bytes below which Cowboy will not attempt to send data, with one exception. When Cowboy has data to send and the window is high enough, Cowboy will always send the data, regardless of this option.

+
+
stream_window_margin_size (65535)
+

Extra amount in bytes to be added to the window size when updating a stream's window. This is used to ensure that there is always some space available in the window.

+
+
stream_window_update_threshold (163840)
+

A stream's window will only get updated when its size becomes lower than this threshold, in bytes. This is to avoid sending too many WINDOW_UPDATE frames.

+
+
+

Changelog

+
  • 2.7: Add the options connection_window_margin_size, connection_window_update_threshold, max_connection_window_size, max_stream_window_size, stream_window_margin_size and stream_window_update_threshold to configure behavior on sending WINDOW_UPDATE frames; max_connection_buffer_size and max_stream_buffer_size to apply backpressure when sending data too fast; max_received_frame_rate and max_reset_stream_rate to protect against various flood scenarios; and stream_window_data_threshold to control how small the DATA frames that Cowboy sends can get. +
    • +
  • 2.7: The logger option was added. +
    • +
  • 2.6: The proxy_header and sendfile options were added. +
    • +
  • 2.4: Add the options initial_connection_window_size, initial_stream_window_size, max_concurrent_streams, max_decode_table_size, max_encode_table_size, max_frame_size_received, max_frame_size_sent and settings_timeout to configure HTTP/2 SETTINGS and related behavior. +
    • +
  • 2.4: Add the experimental option enable_connect_protocol. +
    • +
  • 2.0: Protocol introduced. +
    • +
+

See also

+

cowboy(7), cowboy_http(3), cowboy_websocket(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_loop/index.html b/docs/en/cowboy/2.7/manual/cowboy_loop/index.html new file mode 100644 index 00000000..fa10b6d1 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_loop/index.html @@ -0,0 +1,212 @@ + + + + + + + + + + Nine Nines: cowboy_loop(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_loop(3)

+ +

Name

+

cowboy_loop - Loop handlers

+

Description

+

The module cowboy_loop defines a callback interface for long running HTTP connections.

+

You should switch to this behavior for long polling, server-sent events and similar long-running requests.

+

There are generally two usage patterns:

+
  • Loop until receiving a specific message, then send a response and stop execution (for example long polling); +
    • +
  • Or initiate a response in init/2 and stream the body in info/3 as necessary (for example server-sent events). +
    • +
+

Callbacks

+

Loop handlers implement the following interface:

+
+
init(Req, State)
+    -> {cowboy_loop, Req, State}
+     | {cowboy_loop, Req, State, hibernate}
+
+info(Info, Req, State)
+    -> {ok, Req, State}
+     | {ok, Req, State, hibernate}
+     | {stop, Req, State}
+
+terminate(Reason, Req, State) -> ok  %% optional
+
+Req    :: cowboy_req:req()
+State  :: any()
+Info   :: any()
+Reason :: stop
+        | {crash, error | exit | throw, any()}
+
+

The init/2 callback is common to all handlers. To switch to the loop behavior, it must return cowboy_loop as the first element of the tuple.

+

The info/3 callback will be called for every Erlang message received. It may choose to continue the receive loop or stop it.

+

The optional terminate/3 callback will ultimately be called with the reason for the termination of the handler. Cowboy will terminate the process right after this. There is no need to perform any cleanup in this callback.

+

The following terminate reasons are defined for loop handlers:

+
stop
+

The handler requested to close the connection by returning a stop tuple.

+
+
{crash, Class, Reason}
+

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

+
+
+

Changelog

+
  • 2.0: Loop handlers no longer need to handle overflow/timeouts. +
    • +
  • 1.0: Behavior introduced. +
    • +
+

See also

+

cowboy(7), cowboy_handler(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_metrics_h/index.html b/docs/en/cowboy/2.7/manual/cowboy_metrics_h/index.html new file mode 100644 index 00000000..0fab9a72 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_metrics_h/index.html @@ -0,0 +1,289 @@ + + + + + + + + + + Nine Nines: cowboy_metrics_h(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_metrics_h(3)

+ +

Name

+

cowboy_metrics_h - Metrics stream handler

+

Description

+

The module cowboy_metrics_h gathers metrics and other information about a stream. It then calls the configured callback with this data.

+

Types

+

metrics()

+
+
metrics() :: #{
+    %% The identifier for this listener.
+    ref := ranch:ref(),
+
+    %% The pid for this connection.
+    pid := pid(),
+
+    %% The streamid also indicates the total number of requests on
+    %% this connection (StreamID div 2 + 1).
+    streamid := cowboy_stream:streamid(),
+
+    %% The terminate reason is always useful.
+    reason := cowboy_stream:reason(),
+
+    %% A filtered Req object or a partial Req object
+    %% depending on how far the request got to.
+    req => cowboy_req:req(),
+    partial_req => cowboy_stream:partial_req(),
+
+    %% Response status.
+    resp_status := cowboy:http_status(),
+
+    %% Filtered response headers.
+    resp_headers := cowboy:http_headers(),
+
+    %% Start/end of the processing of the request.
+    %%
+    %% This represents the time from this stream handler's init
+    %% to terminate.
+    req_start => integer(),
+    req_end => integer(),
+
+    %% Start/end of the receiving of the request body.
+    %% Begins when the first packet has been received.
+    req_body_start => integer(),
+    req_body_end => integer(),
+
+    %% Start/end of the sending of the response.
+    %% Begins when we send the headers and ends on the final
+    %% packet of the response body. If everything is sent at
+    %% once these values are identical.
+    resp_start => integer(),
+    resp_end => integer(),
+
+    %% For early errors all we get is the time we received it.
+    early_error_time => integer(),
+
+    %% Start/end of spawned processes. This is where most of
+    %% the user code lies, excluding stream handlers. On a
+    %% default Cowboy configuration there should be only one
+    %% process: the request process.
+    procs => ProcMetrics,
+
+    %% Informational responses sent before the final response.
+    informational => [InformationalMetrics],
+
+    %% Length of the request and response bodies. This does
+    %% not include the framing.
+    req_body_length => non_neg_integer(),
+    resp_body_length => non_neg_integer(),
+
+    %% Additional metadata set by the user.
+    user_data => map()
+}
+
+InformationalMetrics :: #{
+    %% Informational response status.
+    status := cowboy:http_status(),
+
+    %% Headers sent with the informational response.
+    headers := cowboy:http_headers(),
+
+    %% Time when the informational response was sent.
+    time := integer()
+}
+
+ProcMetrics :: #{pid() => #{
+    %% Time at which the process spawned.
+    spawn := integer(),
+
+    %% Time at which the process exited.
+    exit => integer(),
+
+    %% Reason for the process exit.
+    reason => any()
+}}
+
+

Metrics given to the callback function.

+

Depending on the life of the stream the metrics may include more or less information.

+

The set_options command can be used to add additional metadata in the user_data metric. This can be used for example to add the handler module which was selected by the router. The option to be set is metrics_user_data. It takes a map which will be merged in the existing user_data map.

+

Options

+
+
opts() :: #{
+    metrics_callback => fun((metrics()) -> any()),
+    metrics_req_filter => fun((cowboy_req:req()) -> map()),
+    metrics_resp_headers_filter => fun((cowboy:http_headers()) -> cowboy:http_headers())
+}
+
+

Configuration for the metrics stream handler.

+
metrics_callback - mandatory
+

The function that will be called upon completion of the stream. It only takes a single argument, the metrics().

+
+
metrics_req_filter
+

A function applied to the Req to compact it and only keep required information. By default no filtering is done.

+
+
metrics_resp_headers_filter
+

A function applied to the response headers to filter them and only keep required information. By default no filtering is done.

+
+
+

Events

+

The metrics stream handler does not produce any event.

+

Changelog

+
  • 2.7: Module introduced. +
    • +
+

See also

+

cowboy(7), cowboy_stream(3), cowboy_compress_h(3), cowboy_stream_h(3), cowboy_tracer_h(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.7/manual/cowboy_middleware/index.html new file mode 100644 index 00000000..ac6bee47 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_middleware/index.html @@ -0,0 +1,209 @@ + + + + + + + + + + Nine Nines: cowboy_middleware(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_middleware(3)

+ +

Name

+

cowboy_middleware - Middlewares

+

Description

+

The module cowboy_middleware defines a callback interface for Cowboy middlewares.

+

Middlewares process the request sequentially in the order they are configured.

+

Callbacks

+

Middlewares implement the following interface:

+
+
execute(Req, Env)
+    -> {ok, Req, Env}
+     | {suspend, module(), atom(), [any()]}
+     | {stop, Req}
+
+Req :: cowboy_req:req()
+Env :: cowboy_middleware:env()
+
+

The execute/2 is the only callback that needs to be implemented. It must execute the middleware and return with instructions for Cowboy.

+
ok
+

Cowboy should continue processing the request using the returned Req object and environment.

+
+
suspend
+

Cowboy will hibernate the process. When resuming, Cowboy will apply the returned module, function and arguments.

+
+
stop
+

Cowboy will stop middleware execution. No other middleware will be executed. This effectively ends the processing of the request.

+
+
+ +

Types

+

env()

+
+
env() :: #{atom() => any()}
+
+

Middleware environment.

+

A new environment is created for every request. The initial environment contained the user configured environment values (like dispatch for example) plus the listener value which contains the name of the listener for this connection.

+

Middlewares may modify the environment as necessary.

+

Changelog

+
  • 2.0: The env type is now a map instead of a proplist. +
    • +
  • 1.0: Behavior introduced. +
    • +
+

See also

+

cowboy(7)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.binding/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.binding/index.html new file mode 100644 index 00000000..ae1f486e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.binding/index.html @@ -0,0 +1,212 @@ + + + + + + + + + + Nine Nines: cowboy_req:binding(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:binding(3)

+ +

Name

+

cowboy_req:binding - Access a value bound from the route

+

Description

+
+
binding(Name, Req)          -> binding(Name, Req, undefined)
+binding(Name, Req, Default) -> any() | Default
+
+Name    :: atom()
+Req     :: cowboy_req:req()
+Default :: any()
+
+

Return the value for the given binding.

+

Arguments

+
Name
+

Desired binding name as an atom.

+
+
Req
+

The Req object.

+
+
Default
+

Default value returned when the binding is missing.

+
+
+

Return value

+

By default the value is a case sensitive binary string, however constraints may change the type of this value (for example automatically converting numbers to integer).

+

Changelog

+
  • 2.0: Only the value is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the username from the path
+
+
%% Route is "/users/:user"
+Username = cowboy_req:binding(user, Req).
+
+
Get the branch name, with a default
+
+
%% Route is "/log[/:branch]"
+Branch = cowboy_req:binding(branch, Req, <<"master">>)
+
+

See also

+

cowboy_req(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_req:path_info(3), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.bindings/index.html new file mode 100644 index 00000000..acfbb738 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.bindings/index.html @@ -0,0 +1,192 @@ + + + + + + + + + + Nine Nines: cowboy_req:bindings(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:bindings(3)

+ +

Name

+

cowboy_req:bindings - Access all values bound from the route

+

Description

+
+
bindings(Req :: cowboy_req:req()) -> cowboy_router:bindings()
+
+

Return a map containing all bindings.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

By default values are case sensitive binary strings, however constraints may change the type of this value (for example automatically converting numbers to integer).

+

Changelog

+
  • 2.0: Only the values are returned, they are no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get all bindings
+
+
Bindings = cowboy_req:bindings(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:binding(3), cowboy_req:host_info(3), cowboy_req:path_info(3), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.body_length/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.body_length/index.html new file mode 100644 index 00000000..6cfdf5c8 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.body_length/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + Nine Nines: cowboy_req:body_length(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:body_length(3)

+ +

Name

+

cowboy_req:body_length - Body length

+

Description

+
+
body_length(Req :: cowboy_req:req()) -> undefined | non_neg_integer()
+
+

Return the length of the request body.

+

The length is not always known before reading the body. In those cases Cowboy will return undefined. The body length is available after the body has been fully read.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The length of the request body, or undefined if it is not known.

+

Changelog

+
  • 2.0: Only the length is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the body length
+
+
Length = cowboy_req:body_length(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_part(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.cast/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.cast/index.html new file mode 100644 index 00000000..e2371b38 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.cast/index.html @@ -0,0 +1,204 @@ + + + + + + + + + + Nine Nines: cowboy_req:cast(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:cast(3)

+ +

Name

+

cowboy_req:cast - Cast a stream handler event

+

Description

+
+
cast(Event :: any(), Req :: cowboy_req:req()) -> ok
+
+

Cast a stream handler event.

+

The event will be passed to stream handlers through the info/3 callback.

+

Arguments

+
Event
+

The event to be sent to stream handlers.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.7: Function introduced. +
    • +
+

Examples

+
Increase the HTTP/1.1 idle timeout
+
+
cowboy_req:cast({set_options, #{
+    idle_timeout => 3600000
+}}, Req).
+
+
Add user data to metrics
+
cowboy_req:cast({set_options, #{
+    metrics_user_data => #{handler => ?MODULE}
+}}, Req).
+
Enable compression buffering
+
cowboy_req:cast({set_options, #{
+    compress_buffering => true
+}}, Req).
+

See also

+

cowboy_req(3), cowboy_stream(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.cert/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.cert/index.html new file mode 100644 index 00000000..48659d3d --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.cert/index.html @@ -0,0 +1,212 @@ + + + + + + + + + + Nine Nines: cowboy_req:cert(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:cert(3)

+ +

Name

+

cowboy_req:cert - Client TLS certificate

+

Description

+
+
cert(Req :: cowboy_req:req()) -> binary() | undefined
+
+

Return the peer's TLS certificate.

+

Using the default configuration this function will always return undefined. You need to explicitly configure Cowboy to request the client certificate. To do this you need to set the verify transport option to verify_peer:

+
+
{ok, _} = cowboy:start_tls(example, [
+    {port, 8443},
+    {certfile, "path/to/cert.pem"},
+    {verify, verify_peer}
+], #{
+    env => #{dispatch => Dispatch}
+}).
+
+

You may also want to customize the verify_fun function. Please consult the ssl application's manual for more details.

+

TCP connections do not allow a certificate and this function will therefore always return undefined.

+

The certificate can also be obtained using pattern matching:

+
+
#{cert := Cert} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The client TLS certificate.

+

Changelog

+
  • 2.1: Function introduced. +
    • +
+

Examples

+
Get the client TLS certificate.
+
+
Cert = cowboy_req:cert(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:peer(3), cowboy_req:sock(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.delete_resp_header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.delete_resp_header/index.html new file mode 100644 index 00000000..436cce80 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.delete_resp_header/index.html @@ -0,0 +1,197 @@ + + + + + + + + + + Nine Nines: cowboy_req:delete_resp_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:delete_resp_header(3)

+ +

Name

+

cowboy_req:delete_resp_header - Delete a response header

+

Description

+
+
delete_resp_header(Name, Req :: cowboy_req:req()) -> Req
+
+Name :: binary()  %% lowercase; case insensitive
+
+

Delete the given response header.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Arguments

+
Name
+

Header name as a lowercase binary string.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward, otherwise the header will still be sent in the response.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Remove the content-type header from the response
+
+
Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0),
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:has_resp_header(3), cowboy_req:resp_header(3), cowboy_req:resp_headers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.filter_cookies/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.filter_cookies/index.html new file mode 100644 index 00000000..edaba76f --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.filter_cookies/index.html @@ -0,0 +1,200 @@ + + + + + + + + + + Nine Nines: cowboy_req:filter_cookies(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:filter_cookies(3)

+ +

Name

+

cowboy_req:filter_cookies - Filter cookie headers

+

Description

+
+
filter_cookies(Names, Req) -> Req
+
+Names :: [atom() | binary()]
+
+

Filter cookie headers.

+

This function is meant to be used before attempting to parse or match cookies in order to remove cookies that are not relevant and are potentially malformed. Because Cowboy by default crashes on malformed cookies, this function allows processing requests that would otherwise result in a 400 error.

+

Malformed cookies are unfortunately fairly common due to the string-based interface provided by browsers and this function provides a middle ground between Cowboy's strict behavior and chaotic real world use cases.

+

Note that there may still be crashes even after filtering cookies because this function does not correct malformed values. Cookies that have malformed values should probably be unset in an error response or in a redirect.

+

This function can be called even if there are no cookies in the request.

+

Arguments

+
Names
+

The cookies that should be kept.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The Req object is returned with its cookie header value filtered.

+

Changelog

+
  • 2.7: Function introduced. +
    • +
+

Examples

+
Filter then parse cookies
+
+
Req = cowboy_req:filter_cookies([session_id, token], Req0),
+Cookies = cowboy_req:parse_cookies(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:parse_cookies(3), cowboy_req:match_cookies(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.has_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.has_body/index.html new file mode 100644 index 00000000..d42426f8 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.has_body/index.html @@ -0,0 +1,190 @@ + + + + + + + + + + Nine Nines: cowboy_req:has_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:has_body(3)

+ +

Name

+

cowboy_req:has_body - Is there a request body?

+

Description

+
+
has_body(Req :: cowboy_req:req()) -> boolean()
+
+

Return whether the request has a body.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

A boolean indicating whether the request has a body.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Ensure the request has a body
+
+
true = cowboy_req:has_body(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_part(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_body/index.html new file mode 100644 index 00000000..c512200e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_body/index.html @@ -0,0 +1,195 @@ + + + + + + + + + + Nine Nines: cowboy_req:has_resp_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:has_resp_body(3)

+ +

Name

+

cowboy_req:has_resp_body - Is there a response body?

+

Description

+
+
has_resp_body(Req :: cowboy_req:req()) -> boolean()
+
+

Return whether a response body has been set.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

A boolean indicating whether a response body has been set.

+

This function will return false when an empty response body has been set.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Check whether a body has been set
+
+
false = cowboy_req:has_resp_body(Req0),
+Req1 = cowboy_req:set_resp_body(<<"Hello!">>, Req0),
+true = cowboy_req:has_resp_body(Req1),
+Req = cowboy_req:set_resp_body(<<>>, Req1),
+false = cowboy_req:has_resp_body(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_header/index.html new file mode 100644 index 00000000..c8864446 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.has_resp_header/index.html @@ -0,0 +1,198 @@ + + + + + + + + + + Nine Nines: cowboy_req:has_resp_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:has_resp_header(3)

+ +

Name

+

cowboy_req:has_resp_header - Is the given response header set?

+

Description

+
+
has_resp_header(Name, Req :: cowboy_req:req()) -> boolean()
+
+Name :: binary()  %% lowercase; case insensitive
+
+

Return whether the given response header has been set.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Arguments

+
Name
+

Header name as a lowercase binary string.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A boolean indicating whether the given response header has been set.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Check whether the content-type header has been set
+
+
false = cowboy_req:has_resp_header(<<"content-type">>, Req0),
+Req = cowboy_req:set_resp_header(<<"content-type">>, <<"text/html">>, Req0),
+true = cowboy_req:has_resp_header(<<"content-type">>, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:resp_header(3), cowboy_req:resp_headers(3), cowboy_req:delete_resp_header(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.header/index.html new file mode 100644 index 00000000..2942ead0 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.header/index.html @@ -0,0 +1,219 @@ + + + + + + + + + + Nine Nines: cowboy_req:header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:header(3)

+ +

Name

+

cowboy_req:header - HTTP header

+

Description

+
+
header(Name, Req)          -> header(Name, Req, undefined)
+header(Name, Req, Default) -> binary() | Default
+
+Name    :: binary()          %% lowercase; case insensitive
+Req     :: cowboy_req:req()
+Default :: any()
+
+

Return the value for the given HTTP header.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Headers can also be obtained using pattern matching:

+
+
#{headers := #{Name := Value}} = Req.
+
+

Note that this snippet will crash if the header is missing.

+

Arguments

+
Name
+

Desired HTTP header name as a lowercase binary string.

+
+
Req
+

The Req object.

+
+
Default
+

Default value returned when the header is missing.

+
+
+

Return value

+

The header value is returned as a binary string. When the header is missing, the default argument is returned.

+

Changelog

+
  • 2.0: Only the header value is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the accept header
+
+
Accept = cowboy_req:header(<<"accept">>, Req).
+
+
Get the content-length header with a default value
+
+
Length = cowboy_req:header(<<"content-length">>, Req, <<"0">>).
+
+

See also

+

cowboy_req(3), cowboy_req:headers(3), cowboy_req:parse_header(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.headers/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.headers/index.html new file mode 100644 index 00000000..e209c872 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.headers/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:headers(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:headers(3)

+ +

Name

+

cowboy_req:headers - HTTP headers

+

Description

+
+
headers(Req :: cowboy_req:req()) -> cowboy:http_headers()
+
+

Return all request headers.

+

Request headers can also be obtained using pattern matching:

+
+
#{headers := Headers} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

Headers are returned as a map with keys being lowercase binary strings, and values as binary strings.

+

Changelog

+
  • 2.0: Only the headers are returned, they are no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get all headers
+
+
Headers = cowboy_req:headers(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:header(3), cowboy_req:parse_header(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.host/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.host/index.html new file mode 100644 index 00000000..144c1cd3 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.host/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:host(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:host(3)

+ +

Name

+

cowboy_req:host - URI host name

+

Description

+
+
host(Req :: cowboy_req:req()) -> Host :: binary()
+
+

Return the host name of the effective request URI.

+

The host name can also be obtained using pattern matching:

+
+
#{host := Host} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The host name is returned as a lowercase binary string. It is case insensitive.

+

Changelog

+
  • 2.0: Only the host name is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the effective request URI's host name
+
+
Host = cowboy_req:host(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:host_info(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.host_info/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.host_info/index.html new file mode 100644 index 00000000..ddfe78d8 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.host_info/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + Nine Nines: cowboy_req:host_info(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:host_info(3)

+ +

Name

+

cowboy_req:host_info - Access the route's heading host segments

+

Description

+
+
host_info(Req :: cowboy_req:req()) -> cowboy_router:tokens()
+
+

Return the tokens for the heading host segments.

+

This is the part of the host name that was matched using the ... notation.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The tokens are returned as a list of case insensitive binary strings.

+

Changelog

+
  • 2.0: Only the tokens are returned, they are no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the host_info tokens
+
+
HostInfo = cowboy_req:host_info(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:path_info(3), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.inform/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.inform/index.html new file mode 100644 index 00000000..febceef1 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.inform/index.html @@ -0,0 +1,217 @@ + + + + + + + + + + Nine Nines: cowboy_req:inform(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:inform(3)

+ +

Name

+

cowboy_req:inform - Send an informational response

+

Description

+
+
inform(Status, Req :: cowboy_req:req())
+    -> inform(StatusCode, #{}, Req)
+
+inform(Status, Headers, Req :: cowboy_req:req())
+    -> ok
+
+Status  :: cowboy:http_status()
+Headers :: cowboy:http_headers()
+
+

Send an informational response.

+

Informational responses use a status code between 100 and 199. They cannot include a body. This function will not use any of the previously set headers. All headers to be sent must be given directly.

+

Any number of informational responses can be sent as long as they are sent before the proper response. Attempting to use this function after sending a normal response will result in an error.

+

The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Arguments

+
Status
+

The status code for the response.

+
+
Headers
+

The response headers.

+

Header names must be given as lowercase binary strings.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.1: Function introduced. +
    • +
+

Examples

+
Send an informational response
+
+
Req = cowboy_req:inform(102, Req0).
+
+
Send an informational response with headers
+
+
Req = cowboy_req:inform(103, #{
+    <<"link">> => <<"</style.css>; rel=preload; as=style">>,
+    <<"link">> => <<"</script.js>; rel=preload; as=script">>
+}, Req0).
+
+

See also

+

cowboy_req(3), cowboy_req:reply(3), cowboy_req:stream_reply(3), cowboy_req:push(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.match_cookies/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.match_cookies/index.html new file mode 100644 index 00000000..79bdf170 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.match_cookies/index.html @@ -0,0 +1,220 @@ + + + + + + + + + + Nine Nines: cowboy_req:match_cookies(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:match_cookies(3)

+ +

Name

+

cowboy_req:match_cookies - Match cookies against constraints

+

Description

+
+
match_cookies(Fields :: cowboy:fields(), Req :: cowboy_req:req())
+    -> #{atom() => any()}
+
+

Parse the cookies and match specific values against constraints.

+

Cowboy will only return the cookie values specified in the fields list, and ignore all others. Fields can be either the name of the cookie requested; the name along with a list of constraints; or the name, a list of constraints and a default value in case the cookie is missing.

+

This function will crash if the cookie is missing and no default value is provided. This function will also crash if a constraint fails.

+

The name of the cookie must be provided as an atom. The key of the returned map will be that atom. The value may be converted through the use of constraints, making this function able to extract, validate and convert values all in one step.

+

This function will crash on invalid cookie data. How to handle this is explained in details in the manual page for cowboy_req:parse_cookies(3).

+

Arguments

+
Fields
+

Cookies to retrieve.

+

See cowboy(3) for a complete description.

+
+
Req
+

The Req object.

+
+
+

Return value

+

Desired values are returned as a map. The key is the atom that was given in the list of fields, and the value is the optionally converted value after applying constraints.

+

The map contains the same keys that were given in the fields.

+

An exception is triggered when the match fails.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Match fields
+
+
%% ID and Lang are binaries.
+#{id := ID, lang := Lang}
+    = cowboy_req:match_cookies([id, lang], Req).
+
+
Match fields and apply constraints
+
+
%% ID is an integer and Lang a non-empty binary.
+#{id := ID, lang := Lang}
+    = cowboy_req:match_cookies([{id, int}, {lang, nonempty}], Req).
+
+
Match fields with default values
+
+
#{lang := Lang}
+    = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).
+
+

See also

+

cowboy_req(3), cowboy_req:filter_cookies(3), cowboy_req:parse_cookies(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.match_qs/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.match_qs/index.html new file mode 100644 index 00000000..96b06baf --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.match_qs/index.html @@ -0,0 +1,219 @@ + + + + + + + + + + Nine Nines: cowboy_req:match_qs(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:match_qs(3)

+ +

Name

+

cowboy_req:match_qs - Match the query string against constraints

+

Description

+
+
match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req())
+    -> #{atom() => any()}
+
+

Parse the query string and match specific values against constraints.

+

Cowboy will only return the query string values specified in the fields list, and ignore all others. Fields can be either the key requested; the key along with a list of constraints; or the key, a list of constraints and a default value in case the key is missing.

+

This function will crash if the key is missing and no default value is provided. This function will also crash if a constraint fails.

+

The key must be provided as an atom. The key of the returned map will be that atom. The value may be converted through the use of constraints, making this function able to extract, validate and convert values all in one step.

+

Arguments

+
Fields
+

Fields to retrieve from the query string.

+

See cowboy(3) for a complete description.

+
+
Req
+

The Req object.

+
+
+

Return value

+

Desired values are returned as a map. The key is the atom that was given in the list of fields, and the value is the optionally converted value after applying constraints.

+

The map contains the same keys that were given in the fields.

+

An exception is triggered when the match fails.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Match fields
+
+
%% ID and Lang are binaries.
+#{id := ID, lang := Lang}
+    = cowboy_req:match_qs([id, lang], Req).
+
+
Match fields and apply constraints
+
+
%% ID is an integer and Lang a non-empty binary.
+#{id := ID, lang := Lang}
+    = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).
+
+
Match fields with default values
+
+
#{lang := Lang}
+    = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
+
+

See also

+

cowboy_req(3), cowboy_req:qs(3), cowboy_req:parse_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.method/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.method/index.html new file mode 100644 index 00000000..01177f78 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.method/index.html @@ -0,0 +1,210 @@ + + + + + + + + + + Nine Nines: cowboy_req:method(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:method(3)

+ +

Name

+

cowboy_req:method - HTTP method

+

Description

+
+
method(Req :: cowboy_req:req()) -> Method :: binary()
+
+

Return the request's HTTP method.

+

The method can also be obtained using pattern matching:

+
+
#{method := Method} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The request's HTTP method is returned as a binary string. While methods are case sensitive, standard methods are always uppercase.

+

Changelog

+
  • 2.0: Only the method is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Ensure the request's method is GET
+
+
<<"GET">> = cowboy_req:method(Req).
+
+
Allow methods from list
+
+
init(Req, State) ->
+    case lists:member(cowboy_req:method(Req), [<<"GET">>, <<"POST">>]) of
+        true -> handle(Req, State);
+        false -> method_not_allowed(Req, State)
+    end.
+
+

See also

+

cowboy_req(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.parse_cookies/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.parse_cookies/index.html new file mode 100644 index 00000000..3125d7a6 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.parse_cookies/index.html @@ -0,0 +1,218 @@ + + + + + + + + + + Nine Nines: cowboy_req:parse_cookies(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:parse_cookies(3)

+ +

Name

+

cowboy_req:parse_cookies - Parse cookie headers

+

Description

+
+
parse_cookies(Req) -> [{Name, Value}]
+
+Name  :: binary() %% case sensitive
+Value :: binary() %% case sensitive
+
+

Parse cookie headers.

+

Alias for cowboy_req:parse_header(<<"cookie">>, Req).

+

When the cookie header is missing or empty, [] is returned.

+

This function will crash on invalid cookie data. Because invalid cookies are fairly common when dealing with browsers (because of the string interface that the Javascript API provides), it is recommended to filter the cookie header value before attempting to parse it. This can be accomplished by calling the function cowboy_req:filter_cookies(3) first. This does not guarantee that parsing succeeds. If it still fails it is recommended to send an error response or redirect with instructions to delete the relevant cookies:

+
Recover from cookie parsing errors
+
+
Req1 = cowboy_req:filter_cookies([session_id, token], Req0),
+try cowboy_req:parse_cookies(Req1) of
+    Cookies ->
+        do_something(Req1, Cookies)
+catch _:_ ->
+    %% We can't parse the cookies we need, unset them
+    %% otherwise the browser will continue sending them.
+    Req2 = cowboy_req:set_resp_cookie(<<"session_id">>,
+        <<>>, Req1, #{max_age => 0}),
+    Req = cowboy_req:set_resp_cookie(<<"token">>,
+        <<>>, Req2, #{max_age => 0}),
+    cowboy_req:reply(500, Req)
+end.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The cookies are returned as a list of key/values. Keys and values are case sensitive binary strings.

+

Changelog

+
  • 2.0: Only the parsed header value is returned, it is no longer wrapped in a tuple. +
    • +
  • 2.0: Function introduced. Replaces cookie/2,3 and cookies/1. +
    • +
+

Examples

+
Look for a specific cookie
+
+
Cookies = cowboy_req:parse_cookies(Req),
+{_, Token} = lists:keyfind(<<"token">>, 1, Cookies).
+
+

See also

+

cowboy_req(3), cowboy_req:parse_header(3), cowboy_req:filter_cookies(3), cowboy_req:match_cookies(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.parse_header/index.html new file mode 100644 index 00000000..6a27a430 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.parse_header/index.html @@ -0,0 +1,370 @@ + + + + + + + + + + Nine Nines: cowboy_req:parse_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:parse_header(3)

+ +

Name

+

cowboy_req:parse_header - Parse the given HTTP header

+

Description

+
+
parse_header(Name, Req)          -> ParsedValue | Default
+parse_header(Name, Req, Default) -> ParsedValue | Default
+
+Name        :: binary()
+Req         :: cowboy_req:req()
+ParsedValue :: any()
+Default     :: any()
+
+

Parse the given HTTP header.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

The type of the parsed value varies depending on the header. Similarly, the default value when calling cowboy_req:parse_header/2 differs depending on the header.

+

Arguments

+
Name
+

Desired HTTP header name as a lowercase binary string.

+
+
Req
+

The Req object.

+
+
Default
+

Default value returned when the header is missing.

+
+
+

Return value

+

The parsed header value varies depending on the header. When the header is missing, the default argument is returned.

+

Headers

+

The following snippets detail the types returned by the different headers. Unless mentioned otherwise, the default value when the header is missing will be undefined:

+
accept
+
+
parse_header(<<"accept">>, Req)
+    -> [{{Type, SubType, Params}, Quality, AcceptExt}]
+
+Type      :: binary()               %% case insensitive
+SubType   :: binary()               %% case insensitive
+Params    :: [{Key, Value}]
+Quality   :: 0..1000
+AcceptExt :: [Key | {Key, Value}]
+Key       :: binary()               %% case insensitive
+Value     :: binary()               %% case sensitive
+
+
accept-charset, accept-encoding and accept-language
+
+
parse_header(Name, Req) -> [{Value, Quality}]
+
+Name    :: <<"accept-charset">>
+         | <<"accept-encoding">>
+         | <<"accept-language">>
+Value   :: binary()                 %% case insensitive
+Quality :: 0..1000
+
+
authorization
+
+
parse_header(<<"authorization">>, Req)
+    -> {basic, Username :: binary(), Password :: binary()}
+     | {bearer, Token :: binary()}
+     | {digest, [{Key :: binary(), Value :: binary()}]}
+
+ +
content-length
+
+
parse_header(<<"content-length">>, Req) -> non_neg_integer()
+
+

When the content-length header is missing, 0 is returned.

+
content-type
+
+
parse_header(<<"content-type">>, Req)
+    -> {Type, SubType, Params}
+
+Type      :: binary()               %% case insensitive
+SubType   :: binary()               %% case insensitive
+Params    :: [{Key, Value}]
+Key       :: binary()               %% case insensitive
+Value     :: binary()               %% case sensitive;
+
+

Note that the value for the charset parameter is case insensitive and returned as a lowercase binary string.

+
cookie
+
+
parse_header(<<"cookie">>, Req) -> [{Name, Value}]
+
+Name  :: binary()                   %% case sensitive
+Value :: binary()                   %% case sensitive
+
+

When the cookie header is missing, [] is returned.

+

While an empty cookie header is not valid, some clients do send it. Cowboy will in this case also return [].

+
expect
+
+
parse_header(<<"expect">>, Req) -> continue
+
+
if-match and if-none-match
+
+
parse_header(Name, Req)
+    -> '*' | [{weak | strong, OpaqueTag}]
+
+Name      :: <<"if-match">>
+           | <<"if-none-match">>
+OpaqueTag :: binary()               %% case sensitive
+
+
if-modified-since and if-unmodified-since
+
+
parse_header(Name, Req) -> calendar:datetime()
+
+
range
+
+
parse_header(<<"range">>, Req) -> {From, To} | Final
+
+From  :: non_neg_integer()
+To    :: non_neg_integer() | infinity
+Final :: neg_integer()
+
+
sec-websocket-extensions
+
+
parse_header(<<"sec-websocket-extensions">>, Req)
+    -> [{Extension, Params}]
+
+Extension :: binary()               %% case sensitive
+Params    :: [Key | {Key, Value}]
+Key       :: binary()               %% case sensitive
+Value     :: binary()               %% case sensitive
+
+
sec-websocket-protocol and upgrade
+
+
parse_header(Name, Req) -> [Token]
+
+Name  :: <<"sec-websocket-protocol">>
+       | <<"upgrade">>
+Token :: binary()                   %% case insensitive
+
+
x-forwarded-for
+
+
parse_header(<<"x-forwarded-for">>, Req) -> [Token]
+
+Token :: binary()                   %% case sensitive
+
+
Unknown headers
+
+
parse_header(_, Req) -> {undefined, RawValue}
+
+

Changelog

+
  • 2.0: Only the parsed header value is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Parse the accept header with a custom default value
+
+
%% Accept everything when header is missing.
+Accept = cowboy_req:parse_header(<<"accept">>, Req,
+    [{{ <<"*">>, <<"*">>, []}, 1000, []}]).
+
+
Parse the content-length header
+
+
%% Default content-length is 0.
+Length = cowboy_req:header(<<"content-length">>, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:header(3), cowboy_req:headers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.parse_qs/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.parse_qs/index.html new file mode 100644 index 00000000..f868bea1 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.parse_qs/index.html @@ -0,0 +1,207 @@ + + + + + + + + + + Nine Nines: cowboy_req:parse_qs(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:parse_qs(3)

+ +

Name

+

cowboy_req:parse_qs - Parse the query string

+

Description

+
+
parse_qs(Req :: cowboy_req:req())
+    -> [{Key :: binary(), Value :: binary() | true}]
+
+

Parse the query string as a list of key/value pairs.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The parsed query string is returned as a list of key/value pairs. The key is a binary string. The value is either a binary string, or the atom true. Both key and value are case sensitive.

+

The atom true is returned when a key is present in the query string without a value. For example, in the following URIs the key <<"edit">> will always have the value true:

+
  • /posts/42?edit +
    • +
  • /posts/42?edit&exclusive=1 +
    • +
  • /posts/42?exclusive=1&edit +
    • +
  • /posts/42?exclusive=1&edit&from=web +
    • +
+

Changelog

+
  • 2.0: The parsed value is not longer cached in the Req object. +
    • +
  • 2.0: Only the parsed query string is returned, it is no longer wrapped in a tuple. +
    • +
  • 2.0: Function introduced. Replaces qs_val/1 and qs_vals/1. +
    • +
+

Examples

+
Parse the query string and convert the keys to atoms
+
+
ParsedQs = cowboy_req:parse_qs(Req),
+AtomsQs = [{binary_to_existing_atom(K, latin1), V}
+    || {K, V} <- ParsedQs].
+
+

See also

+

cowboy_req(3), cowboy_req:qs(3), cowboy_req:match_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.path/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.path/index.html new file mode 100644 index 00000000..11f8c46d --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.path/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:path(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:path(3)

+ +

Name

+

cowboy_req:path - URI path

+

Description

+
+
path(Req :: cowboy_req:req()) -> Path :: binary()
+
+

Return the path of the effective request URI.

+

The path can also be obtained using pattern matching:

+
+
#{path := Path} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The path is returned as a binary string. It is case sensitive.

+

Changelog

+
  • 2.0: Only the path is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the effective request URI's path
+
+
Path = cowboy_req:path(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:path_info(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.path_info/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.path_info/index.html new file mode 100644 index 00000000..a79d8ca5 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.path_info/index.html @@ -0,0 +1,193 @@ + + + + + + + + + + Nine Nines: cowboy_req:path_info(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:path_info(3)

+ +

Name

+

cowboy_req:path_info - Access the route's trailing path segments

+

Description

+
+
path_info(Req :: cowboy_req:req()) -> cowboy_router:tokens()
+
+

Return the tokens for the trailing path segments.

+

This is the part of the host name that was matched using the ... notation.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The tokens are returned as a list of case sensitive binary strings.

+

Changelog

+
  • 2.0: Only the tokens are returned, they are no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the path_info tokens
+
+
PathInfo = cowboy_req:path_info(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.peer/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.peer/index.html new file mode 100644 index 00000000..3ed63f29 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.peer/index.html @@ -0,0 +1,203 @@ + + + + + + + + + + Nine Nines: cowboy_req:peer(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:peer(3)

+ +

Name

+

cowboy_req:peer - Peer address and port

+

Description

+
+
peer(Req :: cowboy_req:req()) -> Info
+
+Info :: {inet:ip_address(), inet:port_number()}
+
+

Return the peer's IP address and port number.

+

The peer information can also be obtained using pattern matching:

+
+
#{peer := {IP, Port}} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The peer's IP address and port number.

+

The peer is not necessarily the client's IP address and port. It is the IP address of the endpoint connecting directly to the server, which may be a gateway or a proxy.

+

The forwarded header can be used to get better information about the different endpoints from the client to the server. Note however that it is only informative; there is no reliable way of determining the source of an HTTP request.

+

Changelog

+
  • 2.0: Only the peer is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the peer IP address and port number.
+
+
{IP, Port} = cowboy_req:peer(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:sock(3), cowboy_req:cert(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.port/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.port/index.html new file mode 100644 index 00000000..b4a3f508 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.port/index.html @@ -0,0 +1,200 @@ + + + + + + + + + + Nine Nines: cowboy_req:port(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:port(3)

+ +

Name

+

cowboy_req:port - URI port number

+

Description

+
+
port(Req :: cowboy_req:req()) -> Port :: inet:port_number()
+
+

Return the port number of the effective request URI.

+

Note that the port number returned by this function is obtained by parsing the host header. It may be different from the port the peer used to connect to Cowboy.

+

The port number can also be obtained using pattern matching:

+
+
#{port := Port} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The port number is returned as an integer.

+

Changelog

+
  • 2.0: Only the port number is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the effective request URI's port number
+
+
Port = cowboy_req:port(Req).
+
+

See also

+

cowboy_req(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.push/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.push/index.html new file mode 100644 index 00000000..74892edf --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.push/index.html @@ -0,0 +1,226 @@ + + + + + + + + + + Nine Nines: cowboy_req:push(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:push(3)

+ +

Name

+

cowboy_req:push - Push a resource to the client

+

Description

+
+
push(Path, Headers, Req :: cowboy_req:req())
+    -> push(Path, Headers, Req, #{})
+
+push(Path, Headers, Req :: cowboy_req:req(), Opts)
+    -> ok
+
+Path    :: iodata()                %% case sensitive
+Headers :: cowboy:http_headers()
+Opts    :: cowboy_req:push_opts()
+
+

Push a resource to the client.

+

Cowboy handles push requests the same way as if they came from the client, including the creation of a request handling process, routing and middlewares and so on.

+

This function does nothing when the HTTP/1.1 protocol is used. You may call it safely without first checking whether the connection uses HTTP/2.

+

The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Note that the headers must be the headers the client is expected to send if it were to perform the request. They are therefore request headers, and not response headers.

+

By default, Cowboy will use the GET method, an empty query string, and take the scheme, host and port directly from the current request's URI. You can override them by passing options.

+

Note that clients may cancel the push or ignore it entirely. For example browsers may ignore the resource when the connection is not considered secure.

+

It is not possible to push resources after sending a response. Any attempt will result in an error.

+

Arguments

+
Path
+

The status code for the response.

+
+
Headers
+

The response headers.

+

Header names must be given as lowercase binary strings.

+
+
Req
+

The Req object.

+
+
Opts
+

Customize the HTTP method or the URI scheme, host, port or query string.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Push a resource
+
+
cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, Req),
+
+
Push a resource with a custom host
+
+
cowboy_req:push("/static/style.css", #{
+    <<"accept">> => <<"text/css">>
+}, #{host => <<"cdn.example.org">>}, Req),
+
+

See also

+

cowboy_req(3), cowboy_req:inform(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.qs/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.qs/index.html new file mode 100644 index 00000000..52d45c05 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.qs/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:qs(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:qs(3)

+ +

Name

+

cowboy_req:qs - URI query string

+

Description

+
+
qs(Req :: cowboy_req:req()) -> Qs :: binary()
+
+

Return the query string of the effective request URI.

+

The query string can also be obtained using pattern matching:

+
+
#{qs := Qs} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The query string is returned as a binary string. It is case sensitive.

+

Changelog

+
  • 2.0: Only the query string is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the effective request URI's query string
+
+
Qs = cowboy_req:qs(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:parse_qs(3), cowboy_req:match_qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.read_and_match_urlencoded_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.read_and_match_urlencoded_body/index.html new file mode 100644 index 00000000..09245fc6 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.read_and_match_urlencoded_body/index.html @@ -0,0 +1,250 @@ + + + + + + + + + + Nine Nines: cowboy_req:read_and_match_urlencoded_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:read_and_match_urlencoded_body(3)

+ +

Name

+

cowboy_req:read_and_match_urlencoded_body - Read, parse and match a urlencoded request body against constraints

+

Description

+
+
read_and_match_urlencoded_body(Fields, Req)
+    -> read_and_match_urlencoded_body(Fields, Req, #{})
+
+read_and_match_urlencoded_body(Fields, Req, Opts)
+    -> {ok, Body, Req}
+
+Fields :: cowboy:fields()
+Req    :: cowboy_req:req()
+Opts   :: cowboy_req:read_body_opts()
+Body   :: #{atom() => any()}
+
+

Read, parse and match a urlencoded request body against constraints.

+

This function reads the request body and parses it as application/x-www-form-urlencoded. It then applies the given field constraints to the urlencoded data and returns the result as a map.

+

The urlencoded media type is used by Web browsers when submitting HTML forms using the POST method.

+

Cowboy will only return the values specified in the fields list, and ignore all others. Fields can be either the key requested; the key along with a list of constraints; or the key, a list of constraints and a default value in case the key is missing.

+

This function will crash if the key is missing and no default value is provided. This function will also crash if a constraint fails.

+

The key must be provided as an atom. The key of the returned map will be that atom. The value may be converted through the use of constraints, making this function able to extract, validate and convert values all in one step.

+

Cowboy needs to read the full body before parsing. By default it will read bodies of size up to 64KB. It is possible to provide options to read larger bodies if required.

+

Cowboy will automatically handle protocol details including the expect header, chunked transfer-encoding and others.

+

Once the body has been read, Cowboy sets the content-length header if it was not previously provided.

+

This function can only be called once. Calling it again will result in undefined behavior.

+

Arguments

+
Fields
+

Fields to retrieve from the urlencoded body.

+

See cowboy(3) for a complete description.

+
+
Req
+

The Req object.

+
+
Opts
+

A map of body reading options. Please refer to cowboy_req:read_body(3) for details about each option.

+

This function defaults the length to 64KB and the period to 5 seconds.

+
+
+

Return value

+

An ok tuple is returned.

+

Desired values are returned as a map. The key is the atom that was given in the list of fields, and the value is the optionally converted value after applying constraints.

+

The map contains the same keys that were given in the fields.

+

An exception is triggered when the match fails.

+

The Req object returned in the tuple must be used from that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.

+

Changelog

+
  • 2.5: Function introduced. +
    • +
+

Examples

+
Match fields
+
+
%% ID and Lang are binaries.
+#{id := ID, lang := Lang}
+    = cowboy_req:read_and_match_urlencoded_body(
+        [id, lang], Req).
+
+
Match fields and apply constraints
+
+
%% ID is an integer and Lang a non-empty binary.
+#{id := ID, lang := Lang}
+    = cowboy_req:read_and_match_urlencoded_body(
+        [{id, int}, {lang, nonempty}], Req).
+
+
Match fields with default values
+
+
#{lang := Lang}
+    = cowboy_req:read_and_match_urlencoded_body(
+        [{lang, [], <<"en-US">>}], Req).
+
+
Allow large urlencoded bodies
+
+
{ok, Body, Req} = cowboy_req:read_and_match_urlencoded_body(
+    Fields, Req0, #{length => 1000000}).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_part(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.read_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.read_body/index.html new file mode 100644 index 00000000..69b05263 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.read_body/index.html @@ -0,0 +1,224 @@ + + + + + + + + + + Nine Nines: cowboy_req:read_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:read_body(3)

+ +

Name

+

cowboy_req:read_body - Read the request body

+

Description

+
+
read_body(Req :: cowboy_req:req())
+    -> read_body(Req, #{})
+
+read_body(Req :: cowboy_req:req(), Opts)
+    -> {ok,   Data :: binary(), Req}
+     | {more, Data :: binary(), Req}
+
+Opts :: cowboy_req:read_body_opts()
+
+

Read the request body.

+

This function reads a chunk of the request body. A more tuple is returned when more data remains to be read. Call the function repeatedly until an ok tuple is returned to read the entire body.

+

An ok tuple with empty data is returned when the request has no body, or when calling this function again after the body has already been read. It is therefore safe to call this function directly. Note that the body can only be read once.

+

This function reads the request body from the connection process. The connection process is responsible for reading from the socket. The exact behavior varies depending on the protocol.

+

The options therefore are only related to the communication between the request process and the connection process.

+

Cowboy will automatically handle protocol details including the expect header, chunked transfer-encoding and others.

+

Once the body has been read fully, Cowboy sets the content-length header if it was not previously provided.

+

Arguments

+
Req
+

The Req object.

+
+
Opts
+

A map of body reading options.

+

The length option can be used to request smaller or bigger chunks of data to be sent. It is a best effort approach, Cowboy may send more data than configured on occasions. It defaults to 8MB.

+

The period indicates how long the connection process will wait before it provides us with the data it received. It defaults to 15 seconds.

+

The connection process sends data to the request process when either the length of data or the period of time is reached.

+

The timeout option is a safeguard in case the connection process becomes unresponsive. The function will crash if no message was received in that interval. The timeout should be larger than the period. It defaults to the period + 1 second.

+
+
+

Return value

+

A more tuple is returned when there are more data to be read.

+

An ok tuple is returned when there are no more data to be read, either because this is the last chunk of data, the body has already been read, or there was no body to begin with.

+

The data is always returned as a binary.

+

The Req object returned in the tuple must be used from that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.

+

Changelog

+
  • 2.0: Function introduced. Replaces body/1,2. +
    • +
+

Examples

+
Read the entire body
+
+
read_body(Req0, Acc) ->
+    case cowboy_req:read_body(Req0) of
+        {ok, Data, Req} -> {ok, << Acc/binary, Data/binary >>, Req};
+        {more, Data, Req} -> read_body(Req, << Acc/binary, Data/binary >>)
+    end.
+
+
Read the body in small chunks
+
+
cowboy_req:read_body(Req, #{length => 64000}).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_and_match_urlencoded_body(3), cowboy_req:read_part(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.read_part/index.html new file mode 100644 index 00000000..1893b1e7 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.read_part/index.html @@ -0,0 +1,246 @@ + + + + + + + + + + Nine Nines: cowboy_req:read_part(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:read_part(3)

+ +

Name

+

cowboy_req:read_part - Read the next multipart headers

+

Description

+
+
read_part(Req :: cowboy_req:req())
+    -> read_part(Req, #{})
+
+read_part(Req :: cowboy_req:req(), Opts)
+    -> {ok, Headers, Req} | {done, Req}
+
+Opts    :: cowboy_req:read_body_opts()
+Headers :: #{binary() => binary()}
+
+

Read the next part of a multipart body.

+

This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body. This function parses and returns headers. Examples of multipart media types are multipart/form-data and multipart/byteranges.

+

Cowboy will skip any data remaining until the beginning of the next part. This includes the preamble to the multipart message but also the body of a previous part if it hasn't been read. Both are skipped automatically when calling this function.

+

Cowboy will read the body before parsing in chunks of size up to 64KB, with a period of 5 seconds. This is tailored for reading part headers and might not be the most efficient for skipping the previous part's body.

+

The headers returned are MIME headers, NOT HTTP headers. They can be parsed using the functions from the cow_multipart module. In addition, the cow_multipart:form_data/1 function can be used to quickly extract information from multipart/form-data representations.

+ +

Once a part has been read, it can not be read again.

+

Once the body has been read, Cowboy sets the content-length header if it was not previously provided.

+ +

Arguments

+
Req
+

The Req object.

+
+
Opts
+

A map of body reading options. Please refer to cowboy_req:read_body(3) for details about each option.

+

This function defaults the length to 64KB and the period to 5 seconds.

+
+
+

Return value

+

An ok tuple is returned containing the next part's headers as a map.

+

A done tuple is returned if there are no more parts to read.

+

The Req object returned in the tuple must be used from that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.

+

Changelog

+
  • 2.0: Function introduced. Replaces part/1,2. +
    • +
+

Examples

+
Read all parts
+
+
acc_multipart(Req0, Acc) ->
+    case cowboy_req:read_part(Req0) of
+        {ok, Headers, Req1} ->
+            {ok, Body, Req} = stream_body(Req1, <<>>),
+            acc_multipart(Req, [{Headers, Body}|Acc]);
+        {done, Req} ->
+            {lists:reverse(Acc), Req}
+    end.
+
+stream_body(Req0, Acc) ->
+    case cowboy_req:read_part_body(Req0) of
+        {more, Data, Req} ->
+            stream_body(Req, << Acc/binary, Data/binary >>);
+        {ok, Data, Req} ->
+            {ok, << Acc/binary, Data/binary >>, Req}
+    end.
+
+
Read all part headers, skipping bodies
+
+
skip_body_multipart(Req0, Acc) ->
+    case cowboy_req:read_part(Req0) of
+        {ok, Headers, Req} ->
+            skip_body_multipart(Req, [Headers|Acc]);
+        {done, Req} ->
+            {lists:reverse(Acc), Req}
+    end.
+
+
Read a part header in larger chunks
+
+
{ok, Headers, Req} = cowboy_req:read_part(Req0, #{length => 1000000}).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_and_match_urlencoded_body(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.read_part_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.read_part_body/index.html new file mode 100644 index 00000000..ba8aef7e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.read_part_body/index.html @@ -0,0 +1,222 @@ + + + + + + + + + + Nine Nines: cowboy_req:read_part_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:read_part_body(3)

+ +

Name

+

cowboy_req:read_part_body - Read the current part's body

+

Description

+
+
read_part_body(Req :: cowboy_req:req())
+    -> read_part_body(Req, #{})
+
+read_part_body(Req :: cowboy_req:req(), Opts)
+    -> {ok,   Data :: binary(), Req}
+     | {more, Data :: binary(), Req}
+
+Opts :: cowboy_req:read_body_opts()
+
+

Read the body of the current part of the multipart message.

+

This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body. This function returns the body of the current part. Examples of multipart media types are multipart/form-data and multipart/byteranges.

+

This function reads a chunk of the part's body. A more tuple is returned when more data remains to be read. Call the function repeatedly until an ok tuple is returned to read the entire body.

+

Once a part has been read, it can not be read again.

+

Once the body has been read, Cowboy sets the content-length header if it was not previously provided.

+ +

Arguments

+
Req
+

The Req object.

+
+
Opts
+

A map of body reading options. Please refer to cowboy_req:read_body(3) for details about each option.

+

This function uses the same default options as the cowboy_req:read_body(3) function.

+
+
+

Return value

+

A more tuple is returned when there are more data to be read.

+

An ok tuple is returned when there are no more data to be read.

+

The data is always returned as a binary.

+

The Req object returned in the tuple must be used from that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.

+

Changelog

+
  • 2.0: Function introduced. Replaces part_body/1,2. +
    • +
+

Examples

+
Read a full part's body
+
+
stream_body(Req0, Acc) ->
+    case cowboy_req:read_part_body(Req0) of
+        {more, Data, Req} ->
+            stream_body(Req, << Acc/binary, Data/binary >>);
+        {ok, Data, Req} ->
+            {ok, << Acc/binary, Data/binary >>, Req}
+    end.
+
+
Ensure a part's body is smaller than 64KB
+
+
{ok, Body, Req} = cowboy_req:read_part_body(Req0, #{length => 64000}).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_urlencoded_body(3), cowboy_req:read_and_match_urlencoded_body(3), cowboy_req:read_part(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.read_urlencoded_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.read_urlencoded_body/index.html new file mode 100644 index 00000000..934b50ff --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.read_urlencoded_body/index.html @@ -0,0 +1,216 @@ + + + + + + + + + + Nine Nines: cowboy_req:read_urlencoded_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:read_urlencoded_body(3)

+ +

Name

+

cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body

+

Description

+
+
read_urlencoded_body(Req :: cowboy_req:req())
+    -> read_urlencoded_body(Req, #{})
+
+read_urlencoded_body(Req :: cowboy_req:req(), Opts)
+    -> {ok, Body, Req}
+
+Opts :: cowboy_req:read_body_opts()
+Body :: [{Key :: binary(), Value :: binary() | true}]
+
+

Read and parse a urlencoded request body.

+

This function reads the request body and parses it as application/x-www-form-urlencoded. It returns a list of key/values.

+

The urlencoded media type is used by Web browsers when submitting HTML forms using the POST method.

+

Cowboy needs to read the full body before parsing. By default it will read bodies of size up to 64KB. It is possible to provide options to read larger bodies if required.

+

Cowboy will automatically handle protocol details including the expect header, chunked transfer-encoding and others.

+

Once the body has been read, Cowboy sets the content-length header if it was not previously provided.

+

This function can only be called once. Calling it again will result in undefined behavior.

+

Arguments

+
Req
+

The Req object.

+
+
Opts
+

A map of body reading options. Please refer to cowboy_req:read_body(3) for details about each option.

+

This function defaults the length to 64KB and the period to 5 seconds.

+
+
+

Return value

+

An ok tuple is returned containing a list of key/values found in the body.

+

The Req object returned in the tuple must be used from that point onward. It contains a more up to date representation of the request. For example it may have an added content-length header once the body has been read.

+

Changelog

+
  • 2.0: Function introduced. Replaces body_qs/1,2. +
    • +
+

Examples

+
Read a urlencoded body
+
+
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0),
+{_, Lang} = lists:keyfind(<<"lang">>, 1, Body).
+
+
Allow large urlencoded bodies
+
+
{ok, Body, Req} = cowboy_req:read_urlencoded_body(Req0, #{length => 1000000}).
+
+

See also

+

cowboy_req(3), cowboy_req:has_body(3), cowboy_req:body_length(3), cowboy_req:read_body(3), cowboy_req:read_and_match_urlencoded_body(3), cowboy_req:read_part(3), cowboy_req:read_part_body(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.reply/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.reply/index.html new file mode 100644 index 00000000..da54a1c0 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.reply/index.html @@ -0,0 +1,238 @@ + + + + + + + + + + Nine Nines: cowboy_req:reply(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:reply(3)

+ +

Name

+

cowboy_req:reply - Send the response

+

Description

+
+
reply(Status, Req :: cowboy_req:req())
+    -> reply(StatusCode, #{}, Req)
+
+reply(Status, Headers, Req :: cowboy_req:req())
+    -> Req
+
+reply(Status, Headers, Body, Req :: cowboy_req:req())
+    -> Req
+
+Status  :: cowboy:http_status()
+Headers :: cowboy:http_headers()
+Body    :: cowboy_req:resp_body()
+
+

Send the response.

+

The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Cowboy does not allow duplicate header names. Headers set by this function may overwrite those set by set_resp_header/3 and set_resp_headers/2.

+

Use cowboy_req:set_resp_cookie(3) instead of this function to set cookies.

+

The reply/2,3 functions will send the body set previously, if any. The reply/4 function always sends the given body, overriding any previously set.

+

You do not need to set the content-length header when sending a response body. Cowboy takes care of it automatically. You should however provide a content-type header.

+

No further data can be transmitted after this function returns. This includes the push mechanism. Attempting to send two replies, or to push resources after a reply has been sent, will result in an error.

+

Arguments

+
Status
+

The status code for the response.

+
+
Headers
+

The response headers.

+

Header names must be given as lowercase binary strings.

+
+
Body
+

The body can be either a binary value, an iolist or a sendfile tuple telling Cowboy to send the contents of a file.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object should be used from that point onward as it contains updated information about the state of the request.

+

Changelog

+
  • 2.0: Only the Req is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Reply
+
+
Req = cowboy_req:reply(404, Req0).
+
+
Reply with custom headers
+
+
Req = cowboy_req:reply(401, #{
+    <<"www-authenticate">> => <<"Basic realm=\"erlang.org\"">>
+}, Req0).
+
+
Reply with custom headers and a body
+
+
Req = cowboy_req:reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, "Hello world!", Req0).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_cookie(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:set_resp_body(3), cowboy_req:inform(3), cowboy_req:stream_reply(3), cowboy_req:push(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.resp_header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.resp_header/index.html new file mode 100644 index 00000000..d38145b5 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.resp_header/index.html @@ -0,0 +1,210 @@ + + + + + + + + + + Nine Nines: cowboy_req:resp_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:resp_header(3)

+ +

Name

+

cowboy_req:resp_header - Response header

+

Description

+
+
resp_header(Name, Req)          -> resp_header(Name, Req, undefined)
+resp_header(Name, Req, Default) -> binary() | Default
+
+Name    :: binary()          %% lowercase; case insensitive
+Req     :: cowboy_req:req()
+Default :: any()
+
+

Return the value for the given response header.

+

The response header must have been set previously using cowboy_req:set_resp_header(3) or cowboy_req:set_resp_headers(3).

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Arguments

+
Name
+

Desired response header name as a lowercase binary string.

+
+
Req
+

The Req object.

+
+
Default
+

Default value returned when the header is missing.

+
+
+

Return value

+

The header value is returned as a binary string. When the header is missing, the default argument is returned.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Get the content-type response header
+
+
Type = cowboy_req:resp_header(<<"content-type">>, Req).
+
+
Get the content-type response header with a default value
+
+
Type = cowboy_req:resp_header(<<"content-type">>, Req, <<"text/html">>).
+
+

See also

+

cowboy_req(3), cowboy_req:resp_headers(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.resp_headers/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.resp_headers/index.html new file mode 100644 index 00000000..b2d772f4 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.resp_headers/index.html @@ -0,0 +1,190 @@ + + + + + + + + + + Nine Nines: cowboy_req:resp_headers(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:resp_headers(3)

+ +

Name

+

cowboy_req:resp_headers - Response headers

+

Description

+
+
resp_headers(Req :: cowboy_req:req()) -> cowboy:http_headers()
+
+

Return all response headers.

+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

Headers are returned as a map with keys being lowercase binary strings, and values as binary strings.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Get all response headers
+
+
Headers = cowboy_req:resp_headers(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:resp_header(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.scheme/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.scheme/index.html new file mode 100644 index 00000000..f68bfd99 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.scheme/index.html @@ -0,0 +1,204 @@ + + + + + + + + + + Nine Nines: cowboy_req:scheme(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:scheme(3)

+ +

Name

+

cowboy_req:scheme - URI scheme

+

Description

+
+
scheme(Req :: cowboy_req:req()) -> Scheme :: binary()
+
+

Return the scheme of the effective request URI.

+

The scheme can also be obtained using pattern matching:

+
+
#{scheme := Scheme} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The scheme is returned as a binary. It is case insensitive.

+

Cowboy will only set the scheme to <<"http">> or <<"https">>.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Redirect HTTP to HTTPS
+
+
init(Req0=#{scheme := <<"http">>}, State) ->
+    Req = cowboy_req:reply(302, #{
+        <<"location">> => cowboy_req:uri(Req, #{scheme => <<"https">>})
+    }, Req0),
+    {ok, Req, State};
+init(Req, State) ->
+    {cowboy_rest, Req, State}.
+
+

See also

+

cowboy_req(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_body/index.html new file mode 100644 index 00000000..2fd4e4bb --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_body/index.html @@ -0,0 +1,231 @@ + + + + + + + + + + Nine Nines: cowboy_req:set_resp_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:set_resp_body(3)

+ +

Name

+

cowboy_req:set_resp_body - Set the response body

+

Description

+
+
set_resp_body(Body, Req :: cowboy_req:req())
+	-> Req
+
+Body :: cowboy_req:resp_body()
+
+

Set the response body.

+

The response body will be sent when a reply is initiated. Note that the functions stream_reply/2,3 and reply/4 will override the body set by this function.

+

This function can also be used to remove a response body that was set previously. To do so, simply call this function with an empty body.

+

Arguments

+
Body
+

The body can be either a binary value, an iolist or a sendfile tuple telling Cowboy to send the contents of a file.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward, otherwise the body will not be sent in the response.

+

Changelog

+
  • 2.0: The function now accepts a sendfile tuple. +
    • +
  • 2.0: The set_resp_body_fun/2,3 functions were removed. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Set the response body
+
+
Req = cowboy_req:set_resp_body(<<"Hello world!">>, Req0).
+
+
Set the response body as an iolist
+
+
Req = cowboy_req:set_resp_body([
+    "<html><head><title>",
+    page_title(),
+    "</title></head><body>",
+    page_body(),
+    "</body></html>"
+], Req0).
+
+
Tell Cowboy to send data from a file
+
+
{ok, #file_info{size=Size}} = file:read_file_info(Filename),
+Req = cowboy_req:set_resp_body({sendfile, 0, Size, Filename}, Req0).
+
+
Clear any previously set response body
+
+
Req = cowboy_req:set_resp_body(<<>>, Req0).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_cookie/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_cookie/index.html new file mode 100644 index 00000000..5c7c9c22 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_cookie/index.html @@ -0,0 +1,256 @@ + + + + + + + + + + Nine Nines: cowboy_req:set_resp_cookie(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:set_resp_cookie(3)

+ +

Name

+

cowboy_req:set_resp_cookie - Set a cookie

+

Description

+
+
set_resp_cookie(Name, Value, Req :: cowboy_req:req())
+    -> set_resp_cookie(Name, Value, Req, #{})
+
+set_resp_cookie(Name, Value, Req :: cowboy_req:req(), Opts)
+    -> Req
+
+Name  :: binary()                  %% case sensitive
+Value :: iodata()                  %% case sensitive
+Opts  :: cow_cookie:cookie_opts()
+
+

Set a cookie to be sent with the response.

+

Note that cookie names are case sensitive.

+

Arguments

+
Name
+

Cookie name.

+
+
Value
+

Cookie value.

+
+
Req
+

The Req object.

+
+
Opts
+

Cookie options.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward, otherwise the cookie will not be sent in the response.

+

Changelog

+
  • 2.0: set_resp_cookie/3 introduced as an alias to set_resp_cookie/4 with no options. +
    • +
  • 2.0: The first argument type is now binary() instead of iodata(). +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Set a session cookie
+
+
SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).
+
+
Set a cookie with an expiration time
+
+
Req = cowboy_req:set_resp_cookie(<<"lang">>, <<"fr-FR">>,
+    Req0, #{max_age => 3600}).
+
+
Delete a cookie
+
+
Req = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>,
+    Req0, #{max_age => 0}).
+
+
Set a cookie for a specific domain and path
+
+
Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>,
+    Req0, #{domain => "my.example.org", path => "/account"}).
+
+
Restrict a cookie to HTTPS
+
+
SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
+    Req0, #{secure => true}).
+
+
Restrict a cookie to HTTP
+
+
SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID,
+    Req0, #{http_only => true}).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_header/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_header/index.html new file mode 100644 index 00000000..04a727a8 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_header/index.html @@ -0,0 +1,212 @@ + + + + + + + + + + Nine Nines: cowboy_req:set_resp_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:set_resp_header(3)

+ +

Name

+

cowboy_req:set_resp_header - Set a response header

+

Description

+
+
set_resp_header(Name, Value, Req :: cowboy_req:req())
+	-> Req
+
+Name  :: binary()  %% lowercase; case insensitive
+Value :: iodata()  %% case depends on header
+
+

Set a header to be sent with the response.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Cowboy does not allow duplicate header names. Headers set by this function may be overwritten by those set from the reply functions.

+

Use cowboy_req:set_resp_cookie(3) instead of this function to set cookies.

+

Arguments

+
Name
+

Header name as a lowercase binary string.

+
+
Value
+

Header value.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward, otherwise the header will not be sent in the response.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Set a header in the response
+
+
Req = cowboy_req:set_resp_header(<<"allow">>, "GET", Req0).
+
+
Construct a header using iolists
+
+
Req = cowboy_req:set_resp_header(<<"allow">>,
+    [allowed_methods(), ", OPTIONS"], Req0).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_cookie(3), cowboy_req:set_resp_headers(3), cowboy_req:has_resp_header(3), cowboy_req:resp_header(3), cowboy_req:resp_headers(3), cowboy_req:delete_resp_header(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_headers/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_headers/index.html new file mode 100644 index 00000000..7d33e844 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.set_resp_headers/index.html @@ -0,0 +1,203 @@ + + + + + + + + + + Nine Nines: cowboy_req:set_resp_headers(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:set_resp_headers(3)

+ +

Name

+

cowboy_req:set_resp_headers - Set several response headers

+

Description

+
+
set_resp_headers(Headers, Req :: cowboy_req:req())
+    -> Req
+
+Headers :: cowboy:http_headers()
+
+

Set several headers to be sent with the response.

+

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Cowboy does not allow duplicate header names. Headers set by this function may be overwritten by those set from the reply functions. Likewise, headers set by this function may overwrite headers that were set previously.

+

Use cowboy_req:set_resp_cookie(3) instead of this function to set cookies.

+

Arguments

+
Headers
+

Headers as a map with keys being lowercase binary strings, and values as binary strings.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward, otherwise the headers will not be sent in the response.

+

Changelog

+
  • 2.0: Function introduced. +
    • +
+

Examples

+
Set several response headers
+
+
Req = cowboy_req:set_resp_headers(#{
+    <<"content-type">>     => <<"text/html">>,
+    <<"content-encoding">> => <<"gzip">>
+}, Req0).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_cookie(3), cowboy_req:set_resp_header(3), cowboy_req:has_resp_header(3), cowboy_req:resp_header(3), cowboy_req:resp_headers(3), cowboy_req:delete_resp_header(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.sock/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.sock/index.html new file mode 100644 index 00000000..c85ba220 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.sock/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:sock(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:sock(3)

+ +

Name

+

cowboy_req:sock - Socket address and port

+

Description

+
+
sock(Req :: cowboy_req:req()) -> Info
+
+Info :: {inet:ip_address(), inet:port_number()}
+
+

Return the socket's IP address and port number.

+

The socket information can also be obtained using pattern matching:

+
+
#{sock := {IP, Port}} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The socket's local IP address and port number.

+

Changelog

+
  • 2.1: Function introduced. +
    • +
+

Examples

+
Get the socket's IP address and port number.
+
+
{IP, Port} = cowboy_req:sock(Req).
+
+

See also

+

cowboy_req(3), cowboy_req:peer(3), cowboy_req:cert(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.stream_body/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.stream_body/index.html new file mode 100644 index 00000000..0422b062 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.stream_body/index.html @@ -0,0 +1,210 @@ + + + + + + + + + + Nine Nines: cowboy_req:stream_body(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:stream_body(3)

+ +

Name

+

cowboy_req:stream_body - Stream the response body

+

Description

+
+
stream_body(Data, IsFin, Req :: cowboy_req:req()) -> ok
+
+Data  :: cowboy_req:resp_body()
+IsFin :: fin | nofin
+
+

Stream the response body.

+

This function may be called as many times as needed after initiating a response using the cowboy_req:stream_reply(3) function.

+

The second argument indicates if this call is the final call. Use the nofin value until you know no more data will be sent. The final call should use fin (possibly with an empty data value) or be a call to the cowboy_req:stream_trailers(3) function.

+

Note that not using fin for the final call is not an error; Cowboy will take care of it when the request handler terminates if needed. Depending on the resource it may however be more efficient to do it as early as possible.

+

You do not need to handle HEAD requests specifically as Cowboy will ensure no data is sent when you call this function.

+

Arguments

+
Data
+

The data to be sent.

+
+
IsFin
+

A flag indicating whether this is the final piece of data to be sent.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.6: The Data argument can now be a sendfile tuple. +
    • +
  • 2.0: Function introduced. Replaces chunk/2. +
    • +
+

Examples

+
Stream the response body
+
+
Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, fin, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:stream_reply(3), cowboy_req:stream_events(3), cowboy_req:stream_trailers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.stream_events/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.stream_events/index.html new file mode 100644 index 00000000..f842313c --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.stream_events/index.html @@ -0,0 +1,224 @@ + + + + + + + + + + Nine Nines: cowboy_req:stream_events(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:stream_events(3)

+ +

Name

+

cowboy_req:stream_events - Stream events

+

Description

+
+
stream_events(Events, IsFin, Req :: cowboy_req:req()) -> ok
+
+Events :: Event | [Event]
+IsFin  :: fin | nofin
+
+Event  :: #{
+    comment => iodata(),
+    data    => iodata(),
+    event   => iodata() | atom(),
+    id      => iodata(),
+    retry   => non_neg_integer()
+}
+
+

Stream events.

+

This function should only be used for text/event-stream responses when using server-sent events. Cowboy will automatically encode the given events to their text representation.

+

This function may be called as many times as needed after initiating a response using the cowboy_req:stream_reply(3) function.

+

The second argument indicates if this call is the final call. Use the nofin value until you know no more data will be sent. The final call should use fin (possibly with an empty data value) or be a call to the cowboy_req:stream_trailers(3) function.

+

Note that not using fin for the final call is not an error; Cowboy will take care of it when the request handler terminates if needed. Depending on the resource it may however be more efficient to do it as early as possible.

+

You do not need to handle HEAD requests specifically as Cowboy will ensure no data is sent when you call this function.

+

Arguments

+
Events
+

Events to be sent. All fields are optional.

+
+
IsFin
+

A flag indicating whether this is the final piece of data to be sent.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.5: Function introduced. +
    • +
+

Examples

+
Stream events
+
+
Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/event-stream">>
+}, Req0),
+cowboy_req:stream_events(#{
+    id => <<"comment-123">>,
+    event => <<"add_comment">>,
+    data => <<"Hello,\n\nI noticed something wrong in ...">>
+}, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_events(#{
+    event => <<"debug">>,
+    data => io_lib:format("An error occurred: ~p~n", [Error])
+}, fin, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:stream_reply(3), cowboy_req:stream_body(3), cowboy_req:stream_trailers(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.stream_reply/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.stream_reply/index.html new file mode 100644 index 00000000..1f117b5b --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.stream_reply/index.html @@ -0,0 +1,227 @@ + + + + + + + + + + Nine Nines: cowboy_req:stream_reply(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:stream_reply(3)

+ +

Name

+

cowboy_req:stream_reply - Send the response headers

+

Description

+
+
stream_reply(Status, Req :: cowboy_req:req())
+    -> stream_reply(StatusCode, #{}, Req)
+
+stream_reply(Status, Headers, Req :: cowboy_req:req())
+    -> Req
+
+Status  :: cowboy:http_status()
+Headers :: cowboy:http_headers()
+
+

Send the response headers.

+

The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

+

Cowboy does not allow duplicate header names. Headers set by this function may overwrite those set by set_resp_header/3.

+

Use cowboy_req:set_resp_cookie(3) instead of this function to set cookies.

+

If a response body was set before calling this function, it will not be sent.

+

Use cowboy_req:stream_body(3) to stream the response body and optionally cowboy_req:stream_trailers(3) to send response trailer field values.

+

You may want to set the content-length header when using this function, if it is known in advance. This will allow clients using HTTP/2 and HTTP/1.0 to process the response more efficiently.

+

The streaming method varies depending on the protocol being used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will use chunked transfer-encoding, if the content-length response header is set the body will be sent without chunked chunked transfer-encoding. HTTP/1.0 will send the body unmodified and close the connection at the end if no content-length was set.

+

It is not possible to push resources after this function returns. Any attempt will result in an error.

+

Arguments

+
Status
+

The status code for the response.

+
+
Headers
+

The response headers.

+

Header names must be given as lowercase binary strings.

+
+
Req
+

The Req object.

+
+
+

Return value

+

A new Req object is returned.

+

The returned Req object must be used from that point onward in order to be able to stream the response body.

+

Changelog

+
  • 2.0: Only the Req is returned, it is no longer wrapped in a tuple. +
    • +
  • 2.0: Function introduced. Replaces chunked_reply/1,2. +
    • +
+

Examples

+
Initiate the response
+
+
Req = cowboy_req:stream_reply(200, Req0).
+
+
Stream the response with custom headers
+
+
Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, fin, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:set_resp_cookie(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:inform(3), cowboy_req:reply(3), cowboy_req:stream_body(3), cowboy_req:stream_events(3), cowboy_req:stream_trailers(3), cowboy_req:push(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.stream_trailers/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.stream_trailers/index.html new file mode 100644 index 00000000..5f8cdc76 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.stream_trailers/index.html @@ -0,0 +1,207 @@ + + + + + + + + + + Nine Nines: cowboy_req:stream_trailers(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:stream_trailers(3)

+ +

Name

+

cowboy_req:stream_trailers - Send the response trailers

+

Description

+
+
stream_trailers(Trailers, Req :: cowboy_req:req()) -> ok
+
+Trailers :: cowboy:http_headers()
+
+

Send the response trailers and terminate the stream.

+

This function can only be called once, after initiating a response using cowboy_req:stream_reply(3) and sending zero or more body chunks using cowboy_req:stream_body(3) with the nofin argument set. The function stream_trailers/2 implies fin and automatically terminate the response.

+

You must list all field names sent in trailers in the trailer header, otherwise they might be dropped by intermediaries or clients.

+

Arguments

+
Trailers
+

Trailer field values to be sent.

+
+
Req
+

The Req object.

+
+
+

Return value

+

The atom ok is always returned. It can be safely ignored.

+

Changelog

+
  • 2.2: Function introduced. +
    • +
+

Examples

+
Stream a response body with trailers
+
+
Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>,
+    <<"trailer">> => <<"expires, content-md5">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, nofin, Req).
+cowboy_req:stream_trailers(#{
+    <<"expires">> => <<"Sun, 10 Dec 2017 19:13:47 GMT">>,
+    <<"content-md5">> => <<"fbf68a8e34b2ded53bba54e68794b4fe">>
+}, Req).
+
+

See also

+

cowboy_req(3), cowboy_req:stream_reply(3), cowboy_req:stream_body(3), cowboy_req:stream_events(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.uri/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.uri/index.html new file mode 100644 index 00000000..bb0224b2 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.uri/index.html @@ -0,0 +1,258 @@ + + + + + + + + + + Nine Nines: cowboy_req:uri(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:uri(3)

+ +

Name

+

cowboy_req:uri - Reconstructed URI

+

Description

+
+
uri(Req :: cowboy_req:req())       -> uri(Req, #{})
+uri(Req :: cowboy_req:req(), Opts) -> URI :: iodata()
+
+Opts :: #{
+    scheme   => iodata()           | undefined,
+    host     => iodata()           | undefined,
+    port     => inet:port_number() | undefined,
+    path     => iodata()           | undefined,
+    qs       => iodata()           | undefined,
+    fragment => iodata()           | undefined
+}
+
+

Reconstruct the effective request URI, optionally modifying components.

+

By default Cowboy will build a URI using the components found in the request. Options allow disabling or replacing individual components.

+

Arguments

+
Req
+

The Req object.

+
+
Opts
+

Map for overriding individual components.

+

To replace a component, provide its new value as a binary string or an iolist. To disable a component, set its value to undefined.

+

As this function always returns a valid URI, there are some things to note:

+
  • Disabling the host also disables the scheme and port. +
    • +
  • There is no fragment component by default as these are not sent with the request. +
    • +
  • The port number may not appear in the resulting URI if it is the default port for the given scheme (http: 80; https: 443). +
    • +
+
+
+

Return value

+

The reconstructed URI is returned as an iolist or a binary string.

+

Changelog

+
  • 2.0: Individual components can be replaced or disabled. +
    • +
  • 2.0: Only the URI is returned, it is no longer wrapped in a tuple. +
    • +
  • 2.0: Function introduced. Replaces host_url/1 and url/1. +
    • +
+

Examples

+

With an effective request URI http://example.org/path/to/res?edit=1 we can have:

+
Protocol relative form
+
+
%% //example.org/path/to/res?edit=1
+cowboy_req:uri(Req, #{scheme => undefined}).
+
+
Serialized origin for use in the origin header
+
+
%% http://example.org
+cowboy_req:uri(Req, #{path => undefined, qs => undefined}).
+
+
HTTP/1.1 origin form (path and query string only)
+
+
%% /path/to/res?edit=1
+cowboy_req:uri(Req, #{host => undefined}).
+
+
Add a fragment to the URI
+
+
%% http://example.org/path/to/res?edit=1#errors
+cowboy_req:uri(Req, #{fragment => <<"errors">>}).
+
+
Ensure the scheme is HTTPS
+
+
%% https://example.org/path/to/res?edit=1
+cowboy_req:uri(Req, #{scheme => <<"https">>}).
+
+
Convert the URI to a binary string
+
+
iolist_to_binary(cowboy_req:uri(Req)).
+
+

See also

+

cowboy_req(3), cowboy_req:scheme(3), cowboy_req:host(3), cowboy_req:port(3), cowboy_req:path(3), cowboy_req:qs(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req.version/index.html b/docs/en/cowboy/2.7/manual/cowboy_req.version/index.html new file mode 100644 index 00000000..c75f9e7e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req.version/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_req:version(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req:version(3)

+ +

Name

+

cowboy_req:version - HTTP version

+

Description

+
+
version(Req :: cowboy_req:req()) -> Version :: cowboy:http_version()
+
+

Return the HTTP version used for the request.

+

The version can also be obtained using pattern matching:

+
+
#{version := Version} = Req.
+
+

Arguments

+
Req
+

The Req object.

+
+
+

Return value

+

The HTTP version used for the request is returned as an atom. It is provided for informative purposes only.

+

Changelog

+
  • 2.0: Only the version is returned, it is no longer wrapped in a tuple. +
    • +
  • 1.0: Function introduced. +
    • +
+

Examples

+
Get the HTTP version
+
+
Version = cowboy_req:version(Req).
+
+

See also

+

cowboy_req(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_req/index.html b/docs/en/cowboy/2.7/manual/cowboy_req/index.html new file mode 100644 index 00000000..1706e2ae --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_req/index.html @@ -0,0 +1,380 @@ + + + + + + + + + + Nine Nines: cowboy_req(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_req(3)

+ +

Name

+

cowboy_req - HTTP request and response

+

Description

+

The module cowboy_req provides functions to access, manipulate and respond to requests.

+

There are four types of functions in this module. They can be differentiated by their name and their return type:

+ + + + + + + + + + + + + + + + + + + + +
TypeName patternReturn type
accessno verb, parse_*, match_*Value
questionhas_*boolean()
modificationset_*Req
actionany other verbok | {Result, Value, Req}
+

Any Req returned must be used in place of the one passed as argument. Functions that perform an action in particular write state in the Req object to make sure you are using the function correctly. For example, it's only possible to send one response, and to read the body once.

+

Exports

+

Connection:

+ +

Raw request:

+ +

Processed request:

+ +

Request body:

+ +

Response:

+ +

Stream handlers:

+ +

Types

+

push_opts()

+
+
push_opts() :: #{
+    method => binary(),            %% case sensitive
+    scheme => binary(),            %% lowercase; case insensitive
+    host   => binary(),            %% lowercase; case insensitive
+    port   => inet:port_number(),
+    qs     => binary()             %% case sensitive
+}
+
+

Push options.

+

By default, Cowboy will use the GET method, an empty query string, and take the scheme, host and port directly from the current request's URI.

+

read_body_opts()

+
+
read_body_opts() :: #{
+    length  => non_neg_integer(),
+    period  => non_neg_integer(),
+    timeout => timeout()
+}
+
+

Body reading options.

+

The defaults are function-specific.

+

req()

+
+
req() :: #{
+    method  := binary(),               %% case sensitive
+    version := cowboy:http_version() | atom(),
+    scheme  := binary(),               %% lowercase; case insensitive
+    host    := binary(),               %% lowercase; case insensitive
+    port    := inet:port_number(),
+    path    := binary(),               %% case sensitive
+    qs      := binary(),               %% case sensitive
+    headers := cowboy:http_headers(),
+    peer    := {inet:ip_address(), inet:port_number()},
+    sock    := {inet:ip_address(), inet:port_number()},
+    cert    := binary() | undefined
+}
+
+

The Req object.

+

Contains information about the request and response. While some fields are publicly documented, others aren't and shouldn't be used.

+

You may add custom fields if required. Make sure to namespace them by prepending an underscore and the name of your application:

+
Setting a custom field
+
+
Req#{'_myapp_auth_method' => pubkey}.
+
+

resp_body()

+
+
resp_body() :: iodata()
+    | {sendfile, Offset, Length, Filename}
+
+Offset   :: non_neg_integer()
+Length   :: non_neg_integer()
+Filename :: file:name_all()
+
+

Response body.

+

It can take two forms: the actual data to be sent or a tuple indicating which file to send.

+

When sending data directly, the type is either a binary or an iolist. Iolists are an efficient way to build output. Instead of concatenating strings or binaries, you can simply build a list containing the fragments you want to send in the order they should be sent:

+
Example iolists usage
+
+
1> RespBody = ["Hello ", [<<"world">>, $!]].
+["Hello ",[<<"world">>,33]]
+2> io:format("~s~n", [RespBody]).
+Hello world!
+
+

Note that the length must be greater than zero for any data to be sent. Cowboy will send an empty body when the length is zero.

+

See also

+

cowboy(7)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_rest/index.html b/docs/en/cowboy/2.7/manual/cowboy_rest/index.html new file mode 100644 index 00000000..2084a4f2 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_rest/index.html @@ -0,0 +1,658 @@ + + + + + + + + + + Nine Nines: cowboy_rest(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_rest(3)

+ +

Name

+

cowboy_rest - REST handlers

+

Description

+

The module cowboy_rest implements the HTTP state machine.

+

Implementing REST handlers is not enough to provide a REST interface; this interface must also follow the REST constraints including HATEOAS (hypermedia as the engine of application state).

+

Callbacks

+

REST handlers implement the following interface:

+
+
init(Req, State)
+    -> {cowboy_rest, Req, State}
+
+Callback(Req, State)
+    -> {Result, Req, State}
+     | {stop, Req, State}
+     | {{switch_handler, Module}, Req, State}
+     | {{switch_handler, Module, Opts}, Req, State}
+
+terminate(Reason, Req, State) -> ok  %% optional
+
+Req    :: cowboy_req:req()
+State  :: any()
+Module :: module()
+Opts   :: any()
+Reason :: normal
+        | {crash, error | exit | throw, any()}
+
+Callback - see below
+Result   - see below
+Default  - see below
+
+

The init/2 callback is common to all handlers. To switch to the REST handler behavior, it must return cowboy_rest as the first element of the tuple.

+

The Callback/2 above represents all the REST-specific callbacks. They are described in the following section of this manual. REST-specific callbacks differ by their name, semantics, result and default values. The default value is the one used when the callback has not been implemented. They otherwise all follow the same interface.

+

The stop tuple can be returned to stop REST processing. If no response was sent before then, Cowboy will send a 204 No Content. The stop tuple can be returned from any callback, excluding expires, generate_etag, last_modified and variances.

+

A switch_handler tuple can be returned from these same callbacks to stop REST processing and switch to a different handler type. This is very useful to, for example, to stream the response body.

+

The optional terminate/3 callback will ultimately be called with the reason for the termination of the handler. Cowboy will terminate the process right after this. There is no need to perform any cleanup in this callback.

+

The following terminate reasons are defined for loop handlers:

+
normal
+

The handler terminated normally.

+
+
{crash, Class, Reason}
+

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

+
+
+

REST callbacks

+

AcceptCallback

+
+
AcceptCallback(Req, State) -> {Result, Req, State}
+
+Result  :: true | {true, URI :: iodata()} | false}
+Default  - crash
+
+

Process the request body.

+

This function should create or update the resource using the request body.

+

For PUT requests, the body is a representation of the resource that is being created or replaced.

+

For POST requests, the body is typically application-specific instructions on how to process the request, but it may also be a representation of the resource. When creating a new resource with POST at a different location, return {true, URI} with URI the new location.

+

For PATCH requests, the body is a series of instructions on how to update the resource. Patch files or JSON Patch are examples of such media types.

+

A response body may be sent. The appropriate media type, charset and language for the response can be retrieved from the Req object using the media_type, charset and language keys, respectively. The body can be set using cowboy_req:set_resp_body(3).

+

allowed_methods

+
+
allowed_methods(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case sensitive
+Default :: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
+
+

Return the list of allowed methods.

+

allow_missing_post

+
+
allow_missing_post(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether POST is allowed when the resource doesn't exist.

+

Returning true here means that a new resource will be created. The URI for the newly created resource should be returned from the AcceptCallback function.

+

charsets_provided

+
+
charsets_provided(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% lowercase; case insensitive
+Default  - skip this step
+
+

Return the list of charsets the resource provides in order of preference.

+

During content negotiation Cowboy will pick the most appropriate charset for the client. The client advertises charsets it prefers with the accept-charset header. When that header is missing, Cowboy picks the first charset from the resource.

+ +

Cowboy will add the negotiated charset to the Req object after this step completes:

+
+
req() :: #{
+    charset => binary()  %% lowercase; case insensitive
+}
+
+

Note that Cowboy will only append the charset to the content-type header of the response if the media type is text.

+

content_types_accepted

+
+
content_types_accepted(Req, State) -> {Result, Req, State}
+
+Result     :: [{'*' | binary() | ParsedMime, AcceptCallback :: atom()}]
+ParsedMime :: {Type :: binary(), SubType :: binary(), '*' | Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+Default     - crash
+
+ +

Return the list of media types the resource accepts in order of preference.

+

A media type is made of different parts. The media type text/html;charset=utf-8 is of type text, subtype html and has a single parameter charset with value utf-8.

+

The special value '*' can be used to accept any media type.

+ + + +

Cowboy will match the content-type request header against the media types the server accepts and select the appropriate callback. When that header is missing, or when the server does not accept this media type, the request fails and an error response is returned. Cowboy will execute the callback immediately otherwise.

+ +

An empty parameters list [] means that no parameters will be accepted. When any parameter is acceptable, the tuple form should be used with parameters as the atom '*'.

+

Cowboy treats all parameters as case sensitive, except for the charset parameter, which is known to be case insensitive. You should therefore always provide the charset as a lowercase binary string.

+ + + + + + +

content_types_provided

+
+
content_types_provided(Req, State) -> {Result, Req, State}
+
+Result     :: [{binary() | ParsedMime, ProvideCallback :: atom()}]
+ParsedMime :: {Type :: binary(), SubType :: binary(), '*' | Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+Default     - [{{ <<"text">>, <<"html">>, '*'}, to_html}]
+
+ + +

Return the list of media types the resource provides in order of preference.

+

A media type is made of different parts. The media type text/html;charset=utf-8 is of type text, subtype html and has a single parameter charset with value utf-8.

+ + + +

During content negotiation Cowboy will pick the most appropriate media type for the client. The client advertises media types it prefers with the accept header. When that header is missing, the content negotiation fails and an error response is returned.

+

The callback given for the selected media type will be called at the end of the execution of GET and HEAD requests when a representation must be sent to the client.

+ +

An empty parameters list [] means that no parameters will be accepted. When any parameter is acceptable, the tuple form should be used with parameters as the atom '*'.

+

Cowboy treats all parameters as case sensitive, except for the charset parameter, which is known to be case insensitive. You should therefore always provide the charset as a lowercase binary string.

+

When a charset is given in the media type parameters in the accept header, Cowboy will do some additional checks to confirm that it can use this charset. When the wildcard is used then Cowboy will immediately call charsets_provided to confirm the charset is acceptable. If the callback is undefined Cowboy assumes any charset is acceptable. When the wildcard is not used and the charset given in the accept header matches one of the configured media types Cowboy will use that charset and skip the charsets_provided step entirely.

+

Cowboy will add the negotiated media_type to the Req object after this step completes:

+
+
req() :: #{
+    media_type => ParsedMime
+}
+
+ +

Cowboy may also add the negotiated charset to the Req object after this step completes:

+
+
req() :: #{
+    charset => binary()  %% lowercase; case insensitive
+}
+
+

delete_completed

+
+
delete_completed(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether the resource has been fully deleted from the system, including from any internal cache.

+

Returning false will result in a 202 Accepted response being sent instead of a 200 OK or 204 No Content.

+

delete_resource

+
+
delete_resource(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Delete the resource.

+

Cowboy will send an error response when this function returns false.

+

expires

+
+
expires(Req, State) -> {Result, Req, State}
+
+Result  :: calendar:datetime() | binary() | undefined
+Default :: undefined
+
+

Return the resource's expiration date.

+

forbidden

+
+
forbidden(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether access to the resource is forbidden.

+

A 403 Forbidden response will be sent if this function returns true. This status code means that access is forbidden regardless of authentication, and that the request shouldn't be repeated.

+

generate_etag

+
+
generate_etag(Req, State) -> {Result, Req, State}
+
+Result  :: binary() | {weak | strong, binary()}
+Default  - no etag value
+
+

Return the entity tag of the resource.

+

When a binary is returned, the value is automatically parsed to a tuple. The binary must be in the same format as the etag header, including quotes.

+

is_authorized

+
+
is_authorized(Req, State) -> {Result, Req, State}
+
+Result  :: true | {false, AuthHeader :: iodata()}
+Default  - true
+
+

Return whether the user is authorized to perform the action.

+

This function should be used to perform any necessary authentication of the user before attempting to perform any action on the resource.

+

When authentication fails, the AuthHeader value will be sent in the www-authenticate header for the 401 Unauthorized response.

+

is_conflict

+
+
is_conflict(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether the PUT request results in a conflict.

+

A 409 Conflict response is sent when true.

+

known_methods

+
+
known_methods(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case sensitive
+Default :: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>,
+            <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
+
+

Return the list of known methods.

+

The full list of methods known by the server should be returned, regardless of their use in the resource.

+

The default value lists the methods Cowboy knows and implement in cowboy_rest.

+

languages_provided

+
+
languages_provided(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% lowercase; case insensitive
+Default  - skip this step
+
+

Return the list of languages the resource provides in order of preference.

+

During content negotiation Cowboy will pick the most appropriate language for the client. The client advertises languages it prefers with the accept-language header. When that header is missing, Cowboy picks the first language from the resource.

+ +

Cowboy will add the negotiated language to the Req object after this step completes:

+
+
req() :: #{
+    language => binary()  %% lowercase; case insensitive
+}
+
+

last_modified

+
+
last_modified(Req, State) -> {Result, Req, State}
+
+Result  :: calendar:datetime()
+Default  - no last modified value
+
+

Return the resource's last modification date.

+

This date will be used to test against the if-modified-since and if-unmodified-since headers, and sent as the last-modified header in the response to GET and HEAD requests.

+

malformed_request

+
+
malformed_request(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether the request is malformed.

+

A request is malformed when a component required by the resource is invalid. This may include the query string or individual headers. They should be parsed and validated in this function. The body should not be read at this point.

+

moved_permanently

+
+
moved_permanently(Req, State) -> {Result, Req, State}
+
+Result  :: {true, URI :: iodata()} | false
+Default :: false
+
+

Return whether the resource was permanently moved, and what its new location is.

+

moved_temporarily

+
+
moved_temporarily(Req, State) -> {Result, Req, State}
+
+Result  :: {true, URI :: iodata()} | false
+Default :: false
+
+

Return whether the resource was temporarily moved, and what its new location is.

+

multiple_choices

+
+
multiple_choices(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether the client should engage in reactive negotiation.

+

Return true when the server has multiple representations of a resource, each with their specific identifier, but is unable to determine which is best for the client. For example an image might have different sizes and the server is unable to determine the capabilities of the client.

+

When returning true the server should send a body with links to the different representations. If the server has a preferred representation it can send its link inside a location header.

+

Note that when replying manually in this callback you should either call cowboy_req:reply/4 or remove the response body that Cowboy sets to avoid surprises.

+

options

+
+
options(Req, State) -> {ok, Req, State}
+
+

Respond to an OPTIONS request.

+

The response should inform the client the communication options available for this resource. By default Cowboy will send a 200 OK response with the allow header set.

+

previously_existed

+
+
previously_existed(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether the resource existed previously.

+

ProvideCallback

+
+
ProvideCallback(Req, State) -> {Result, Req, State}
+
+Result  :: cowboy_req:resp_body()
+Default  - crash
+
+

Return the response body.

+

The response body can be provided either as the actual data to be sent or a tuple indicating which file to send.

+

This function is called for both GET and HEAD requests. For the latter the body is not sent, however.

+ + + +

Note that there used to be a way to stream the response body. It was temporarily removed and will be added back in a later release.

+ +

rate_limited

+
+
rate_limited(Req, State) -> {Result, Req, State}
+
+Result     :: false | {true, RetryAfter}
+RetryAfter :: non_neg_integer() | calendar:datetime()
+Default  - false
+
+

Return whether the user is rate limited.

+

This function can be used to temporarily restrict access to a resource when the user has issued too many requests.

+

When the resource is rate limited the RetryAfter value will be sent in the retry-after header for the 429 Too Many Requests response. It indicates when the resource will become available again and can be specified as a number of seconds in the future or a specific date/time.

+

resource_exists

+
+
resource_exists(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether the resource exists.

+

service_available

+
+
service_available(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether the service is available.

+

A 503 Service Unavailable response will be sent when this function returns false.

+

uri_too_long

+
+
uri_too_long(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: false
+
+

Return whether the requested URI is too long.

+

This function can be used to further restrict the length of the URI for this specific resource.

+

valid_content_headers

+
+
valid_content_headers(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether the content headers are valid.

+

This callback can be used to reject requests that have invalid content header values, for example an unsupported content-encoding.

+

valid_entity_length

+
+
valid_entity_length(Req, State) -> {Result, Req, State}
+
+Result  :: boolean()
+Default :: true
+
+

Return whether the request body length is within acceptable boundaries.

+

A 413 Request Entity Too Large response will be sent if this function returns false.

+

variances

+
+
variances(Req, State) -> {Result, Req, State}
+
+Result  :: [binary()]  %% case insensitive
+Default :: []
+
+

Return the list of request headers that affect the representation of the resource.

+

Cowboy automatically adds the accept, accept-charset and accept-language headers when necessary. It's also useful to note that some standard headers also do not need to be listed here, like the authorization header.

+

Changelog

+
  • 2.7: The media type wildcard in content_types_accepted is now documented. +
    • +
  • 2.6: The callback rate_limited was added. +
    • +
  • 2.1: The switch_handler return value was added. +
    • +
  • 1.0: Behavior introduced. +
    • +
+

See also

+

cowboy(7), cowboy_handler(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_router.compile/index.html b/docs/en/cowboy/2.7/manual/cowboy_router.compile/index.html new file mode 100644 index 00000000..27db13b5 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_router.compile/index.html @@ -0,0 +1,200 @@ + + + + + + + + + + Nine Nines: cowboy_router:compile(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_router:compile(3)

+ +

Name

+

cowboy_router:compile - Compile routes to the resources

+

Description

+
+
compile(cowboy_router:routes()) -> cowboy_router:dispatch_rules()
+
+

Compile routes to the resources.

+

Takes a human readable list of routes and transforms it into a form more efficient to process.

+

Arguments

+
Routes
+

Human readable list of routes.

+
+
+

Return value

+

An opaque dispatch rules value is returned. This value must be given to Cowboy as a middleware environment value.

+

Changelog

+
  • 1.0: Function introduced. +
    • +
+

Examples

+
Compile routes and start a listener
+
+
Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []},
+        {"/[...]", cowboy_static, {priv_dir, my_example_app, ""}}
+    ]}
+]),
+
+{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{
+    env => #{dispatch => Dispatch}
+}).
+
+

See also

+

cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_router/index.html b/docs/en/cowboy/2.7/manual/cowboy_router/index.html new file mode 100644 index 00000000..3483ba4d --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_router/index.html @@ -0,0 +1,217 @@ + + + + + + + + + + Nine Nines: cowboy_router(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_router(3)

+ +

Name

+

cowboy_router - Router middleware

+

Description

+

The cowboy_router middleware maps the requested host and path to the handler to be used for processing the request.

+

The router takes the dispatch rules as input from the middleware environment. Dispatch rules are generated by calling the cowboy_router:compile(3) function. The environment can contain the rules directly or a tuple {persistent_term, Key}, in which case Cowboy will call persistent_term:get(Key) to retrieve the dispatch rules.

+

When a route matches, the router sets the handler and handler_opts middleware environment values containing the handler module and initial state, respectively.

+

The router will stop execution when no route matches. It will send a 400 response if no host was found, and a 404 response otherwise.

+

Exports

+ +

Types

+

bindings()

+
+
bindings() :: #{atom() => any()}
+
+

Bindings found during routing.

+

dispatch_rules()

+

Opaque type containing the compiled routes.

+

routes()

+
+
routes() = [
+    {Host, PathList} |
+    {Host, Fields, PathList}
+]
+
+PathList :: [
+    {Path, Handler, InitialState} |
+    {Path, Fields, Handler, InitialState}
+]
+
+Host         :: '_' | iodata()
+Path         :: '_' | iodata()
+Fields       :: cowboy:fields()
+Handler      :: module()
+InitialState :: any()
+
+

Human readable list of routes to handlers.

+

Cowboy uses this list to map hosts and paths, optionally augmented with constraints applied to the bindings, to handler modules.

+

The syntax for routes is currently defined in the user guide.

+ + +

tokens()

+
+
tokens() :: [binary()]
+
+

List of host_info and path_info tokens that were found using the ... syntax.

+

See also

+

cowboy(7), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_req:path_info(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_static/index.html b/docs/en/cowboy/2.7/manual/cowboy_static/index.html new file mode 100644 index 00000000..05129151 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_static/index.html @@ -0,0 +1,275 @@ + + + + + + + + + + Nine Nines: cowboy_static(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_static(3)

+ +

Name

+

cowboy_static - Static file handler

+

Description

+

The module cowboy_static implements file serving capabilities using the REST semantics provided by cowboy_rest.

+

The static file handler is a pre-written handler coming with Cowboy. To serve files, use it in your routes.

+

Options

+
+
opts() :: {priv_file, App, Path}
+        | {priv_file, App, Path, Extra}
+        | {file, Path}
+        | {file, Path, Extra}
+        | {priv_dir, App, Path}
+        | {priv_dir, App, Path, Extra}
+        | {dir, Path}
+        | {dir, Path, Extra}
+
+App        :: atom()
+Path       :: binary() | string()
+Extra      :: [Charset | Etag | Mimetypes]
+
+Charset    :: {charset, module(), function()}
+            | {charset, binary()}
+
+Etag       :: {etag, module(), function()}
+            | {etag, false}
+
+Mimetypes  :: {mimetypes, module(), function()}
+            | {mimetypes, binary() | ParsedMime}
+
+ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+

Static handler configuration.

+
priv_file
+

Send a file.

+

The path is relative to the given application's private directory.

+
+
file
+

Send a file.

+

The path is either absolute or relative to the Erlang node's current directory.

+
+
priv_dir
+

Recursively serve files from a directory.

+

The path is relative to the given application's private directory.

+
+
dir
+

Recursively serve files from a directory.

+

The path is either absolute or relative to the Erlang node's current directory.

+
+
+

The extra options allow you to define how the etag should be calculated and how the MIME type of files should be detected.

+

By default the static handler will not send a charset with the response. You can provide a specific charset that will be used for all files using the text media type, or provide a module and function that will be called when needed:

+
+
detect_charset(Path :: binary()) -> Charset :: binary()
+
+

A charset must always be returned even if it doesn't make sense considering the media type of the file. A good default is <<"utf-8">>.

+

By default the static handler will generate an etag based on the size and modification time of the file. You may disable the etag entirely with {etag, false} or provide a module and function that will be called when needed:

+
+
generate_etag(Path, Size, Mtime) -> {strong | weak, binary()}
+
+Path  :: binary()
+Size  :: non_neg_integer()
+Mtime :: file:date_time()
+
+

By default the static handler will detect Web-related MIME types by looking at the file extension. You can provide a specific MIME type that will always be used, or a module and function that will be called when needed:

+
+
detect_mimetype(Path) -> ParsedMime
+
+Path       :: binary()
+ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
+Params     :: [{Key :: binary(), Value :: binary()}]
+
+ +

Cowboy comes with two such functions; the default function cow_mimetypes:web/1, and a second function generated from the Apache mime.types file, cow_mimetypes:all/1.

+

The MIME type function should return {<<"application">>, <<"octet-stream">>, []} when it fails to detect a file's MIME type.

+

Changelog

+
  • 2.6: The charset extra option was added. +
    • +
  • 1.0: Handler introduced. +
    • +
+

Examples

+
Custom etag function
+
+
generate_etag(Path, Size, Mtime) ->
+    {strong, integer_to_binary(
+        erlang:phash2({Path, Size, Mtime}, 16#ffffffff))}.
+
+
Custom MIME type function
+
+
always_octet_stream(_Path) ->
+    case filename:extension(Path) of
+        <<".erl">> -> {<<"text">>, <<"plain">>, []};
+        _ -> {<<"application">>, <<"octet-stream">>, []}
+    end.
+
+

See also

+

cowboy(7), cowboy_router(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_stream/index.html b/docs/en/cowboy/2.7/manual/cowboy_stream/index.html new file mode 100644 index 00000000..40f5def9 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_stream/index.html @@ -0,0 +1,435 @@ + + + + + + + + + + Nine Nines: cowboy_stream(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_stream(3)

+ +

Name

+

cowboy_stream - Stream handlers

+

Description

+

The module cowboy_stream defines a callback interface and a protocol for handling HTTP streams.

+

An HTTP request and its associated response is called a stream. A connection may have many streams. In HTTP/1.1 they are executed sequentially, while in HTTP/2 they are executed concurrently.

+

Cowboy calls the stream handler for nearly all events related to a stream. Exceptions vary depending on the protocol.

+

Extra care must be taken when implementing stream handlers to ensure compatibility. While some modification of the events and commands is allowed, it is generally not a good idea to completely discard them.

+

Callbacks

+

Stream handlers must implement the following interface:

+
+
init(StreamID, Req, Opts) -> {Commands, State}
+data(StreamID, IsFin, Data, State) -> {Commands, State}
+info(StreamID, Info, State) -> {Commands, State}
+terminate(StreamID, Reason, State) -> any()
+early_error(StreamID, Reason, PartialReq, Resp, Opts) -> Resp
+
+StreamID   :: cowboy_stream:streamid()
+Req        :: cowboy_req:req()
+Opts       :: cowboy:opts()
+Commands   :: cowboy_stream:commands()
+State      :: any()
+IsFin      :: cowboy_stream:fin()
+Data       :: binary()
+Info       :: any()
+Reason     :: cowboy_stream:reason()
+PartialReq  - cowboy_req:req(), except all fields are optional
+Resp       :: cowboy_stream:resp_command()
+
+

HTTP/1.1 will initialize a stream only when the request-line and all headers have been received. When errors occur before that point Cowboy will call the callback early_error/5 with a partial request, the error reason and the response Cowboy intends to send. All other events go throuh the stream handler using the normal callbacks.

+

HTTP/2 will initialize the stream when the HEADERS block has been fully received and decoded. Any protocol error occuring before that will not result in a response being sent and will therefore not go through the stream handler. In addition Cowboy may terminate streams without sending an HTTP response back.

+

The stream is initialized by calling init/3. All streams that are initialized will eventually be terminated by calling terminate/3.

+

When Cowboy receives data for the stream it will call data/4. The data given is the request body after any transfer decoding has been applied.

+

When Cowboy receives a message addressed to a stream, or when Cowboy needs to inform the stream handler that an internal event has occurred, it will call info/3.

+

Commands

+

Stream handlers can return a list of commands to be executed from the init/3, data/4 and info/3 callbacks. In addition, the early_error/5 callback must return a response command.

+ + +

The following commands are defined:

+

inform

+

Send an informational response to the client.

+
+
{inform, cowboy:http_status(), cowboy:http_headers()}
+
+

Any number of informational responses may be sent, but only until the final response is sent.

+

response

+

Send a response to the client.

+
+
{response, cowboy:http_status(), cowboy:http_headers(),
+    cowboy_req:resp_body()}
+
+

No more data can be sent after this command.

+

Note that in Cowboy it is the cowboy_req module that sets the date and server headers. When using the command directly those headers will not be added.

+

headers

+

Initiate a response to the client.

+
+
{headers, cowboy:http_status(), cowboy:http_headers()}
+
+

This initiates a response to the client. The stream will end when a data command with the fin flag or a trailer command is returned.

+

Note that in Cowboy it is the cowboy_req module that sets the date and server headers. When using the command directly those headers will not be added.

+

data

+

Send data to the client.

+
+
{data, fin(), cowboy_req:resp_body()}
+
+

trailers

+

Send response trailers to the client.

+
+
{trailers, cowboy:http_headers()}
+
+

push

+

Push a resource to the client.

+
+
{push, Method, Scheme, Host, inet:port_number(),
+    Path, Qs, cowboy:http_headers()}
+
+Method = Scheme = Host = Path = Qs = binary()
+
+

The command will be ignored if the protocol does not provide any server push mechanism.

+

flow

+
+
{flow, pos_integer()}
+
+

Request more data to be read from the request body. The exact behavior depends on the protocol.

+

spawn

+

Inform Cowboy that a process was spawned and should be supervised.

+
+
{spawn, pid(), timeout()}
+
+

error_response

+

Send an error response if no response was sent previously.

+
+
{error_response, cowboy:http_status(), cowboy:http_headers(), iodata()}
+
+

switch_protocol

+

Switch to a different protocol.

+
+
{switch_protocol, cowboy:http_headers(), module(), state()}
+
+

Contains the headers that will be sent in the 101 response, along with the module implementing the protocol we are switching to and its initial state.

+

Note that the 101 informational response will not be sent after a final response.

+

stop

+

Stop the stream.

+
+
stop
+
+

While no more data can be sent after the fin flag was set, the stream is still tracked by Cowboy until it is stopped by the handler.

+

The behavior when stopping a stream for which no response has been sent will vary depending on the protocol. The stream will end successfully as far as the client is concerned.

+

To indicate that an error occurred, either use error_response before stopping, or use internal_error.

+

internal_error

+

Stop the stream with an error.

+
+
{internal_error, Reason, HumanReadable}
+
+Reason        = any()
+HumanReadable = atom()
+
+

This command should be used when the stream cannot continue because of an internal error. An error_response command may be sent before that to advertise to the client why the stream is dropped.

+

log

+

Log a message.

+
+
{log, logger:level(), io:format(), list()}
+
+

This command can be used to log a message using the configured logger module.

+

set_options

+

Set protocol options.

+
+
{set_options, map()}
+
+

This can also be used to override stream handler options. For example this is supported by cowboy_compress_h(3).

+

Not all options can be overriden. Please consult the relevant option's documentation for details.

+

Predefined events

+

Cowboy will forward all messages sent to the stream to the info/3 callback. To send a message to a stream, the function cowboy_req:cast(3) can be used.

+

Cowboy will also forward the exit signals for the processes that the stream spawned.

+

When Cowboy needs to send a response it will trigger an event that looks exactly like the corresponding command. This event must be returned to be processed by Cowboy (which is done automatically when using cowboy_stream_h(3)).

+

Cowboy may trigger the following events on its own, regardless of the stream handlers configured: inform (to send a 101 informational response when upgrading to HTTP/2 or Websocket), response, headers, data and switch_protocol.

+

Exports

+

The following function should be called by modules implementing stream handlers to execute the next stream handler in the list:

+ +

Types

+

commands()

+
+
commands() :: [Command]
+
+

See the list of commands for details.

+

fin()

+
+
fin() :: fin | nofin
+
+

Used in commands and events to indicate that this is the end of the stream.

+

partial_req()

+
+
req() :: #{
+    method  => binary(),               %% case sensitive
+    version => cowboy:http_version() | atom(),
+    scheme  => binary(),               %% lowercase; case insensitive
+    host    => binary(),               %% lowercase; case insensitive
+    port    => inet:port_number(),
+    path    => binary(),               %% case sensitive
+    qs      => binary(),               %% case sensitive
+    headers => cowboy:http_headers(),
+    peer    => {inet:ip_address(), inet:port_number()}
+}
+
+

Partial request information received when an early error is detected.

+

reason()

+
+
reason() :: normal | switch_protocol
+    | {internal_error, timeout | {error | exit | throw, any()}, HumanReadable}
+    | {socket_error, closed | atom(), HumanReadable}
+    | {stream_error, Error, HumanReadable}
+    | {connection_error, Error, HumanReadable}
+    | {stop, cow_http2:frame() | {exit, any()}, HumanReadable}
+
+Error         = atom()
+HumanReadable = atom()
+
+

Reason for the stream termination.

+

resp_command()

+
+
resp_command() :: {response, cowboy:http_status(),
+    cowboy:http_headers(), cowboy_req:resp_body()}
+
+

See the response command for details.

+

streamid()

+
+
streamid() :: any()
+
+

The identifier for this stream.

+

The identifier is unique over the connection process. It is possible to form a unique identifier node-wide and cluster-wide by wrapping it in a {self(), StreamID} tuple.

+

Changelog

+
  • 2.7: The log and set_options commands were introduced. +
    • +
  • 2.6: The data command can now contain a sendfile tuple. +
    • +
  • 2.6: The {stop, {exit, any()}, HumanReadable} terminate reason was added. +
    • +
  • 2.2: The trailers command was introduced. +
    • +
  • 2.0: Module introduced. +
    • +
+

See also

+

cowboy(7), cowboy_http(3), cowboy_http2(3), cowboy_req:cast(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_stream_h/index.html b/docs/en/cowboy/2.7/manual/cowboy_stream_h/index.html new file mode 100644 index 00000000..525527c7 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_stream_h/index.html @@ -0,0 +1,199 @@ + + + + + + + + + + Nine Nines: cowboy_stream_h(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

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.

+ + +

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.

+ +

Because this stream handler converts events from the request process into commands, other stream handlers may not work properly if they are executed

+

Changelog

+
  • 2.0: Module introduced. +
    • +
+

See also

+

cowboy(7), cowboy_stream(3), cowboy_compress_h(3), cowboy_metrics_h(3), cowboy_tracer_h(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_tracer_h/index.html b/docs/en/cowboy/2.7/manual/cowboy_tracer_h/index.html new file mode 100644 index 00000000..f5a086d4 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_tracer_h/index.html @@ -0,0 +1,212 @@ + + + + + + + + + + Nine Nines: cowboy_tracer_h(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_tracer_h(3)

+ +

Name

+

cowboy_tracer_h - Tracer stream handler

+

Description

+

The module cowboy_tracer_h can be used to conditionally trace streams based on information found in the request. Trace messages are given to the configured callback.

+

Options

+
+
opts() :: #{
+    tracer_callback    => Callback,
+    tracer_flags       => [atom()],
+    tracer_match_specs => [MatchSpec]
+}
+
+Callback :: fun((init | terminate | tuple(), State) -> State)
+
+MatchSpec :: MatchPredicate
+           | {method, binary()}
+           | {host, binary()}
+           | {path, binary()}
+           | {path_start, binary()}
+           | {header, binary()}
+           | {header, binary(), binary()}
+           | {peer_ip, inet:ip_address()}
+
+MatchPredicate :: fun((cowboy_stream:streamid(),
+                       cowboy_req:req(),
+                       cowboy:opts()) -> boolean())
+}
+
+

Configuration for the tracer stream handler.

+

This module will not set trace patterns. Those must be set by the user directly, either from the callback's init or, preferably, in advance.

+
tracer_callback
+

The function that will be called for each trace events. It will also be called before any trace event with an argument init, and when the stream is terminated with an argument terminate.

+

This option is required for tracing to be enabled. The tracer stream handler does nothing otherwise.

+
+
tracer_flags
+

Trace flags to enable. See the documentation of erlang:trace/3 for details. Note that all trace flags are allowed except for the tracer flag.

+
+
tracer_match_specs
+

A list of match conditions that must all be fulfilled for the stream to be traced. Cowboy will compare these with the information found in the request and only enable tracing if all matches succeed.

+

This option is required for tracing to be enabled. The tracer stream handler does nothing otherwise.

+
+
+

Events

+

The tracer stream handler does not produce any event.

+

Changelog

+
  • 2.7: Module introduced. +
    • +
+

See also

+

cowboy(7), cowboy_stream(3), cowboy_compress_h(3), cowboy_metrics_h(3), cowboy_stream_h(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.7/manual/cowboy_websocket/index.html new file mode 100644 index 00000000..8057e3d7 --- /dev/null +++ b/docs/en/cowboy/2.7/manual/cowboy_websocket/index.html @@ -0,0 +1,353 @@ + + + + + + + + + + Nine Nines: cowboy_websocket(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

cowboy_websocket(3)

+ +

Name

+

cowboy_websocket - Websocket

+

Description

+

The module cowboy_websocket implements Websocket as a Ranch protocol. It also defines a callback interface for handling Websocket connections.

+

Callbacks

+

Websocket handlers must implement the following callback interface:

+
+
init(Req, State)
+    -> {cowboy_websocket, Req, State}
+     | {cowboy_websocket, Req, State, Opts}
+
+websocket_init(State)            -> CallResult  %% optional
+websocket_handle(InFrame, State) -> CallResult
+websocket_info(Info, State)      -> CallResult
+
+terminate(Reason, PartialReq, State) -> ok      %% optional
+
+Req        :: cowboy_req:req()
+PartialReq :: map()
+State      :: any()
+Opts       :: cowboy_websocket:opts()
+InFrame    :: ping | pong | {text | binary | ping | pong, binary()}
+Info       :: any()
+
+CallResult :: {commands(), State}
+            | {commands(), State, hibernate}
+            | Deprecated
+
+Deprecated :: {ok, State}
+            | {ok, State, hibernate}
+            | {reply, OutFrame | [OutFrame], State}
+            | {reply, OutFrame | [OutFrame], State, hibernate}
+            | {stop, State}
+OutFrame   :: cow_ws:frame()                    %% see types below
+
+Reason     :: normal | stop | timeout
+            | remote | {remote, cow_ws:close_code(), binary()}
+            | {error, badencoding | badframe | closed | atom()}
+            | {crash, error | exit | throw, any()}
+
+

The init/2 callback is common to all handlers. To upgrade the connection to Websocket, it must return cowboy_websocket as the first element of the tuple.

+

Any operation requiring the HTTP request must be done in the init/2 function, as the Req object will not be available after it returns. Websocket sub-protocol selection should therefore be done in this function.

+

The optional websocket_init/1 callback will be called once the connection has been upgraded to Websocket. It can be used to perform any required initialization of the handler.

+

Note that the init/2 function does not run in the same process as the Websocket callbacks. Any Websocket-specific initialization must be done in websocket_init/1.

+

The websocket_handle/2 callback will be called for every frame received. The websocket_info/2 callback will be called for every Erlang message received.

+

All three Websocket callbacks may send one or more frames back to the client, including close frames to terminate the connection; enable/disable active mode; enable/disable compression for subsequent frames; or change Websocket options.

+

The optional terminate/3 callback will ultimately be called with the reason for the termination of the connection. This callback is common to all handlers. Note that Websocket will not provide the full Req object by default, to save memory.

+

Cowboy will terminate the process right after closing the Websocket connection. This means that there is no need to perform any cleanup in the terminate/3 callback.

+

The following terminate reasons are defined for Websocket connections:

+
normal
+

The connection was closed normally before establishing a Websocket connection. This typically happens if an ok tuple is returned from the init/2 callback.

+
+
remote
+

The remote endpoint closed the connection without giving any further details.

+
+
{remote, Code, Payload}
+

The remote endpoint closed the connection with the given Code and Payload as the reason.

+
+
stop
+

The handler requested to close the connection, either by returning a stop tuple or by sending a close frame.

+
+
timeout
+

The connection has been closed due to inactivity. The timeout value can be configured from init/2.

+
+
{crash, Class, Reason}
+

A crash occurred in the handler. Class and Reason can be used to obtain more information about the crash. The function erlang:get_stacktrace/0 can also be called to obtain the stacktrace of the process when the crash occurred.

+
+
{error, badencoding}
+

A text frame was sent by the client with invalid encoding. All text frames must be valid UTF-8.

+
+
{error, badframe}
+

A protocol error has been detected.

+
+
{error, closed}
+

The socket has been closed brutally without a close frame being received first.

+
+
{error, Reason}
+

A socket error ocurred.

+
+
+

Types

+

commands()

+
+
commands() :: [Command]
+
+Command :: {active, boolean()}
+         | {deflate, boolean()}
+         | {set_options, #{idle_timeout => timeout()}}
+         | {shutdown_reason, any()}
+         | Frame :: cow_ws:frame()
+
+

Commands that may be returned from Websocket callbacks.

+

The following commands are defined:

+
active
+

Whether to disable or enable reading from the socket. This can be used to apply flow control to a Websocket connection.

+
+
deflate
+

Whether the subsequent frames should be compressed. Has no effect on connections that did not negotiate compression.

+
+
set_options
+

Set Websocket options. Currently only the option idle_timeout may be updated from a Websocket handler.

+
+
shutdown_reason
+

Change the shutdown reason. The Websocket process will exit with reason normal by default. This command can be used to exit with reason {shutdown, ShutdownReason} under normal conditions. This command has no effect when the Websocket process exits abnormally, for example following a crash in a handler callback.

+
+
Frame
+

Send the corresponding Websocket frame.

+
+
+

cow_ws:frame()

+
+
frame() :: {text, iodata()}
+    | {binary, iodata()}
+    | ping | {ping, iodata()}
+    | pong | {pong, iodata()}
+    | close | {close, iodata()} | {close, close_code(), iodata()}
+
+close_code() :: 1000..1003 | 1006..1011 | 3000..4999
+
+

Websocket frames that can be sent as a response.

+

Note that there is no need to send pong frames back as Cowboy does it automatically for you.

+

opts()

+
+
opts() :: #{
+    compress       => boolean(),
+    deflate_opts   => cow_ws:deflate_opts()
+    idle_timeout   => timeout(),
+    max_frame_size => non_neg_integer() | infinity,
+    req_filter     => fun((cowboy_req:req()) -> map()),
+    validate_utf8  => boolean()
+}
+
+

Websocket handler options.

+

This configuration is passed to Cowboy from the init/2 function:

+
+
init(Req, State) ->
+    Opts = #{compress => true},
+    {cowboy_websocket, Req, State, Opts}.
+
+

The default value is given next to the option name:

+
compress (false)
+

Whether to enable the Websocket frame compression extension. Frames will only be compressed for the clients that support this extension.

+
+
deflate_opts (#{})
+

Configuration for the permessage-deflate Websocket extension. Allows configuring both the negotiated options and the zlib compression options. The defaults optimize the compression at the expense of some memory and CPU.

+
+
idle_timeout (60000)
+

Time in milliseconds that Cowboy will keep the connection open without receiving anything from the client.

+

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

+
+
max_frame_size (infinity)
+

Maximum frame size in bytes allowed by this Websocket handler. Cowboy will close the connection when a client attempts to send a frame that goes over this limit. For fragmented frames this applies to the size of the reconstituted frame.

+
+
req_filter
+

A function applied to the Req to compact it and only keep required information. The Req is only given back in the terminate/3 callback. By default it keeps the method, version, URI components and peer information.

+
+
validate_utf8 (true)
+

Whether Cowboy should verify that the payload of text and close frames is valid UTF-8. This is required by the protocol specification but in some cases it may be more interesting to disable it in order to save resources.

+

Note that binary frames do not have this UTF-8 requirement and are what should be used under normal circumstances if necessary.

+
+
+

Changelog

+
  • 2.7: The commands based interface has been documented. The old interface is now deprecated. +
    • +
  • 2.7: The command shutdown_reason was introduced. +
    • +
  • 2.7: The option validate_utf8 has been added. +
    • +
  • 2.6: Deflate options can now be configured via deflate_opts. +
    • +
  • 2.0: The Req object is no longer passed to Websocket callbacks. +
    • +
  • 2.0: The callback websocket_terminate/3 was removed in favor of terminate/3. +
    • +
  • 1.0: Protocol introduced. +
    • +
+

See also

+

cowboy(7), cowboy_handler(3), cowboy_http(3), cowboy_http2(3)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/http_status_codes/index.html b/docs/en/cowboy/2.7/manual/http_status_codes/index.html new file mode 100644 index 00000000..79b11bdc --- /dev/null +++ b/docs/en/cowboy/2.7/manual/http_status_codes/index.html @@ -0,0 +1,244 @@ + + + + + + + + + + Nine Nines: HTTP status codes(7) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

HTTP status codes(7)

+ +

Name

+

HTTP status codes - status codes used by Cowboy

+

Description

+

This chapter aims to list all HTTP status codes that Cowboy may return, with details on the reasons why. The list given here only includes the replies that Cowboy sends, not user replies.

+

100 Continue

+

When the client sends an expect: 100-continue header, Cowboy automatically sends a this status code before trying to read the request body. This behavior can be disabled using the appropriate body option.

+

101 Switching Protocols

+

This is the status code sent when switching to the Websocket protocol.

+

200 OK

+

This status code is sent by cowboy_rest.

+

201 Created

+

This status code is sent by cowboy_rest.

+

202 Accepted

+

This status code is sent by cowboy_rest.

+

204 No Content

+

This status code is sent when the processing of a request ends without any reply having been sent. It may also be sent by cowboy_rest under normal conditions.

+

300 Multiple Choices

+

This status code is sent by cowboy_rest.

+

301 Moved Permanently

+

This status code is sent by cowboy_rest.

+

303 See Other

+

This status code is sent by cowboy_rest.

+

304 Not Modified

+

This status code is sent by cowboy_rest.

+

307 Temporary Redirect

+

This status code is sent by cowboy_rest.

+

400 Bad Request

+

Cowboy will send this status code for any of the following reasons:

+
  • Too many empty lines were sent before the request. +
    • +
  • The request-line could not be parsed. +
    • +
  • Too many headers were sent. +
    • +
  • A header name was too long. +
    • +
  • A header value was too long. +
    • +
  • The host header was missing from an HTTP/1.1 request. +
    • +
  • The host header could not be parsed. +
    • +
  • The requested host was not found. +
    • +
  • The requested path could not be parsed. +
    • +
  • The accept header could not be parsed when using REST. +
    • +
  • REST under normal conditions. +
    • +
  • A Websocket upgrade failed. +
    • +
+

401 Unauthorized

+

This status code is sent by cowboy_rest.

+

403 Forbidden

+

This status code is sent by cowboy_rest.

+

404 Not Found

+

This status code is sent when the router successfully resolved the host but didn't find a matching path for the request. It may also be sent by cowboy_rest under normal conditions.

+

405 Method Not Allowed

+

This status code is sent by cowboy_rest.

+

406 Not Acceptable

+

This status code is sent by cowboy_rest.

+

408 Request Timeout

+

Cowboy will send this status code to the client if the client started to send a request, indicated by the request-line being received fully, but failed to send all headers in a reasonable time.

+

409 Conflict

+

This status code is sent by cowboy_rest.

+

410 Gone

+

This status code is sent by cowboy_rest.

+

412 Precondition Failed

+

This status code is sent by cowboy_rest.

+

413 Request Entity Too Large

+

This status code is sent by cowboy_rest.

+

414 Request-URI Too Long

+

Cowboy will send this status code to the client if the request-line is too long. It may also be sent by cowboy_rest under normal conditions.

+

415 Unsupported Media Type

+

This status code is sent by cowboy_rest.

+

500 Internal Server Error

+

This status code is sent when a crash occurs in HTTP, loop or REST handlers, or when an invalid return value is returned. It may also be sent by cowboy_rest under normal conditions.

+

501 Not Implemented

+

This status code is sent by cowboy_rest.

+

503 Service Unavailable

+

This status code is sent by cowboy_rest.

+

505 HTTP Version Not Supported

+

Cowboy only supports the versions 1.0 and 1.1 of HTTP. In all other cases this status code is sent back to the client and the connection is closed.

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + diff --git a/docs/en/cowboy/2.7/manual/index.html b/docs/en/cowboy/2.7/manual/index.html new file mode 100644 index 00000000..a2f5263e --- /dev/null +++ b/docs/en/cowboy/2.7/manual/index.html @@ -0,0 +1,239 @@ + + + + + + + + + + Nine Nines: Cowboy Function Reference + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Cowboy Function Reference

+ +

Name

+

cowboy - Small, fast, modern HTTP server for Erlang/OTP

+

Description

+

Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols.

+

Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events.

+

Modules

+

Functions:

+ +

Protocols:

+ +

Handlers:

+ +

Stream handlers:

+ +

Behaviors:

+ +

Middlewares:

+ + +

Dependencies

+
  • ranch(7) - Socket acceptor pool for TCP protocols +
    • +
  • cowlib(7) - Support library for manipulating Web protocols +
    • +
  • ssl - Secure communication over sockets +
    • +
  • crypto - Crypto functions +
    • +
+

All these applications must be started before the cowboy application. To start Cowboy and all dependencies at once:

+
+
{ok, _} = application:ensure_all_started(cowboy).
+
+

Environment

+

The cowboy application does not define any application environment configuration parameters.

+

See also

+

ranch(7), cowlib(7)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.7 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3