Plug

v1.4.3

Plug v1.4.3 Plug.Parsers behaviour View Source

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.

Link to this section Summary

Functions

call(conn, options)

Callback implementation for Plug.call/2

init(opts)

Callback implementation for Plug.init/1

Callbacks

parse(conn, type, subtype, params, opts)

Attempts to parse the connection’s request body given the content-type type, subtype, and its parameters

Link to this section Functions

Link to this function call(conn, options) View Source

Callback implementation for Plug.call/2.

Link to this function init(opts) View Source

Callback implementation for Plug.init/1.

Link to this section Callbacks

Link to this callback parse(conn, type, subtype, params, opts) View Source 
parse(conn :: Plug.Conn.t, type :: binary, subtype :: binary, params :: Keyword.t, opts :: Keyword.t) ::
  {:ok, Plug.Conn.params, Plug.Conn.t} |
  {:error, :too_large, Plug.Conn.t} |
  {:next, Plug.Conn.t}

Attempts to parse the connection’s request body given the content-type type, subtype, and its parameters.

The arguments are:

  • the Plug.Conn connection
  • type, the content-type type (e.g., "x-sample" for the "x-sample/json" content-type)
  • subtype, the content-type subtype (e.g., "json" for the "x-sample/json" content-type)
  • params, the content-type parameters (e.g., %{"foo" => "bar"} for the "text/plain; foo=bar" content-type)

This function should return:

  • {:ok, body_params, conn} if the parser is able to handle the given content-type; body_params should be a map
  • {:next, conn} if the next parser should be invoked
  • {:error, :too_large, conn} if the request goes over the given limit