@spec allow_missing_post(conn(), state()) :: {boolean() | halt(), conn(), state()}

If the resource accepts POST requests to nonexistent resources, then this should return true.

Default: false

@spec allowed_methods(conn(), state()) :: {[String.t()] | halt(), conn(), state()}

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 base_uri(conn(), state()) :: {String.t() | halt(), conn(), state()}

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 charsets_provided(conn(), state()) ::
  {:no_charset
   | [{String.Chars.t(), (binary() -> binary())}]
   | Enum.t()
   | halt(), conn(), state()}

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 content_types_accepted(conn(), state()) ::
  {[{String.Chars.t(), atom()}] | Enum.t() | halt(), conn(), state()}

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_provided(conn(), state()) ::
  {[{String.Chars.t(), atom()}] | Enum.t() | halt(), conn(), state()}

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 create_path(conn(), state()) :: {nil | String.t() | halt(), conn(), state()}

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 delete_completed(conn(), state()) :: {boolean() | halt(), conn(), state()}

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_resource(conn(), state()) :: {boolean() | halt(), conn(), state()}

This is called when a DELETE request should be enacted, and should return true if the deletion succeeded.

@spec encodings_provided(conn(), state()) ::
  {[{String.Chars.t(), (binary() -> binary())}] | Enum.t() | halt(), conn(),
   state()}

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 expires(conn(), state()) ::
  {nil
   | {{day :: integer(), month :: integer(), year :: integer()},
      {hour :: integer(), min :: integer(), sec :: integer()}}
   | halt(), conn(), state()}

If not nil, set the expires header

Default: nil

@spec finish_request(conn(), state()) :: {any() | halt(), conn(), state()}

Last handler, always called. Response is ignored except if it is a halt.

@spec forbidden(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning true will result in 403 Forbidden.

Default: false

@spec from_json(conn(), state()) :: {true | halt(), conn(), state()}

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 generate_etag(conn(), state()) :: {nil | binary() | halt(), conn(), state()}

If not nil, it will be used for the ETag header and for comparison in conditional requests.

Default: nil

@spec is_authorized(conn(), state()) :: {boolean() | halt(), conn(), state()}

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_conflict(conn(), state()) :: {boolean() | halt(), conn(), state()}

If this returns true, the client will receive a 409 Conflict.

Default : false

@spec known_content_type(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning false will result in 415 Unsupported Media Type.

Default: true

@spec known_methods(conn(), state()) :: {[String.t()] | halt(), conn(), state()}

Override the known methods accepted by your automate

Default: ["GET", "HEAD", "POST", "PUT", "DELETE", "TRACE", "CONNECT", "OPTIONS"]

@spec language_available(conn(), state()) :: {boolean() | halt(), conn(), state()}

return false if language in Plug.Conn.get_resp_header(conn,"accept-language") is not available.

@spec last_modified(conn(), state()) ::
  {nil
   | {{day :: integer(), month :: integer(), year :: integer()},
      {hour :: integer(), min :: integer(), sec :: integer()}}
   | halt(), conn(), state()}

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 malformed_request(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning true will result in 400 Bad Request.

Default: false

@spec moved_permanently(conn(), state()) :: {boolean() | halt(), conn(), state()}

If this returns {true, uri}, the client will receive a 301 Moved Permanently with uri in the Location header.

Default: false

@spec moved_temporarily(conn(), state()) :: {boolean() | halt(), conn(), state()}

If this returns {true, uri}, the client will receive a 307 Temporary Redirect with uri in the Location header.

Default: false

@spec multiple_choices(conn(), state()) :: {boolean() | halt(), conn(), state()}

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 options(conn(), state()) ::
  {[{String.t(), String.t()}] | halt(), conn(), state()}

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 ping(conn(), state()) :: {:pang | :pong | halt(), conn(), state()}

Must be present and returning pong to prove that handlers are well linked to the automate

@spec post_is_create(conn(), state()) :: {boolean() | halt(), conn(), state()}

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 previously_existed(conn(), state()) :: {boolean() | halt(), conn(), state()}

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 process_post(conn(), state()) :: {boolean() | halt(), conn(), state()}

If post_is_create returns false, then this will be called to process any POST requests. If it succeeds, it should return true.

@spec resource_exists(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning non-true values will result in 404 Not Found.

Default: true

@spec service_available(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning non-true values will result in 503 Service Unavailable.

Default: true

@spec to_html(conn(), state()) :: {iodata() | Enum.t() | halt(), conn(), state()}

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 uri_too_long(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning true will result in 414 Request-URI Too Long.

Default: false

@spec valid_content_headers(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning false will result in 501 Not Implemented.

Default: true

@spec valid_entity_length(conn(), state()) :: {boolean() | halt(), conn(), state()}

Returning false will result in 413 Request Entity Too Large.

Default: false

@spec validate_content_checksum(conn(), state()) ::
  {:not_validated | boolean() | halt(), conn(), state()}

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 variances(conn(), state()) :: {[String.t()] | halt(), conn(), state()}

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 : []