diff options
Diffstat (limited to 'doc/src/manual')
| -rw-r--r-- | doc/src/manual/cowboy.ezdoc | 101 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_app.ezdoc | 23 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_handler.ezdoc | 24 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_http_handler.ezdoc | 57 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_loop_handler.ezdoc | 91 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_middleware.ezdoc | 54 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_protocol.ezdoc | 84 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_req.ezdoc | 704 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_rest.ezdoc | 561 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_router.ezdoc | 70 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_spdy.ezdoc | 43 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_static.ezdoc | 32 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_sub_protocol.ezdoc | 32 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_websocket.ezdoc | 36 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_websocket_handler.ezdoc | 133 | ||||
| -rw-r--r-- | doc/src/manual/http_status_codes.ezdoc | 151 | ||||
| -rw-r--r-- | doc/src/manual/index.ezdoc | 20 |
17 files changed, 2216 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy.ezdoc b/doc/src/manual/cowboy.ezdoc new file mode 100644 index 0000000..a207afe --- /dev/null +++ b/doc/src/manual/cowboy.ezdoc @@ -0,0 +1,101 @@ +::: 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/doc/src/manual/cowboy_app.ezdoc b/doc/src/manual/cowboy_app.ezdoc new file mode 100644 index 0000000..2e2b877 --- /dev/null +++ b/doc/src/manual/cowboy_app.ezdoc @@ -0,0 +1,23 @@ +::: 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/doc/src/manual/cowboy_handler.ezdoc b/doc/src/manual/cowboy_handler.ezdoc new file mode 100644 index 0000000..0495f28 --- /dev/null +++ b/doc/src/manual/cowboy_handler.ezdoc @@ -0,0 +1,24 @@ +::: cowboy_handler + +The `cowboy_handler` middleware executes the handler passed +through the environment values `handler` and `handler_opts`, +and adds 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/doc/src/manual/cowboy_http_handler.ezdoc b/doc/src/manual/cowboy_http_handler.ezdoc new file mode 100644 index 0000000..6776598 --- /dev/null +++ b/doc/src/manual/cowboy_http_handler.ezdoc @@ -0,0 +1,57 @@ +::: 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/doc/src/manual/cowboy_loop_handler.ezdoc b/doc/src/manual/cowboy_loop_handler.ezdoc new file mode 100644 index 0000000..0811a9a --- /dev/null +++ b/doc/src/manual/cowboy_loop_handler.ezdoc @@ -0,0 +1,91 @@ +::: 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` callback 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/doc/src/manual/cowboy_middleware.ezdoc b/doc/src/manual/cowboy_middleware.ezdoc new file mode 100644 index 0000000..065139c --- /dev/null +++ b/doc/src/manual/cowboy_middleware.ezdoc @@ -0,0 +1,54 @@ +::: 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/doc/src/manual/cowboy_protocol.ezdoc b/doc/src/manual/cowboy_protocol.ezdoc new file mode 100644 index 0000000..6813295 --- /dev/null +++ b/doc/src/manual/cowboy_protocol.ezdoc @@ -0,0 +1,84 @@ +::: 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/doc/src/manual/cowboy_req.ezdoc b/doc/src/manual/cowboy_req.ezdoc new file mode 100644 index 0000000..beac1f4 --- /dev/null +++ b/doc/src/manual/cowboy_req.ezdoc @@ -0,0 +1,704 @@ +::: 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/doc/src/manual/cowboy_rest.ezdoc b/doc/src/manual/cowboy_rest.ezdoc new file mode 100644 index 0000000..4d13530 --- /dev/null +++ b/doc/src/manual/cowboy_rest.ezdoc @@ -0,0 +1,561 @@ +::: 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/doc/src/manual/cowboy_router.ezdoc b/doc/src/manual/cowboy_router.ezdoc new file mode 100644 index 0000000..f76acf6 --- /dev/null +++ b/doc/src/manual/cowboy_router.ezdoc @@ -0,0 +1,70 @@ +::: 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/doc/src/manual/cowboy_spdy.ezdoc b/doc/src/manual/cowboy_spdy.ezdoc new file mode 100644 index 0000000..51a2110 --- /dev/null +++ b/doc/src/manual/cowboy_spdy.ezdoc @@ -0,0 +1,43 @@ +::: 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/doc/src/manual/cowboy_static.ezdoc b/doc/src/manual/cowboy_static.ezdoc new file mode 100644 index 0000000..ee122c1 --- /dev/null +++ b/doc/src/manual/cowboy_static.ezdoc @@ -0,0 +1,32 @@ +::: 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/doc/src/manual/cowboy_sub_protocol.ezdoc b/doc/src/manual/cowboy_sub_protocol.ezdoc new file mode 100644 index 0000000..2ad0cf7 --- /dev/null +++ b/doc/src/manual/cowboy_sub_protocol.ezdoc @@ -0,0 +1,32 @@ +::: 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/doc/src/manual/cowboy_websocket.ezdoc b/doc/src/manual/cowboy_websocket.ezdoc new file mode 100644 index 0000000..59a6248 --- /dev/null +++ b/doc/src/manual/cowboy_websocket.ezdoc @@ -0,0 +1,36 @@ +::: 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/doc/src/manual/cowboy_websocket_handler.ezdoc b/doc/src/manual/cowboy_websocket_handler.ezdoc new file mode 100644 index 0000000..0d31a54 --- /dev/null +++ b/doc/src/manual/cowboy_websocket_handler.ezdoc @@ -0,0 +1,133 @@ +::: 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/doc/src/manual/http_status_codes.ezdoc b/doc/src/manual/http_status_codes.ezdoc new file mode 100644 index 0000000..4d24b20 --- /dev/null +++ b/doc/src/manual/http_status_codes.ezdoc @@ -0,0 +1,151 @@ +::: 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/doc/src/manual/index.ezdoc b/doc/src/manual/index.ezdoc new file mode 100644 index 0000000..e364e90 --- /dev/null +++ b/doc/src/manual/index.ezdoc @@ -0,0 +1,20 @@ +::: Cowboy Function Reference + +The function reference documents the public interface of Cowboy. + +* ^"The Cowboy Application^cowboy_app +* ^cowboy +* ^cowboy_handler +* ^cowboy_http_handler +* ^cowboy_loop_handler +* ^cowboy_middleware +* ^cowboy_protocol +* ^cowboy_req +* ^cowboy_rest +* ^cowboy_router +* ^cowboy_spdy +* ^cowboy_static +* ^cowboy_sub_protocol +* ^cowboy_websocket +* ^cowboy_websocket_handler +* ^"HTTP status codes^http_status_codes |