Assigns a value to a key in the connection

Examples

iex> conn.assigns[:hello]
nil
iex> conn = assign(conn, :hello, :world)
iex> conn.assigns[:hello]
:world

Starts a task to assign a value to a key in the connection.

await_assign/2 can be used to wait for the async task to complete and retrieve the resulting value.

Behind the scenes, it uses Task.async/1.

Examples

iex> conn.assigns[:hello]
nil
iex> conn = async_assign(conn, :hello, fn -> :world end)
iex> conn.assigns[:hello]
%Task{...}

Awaits the completion of an async assign.

Returns a connection with the value resulting from the async assignment placed under key in the :assigns field.

Behind the scenes, it uses Task.await/2.

Examples

iex> conn.assigns[:hello]
nil
iex> conn = async_assign(conn, :hello, fn -> :world end)
iex> conn = await_assign(conn, :hello) # blocks until `conn.assigns[:hello]` is available
iex> conn.assigns[:hello]
:world

Sends a chunk as part of a chunked response.

It expects a connection with state :chunked as set by send_chunked/2. It returns {:ok, conn} in case of success, otherwise {:error, reason}.

To stream data use Enum.reduce_while/3 instead of Enum.into/2. Enum.reduce_while/3 allows aborting the execution if chunk/2 fails to deliver the chunk of data.

Example

~w(each chunk as a word)
|> Enum.reduce_while(conn, fn (chunk, conn) ->
  case Plug.Conn.chunk(conn, chunk) do
    {:ok, conn} ->
      {:cont, conn}
    {:error, :closed} ->
      {:halt, conn}
  end
end)

Clears the entire session.

This function removes every key from the session, clearing the session.

Note that, even if clear_session/1 is used, the session is still sent to the client. If the session should be effectively dropped, configure_session/2 should be used with the :drop option set to true.

Configures the session.

Options

• :renew - generates a new session id for the cookie
• :drop - drops the session, a session cookie will not be included in the response
• :ignore - ignores all changes made to the session in this request cycle

Deletes a request header if present.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Deletes a response cookie.

Deleting a cookie requires the same options as to when the cookie was put. Check put_resp_cookie/4 for more information.

Deletes a response header if present.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Deletes the session for the given key.

The key can be a string or an atom, where atoms are automatically converted to strings.

Fetches cookies from the request headers.

Fetches query parameters from the query string.

This function does not fetch parameters from the body. To fetch parameters from the body, use the Plug.Parsers plug.

Options

• :length - the maximum query string length. Defaults to 1_000_000 bytes.

Fetches the session from the session store. Will also fetch cookies.

Returns the values of the request header specified by key.

Returns the values of the response header specified by key.

Examples

iex> conn = %{conn | resp_headers: [{"content-type", "text/plain"}]}
iex> get_resp_header(conn, "content-type")
["text/plain"]

Returns session value for the given key. If key is not set, nil is returned.

The key can be a string or an atom, where atoms are automatically converted to strings.

Halts the Plug pipeline by preventing further plugs downstream from being invoked. See the docs for Plug.Builder for more information on halting a plug pipeline.

Merges a series of response headers into the connection.

Example

iex> conn = merge_resp_headers(conn, [{"content-type", "text/plain"}, {"X-1337", "5P34K"}])

Prepends the list of headers to the connection response headers.

Similar to put_resp_header this functions adds a new response header (key) but rather then replacing the exising one it prepends another header with the same key.

It is recommended for header keys to be in lower-case, to avoid sending duplicate keys in a request. As a convenience, this is validated during testing which raises a Plug.Conn.InvalidHeaderError if the header key is not lowercase.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Raises a Plug.Conn.InvalidHeaderError if the header value contains control feed (\r) or newline (\n) characters.

Pushes a resource to the client.

Server pushes must happen prior to a response being sent. If a server push is attempted after a response is sent then a Plug.Conn.AlreadySentError will be raised.

If the adapter does not support server push then this is a noop.

Pushes a resource to the client but raises if the adapter does not support server push.

Assigns a new private key and value in the connection.

This storage is meant to be used by libraries and frameworks to avoid writing to the user storage (the :assigns field). It is recommended for libraries/frameworks to prefix the keys with the library name.

For example, if some plug needs to store a :hello key, it should do so as :plug_hello:

iex> conn.private[:plug_hello]
nil
iex> conn = put_private(conn, :plug_hello, :world)
iex> conn.private[:plug_hello]
:world

Adds a new request header (key) if not present, otherwise replaces the previous value of that header with value.

It is recommended for header keys to be in lower-case, to avoid sending duplicate keys in a request. As a convenience, this is validated during testing which raises a Plug.Conn.InvalidHeaderError if the header key is not lowercase.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Sets the value of the "content-type" response header taking into account the charset.

