From 92b54aacc0de5446dd5497c39897b0bbff72e626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 13 Jun 2018 09:54:12 +0200 Subject: Rebuild using Asciideck --- .../en/cowboy/2.4/manual/cowboy.set_env/index.html | 124 +-- .../2.4/manual/cowboy.start_clear/index.html | 159 ++-- .../cowboy/2.4/manual/cowboy.start_tls/index.html | 165 ++-- .../2.4/manual/cowboy.stop_listener/index.html | 87 +-- docs/en/cowboy/2.4/manual/cowboy/index.html | 135 +--- docs/en/cowboy/2.4/manual/cowboy_app/index.html | 178 +---- .../2.4/manual/cowboy_constraints.int/index.html | 92 +-- .../manual/cowboy_constraints.nonempty/index.html | 90 +-- .../2.4/manual/cowboy_constraints/index.html | 85 +-- .../2.4/manual/cowboy_handler.terminate/index.html | 115 +-- .../en/cowboy/2.4/manual/cowboy_handler/index.html | 108 +-- docs/en/cowboy/2.4/manual/cowboy_http/index.html | 321 +++----- docs/en/cowboy/2.4/manual/cowboy_http2/index.html | 279 ++----- docs/en/cowboy/2.4/manual/cowboy_loop/index.html | 140 +--- .../cowboy/2.4/manual/cowboy_middleware/index.html | 123 +-- .../2.4/manual/cowboy_req.binding/index.html | 122 +-- .../2.4/manual/cowboy_req.bindings/index.html | 82 +- .../2.4/manual/cowboy_req.body_length/index.html | 86 +-- .../cowboy/2.4/manual/cowboy_req.cert/index.html | 108 +-- .../cowboy_req.delete_resp_header/index.html | 94 +-- .../2.4/manual/cowboy_req.has_body/index.html | 76 +- .../2.4/manual/cowboy_req.has_resp_body/index.html | 83 +- .../manual/cowboy_req.has_resp_header/index.html | 95 +-- .../cowboy/2.4/manual/cowboy_req.header/index.html | 129 +--- .../2.4/manual/cowboy_req.headers/index.html | 87 +-- .../cowboy/2.4/manual/cowboy_req.host/index.html | 88 +-- .../2.4/manual/cowboy_req.host_info/index.html | 84 +- .../cowboy/2.4/manual/cowboy_req.inform/index.html | 139 +--- .../2.4/manual/cowboy_req.match_cookies/index.html | 134 +--- .../2.4/manual/cowboy_req.match_qs/index.html | 134 +--- .../cowboy/2.4/manual/cowboy_req.method/index.html | 102 +-- .../2.4/manual/cowboy_req.parse_cookies/index.html | 94 +-- .../2.4/manual/cowboy_req.parse_header/index.html | 359 ++++----- .../2.4/manual/cowboy_req.parse_qs/index.html | 118 +-- .../cowboy/2.4/manual/cowboy_req.path/index.html | 87 +-- .../2.4/manual/cowboy_req.path_info/index.html | 84 +- .../cowboy/2.4/manual/cowboy_req.peer/index.html | 97 +-- .../cowboy/2.4/manual/cowboy_req.port/index.html | 88 +-- .../cowboy/2.4/manual/cowboy_req.push/index.html | 162 ++-- docs/en/cowboy/2.4/manual/cowboy_req.qs/index.html | 86 +-- .../2.4/manual/cowboy_req.read_body/index.html | 165 ++-- .../2.4/manual/cowboy_req.read_part/index.html | 200 ++--- .../manual/cowboy_req.read_part_body/index.html | 150 ++-- .../cowboy_req.read_urlencoded_body/index.html | 140 +--- .../cowboy/2.4/manual/cowboy_req.reply/index.html | 190 ++--- .../2.4/manual/cowboy_req.resp_header/index.html | 119 +-- .../2.4/manual/cowboy_req.resp_headers/index.html | 75 +- .../cowboy/2.4/manual/cowboy_req.scheme/index.html | 93 +-- .../2.4/manual/cowboy_req.set_resp_body/index.html | 151 ++-- .../manual/cowboy_req.set_resp_cookie/index.html | 189 ++--- .../manual/cowboy_req.set_resp_header/index.html | 129 +--- .../manual/cowboy_req.set_resp_headers/index.html | 116 +-- .../cowboy/2.4/manual/cowboy_req.sock/index.html | 83 +- .../2.4/manual/cowboy_req.stream_body/index.html | 129 +--- .../2.4/manual/cowboy_req.stream_reply/index.html | 174 ++--- .../manual/cowboy_req.stream_trailers/index.html | 118 +-- .../en/cowboy/2.4/manual/cowboy_req.uri/index.html | 199 ++--- .../2.4/manual/cowboy_req.version/index.html | 85 +-- docs/en/cowboy/2.4/manual/cowboy_req/index.html | 556 +++++--------- docs/en/cowboy/2.4/manual/cowboy_rest/index.html | 845 ++++++++------------- .../2.4/manual/cowboy_router.compile/index.html | 93 +-- docs/en/cowboy/2.4/manual/cowboy_router/index.html | 117 +-- docs/en/cowboy/2.4/manual/cowboy_static/index.html | 221 ++---- docs/en/cowboy/2.4/manual/cowboy_stream/index.html | 540 +++++-------- .../cowboy/2.4/manual/cowboy_websocket/index.html | 370 +++------ .../cowboy/2.4/manual/http_status_codes/index.html | 267 ++----- docs/en/cowboy/2.4/manual/index.html | 178 +---- 67 files changed, 3143 insertions(+), 7568 deletions(-) (limited to 'docs/en/cowboy/2.4/manual') diff --git a/docs/en/cowboy/2.4/manual/cowboy.set_env/index.html b/docs/en/cowboy/2.4/manual/cowboy.set_env/index.html index 89ae117c..5ac0bdb2 100644 --- a/docs/en/cowboy/2.4/manual/cowboy.set_env/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy.set_env/index.html @@ -62,117 +62,59 @@

cowboy:set_env(3)

-

Name

-
-

cowboy:set_env - Update a listener’s environment value

-
-
-
+

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.

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

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

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

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

-
-
-
+

The atom ok is returned on success.

+

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

Changelog

-
-
    -
  • -

    -1.0: Function introduced. -

    +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy.start_clear/index.html b/docs/en/cowboy/2.4/manual/cowboy.start_clear/index.html index 04d9f310..f932cb38 100644 --- a/docs/en/cowboy/2.4/manual/cowboy.start_clear/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy.start_clear/index.html @@ -62,148 +62,77 @@

cowboy:start_clear(3)

-

Name

-
-

cowboy:start_clear - Listen for connections using plain TCP

-
-
-
+

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.

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

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

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

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

-
-
-
+

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: HTTP/2 support added.
      • -
    • -

      -2.0: Function introduced. Replaces cowboy:start_http/4. -

      +
    • 2.0: Function introduced. Replaces cowboy:start_http/4.
      • -
-
-
-
+

Examples

