defmodule Ewebmachine.Handlers do
@type conn :: Plug.Conn.t
@type state :: any
@type halt :: {:halt, 200..599}
@moduledoc """
Implement the functions described below to make decisions in the
[HTTP decision tree](http_diagram.png) :
- `service_available/2`
- `resource_exists/2`
- `is_authorized/2`
- `forbidden/2`
- `allow_missing_post/2`
- `malformed_request/2`
- `uri_too_long/2`
- `known_content_type/2`
- `valid_content_headers/2`
- `valid_entity_length/2`
- `options/2`
- `allowed_methods/2`
- `known_methods/2`
- `content_types_provided/2`
- `content_types_accepted/2`
- `delete_resource/2`
- `delete_completed/2`
- `post_is_create/2`
- `create_path/2`
- `base_uri/2`
- `process_post/2`
- `language_available/2`
- `charsets_provided/2`
- `encodings_provided/2`
- `variances/2`
- `is_conflict/2`
- `multiple_choices/2`
- `previously_existed/2`
- `moved_permanently/2`
- `moved_temporarily/2`
- `last_modified/2`
- `expires/2`
- `generate_etag/2`
- `validate_content_checksum/2`
- `ping/2`
- Body-producing function, see `to_html/2` (but any function name can be
used, as referenced by `content_types_provided/2`
- POST/PUT processing function, see `from_json/2` (but any function name can be
used, as referenced by `content_types_accepted/2`
All the handlers have the same signature :
```
(conn :: Plug.Conn.t,state :: any)->{response :: any | {:halt,200..599},conn :: Plug.Conn.t, state :: any}
```
where every handler implementation :
- can change or halt the plug `conn` passed as argument
- can change the user state object passed from on handler to another in its arguments
- returns something which will make decision in the HTTP decision tree (see
documentation of functions in this module to see expected results and effects)
- can return `{:halt,200..599}` to end the ewebmachine automate execution,
but do not `halt` the `conn`, so the plug pipeline can continue.
So each handler implementation is actually a "plug" returning a response giving
information allowing to make the good response code and path in the HTTP
specification.
## Usage ##
The following modules will help you to construct these handlers and use them :
- `Ewebmachine.Builder.Handlers` gives you macros and helpers to define the
handlers and automatically create the plug to add them to your `conn.private[:resource_handlers]`
- `Ewebmachine.Plug.Run` run the HTTP decision tree executing the handler
implementations described in its `conn.private[:resource_handlers]`. The
initial user `state` is taken in `conn.private[:machine_init]`
"""
@doc """
Returning non-true values will result in `503 Service Unavailable`.
Default: `true`
"""
@spec service_available(conn,state) :: {boolean | halt,conn,state}
def service_available(conn,state), do: {true,conn,state}
@doc """
Returning non-true values will result in `404 Not Found`.
Default: `true`
"""
@spec resource_exists(conn,state) :: {boolean | halt,conn,state}
def resource_exists(conn,state), do: {true,conn,state}
@doc """
If this returns anything other than `true`, the response will be
`401 Unauthorized`. The return value will be used as the value in
the `WWW-Authenticate` header, for example `Basic
realm="Webmachine"`.
Default: `true`
"""
@spec is_authorized(conn,state) :: {boolean | halt,conn,state}
def is_authorized(conn,state), do: {true,conn,state}
@doc """
Returning true will result in 403 Forbidden.
Default: `false`
"""
@spec forbidden(conn,state) :: {boolean | halt,conn,state}
def forbidden(conn,state), do: {false,conn,state}
@doc """
If the resource accepts POST requests to nonexistent resources, then this should return `true`.
Default: `false`
"""
@spec allow_missing_post(conn,state) :: {boolean | halt,conn,state}
def allow_missing_post(conn,state), do: {false,conn,state}
@doc """
Returning true will result in 400 Bad Request.
Default: `false`
"""
@spec malformed_request(conn,state) :: {boolean | halt,conn,state}
def malformed_request(conn,state), do:
{false,conn,state}
@doc """
Returning true will result in 414 Request-URI Too Long.
Default: `false`
"""
@spec uri_too_long(conn,state) :: {boolean | halt,conn,state}
def uri_too_long(conn,state), do:
{false,conn,state}
@doc """
Returning false will result in 415 Unsupported Media Type.
Default: `true`
"""
@spec known_content_type(conn,state) :: {boolean | halt,conn,state}
def known_content_type(conn,state), do:
{true,conn,state}
@doc """
Returning false will result in 501 Not Implemented.
Default: `true`
"""
@spec valid_content_headers(conn,state) :: {boolean | halt,conn,state}
def valid_content_headers(conn,state), do:
{true,conn,state}
@doc """
Returning false will result in 413 Request Entity Too Large.
Default: `false`
"""
@spec valid_entity_length(conn,state) :: {boolean | halt,conn,state}
def valid_entity_length(conn,state), do:
{true,conn,state}
@doc """
If the OPTIONS method is supported and is used, the return value of
this function is expected to be a list of pairs representing header
names and values that should appear in the response.
"""
@spec options(conn,state) :: {[{String.t,String.t}] | halt,conn,state}
def options(conn,state), do:
{[],conn,state}
@doc """
If a Method not in this list is requested, then a 405 Method Not
Allowed will be sent. Note that these are all-caps Strings (binary).
Default: `["GET", "HEAD"]`
"""
@spec allowed_methods(conn,state) :: {[String.t] | halt,conn,state}
def allowed_methods(conn,state), do:
{["GET", "HEAD"],conn,state}
@doc """
Override the known methods accepted by your automate
Default: `["GET", "HEAD", "POST", "PUT", "DELETE", "TRACE", "CONNECT", "OPTIONS"]`
"""
@spec known_methods(conn,state) :: {[String.t] | halt,conn,state}
def known_methods(conn,state), do:
{["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "TRACE", "CONNECT", "OPTIONS"],conn,state}
@doc """
This should return a key value tuple enumerable where the key is
the content-type format and the value is an atom naming the
function which can provide a resource representation in that media
type. Content negotiation is driven by this return value. For
example, if a client request includes an Accept header with a value
that does not appear as a first element in any of the return
tuples, then a 406 Not Acceptable will be
sent.
Default: `[{"text/html", to_html}]`
"""
@spec content_types_provided(conn,state) :: {[{String.Chars.t,atom}] | Enum.t | halt,conn,state}
def content_types_provided(conn,state), do:
{[{"text/html", :to_html}],conn,state}
@doc """
This is used similarly to content_types_provided, except that it is
for incoming resource representations -- for example, PUT requests.
Handler functions usually want to use `Plug.read_body(conn)` to
access the incoming request body.
Default: `[]`
"""
@spec content_types_accepted(conn,state) :: {[{String.Chars.t,atom}] | Enum.t | halt,conn,state}
def content_types_accepted(conn,state), do:
{[],conn,state}
@doc """
This is called when a DELETE request should be enacted, and should
return `true` if the deletion succeeded.
"""
@spec delete_resource(conn,state) :: {boolean | halt,conn,state}
def delete_resource(conn,state), do:
{false,conn,state}
@doc """
This is only called after a successful `delete_resource` call, and
should return `false` if the deletion was accepted but cannot yet be
guaranteed to have finished.
"""
@spec delete_completed(conn,state) :: {boolean | halt,conn,state}
def delete_completed(conn,state), do:
{true,conn,state}
@doc """
If POST requests should be treated as a request to put content into
a (potentially new) resource as opposed to being a generic
submission for processing, then this function should return true.
If it does return `true`, then `create_path` will be called and the
rest of the request will be treated much like a PUT to the Path
entry returned by that call.
Default: `false`
"""
@spec post_is_create(conn,state) :: {boolean | halt,conn,state}
def post_is_create(conn,state), do:
{false,conn,state}
@doc """
This will be called on a POST request if `post_is_create` returns
true. It is an error for this function not to produce a Path if
post_is_create returns true. The Path returned should be a valid
URI part.
"""
@spec create_path(conn,state) :: {nil | String.t | halt,conn,state}
def create_path(conn,state), do:
{nil,conn,state}
@doc """
The base URI used in the location header on resource creation (when
`post_is_create` is `true`), will be prepended to the `create_path`
"""
@spec base_uri(conn,state) :: {String.t | halt,conn,state}
def base_uri(conn,state), do:
{"#{conn.scheme}://#{conn.host}#{port_suffix(conn.scheme,conn.port)}",conn,state}
defp port_suffix(:http,80), do: ""
defp port_suffix(:https,443), do: ""
defp port_suffix(_,port), do: ":#{port}"
@doc """
If `post_is_create` returns `false`, then this will be called to
process any POST requests. If it succeeds, it should return `true`.
"""
@spec process_post(conn,state) :: {boolean | halt,conn,state}
def process_post(conn,state), do:
{false,conn,state}
@doc """
return false if language in
`Plug.Conn.get_resp_header(conn,"accept-language")` is not
available.
"""
@spec language_available(conn,state) :: {boolean | halt,conn,state}
def language_available(conn,state), do:
{true,conn,state}
@doc """
If this is anything other than the atom `:no_charset`, it must be a
`{key,value}` Enumerable where `key` is the charset and `value` is a
callable function in the resource which will be called on the
produced body in a GET and ensure that it is in Charset.
Default: `:no_charset`
"""
@spec charsets_provided(conn,state) :: {:no_charset | [{String.Chars.t,(binary->binary)}] | Enum.t | halt,conn,state}
def charsets_provided(conn,state), do:
{:no_charset,conn,state}
## this atom causes charset-negotation to short-circuit
## the default setting is needed for non-charset responses such as image/png
## an example of how one might do actual negotiation
## [{"iso-8859-1", fun(X) -> X end}, {"utf-8", make_utf8}];
@doc """
This must be a `{key,value}` Enumerable where `key` is a valid
content encoding and `value` is a callable function in the resource
which will be called on the produced body in a GET and ensure that
it is so encoded. One useful setting is to have the function check
on method, and on GET requests return:
```
[identity: &(&1), gzip: &:zlib.gzip/1]
```
as this is all that is needed to support gzip content encoding.
Default: `[{"identity", fn X-> X end}]`
"""
@spec encodings_provided(conn,state) :: {[{String.Chars.t,(binary->binary)}] | Enum.t | halt,conn,state}
def encodings_provided(conn,state), do:
{[{"identity", &(&1)}],conn,state}
# this is handy for auto-gzip of GET-only resources:
# [{"identity", fun(X) -> X end}, {"gzip", fun(X) -> zlib:gzip(X) end}];
@doc """
If this function is implemented, it should return a list of strings
with header names that should be included in a given response's
Vary header. The standard conneg headers (`Accept`, `Accept-Encoding`,
`Accept-Charset`, `Accept-Language`) do not need to be specified here
as Webmachine will add the correct elements of those automatically
depending on resource behavior.
Default : `[]`
"""
@spec variances(conn,state) :: {[String.t] | halt,conn,state}
def variances(conn,state), do:
{[],conn,state}
@doc """
If this returns `true`, the client will receive a 409 Conflict.
Default : `false`
"""
@spec is_conflict(conn,state) :: {boolean | halt,conn,state}
def is_conflict(conn,state), do:
{false,conn,state}
@doc """
If this returns `true`, then it is assumed that multiple
representations of the response are possible and a single one
cannot be automatically chosen, so a `300 Multiple Choices` will be
sent instead of a `200 OK`.
Default: `false`
"""
@spec multiple_choices(conn,state) :: {boolean | halt,conn,state}
def multiple_choices(conn,state), do:
{false,conn,state}
@doc """
If this returns `true`, the `moved_permanently` and `moved_temporarily`
callbacks will be invoked to determine whether the response should
be `301 Moved Permanently`, `307 Temporary Redirect`, or `410 Gone`.
Default: `false`
"""
@spec previously_existed(conn,state) :: {boolean | halt,conn,state}
def previously_existed(conn,state), do:
{false,conn,state}
@doc """
If this returns `{true, uri}`, the client will receive a `301 Moved
Permanently` with `uri` in the Location header.
Default: `false`
"""
@spec moved_permanently(conn,state) :: {boolean | halt,conn,state}
def moved_permanently(conn,state), do:
{false,conn,state}
@doc """
If this returns `{true, uri}`, the client will receive a `307
Temporary Redirect` with `uri` in the Location header.
Default: `false`
"""
@spec moved_temporarily(conn,state) :: {boolean | halt,conn,state}
def moved_temporarily(conn,state), do:
{false,conn,state}
@doc """
If this returns a `datetime()` (`{{day,month,year},{h,m,s}}`, it
will be used for the `Last-Modified` header and for comparison in
conditional requests.
Default: `nil`
"""
@spec last_modified(conn,state) :: {nil | {{day::integer,month::integer,year::integer},{hour::integer,min::integer,sec::integer}} | halt,conn,state}
def last_modified(conn,state), do:
{nil,conn,state}
@doc """
If not `nil`, set the expires header
Default: `nil`
"""
@spec expires(conn,state) :: {nil | {{day::integer,month::integer,year::integer},{hour::integer,min::integer,sec::integer}} | halt,conn,state}
def expires(conn,state), do:
{nil,conn,state}
@doc """
If not `nil`, it will be used for the ETag header and
for comparison in conditional requests.
Default: `nil`
"""
@spec generate_etag(conn,state) :: {nil | binary | halt,conn,state}
def generate_etag(conn,state), do:
{nil,conn,state}
@doc """
if `content-md5` header exists:
- If `:not_validated`, test if input body validate `content-md5`,
- if return `false`, then return a bad request
Useful if content-md5 validation does not imply only raw md5 hash
"""
@spec validate_content_checksum(conn,state) :: {:not_validated | boolean | halt,conn,state}
def validate_content_checksum(conn,state), do:
{:not_validated,conn,state}
@doc """
Must be present and returning `pong` to prove that handlers are
well linked to the automate
"""
@spec ping(conn,state) :: {:pang | :pong | halt,conn,state}
def ping(conn,state), do:
{:pang,conn,state}
@doc """
Last handler, always called. Response is ignored except if it is a `halt`.
"""
@spec finish_request(conn,state) :: {any | halt, conn, state}
def finish_request(conn,state), do:
{false,conn,state}
@doc """
Example body-producing function, function atom name must be referenced in `content_types_provided/2`.
- If the result is an `Enumerable` of `iodata`, then the HTTP response will be
a chunk encoding response where each chunk on element of the enumeration.
- If the result is an iodata, then it is used as the HTTP response body
"""
@spec to_html(conn,state) :: {iodata | Enum.t | halt,conn,state}
def to_html(conn,state), do:
{"<html><body><h1>Hello World</h1></body></html>",conn,state}
@doc """
Example POST/PUT processing function, function atom name must be referenced
in `content_types_accepted/2`.
It will be called when the request is `PUT` or when the
request is `POST` and `post_is_create` returns true.
"""
@spec from_json(conn,state) :: {true | halt,conn,state}
def from_json(conn,state), do:
{true,conn,state}
end