Puts a response cookie.

The cookie value is not automatically escaped. Therefore, if you want to store values with comma, quotes, etc, you need to explicitly escape them or use a function such as Base.encode64(value, padding: false) when writing and Base.decode64(encoded, padding: false) when reading the cookie. Padding needs to be disabled since = is not a valid character in cookie values.

Options

• :domain - the domain the cookie applies to
• :max_age - the cookie max-age, in seconds. Providing a value for this option will set both the max-age and expires cookie attributes
• :path - the path the cookie applies to
• :http_only - when false, the cookie is accessible beyond http
• :secure - if the cookie must be sent only over https. Defaults to true when the connection is https
• :extra - string to append to cookie. Use this to take advantage of non-standard cookie attributes.

Adds a new response header (key) if not present, otherwise replaces the previous value of that header with value.

It is recommended for header keys to be in lower-case, to avoid sending duplicate keys in a request. As a convenience, this is validated during testing which raises a Plug.Conn.InvalidHeaderError if the header key is not lowercase.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Raises a Plug.Conn.InvalidHeaderError if the header value contains control feed (\r) or newline (\n) characters.

Puts the specified value in the session for the given key.

The key can be a string or an atom, where atoms are automatically converted to strings. Can only be invoked on unsent conns. Will raise otherwise.

Stores the given status code in the connection.

The status code can be nil, an integer or an atom. The list of allowed atoms is available in Plug.Conn.Status.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Reads the request body.

This function reads a chunk of the request body up to a given :length. If there is more data to be read, then {:more, partial_body, conn} is returned. Otherwise {:ok, body, conn} is returned. In case of an error reading the socket, {:error, reason} is returned as per :gen_tcp.recv/2.

In order to, for instance, support slower clients you can tune the :read_length and :read_timeout options. These specify how much time should be allowed to pass for each read from the underlying socket.

Because the request body can be of any size, reading the body will only work once, as Plug will not cache the result of these operations. If you need to access the body multiple times, it is your responsibility to store it. Finally keep in mind some plugs like Plug.Parsers may read the body, so the body may be unavailable after being accessed by such plugs.

This function is able to handle both chunked and identity transfer-encoding by default.

Options

• :length - sets the maximum number of bytes to read from the body on every call, 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

The values above are not meant to be exact. For example, setting the length to 8_000_000 may end up reading some hundred bytes more from the socket until we halt.

Examples

{:ok, body, conn} = Plug.Conn.read_body(conn, length: 1_000_000)

Reads the body of a multipart request.

Returns {:ok, body, conn} if all body has been read, {:more, binary, conn} otherwise, and {:done, conn} if there is no more body.

It accepts the same options as read_body/2.

Reads the headers of a multipart request.

It returns {:ok, headers, conn} with the headers or {:done, conn} if there are no more parts.

Once read_part_headers/2 is invoked, a developer may call read_part_body/2 to read the body associated to the headers. If read_part_headers/2 is called instead, the body is automatically skipped until the next part headers.

Options

• :length - sets the maximum number of bytes to read from the body for each chunk, defaults to 64_000 bytes
• :read_length - sets the amount of bytes to read at one time from the underlying socket to fill the chunk, defaults to 64_000 bytes
• :read_timeout - sets the timeout for each socket read, defaults to 5_000ms

Registers a callback to be invoked before the response is sent.

Callbacks are invoked in the reverse order they are defined (callbacks defined first are invoked last).

Returns the full request URL.

Sets the response to the given status and body.

It sets the connection state to :set (if not already :set) and raises Plug.Conn.AlreadySentError if it was already :sent.

Sends the response headers as a chunked response.

It expects a connection that has not been :sent yet and sets its state to :chunked afterwards. Otherwise raises Plug.Conn.AlreadySentError.

Sends a file as the response body with the given status and optionally starting at the given offset until the given length.

If available, the file is sent directly over the socket using the operating system sendfile operation.

It expects a connection that has not been :sent yet and sets its state to :file afterwards. Otherwise raises Plug.Conn.AlreadySentError.

Examples

Plug.Conn.send_file(conn, 200, "README.md")

Sends a response to the client.

It expects the connection state to be :set, otherwise raises an ArgumentError for :unset connections or a Plug.Conn.AlreadySentError for already :sent connections.

At the end sets the connection state to :sent.

Sends a response with the given status and body.

See send_resp/1 for more information.

Updates a request header if present, otherwise it sets it to an initial value.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.

Updates a response header if present, otherwise it sets it to an initial value.

Raises a Plug.Conn.AlreadySentError if the connection has already been :sent or :chunked.