-
-
-
Start a listener
-
-
Dispatch = cowboy_router:compile([
-    {'_', [
-        {"/", toppage_h, []}
+
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,
+
Name = example,
 
-{ok, _} = cowboy:start_clear(Name, [], #{
-    env => #{dispatch => Dispatch}
+{ok, _} = cowboy:start_clear(Name, [], #{
+    env => #{dispatch => Dispatch}
 }),
 
-Port = ranch:get_port(Name).
-
-
-
+Port = ranch:get_port(Name). +

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy.start_tls/index.html b/docs/en/cowboy/2.4/manual/cowboy.start_tls/index.html index 009a39a5..27f8e409 100644 --- a/docs/en/cowboy/2.4/manual/cowboy.start_tls/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy.start_tls/index.html @@ -62,153 +62,82 @@

cowboy:start_tls(3)

-

Name

-
-

cowboy:start_tls - Listen for connections using TLS

-
-
-
+

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.

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

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

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

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

-
-
-
+

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: HTTP/2 support added.
      • -
    • -

      -2.0: Function introduced. Replaces cowboy:start_https/4. -

      +
    • 2.0: Function introduced. Replaces cowboy:start_https/4.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy.stop_listener/index.html b/docs/en/cowboy/2.4/manual/cowboy.stop_listener/index.html index 06b88e2d..59e0c6eb 100644 --- a/docs/en/cowboy/2.4/manual/cowboy.stop_listener/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy.stop_listener/index.html @@ -62,87 +62,42 @@

cowboy:stop_listener(3)

-

Name

-
-

cowboy:stop_listener - Stop the given listener

-
-
-
+

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

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

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

-
-
-
+

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

    +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy/index.html b/docs/en/cowboy/2.4/manual/cowboy/index.html index f9e9e279..fb723a60 100644 --- a/docs/en/cowboy/2.4/manual/cowboy/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy/index.html @@ -62,129 +62,76 @@

cowboy(3)

-

Name

-
-

cowboy - HTTP server

-
-
-
+

cowboy - HTTP server

Description

-
-

The module cowboy provides convenience functions for -manipulating Ranch listeners.

-
-
-
+

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

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

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

- - - -
+
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(7), ranch(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_app/index.html b/docs/en/cowboy/2.4/manual/cowboy_app/index.html index ab3eecf9..11819440 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_app/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_app/index.html @@ -62,171 +62,77 @@

cowboy(7)

-

Name

-
-

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

-
-
-
+

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.

-
-
-
+

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:

-
+

Protocols:

+
-

Handlers:

-
+

Handlers:

+
-

Behaviors:

-
+

Behaviors:

+
-

Middlewares:

-
+

Middlewares:

+
-
-
-
+ +

Dependencies

-
-
    -
  • -

    -ranch(7) - Socket acceptor pool for TCP protocols -

    +
    • ranch(7) - Socket acceptor pool for TCP protocols
      • -
    • -

      -cowlib(7) - Support library for manipulating Web protocols -

      +
    • cowlib(7) - Support library for manipulating Web protocols
      • -
    • -

      -ssl - Secure communication over sockets -

      +
    • ssl - Secure communication over sockets
      • -
    • -

      -crypto - Crypto functions -

      +
    • 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).
-
-
-
+
{ok, _} = application:ensure_all_started(cowboy).
+

Environment

-
-

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

-
- -
+

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

See also

-
-

ranch(7), -cowlib(7)

-
-
+

ranch(7), cowlib(7)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_constraints.int/index.html b/docs/en/cowboy/2.4/manual/cowboy_constraints.int/index.html index aa888d30..38536c3f 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_constraints.int/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_constraints.int/index.html @@ -62,92 +62,52 @@

cowboy_constraints:int(3)

-

Name

-
-

cowboy_constraints:int - Integer constraint

-
-
-
+

cowboy_constraints:int - Integer constraint

Description

-
-

Constraint functions implement a number of different operations.

-
-
-
int(forward, Bin) -> {ok, Int} | {error, not_an_integer}
+
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
+
int(format_error, Error) -> HumanReadable
 
-Error         :: {not_an_integer, Bin | Int}
-HumanReadable :: iolist()
-

Generate a human-readable error message.

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

-
- -
+

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.

-
-
-
+

The return value varies depending on the operation.

Changelog

-
-
    -
  • -

    -2.0: Interface modified to allow for a variety of operations. -

    +
    • 2.0: Interface modified to allow for a variety of operations.
      • -
    • -

      -1.0: Constraint introduced. -

      +
    • 1.0: Constraint introduced.
      • -
-
-
-
+

Examples

-
-

This function is not meant to be called directly.

-
-
-
+

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_constraints(3), cowboy_constraints:nonempty(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_constraints.nonempty/index.html b/docs/en/cowboy/2.4/manual/cowboy_constraints.nonempty/index.html index 25112067..e0369700 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_constraints.nonempty/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_constraints.nonempty/index.html @@ -62,91 +62,51 @@

cowboy_constraints:nonempty(3)

-

Name

-
-

cowboy_constraints:nonempty - Non-empty constraint

-
-
-
+

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}
+
nonempty(forward | reverse, Bin) -> {ok, Bin}
 
-Bin :: binary()
-

Accept any other binary values.

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

Generate a human-readable error message.

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

-
- -
+

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.

-
-
-
+

The return value varies depending on the operation.

Changelog

-
-
    -
  • -

    -2.0: Interface modified to allow for a variety of operations. -

    +
    • 2.0: Interface modified to allow for a variety of operations.
      • -
    • -

      -1.0: Constraint introduced. -

      +
    • 1.0: Constraint introduced.
      • -
-
-
-
+

Examples

-
-

This function is not meant to be called directly.

-
-
-
+

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_constraints(3), cowboy_constraints:int(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_constraints/index.html b/docs/en/cowboy/2.4/manual/cowboy_constraints/index.html index 09db9803..82c7f1a2 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_constraints/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_constraints/index.html @@ -62,84 +62,43 @@

cowboy_constraints(3)

-

Name

-
-

cowboy_constraints - Constraints

-
-
-
+

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.

-
-
-
+

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.

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

-
- - -
+
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(7), cowboy(3), cowboy_router(3), cowboy_req:match_cookies(3), cowboy_req:match_qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_handler.terminate/index.html b/docs/en/cowboy/2.4/manual/cowboy_handler.terminate/index.html index 2c010b6a..f677bbab 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_handler.terminate/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_handler.terminate/index.html @@ -62,109 +62,54 @@

cowboy_handler:terminate(3)

-

Name

-
-

cowboy_handler:terminate - Terminate the handler

-
-
-
+

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.

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

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

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

+
State
+

Handler state.

-
-Handler -
-
-

-Handler module. -

+
Handler
+

Handler module.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.0: Function introduced. -

    +
    • 2.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

cowboy_handler(3)

-
- +

cowboy_handler(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_handler/index.html b/docs/en/cowboy/2.4/manual/cowboy_handler/index.html index 5414b066..e6a0c3f4 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_handler/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_handler/index.html @@ -62,96 +62,46 @@

cowboy_handler(3)

-

Name

-
-

cowboy_handler - Plain HTTP handlers

-
-
-
+

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.

-
-
-
+

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

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

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_http/index.html b/docs/en/cowboy/2.4/manual/cowboy_http/index.html index d7304e5a..467563e1 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_http/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_http/index.html @@ -62,255 +62,116 @@

cowboy_http(3)

-

Name

-
-

cowboy_http - HTTP/1.1

-
-
-
+

cowboy_http - HTTP/1.1

Description

-
-

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

-
-
-
+

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

Options

-
-
-
+ +
-
opts() :: #{
-    connection_type         => worker | supervisor,
-    env                     => cowboy_middleware:env(),
-    idle_timeout            => timeout(),
-    inactivity_timeout      => timeout(),
-    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(),
-    middlewares             => [module()],
-    request_timeout         => timeout(),
-    shutdown_timeout        => timeout(),
-    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:

-
-
-connection_type (supervisor) -
-
-

- Whether the connection process also acts as a supervisor. -

-
-
-env (#{}) -
-
-

- Middleware environment. -

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

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

-
-
-middlewares ([cowboy_router, cowboy_handler]) -
-
-

- Middlewares to run for every request. -

-
-
-request_timeout (5000) -
-
-

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

-
-
-shutdown_timeout (5000) -
-
-

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

-
-
-stream_handlers ([cowboy_stream_h]) -
-
-

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

-
-
-
-
-
+
opts() :: #{
+    connection_type         => worker | supervisor,
+    env                     => cowboy_middleware:env(),
+    idle_timeout            => timeout(),
+    inactivity_timeout      => timeout(),
+    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(),
+    middlewares             => [module()],
+    request_timeout         => timeout(),
+    shutdown_timeout        => timeout(),
+    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:

+
connection_type (supervisor)
+

Whether the connection process also acts as a supervisor.

+
+
env (#{})
+

Middleware environment.

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

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

+
+
middlewares ([cowboy_router, cowboy_handler])
+

Middlewares to run for every request.

+
+
request_timeout (5000)
+

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

+
+
shutdown_timeout (5000)
+

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

+
+
stream_handlers ([cowboy_stream_h])
+

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

+
+

Changelog

-
-
    -
  • -

    -2.2: The max_skip_body_length 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 timeout option was renamed request_timeout.
      • -
    • -

      -2.0: The idle_timeout, inactivity_timeout and shutdown_timeout options were added. -

      +
    • 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_method_length option was added.
      • -
    • -

      -2.0: The max_request_line_length default was increased from 4096 to 8000. -

      +
    • 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 connection_type option was added.
      • -
    • -

      -2.0: The env option is now a map instead of a proplist. -

      +
    • 2.0: The env option is now a map instead of a proplist.
      • -
    • -

      -2.0: The stream_handlers option was added. -

      +
    • 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: 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: Options are now a map instead of a proplist.
      • -
    • -

      -2.0: Protocol introduced. Replaces cowboy_protocol. -

      +
    • 2.0: Protocol introduced. Replaces cowboy_protocol.
      • -
-
-
-
+

See also

-
-

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

-
-
+

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_http2/index.html b/docs/en/cowboy/2.4/manual/cowboy_http2/index.html index ec1b8d28..9b915b91 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_http2/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_http2/index.html @@ -62,243 +62,102 @@

cowboy_http2(3)

-

Name

-
-

cowboy_http2 - HTTP/2

-
-
-
+

cowboy_http2 - HTTP/2

Description

-
-

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

-
-
-
+

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

Options

-
-
-
+ +
-
opts() :: #{
-    connection_type                => worker | supervisor,
-    enable_connect_protocol        => boolean(),
-    env                            => cowboy_middleware:env(),
-    inactivity_timeout             => timeout(),
-    initial_connection_window_size => 65535..16#7fffffff,
-    initial_stream_window_size     => 0..16#7fffffff,
-    max_concurrent_streams         => non_neg_integer() | infinity,
-    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,
-    middlewares                    => [module()],
-    preface_timeout                => timeout(),
-    settings_timeout               => timeout(),
-    shutdown_timeout               => timeout(),
-    stream_handlers                => [module()]
-}
-

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

+
opts() :: #{
+    connection_type                => worker | supervisor,
+    enable_connect_protocol        => boolean(),
+    env                            => cowboy_middleware:env(),
+    inactivity_timeout             => timeout(),
+    initial_connection_window_size => 65535..16#7fffffff,
+    initial_stream_window_size     => 0..16#7fffffff,
+    max_concurrent_streams         => non_neg_integer() | infinity,
+    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,
+    middlewares                    => [module()],
+    preface_timeout                => timeout(),
+    settings_timeout               => timeout(),
+    shutdown_timeout               => timeout(),
+    stream_handlers                => [module()]
+}
+
+

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.

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

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

-
-env (#{}) -
-
-

- Middleware environment. -

+
env (#{})
+

Middleware environment.

-
-inactivity_timeout (300000) -
-
-

- Time in ms with nothing received at all 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 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_connection_window_size (65535)
+

Initial window size 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 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. -

+
initial_stream_window_size (65535)
+

Initial window size 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.

-
-max_concurrent_streams (infinity) -
-
-

- Maximum number of concurrent streams allowed on the connection. -

+
max_concurrent_streams (infinity)
+

Maximum number of concurrent streams allowed on the connection.

-
-max_decode_table_size (4096) -
-
-

- Maximum header table size 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_decode_table_size (4096)
+

Maximum header table size 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 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_encode_table_size (4096)
+

Maximum header table size 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 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_received (16384)
+

Maximum size 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 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_frame_size_sent (infinity)
+

Maximum size 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.

-
-middlewares ([cowboy_router, cowboy_handler]) -
-
-

- Middlewares to run for every request. -

+
middlewares ([cowboy_router, cowboy_handler])
+

Middlewares to run for every request.

-
-preface_timeout (5000) -
-
-

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

+
preface_timeout (5000)
+

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

-
-settings_timeout (5000) -
-
-

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

+
settings_timeout (5000)
+

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

-
-shutdown_timeout (5000) -
-
-

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

+
shutdown_timeout (5000)
+

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

-
-stream_handlers ([cowboy_stream_h]) -
-
-

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

+
stream_handlers ([cowboy_stream_h])
+

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

-
-
-
-
+

Changelog

-
-
    -
  • -

    -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 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.4: Add the experimental option enable_connect_protocol.
      • -
    • -

      -2.0: Protocol introduced. -

      +
    • 2.0: Protocol introduced.
      • -
-
-
-
+

See also

-
-

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

-
-
+

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_loop/index.html b/docs/en/cowboy/2.4/manual/cowboy_loop/index.html index ea078cb9..a6348946 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_loop/index.html @@ -62,120 +62,60 @@

cowboy_loop(3)

-

Name

-
-

cowboy_loop - Loop handlers

-
-
-
+

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

    +

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

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

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

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

    +
    • 2.0: Loop handlers no longer need to handle overflow/timeouts.
      • -
    • -

      -1.0: Behavior introduced. -

      +
    • 1.0: Behavior introduced.
      • -
-
-
-
+

See also

-
-

cowboy(7), -cowboy_handler(3)

-
-
+

cowboy(7), cowboy_handler(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.4/manual/cowboy_middleware/index.html index e7e7de29..8d5a30ad 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_middleware/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_middleware/index.html @@ -62,115 +62,56 @@

cowboy_middleware(3)

-

Name

-
-

cowboy_middleware - Middlewares

-
-
-
+

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.

-
-
-
+

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

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

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

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

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

    +
    • 2.0: The env type is now a map instead of a proplist.
      • -
    • -

      -1.0: Behavior introduced. -

      +
    • 1.0: Behavior introduced.
      • -
-
- -
+

See also

-
-

cowboy(7)

-
-
+

cowboy(7)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.binding/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.binding/index.html index 46d46121..95666a38 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.binding/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.binding/index.html @@ -62,116 +62,60 @@

cowboy_req:binding(3)

-

Name

-
-

cowboy_req:binding - Access a value bound from the route

-
-
-
+

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.

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

+
Name
+

Desired binding name as an atom.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Default -
-
-

-Default value returned when the binding is missing. -

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 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">>)
-
-
-
+
%% 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_req(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_req:path_info(3), cowboy_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.bindings/index.html index 12415270..aa61c3ac 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.bindings/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.bindings/index.html @@ -62,86 +62,40 @@

cowboy_req:bindings(3)

-

Name

-
-

cowboy_req:bindings - Access all values bound from the route

-
-
-
+

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.

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

Return a map containing all bindings.

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get all bindings
-
-
Bindings = cowboy_req:bindings(Req).
-
-
-
+
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_req(3), cowboy_req:binding(3), cowboy_req:host_info(3), cowboy_req:path_info(3), cowboy_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.body_length/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.body_length/index.html index de5f9045..fe1fc5bc 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.body_length/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.body_length/index.html @@ -62,89 +62,41 @@

cowboy_req:body_length(3)

-

Name

-
-

cowboy_req:body_length - Body length

-
-
-
+

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.

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

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get the body length
-
-
Length = cowboy_req:body_length(Req).
-
-
-
+
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_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)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.cert/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.cert/index.html index 5035f160..3222b2f3 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.cert/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.cert/index.html @@ -62,104 +62,60 @@

cowboy_req:cert(3)

-

Name

-
-

cowboy_req:cert - Client TLS certificate

-
-
-
+

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},
-    {cert, "path/to/cert.pem"},
-    {verify, verify_peer}
+
{ok, _} = cowboy:start_tls(example, [
+    {port, 8443},
+    {cert, "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.
-
-
-
+
#{cert := Cert} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

The client TLS certificate.

-
-
-
+

The client TLS certificate.

Changelog

-
-
    -
  • -

    -2.1: Function introduced. -

    +
    • 2.1: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.delete_resp_header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.delete_resp_header/index.html index 073d8fb9..8dfbb72d 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.delete_resp_header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.delete_resp_header/index.html @@ -62,95 +62,45 @@

cowboy_req:delete_resp_header(3)

-

Name

-
-

cowboy_req:delete_resp_header - Delete a response header

-
-
-
+

cowboy_req:delete_resp_header - Delete a response header

Description

-
-
-
-
delete_resp_header(Name, Req :: cowboy_req:req()) -> Req
+
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.

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

+
Name
+

Header name as a lowercase binary string.

-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Remove the content-type header from the response
-
-
Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0),
-
-
-
+
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_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)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.has_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.has_body/index.html index c093e60d..591691aa 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.has_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.has_body/index.html @@ -62,80 +62,38 @@

cowboy_req:has_body(3)

-

Name

-
-

cowboy_req:has_body - Is there a request body?

-
-
-
+

cowboy_req:has_body - Is there a request body?

Description

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

Return whether the request has a body.

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

Return whether the request has a body.

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

A boolean indicating whether the request has a body.

-
-
-
+

A boolean indicating whether the request has a body.

Changelog

-
-
    -
  • -

    -1.0: Function introduced. -

    +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Ensure the request has a body
-
-
true = cowboy_req:has_body(Req).
-
-
-
+
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_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)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_body/index.html index e99ff1b7..34624718 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_body/index.html @@ -62,82 +62,43 @@

cowboy_req:has_resp_body(3)

-

Name

-
-

cowboy_req:has_resp_body - Is there a response body?

-
-
-
+

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.

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

Return whether a response body has been set.

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 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).
-
-
-
+
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_req(3), cowboy_req:set_resp_body(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_header/index.html index 21eca0bc..2d613eca 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.has_resp_header/index.html @@ -62,95 +62,46 @@

cowboy_req:has_resp_header(3)

-

Name

-
-

cowboy_req:has_resp_header - Is the given response header set?

-
-
-
+

cowboy_req:has_resp_header - Is the given response header set?

Description

-
-
-
-
has_resp_header(Name, Req :: cowboy_req:req()) -> boolean()
+
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.

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

+
Name
+

Header name as a lowercase binary string.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -1.0: Function introduced. -

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.header/index.html index ed2978a7..487a76da 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.header/index.html @@ -62,122 +62,67 @@

cowboy_req:header(3)

-

Name

-
-

cowboy_req:header - HTTP header

-
-
-
+

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.

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

+
Name
+

Desired HTTP header name as a lowercase binary string.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Default -
-
-

-Default value returned when the header is missing. -

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 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">>).
-
-
-
+
Length = cowboy_req:header(<<"content-length">>, Req, <<"0">>).
+

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.headers/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.headers/index.html index 420c594e..514d9f2a 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.headers/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.headers/index.html @@ -62,90 +62,47 @@

cowboy_req:headers(3)

-

Name

-
-

cowboy_req:headers - HTTP headers

-
-
-
+

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.
-
-
-
+
#{headers := Headers} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.host/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.host/index.html index f04f7c16..a8e0e313 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.host/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.host/index.html @@ -62,91 +62,47 @@

cowboy_req:host(3)

-

Name

-
-

cowboy_req:host - URI host 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.
-
-
-
+
#{host := Host} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.host_info/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.host_info/index.html index 16947144..bff72d35 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.host_info/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.host_info/index.html @@ -62,87 +62,41 @@

cowboy_req:host_info(3)

-

Name

-
-

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

-
-
-
+

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.

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

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get the host_info tokens
-
-
HostInfo = cowboy_req:host_info(Req).
-
-
-
+
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_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:path_info(3), cowboy_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.inform/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.inform/index.html index b017d12d..b3c27fe1 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.inform/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.inform/index.html @@ -62,125 +62,66 @@

cowboy_req:inform(3)

-

Name

-
-

cowboy_req:inform - Send an informational response

-
-
-
+

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.

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

+
Status
+

The status code for the response.

-
-Headers -
-
-

-The response headers. -

+
Headers
+

The response headers.

-
-

Header names must be given as lowercase binary strings.

-
-
-Req -
-
-

-The Req object. -

+
+

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.

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.1: Function introduced. -

    +
    • 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).
-
-
-
+
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_req(3), cowboy_req:reply(3), cowboy_req:stream_reply(3), cowboy_req:push(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.match_cookies/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.match_cookies/index.html index b5ebef85..9b524b1c 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.match_cookies/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.match_cookies/index.html @@ -62,123 +62,67 @@

cowboy_req:match_cookies(3)

-

Name

-
-

cowboy_req:match_cookies - Match cookies against constraints

-
-
-
+

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.

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

Arguments

-
-
-
-Fields -
-
-

-Cookies to retrieve. -

-

See cowboy(3) for a complete description.

+
Fields
+

Cookies to retrieve.

+

See cowboy(3) for a complete description.

-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 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).
-
-
-
+
#{lang := Lang}
+    = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).
+

See also

-
-

cowboy_req(3), -cowboy_req:parse_cookies(3)

-
- +

cowboy_req(3), cowboy_req:parse_cookies(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.match_qs/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.match_qs/index.html index 634b6723..b46745c6 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.match_qs/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.match_qs/index.html @@ -62,123 +62,67 @@

cowboy_req:match_qs(3)

-

Name

-
-

cowboy_req:match_qs - Match the query string against constraints

-
-
-
+

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.

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

+
Fields
+

Fields to retrieve from the query string.

+

See cowboy(3) for a complete description.

-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 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).
-
-
-
+
#{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_req(3), cowboy_req:qs(3), cowboy_req:parse_qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.method/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.method/index.html index 5619ed1f..facfa943 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.method/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.method/index.html @@ -62,100 +62,58 @@

cowboy_req:method(3)

-

Name

-
-

cowboy_req:method - HTTP method

-
-
-
+

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.
-
-
-
+
#{method := Method} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 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.
-
-
-
+
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_req(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.parse_cookies/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.parse_cookies/index.html index 932f72a3..d8188db0 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.parse_cookies/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.parse_cookies/index.html @@ -62,91 +62,47 @@

cowboy_req:parse_cookies(3)

-

Name

-
-

cowboy_req:parse_cookies - Parse cookie headers

-
-
-
+

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, [] is returned.

-

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

-
-
-
+
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, [] is returned.

+

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

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

      +
    • 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).
-
-
-
+
Cookies = cowboy_req:parse_cookies(Req),
+{_, Token} = lists:keyfind(<<"token">>, 1, Cookies).
+

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.parse_header/index.html index a074485f..a4e0c4d7 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.parse_header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.parse_header/index.html @@ -62,283 +62,218 @@

cowboy_req:parse_header(3)

-

Name

-
-

cowboy_req:parse_header - Parse the given HTTP header

-
-
-
+

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.

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

+
Name
+

Desired HTTP header name as a lowercase binary string.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Default -
-
-

-Default value returned when the header is missing. -

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

-
-
-
+

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
-
+
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]
+
parse_header(<<"x-forwarded-for">>, Req) -> [Token]
 
-Token :: binary()                   %% case sensitive
-
-
Unknown headers
-
-
parse_header(_, Req) -> {undefined, RawValue}
-
-
-
+
parse_header(_, Req) -> {undefined, RawValue}
+

Changelog

-
-
    -
  • -

    -2.0: Only the parsed header value is returned, it is no longer wrapped in a tuple. -

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

      -1.0: Function introduced. -

      +
    • 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).
-
-
-
+
%% 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_req(3), cowboy_req:header(3), cowboy_req:headers(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.parse_qs/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.parse_qs/index.html index bff11c10..1680b60e 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.parse_qs/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.parse_qs/index.html @@ -62,117 +62,55 @@

cowboy_req:parse_qs(3)

-

Name

-
-

cowboy_req:parse_qs - Parse the query string

-
-
-
+

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.

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

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

    +

    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?edit&exclusive=1
      • -
    • -

      -/posts/42?exclusive=1&edit -

      +
    • /posts/42?exclusive=1&edit
      • -
    • -

      -/posts/42?exclusive=1&edit&from=web -

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

Changelog

-
-
    -
  • -

    -2.0: The parsed value is not longer cached in the Req object. -

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

      +
    • 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].
-
-
-
+
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_req(3), cowboy_req:qs(3), cowboy_req:match_qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.path/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.path/index.html index 4779baf5..0fe2594d 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.path/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.path/index.html @@ -62,90 +62,47 @@

cowboy_req:path(3)

-

Name

-
-

cowboy_req:path - URI path

-
-
-
+

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.
-
-
-
+
#{path := Path} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.path_info/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.path_info/index.html index 9adc2dfd..cc5a9709 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.path_info/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.path_info/index.html @@ -62,87 +62,41 @@

cowboy_req:path_info(3)

-

Name

-
-

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

-
-
-
+

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.

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

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get the path_info tokens
-
-
PathInfo = cowboy_req:path_info(Req).
-
-
-
+
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_req(3), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.peer/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.peer/index.html index bbce29da..9271abc7 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.peer/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.peer/index.html @@ -62,98 +62,51 @@

cowboy_req:peer(3)

-

Name

-
-

cowboy_req:peer - Peer address and port

-
-
-
+

cowboy_req:peer - Peer address and port

Description

-
-
-
-
peer(Req :: cowboy_req:req()) -> Info
+
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.
-
-
-
+
#{peer := {IP, Port}} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.port/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.port/index.html index 30c8840e..6db57560 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.port/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.port/index.html @@ -62,90 +62,48 @@

cowboy_req:port(3)

-

Name

-
-

cowboy_req:port - URI port number

-
-
-
+

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.
-
-
-
+
#{port := Port} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

The port number is returned as an integer.

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

cowboy_req(3)

-
- +

cowboy_req(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.push/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.push/index.html index 1ad3e8f8..6b2f47a5 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.push/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.push/index.html @@ -62,142 +62,74 @@

cowboy_req:push(3)

-

Name

-
-

cowboy_req:push - Push a resource to the client

-
-
-
+

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.

-

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

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

+

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

+
Path
+

The status code for the response.

-
-Headers -
-
-

-The response headers. -

+
Headers
+

The response headers.

-
-

Header names must be given as lowercase binary strings.

-
-
-Req -
-
-

-The Req object. -

+
+

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

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.0: Function introduced. -

    +
    • 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),
-
-
-
+
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_req(3), cowboy_req:inform(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.qs/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.qs/index.html index ef4fd23f..66e4ebbd 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.qs/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.qs/index.html @@ -62,89 +62,47 @@

cowboy_req:qs(3)

-

Name

-
-

cowboy_req:qs - URI query string

-
-
-
+

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.
-
-
-
+
#{qs := Qs} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

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

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.read_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.read_body/index.html index d4c2157a..1be995a0 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.read_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.read_body/index.html @@ -62,143 +62,72 @@

cowboy_req:read_body(3)

-

Name

-
-

cowboy_req:read_body - Read the request body

-
-
-
+

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.

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

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

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

-
-
-
+

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

    +
    • 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}).
-
-
-
+
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_part(3), -cowboy_req:read_part_body(3)

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html index 50931838..7746b475 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.read_part/index.html @@ -62,162 +62,94 @@

cowboy_req:read_part(3)

-

Name

-
-

cowboy_req:read_part - Read the next multipart headers

-
-
-
+

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.

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

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

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

-
-
-
+

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

    +
    • 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}).
-
-
-
+
{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_part_body(3)

-
- +

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_body(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.read_part_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.read_part_body/index.html index 340bb2cb..403a6271 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.read_part_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.read_part_body/index.html @@ -62,130 +62,70 @@

cowboy_req:read_part_body(3)

-

Name

-
-

cowboy_req:read_part_body - Read the current part’s body

-
-
-
+

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.

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

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

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

-
-
-
+

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

    +
    • 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}).
-
-
-
+
{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_part(3)

-
- +

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)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.read_urlencoded_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.read_urlencoded_body/index.html index 9565153e..be73fe71 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.read_urlencoded_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.read_urlencoded_body/index.html @@ -62,126 +62,64 @@

cowboy_req:read_urlencoded_body(3)

-

Name

-
-

cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body

-
-
-
+

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.

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

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

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

-
-
-
+

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

    +
    • 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}).
