From 8459bebceb9533948193774371cbd9fd571b78ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 16 Oct 2019 09:48:31 +0200 Subject: Cowboy 2.7.0 --- docs/en/cowboy/2.2/guide/constraints/index.html | 12 +++-- docs/en/cowboy/2.2/guide/cookies/index.html | 22 ++++---- docs/en/cowboy/2.2/guide/erlang_web/index.html | 2 + docs/en/cowboy/2.2/guide/flow_diagram/index.html | 2 + .../en/cowboy/2.2/guide/getting_started/index.html | 18 ++++--- docs/en/cowboy/2.2/guide/handlers/index.html | 10 ++-- docs/en/cowboy/2.2/guide/index.html | 2 + docs/en/cowboy/2.2/guide/introduction/index.html | 2 + docs/en/cowboy/2.2/guide/listeners/index.html | 6 ++- docs/en/cowboy/2.2/guide/loop_handlers/index.html | 10 ++-- docs/en/cowboy/2.2/guide/middlewares/index.html | 2 + .../cowboy/2.2/guide/migrating_from_1.0/index.html | 2 + .../cowboy/2.2/guide/migrating_from_2.0/index.html | 2 + .../cowboy/2.2/guide/migrating_from_2.1/index.html | 2 + .../cowboy/2.2/guide/migrating_from_2.2/index.html | 2 + docs/en/cowboy/2.2/guide/modern_web/index.html | 2 + docs/en/cowboy/2.2/guide/multipart/index.html | 14 ++--- docs/en/cowboy/2.2/guide/req/index.html | 60 +++++++++++----------- docs/en/cowboy/2.2/guide/req_body/index.html | 18 ++++--- .../en/cowboy/2.2/guide/resource_design/index.html | 2 + docs/en/cowboy/2.2/guide/resp/index.html | 38 +++++++------- .../en/cowboy/2.2/guide/rest_flowcharts/index.html | 2 + docs/en/cowboy/2.2/guide/rest_handlers/index.html | 4 +- .../en/cowboy/2.2/guide/rest_principles/index.html | 2 + docs/en/cowboy/2.2/guide/routing/index.html | 40 ++++++++------- docs/en/cowboy/2.2/guide/specs/index.html | 2 + docs/en/cowboy/2.2/guide/static_files/index.html | 22 ++++---- docs/en/cowboy/2.2/guide/streams/index.html | 2 + docs/en/cowboy/2.2/guide/ws_handlers/index.html | 26 +++++----- docs/en/cowboy/2.2/guide/ws_protocol/index.html | 2 + 30 files changed, 196 insertions(+), 136 deletions(-) (limited to 'docs/en/cowboy/2.2/guide') diff --git a/docs/en/cowboy/2.2/guide/constraints/index.html b/docs/en/cowboy/2.2/guide/constraints/index.html index 7405b833..7ab31189 100644 --- a/docs/en/cowboy/2.2/guide/constraints/index.html +++ b/docs/en/cowboy/2.2/guide/constraints/index.html @@ -71,7 +71,7 @@

Constraints for each field are provided as an ordered list of atoms or funs to apply. Built-in constraints are provided as atoms, while custom constraints are provided as funs.

When multiple constraints are provided, they are applied in the order given. If the value has been modified by a constraint then the next one receives the new value.

For example, the following constraints will first validate and convert the field my_value to an integer, and then check that the integer is positive:

-
@@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite -->

We ignore the first fun argument in this snippet. We shouldn't. We will simply learn what it is later in this chapter.

When there's only one constraint, it can be provided directly without wrapping it into a list:

-
@@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

Custom constraints

Custom constraints are specified as a fun. This fun takes two arguments. The first argument indicates the operation to be performed, and the second is the value. What the value is and what must be returned depends on the operation.

Cowboy currently defines three operations. The operation used for validating and converting user input is the forward operation.

-
@@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite -->

The value must be returned even if it is not converted by the constraint.

The reverse operation does the opposite: it takes a converted value and changes it back to what the user input would have been.

-
@@ -132,7 +132,7 @@ http://www.gnu.org/software/src-highlite --> end;

Finally, the format_error operation takes an error returned by any other operation and returns a formatted human-readable error message.

