diff options
author | Loïc Hoguin <[email protected]> | 2014-06-25 11:23:58 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2014-06-25 11:23:58 +0200 |
commit | fd3c40c7ee7d5efdd75481876e457e723e4b4e20 (patch) | |
tree | bbe0880196f81daa29d43954b2e774810353c108 /guide/upgrade_protocol.md | |
parent | 642630fea10490e3bbe214652142c51c7787de46 (diff) | |
download | cowboy-fd3c40c7ee7d5efdd75481876e457e723e4b4e20.tar.gz cowboy-fd3c40c7ee7d5efdd75481876e457e723e4b4e20.tar.bz2 cowboy-fd3c40c7ee7d5efdd75481876e457e723e4b4e20.zip |
Wrap-up the user guide
Diffstat (limited to 'guide/upgrade_protocol.md')
-rw-r--r-- | guide/upgrade_protocol.md | 37 |
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. |