aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2014-09-23 16:43:29 +0300
committerLoïc Hoguin <[email protected]>2014-09-23 16:43:29 +0300
commitf1c3b6d76f0c97e1ab927c288bb94891ae4c253b (patch)
tree5a14c007cdcb487032162b3ca96df648f521321a /doc/src/manual
parentb57f94661f5fd186f55eb0fead49849e0b1399d1 (diff)
downloadcowboy-f1c3b6d76f0c97e1ab927c288bb94891ae4c253b.tar.gz
cowboy-f1c3b6d76f0c97e1ab927c288bb94891ae4c253b.tar.bz2
cowboy-f1c3b6d76f0c97e1ab927c288bb94891ae4c253b.zip
Breaking update of the cowboy_req interface
Simplify the interface for most cowboy_req functions. They all return a single value except the four body reading functions. The reply functions now only return a Req value. Access functions do not return a Req anymore. Functions that used to cache results do not have a cache anymore. The interface for accessing query string and cookies has therefore been changed. There are now three query string functions: qs/1 provides access to the raw query string value; parse_qs/1 returns the query string as a list of key/values; match_qs/2 returns a map containing the values requested in the second argument, after applying constraints and default value. Similarly, there are two cookie functions: parse_cookies/1 and match_cookies/2. More match functions will be added in future commits. None of the functions return an error tuple anymore. It either works or crashes. Cowboy will attempt to provide an appropriate status code in the response of crashed handlers. As a result, the content decode function has its return value changed to a simple binary, and the body reading functions only return on success.
Diffstat (limited to 'doc/src/manual')
-rw-r--r--doc/src/manual/cowboy.ezdoc6
-rw-r--r--doc/src/manual/cowboy_req.ezdoc195
2 files changed, 115 insertions, 86 deletions
diff --git a/doc/src/manual/cowboy.ezdoc b/doc/src/manual/cowboy.ezdoc
index a207afe..209d473 100644
--- a/doc/src/manual/cowboy.ezdoc
+++ b/doc/src/manual/cowboy.ezdoc
@@ -5,6 +5,12 @@ manipulating Ranch listeners.
:: Types
+: fields() = [atom()
+ | {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()]}
+ | {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()], any()}]
+
+Fields for match operations. Constraint(s) and default value are optional.
+
: http_headers() = [{binary(), iodata()}]
HTTP headers as a list of key/values.
diff --git a/doc/src/manual/cowboy_req.ezdoc b/doc/src/manual/cowboy_req.ezdoc
index beac1f4..94556b2 100644
--- a/doc/src/manual/cowboy_req.ezdoc
+++ b/doc/src/manual/cowboy_req.ezdoc
@@ -6,21 +6,19 @@ 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()}`
+* access: `Value`
+* action: `ok | {Result, Req} | {Result, Value, Req}`
* 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.
+values which are necessary for Cowboy to keep track of the request
+and response states.
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.
+throw an error on the second call when it detects suspicious behavior.
It is highly discouraged to pass the Req object to another process.
Doing so and calling `cowboy_req` functions from it leads to
@@ -54,7 +52,7 @@ the function descriptions below.
:: Request related exports
: binding(Name, Req) -> binding(Name, Req, undefined)
-: binding(Name, Req, Default) -> {Value, Req2}
+: binding(Name, Req, Default) -> Value
Types:
@@ -68,7 +66,7 @@ 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}
+: bindings(Req) -> [{Name, Value}]
Types:
@@ -81,30 +79,8 @@ 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}
+: header(Name, Req, Default) -> Value
Types:
@@ -117,7 +93,7 @@ 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}
+: headers(Req) -> Headers
Types:
@@ -125,7 +101,7 @@ Types:
Return all headers.
-: host(Req) -> {Host, Req2}
+: host(Req) -> Host
Types:
@@ -133,7 +109,7 @@ Types:
Return the requested host.
-: host_info(Req) -> {HostInfo, Req2}
+: host_info(Req) -> HostInfo
Types:
@@ -141,7 +117,7 @@ Types:
Return the extra tokens from matching against `...` during routing.
-: host_url(Req) -> {HostURL, Req2}
+: host_url(Req) -> HostURL
Types:
@@ -153,8 +129,57 @@ This function will always return `undefined` until the
`cowboy_router` middleware has been executed. This includes
the `onrequest` hook.
+: match_cookies(Req, Fields) -> Map
+
+Types:
+
+* Fields = cowboy:fields()
+* Map = map()
+
+Match cookies against the given fields.
+
+Cowboy will only return the cookie values specified in the
+fields list, and ignore all others. Fields can be either
+the name of the cookie requested; the name along with a
+list of constraints; or the name, a list of constraints
+and a default value in case the cookie is missing.
+
+This function will crash if the cookie is missing and no
+default value is provided. This function will also crash
+if a constraint fails.
+
+The name of the cookie must be provided as an atom. The
+key of the returned map will be that atom. The value may
+be converted through the use of constraints, making this
+function able to extract, validate and convert values all
+in one step.
+
+: match_qs(Req, Fields) -> Map
+
+Types:
+
+* Fields = cowboy:fields()
+* Map = map()
+
+Match the query string against the given fields.
+
+Cowboy will only return the query string values specified
+in the fields list, and ignore all others. Fields can be
+either the key requested; the key along with a list of
+constraints; or the key, a list of constraints and a
+default value in case the key is missing.
+
+This function will crash if the key is missing and no
+default value is provided. This function will also crash
+if a constraint fails.
+
+The key must be provided as an atom. The key of the
+returned map will be that atom. The value may be converted
+through the use of constraints, making this function able
+to extract, validate and convert values all in one step.
+
: meta(Name, Req) -> meta(Name, Req, undefined)
-: meta(Name, Req, Default) -> {Value, Req2}
+: meta(Name, Req, Default) -> Value
Types:
@@ -164,7 +189,7 @@ Types:
Return metadata about the request.
-: method(Req) -> {Method, Req2}
+: method(Req) -> Method
Types:
@@ -174,16 +199,25 @@ 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}
+: parse_cookies(Req) -> [{Name, Value}]
+
+Types:
+
+* Name = binary()
+* Value = binary()
+
+Parse and return all cookies.
+
+Cookie names are case sensitive.
+
+: parse_header(Name, Req) -> see below
+: parse_header(Name, Req, Default) -> ParsedValue | Default
Types:
* Name = binary()
* Default = any()
* ParsedValue - see below
-* Value = any()
Parse the given header.
@@ -196,6 +230,8 @@ following table summarizes the default values used.
|| Header name Default value
|
+| content-length `0`
+| cookie `[]`
| transfer-encoding `[<<"identity">>]`
| Any other header `undefined`
@@ -241,8 +277,8 @@ 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.
+an empty list. Some other headers are expected to have a value if provided
+and may crash if the value is missing.
The authorization header parsing code currently only supports basic
HTTP authentication. The `Credentials` type is thus `{Username, Password}`
@@ -257,7 +293,21 @@ The range header value `Range` can take three forms:
An `undefined` tuple will be returned if Cowboy doesn't know how
to parse the requested header.
-: path(Req) -> {Path, Req2}
+: parse_qs(Req) -> [{Name, Value}]
+
+Types:
+
+* Name = binary()
+* Value = binary() | true
+
+Return the request's query string as a list of tuples.
+
+The atom `true` is returned for keys which have no value.
+Keys with no value are different from keys with an empty
+value in that they do not have a `=` indicating the presence
+of a value.
+
+: path(Req) -> Path
Types:
@@ -265,7 +315,7 @@ Types:
Return the requested path.
-: path_info(Req) -> {PathInfo, Req2}
+: path_info(Req) -> PathInfo
Types:
@@ -273,7 +323,7 @@ Types:
Return the extra tokens from matching against `...` during routing.
-: peer(Req) -> {Peer, Req2}
+: peer(Req) -> Peer
Types:
@@ -281,7 +331,7 @@ Types:
Return the client's IP address and port number.
-: port(Req) -> {Port, Req2}
+: port(Req) -> Port
Types:
@@ -293,7 +343,7 @@ 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}
+: qs(Req) -> QueryString
Types:
@@ -301,32 +351,6 @@ Types:
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:
@@ -338,7 +362,7 @@ Set metadata about the request.
An existing value will be overwritten.
-: url(Req) -> {URL, Req2}
+: url(Req) -> URL
Types:
@@ -350,7 +374,7 @@ This function will always return `undefined` until the
`cowboy_router` middleware has been executed. This includes
the `onrequest` hook.
-: version(Req) -> {Version, Req2}
+: version(Req) -> Version
Types:
@@ -361,7 +385,7 @@ 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}
+: body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2}
Types:
@@ -400,7 +424,7 @@ 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}
+: body_length(Req) -> Length
Types:
@@ -414,8 +438,7 @@ 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}
+: body_qs(Req, Opts) -> {ok, [{Name, Value}], Req2} | {badlength, Req2}
Types:
@@ -501,7 +524,7 @@ it cannot be read again.
:: Response related exports
-: chunk(Data, Req) -> ok | {error, Reason}
+: chunk(Data, Req) -> ok
Types:
@@ -520,7 +543,7 @@ 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}
+: chunked_reply(StatusCode, Headers, Req) -> Req2
Types:
@@ -543,7 +566,7 @@ 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}
+: continue(Req) -> ok
Types:
@@ -591,7 +614,7 @@ 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}
+: reply(StatusCode, Headers, Body, Req) -> Req2
Types:
@@ -657,7 +680,7 @@ arguments. Only send and sendfile operations are supported.
Types:
* Fun = fun((ChunkFun) -> ok)
-* ChunkFun = fun((iodata()) -> ok | {error, atom()})
+* ChunkFun = fun((iodata()) -> ok)
Set a fun for sending the response body using chunked transfer-encoding.