1 files changed, 55 insertions, 0 deletions
diff --git a/guide/handlers.md b/guide/handlers.md
new file mode 100644
index 0000000..e2c1264
--- /dev/null
+++ b/guide/handlers.md
@@ -0,0 +1,55 @@
+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}.
+```
+
+Cowboy comes with two protocol upgrades: `cowboy_rest` and
+`cowboy_websocket`. Use these values in place of `my_protocol`
+to use them.
+
+Custom protocol upgrades
+------------------------
+
+The `my_protocol` module above will be used for further processing
+of the request. It requires only one callback, `upgrade/4`.
+
+It receives the request object, the middleware environment, and
+the handler this request has been routed to along with its options.
+
+``` erlang
+upgrade(Req, Env, Handler, HandlerOpts) ->
+    %% ...
+```
+
+This callback is expected to behave like any middleware. Please
+see the corresponding chapter for more information.