Add the Cowboy Function Reference

The manual details every stable public functions of Cowboy.

1 files changed, 56 insertions, 0 deletions

diff --git a/manual/cowboy_middleware.md b/manual/cowboy_middleware.md
new file mode 100644
index 0000000..dd28ff8
--- /dev/null
+++ b/manual/cowboy_middleware.md
@@ -0,0 +1,56 @@
+cowboy_middleware
+=================
+
+The `cowboy_middleware` behaviour defines the interface used
+by Cowboy middleware modules.
+
+Middlewares process the request sequentially in the order they
+are configured.
+
+Types
+-----
+
+### env() = [{atom(), any()}]
+
+> The environment variable.
+>
+> One is created for every request. It is passed to each
+> middleware module executed and subsequently returned,
+> optionally with its contents modified.
+
+Callbacks
+---------
+
+### execute(Req, Env)
+	-> {ok, Req, Env}
+	| {suspend, Module, Function, Args}
+	| {halt, Req}
+	| {error, StatusCode, Req}
+
+> Types:
+>  *  Req = cowboy_req:req()
+>  *  Env = env()
+>  *  Module = module()
+>  *  Function = atom()
+>  *  Args = [any()]
+>  *  StatusCode = cowboy:http_status()
+>
+> Execute the middleware.
+>
+> The `ok` return value indicates that everything went well
+> and that Cowboy should continue processing the request. A
+> response may or may not have been sent.
+>
+> The `suspend` return value will hibernate the process until
+> an Erlang message is received. Note that when resuming, any
+> previous stacktrace information will be gone.
+>
+> The `halt` return value stops Cowboy from doing any further
+> processing of the request, even if there are middlewares
+> that haven't been executed yet. The connection may be left
+> open to receive more requests from the client.
+>
+> The `error` return value sends an error response identified
+> by the `StatusCode` and then proceeds to terminate the
+> connection. Middlewares that haven't been executed yet
+> will not be called.