-
-
-
+
{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_part(3), -cowboy_req:read_part_body(3)

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.reply/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.reply/index.html index e980e297..bb8a0c83 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.reply/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.reply/index.html @@ -62,165 +62,87 @@

cowboy_req:reply(3)

-

Name

-
-

cowboy_req:reply - Send the response

-
-
-
+

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.

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

+
Status
+

The status code for the response.

-
-Headers -
-
-

-The response headers. -

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

+
+

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

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

-
-
-
+

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

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

      -1.0: Function introduced. -

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.resp_header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.resp_header/index.html index 76d70761..9a11c12d 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.resp_header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.resp_header/index.html @@ -62,113 +62,58 @@

cowboy_req:resp_header(3)

-

Name

-
-

cowboy_req:resp_header - Response header

-
-
-
+

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.

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

+
Name
+

Desired response header name as a lowercase binary string.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Default -
-
-

-Default value returned when the header is missing. -

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.0: Function introduced. -

    +
    • 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">>).
-
-
-
+
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_req(3), cowboy_req:resp_headers(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.resp_headers/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.resp_headers/index.html index 54cc8537..a0c4ff34 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.resp_headers/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.resp_headers/index.html @@ -62,79 +62,38 @@

cowboy_req:resp_headers(3)

-

Name

-
-

cowboy_req:resp_headers - Response headers

-
-
-
+

cowboy_req:resp_headers - Response headers

Description

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

Return all response headers.

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

Return all response headers.

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.0: Function introduced. -

    +
    • 2.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get all response headers
-
-
Headers = cowboy_req:resp_headers(Req).
-
-
-
+
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_req(3), cowboy_req:resp_header(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.scheme/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.scheme/index.html index a1227edf..3f73db92 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.scheme/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.scheme/index.html @@ -62,89 +62,52 @@

cowboy_req:scheme(3)

-

Name

-
-

cowboy_req:scheme - URI scheme

-
-
-
+

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.
-
-
-
+
#{scheme := Scheme} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 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}.
-
-
-
+
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_req(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_body/index.html index a41023dd..20331259 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_body/index.html @@ -62,138 +62,79 @@

cowboy_req:set_resp_body(3)

-

Name

-
-

cowboy_req:set_resp_body - Set the response body

-
-
-
+

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.

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

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

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

-
-
-
+

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 function now accepts a sendfile tuple.
      • -
    • -

      -2.0: The set_resp_body_fun/2,3 functions were removed. -

      +
    • 2.0: The set_resp_body_fun/2,3 functions were removed.
      • -
    • -

      -1.0: Function introduced. -

      +
    • 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).
-
-
-
+
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_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_cookie/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_cookie/index.html index 157e9162..6844dc8e 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_cookie/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_cookie/index.html @@ -62,167 +62,104 @@

cowboy_req:set_resp_cookie(3)

-

Name

-
-

cowboy_req:set_resp_cookie - Set a cookie

-
-
-
+

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.

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

+
Name
+

Cookie name.

-
-Value -
-
-

-Cookie value. -

+
Value
+

Cookie value.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-Opts -
-
-

-Cookie options. -

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

-
-
-
+

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: 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(). -

      +
    • 2.0: The first argument type is now binary() instead of iodata().
      • -
    • -

      -1.0: Function introduced. -

      +
    • 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}).
-
-
-
+
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_req(3), cowboy_req:set_resp_header(3), cowboy_req:set_resp_headers(3), cowboy_req:reply(3), cowboy_req:stream_reply(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_header/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_header/index.html index 9bb6ad4a..64350df0 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_header/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_header/index.html @@ -62,121 +62,60 @@

cowboy_req:set_resp_header(3)

-

Name

-
-

cowboy_req:set_resp_header - Set a response header

-
-
-
+

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.

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

+
Name
+

Header name as a lowercase binary string.

-
-Value -
-
-

-Header value. -

+
Value
+

Header value.

-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_headers/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_headers/index.html index cbd6ade8..7481bf57 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_headers/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.set_resp_headers/index.html @@ -62,109 +62,51 @@

cowboy_req:set_resp_headers(3)

-

Name

-
-

cowboy_req:set_resp_headers - Set several response headers

-
-
-
+

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.

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

+
Headers
+

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

-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 2.0: Function introduced.
      • -
-
-
-
+

Examples

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.sock/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.sock/index.html index 5bfb7e57..c9da79f7 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.sock/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.sock/index.html @@ -62,86 +62,47 @@

cowboy_req:sock(3)

-

Name

-
-

cowboy_req:sock - Socket address and port

-
-
-
+

cowboy_req:sock - Socket address and port

Description

-
-
-
-
sock(Req :: cowboy_req:req()) -> Info
+
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.
-
-
-
+
#{sock := {IP, Port}} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

The socket’s local IP address and port number.

-
-
-
+

The socket's local IP address and port number.

Changelog

-
-
    -
  • -

    -2.1: Function introduced. -

    +
    • 2.1: Function introduced.
      • -
-
-
-
+

Examples

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

See also

-
-

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

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.stream_body/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.stream_body/index.html index 97ae71b6..0a3ca04f 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.stream_body/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.stream_body/index.html @@ -62,119 +62,56 @@

cowboy_req:stream_body(3)

-

Name

-
-

cowboy_req:stream_body - Stream the response body

-
-
-
+

cowboy_req:stream_body - Stream the response body

Description

-
-
-
-
stream_body(Data, IsFin, Req :: cowboy_req:req()) -> ok
-
-Data  :: iodata()
-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.

-
-
-
+
stream_body(Data, IsFin, Req :: cowboy_req:req()) -> ok
+
+Data  :: iodata()
+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. -

+
Data
+

The data to be sent.

-
-IsFin -
-
-

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

+
IsFin
+

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

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.0: Function introduced. Replaces chunk/2. -

    +
    • 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).
-
-
-
+
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_trailers(3)

-
- +

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.stream_reply/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.stream_reply/index.html index 9534020b..17382cf6 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.stream_reply/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.stream_reply/index.html @@ -62,152 +62,76 @@

cowboy_req:stream_reply(3)

-

Name

-
-

cowboy_req:stream_reply - Send the response headers

-
-
-
+

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

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

+
Status
+

The status code for the response.

-
-Headers -
-
-

-The response headers. -

+
Headers
+

The response headers.

-
-

Header names must be given as lowercase binary strings.

-
-
-Req -
-
-

-The Req object. -

+
+

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.

-
-
-
+

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: Only the Req is returned, it is no longer wrapped in a tuple.
      • -
    • -

      -2.0: Function introduced. Replaces chunked_reply/1,2. -

      +
    • 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).
