diff options
Diffstat (limited to 'guide')
| -rw-r--r-- | guide/middlewares.md | 2 | ||||
| -rw-r--r-- | guide/req.md | 7 | ||||
| -rw-r--r-- | guide/resources.md | 17 | ||||
| -rw-r--r-- | guide/rest_handlers.md | 84 | ||||
| -rw-r--r-- | guide/toc.md | 4 |
5 files changed, 107 insertions, 7 deletions
diff --git a/guide/middlewares.md b/guide/middlewares.md index b5f055c..a1f1f8d 100644 --- a/guide/middlewares.md +++ b/guide/middlewares.md @@ -48,7 +48,7 @@ the routing information. It is a list of tuples with the first element being an atom and the second any Erlang term. Two values in the environment are reserved: - * `listener` contains the pid of the listener process + * `listener` contains the name of the listener * `result` contains the result of the processing The `listener` value is always defined. The `result` value can be diff --git a/guide/req.md b/guide/req.md index f627737..aa3bf4b 100644 --- a/guide/req.md +++ b/guide/req.md @@ -33,7 +33,6 @@ The following access functions are defined in `cowboy_req`: * `method/1`: the request method (`<<"GET">>`, `<<"POST">>`...) * `version/1`: the HTTP version (`{1,0}` or `{1,1}`) * `peer/1`: the peer address and port number - * `peer_addr/1`: the peer address guessed using the request headers * `host/1`: the hostname requested * `host_info/1`: the result of the `[...]` match on the host * `port/1`: the port number used for the connection @@ -104,9 +103,9 @@ and `body_qs/2` will return `{error, badlength}`. If the request contains chunked body, `body/1`, `body/2`, `body_qs/1` and `body_qs/2` will return `{error, chunked}`. If you get either of the above two errors, you will want to -handle the body of the request using `stream_body/1` and -`skip_body/1`, with the streaming process optionally -initialized using `init_stream/4` or `init_stream/5`. +handle the body of the request using `stream_body/1`, +`stream_body/2` and `skip_body/1`, with the streaming process +optionally initialized using `init_stream/4`. Multipart request body ---------------------- diff --git a/guide/resources.md b/guide/resources.md new file mode 100644 index 0000000..1d1b18a --- /dev/null +++ b/guide/resources.md @@ -0,0 +1,17 @@ +Resources +========= + +Frameworks +---------- + + * Please send a pull request! + +Helper libraries +---------------- + + * Please send a pull request! + +Articles +-------- + + * Please send a pull request! diff --git a/guide/rest_handlers.md b/guide/rest_handlers.md index 62f0ba1..1eccc65 100644 --- a/guide/rest_handlers.md +++ b/guide/rest_handlers.md @@ -25,9 +25,89 @@ Not done yet. Feel free to use the one that is currently being worked on. Callbacks --------- -Please see the Webmachine documentation at this time. +All callbacks are optional. Some may become mandatory depending +on what other defined callbacks return. The flow diagram should +be a pretty good resource to determine which callbacks you need. + +When the request starts being processed, Cowboy will call the +`rest_init/2` function if it is defined, with the Req object +and the handler options as arguments. This function must return +`{ok, Req, State}` where `State` is the handler's state that all +subsequent callbacks will receive. + +At the end of every request, the special callback `rest_terminate/2` +will be called if it is defined. It cannot be used to send a reply, +and must always return `ok`. + +All other callbacks are resource callbacks. They all take two +arguments, the Req object and the State, and return a three-element +tuple of the form `{Value, Req, State}`. + +The following table summarizes the callbacks and their default values. +If the callback isn't defined, then the default value will be used. +Please look at the flow diagram to find out the result of each return +value. + +All callbacks can also return `{halt, Req, State}` to stop execution +of the request, at which point `rest_terminate/2` will be called. + +In the following table, "skip" means the callback is entirely skipped +if it is undefined, moving directly to the next step. Similarly, an +empty column means there is no default value for this callback. + +| Callback name | Default value | +| ---------------------- | ------------------------- | +| allowed_methods | `[<<"GET">>, <<"HEAD">>]` | +| allow_missing_post | `true` | +| charsets_provided | skip | +| content_types_accepted | | +| content_types_provided | | +| delete_completed | `true` | +| delete_resource | `false` | +| expires | `undefined` | +| forbidden | `false` | +| generate_etag | `undefined` | +| is_authorized | `true` | +| is_conflict | `false` | +| known_content_type | `true` | +| known_methods | `[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]` | +| languages_provided | skip | +| last_modified | `undefined` | +| malformed_request | `false` | +| moved_permanently | `false` | +| moved_temporarily | `false` | +| multiple_choices | `false` | +| options | | +| previously_existed | `false` | +| resource_exists | `true` | +| service_available | `true` | +| uri_too_long | `false` | +| valid_content_headers | `true` | +| valid_entity_length | `true` | +| variances | `[]` | + +As you can see, Cowboy tries to move on with the request whenever +possible by using well thought out default values. + +In addition to these, there can be any number of user-defined +callbacks that are specified through `content_types_accepted/2` +and `content_types_provided/2`. They can take any name, however +it is recommended to use a separate prefix for the callbacks of +each function. For example, `from_html` and `to_html` indicate +in the first case that we're accepting a resource given as HTML, +and in the second case that we send one as HTML. Usage ----- -Please see the examples at this time. +Like Websocket, REST is a sub-protocol of HTTP. It therefore +requires a protocol upgrade. + +``` erlang +init({tcp, http}, Req, Opts) -> + {upgrade, protocol, cowboy_rest}. +``` + +Cowboy will then switch to the REST protocol and start executing +the flow diagram, starting from `rest_init/2` if it's defined, +and ending with `rest_terminate/2` also if defined. diff --git a/guide/toc.md b/guide/toc.md index 2f0d914..6909bed 100644 --- a/guide/toc.md +++ b/guide/toc.md @@ -58,3 +58,7 @@ Cowboy User Guide * One process for many requests * Lowercase header names * Improving performance + * [Resources](resources.md) + * Frameworks + * Helper libraries + * Articles |