From 06e74355c0a993b416b21bb4e9586c37973e8d83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 1 Jan 2013 18:27:41 +0100 Subject: 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. --- guide/handlers.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 guide/handlers.md (limited to 'guide/handlers.md') 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. -- cgit v1.2.3