Plug.Conn

The Plug connection.

This module defines a Plug.Conn struct and the main functions for working with Plug connections.

Note request headers are normalized to lowercase and response headers are expected to have lower-case keys.

Request fields

These fields contain request information:

Fetchable fields

The request information in these fields is not populated until it is fetched using the associated fetch_ function. For example, the cookies field uses fetch_cookies/2.

If you access these fields before fetching them, they will be returned as Plug.Conn.Unfetched structs.

Response fields

These fields contain response information:

Furthermore, the before_send field stores callbacks that are invoked before the connection is sent. Callbacks are invoked in the reverse order they are registered (callbacks registered first are invoked last) in order to reproduce a pipeline ordering.

Connection fields

The connection state is used to track the connection lifecycle. It starts as :unset but is changed to :set (via Plug.Conn.resp/3) or :file (when invoked via Plug.Conn.send_file/3). Its final result is :sent or :chunked depending on the response model.

Private fields

These fields are reserved for libraries/framework usage.

Protocols

Plug.Conn implements both the Collectable and Inspect protocols out of the box. The inspect protocol provides a nice representation of the connection while the collectable protocol allows developers to easily chunk data. For example:

# Send the chunked response headers
conn = send_chunked(conn, 200)

# Pipe the given list into a connection
# Each item is emitted as a chunk
Enum.into(~w(each chunk as a word), conn)
Source

Summary

assign(conn, key, value)

Assigns a value to a key in the connection

async_assign(conn, key, fun)

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

await_assign(conn, key, timeout \\ 5000)

Awaits the completion of an async assign

chunk(conn, chunk)

Sends a chunk as part of a chunked response

clear_session(conn)

Clears the entire session

configure_session(conn, opts)

Configures the session

delete_req_header(conn, key)

Deletes a request header if present

delete_resp_cookie(conn, key, opts \\ [])

Deletes a response cookie

delete_resp_header(conn, key)

Deletes a response header if present

delete_session(conn, key)

Deletes the session for the given key

fetch_cookies(conn, opts \\ [])

Fetches cookies from the request headers

fetch_query_params(conn, opts \\ [])

Fetches query parameters from the query string

fetch_session(conn, opts \\ [])

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

get_req_header(conn, key)

Returns the values of the request header specified by key

get_resp_header(conn, key)

Returns the values of the response header specified by key

get_session(conn, key)

Returns session value for the given key

halt(conn)

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

merge_resp_headers(conn, headers)

Merges a series of response headers into the connection

put_private(conn, key, value)

Assigns a new private key and value in the connection

put_req_header(conn, key, value)

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

put_resp_content_type(conn, content_type, charset \\ "utf-8")

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

put_resp_cookie(conn, key, value, opts \\ [])

Puts a response cookie

put_resp_header(conn, key, value)

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

put_session(conn, key, value)

Puts the specified value in the session for the given key

put_status(conn, status)

Stores the given status code in the connection

read_body(conn, opts \\ [])

Reads the request body

register_before_send(conn, callback)

Registers a callback to be invoked before the response is sent

resp(conn, status, body)

Sets the response to the given status and body

send_chunked(conn, status)

Sends the response headers as a chunked response

send_file(conn, status, file, offset \\ 0, length \\ :all)

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

send_resp(conn)

Sends a response to the client

send_resp(conn, status, body)

Sends a response with the given status and body

update_req_header(conn, key, initial, fun)

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

update_resp_header(conn, key, initial, fun)

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

Types

adapter :: {module, term}

assigns :: %{atom => any}

before_send :: [(t -> t)]

body :: iodata | nil

cookies :: %{binary => binary}

halted :: boolean

headers :: [{binary, binary}]

host :: binary

int_status :: non_neg_integer | nil

owner :: pid

method :: binary

param :: binary | %{binary => param} | [param]

params :: %{binary => param}

peer :: {:inet.ip_address, :inet.port_number}

port_number :: :inet.port_number

resp_cookies :: %{binary => %{}}

scheme :: :http | :https

secret_key_base :: binary | nil

segments :: [binary]

state :: :unset | :set | :file | :chunked | :sent

status :: atom | int_status

t :: %Plug.Conn{adapter: adapter, assigns: assigns, before_send: before_send, body_params: params | Plug.Conn.Unfetched.t, cookies: cookies | Plug.Conn.Unfetched.t, host: host, method: method, owner: owner, params: params | Plug.Conn.Unfetched.t, path_info: segments, port: :inet.port_number, private: assigns, query_params: params | Plug.Conn.Unfetched.t, query_string: query_string, peer: peer, remote_ip: :inet.ip_address, req_cookies: cookies | Plug.Conn.Unfetched.t, req_headers: headers, request_path: binary, resp_body: body, resp_cookies: resp_cookies, resp_headers: headers, scheme: scheme, script_name: segments, secret_key_base: secret_key_base, state: state, status: int_status, halted: term}

