diff options
author | Loïc Hoguin <[email protected]> | 2016-01-14 13:35:25 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2016-01-14 13:37:20 +0100 |
commit | 4023e7f4e429179fd9c2cce4487c33646c6bd327 (patch) | |
tree | 3c4e26d1b5592958e35297c82ad3069bdb642594 /doc/src/guide/sub_protocols.asciidoc | |
parent | b7d666cfc746f55b0a72ef8d37f703885099daf7 (diff) | |
download | cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.gz cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.tar.bz2 cowboy-4023e7f4e429179fd9c2cce4487c33646c6bd327.zip |
Convert the documentation to Asciidoc
A few small revisions were made, and Erlang.mk has been updated.
Diffstat (limited to 'doc/src/guide/sub_protocols.asciidoc')
-rw-r--r-- | doc/src/guide/sub_protocols.asciidoc | 68 |
1 files changed, 68 insertions, 0 deletions
diff --git a/doc/src/guide/sub_protocols.asciidoc b/doc/src/guide/sub_protocols.asciidoc new file mode 100644 index 0000000..63fd52b --- /dev/null +++ b/doc/src/guide/sub_protocols.asciidoc @@ -0,0 +1,68 @@ +[[sub_protocols]] +== Sub protocols + +Sub protocols are used for creating new types of handlers that +provide extra functionality in a reusable way. Cowboy uses this +mechanism to provide its loop, REST and Websocket handlers. + +This chapter will explain how to create your own sub protocols +and handler types. + +=== Usage + +To switch to a sub protocol, the `init/2` callback must return +the name of the sub protocol module. Everything past this point +is handled by the sub protocol. + +[source,erlang] +---- +init(Req, _Opts) -> + {cowboy_websocket, Req, #state{}}. +---- + +The return value may also have a `Timeout` value and/or the +atom `hibernate`. These options are useful for long living +connections. When they are not provided, the timeout value +defaults to `infinity` and the hibernate value to `run`. + +The following snippet switches to the `my_protocol` sub +protocol, sets the timeout value to 5 seconds and enables +hibernation: + +[source,erlang] +---- +init(Req, _Opts) -> + {my_protocol, Req, #state{}, 5000, hibernate}. +---- + +If a sub protocol does not make use of these options, it should +crash if it receives anything other than the default values. + +=== Upgrade + +After the `init/2` function returns, Cowboy will then call the +`upgrade/6` function. This is the only callback defined by the +`cowboy_sub_protocol` behavior. + +The function is named `upgrade` because it mimics the mechanism +of HTTP protocol upgrades. For some sub protocols, like Websocket, +an actual upgrade is performed. For others, like REST, this is +only an upgrade at Cowboy's level and the client has nothing to +do about it. + +The upgrade callback receives the Req object, the middleware +environment, the handler and its options, and the aforementioned +timeout and hibernate values. + +[source,erlang] +---- +upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) -> + %% Sub protocol code here. +---- + +This callback is expected to behave like a middleware and to +return an updated environment and Req object. + +Sub protocols are expected to call the `cowboy_handler:terminate/4` +function when they terminate. This function will make sure that +the optional `terminate/3` callback is called, if present. |