diff options
| -rw-r--r-- | guide/handlers.md | 3 | ||||
| -rw-r--r-- | src/cowboy_rest.erl | 1 | ||||
| -rw-r--r-- | src/cowboy_sub_protocol.erl | 37 | ||||
| -rw-r--r-- | src/cowboy_websocket.erl | 1 |
4 files changed, 41 insertions, 1 deletions
diff --git a/guide/handlers.md b/guide/handlers.md index e2c1264..5ffe401 100644 --- a/guide/handlers.md +++ b/guide/handlers.md @@ -41,7 +41,8 @@ Custom protocol upgrades ------------------------ The `my_protocol` module above will be used for further processing -of the request. It requires only one callback, `upgrade/4`. +of the request. It should use the `cowboy_sub_protocol` behaviour, +which 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. diff --git a/src/cowboy_rest.erl b/src/cowboy_rest.erl index d3a91d3..a40e1c6 100644 --- a/src/cowboy_rest.erl +++ b/src/cowboy_rest.erl @@ -19,6 +19,7 @@ %% documentation available at http://wiki.basho.com/Webmachine.html %% at the time of writing. -module(cowboy_rest). +-behaviour(cowboy_sub_protocol). -export([upgrade/4]). diff --git a/src/cowboy_sub_protocol.erl b/src/cowboy_sub_protocol.erl new file mode 100644 index 0000000..0b231d3 --- /dev/null +++ b/src/cowboy_sub_protocol.erl @@ -0,0 +1,37 @@ +%% Copyright (c) 2013, James Fish <[email protected]> +%% +%% Permission to use, copy, modify, and/or distribute this software for any +%% purpose with or without fee is hereby granted, provided that the above +%% copyright notice and this permission notice appear in all copies. +%% +%% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +%% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +%% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +%% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +%% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +%% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +%% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +%% @doc Behaviour for sub protocols. +%% +%% Only one function needs to be implemented, <em>upgrade/4</em>. +%% It receives the Req, the environment, the handler that the request has been +%% routed to and the handler's options. It acts exactly the same as a +%% middleware, so returns the same values a middleware's execute/2. +%% +%% Once the sub protocol has processed the request it should add the result +%% to the environment. This is done by adding the tuple {result, Value} to the +%% environment list. To continue handling requests on the current connection the +%% Value should be the atom ok. Any other value will prevent the processing of +%% subsequent requests. +%% +%% <em>upgrade/4</em> will be called when a handler's init/3 returns +%% {upgrade, protocol, Module}, where Module is the module of the sub protocol. +-module(cowboy_sub_protocol). + +-callback upgrade(Req, Env, module(), any()) + -> {ok, Req, Env} + | {suspend, module(), atom(), any()} + | {halt, Req} + | {error, cowboy_http:status(), Req} + when Req::cowboy_req:req(), Env::cowboy_middleware:env(). diff --git a/src/cowboy_websocket.erl b/src/cowboy_websocket.erl index fa74223..7bb5e74 100644 --- a/src/cowboy_websocket.erl +++ b/src/cowboy_websocket.erl @@ -17,6 +17,7 @@ %% Cowboy supports versions 7 through 17 of the Websocket drafts. %% It also supports RFC6455, the proposed standard for Websocket. -module(cowboy_websocket). +-behaviour(cowboy_sub_protocol). %% API. -export([upgrade/4]). |