diff options
author | Loïc Hoguin <[email protected]> | 2013-01-01 18:27:41 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2013-01-01 18:27:41 +0100 |
commit | 06e74355c0a993b416b21bb4e9586c37973e8d83 (patch) | |
tree | bb70dc2d6369637d5663c01e031f3da875eb3dc9 /guide/handlers.md | |
parent | 2690d1254caffa2d85965baf95ed005c39fc820a (diff) | |
download | cowboy-06e74355c0a993b416b21bb4e9586c37973e8d83.tar.gz cowboy-06e74355c0a993b416b21bb4e9586c37973e8d83.tar.bz2 cowboy-06e74355c0a993b416b21bb4e9586c37973e8d83.zip |
Add a skeleton of the guide to ease user contributions
Has some stuff that aren't in master yet, and lacks a lot more
that is already in master.
Diffstat (limited to 'guide/handlers.md')
-rw-r--r-- | guide/handlers.md | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/guide/handlers.md b/guide/handlers.md new file mode 100644 index 0000000..dac5460 --- /dev/null +++ b/guide/handlers.md @@ -0,0 +1,39 @@ +Handlers +======== + +Purpose +------- + +Handlers are Erlang modules that represent a resource. + +Handlers must process the request and send a reply. The nature of the +reply will vary between handlers. + +Different kinds of handlers can be combined in a single module. This +allows a module to handle both websocket and long-polling code in a +single place, for example. + +Protocol upgrades +----------------- + +Cowboy features many different handlers: HTTP handlers, loop handlers, +websocket handlers, REST handlers and static handlers. All of them +have a common entry point: the `init/3` function. + +By default, Cowboy considers your handler to be an HTTP handler. + +To switch to a different protocol, like, for example, Websocket, +you must perform a protocol upgrade. This is done by returning +a protocol upgrade tuple at the end of `init/3`. + +The following snippet upgrades the handler to `my_protocol`. + +``` erlang +init(_Any, _Req, _Opts) -> + {upgrade, protocol, my_protocol}. +``` + +The `my_protocol` module will be used for further processing of the +request. It requires only one callback, `upgrade/4`. + +@todo Describe `upgrade/4` when the middleware code gets pushed. |