-
-
-
+
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_trailers(3), -cowboy_req:push(3)

-
- +

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_trailers(3), cowboy_req:push(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.stream_trailers/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.stream_trailers/index.html index 9f08091c..6a96ed52 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.stream_trailers/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.stream_trailers/index.html @@ -62,107 +62,55 @@

cowboy_req:stream_trailers(3)

-

Name

-
-

cowboy_req:stream_trailers - Send the response trailers

-
-
-
+

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.

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

+
Trailers
+

Trailer field values to be sent.

-
-Req -
-
-

-The Req object. -

+
Req
+

The Req object.

-
-
- -
+

Return value

-
-

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

-
-
-
+

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

Changelog

-
-
    -
  • -

    -2.2: Function introduced. -

    +
    • 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).
-
-
-
+
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(3), cowboy_req:stream_reply(3), cowboy_req:stream_body(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.uri/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.uri/index.html index c7e9efc4..e70c3d45 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.uri/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.uri/index.html @@ -62,177 +62,106 @@

cowboy_req:uri(3)

-

Name

-
-

cowboy_req:uri - Reconstructed URI

-
-
-
+

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.

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

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

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

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

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

-
-
-
+

The reconstructed URI is returned as an iolist or a binary string.

Changelog

-
-
    -
  • -

    -2.0: Individual components can be replaced or disabled. -

    +
    • 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: Only the URI is returned, it is no longer wrapped in a tuple.
      • -
    • -

      -2.0: Function introduced. Replaces host_url/1 and url/1. -

      +
    • 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)).
