aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_loop.ezdoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-09-30 20:12:13 +0300
committerLoïc Hoguin <[email protected]>2014-09-30 20:12:13 +0300
commit0dc063ab7d94edb37c61f821b5d8e4c2da7f8ff1 (patch)
treeaaa71b552b0348fc403cc68ba8318e58f213d4fd /doc/src/manual/cowboy_loop.ezdoc
parent5ce4c2bfb40ecc4b687a2941e612025a1c4ff913 (diff)
downloadcowboy-0dc063ab7d94edb37c61f821b5d8e4c2da7f8ff1.tar.gz
cowboy-0dc063ab7d94edb37c61f821b5d8e4c2da7f8ff1.tar.bz2
cowboy-0dc063ab7d94edb37c61f821b5d8e4c2da7f8ff1.zip
Improve handler interface and documentation
This change simplifies a little more the sub protocols mechanism. Aliases have been removed. The renaming of loop handlers as long polling handlers has been reverted. Plain HTTP handlers now simply do their work in the init/2 callback. There is no specific code for them. Loop handlers now follow the same return value as Websocket, they use ok to continue and shutdown to stop. Terminate reasons for all handler types have been documented. The terminate callback is now appropriately called in all cases (or should be). Behaviors for all handler types have been moved in the module that implement them. This means that cowboy_handler replaces the cowboy_http_handler behavior, and similarly cowboy_loop replaces cowboy_loop_handler, cowboy_websocket replaces cowboy_websocket_handler. Finally cowboy_rest now has the start of a behavior in it and will have the full list of optional callbacks defined once Erlang 18.0 gets released. The guide has been reorganized and should be easier to follow.
Diffstat (limited to 'doc/src/manual/cowboy_loop.ezdoc')
-rw-r--r--doc/src/manual/cowboy_loop.ezdoc100
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.