aboutsummaryrefslogtreecommitdiffstats
path: root/manual
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
committerLoïc Hoguin <[email protected]>2014-07-06 13:10:35 +0200
commit078d686a0ac0aed212db97d73bd1e4a9387a4956 (patch)
tree6bbc6111fdbdfedd3bb351bf3b01c63fac0d7143 /manual
parent1a71a733c37df70c15ebfd28157b10915cd738d1 (diff)
downloadcowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.gz
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.tar.bz2
cowboy-078d686a0ac0aed212db97d73bd1e4a9387a4956.zip
Provide installable man pages
make docs: generate Markdown and man pages in doc/ make install-docs: install man pages to be usable directly Docs are generated from the ezdoc files in doc/src/.
Diffstat (limited to 'manual')
-rw-r--r--manual/cowboy.md100
-rw-r--r--manual/cowboy_app.md26
-rw-r--r--manual/cowboy_handler.md25
-rw-r--r--manual/cowboy_http_handler.md57
-rw-r--r--manual/cowboy_loop_handler.md91
-rw-r--r--manual/cowboy_middleware.md56
-rw-r--r--manual/cowboy_protocol.md65
-rw-r--r--manual/cowboy_req.md670
-rw-r--r--manual/cowboy_rest.md560
-rw-r--r--manual/cowboy_router.md68
-rw-r--r--manual/cowboy_spdy.md40
-rw-r--r--manual/cowboy_static.md34
-rw-r--r--manual/cowboy_sub_protocol.md34
-rw-r--r--manual/cowboy_websocket.md40
-rw-r--r--manual/cowboy_websocket_handler.md131
-rw-r--r--manual/http_status_codes.md180
-rw-r--r--manual/toc.md21
17 files changed, 0 insertions, 2198 deletions
diff --git a/manual/cowboy.md b/manual/cowboy.md
deleted file mode 100644
index 0eab0f8..0000000
--- a/manual/cowboy.md
+++ /dev/null
@@ -1,100 +0,0 @@
-cowboy
-======
-
-The `cowboy` module provides convenience functions for
-manipulating Ranch listeners.
-
-Types
------
-
-### http_headers() = [{binary(), iodata()}]
-
-> HTTP headers as a list of key/values.
-
-### http_status() = non_neg_integer() | binary()
-
-> HTTP status.
->
-> A binary status can be used to set a custom message.
-
-### http_version() = 'HTTP/1.1' | 'HTTP/1.0'
-
-> HTTP version.
-
-### onrequest_fun() = fun((cowboy_req:req()) -> cowboy_req:req())
-
-> Fun called immediately after receiving a request.
->
-> It can perform any operation on the `Req` object, including
-> reading the request body or replying. If a reply is sent,
-> the processing of the request ends here, before any middleware
-> is executed.
-
-### onresponse_fun() = fun((http_status(), http_headers(),
- iodata(), cowboy_req:req()) -> cowboy_req:req())
-
-> Fun called immediately before sending the response.
->
-> It can perform any operation on the `Req` object, including
-> reading the request body or replying. If a reply is sent, it
-> overrides the reply initially sent. The callback will not be
-> called again for the new reply.
-
-Exports
--------
-
-### start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
-
-> Types:
-> * Ref = ranch:ref()
-> * NbAcceptors = non_neg_integer()
-> * TransOpts = ranch_tcp:opts()
-> * ProtoOpts = cowboy_protocol:opts()
->
-> Start listening for HTTP connections. Returns the pid for this
-> listener's supervisor.
-
-### start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
-
-> Types:
-> * Ref = ranch:ref()
-> * NbAcceptors = non_neg_integer()
-> * TransOpts = ranch_ssl:opts()
-> * ProtoOpts = cowboy_protocol:opts()
->
-> Start listening for HTTPS connections. Returns the pid for this
-> listener's supervisor.
-
-### start_spdy(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
-
-> Types:
-> * Ref = ranch:ref()
-> * NbAcceptors = non_neg_integer()
-> * TransOpts = ranch_ssl:opts()
-> * ProtoOpts = cowboy_spdy:opts()
->
-> Start listening for SPDY connections. Returns the pid for this
-> listener's supervisor.
-
-### stop_listener(Ref) -> ok | {error, not_found}
-
-> Types:
-> * Ref = ranch:ref()
->
-> Stop a previously started listener.
-
-### set_env(Ref, Name, Value) -> ok
-
-> Types:
-> * Ref = ranch:ref()
-> * Name = atom()
-> * Value = any()
->
-> Set or update an environment value for an already running listener.
-> This will take effect on all subsequent connections.
-
-See also
---------
-
-The [Ranch guide](http://ninenines.eu/docs/en/ranch/HEAD/guide)
-provides detailed information about how listeners work.
diff --git a/manual/cowboy_app.md b/manual/cowboy_app.md
deleted file mode 100644
index 2a086de..0000000
--- a/manual/cowboy_app.md
+++ /dev/null
@@ -1,26 +0,0 @@
-The Cowboy Application
-======================
-
-Small, fast, modular HTTP server.
-
-Dependencies
-------------
-
-The `cowboy` application uses the Erlang applications `ranch`
-for listening and accepting TCP connections, `crypto` for
-establishing Websocket connections, and `cowlib` for parsing and
-building messages for Web protocols. These dependencies must
-be loaded for the `cowboy` application to work. In an embedded
-environment this means that they need to be started with the
-`application:start/{1,2}` function before the `cowboy`
-application is started.
-
-The `cowboy` application also uses the Erlang applications
-`asn1`, `public_key` and `ssl` when listening for HTTPS connections.
-These are started automatically if they weren't before.
-
-Environment
------------
-
-The `cowboy` application does not define any application
-environment configuration parameters.
diff --git a/manual/cowboy_handler.md b/manual/cowboy_handler.md
deleted file mode 100644
index 8d13492..0000000
--- a/manual/cowboy_handler.md
+++ /dev/null
@@ -1,25 +0,0 @@
-cowboy_handler
-==============
-
-The `cowboy_handler` middleware executes the handler passed
-through the environment values `handler` and `handler_opts`,
-and add the result of this execution to the environment as
-the value `result`, indicating that the request has been
-handled and received a response.
-
-Environment input:
- * handler = module()
- * handler_opts = any()
-
-Environment output:
- * result = ok
-
-Types
------
-
-None.
-
-Exports
--------
-
-None.
diff --git a/manual/cowboy_http_handler.md b/manual/cowboy_http_handler.md
deleted file mode 100644
index 9d283e7..0000000
--- a/manual/cowboy_http_handler.md
+++ /dev/null
@@ -1,57 +0,0 @@
-cowboy_http_handler
-===================
-
-The `cowboy_http_handler` behaviour defines the interface used
-by plain HTTP handlers.
-
-Unless noted otherwise, the callbacks will be executed sequentially.
-
-Types
------
-
-None.
-
-Callbacks
----------
-
-### init({TransportName, ProtocolName}, Req, Opts)
- -> {ok, Req, State} | {shutdown, Req, State}
-
-> Types:
-> * TransportName = tcp | ssl | atom()
-> * ProtocolName = http | atom()
-> * Req = cowboy_req:req()
-> * Opts = any()
-> * State = any()
->
-> Initialize the state for this request.
->
-> The `shutdown` return value can be used to skip the `handle/2`
-> call entirely.
-
-### handle(Req, State) -> {ok, Req, State}
-
-> Types:
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Handle the request.
->
-> This callback is where the request is handled and a response
-> should be sent. If a response is not sent, Cowboy will send
-> a `204 No Content` response automatically.
-
-### terminate(Reason, Req, State) -> ok
-
-> Types:
-> * Reason = {normal, shutdown} | {error, atom()}
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Perform any necessary cleanup of the state.
->
-> This callback should release any resource currently in use,
-> clear any active timer and reset the process to its original
-> state, as it might be reused for future requests sent on the
-> same connection. Typical plain HTTP handlers rarely need to
-> use it.
diff --git a/manual/cowboy_loop_handler.md b/manual/cowboy_loop_handler.md
deleted file mode 100644
index ccbb9b0..0000000
--- a/manual/cowboy_loop_handler.md
+++ /dev/null
@@ -1,91 +0,0 @@
-cowboy_loop_handler
-===================
-
-The `cowboy_loop_handler` behaviour defines the interface used
-by HTTP handlers that do not send a response directly, instead
-requiring a receive loop to process Erlang messages.
-
-This interface is best fit for long-polling types of requests.
-
-The `init/3` callback will always be called, followed by zero
-or more calls to `info/3`. The `terminate/3` will always be
-called last.
-
-Types
------
-
-None.
-
-Callbacks
----------
-
-### init({TransportName, ProtocolName}, Req, Opts)
- -> {loop, Req, State}
- | {loop, Req, State, hibernate}
- | {loop, Req, State, Timeout}
- | {loop, Req, State, Timeout, hibernate}
- | {shutdown, Req, State}
-
-> Types:
-> * TransportName = tcp | ssl | atom()
-> * ProtocolName = http | atom()
-> * Req = cowboy_req:req()
-> * Opts = any()
-> * State = any()
-> * Timeout = timeout()
->
-> Initialize the state for this request.
->
-> This callback will typically be used to register this process
-> to an event manager or a message queue in order to receive
-> the messages the handler wants to process.
->
-> The receive loop will run for a duration of up to `Timeout`
-> milliseconds after it last received data from the socket,
-> at which point it will stop and send a `204 No Content` reply.
-> By default this value is set to `infinity`. It is recommended
-> to either set this value or ensure by any other mechanism
-> that the handler will be closed after a certain period of
-> inactivity.
->
-> The `hibernate` option will hibernate the process until it
-> starts receiving messages.
->
-> The `shutdown` return value can be used to skip the receive
-> loop entirely.
-
-### info(Info, Req, State) -> {ok, Req, State} | {loop, Req, State}
- | {loop, Req, State, hibernate}
-
-> Types:
-> * Info = any()
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Handle the Erlang message received.
->
-> This function will be called every time an Erlang message
-> has been received. The message can be any Erlang term.
->
-> The `ok` return value can be used to stop the receive loop,
-> typically because a response has been sent.
->
-> The `hibernate` option will hibernate the process until
-> it receives another message.
-
-### terminate(Reason, Req, State) -> ok
-
-> Types:
-> * Reason = {normal, shutdown} | {normal, timeout} | {error, closed} | {error, overflow} | {error, atom()}
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Perform any necessary cleanup of the state.
->
-> This callback will typically unregister from any event manager
-> or message queue it registered to in `init/3`.
->
-> This callback should release any resource currently in use,
-> clear any active timer and reset the process to its original
-> state, as it might be reused for future requests sent on the
-> same connection.
diff --git a/manual/cowboy_middleware.md b/manual/cowboy_middleware.md
deleted file mode 100644
index dd28ff8..0000000
--- a/manual/cowboy_middleware.md
+++ /dev/null
@@ -1,56 +0,0 @@
-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.
diff --git a/manual/cowboy_protocol.md b/manual/cowboy_protocol.md
deleted file mode 100644
index 86aee9d..0000000
--- a/manual/cowboy_protocol.md
+++ /dev/null
@@ -1,65 +0,0 @@
-cowboy_protocol
-===============
-
-The `cowboy_protocol` module implements HTTP/1.1 and HTTP/1.0
-as a Ranch protocol.
-
-Types
------
-
-### opts() = [{compress, boolean()}
- | {env, cowboy_middleware:env()}
- | {max_empty_lines, non_neg_integer()}
- | {max_header_name_length, non_neg_integer()}
- | {max_header_value_length, non_neg_integer()}
- | {max_headers, non_neg_integer()}
- | {max_keepalive, non_neg_integer()}
- | {max_request_line_length, non_neg_integer()}
- | {middlewares, [module()]}
- | {onrequest, cowboy:onrequest_fun()}
- | {onresponse, cowboy:onresponse_fun()}
- | {timeout, timeout()}]
-
-> Configuration for the HTTP protocol handler.
->
-> This configuration is passed to Cowboy when starting listeners
-> using `cowboy:start_http/4` or `cowboy:start_https/4` functions.
->
-> It can be updated without restarting listeners using the
-> Ranch functions `ranch:get_protocol_options/1` and
-> `ranch:set_protocol_options/2`.
-
-Option descriptions
--------------------
-
-The default value is given next to the option name.
-
- - compress (false)
- - When enabled, Cowboy will attempt to compress the response body.
- - env ([{listener, Ref}])
- - Initial middleware environment.
- - max_empty_lines (5)
- - Maximum number of empty lines before a request.
- - max_header_name_length (64)
- - Maximum length of header names.
- - max_header_value_length (4096)
- - Maximum length of header values.
- - max_headers (100)
- - Maximum number of headers allowed per request.
- - max_keepalive (100)
- - Maximum number of requests allowed per connection.
- - max_request_line_length (4096)
- - Maximum length of the request line.
- - middlewares ([cowboy_router, cowboy_handler])
- - List of middlewares to execute for every requests.
- - onrequest (undefined)
- - Fun called every time a request is received.
- - onresponse (undefined)
- - Fun called every time a response is sent.
- - timeout (5000)
- - Time in ms with no requests before Cowboy closes the connection.
-
-Exports
--------
-
-None.
diff --git a/manual/cowboy_req.md b/manual/cowboy_req.md
deleted file mode 100644
index 00bfd64..0000000
--- a/manual/cowboy_req.md
+++ /dev/null
@@ -1,670 +0,0 @@
-cowboy_req
-==========
-
-The `cowboy_req` module provides functions to access, manipulate
-and respond to requests.
-
-The functions in this module follow patterns for their return types,
-based on the kind of function.
-
- * access: `{Value, Req}`
- * action: `{Result, Req} | {Result, Value, Req} | {error, atom()}`
- * modification: `Req`
- * question: `boolean()`
-
-The only exception is the `chunk/2` function which may return `ok`.
-
-Whenever `Req` is returned, you must use this returned value and
-ignore any previous you may have had. This value contains various
-state informations which are necessary for Cowboy to do some lazy
-evaluation or cache results where appropriate.
-
-All functions which perform an action should only be called once.
-This includes reading the request body or replying. Cowboy will
-generally throw an error on the second call.
-
-It is highly discouraged to pass the Req object to another process.
-Doing so and calling `cowboy_req` functions from it leads to
-undefined behavior.
-
-Types
------
-
-### body_opts() = [{continue, boolean()}
- | {length, non_neg_integer()}
- | {read_length, non_neg_integer()}
- | {read_timeout, timeout()}
- | {transfer_decode, transfer_decode_fun(), any()}
- | {content_decode, content_decode_fun()}]
-
-> Request body reading options.
-
-### cookie_opts() = [{max_age, non_neg_integer()}
- | {domain, binary()} | {path, binary()}
- | {secure, boolean()} | {http_only, boolean()}]
-
-> Cookie options.
-
-### req() - opaque to the user
-
-> The `Req` object.
->
-> All functions in this module receive a `Req` as argument,
-> and most of them return a new object labelled `Req2` in
-> the function descriptions below.
-
-Request related exports
------------------------
-
-### binding(Name, Req) -> binding(Name, Req, undefined)
-### binding(Name, Req, Default) -> {Value, Req2}
-
-> Types:
-> * Name = atom()
-> * Default = any()
-> * Value = any() | Default
->
-> Return the value for the given binding.
->
-> By default the value is a binary, however constraints may change
-> the type of this value (for example automatically converting
-> numbers to integer).
-
-### bindings(Req) -> {[{Name, Value}], Req2}
-
-> Types:
-> * Name = atom()
-> * Value = any()
->
-> Return all bindings.
->
-> By default the value is a binary, however constraints may change
-> the type of this value (for example automatically converting
-> numbers to integer).
-
-### cookie(Name, Req) -> cookie(Name, Req, undefined)
-### cookie(Name, Req, Default) -> {Value, Req2}
-
-> Types:
-> * Name = binary()
-> * Default = any()
-> * Value = binary() | Default
->
-> Return the value for the given cookie.
->
-> Cookie names are case sensitive.
-
-### cookies(Req) -> {[{Name, Value}], Req2}
-
-> Types:
-> * Name = binary()
-> * Value = binary()
->
-> Return all cookies.
-
-### header(Name, Req) -> header(Name, Req, undefined)
-### header(Name, Req, Default) -> {Value, Req2}
-
-> Types:
-> * Name = binary()
-> * Default = any()
-> * Value = binary() | Default
->
-> Return the value for the given header.
->
-> While header names are case insensitive, this function expects
-> the name to be a lowercase binary.
-
-### headers(Req) -> {Headers, Req2}
-
-> Types:
-> * Headers = cowboy:http_headers()
->
-> Return all headers.
-
-### host(Req) -> {Host, Req2}
-
-> Types:
-> * Host = binary()
->
-> Return the requested host.
-
-### host_info(Req) -> {HostInfo, Req2}
-
-> Types:
-> * HostInfo = cowboy_router:tokens() | undefined
->
-> Return the extra tokens from matching against `...` during routing.
-
-### host_url(Req) -> {HostURL, Req2}
-
-> Types:
-> * HostURL = binary() | undefined
->
-> Return the requested URL excluding the path component.
->
-> This function will always return `undefined` until the
-> `cowboy_router` middleware has been executed. This includes
-> the `onrequest` hook.
-
-### meta(Name, Req) -> meta(Name, Req, undefined)
-### meta(Name, Req, Default) -> {Value, Req2}
-
-> Types:
-> * Name = atom()
-> * Default = any()
-> * Value = any()
->
-> Return metadata about the request.
-
-### method(Req) -> {Method, Req2}
-
-> Types:
-> * Method = binary()
->
-> Return the method.
->
-> Methods are case sensitive. Standard methods are always uppercase.
-
-### parse_header(Name, Req) ->
-### parse_header(Name, Req, Default) -> {ok, ParsedValue, Req2}
- | {undefined, Value, Req2} | {error, badarg}
-
-> Types:
-> * Name = binary()
-> * Default = any()
-> * ParsedValue - see below
-> * Value = any()
->
-> Parse the given header.
->
-> While header names are case insensitive, this function expects
-> the name to be a lowercase binary.
->
-> The `parse_header/2` function will call `parser_header/3` with a
-> different default value depending on the header being parsed. The
-> following table summarizes the default values used.
->
-> | Header name | Default value |
-> | ----------------- | ------------------ |
-> | transfer-encoding | `[<<"identity">>]` |
-> | Any other header | `undefined` |
->
-> The parsed value differs depending on the header being parsed. The
-> following table summarizes the different types returned.
->
-> | Header name | Type |
-> | ---------------------- | ------------------------------------------------- |
-> | accept | `[{{Type, SubType, Params}, Quality, AcceptExt}]` |
-> | accept-charset | `[{Charset, Quality}]` |
-> | accept-encoding | `[{Encoding, Quality}]` |
-> | accept-language | `[{LanguageTag, Quality}]` |
-> | authorization | `{AuthType, Credentials}` |
-> | content-length | `non_neg_integer()` |
-> | content-type | `{Type, SubType, ContentTypeParams}` |
-> | cookie | `[{binary(), binary()}]` |
-> | expect | `[Expect | {Expect, ExpectValue, Params}]` |
-> | if-match | `'*' | [{weak | strong, OpaqueTag}]` |
-> | if-modified-since | `calendar:datetime()` |
-> | if-none-match | `'*' | [{weak | strong, OpaqueTag}]` |
-> | if-unmodified-since | `calendar:datetime()` |
-> | range | `{Unit, [Range]}` |
-> | sec-websocket-protocol | `[binary()]` |
-> | transfer-encoding | `[binary()]` |
-> | upgrade | `[binary()]` |
-> | x-forwarded-for | `[binary()]` |
->
-> Types for the above table:
-> * Type = SubType = Charset = Encoding = LanguageTag = binary()
-> * AuthType = Expect = OpaqueTag = Unit = binary()
-> * Params = ContentTypeParams = [{binary(), binary()}]
-> * Quality = 0..1000
-> * AcceptExt = [{binary(), binary()} | binary()]
-> * Credentials - see below
-> * Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer()
->
-> The cookie names and values, the values of the sec-websocket-protocol
-> and x-forwarded-for headers, the values in `AcceptExt` and `Params`,
-> the authorization `Credentials`, the `ExpectValue` and `OpaqueTag`
-> are case sensitive. All values in `ContentTypeParams` are case sensitive
-> except the value of the charset parameter, which is case insensitive.
-> All other values are case insensitive and will be returned as lowercase.
->
-> The headers accept, accept-encoding and cookie headers can return
-> an empty list. Others will return `{error, badarg}` if the header
-> value is empty.
->
-> The authorization header parsing code currently only supports basic
-> HTTP authentication. The `Credentials` type is thus `{Username, Password}`
-> with `Username` and `Password` being `binary()`.
->
-> The range header value `Range` can take three forms:
-> * `{From, To}`: from `From` to `To` units
-> * `{From, infinity}`: everything after `From` units
-> * `-Final`: the final `Final` units
->
-> An `undefined` tuple will be returned if Cowboy doesn't know how
-> to parse the requested header.
-
-### path(Req) -> {Path, Req2}
-
-> Types:
-> * Path = binary()
->
-> Return the requested path.
-
-### path_info(Req) -> {PathInfo, Req2}
-
-> Types:
-> * PathInfo = cowboy_router:tokens() | undefined
->
-> Return the extra tokens from matching against `...` during routing.
-
-### peer(Req) -> {Peer, Req2}
-
-> Types:
-> * Peer = {inet:ip_address(), inet:port_number()}
->
-> Return the client's IP address and port number.
-
-### port(Req) -> {Port, Req2}
-
-> Types:
-> * Port = inet:port_number()
->
-> Return the request's port.
->
-> The port returned by this function is obtained by parsing
-> the host header. It may be different than the actual port
-> the client used to connect to the Cowboy server.
-
-### qs(Req) -> {QueryString, Req2}
-
-> Types:
-> * QueryString = binary()
->
-> Return the request's query string.
-
-### qs_val(Name, Req) -> qs_val(Name, Req, undefined)
-### qs_val(Name, Req, Default) -> {Value, Req2}
-
-> Types:
-> * Name = binary()
-> * Default = any()
-> * Value = binary() | true
->
-> Return a value from the request's query string.
->
-> The value `true` will be returned when the name was found
-> in the query string without an associated value.
-
-### qs_vals(Req) -> {[{Name, Value}], Req2}
-
-> Types:
-> * Name = binary()
-> * Value = binary() | true
->
-> Return the request's query string as a list of tuples.
->
-> The value `true` will be returned when a name was found
-> in the query string without an associated value.
-
-### set_meta(Name, Value, Req) -> Req2
-
-> Types:
-> * Name = atom()
-> * Value = any()
->
-> Set metadata about the request.
->
-> An existing value will be overwritten.
-
-### url(Req) -> {URL, Req2}
-
-> Types:
-> * URL = binary() | undefined
->
-> Return the requested URL.
->
-> This function will always return `undefined` until the
-> `cowboy_router` middleware has been executed. This includes
-> the `onrequest` hook.
-
-### version(Req) -> {Version, Req2}
-
-> Types:
-> * Version = cowboy:http_version()
->
-> Return the HTTP version used for this request.
-
-Request body related exports
-----------------------------
-
-### body(Req) -> body(Req, [])
-### body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2} | {error, Reason}
-
-> Types:
-> * Opts = [body_opt()]
-> * Data = binary()
-> * Reason = atom()
->
-> Read the request body.
->
-> This function will read a chunk of the request body. If there is
-> more data to be read after this function call, then a `more` tuple
-> is returned. Otherwise an `ok` tuple is returned.
->
-> Cowboy will automatically send a `100 Continue` reply if
-> required. If this behavior is not desirable, it can be disabled
-> by setting the `continue` option to `false`.
->
-> Cowboy will by default attempt to read up to 8MB of the body,
-> but in chunks of 1MB. It will use a timeout of 15s per chunk.
-> All these values can be changed using the `length`, `read_length`
-> and `read_timeout` options respectively. Note that the size
-> of the data may not be the same as requested as the decoding
-> functions may grow or shrink it, and Cowboy makes not attempt
-> at returning an exact amount.
->
-> Cowboy will properly handle chunked transfer-encoding by
-> default. If any other transfer-encoding or content-encoding
-> has been used for the request, custom decoding functions
-> can be used. The `content_decode` and `transfer_decode`
-> options allow setting the decode functions manually.
->
-> After the body has been streamed fully, Cowboy will remove
-> the transfer-encoding header from the `Req` object, and add
-> the content-length header if it wasn't already there.
->
-> This function can only be called once. Cowboy will not cache
-> the result of this call.
-
-### body_length(Req) -> {Length, Req2}
-
-> Types:
-> * Length = non_neg_integer() | undefined
->
-> Return the length of the request body.
->
-> The length will only be returned if the request does not
-> use any transfer-encoding and if the content-length header
-> is present.
-
-### body_qs(Req) -> body_qs(Req,
- [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])
-### body_qs(Req, Opts) -> {ok, [{Name, Value}], Req2}
- | {badlength, Req2} | {error, Reason}
-
-> Types:
-> * Opts = [body_opt()]
-> * Name = binary()
-> * Value = binary() | true
-> * Reason = chunked | badlength | atom()
->
-> Return the request body as a list of tuples.
->
-> This function will parse the body assuming the content-type
-> application/x-www-form-urlencoded, commonly used for the
-> query string.
->
-> This function calls `body/2` for reading the body, with the
-> same options it received. By default it will attempt to read
-> a body of 64KB in one chunk, with a timeout of 5s. If the
-> body is larger then a `badlength` tuple is returned.
->
-> This function can only be called once. Cowboy will not cache
-> the result of this call.
-
-### has_body(Req) -> boolean()
-
-> Return whether the request has a body.
-
-### part(Req) -> part(Req,
- [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}])
-### part(Req, Opts) -> {ok, Headers, Req2} | {done, Req2}
-
-> Types:
-> * Opts = [body_opt()]
-> * Headers = cow_multipart:headers()
->
-> Read the headers for the next part of the multipart message.
->
-> Cowboy will skip any data remaining until the beginning of
-> the next part. This includes the preamble to the multipart
-> message but also the body of a previous part if it hasn't
-> been read. Both are skipped automatically when calling this
-> function.
->
-> The headers returned are MIME headers, NOT HTTP headers.
-> They can be parsed using the functions from the `cow_multipart`
-> module. In addition, the `cow_multipart:form_data/1` function
-> can be used to quickly figure out `multipart/form-data` messages.
-> It takes the list of headers and returns whether this part is
-> a simple form field or a file being uploaded.
->
-> Note that once a part has been read, or skipped, it cannot
-> be read again.
->
-> This function calls `body/2` for reading the body, with the
-> same options it received. By default it will only read chunks
-> of 64KB with a timeout of 5s. This is tailored for reading
-> part headers, not for skipping the previous part's body.
-> You might want to consider skipping large parts manually.
-
-### part_body(Req) -> part_body(Req, [])
-### part_body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2}
-
-> Types:
-> * Opts = [body_opt()]
-> * Data = binary()
->
-> Read the body of the current part of the multipart message.
->
-> This function calls `body/2` for reading the body, with the
-> same options it received. It uses the same defaults.
->
-> If there are more data to be read from the socket for this
-> part, the function will return what it could read inside a
-> `more` tuple. Otherwise, it will return an `ok` tuple.
->
-> Calling this function again after receiving a `more` tuple
-> will return another chunk of body. The last chunk will be
-> returned inside an `ok` tuple.
->
-> Note that once the body has been read, fully or partially,
-> it cannot be read again.
-
-Response related exports
-------------------------
-
-### chunk(Data, Req) -> ok | {error, Reason}
-
-> Types:
-> * Data = iodata()
-> * Reason = atom()
->
-> Send a chunk of data.
->
-> This function should be called as many times as needed
-> to send data chunks after calling `chunked_reply/{2,3}`.
->
-> When the method is HEAD, no data will actually be sent.
->
-> If the request uses HTTP/1.0, the data is sent directly
-> without wrapping it in an HTTP/1.1 chunk, providing
-> compatibility with older clients.
-
-### chunked_reply(StatusCode, Req) -> chunked_reply(StatusCode, [], Req)
-### chunked_reply(StatusCode, Headers, Req) -> {ok, Req2}
-
-> Types:
-> * StatusCode = cowboy:http_status()
-> * Headers = cowboy:http_headers()
->
-> Send a response using chunked transfer-encoding.
->
-> This function effectively sends the response status line
-> and headers to the client.
->
-> This function will not send any body set previously. After
-> this call the handler must use the `chunk/2` function
-> repeatedly to send the body in as many chunks as needed.
->
-> If the request uses HTTP/1.0, the data is sent directly
-> without wrapping it in an HTTP/1.1 chunk, providing
-> compatibility with older clients.
->
-> This function can only be called once, with the exception
-> of overriding the response in the `onresponse` hook.
-
-### continue(Req) -> ok | {error, Reason}
-
-> Types:
-> * Reason = atom()
->
-> Send a 100 Continue intermediate reply.
->
-> This reply is required before the client starts sending the
-> body when the request contains the `expect` header with the
-> `100-continue` value.
->
-> Cowboy will send this automatically when required. However
-> you may want to do it manually by disabling this behavior
-> with the `continue` body option and then calling this
-> function.
-
-### delete_resp_header(Name, Req) -> Req2
-
-> Types:
-> * Name = binary()
->
-> Delete the given response header.
->
-> While header names are case insensitive, this function expects
-> the name to be a lowercase binary.
-
-### has_resp_body(Req) -> boolean()
-
-> Return whether a response body has been set.
->
-> This function will return false if a response body has
-> been set with a length of 0.
-
-### has_resp_header(Name, Req) -> boolean()
-
-> Types:
-> * Name = binary()
->
-> Return whether the given response header has been set.
->
-> While header names are case insensitive, this function expects
-> the name to be a lowercase binary.
-
-### reply(StatusCode, Req) -> reply(StatusCode, [], Req)
-### reply(StatusCode, Headers, Req) - see below
-### reply(StatusCode, Headers, Body, Req) -> {ok, Req2}
-
-> Types:
-> * StatusCode = cowboy:http_status()
-> * Headers = cowboy:http_headers()
-> * Body = iodata()
->
-> Send a response.
->
-> This function effectively sends the response status line,
-> headers and body to the client, in a single send function
-> call.
->
-> The `reply/2` and `reply/3` functions will send the body
-> set previously, if any. The `reply/4` function overrides
-> any body set previously and sends `Body` instead.
->
-> If a body function was set, and `reply/2` or `reply/3` was
-> used, it will be called before returning.
->
-> No more data can be sent to the client after this function
-> returns.
->
-> This function can only be called once, with the exception
-> of overriding the response in the `onresponse` hook.
-
-### set_resp_body(Body, Req) -> Req2
-
-> Types:
-> * Body = iodata()
->
-> Set a response body.
->
-> This body will not be sent if `chunked_reply/{2,3}` or
-> `reply/4` is used, as they override it.
-
-### set_resp_body_fun(Fun, Req) -> Req2
-### set_resp_body_fun(Length, Fun, Req) -> Req2
-
-> Types:
-> * Fun = fun((Socket, Transport) -> ok)
-> * Socket = inet:socket()
-> * Transport = module()
-> * Length = non_neg_integer()
->
-> Set a fun for sending the response body.
->
-> If a `Length` is provided, it will be sent in the
-> content-length header in the response. It is recommended
-> to set the length if it can be known in advance. Otherwise,
-> the transfer-encoding header will be set to identity.
->
-> This function will only be called if the response is sent
-> using the `reply/2` or `reply/3` function.
->
-> The fun will receive the Ranch `Socket` and `Transport` as
-> arguments. Only send and sendfile operations are supported.
-
-### set_resp_body_fun(chunked, Fun, Req) -> Req2
-
-> Types:
-> * Fun = fun((ChunkFun) -> ok)
-> * ChunkFun = fun((iodata()) -> ok | {error, atom()})
->
-> Set a fun for sending the response body using chunked transfer-encoding.
->
-> This function will only be called if the response is sent
-> using the `reply/2` or `reply/3` function.
->
-> The fun will receive another fun as argument. This fun is to
-> be used to send chunks in a similar way to the `chunk/2` function,
-> except the fun only takes one argument, the data to be sent in
-> the chunk.
-
-### set_resp_cookie(Name, Value, Opts, Req) -> Req2
-
-> Types:
-> * Name = iodata()
-> * Value = iodata()
-> * Opts = cookie_opts()
->
-> Set a cookie in the response.
->
-> Cookie names are case sensitive.
-
-### set_resp_header(Name, Value, Req) -> Req2
-
-> Types:
-> * Name = binary()
-> * Value = iodata()
->
-> Set a response header.
->
-> You should use `set_resp_cookie/4` instead of this function
-> to set cookies.
-
-Misc. exports
--------------
-
-### compact(Req) -> Req2
-
-> Remove any non-essential data from the `Req` object.
->
-> Long-lived connections usually only need to manipulate the
-> `Req` object at initialization. Compacting allows saving up
-> memory by discarding extraneous information.
diff --git a/manual/cowboy_rest.md b/manual/cowboy_rest.md
deleted file mode 100644
index a2abf3a..0000000
--- a/manual/cowboy_rest.md
+++ /dev/null
@@ -1,560 +0,0 @@
-cowboy_rest
-===========
-
-The `cowboy_rest` module implements REST semantics on top of
-the HTTP protocol.
-
-This module cannot be described as a behaviour due to most of
-the callbacks it defines being optional. It has the same
-semantics as a behaviour otherwise.
-
-The only mandatory callback is `init/3`, needed to perform
-the protocol upgrade.
-
-Types
------
-
-None.
-
-Meta values
------------
-
-### charset
-
-> Type: binary()
->
-> Negotiated charset.
->
-> This value may not be defined if no charset was negotiated.
-
-### language
-
-> Type: binary()
->
-> Negotiated language.
->
-> This value may not be defined if no language was negotiated.
-
-### media_type
-
-> Type: {binary(), binary(), '*' | [{binary(), binary()}]}
->
-> Negotiated media-type.
->
-> The media-type is the content-type, excluding the charset.
->
-> This value is always defined after the call to
-> `content_types_provided/2`.
-
-Callbacks
----------
-
-### init({TransportName, ProtocolName}, Req, Opts)
- -> {upgrade, protocol, cowboy_rest}
- | {upgrade, protocol, cowboy_rest, Req, Opts}
-
-> Types:
-> * TransportName = tcp | ssl | atom()
-> * ProtocolName = http | atom()
-> * Req = cowboy_req:req()
-> * Opts = any()
->
-> Upgrade the protocol to `cowboy_rest`.
->
-> This is the only mandatory callback.
-
-### rest_init(Req, Opts) -> {ok, Req, State}
-
-> Types:
-> * Req = cowboy_req:req()
-> * Opts = any()
-> * State = any()
->
-> Initialize the state for this request.
-
-### rest_terminate(Req, State) -> ok
-
-> Types:
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Perform any necessary cleanup of the state.
->
-> This callback should release any resource currently in use,
-> clear any active timer and reset the process to its original
-> state, as it might be reused for future requests sent on the
-> same connection.
-
-### Callback(Req, State) -> {Value, Req, State} | {halt, Req, State}
-
-> Types:
-> * Callback - one of the REST callbacks described below
-> * Req = cowboy_req:req()
-> * State = any()
-> * Value - see the REST callbacks description below
->
-> Please see the REST callbacks description below for details
-> on the `Value` type, the default value if the callback is
-> not defined, and more general information on when the
-> callback is called and what its intended use is.
->
-> The `halt` tuple can be returned to stop REST processing.
-> It is up to the resource code to send a reply before that,
-> otherwise a `204 No Content` will be sent.
-
-REST callbacks description
---------------------------
-
-### allowed_methods
-
-> * Methods: all
-> * Value type: [binary()]
-> * Default value: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
->
-> Return the list of allowed methods.
->
-> Methods are case sensitive. Standard methods are always uppercase.
-
-### allow_missing_post
-
-> * Methods: POST
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether POST is allowed when the resource doesn't exist.
->
-> Returning `true` here means that a new resource will be
-> created. The URL to the created resource should also be
-> returned from the `AcceptResource` callback.
-
-### charsets_provided
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: [binary()]
-> * Skip to the next step if undefined
->
-> Return the list of charsets the resource provides.
->
-> The list must be ordered in order of preference.
->
-> If the accept-charset header was not sent, the first charset
-> in the list will be selected. Otherwise Cowboy will select
-> the most appropriate charset from the list.
->
-> The chosen charset will be set in the `Req` object as the meta
-> value `charset`.
->
-> While charsets are case insensitive, this callback is expected
-> to return them as lowercase binary.
-
-### content_types_accepted
-
-> * Methods: POST, PUT, PATCH
-> * No default
->
-> Types:
-> * Value = [{binary() | {Type, SubType, Params}, AcceptResource}]
-> * Type = SubType = binary()
-> * Params = '*' | [{binary(), binary()}]
-> * AcceptResource = atom()
->
-> Return the list of content-types the resource accepts.
->
-> The list must be ordered in order of preference.
->
-> Each content-type can be given either as a binary string or as
-> a tuple containing the type, subtype and parameters.
->
-> Cowboy will select the most appropriate content-type from the list.
-> If any parameter is acceptable, then the tuple form should be used
-> with parameters set to `'*'`. If the parameters value is set to `[]`
-> only content-type values with no parameters will be accepted. All
-> parameter values are treated in a case sensitive manner except the
-> `charset` parameter, if present, which is case insensitive.
->
-> This function will be called for POST, PUT and PATCH requests.
-> It is entirely possible to define different callbacks for different
-> methods if the handling of the request differs. Simply verify
-> what the method is with `cowboy_req:method/1` and return a
-> different list for each methods.
->
-> The `AcceptResource` value is the name of the callback that will
-> be called if the content-type matches. It is defined as follow.
->
-> * Value type: true | {true, URL} | false
-> * No default
->
-> Process the request body.
->
-> This function should create or update the resource with the
-> information contained in the request body. This information
-> may be full or partial depending on the request method.
->
-> If the request body was processed successfully, `true` or
-> `{true, URL}` may be returned. If an URL is provided, the
-> response will redirect the client to the location of the
-> resource.
->
-> If a response body must be sent, the appropriate media-type, charset
-> and language can be retrieved using the `cowboy_req:meta/{2,3}`
-> functions. The respective keys are `media_type`, `charset`
-> and `language`. The body can be set using `cowboy_req:set_resp_body/2`.
-
-### content_types_provided
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
->
-> Types:
-> * Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
-> * Type = SubType = binary()
-> * Params = '*' | [{binary(), binary()}]
-> * ProvideResource = atom()
->
-> Return the list of content-types the resource provides.
->
-> The list must be ordered in order of preference.
->
-> Each content-type can be given either as a binary string or as
-> a tuple containing the type, subtype and parameters.
->
-> Cowboy will select the most appropriate content-type from the list.
-> If any parameter is acceptable, then the tuple form should be used
-> with parameters set to `'*'`. If the parameters value is set to `[]`
-> only content-type values with no parameters will be accepted. All
-> parameter values are treated in a case sensitive manner except the
-> `charset` parameter, if present, which is case insensitive.
->
-> The `ProvideResource` value is the name of the callback that will
-> be called if the content-type matches. It will only be called when
-> a representation of the resource needs to be returned. It is defined
-> as follow.
->
-> * Methods: GET, HEAD
-> * Value type: iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
-> * No default
->
-> Return the response body.
->
-> The response body may be provided directly or through a fun.
-> If a fun tuple is returned, the appropriate `set_resp_body_fun`
-> function will be called. Please refer to the documentation for
-> these functions for more information about the types.
->
-> The call to this callback happens a good time after the call to
-> `content_types_provided/2`, when it is time to start rendering
-> the response body.
-
-### delete_completed
-
-> * Methods: DELETE
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the delete action has been completed.
->
-> This function should return `false` if there is no guarantee
-> that the resource gets deleted immediately from the system,
-> including from any internal cache.
->
-> When this function returns `false`, a `202 Accepted`
-> response will be sent instead of a `200 OK` or `204 No Content`.
-
-### delete_resource
-
-> * Methods: DELETE
-> * Value type: boolean()
-> * Default value: false
->
-> Delete the resource.
->
-> The value returned indicates if the action was successful,
-> regardless of whether the resource is immediately deleted
-> from the system.
-
-### expires
-
-> * Methods: GET, HEAD
-> * Value type: calendar:datetime() | binary() | undefined
-> * Default value: undefined
->
-> Return the date of expiration of the resource.
->
-> This date will be sent as the value of the expires header.
-
-### forbidden
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether access to the resource is forbidden.
->
-> A `403 Forbidden` response will be sent if this
-> function returns `true`. This status code means that
-> access is forbidden regardless of authentication,
-> and that the request shouldn't be repeated.
-
-### generate_etag
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: binary() | {weak | strong, binary()}
-> * Default value: undefined
->
-> Return the entity tag of the resource.
->
-> This value will be sent as the value of the etag header.
->
-> If a binary is returned, then the value will be parsed
-> to the tuple form automatically. The value must be in
-> the same format as the etag header, including quotes.
-
-### is_authorized
-
-> * Methods: all
-> * Value type: true | {false, AuthHeader}
-> * Default value: true
->
-> Return whether the user is authorized to perform the action.
->
-> This function should be used to perform any necessary
-> authentication of the user before attempting to perform
-> any action on the resource.
->
-> If the authentication fails, the value returned will be sent
-> as the value for the www-authenticate header in the
-> `401 Unauthorized` response.
-
-### is_conflict
-
-> * Methods: PUT
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether the put action results in a conflict.
->
-> A `409 Conflict` response will be sent if this function
-> returns `true`.
-
-### known_content_type
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the content-type is known.
->
-> This function determines if the server understands the
-> content-type, regardless of its use by the resource.
-
-### known_methods
-
-> * Methods: all
-> * Value type: [binary()]
-> * Default value: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
->
-> Return the list of known methods.
->
-> The full list of methods known by the server should be
-> returned, regardless of their use in the resource.
->
-> The default value lists the methods Cowboy knows and
-> implement in `cowboy_rest`.
->
-> Methods are case sensitive. Standard methods are always uppercase.
-
-### languages_provided
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: [binary()]
-> * Skip to the next step if undefined
->
-> Return the list of languages the resource provides.
->
-> The list must be ordered in order of preference.
->
-> If the accept-language header was not sent, the first language
-> in the list will be selected. Otherwise Cowboy will select
-> the most appropriate language from the list.
->
-> The chosen language will be set in the `Req` object as the meta
-> value `language`.
->
-> While languages are case insensitive, this callback is expected
-> to return them as lowercase binary.
-
-### last_modified
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: calendar:datetime()
-> * Default value: undefined
->
-> Return the date of last modification of the resource.
->
-> This date will be used to test against the if-modified-since
-> and if-unmodified-since headers, and sent as the last-modified
-> header in the response of GET and HEAD requests.
-
-### malformed_request
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether the request is malformed.
->
-> Cowboy has already performed all the necessary checks
-> by the time this function is called, so few resources
-> are expected to implement it.
->
-> The check is to be done on the request itself, not on
-> the request body, which is processed later.
-
-### moved_permanently
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: {true, URL} | false
-> * Default value: false
->
-> Return whether the resource was permanently moved.
->
-> If it was, its new URL is also returned and sent in the
-> location header in the response.
-
-### moved_temporarily
-
-> * Methods: GET, HEAD, POST, PATCH, DELETE
-> * Value type: {true, URL} | false
-> * Default value: false
->
-> Return whether the resource was temporarily moved.
->
-> If it was, its new URL is also returned and sent in the
-> location header in the response.
-
-### multiple_choices
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether there are multiple representations of the resource.
->
-> This function should be used to inform the client if there
-> are different representations of the resource, for example
-> different content-type. If this function returns `true`,
-> the response body should include information about these
-> different representations using `cowboy_req:set_resp_body/2`.
-> The content-type of the response should be the one previously
-> negociated and that can be obtained by calling
-> `cowboy_req:meta(media_type, Req)`.
-
-### options
-
-> * Methods: OPTIONS
-> * Value type: ok
-> * Default value: ok
->
-> Handle a request for information.
->
-> The response should inform the client the communication
-> options available for this resource.
->
-> By default, Cowboy will send a `200 OK` response with the
-> allow header set.
-
-### previously_existed
-
-> * Methods: GET, HEAD, POST, PATCH, DELETE
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether the resource existed previously.
-
-### resource_exists
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the resource exists.
->
-> If it exists, conditional headers will be tested before
-> attempting to perform the action. Otherwise, Cowboy will
-> check if the resource previously existed first.
-
-### service_available
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the service is available.
->
-> This function can be used to test that all relevant backend
-> systems are up and able to handle requests.
->
-> A `503 Service Unavailable` response will be sent if this
-> function returns `false`.
-
-### uri_too_long
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: false
->
-> Return whether the requested URI is too long.
->
-> Cowboy has already performed all the necessary checks
-> by the time this function is called, so few resources
-> are expected to implement it.
->
-> A `414 Request-URI Too Long` response will be sent if this
-> function returns `true`.
-
-### valid_content_headers
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the content-* headers are valid.
->
-> This also applies to the transfer-encoding header. This
-> function must return `false` for any unknown content-*
-> headers, or if the headers can't be understood. The
-> function `cowboy_req:parse_header/2` can be used to
-> quickly check the headers can be parsed.
->
-> A `501 Not Implemented` response will be sent if this
-> function returns `false`.
-
-### valid_entity_length
-
-> * Methods: all
-> * Value type: boolean()
-> * Default value: true
->
-> Return whether the request body length is within acceptable boundaries.
->
-> A `413 Request Entity Too Large` response will be sent if this
-> function returns `false`.
-
-### variances
-
-> * Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-> * Value type: [binary()]
-> * Default value: []
->
-> Return the list of headers that affect the representation of the resource.
->
-> These request headers return the same resource but with different
-> parameters, like another language or a different content-type.
->
-> Cowboy will automatically add the accept, accept-language and
-> accept-charset headers to the list if the respective functions
-> were defined in the resource.
->
-> This operation is performed right before the `resource_exists/2`
-> callback. All responses past that point will contain the vary
-> header which holds this list.
diff --git a/manual/cowboy_router.md b/manual/cowboy_router.md
deleted file mode 100644
index 1c6dc04..0000000
--- a/manual/cowboy_router.md
+++ /dev/null
@@ -1,68 +0,0 @@
-cowboy_router
-=============
-
-The `cowboy_router` middleware maps the requested host and
-path to the handler to be used for processing the request.
-It uses the dispatch rules compiled from the routes given
-to the `compile/1` function for this purpose. It adds the
-handler name and options to the environment as the values
-`handler` and `handler_opts` respectively.
-
-Environment input:
- * dispatch = dispatch_rules()
-
-Environment output:
- * handler = module()
- * handler_opts = any()
-
-Types
------
-
-### bindings() = [{atom(), binary()}]
-
-> List of bindings found during routing.
-
-### constraints() = [IntConstraint | FunConstraint]
-
-> Types:
-> * IntConstraint = {atom(), int}
-> * FunConstraint = {atom(), function, Fun}
-> * Fun = fun((binary()) -> true | {true, any()} | false)
->
-> List of constraints to apply to the bindings.
->
-> The int constraint will convert the binding to an integer.
-> The fun constraint allows writing custom code for checking
-> the bindings. Returning a new value from that fun allows
-> replacing the current binding with a new value.
-
-### dispatch_rules() - opaque to the user
-
-> Rules for dispatching request used by Cowboy.
-
-### routes() = [{Host, Paths} | {Host, constraints(), Paths}]
-
-> Types:
-> * Host = Path = '_' | iodata()
-> * Paths = [{Path, Handler, Opts} | {Path, constraints(), Handler, Opts}]
-> * Handler = module()
-> * Opts = any()
->
-> Human readable list of routes mapping hosts and paths to handlers.
->
-> The syntax for routes is defined in the user guide.
-
-### tokens() = [binary()]
-
-> List of host_info and path_info tokens found during routing.
-
-Exports
--------
-
-### compile(Routes) -> Dispatch
-
-> Types:
-> * Routes = routes()
-> * Dispatch = dispatch_rules()
->
-> Compile the routes for use by Cowboy.
diff --git a/manual/cowboy_spdy.md b/manual/cowboy_spdy.md
deleted file mode 100644
index 527dbb1..0000000
--- a/manual/cowboy_spdy.md
+++ /dev/null
@@ -1,40 +0,0 @@
-cowboy_spdy
-===========
-
-The `cowboy_spdy` module implements SPDY/3 as a Ranch protocol.
-
-Types
------
-
-### opts() = [{env, cowboy_middleware:env()}
- | {middlewares, [module()]}
- | {onrequest, cowboy:onrequest_fun()}
- | {onresponse, cowboy:onresponse_fun()}]
-
-> Configuration for the SPDY protocol handler.
->
-> This configuration is passed to Cowboy when starting listeners
-> using the `cowboy:start_spdy/4` function.
->
-> It can be updated without restarting listeners using the
-> Ranch functions `ranch:get_protocol_options/1` and
-> `ranch:set_protocol_options/2`.
-
-Option descriptions
--------------------
-
-The default value is given next to the option name.
-
- - env ([{listener, Ref}])
- - Initial middleware environment.
- - middlewares ([cowboy_router, cowboy_handler])
- - List of middlewares to execute for every requests.
- - onrequest (undefined)
- - Fun called every time a request is received.
- - onresponse (undefined)
- - Fun called every time a response is sent.
-
-Exports
--------
-
-None.
diff --git a/manual/cowboy_static.md b/manual/cowboy_static.md
deleted file mode 100644
index 01aa2bf..0000000
--- a/manual/cowboy_static.md
+++ /dev/null
@@ -1,34 +0,0 @@
-cowboy_static
-=============
-
-The `cowboy_static` module implements file serving capabilities
-by using the REST semantics provided by `cowboy_rest`.
-
-Types
------
-
-### opts() = {priv_file, atom(), string() | binary()}
- | {priv_file, atom(), string() | binary(), extra()}
- | {file, string() | binary()}
- | {file, string() | binary(), extra()}
- | {priv_dir, atom(), string() | binary()}
- | {priv_dir, atom(), string() | binary(), extra()}
- | {dir, atom(), string() | binary()}
- | {dir, atom(), string() | binary(), extra()}
-
-> Configuration for the static handler.
->
-> The handler can be configured for sending either one file or
-> a directory (including its subdirectories).
->
-> Extra options allow you to define how the etag should be calculated
-> and how the mimetype of files should be detected. They are defined
-> as follow, but do note that these types are not exported, only the
-> `opts/0` type is public.
-
-### extra() = [extra_etag() | extra_mimetypes()]
-
-### extra_etag() = {etag, module(), function()} | {etag, false}
-
-### extra_mimetypes() = {mimetypes, module(), function()}
- | {mimetypes, binary() | {binary(), binary(), [{binary(), binary()}]}}
diff --git a/manual/cowboy_sub_protocol.md b/manual/cowboy_sub_protocol.md
deleted file mode 100644
index a8ecae1..0000000
--- a/manual/cowboy_sub_protocol.md
+++ /dev/null
@@ -1,34 +0,0 @@
-cowboy_sub_protocol
-===================
-
-The `cowboy_sub_protocol` behaviour defines the interface used
-by modules that implement a protocol on top of HTTP.
-
-Types
------
-
-None.
-
-Callbacks
----------
-
-### upgrade(Req, Env, Handler, Opts)
- -> {ok, Req, Env}
- | {suspend, Module, Function, Args}
- | {halt, Req}
- | {error, StatusCode, Req}
-
-> Types:
-> * Req = cowboy_req:req()
-> * Env = env()
-> * Handler = module()
-> * Opts = any()
-> * Module = module()
-> * Function = atom()
-> * Args = [any()]
-> * StatusCode = cowboy:http_status()
->
-> Upgrade the protocol.
->
-> Please refer to the `cowboy_middleware` manual for a
-> description of the return values.
diff --git a/manual/cowboy_websocket.md b/manual/cowboy_websocket.md
deleted file mode 100644
index 9a81878..0000000
--- a/manual/cowboy_websocket.md
+++ /dev/null
@@ -1,40 +0,0 @@
-cowboy_websocket
-================
-
-The `cowboy_websocket` module implements the Websocket protocol.
-
-The callbacks for websocket handlers are defined in the manual
-for the `cowboy_websocket_handler` behaviour.
-
-Types
------
-
-### close_code() = 1000..4999
-
-> Reason for closing the connection.
-
-### frame() = close | ping | pong
- | {text | binary | close | ping | pong, iodata()}
- | {close, close_code(), iodata()}
-
-> Frames that can be sent to the client.
-
-Meta values
------------
-
-### websocket_compress
-
-> Type: true | false
->
-> Whether a websocket compression extension in in use.
-
-### websocket_version
-
-> Type: 7 | 8 | 13
->
-> The version of the Websocket protocol being used.
-
-Exports
--------
-
-None.
diff --git a/manual/cowboy_websocket_handler.md b/manual/cowboy_websocket_handler.md
deleted file mode 100644
index f0480b1..0000000
--- a/manual/cowboy_websocket_handler.md
+++ /dev/null
@@ -1,131 +0,0 @@
-cowboy_websocket_handler
-========================
-
-The `cowboy_websocket_handler` behaviour defines the interface used
-by Websocket handlers.
-
-The `init/3` and `websocket_init/3` callbacks will always be called,
-followed by zero or more calls to `websocket_handle/3` and
-`websocket_info/3`. The `websocket_terminate/3` will always
-be called last.
-
-Types
------
-
-None.
-
-Callbacks
----------
-
-### init({TransportName, ProtocolName}, Req, Opts)
- -> {upgrade, protocol, cowboy_websocket}
- | {upgrade, protocol, cowboy_websocket, Req, Opts}
-
-> Types:
-> * TransportName = tcp | ssl | atom()
-> * ProtocolName = http | atom()
-> * Req = cowboy_req:req()
-> * Opts = any()
->
-> Upgrade the protocol to `cowboy_websocket`.
-
-### websocket_init(TransportName, Req, Opts)
- -> {ok, Req, State}
- | {ok, Req, State, hibernate}
- | {ok, Req, State, Timeout}
- | {ok, Req, State, Timeout, hibernate}
- | {shutdown, Req}
-
-> Types:
-> * TransportName = tcp | ssl | atom()
-> * Req = cowboy_req:req()
-> * Opts = any()
-> * State = any()
-> * Timeout = timeout()
->
-> Initialize the state for this session.
->
-> This function is called before the upgrade to Websocket occurs.
-> It can be used to negotiate Websocket protocol extensions
-> with the client. It will typically be used to register this process
-> to an event manager or a message queue in order to receive
-> the messages the handler wants to process.
->
-> The connection will stay up for a duration of up to `Timeout`
-> milliseconds after it last received data from the socket,
-> at which point it will stop and close the connection.
-> By default this value is set to `infinity`. It is recommended
-> to either set this value or ensure by any other mechanism
-> that the handler will be closed after a certain period of
-> inactivity.
->
-> The `hibernate` option will hibernate the process until it
-> starts receiving either data from the Websocket connection
-> or Erlang messages.
->
-> The `shutdown` return value can be used to close the connection
-> before upgrading to Websocket.
-
-### websocket_handle(InFrame, Req, State)
- -> {ok, Req, State}
- | {ok, Req, State, hibernate}
- | {reply, OutFrame | [OutFrame], Req, State}
- | {reply, OutFrame | [OutFrame], Req, State, hibernate}
- | {shutdown, Req, State}
-
-> Types:
-> * InFrame = {text | binary | ping | pong, binary()}
-> * Req = cowboy_req:req()
-> * State = any()
-> * OutFrame = cowboy_websocket:frame()
->
-> Handle the data received from the Websocket connection.
->
-> This function will be called every time data is received
-> from the Websocket connection.
->
-> The `shutdown` return value can be used to close the
-> connection. A close reply will also result in the connection
-> being closed.
->
-> The `hibernate` option will hibernate the process until
-> it receives new data from the Websocket connection or an
-> Erlang message.
-
-### websocket_info(Info, Req, State)
- -> {ok, Req, State}
- | {ok, Req, State, hibernate}
- | {reply, OutFrame | [OutFrame], Req, State}
- | {reply, OutFrame | [OutFrame], Req, State, hibernate}
- | {shutdown, Req, State}
-
-> Types:
-> * Info = any()
-> * Req = cowboy_req:req()
-> * State = any()
-> * OutFrame = cowboy_websocket:frame()
->
-> Handle the Erlang message received.
->
-> This function will be called every time an Erlang message
-> has been received. The message can be any Erlang term.
->
-> The `shutdown` return value can be used to close the
-> connection. A close reply will also result in the connection
-> being closed.
->
-> The `hibernate` option will hibernate the process until
-> it receives another message or new data from the Websocket
-> connection.
-
-### websocket_terminate(Reason, Req, State) -> ok
-
-> Types:
-> * Reason = {normal, shutdown | timeout} | {remote, closed} | {remote, cowboy_websocket:close_code(), binary()} | {error, badencoding | badframe | closed | atom()}
-> * Req = cowboy_req:req()
-> * State = any()
->
-> Perform any necessary cleanup of the state.
->
-> The connection will be closed and the process stopped right
-> after this call.
diff --git a/manual/http_status_codes.md b/manual/http_status_codes.md
deleted file mode 100644
index 070dce8..0000000
--- a/manual/http_status_codes.md
+++ /dev/null
@@ -1,180 +0,0 @@
-HTTP status codes
-=================
-
-This chapter aims to list all HTTP status codes that Cowboy
-may return, with details on the reasons why. The list given
-here only includes the replies that Cowboy sends, not user
-replies.
-
-100 Continue
-------------
-
-When the client sends an `expect: 100-continue` header,
-Cowboy automatically sends a this status code before
-trying to read the request body. This behavior can be
-disabled using the appropriate body option.
-
-101 Switching Protocols
------------------------
-
-This is the status code sent when switching to the
-Websocket protocol.
-
-200 OK
-------
-
-This status code is sent by `cowboy_rest`.
-
-201 Created
------------
-
-This status code is sent by `cowboy_rest`.
-
-202 Accepted
-------------
-
-This status code is sent by `cowboy_rest`.
-
-204 No Content
---------------
-
-This status code is sent when the processing of a request
-ends without any reply having been sent. It may also be
-sent by `cowboy_rest` under normal conditions.
-
-300 Multiple Choices
---------------------
-
-This status code is sent by `cowboy_rest`.
-
-301 Moved Permanently
----------------------
-
-This status code is sent by `cowboy_rest`.
-
-303 See Other
--------------
-
-This status code is sent by `cowboy_rest`.
-
-304 Not Modified
-----------------
-
-This status code is sent by `cowboy_rest`.
-
-307 Temporary Redirect
-----------------------
-
-This status code is sent by `cowboy_rest`.
-
-400 Bad Request
----------------
-
-Cowboy will send this status code for any of the
-following reasons:
-
-* Too many empty lines were sent before the request.
-* The request-line could not be parsed.
-* Too many headers were sent.
-* A header name was too long.
-* A header value was too long.
-* The host header was missing from an HTTP/1.1 request.
-* The host header could not be parsed.
-* The requested host was not found.
-* The requested path could not be parsed.
-* The accept header could not be parsed when using REST.
-* REST under normal conditions.
-* A Websocket upgrade failed.
-
-401 Unauthorized
-----------------
-
-This status code is sent by `cowboy_rest`.
-
-403 Forbidden
--------------
-
-This status code is sent by `cowboy_rest`.
-
-404 Not Found
--------------
-
-This status code is sent when the router successfully
-resolved the host but didn't find a matching path for
-the request. It may also be sent by `cowboy_rest` under
-normal conditions.
-
-405 Method Not Allowed
-----------------------
-
-This status code is sent by `cowboy_rest`.
-
-406 Not Acceptable
-------------------
-
-This status code is sent by `cowboy_rest`.
-
-408 Request Timeout
--------------------
-
-Cowboy will send this status code to the client if the
-client started to send a request, indicated by the
-request-line being received fully, but failed to send
-all headers in a reasonable time.
-
-409 Conflict
-------------
-
-This status code is sent by `cowboy_rest`.
-
-410 Gone
---------
-
-This status code is sent by `cowboy_rest`.
-
-412 Precondition Failed
------------------------
-
-This status code is sent by `cowboy_rest`.
-
-413 Request Entity Too Large
-----------------------------
-
-This status code is sent by `cowboy_rest`.
-
-414 Request-URI Too Long
-------------------------
-
-Cowboy will send this status code to the client if the
-request-line is too long. It may also be sent by
-`cowboy_rest` under normal conditions.
-
-415 Unsupported Media Type
---------------------------
-
-This status code is sent by `cowboy_rest`.
-
-500 Internal Server Error
--------------------------
-
-This status code is sent when a crash occurs in HTTP, loop
-or REST handlers, or when an invalid return value is
-returned. It may also be sent by `cowboy_rest` under
-normal conditions.
-
-501 Not Implemented
--------------------
-
-This status code is sent by `cowboy_rest`.
-
-503 Service Unavailable
------------------------
-
-This status code is sent by `cowboy_rest`.
-
-505 HTTP Version Not Supported
-------------------------------
-
-Cowboy only supports the versions 1.0 and 1.1 of HTTP.
-In all other cases this status code is sent back to the
-client and the connection is closed.
diff --git a/manual/toc.md b/manual/toc.md
deleted file mode 100644
index 165470e..0000000
--- a/manual/toc.md
+++ /dev/null
@@ -1,21 +0,0 @@
-Cowboy Function Reference
-=========================
-
-The function reference documents the public interface of Cowboy.
-
- * [The Cowboy Application](cowboy_app.md)
- * [cowboy](cowboy.md)
- * [cowboy_handler](cowboy_handler.md)
- * [cowboy_http_handler](cowboy_http_handler.md)
- * [cowboy_loop_handler](cowboy_loop_handler.md)
- * [cowboy_middleware](cowboy_middleware.md)
- * [cowboy_protocol](cowboy_protocol.md)
- * [cowboy_req](cowboy_req.md)
- * [cowboy_rest](cowboy_rest.md)
- * [cowboy_router](cowboy_router.md)
- * [cowboy_spdy](cowboy_spdy.md)
- * [cowboy_static](cowboy_static.md)
- * [cowboy_sub_protocol](cowboy_sub_protocol.md)
- * [cowboy_websocket](cowboy_websocket.md)
- * [cowboy_websocket_handler](cowboy_websocket_handler.md)
- * [HTTP status codes](http_status_codes.md)