-
-
-
+
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_req(3), cowboy_req:scheme(3), cowboy_req:host(3), cowboy_req:port(3), cowboy_req:path(3), cowboy_req:qs(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req.version/index.html b/docs/en/cowboy/2.4/manual/cowboy_req.version/index.html index ad6cb189..ecf55796 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req.version/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req.version/index.html @@ -62,88 +62,47 @@

cowboy_req:version(3)

-

Name

-
-

cowboy_req:version - HTTP version

-
-
-
+

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.
-
-
-
+
#{version := Version} = Req.
+

Arguments

-
-
-
-Req -
-
-

-The Req object. -

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

-
-
-
+

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

    +
    • 2.0: Only the version is returned, it is no longer wrapped in a tuple.
      • -
    • -

      -1.0: Function introduced. -

      +
    • 1.0: Function introduced.
      • -
-
-
-
+

Examples

-
-
-
Get the HTTP version
-
-
Version = cowboy_req:version(Req).
-
-
-
+
Version = cowboy_req:version(Req).
+

See also

-
-

cowboy_req(3)

-
- +

cowboy_req(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_req/index.html b/docs/en/cowboy/2.4/manual/cowboy_req/index.html index 27795e51..f8d793ab 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_req/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_req/index.html @@ -62,414 +62,218 @@

cowboy_req(3)

-

Name

-
-

cowboy_req - HTTP request and response

-
-
-
+

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:

-
- ---- - - - - - - - - - - - +

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:

+
Type Name pattern Return type

access

no verb, parse_*, match_*

Value

+ + + + + + - - - - + + + - - - - + + + - - - - + + + - -
TypeName patternReturn type
accessno verb, parse_*, match_*Value

question

has_*

boolean()

questionhas_*boolean()

modification

set_*

Req

modificationset_*Req

action

any other verb

ok | {Result, Value, 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.

-
-
-
+ +

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:

-
-
-
-
+

Connection:

+ +

Raw request:

+ +

Processed request:

+ +

Request body:

+ +

Response:

+

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.

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

-
-
+
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}.
- -
+
Req#{_myapp_auth_method => pubkey}.
+

resp_body()

-
-
-
resp_body() :: iodata()
-    | {sendfile, Offset, Length, Filename}
+
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.

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

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_rest/index.html b/docs/en/cowboy/2.4/manual/cowboy_rest/index.html index 1c8bed7c..77a021bb 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_rest/index.html @@ -62,670 +62,475 @@

cowboy_rest(3)

-

Name

-
-

cowboy_rest - REST handlers

-
-
-
+

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

-
-
-
+

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

+

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

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

-
-
+
+
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}
+
allowed_methods(Req, State) -> {Result, Req, State}
 
-Result  :: [binary()]  %% case sensitive
-Default :: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
-

Return the list of allowed methods.

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

-
-
+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}
+
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:

