aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide/sub_protocols.asciidoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2016-01-14 13:35:25 +0100
committerLoïc Hoguin <[email protected]>2016-01-14 13:37:20 +0100
commit4023e7f4e429179fd9c2cce4487c33646c6bd327 (patch)
tree3c4e26d1b5592958e35297c82ad3069bdb642594 /doc/src/guide/sub_protocols.asciidoc
parentb7d666cfc746f55b0a72ef8d37f703885099daf7 (diff)
downloadcowboy-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.asciidoc68
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.