-
@@ -198,6 +198,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/cookies/index.html b/docs/en/cowboy/2.2/guide/cookies/index.html index 5c682860..96012abf 100644 --- a/docs/en/cowboy/2.2/guide/cookies/index.html +++ b/docs/en/cowboy/2.2/guide/cookies/index.html @@ -71,7 +71,7 @@

    Cookies may be sent repeatedly. This is often useful to update the expiration time and avoid losing a cookie.

    Setting cookies

    By default cookies are defined for the duration of the session:

    -
    @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite --> Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).

    They can also be set for a duration in seconds:

    -
    @@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite --> #{max_age => 3600}).

    To delete cookies, set max_age to 0:

    -
    @@ -97,7 +97,7 @@ http://www.gnu.org/software/src-highlite --> #{max_age => 0}).

    To restrict cookies to a specific domain and path, the options of the same name can be used:

    -
    @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite -->

    Cookies will be sent with requests to this domain and all its subdomains, and to resources on this path or deeper in the path hierarchy.

    To restrict cookies to secure channels (typically resources available over HTTPS):

    -
    @@ -115,7 +115,7 @@ http://www.gnu.org/software/src-highlite --> #{secure => true}).

    To prevent client-side scripts from accessing a cookie:

    -
    @@ -128,7 +128,7 @@ http://www.gnu.org/software/src-highlite -->

    The client only ever sends back the cookie name and value. All other options that can be set are never sent back.

    Cowboy provides two functions for reading cookies. Both involve parsing the cookie header(s) and so should not be called repeatedly.

    You can get all cookies as a key/value list:

    -
    @@ -136,14 +136,14 @@ http://www.gnu.org/software/src-highlite --> {_, Lang} = lists:keyfind(<<"lang">>, 1, Cookies).

    Or you can perform a match against cookies and retrieve only the ones you need, while at the same time doing any required post processing using constraints. This function returns a map:

    -
    #{id := ID, lang := Lang} = cowboy_req:match_cookies([id, lang], Req).

    You can use constraints to validate the values while matching them. The following snippet will crash if the id cookie is not an integer number or if the lang cookie is empty. Additionally the id cookie value will be converted to an integer term:

    -
    @@ -151,7 +151,7 @@ http://www.gnu.org/software/src-highlite -->

    Note that if two cookies share the same name, then the map value will be a list of the two cookie values.

    A default value can be provided. The default will be used if the lang cookie is not found. It will not be used if the cookie is found but has an empty value:

    -
    @@ -215,6 +215,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/erlang_web/index.html b/docs/en/cowboy/2.2/guide/erlang_web/index.html index ebb6174f..e928eecd 100644 --- a/docs/en/cowboy/2.2/guide/erlang_web/index.html +++ b/docs/en/cowboy/2.2/guide/erlang_web/index.html @@ -164,6 +164,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/flow_diagram/index.html b/docs/en/cowboy/2.2/guide/flow_diagram/index.html index 84505c22..4a5e732b 100644 --- a/docs/en/cowboy/2.2/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.2/guide/flow_diagram/index.html @@ -142,6 +142,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/getting_started/index.html b/docs/en/cowboy/2.2/guide/getting_started/index.html index 80d52c47..bc56e161 100644 --- a/docs/en/cowboy/2.2/guide/getting_started/index.html +++ b/docs/en/cowboy/2.2/guide/getting_started/index.html @@ -68,7 +68,7 @@

    We are going to use the Erlang.mk build system. If you are using Windows, please check the Installation instructions to get your environment setup before you continue.

    Bootstrap

    First, let's create the directory for our application.

    -
    @@ -76,21 +76,21 @@ http://www.gnu.org/software/src-highlite --> $ cd hello_erlang

    Then we need to download Erlang.mk. Either use the following command or download it manually.

    -
    $ wget https://erlang.mk/erlang.mk

    We can now bootstrap our application. Since we are going to generate a release, we will also bootstrap it at the same time.

    -
    $ make -f erlang.mk bootstrap bootstrap-rel

    This creates a Makefile, a base application, and the release files necessary for creating the release. We can already build and start this release.

    -
    @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite -->

    The release currently does nothing. In the rest of this chapter we will add Cowboy as a dependency and write a simple "Hello world!" handler.

    Cowboy setup

    We will modify the Makefile to tell the build system it needs to fetch and compile Cowboy:

    -
    @@ -120,7 +120,7 @@ include erlang.mk

    Listening for connections

    First we define the routes that Cowboy will use to map requests to handler modules, and then we start the listener. This is best done at application startup.

    Open the src/hello_erlang_app.erl file and add the necessary code to the start/2 function to make it look like this:

    -
    @@ -139,14 +139,14 @@ http://www.gnu.org/software/src-highlite -->

    Handling requests

    Cowboy features different kinds of handlers, including REST and Websocket handlers. For this tutorial we will use a plain HTTP handler.

    Generate a handler from a template:

    -
    $ make new t=cowboy.http n=hello_handler

    Then, open the src/hello_handler.erl file and modify the init/2 function like this to send a reply.

    -
    @@ -216,6 +216,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/handlers/index.html b/docs/en/cowboy/2.2/guide/handlers/index.html index 3afcf92a..2f55cdba 100644 --- a/docs/en/cowboy/2.2/guide/handlers/index.html +++ b/docs/en/cowboy/2.2/guide/handlers/index.html @@ -67,7 +67,7 @@

    The most basic handler in Cowboy implements the mandatory init/2 callback, manipulates the request, optionally sends a response and then returns.

    This callback receives the Req object and the initial state defined in the router configuration.

    A handler that does nothing would look like this:

    -
    @@ -76,7 +76,7 @@ http://www.gnu.org/software/src-highlite -->

    Despite sending no reply, a 204 No Content response will be sent to the client, as Cowboy makes sure that a response is sent for every request.

    We need to use the Req object to reply.

    -
    @@ -93,7 +93,7 @@ http://www.gnu.org/software/src-highlite -->

    The init/2 callback can also be used to inform Cowboy that this is a different kind of handler and that Cowboy should switch to it. To do this you simply need to return the module name of the handler type you want to switch to.

    Cowboy comes with three handler types you can switch to: cowboy_rest, cowboy_websocket and cowboy_loop. In addition to those you can define your own handler types.

    Switching is simple. Instead of returning ok, you simply return the name of the handler type you want to use. The following snippet switches to a Websocket handler:

    -
    @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite -->

    Cleaning up

    All handler types provide the optional terminate/3 callback.

    -
    @@ -169,6 +169,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/index.html b/docs/en/cowboy/2.2/guide/index.html index 8e9e8dff..0e08e239 100644 --- a/docs/en/cowboy/2.2/guide/index.html +++ b/docs/en/cowboy/2.2/guide/index.html @@ -175,6 +175,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/introduction/index.html b/docs/en/cowboy/2.2/guide/introduction/index.html index 82ac9f36..0cc465bf 100644 --- a/docs/en/cowboy/2.2/guide/introduction/index.html +++ b/docs/en/cowboy/2.2/guide/introduction/index.html @@ -152,6 +152,8 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
    +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/listeners/index.html b/docs/en/cowboy/2.2/guide/listeners/index.html index c445ce06..999848d3 100644 --- a/docs/en/cowboy/2.2/guide/listeners/index.html +++ b/docs/en/cowboy/2.2/guide/listeners/index.html @@ -68,7 +68,7 @@

    Clear TCP listener

    The clear TCP listener will accept connections on the given port. A typical HTTP server would listen on port 80. Port 80 requires special permissions on most platforms however so a common alternative is port 8080.

    The following snippet starts listening for connections on port 8080:

    -
    @@ -90,7 +90,7 @@ http://www.gnu.org/software/src-highlite -->

    The secure TLS listener will accept connections on the given port. A typical HTTPS server would listen on port 443. Port 443 requires special permissions on most platforms however so a common alternative is port 8443.

    The function provided by Cowboy will ensure that the TLS options given are following the HTTP/2 RFC with regards to security. For example some TLS extensions or ciphers may be disabled. This also applies to HTTP/1.1 connections on this listener. If this is not desirable, Ranch can be used directly to setup a custom listener.

    -
    @@ -173,6 +173,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/loop_handlers/index.html b/docs/en/cowboy/2.2/guide/loop_handlers/index.html index 282581a3..ff5d3ae7 100644 --- a/docs/en/cowboy/2.2/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/loop_handlers/index.html @@ -70,7 +70,7 @@

    Initialization

    The init/2 function must return a cowboy_loop tuple to enable loop handler behavior. This tuple may optionally contain a timeout value and/or the atom hibernate to make the process enter hibernation until a message is received.

    This snippet enables the loop handler:

    -
    @@ -78,7 +78,7 @@ http://www.gnu.org/software/src-highlite --> {cowboy_loop, Req, State}.

    This also makes the process hibernate:

    -
    @@ -88,7 +88,7 @@ http://www.gnu.org/software/src-highlite -->

    Receive loop

    Once initialized, Cowboy will wait for messages to arrive in the process' mailbox. When a message arrives, Cowboy calls the info/3 function with the message, the Req object and the handler's state.

    The following snippet sends a reply when it receives a reply message from another process, or waits for another message otherwise.

    -
    @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite -->

    Streaming loop

    Another common case well suited for loop handlers is streaming data received in the form of Erlang messages. This can be done by initiating a chunked reply in the init/2 callback and then using cowboy_req:chunk/2 every time a message is received.

    The following snippet does exactly that. As you can see a chunk is sent every time an event message is received, and the loop is stopped by sending an eof message.

    -
    @@ -184,6 +184,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/middlewares/index.html b/docs/en/cowboy/2.2/guide/middlewares/index.html index ee0edc31..129ac341 100644 --- a/docs/en/cowboy/2.2/guide/middlewares/index.html +++ b/docs/en/cowboy/2.2/guide/middlewares/index.html @@ -150,6 +150,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html b/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html index 1228810c..e8a2c1d9 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_1.0/index.html @@ -232,6 +232,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html index dae82463..5639f80e 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.0/index.html @@ -167,6 +167,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html index 62d00ae8..1d10126e 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.1/index.html @@ -178,6 +178,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html b/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html index 18949119..02b6078a 100644 --- a/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html +++ b/docs/en/cowboy/2.2/guide/migrating_from_2.2/index.html @@ -132,6 +132,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/modern_web/index.html b/docs/en/cowboy/2.2/guide/modern_web/index.html index fd461288..dd71b961 100644 --- a/docs/en/cowboy/2.2/guide/modern_web/index.html +++ b/docs/en/cowboy/2.2/guide/modern_web/index.html @@ -146,6 +146,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/multipart/index.html b/docs/en/cowboy/2.2/guide/multipart/index.html index 1e38b817..816b76b3 100644 --- a/docs/en/cowboy/2.2/guide/multipart/index.html +++ b/docs/en/cowboy/2.2/guide/multipart/index.html @@ -73,7 +73,7 @@

    The browser does its best to determine the media type of the files it sends this way, but you should not rely on it for determining the contents of the file. Proper investigation of the contents is recommended.

    Checking for multipart messages

    The content-type header indicates the presence of a multipart message:

    -
    @@ -85,7 +85,7 @@ http://www.gnu.org/software/src-highlite -->

    The cowboy_req:read_part/1,2 functions return the next part's headers, if any.

    The cowboy_req:read_part_body/1,2 functions return the current part's body. For large bodies you may need to call the function multiple times.

    To read a multipart message you need to iterate over all its parts:

    -
    @@ -101,7 +101,7 @@ http://www.gnu.org/software/src-highlite -->

    When part bodies are too large, Cowboy will return a more tuple, and allow you to loop until the part body has been fully read.

    The function cow_multipart:form_data/1 can be used to quickly obtain information about a part from a multipart/form-data message. The function returns a data or a file tuple depending on whether this is a normal field or a file being uploaded.

    The following snippet will use this function and use different strategies depending on whether the part is a file:

    -
    @@ -130,14 +130,14 @@ http://www.gnu.org/software/src-highlite -->

    Both the part header and body reading functions can take options that will be given to the request body reading functions. By default, cowboy_req:read_part/1 reads up to 64KB for up to 5 seconds. cowboy_req:read_part_body/1 has the same defaults as cowboy_req:read_body/1.

    To change the defaults for part headers:

    -
    cowboy_req:read_part(Req, #{length => 128000}).

    And for part bodies:

    -
    @@ -146,7 +146,7 @@ http://www.gnu.org/software/src-highlite -->

    Skipping unwanted parts

    Part bodies do not have to be read. Cowboy will automatically skip it when you request the next part's body.

    The following snippet reads all part headers and skips all bodies:

    -
    @@ -219,6 +219,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/req/index.html b/docs/en/cowboy/2.2/guide/req/index.html index 5f466e5b..f4974e90 100644 --- a/docs/en/cowboy/2.2/guide/req/index.html +++ b/docs/en/cowboy/2.2/guide/req/index.html @@ -69,7 +69,7 @@

    The Req map contains a number of fields which are documented and can be accessed directly. They are the fields that have a direct mapping to HTTP: the request method; the HTTP version used; the effective URI components scheme, host, port, path and qs; the request headers; and the connection peer address and port.

    Note that the version field can be used to determine whether a connection is using HTTP/2.

    To access a field, you can simply match in the function head. The following example sends a simple "Hello world!" response when the method is GET, and a 405 error otherwise.

    -
    @@ -96,14 +96,14 @@ http://www.gnu.org/software/src-highlite -->

    All functions will crash if something goes wrong. There is usually no need to catch these errors, Cowboy will send the appropriate 4xx or 5xx response depending on where the crash occurred.

    Request method

    The request method can be retrieved directly:

    -
    #{method := Method} = Req.

    Or using a function:

    -
    @@ -115,14 +115,14 @@ http://www.gnu.org/software/src-highlite -->

    There is typically no need to change behavior based on the HTTP version: Cowboy already does it for you.

    It can be useful in some cases, though. For example, one may want to redirect HTTP/1.1 clients to use Websocket, while HTTP/2 clients keep using HTTP/2.

    The HTTP version can be retrieved directly:

    -
    #{version := Version} = Req.

    Or using a function:

    -
    @@ -131,7 +131,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy defines the 'HTTP/1.0', 'HTTP/1.1' and 'HTTP/2' versions. Custom protocols can define their own values as atoms.

    Effective request URI

    The scheme, host, port, path and query string components of the effective request URI can all be retrieved directly:

    -
    @@ -144,7 +144,7 @@ http://www.gnu.org/software/src-highlite --> } = Req.

    Or using the related functions:

    -
    @@ -158,7 +158,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy defines only the <<"http">> and <<"https">> schemes. They are chosen so that the scheme will only be <<"https">> for requests on secure HTTP/1.1 or HTTP/2 connections.

    The effective request URI itself can be reconstructed with the cowboy_req:uri/1,2 function. By default, an absolute URI is returned:

    -
    @@ -166,7 +166,7 @@ http://www.gnu.org/software/src-highlite --> URI = cowboy_req:uri(Req).

    Options are available to either disable or replace some or all of the components. Various URIs or URI formats can be generated this way, including the origin form:

    -
    @@ -174,7 +174,7 @@ http://www.gnu.org/software/src-highlite --> URI = cowboy_req:uri(Req, #{host => undefined}).

    The protocol relative form:

    -
    @@ -182,14 +182,14 @@ http://www.gnu.org/software/src-highlite --> URI = cowboy_req:uri(Req, #{scheme => undefined}).

    The absolute URI without a query string:

    -
    URI = cowboy_req:uri(Req, #{qs => undefined}).

    A different host:

    -
    @@ -200,21 +200,21 @@ http://www.gnu.org/software/src-highlite -->

    Bindings are the host and path components that you chose to extract when defining the routes of your application. They are only available after the routing.

    Cowboy provides functions to retrieve one or all bindings.

    To retrieve a single value:

    -
    Value = cowboy_req:binding(userid, Req).

    When attempting to retrieve a value that was not bound, undefined will be returned. A different default value can be provided:

    -
    Value = cowboy_req:binding(userid, Req, 42).

    To retrieve everything that was bound:

    -
    @@ -223,14 +223,14 @@ http://www.gnu.org/software/src-highlite -->

    They are returned as a map, with keys being atoms.

    The Cowboy router also allows you to capture many host or path segments at once using the ... qualifier.

    To retrieve the segments captured from the host name:

    -
    HostInfo = cowboy_req:host_info(Req).

    And the path segments:

    -
    @@ -239,7 +239,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy will return undefined if ... was not used in the route.

    Query parameters

    Cowboy provides two functions to access query parameters. You can use the first to get the entire list of parameters.

    -
    @@ -251,21 +251,21 @@ http://www.gnu.org/software/src-highlite -->

    The same is true when trying to use the PHP-style suffix []. When a query string is key[]=1&key[]=2, the list returned will contain two parameters of name key[].

    When a query string is simply key, Cowboy will return the list [{<<"key">>, true}], using true to indicate that the parameter key was defined, but with no value.

    The second function Cowboy provides allows you to match out only the parameters you are interested in, and at the same time do any post processing you require using constraints. This function returns a map.

    -
    #{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req).

    Constraints can be applied automatically. The following snippet will crash when the id parameter is not an integer, or when the lang parameter is empty. At the same time, the value for id will be converted to an integer term:

    -
    QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).

    A default value may also be provided. The default will be used if the lang key is not found. It will not be used if the key is found but has an empty value.

    -
    @@ -276,7 +276,7 @@ http://www.gnu.org/software/src-highlite -->

    Headers

    Header values can be retrieved either as a binary string or parsed into a more meaningful representation.

    The get the raw value:

    -
    @@ -284,21 +284,21 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy expects all header names to be provided as lowercase binary strings. This is true for both requests and responses, regardless of the underlying protocol.

    When the header is missing from the request, undefined will be returned. A different default can be provided:

    -
    HeaderVal = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>).

    All headers can be retrieved at once, either directly:

    -
    #{headers := AllHeaders} = Req.

    Or using a function:

    -
    @@ -306,7 +306,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy provides equivalent functions to parse individual headers. There is no function to parse all headers at once.

    To parse a specific header:

    -
    @@ -314,7 +314,7 @@ http://www.gnu.org/software/src-highlite -->

    An exception will be thrown if it doesn't know how to parse the given header, or if the value is invalid. The list of known headers and default values can be found in the manual.

    When the header is missing, undefined is returned. You can change the default value. Note that it should be the parsed value directly:

    -
    @@ -324,14 +324,14 @@ http://www.gnu.org/software/src-highlite -->

    Peer

    The peer address and port number for the connection can be retrieved either directly or using a function.

    To retrieve the peer directly:

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

    And using a function:

    -
    @@ -395,6 +395,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/req_body/index.html b/docs/en/cowboy/2.2/guide/req_body/index.html index d6677edb..22bb3fb5 100644 --- a/docs/en/cowboy/2.2/guide/req_body/index.html +++ b/docs/en/cowboy/2.2/guide/req_body/index.html @@ -69,7 +69,7 @@

    Cowboy provides functions for reading the body raw, and read and parse form urlencoded or multipart bodies. The latter is covered in its own chapter.

    Request body presence

    Not all requests come with a body. You can check for the presence of a request body with this function:

    -
    @@ -79,7 +79,7 @@ http://www.gnu.org/software/src-highlite -->

    In practice, this function is rarely used. When the method is POST, PUT or PATCH, the request body is often required by the application, which should just attempt to read it directly.

    Request body length

    You can obtain the length of the body:

    -
    @@ -89,7 +89,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy will update the body length in the Req object once the body has been read completely. A length will always be returned when attempting to call this function after reading the body completely.

    Reading the body

    You can read the entire body with one function call:

    -
    @@ -98,7 +98,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy returns an ok tuple when the body has been read fully.

    By default, Cowboy will attempt to read up to 8MB of data, for up to 15 seconds. The call will return once Cowboy has read at least 8MB of data, or at the end of the 15 seconds period.

    These values can be customized. For example, to read only up to 1MB for up to 5 seconds:

    -
    @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite --> #{length => 1000000, period => 5000}).

    You may also disable the length limit:

    -
    @@ -116,7 +116,7 @@ http://www.gnu.org/software/src-highlite -->

    These two options can effectively be used to control the rate of transmission of the request body.

    Streaming the body

    When the body is too large, the first call will return a more tuple instead of ok. You can call the function again to read more of the body, reading it one chunk at a time.

    -
    @@ -133,7 +133,7 @@ http://www.gnu.org/software/src-highlite -->

    The length and period options can also be used. They need to be passed for every call.

    Reading a form urlencoded body

    Cowboy provides a convenient function for reading and parsing bodies sent as application/x-www-form-urlencoded.

    -
    @@ -141,7 +141,7 @@ http://www.gnu.org/software/src-highlite -->

    This function returns a list of key/values, exactly like the function cowboy_req:parse_qs/1.

    The defaults for this function are different. Cowboy will read for up to 64KB and up to 5 seconds. They can be modified:

    -
    @@ -205,6 +205,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/resource_design/index.html b/docs/en/cowboy/2.2/guide/resource_design/index.html index 01447fb5..b93da6e0 100644 --- a/docs/en/cowboy/2.2/guide/resource_design/index.html +++ b/docs/en/cowboy/2.2/guide/resource_design/index.html @@ -178,6 +178,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/resp/index.html b/docs/en/cowboy/2.2/guide/resp/index.html index 2ad38c40..b25fe3a1 100644 --- a/docs/en/cowboy/2.2/guide/resp/index.html +++ b/docs/en/cowboy/2.2/guide/resp/index.html @@ -69,14 +69,14 @@

    Reply

    Cowboy provides three functions for sending the entire reply, depending on whether you need to set headers and body. In all cases, Cowboy will add any headers required by the protocol (for example the date header will always be sent).

    When you need to set only the status code, use cowboy_req:reply/2:

    -
    Req = cowboy_req:reply(200, Req0).

    When you need to set response headers at the same time, use cowboy_req:reply/3:

    -
    @@ -86,7 +86,7 @@ http://www.gnu.org/software/src-highlite -->

    Note that the header name must always be a lowercase binary.

    When you also need to set the response body, use cowboy_req:reply/4:

    -
    @@ -96,7 +96,7 @@ http://www.gnu.org/software/src-highlite -->

    You should always set the content-type header when the response has a body. There is however no need to set the content-length header; Cowboy does it automatically.

    The response body and the header values must be either a binary or an iolist. An iolist is a list containing binaries, characters, strings or other iolists. This allows you to build a response from different parts without having to do any concatenation:

    -
    @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy provides two functions for initiating a response, and an additional function for streaming the response body. Cowboy will add any required headers to the response.

    When you need to set only the status code, use cowboy_req:stream_reply/2:

    -
    @@ -124,7 +124,7 @@ http://www.gnu.org/software/src-highlite -->

    The second argument to cowboy_req:stream_body/3 indicates whether this data terminates the body. Use fin for the final flag, and nofin otherwise.

    This snippet does not set a content-type header. This is not recommended. All responses with a body should have a content-type. The header can be set beforehand, or using the cowboy_req:stream_reply/3:

    -
    @@ -139,7 +139,7 @@ http://www.gnu.org/software/src-highlite -->

    While not required by any means, it is recommended that you set the content-length header in the response if you know it in advance. This will ensure that the best response method is selected and help clients understand when the response is fully received.

    Cowboy also provides a function to send response trailers. Response trailers are semantically equivalent to the headers you send in the response, only they are sent at the end. This is especially useful to attach information to the response that could not be generated until the response body was fully generated.

    Trailer fields must be listed in the trailer header. Any field not listed might be dropped by the client or an intermediary.

    -
    @@ -160,7 +160,7 @@ http://www.gnu.org/software/src-highlite -->

    Preset response headers

    Cowboy provides functions to set response headers without immediately sending them. They are stored in the Req object and sent as part of the response when a reply function is called.

    To set response headers:

    -
    @@ -169,7 +169,7 @@ http://www.gnu.org/software/src-highlite -->

    Header names must be a lowercase binary.

    Do not use this function for setting cookies. Refer to the Cookies chapter for more information.

    To check if a response header has already been set:

    -
    @@ -177,7 +177,7 @@ http://www.gnu.org/software/src-highlite -->

    It returns true if the header was set, false otherwise.

    To delete a response header that was set previously:

    -
    @@ -202,7 +202,7 @@ http://www.gnu.org/software/src-highlite -->

    Headers given to the reply function will always override preset headers and required headers. If a header is found in two or three of these, then the one in the reply function is picked and the others are dropped.

    Similarly, preset headers will always override required headers.

    To illustrate, look at the following snippet. Cowboy by default sends the server header with the value "Cowboy". We can override it:

    -
    @@ -213,7 +213,7 @@ http://www.gnu.org/software/src-highlite -->

    Preset response body

    Cowboy provides functions to set the response body without immediately sending it. It is stored in the Req object and sent when the reply function is called.

    To set the response body:

    -
    @@ -222,7 +222,7 @@ http://www.gnu.org/software/src-highlite -->

    To check if a response body has already been set:

    -
    @@ -235,7 +235,7 @@ http://www.gnu.org/software/src-highlite -->

    The preset response body is only sent if the reply function used is cowboy_req:reply/2 or cowboy_req:reply/3.

    Sending files

    Cowboy provides a shortcut for sending files. When using cowboy_req:reply/4, or when presetting the response header, you can give a sendfile tuple to Cowboy:

    -
    @@ -244,7 +244,7 @@ http://www.gnu.org/software/src-highlite -->

    Depending on the values for Offset or Length, the entire file may be sent, or just a part of it.

    The length is required even for sending the entire file. Cowboy sends it in the content-length header.

    To send a file while replying:

    -
    @@ -265,7 +265,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy allows you to send informational responses.

    Informational responses are responses that have a status code between 100 and 199. Any number can be sent before the proper response. Sending an informational response does not change the behavior of the proper response, and clients are expected to ignore any informational response they do not understand.

    The following snippet sends a 103 informational response with some headers that are expected to be in the final response.

    -
    @@ -281,7 +281,7 @@ http://www.gnu.org/software/src-highlite -->

    To push a resource, you need to provide the same information as a client performing a request would. This includes the HTTP method, the URI and any necessary request headers.

    Cowboy by default only requires you to give the path to the resource and the request headers. The rest of the URI is taken from the current request (excluding the query string, set to empty) and the method is GET by default.

    The following snippet pushes a CSS file that is linked to in the response:

    -
    @@ -295,7 +295,7 @@ http://www.gnu.org/software/src-highlite --> "<body><p>Welcome to Erlang!</p></body></html>"], Req0).

    To override the method, scheme, host, port or query string, simply pass in a fourth argument. The following snippet uses a different host name:

    -
    @@ -362,6 +362,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html b/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html index 0496db5f..e8ddb8a1 100644 --- a/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html +++ b/docs/en/cowboy/2.2/guide/rest_flowcharts/index.html @@ -176,6 +176,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/rest_handlers/index.html b/docs/en/cowboy/2.2/guide/rest_handlers/index.html index 4c83fc1c..c3e3dbab 100644 --- a/docs/en/cowboy/2.2/guide/rest_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/rest_handlers/index.html @@ -66,7 +66,7 @@

    The REST handler is the recommended way to handle HTTP requests.

    Initialization

    First, the init/2 callback is called. This callback is common to all handlers. To use REST for the current request, this function must return a cowboy_rest tuple.

    -
    @@ -274,6 +274,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/rest_principles/index.html b/docs/en/cowboy/2.2/guide/rest_principles/index.html index 34ec3366..4f769edf 100644 --- a/docs/en/cowboy/2.2/guide/rest_principles/index.html +++ b/docs/en/cowboy/2.2/guide/rest_principles/index.html @@ -150,6 +150,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/routing/index.html b/docs/en/cowboy/2.2/guide/routing/index.html index b0b06a50..18229ec4 100644 --- a/docs/en/cowboy/2.2/guide/routing/index.html +++ b/docs/en/cowboy/2.2/guide/routing/index.html @@ -68,14 +68,14 @@

    Routes need to be compiled before they can be used by Cowboy. The result of the compilation is the dispatch rules.

    Syntax

    The general structure for the routes is defined as follow.

    -
    Routes = [Host1, Host2, ... HostN].

    Each host contains matching rules for the host along with optional constraints, and a list of routes for the path component.

    -
    @@ -83,14 +83,14 @@ http://www.gnu.org/software/src-highlite --> Host2 = {HostMatch, Constraints, PathsList}.

    The list of routes for the path component is defined similar to the list of hosts.

    -
    PathsList = [Path1, Path2, ... PathN].

    Finally, each path contains matching rules for the path along with optional constraints, and gives us the handler module to be used along with its initial state.

    -
    @@ -102,7 +102,7 @@ http://www.gnu.org/software/src-highlite -->

    The match syntax is used to associate host names and paths with their respective handlers.

    The match syntax is the same for host and path with a few subtleties. Indeed, the segments separator is different, and the host is matched starting from the last segment going to the first. All examples will feature both host and path match rules and explain the differences when encountered.

    Excluding special values that we will explain at the end of this section, the simplest match value is a host or a path. It can be given as either a string() or a binary().

    -
    @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite --> HostMatch1 = "cowboy.example.org".

    As you can see, all paths defined this way must start with a slash character. Note that these two paths are identical as far as routing is concerned.

    -
    @@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> PathMatch3 = "/path/to/resource/".

    Hosts with and without a trailing dot are equivalent for routing. Similarly, hosts with and without a leading dot are also equivalent.

    -
    @@ -130,7 +130,7 @@ http://www.gnu.org/software/src-highlite -->

    It is possible to extract segments of the host and path and to store the values in the Req object for later use. We call these kind of values bindings.

    The syntax for bindings is very simple. A segment that begins with the : character means that what follows until the end of the segment is the name of the binding in which the segment value will be stored.

    -
    @@ -139,14 +139,14 @@ http://www.gnu.org/software/src-highlite -->

    If these two end up matching when routing, you will end up with two bindings defined, subdomain and name, each containing the segment value where they were defined. For example, the URL http://test.example.org/hats/wild_cowboy_legendary/prices will result in having the value test bound to the name subdomain and the value wild_cowboy_legendary bound to the name name. They can later be retrieved using cowboy_req:binding/{2,3}. The binding name must be given as an atom.

    There is a special binding name you can use to mimic the underscore variable in Erlang. Any match against the _ binding will succeed but the data will be discarded. This is especially useful for matching against many domain names in one go.

    -
    HostMatch = "ninenines.:_".

    Similarly, it is possible to have optional segments. Anything between brackets is optional.

    -
    @@ -154,14 +154,14 @@ http://www.gnu.org/software/src-highlite --> HostMatch = "[www.]ninenines.eu".

    You can also have imbricated optional segments.

    -
    PathMatch = "/hats/[page/[:number]]".

    You can retrieve the rest of the host or path using [...]. In the case of hosts it will match anything before, in the case of paths anything after the previously matched segments. It is a special case of optional segments, in that it can have zero, one or many segments. You can then find the segments using cowboy_req:host_info/1 and cowboy_req:path_info/1 respectively. They will be represented as a list of segments.

    -
    @@ -169,21 +169,21 @@ http://www.gnu.org/software/src-highlite --> HostMatch = "[...]ninenines.eu".

    If a binding appears twice in the routing rules, then the match will succeed only if they share the same value. This copies the Erlang pattern matching behavior.

    -
    PathMatch = "/hats/:name/:name".

    This is also true when an optional segment is present. In this case the two values must be identical only if the segment is available.

    -
    PathMatch = "/hats/:name/[:name]".

    If a binding is defined in both the host and path, then they must also share the same value.

    -
    @@ -191,7 +191,7 @@ http://www.gnu.org/software/src-highlite --> HostMatch = ":user.github.com".

    Finally, there are two special match values that can be used. The first is the atom '_' which will match any host or path.

    -
    @@ -199,7 +199,7 @@ http://www.gnu.org/software/src-highlite --> HostMatch = '_'.

    The second is the special host match "*" which will match the wildcard path, generally used alongside the OPTIONS method.

    -
    @@ -212,7 +212,7 @@ http://www.gnu.org/software/src-highlite -->

    Compilation

    The routes must be compiled before Cowboy can use them. The compilation step normalizes the routes to simplify the code and speed up the execution, but the routes are still looked up one by one in the end. Faster compilation strategies could be to compile the routes directly to Erlang code, but would require heavier dependencies.

    To compile routes, just call the appropriate function:

    -
    @@ -228,7 +228,7 @@ http://www.gnu.org/software/src-highlite -->

    Live update

    You can use the cowboy:set_env/3 function for updating the dispatch list used by routing. This will apply to all new connections accepted by the listener:

    -
    @@ -293,6 +293,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/specs/index.html b/docs/en/cowboy/2.2/guide/specs/index.html index 8fedf01b..9bd4a261 100644 --- a/docs/en/cowboy/2.2/guide/specs/index.html +++ b/docs/en/cowboy/2.2/guide/specs/index.html @@ -447,6 +447,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/static_files/index.html b/docs/en/cowboy/2.2/guide/static_files/index.html index c4c80cd7..e6ef0b75 100644 --- a/docs/en/cowboy/2.2/guide/static_files/index.html +++ b/docs/en/cowboy/2.2/guide/static_files/index.html @@ -68,14 +68,14 @@

    Serve one file

    You can use the static handler to serve one specific file from an application's private directory. This is particularly useful to serve an index.html file when the client requests the / path, for example. The path configured is relative to the given application's private directory.

    The following rule will serve the file static/index.html from the application my_app's priv directory whenever the path / is accessed:

    -
    {"/", cowboy_static, {priv_file, my_app, "static/index.html"}}

    You can also specify the absolute path to a file, or the path to the file relative to the current directory:

    -
    @@ -85,14 +85,14 @@ http://www.gnu.org/software/src-highlite -->

    You can also use the static handler to serve all files that can be found in the configured directory. The handler will use the path_info information to resolve the file location, which means that your route must end with a [...] pattern for it to work. All files are served, including the ones that may be found in subfolders.

    You can specify the directory relative to an application's private directory.

    The following rule will serve any file found in the application my_app's priv directory inside the static/assets folder whenever the requested path begins with /assets/:

    -
    {"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets"}}

    You can also specify the absolute path to the directory or set it relative to the current directory:

    -
    @@ -103,7 +103,7 @@ http://www.gnu.org/software/src-highlite -->

    You can override the function that figures out the mimetype of the static files. It can be useful when Cowboy is missing a mimetype you need to handle, or when you want to reduce the list to make lookups faster. You can also give a hard-coded mimetype that will be used unconditionally.

    Cowboy comes with two functions built-in. The default function only handles common file types used when building Web applications. The other function is an extensive list of hundreds of mimetypes that should cover almost any need you may have. You can of course create your own function.

    To use the default function, you should not have to configure anything, as it is the default. If you insist, though, the following will do the job:

    -
    @@ -112,7 +112,7 @@ http://www.gnu.org/software/src-highlite -->

    As you can see, there is an optional field that may contain a list of less used options, like mimetypes or etag. All option types have this optional field.

    To use the function that will detect almost any mimetype, the following configuration will do:

    -
    @@ -120,7 +120,7 @@ http://www.gnu.org/software/src-highlite --> [{mimetypes, cow_mimetypes, all}]}}

    You probably noticed the pattern by now. The configuration expects a module and a function name, so you can use any of your own functions instead:

    -
    @@ -130,7 +130,7 @@ http://www.gnu.org/software/src-highlite -->

    The function that performs the mimetype detection receives a single argument that is the path to the file on disk. It is recommended to return the mimetype in tuple form, although a binary string is also allowed (but will require extra processing). If the function can't figure out the mimetype, then it should return {<<"application">>, <<"octet-stream">>, []}.

    When the static handler fails to find the extension, it will send the file as application/octet-stream. A browser receiving such file will attempt to download it directly to disk.

    Finally, the mimetype can be hard-coded for all files. This is especially useful in combination with the file and priv_file options as it avoids needless computation:

    -
    @@ -140,7 +140,7 @@ http://www.gnu.org/software/src-highlite -->

    Generate an etag

    By default, the static handler will generate an etag header value based on the size and modified time. This solution can not be applied to all systems though. It would perform rather poorly over a cluster of nodes, for example, as the file metadata will vary from server to server, giving a different etag on each server.

    You can however change the way the etag is calculated:

    -
    @@ -149,7 +149,7 @@ http://www.gnu.org/software/src-highlite -->

    This function will receive three arguments: the path to the file on disk, the size of the file and the last modification time. In a distributed setup, you would typically use the file path to retrieve an etag value that is identical across all your servers.

    You can also completely disable etag handling:

    -
    @@ -213,6 +213,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/streams/index.html b/docs/en/cowboy/2.2/guide/streams/index.html index 652210af..d1d96c34 100644 --- a/docs/en/cowboy/2.2/guide/streams/index.html +++ b/docs/en/cowboy/2.2/guide/streams/index.html @@ -135,6 +135,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/ws_handlers/index.html b/docs/en/cowboy/2.2/guide/ws_handlers/index.html index 6a40521e..f60eedce 100644 --- a/docs/en/cowboy/2.2/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.2/guide/ws_handlers/index.html @@ -66,7 +66,7 @@

    As Websocket connections are established through the HTTP/1.1 upgrade mechanism, Websocket handlers need to be able to first receive the HTTP request for the upgrade, before switching to Websocket and taking over the connection. They can then receive or send Websocket frames, handle incoming Erlang messages or close the connection.

    Upgrade

    The init/2 callback is called when the request is received. To establish a Websocket connection, you must switch to the cowboy_websocket module:

    -
    @@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

    If the server only understands MQTT it can return:

    sec-websocket-protocol: mqtt

    This selection must be done in init/2. An example usage could be:

    -
    @@ -106,7 +106,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy has separate processes for handling the connection and requests. Because Websocket takes over the connection, the Websocket protocol handling occurs in a different process than the request handling.

    This is reflected in the different callbacks Websocket handlers have. The init/2 callback is called from the temporary request process and the websocket_ callbacks from the connection process.

    This means that some initialization cannot be done from init/2. Anything that would require the current pid, or be tied to the current pid, will not work as intended. The optional websocket_init/1 can be used instead:

    -
    @@ -115,7 +115,7 @@ http://www.gnu.org/software/src-highlite --> {ok, State}.

    All Websocket callbacks share the same return values. This means that we can send frames to the client right after the upgrade:

    -
    @@ -126,7 +126,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy will call websocket_handle/2 whenever a text, binary, ping or pong frame arrives from the client.

    The handler can handle or ignore the frames. It can also send frames back to the client or stop the connection.

    The following snippet echoes back any text frame received and ignores all others:

    -
    @@ -140,7 +140,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy will call websocket_info/2 whenever an Erlang message arrives.

    The handler can handle or ignore the messages. It can also send frames to the client or stop the connection.

    The following snippet forwards log messages to the client and ignores all others:

    -
    @@ -155,7 +155,7 @@ http://www.gnu.org/software/src-highlite -->

    All websocket_ callbacks share return values. They may send zero, one or many frames to the client.

    To send nothing, just return an ok tuple:

    -
    @@ -163,7 +163,7 @@ http://www.gnu.org/software/src-highlite --> {ok, State}.

    To send one frame, return a reply tuple with the frame to send:

    -
    @@ -172,7 +172,7 @@ http://www.gnu.org/software/src-highlite -->

    You can send frames of any type: text, binary, ping, pong or close frames.

    To send many frames at once, return a reply tuple with the list of frames to send:

    -
    @@ -189,7 +189,7 @@ http://www.gnu.org/software/src-highlite -->

    Cowboy does not send ping frames itself. The handler can do it if required. A better solution in most cases is to let the client handle pings. Doing it from the handler would imply having an additional timer per connection and this can be a considerable cost for servers that need to handle large numbers of connections.

    Cowboy can be configured to close idle connections automatically. It is highly recommended to configure a timeout here, to avoid having processes linger longer than needed.

    The init/2 callback can set the timeout to be used for the connection. For example, this would make Cowboy close connections idle for more than 30 seconds:

    -
    @@ -201,7 +201,7 @@ http://www.gnu.org/software/src-highlite -->

    Saving memory

    The Websocket connection process can be set to hibernate after the callback returns.

    Simply add an hibernate field to the ok or reply tuples:

    -
    @@ -218,7 +218,7 @@ http://www.gnu.org/software/src-highlite -->

    Closing the connection

    The connection can be closed at any time, either by telling Cowboy to stop it or by sending a close frame.

    To tell Cowboy to close the connection, use a stop tuple:

    -
    @@ -283,6 +283,8 @@ http://www.gnu.org/software/src-highlite --> +
  • 2.7
    • +
  • 2.6
  • 2.5
    • diff --git a/docs/en/cowboy/2.2/guide/ws_protocol/index.html b/docs/en/cowboy/2.2/guide/ws_protocol/index.html index 3f77bc47..ae657e6e 100644 --- a/docs/en/cowboy/2.2/guide/ws_protocol/index.html +++ b/docs/en/cowboy/2.2/guide/ws_protocol/index.html @@ -134,6 +134,8 @@ +
  • 2.7
    • +
  • 2.6
  • 2.5
    • -- cgit v1.2.3