-
-
+

Cowboy will add the negotiated charset to the Req object after this step completes:

+
-
req() :: #{
-    charset => binary()  %% lowercase; case insensitive
-}
-
-
+
req() :: #{
+    charset => binary()  %% lowercase; case insensitive
+}
+

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.

-

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

+ + + +

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.

-

Cowboy will add the negotiated media_type to the Req object -after this step completes:

-
-
-
req() :: #{
-    media_type => ParsedMime
-}
-
-
+
+
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.

+

Cowboy will add the negotiated media_type to the Req object after this step completes:

+
+
req() :: #{
+    media_type => ParsedMime
+}
+
+

delete_completed

-
-
-
delete_completed(Req, State) -> {Result, Req, State}
+
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.

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

- -
+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}
+
expires(Req, State) -> {Result, Req, State}
 
-Result  :: calendar:datetime() | binary() | undefined
-Default :: undefined
-

Return the resource’s expiration date.

- -
+Result :: calendar:datetime() | binary() | undefined +Default :: undefined +
+

Return the resource's expiration date.

forbidden

-
-
-
forbidden(Req, State) -> {Result, Req, State}
+
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.

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

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

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

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

- -
+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}
+
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:

-
-
+

Cowboy will add the negotiated language to the Req object after this step completes:

+
-
req() :: #{
-    language => binary()  %% lowercase; case insensitive
-}
-
-
+
req() :: #{
+    language => binary()  %% lowercase; case insensitive
+}
+

