Add the Cowboy Function Reference

The manual details every stable public functions of Cowboy.

1 files changed, 549 insertions, 0 deletions

diff --git a/manual/cowboy_rest.md b/manual/cowboy_rest.md
new file mode 100644
index 0000000..b7890e4
--- /dev/null
+++ b/manual/cowboy_rest.md
@@ -0,0 +1,549 @@
+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.
+>
+> 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
+>  *  Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
+>
+> Types:
+>  *  Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
+>  *  Type = SubType = binary()
+>  *  Params = '*' | [{binary(), binary()}]
+>  *  AcceptResource = 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.
+>
+> The `ProvideResource` value is the name of the callback that will
+> be called if the content-type matches. It is defined as follow.
+>
+>  *  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() | 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()
+>  *  Default value: undefined
+>
+> Return the entity tag of the resource.
+>
+> This value will be sent as the value of the etag header.
+
+### 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.