Functions

assign(conn, key, value)

Specs:

  • assign(t, atom, term) :: t

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
Source
async_assign(conn, key, fun)

Specs:

  • async_assign(t, atom, (() -> term)) :: t

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{...}
Source
await_assign(conn, key, timeout \\ 5000)

Specs:

  • await_assign(t, atom, timeout) :: t

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
Source
chunk(conn, chunk)

Specs:

  • chunk(t, body) :: {:ok, t} | {:error, term} | no_return

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}.

Source
clear_session(conn)

Specs:

  • clear_session(t) :: t

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.

Source
configure_session(conn, opts)

Specs:

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
Source
delete_req_header(conn, key)

Specs:

  • delete_req_header(t, binary) :: t

Deletes a request header if present.

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

Source
delete_resp_cookie(conn, key, opts \\ [])

Specs:

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.

Source
delete_resp_header(conn, key)

Specs:

  • delete_resp_header(t, binary) :: t

Deletes a response header if present.

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

Source
delete_session(conn, key)

Specs:

Deletes the session for the given key.

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

Source
fetch_cookies(conn, opts \\ [])

Specs:

Fetches cookies from the request headers.

Source
fetch_query_params(conn, opts \\ [])

Specs:

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.

Source
fetch_session(conn, opts \\ [])

Specs:

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

Source
get_req_header(conn, key)

Specs:

  • get_req_header(t, binary) :: [binary]

Returns the values of the request header specified by key.

Source
get_resp_header(conn, key)

Specs:

  • get_resp_header(t, binary) :: [binary]

Returns the values of the response header specified by key.

Examples

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

Specs:

Returns session value for the given key.

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

Source
halt(conn)

Specs:

  • halt(t) :: t

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.

Source
merge_resp_headers(conn, headers)

Specs:

Merges a series of response headers into the connection.

Source
put_private(conn, key, value)

Specs:

  • put_private(t, atom, term) :: t

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
Source
put_req_header(conn, key, value)

Specs:

  • put_req_header(t, binary, binary) :: t

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

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

Source
put_resp_content_type(conn, content_type, charset \\ "utf-8")

Specs:

  • put_resp_content_type(t, binary, binary | nil) :: t

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

Source
put_resp_cookie(conn, key, value, opts \\ [])

Specs:

Puts a response cookie.

Options

  • :domain - the domain the cookie applies to
  • :max_age - the cookie max-age
  • :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
Source
put_resp_header(conn, key, value)

Specs:

  • put_resp_header(t, binary, binary) :: t

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

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

Source
put_session(conn, key, value)

Specs:

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.

Source
put_status(conn, status)

Specs:

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.

Source
read_body(conn, opts \\ [])

Specs:

  • read_body(t, Keyword.t) :: {:ok, binary, t} | {:more, binary, t} | {:error, term}

Reads the request body.

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

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 accessing such plugs.

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

Options

  • :length - sets the max body length to read, defaults to 8_000_000 bytes;
  • :read_length - set the amount of bytes to read at one time, defaults to 1_000_000 bytes;
  • :read_timeout - set the timeout for each chunk received, defaults to 15_000 ms;

Examples

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

Specs:

  • register_before_send(t, (t -> t)) :: t

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).

Source
resp(conn, status, body)

Specs:

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.

Source
send_chunked(conn, status)

Specs:

  • send_chunked(t, status) :: t | no_return

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.

Source
send_file(conn, status, file, offset \\ 0, length \\ :all)

Specs:

  • send_file(t, status, filename :: binary, offset :: integer, length :: integer | :all) :: t | no_return

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 :sent afterwards. Otherwise raises Plug.Conn.AlreadySentError.

Source
send_resp(conn)

Specs:

  • send_resp(t) :: t | no_return

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.

Source
send_resp(conn, status, body)

Specs:

Sends a response with the given status and body.

See send_resp/1 for more information.

Source
update_req_header(conn, key, initial, fun)

Specs:

  • update_req_header(t, binary, binary, (binary -> binary)) :: t

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.

Source
update_resp_header(conn, key, initial, fun)

Specs:

  • update_resp_header(t, binary, binary, (binary -> binary)) :: t

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.

Source