last_modified

-
-
-
last_modified(Req, State) -> {Result, Req, State}
+
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.

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

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

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

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

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

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.

-
-
+
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}
+
previously_existed(Req, State) -> {Result, Req, State}
 
-Result  :: boolean()
-Default :: false
-

Return whether the resource existed previously.

- -
+Result :: boolean() +Default :: false +
+

Return whether the resource existed previously.

ProvideCallback

-
-
-
ProvideCallback(Req, State) -> {Result, Req, State}
+
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.

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

+

resource_exists

-
-
-
resource_exists(Req, State) -> {Result, Req, State}
+
resource_exists(Req, State) -> {Result, Req, State}
 
-Result  :: boolean()
-Default :: true
-

Return whether the resource exists.

- -
+Result :: boolean() +Default :: true +
+

Return whether the resource exists.

service_available

-
-
-
service_available(Req, State) -> {Result, Req, State}
+
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.

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

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

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

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

- - - -
+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.1: The switch_handler return value was added. -

    +
    • 2.1: The switch_handler return value was added.
      • -
    • -

      -1.0: Behavior introduced. -

      +
    • 1.0: Behavior introduced.
      • -
-
- -
+

See also

-
-

cowboy(7), -cowboy_handler(3)

-
-
+

cowboy(7), cowboy_handler(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_router.compile/index.html b/docs/en/cowboy/2.4/manual/cowboy_router.compile/index.html index c3eb3884..1aac627b 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_router.compile/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_router.compile/index.html @@ -62,87 +62,48 @@

cowboy_router:compile(3)

-

Name

-
-

cowboy_router:compile - Compile routes to the resources

-
-
-
+

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.

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

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

-
-
-
+

An opaque dispatch rules value is returned. This value must be given to Cowboy as a middleware environment value.

Changelog

-
-
    -
  • -

    -1.0: Function introduced. -

    +
    • 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}
-}).
-
-
-
+
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_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_router/index.html b/docs/en/cowboy/2.4/manual/cowboy_router/index.html index 0169ae42..e08c3983 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_router/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_router/index.html @@ -62,110 +62,65 @@

cowboy_router(3)

-

Name

-
-

cowboy_router - Router middleware

-
-
-
+

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.

-

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.

-
-
-
+

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.

+

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.

-
-
+
bindings() :: #{atom() => any()}
+
+

Bindings found during routing.

dispatch_rules()

-

Opaque type containing the compiled routes.

-
-
+

Opaque type containing the compiled routes.

routes()

