Plug.Parsers

Parsed documentation:
View on GitHub
A plug for parsing the request body.

This module also specifies a behaviour that all the parsers to be used with
Plug should adopt.

## Options

  * `:parsers` - a list of modules to be invoked for parsing.
    These modules need to implement the behaviour outlined in
    this module.

  * `:pass` - an optional list of MIME type strings that are allowed
    to pass through. Any mime not handled by a parser and not explicitly
    listed in `:pass` will `raise UnsupportedMediaTypeError`. For example:

      * `["*/*"]` - never raises
      * `["text/html", "application/*"]` - doesn't raise for those values
      * `[]` - always raises (default)

All options supported by `Plug.Conn.read_body/2` are also supported here.
They are repeated here for convenience:

  * `:length` - sets the maximum number of bytes to read from the request,
    defaults to 8_000_000 bytes
  * `:read_length` - sets the amount of bytes to read at one time from the
    underlying socket to fill the chunk, defaults to 1_000_000 bytes
  * `:read_timeout` - sets the timeout for each socket read, defaults to
    15_000ms

So by default, `Plug.Parsers` will read 1_000_000 bytes at a time from the
socket with an overall limit of 8_000_000 bytes.

This plug also fetches query params in the connection through
`Plug.Conn.fetch_query_params/2`.

Once a connection goes through this plug, it will have `:body_params` set to
the map of params parsed by one of the parsers listed in `:parsers` and
`:params` set to the result of merging the `:body_params` and `:query_params`.

This plug will raise `Plug.Parsers.UnsupportedMediaTypeError` by default if
the request cannot be parsed by any of the given types and the MIME type has
not been explicity accepted with the `:pass` option.

`Plug.Parsers.RequestTooLargeError` will be raised if the request goes over
the given limit.

Parsers may raise a `Plug.Parsers.ParseError` if the request has a malformed
body.

This plug only parses the body if the request method is one of the following:

  * `POST`
  * `PUT`
  * `PATCH`
  * `DELETE`

For requests with a different request method, this plug will only fetch the
query params.

## Examples

    plug Plug.Parsers, parsers: [:urlencoded, :multipart]
    plug Plug.Parsers, parsers: [:urlencoded, :json],
                       pass:  ["text/*"],
                       json_decoder: Poison

## Built-in parsers

Plug ships with the following parsers:

  * `Plug.Parsers.URLENCODED` - parses `application/x-www-form-urlencoded`
    requests (can be used as `:urlencoded` as well in the `:parsers` option)
  * `Plug.Parsers.MULTIPART` - parses `multipart/form-data` and
    `multipart/mixed` requests (can be used as `:multipart` as well in the
    `:parsers` option)
  * `Plug.Parsers.JSON` - parses `application/json` requests with the given
    `:json_decoder` (can be used as `:json` as well in the `:parsers` option)

## File handling

If a file is uploaded via any of the parsers, Plug will
stream the uploaded contents to a file in a temporary directory in order to
avoid loading the whole file into memory. For such, the `:plug` application
needs to be started in order for file uploads to work. More details on how the
uploaded file is handled can be found in the documentation for `Plug.Upload`.

When a file is uploaded, the request parameter that identifies that file will
be a `Plug.Upload` struct with information about the uploaded file (e.g.
filename and content type) and about where the file is stored.

The temporary directory where files are streamed to can be customized by
setting the `PLUG_TMPDIR` environment variable on the host system. If
`PLUG_TMPDIR` isn't set, Plug will look at some environment
variables which usually hold the value of the system's temporary directory
(like `TMPDIR` or `TMP`). If no value is found in any of those variables,
`/tmp` is used as a default.
No suggestions.
Please help! Open an issue on GitHub if this assessment is incorrect.