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