-
-
-
routes() = [
-    {Host, PathList} |
-    {Host, Fields, PathList}
+
routes() = [
+    {Host, PathList} |
+    {Host, Fields, PathList}
 ]
 
-PathList :: [
-    {Path, Handler, InitialState} |
-    {Path, Fields, Handler, InitialState}
+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.

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

- - - -
+
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(7), cowboy_req:binding(3), cowboy_req:bindings(3), cowboy_req:host_info(3), cowboy_req:path_info(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_static/index.html b/docs/en/cowboy/2.4/manual/cowboy_static/index.html index d1bfd062..0bad63bb 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_static/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_static/index.html @@ -62,175 +62,110 @@

cowboy_static(3)

-

Name

-
-

cowboy_static - Static file handler

-
-
-
+

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.

-
-
-
+

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      :: [Etag | Mimetypes]
-
-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.

+
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      :: [Etag | Mimetypes]
+
+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.

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

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

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

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

-
-
    -
  • -

    -1.0: Handler introduced. -

    +
    • 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.
-
-
-
+
always_octet_stream(_Path) ->
+    case filename:extension(Path) of
+        <<".erl">> -> {<<"text">>, <<"plain">>, []};
+        _ -> {<<"application">>, <<"octet-stream">>, []}
+    end.
+

See also

-
-

cowboy(7), -cowboy_router(3)

-
- +

cowboy(7), cowboy_router(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_stream/index.html b/docs/en/cowboy/2.4/manual/cowboy_stream/index.html index bd9ef67b..b3ff1222 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_stream/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_stream/index.html @@ -62,452 +62,306 @@

cowboy_stream(3)

-

Name

-
-

cowboy_handler - Stream handlers

-
-
-
+

cowboy_handler - 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 omit them.

-
-
-
+

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

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

-
+

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.

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

- -
+
{response, cowboy:http_status(), cowboy:http_headers(),
+    cowboy_req:resp_body()}
+
+

No more data can be sent after this command.

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.

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

data

-

Send data to the client.

-
-
-
{data, fin(), iodata()}
- -
+
{data, fin(), iodata()}
+

trailers

-

Send response trailers to the client.

-
-
-
{trailers, cowboy:http_headers()}
- -
+
{trailers, cowboy:http_headers()}
+

push

-

Push a resource to the client.

-
-
-
{push, Method, Scheme, Host, inet:port_number(),
-    Path, Qs, cowboy:http_headers()}
+
{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.

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

- -
+
{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()}
- -
+
{spawn, pid(), timeout()}
+

error_response

-

Send an error response if no response was sent previously.

-
-
-
{error_response, cowboy:http_status(), cowboy:http_headers(), iodata()}
- -
+
{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.

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

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.

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

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

Predefined events

-
-

Cowboy will forward all messages sent to the stream to -the info/3 callback. To send a message to a stream, -send a message to the connection process with the form -{{Pid, StreamID}, Msg}. The connection process will -then forward Msg to the stream handlers.

-

Cowboy will also forward the exit signals for the -processes that the stream spawned.

-
+

Cowboy will forward all messages sent to the stream to the info/3 callback. To send a message to a stream, send a message to the connection process with the form {{Pid, StreamID}, Msg}. The connection process will then forward Msg to the stream handlers.

+

Cowboy will also forward the exit signals for the processes that the stream spawned.

EXIT

-

A process spawned by this stream has exited.

-
-
+ + +

A process spawned by this stream has exited.

+
-
{'EXIT', pid(), any()}
-

This is the raw exit message without any modification.

-
-
+
{'EXIT', pid(), any()}
+
+

This is the raw exit message without any modification.

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

inform

-

Same as the inform command.

-

Sent when the request process reads the body and an -expect: 100-continue header was present in the request, -or when the request process sends an informational -response on its own.

-
-
+

Same as the inform command.

+

Sent when the request process reads the body and an expect: 100-continue header was present in the request, or when the request process sends an informational response on its own.

response

-

Same as the response command.

-

Usually sent when the request process replies to the client. -May also be sent by Cowboy internally.

-
-
+

Same as the response command.

+

Usually sent when the request process replies to the client. May also be sent by Cowboy internally.

headers

-

Same as the headers command.

-

Sent when the request process starts replying to the client.

-
-
+

Same as the headers command.

+

Sent when the request process starts replying to the client.

data

-

Same as the data command.

-

Sent when the request process streams data to the client.

-
-
+

Same as the data command.

+

Sent when the request process streams data to the client.

trailers

-

Same as the trailers command.

-

Sent when the request process sends the trailer field values -to the client.

-
-
+

Same as the trailers command.

+

Sent when the request process sends the trailer field values to the client.

push

-

Same as the push command.

-

Sent when the request process pushes a resource to the client.

-
-
+

Same as the push command.

+

Sent when the request process pushes a resource to the client.

switch_protocol

-

Same as the switch_protocol command.

-

Sent when switching to the HTTP/2 or Websocket protocol.

-
-
- -
+

Same as the switch_protocol command.

+

Sent when switching to the HTTP/2 or Websocket 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.

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

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

- -
+
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(), HumanReadable}
-
-Error         = atom()
-HumanReadable = atom()
-

Reason for the stream termination.

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

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

- - - -
+
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.2: The trailers command was introduced. -

    +
    • 2.2: The trailers command was introduced.
      • -
    • -

      -2.0: Module introduced. -

      +
    • 2.0: Module introduced.
      • -
-
- -
+

See also

-
-

cowboy(7), -cowboy_http(3), -cowboy_http2(3)

-
-
+

cowboy(7), cowboy_http(3), cowboy_http2(3)

+ diff --git a/docs/en/cowboy/2.4/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.4/manual/cowboy_websocket/index.html index 01b70c1c..4fd95da2 100644 --- a/docs/en/cowboy/2.4/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.4/manual/cowboy_websocket/index.html @@ -62,308 +62,148 @@

cowboy_websocket(3)

-

Name

-
-

cowboy_websocket - Websocket

-
-
-
+

cowboy_websocket - Websocket

Description

-
-

The module cowboy_websocket implements Websocket -as a Ranch protocol. It also defines a callback interface -for handling Websocket connections.

-
-
-
+

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    :: {text | binary | ping | pong, binary()}
-OutFrame   :: cow_ws:frame()                    %% see types below
-Info       :: any()
-
-CallResult :: {ok, State}
-            | {ok, State, hibernate}
-            | {reply, OutFrame | [OutFrame], State}
-            | {reply, OutFrame | [OutFrame], State, hibernate}
-            | {stop, State}
-
-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 (by returning a reply tuple) or terminate -the connection (by sending a close frame or returning a stop -tuple).

-

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

+
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    :: {text | binary | ping | pong, binary()}
+OutFrame   :: cow_ws:frame()                    %% see types below
+Info       :: any()
+
+CallResult :: {ok, State}
+            | {ok, State, hibernate}
+            | {reply, OutFrame | [OutFrame], State}
+            | {reply, OutFrame | [OutFrame], State, hibernate}
+            | {stop, State}
+
+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 (by returning a reply tuple) or terminate the connection (by sending a close frame or returning a stop tuple).

+

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
+

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

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

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

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

+
{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, 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, badframe}
+

A protocol error has been detected.

-
-{error, closed} -
-
-

- The socket has been closed brutally without a close frame being - received first. -

+
{error, closed}
+

The socket has been closed brutally without a close frame being received first.

-
-{error, Reason} -
-
-

- A socket error ocurred. -

+
{error, Reason}
+

A socket error ocurred.

-
- - -
+

Types

-
-

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.

-
-
+
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(),
-    idle_timeout => timeout(),
-    max_frame_size => non_neg_integer() | infinity,
-    req_filter => fun((cowboy_req:req()) -> map())
-}
-

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

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

-
-idle_timeout (60000) -
-
-

- Time in milliseconds that Cowboy will keep the - connection open without receiving anything from - the client. -

+
idle_timeout (60000)
+

Time in milliseconds that Cowboy will keep the connection open without receiving anything from the client.

-
-max_frame_size (infinity) -
-
-

- Maximum frame size 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. -

+
max_frame_size (infinity)
+

Maximum frame size 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. -

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

-
- - - -
+

Changelog

-
-
    -
  • -

    -2.0: The Req object is no longer passed to Websocket callbacks. -

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

      +
    • 2.0: The callback websocket_terminate/3 was removed in favor of terminate/3.
      • -
    • -

      -1.0: Protocol introduced. -

      +
    • 1.0: Protocol introduced.
      • -
-
-
-
+

See also

-
-

cowboy(7), -cowboy_handler(3), -cowboy_http(3), -cowboy_http2(3)

-
-
+

cowboy(7), cowboy_handler(3), cowboy_http(3), cowboy_http2(3)

+ diff --git a/docs/en/cowboy/2.4/manual/http_status_codes/index.html b/docs/en/cowboy/2.4/manual/http_status_codes/index.html index e6d2cc5a..0d858a45 100644 --- a/docs/en/cowboy/2.4/manual/http_status_codes/index.html +++ b/docs/en/cowboy/2.4/manual/http_status_codes/index.html @@ -62,271 +62,92 @@

HTTP status codes(7)

-

Name

-
-

HTTP status codes - status codes used by Cowboy

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

This is the status code sent when switching to the Websocket protocol.

200 OK

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

201 Created

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

202 Accepted

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

This status code is sent by cowboy_rest.

301 Moved Permanently

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

303 See Other

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

304 Not Modified

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

307 Temporary Redirect

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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

    +

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

      +
    • The request-line could not be parsed.
      • -
    • -

      -Too many headers were sent. -

      +
    • Too many headers were sent.
      • -
    • -

      -A header name was too long. -

      +
    • A header name was too long.
      • -
    • -

      -A header value was too long. -

      +
    • A header value was too long.
      • -
    • -

      -The host header was missing from an HTTP/1.1 request. -

      +
    • The host header was missing from an HTTP/1.1 request.
      • -
    • -

      -The host header could not be parsed. -

      +
    • The host header could not be parsed.
      • -
    • -

      -The requested host was not found. -

      +
    • The requested host was not found.
      • -
    • -

      -The requested path could not be parsed. -

      +
    • The requested path could not be parsed.
      • -
    • -

      -The accept header could not be parsed when using REST. -

      +
    • The accept header could not be parsed when using REST.
      • -
    • -

      -REST under normal conditions. -

      +
    • REST under normal conditions.
      • -
    • -

      -A Websocket upgrade failed. -

      +
    • A Websocket upgrade failed.
      • -
-
-
-
+

401 Unauthorized

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

403 Forbidden

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

This status code is sent by cowboy_rest.

406 Not Acceptable

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

This status code is sent by cowboy_rest.

410 Gone

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

412 Precondition Failed

-
-

This status code is sent by cowboy_rest.

-
-
-
+

This status code is sent by cowboy_rest.

413 Request Entity Too Large

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

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.

-
-
-
+

This status code is sent by cowboy_rest.

503 Service Unavailable

-
-

This status code is sent by cowboy_rest.

-
-
-
+

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

+ diff --git a/docs/en/cowboy/2.4/manual/index.html b/docs/en/cowboy/2.4/manual/index.html index 78e44814..91caacbe 100644 --- a/docs/en/cowboy/2.4/manual/index.html +++ b/docs/en/cowboy/2.4/manual/index.html @@ -62,171 +62,77 @@

Cowboy Function Reference

-

Name

-
-

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

-
-
-
+

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.

-
-
-
+

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:

-
+

Protocols:

+
-

Handlers:

-
+

Handlers:

+
-

Behaviors:

-
+

Behaviors:

+
-

Middlewares:

-
+

Middlewares:

+
-
-
-
+ +

Dependencies

-
-
    -
  • -

    -ranch(7) - Socket acceptor pool for TCP protocols -

    +
    • ranch(7) - Socket acceptor pool for TCP protocols
      • -
    • -

      -cowlib(7) - Support library for manipulating Web protocols -

      +
    • cowlib(7) - Support library for manipulating Web protocols
      • -
    • -

      -ssl - Secure communication over sockets -

      +
    • ssl - Secure communication over sockets
      • -
    • -

      -crypto - Crypto functions -

      +
    • 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).
-
-
-
+
{ok, _} = application:ensure_all_started(cowboy).
+

Environment

-
-

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

-
- -
+

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

See also

-
-

ranch(7), -cowlib(7)

-
-
+

ranch(7), cowlib(7)

+ -- cgit v1.2.3