path: root/guide
diff options
authorLoïc Hoguin <[email protected]>2013-01-03 22:47:51 +0100
committerLoïc Hoguin <[email protected]>2013-01-03 22:47:51 +0100
commit1b3f510b7e8d5413901ba72adfe361773f3e9097 (patch)
tree314d24a8bbbdfc1e326cac28193ab6d9f7dc3b61 /guide
parent73d86057f2f9d6b3de5fb12e23b2cd65be50e226 (diff)
Add middleware support
Middlewares allow customizing the request processing. All existing Cowboy project are incompatible with this commit. You need to change `{dispatch, Dispatch}` in the protocol options to `{env, [{dispatch, Dispatch}]}` to fix your code.
Diffstat (limited to 'guide')
3 files changed, 82 insertions, 5 deletions
diff --git a/guide/middlewares.md b/guide/middlewares.md
new file mode 100644
index 0000000..2f583cf
--- /dev/null
+++ b/guide/middlewares.md
@@ -0,0 +1,74 @@
+Cowboy delegates the request processing to middleware components.
+By default, two middlewares are defined, for the routing and handling
+of the request, as is detailed in most of this guide.
+Middlewares give you complete control over how requests are to be
+processed. You can add your own middlewares to the mix or completely
+change the chain of middlewares as needed.
+Cowboy will execute all middlewares in the given order, unless one
+of them decides to stop processing.
+Middlewares only need to implement a single callback: `execute/2`.
+It is defined in the `cowboy_middleware` behavior.
+This callback has two arguments. The first is the `Req` object.
+The second is the environment.
+Middlewares can return one of four different values:
+ * `{ok, Req, Env}` to continue the request processing
+ * `{suspend, Module, Function, Args}` to hibernate
+ * `{halt, Req}` to stop processing and move on to the next request
+ * `{error, StatusCode, Req}` to reply an error and close the socket
+Of note is that when hibernating, processing will resume on the given
+MFA, discarding all previous stacktrace. Make sure you keep the `Req`
+and `Env` in the arguments of this MFA for later use.
+If an error happens during middleware processing, Cowboy will not try
+to send an error back to the socket, the process will just crash. It
+is up to the middleware to make sure that a reply is sent if something
+goes wrong.
+The middleware environment is defined as the `env` protocol option.
+In the previous chapters we saw it briefly when we needed to pass
+the routing information. It is a list of tuples with the first
+element being an atom and the second any Erlang term.
+Two values in the environment are reserved:
+ * `listener` contains the pid of the listener process
+ * `result` contains the result of the processing
+The `listener` value is always defined. The `result` value can be
+set by any middleware. If set to anything other than `ok`, Cowboy
+will not process any subsequent requests on this connection.
+The middlewares that come with Cowboy may define or require other
+environment values to perform.
+Routing middleware
[email protected] Routing middleware value is renamed very soon.
+The routing middleware requires the `dispatch` value. If routing
+succeeds, it will put the handler name and options in the `handler`
+and `handler_opts` values of the environment, respectively.
+Handler middleware
+The handler middleware requires the `handler` and `handler_opts`
+values. It puts the result of the request handling into `result`.
diff --git a/guide/routing.md b/guide/routing.md
index 936b37c..7d6fa41 100644
--- a/guide/routing.md
+++ b/guide/routing.md
@@ -135,18 +135,15 @@ handler to run instead of having to parse the routes repeatedly.
This can be done with a simple call to `cowboy_routing:compile/1`.
[email protected] Note that the `routes` option will be specified slightly differently
-when middleware support gets in.
``` erlang
{ok, Routes} = cowboy_routing:compile([
- %% {URIHost, list({URIPath, Handler, Opts})}
+ %% {HostMatch, list({PathMatch, Handler, Opts})}
{'_', [{'_', my_handler, []}]}
%% Name, NbAcceptors, TransOpts, ProtoOpts
cowboy:start_http(my_http_listener, 100,
[{port, 8080}],
- [{routes, Routes}]
+ [{env, [{routes, Routes}]}]
diff --git a/guide/toc.md b/guide/toc.md
index 32234cd..2498b4d 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -43,6 +43,12 @@ Cowboy User Guide
* [Hooks](hooks.md)
* On request
* On response
+ * [Middlewares](middlewares.md)
+ * Purpose
+ * Usage
+ * Configuration
+ * Routing middleware
+ * Handler middleware
* [Internals](internals.md)
* Architecture
* Efficiency considerations