aboutsummaryrefslogtreecommitdiffstats
path: root/guide/upgrade_protocol.md
diff options
context:
space:
mode:
Diffstat (limited to 'guide/upgrade_protocol.md')
-rw-r--r--guide/upgrade_protocol.md37
1 files changed, 37 insertions, 0 deletions
diff --git a/guide/upgrade_protocol.md b/guide/upgrade_protocol.md
new file mode 100644
index 0000000..db7a453
--- /dev/null
+++ b/guide/upgrade_protocol.md
@@ -0,0 +1,37 @@
+Protocol upgrades
+=================
+
+Cowboy features many different handlers, each for different purposes.
+All handlers have a common entry point: the `init/3` function.
+
+The default handler type is the simple HTTP handler.
+
+To switch to a different protocol, you must perform a protocol
+upgrade. This is what is done for Websocket and REST and is
+explained in details in the respective chapters.
+
+You can also create your own protocol on top of Cowboy and use
+the protocol upgrade mechanism to switch to it.
+
+For example, if you create the `my_protocol` module implementing
+the `cowboy_sub_protocol` behavior, then you can upgrade to it
+by simply returning the module name from `init/3`.
+
+``` erlang
+init(_, _, _Opts) ->
+ {upgrade, protocol, my_protocol}.
+```
+
+The `cowboy_sub_protocol` behavior only requires one callback,
+`upgrade/4`. It receives the Req object, the middleware environment,
+and the handler and options for this request. This is the same
+module as the `init/3` function and the same options that were
+passed to it.
+
+``` erlang
+upgrade(Req, Env, Handler, HandlerOpts) ->
+ %% ...
+```
+
+This callback is expected to behave like a middleware. Please
+see the corresponding chapter for more information.