diff options
author | Loïc Hoguin <[email protected]> | 2013-01-03 22:47:51 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2013-01-03 22:47:51 +0100 |
commit | 1b3f510b7e8d5413901ba72adfe361773f3e9097 (patch) | |
tree | 314d24a8bbbdfc1e326cac28193ab6d9f7dc3b61 /guide | |
parent | 73d86057f2f9d6b3de5fb12e23b2cd65be50e226 (diff) | |
download | cowboy-1b3f510b7e8d5413901ba72adfe361773f3e9097.tar.gz cowboy-1b3f510b7e8d5413901ba72adfe361773f3e9097.tar.bz2 cowboy-1b3f510b7e8d5413901ba72adfe361773f3e9097.zip |
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')
-rw-r--r-- | guide/middlewares.md | 74 | ||||
-rw-r--r-- | guide/routing.md | 7 | ||||
-rw-r--r-- | guide/toc.md | 6 |
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 @@ +Middlewares +=========== + +Purpose +------- + +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. + +Usage +----- + +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. + +Configuration +------------- + +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 +------------------ + +@todo 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`. -@todo 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 |