diff options
Diffstat (limited to 'doc/src/manual/cowboy_loop.ezdoc')
-rw-r--r-- | doc/src/manual/cowboy_loop.ezdoc | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_loop.ezdoc b/doc/src/manual/cowboy_loop.ezdoc new file mode 100644 index 0000000..1f3ab9e --- /dev/null +++ b/doc/src/manual/cowboy_loop.ezdoc @@ -0,0 +1,100 @@ +::: cowboy_loop + +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. + +:: Types + +None. + +:: Terminate reasons + +The following values may be received as the terminate reason +in the optional `terminate/3` callback. + +: 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. + +: shutdown + +The handler requested to close the connection by returning +a `shutdown` tuple. + +: 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`. + +: {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, 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. + +:: Callbacks + +: info(Info, Req, State) + -> {ok, Req, State} + | {ok, Req, State, hibernate} + | {shutdown, Req, State} + +Types: + +* Info = any() +* Req = cowboy_req:req() +* State = any() + +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 `shutdown` 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. + +:: Exports + +None. |