aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide/sub_protocols.ezdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/guide/sub_protocols.ezdoc')
-rw-r--r--doc/src/guide/sub_protocols.ezdoc64
1 files changed, 64 insertions, 0 deletions
diff --git a/doc/src/guide/sub_protocols.ezdoc b/doc/src/guide/sub_protocols.ezdoc
new file mode 100644
index 0000000..d34f21e
--- /dev/null
+++ b/doc/src/guide/sub_protocols.ezdoc
@@ -0,0 +1,64 @@
+::: 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.
+
+``` erlang
+init(Req, Opts) ->
+ {cowboy_websocket, Req, Opts}.
+```
+
+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:
+
+``` erlang
+init(Req, Opts) ->
+ {my_protocol, Req, Opts, 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.
+
+``` 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.