From fd3c40c7ee7d5efdd75481876e457e723e4b4e20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 25 Jun 2014 11:23:58 +0200 Subject: Wrap-up the user guide --- guide/upgrade_protocol.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 guide/upgrade_protocol.md (limited to 'guide/upgrade_protocol.md') 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. -- cgit v1.2.3