From 489533603eb88a427df579039475ffd08b176e40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Fri, 23 Dec 2016 18:59:45 +0100 Subject: Update docs --- docs/en/cowboy/2.0/manual/cowboy_app/index.html | 11 +- .../en/cowboy/2.0/manual/cowboy_handler/index.html | 8 +- docs/en/cowboy/2.0/manual/cowboy_loop/index.html | 181 +++++++++------------ .../cowboy/2.0/manual/cowboy_middleware/index.html | 115 +++++++------ .../cowboy/2.0/manual/cowboy_websocket/index.html | 1 + 5 files changed, 154 insertions(+), 162 deletions(-) (limited to 'docs/en/cowboy') diff --git a/docs/en/cowboy/2.0/manual/cowboy_app/index.html b/docs/en/cowboy/2.0/manual/cowboy_app/index.html index eeaa33e3..6eb67fce 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_app/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_app/index.html @@ -152,16 +152,7 @@ related standards, like Websocket or Server-Sent Events.

  • cowboy_rest(3) - REST handlers -

    -
    • -
  • -

    -cowboy_stream(3) - Stream handlers -

    -
    • -
  • -

    -cowboy_sub_protocol(3) - Sub protocols +

  • diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html index 604c8f26..17164fc5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html @@ -102,10 +102,10 @@ http://www.gnu.org/software/src-highlite --> terminate(Reason, Req, State) -> ok %% optional -Req :: cowboy_req:req() -State :: any() -Reason :: normal - | {crash, error | exit | throw, any()} +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 diff --git a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html index e5d69511..5882a278 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -72,51 +72,79 @@

    Name

    -

    cowboy_loop - loop handlers

    +

    cowboy_loop - Loop handlers

    Description

    -

    The cowboy_loop module implements a handler interface for -long running HTTP connections. It is the recommended interface -for long polling and server-sent events, amongst others.

    -

    This module is a sub protocol that defines three callbacks to -be implemented by handlers. The init/2 and terminate/3 -callbacks are common to all handler types and are documented -in the manual for the cowboy_handler module.

    -

    The info/3 callback is specific to loop handlers and will be -called as many times as necessary until a reply is sent.

    -

    It is highly recommended to return a timeout value from the -init/2 callback to ensure that the process is terminated -when no data has been received during that timespan. The -default timeout is infinity, which should only be used if -you have alternate means of ending inactive connections.

    +

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

      +
      • +
    -

    Terminate reasons

    +

    Callbacks

    -

    The following values may be received as the terminate reason -in the optional terminate/3 callback.

    +

    Loop handlers implement the following interface:

    +
    +
    +
    init(Req, State)
+    -> {cowboy_loop, Req, State}
+     | {cowboy_loop, Req, State, hibernate}
+     | {cowboy_loop, Req, State, timeout()}
+     | {cowboy_loop, Req, State, timeout(), 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 | timeout
+        | {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:

    -normal -
    -
    -

    - The connection was closed normally before switching to the - loop sub protocol. This typically happens if an ok tuple is - returned from the init/2 callback. -

    -
    -
    stop

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

    @@ -124,9 +152,9 @@ timeout

    - The connection has been closed due to inactivity. The timeout - value can be configured from init/2. The response sent when - this happens is a 204 No Content. + The connection has been closed due to inactivity. The timeout + value can be configured from init/2. The response sent when + this happens is a 204 No Content.

    @@ -134,87 +162,38 @@ timeout

    - 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, overflow} -
    -
    -

    - The connection is being closed and the process terminated - because the buffer Cowboy uses to keep data sent by the - client has reached its maximum. The buffer size can be - configured through the environment value loop_max_buffer - and defaults to 5000 bytes. -
    - If the long running request comes with a body it is recommended - to process this body before switching to the loop sub protocol. -

    -
    -
    -{error, closed} -
    -
    -

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

    -
    -
    -{error, Reason} -
    -
    -

    - A socket error ocurred. + 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.

    -

    Callbacks

    +

    Changelog

    -
    -

    info(Info, Req, State) → {ok, Req, State} | {ok, Req, State, hibernate} | {stop, Req, State}

    -
    -
    -Info = any() -
    -
    -

    -Message received by the process. -

    -
    -
    -Req = cowboy_req:req() -
    -
    +
      +

    • -The Req object. +2.0: Cowboy temporarily no longer checks the socket for data with HTTP/1.1.

      -
    -
    -State = any() -
    -
    +
    • +

  • -Handler state. +1.0: Behavior introduced.

    - - -

    Handle the Erlang message received.

    -

    This function will be called every time an Erlang message -has been received. The message can be any Erlang term.

    -

    The stop return value can be used to stop the receive loop, -typically because a response has been sent.

    -

    The hibernate option will hibernate the process until -it receives another message.

    +
    • + +
    +

    See also

    +
    +

    cowboy(7), +cowboy_handler(3)

    +
    diff --git a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html index ebc7ba07..2a78e5b6 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html @@ -72,89 +72,110 @@

    Name

    -

    cowboy_middleware - behaviour for middlewares

    +

    cowboy_middleware - Middlewares

    Description

    -

    The cowboy_middleware behaviour defines the interface used -by Cowboy middleware modules.

    +

    The module cowboy_middleware defines a callback interface for +Cowboy middlewares.

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

    -

    Types

    -
    -
    -

    env() = [{atom(), any()}]

    -

    The environment variable.

    -

    One is created for every request. It is passed to each -middleware module executed and subsequently returned, -optionally with its contents modified.

    -
    -
    -
    -

    Callbacks

    -
    -

    execute(Req, Env) → {ok, Req, Env} | {suspend, Module, Function, Args} | {stop, Req}

    +

    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.

    -Req = cowboy_req:req() +ok

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

    -Env = env() +suspend

    -The request environment. +Cowboy will hibernate the process. When resuming, Cowboy +will apply the returned module, function and arguments.

    -Module = module() +stop

    -MFA to call when resuming the process. +Cowboy will stop middleware execution. No other middleware +will be executed. This effectively ends the processing of +the request.

    -
    -Function = atom() -
    -
    +
    +
    +
    +
    +

    Types

    +
    +
    +

    env()

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

    Middleware environment.

    +

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

    +

    Middlewares may modify the environment as necessary.

    +
    +
    +
    +
    +

    Changelog

    +
    +
      +

    • -MFA to call when resuming the process. +2.0: The env type is now a map instead of a proplist.

      - -
      -Args = [any()] -
      -
      +
      • +

    • -MFA to call when resuming the process. +1.0: Behavior introduced.

      - -
    -

    Execute the middleware.

    -

    The ok return value indicates that everything went well -and that Cowboy should continue processing the request. A -response may or may not have been sent.

    -

    The suspend return value will hibernate the process until -an Erlang message is received. Note that when resuming, any -previous stacktrace information will be gone.

    -

    The stop return value stops Cowboy from doing any further -processing of the request, even if there are middlewares -that haven’t been executed yet. The connection may be left -open to receive more requests from the client.

    + +
    +
    +
    +

    See also

    +
    +

    cowboy(7)

    diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html index e6cb088a..1d426ebd 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -304,6 +304,7 @@ timeout

    See also

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

    -- cgit v1.2.3