plug v0.8.1 → Overview → Plug → Conn

Plug.Conn

The Plug connection.

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

All the struct fields are defined below. Note both request and response headers are expected to have lower-case keys.

Request fields

Those fields contain request information:

Fetchable fields

Those fields contain request information and they need to be explicitly fetched. Before fetching those fields return a Plug.Conn.Unfetched record.

Response fields

Those 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 mimic a Plug stack behaviour.

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

Those fields are reserved for libraries/framework usage.

Summary
↑

assign(conn, key, value)

Assigns a new key and value in the connection
chunk(conn, chunk)

Sends a chunk as part of a chunked response
configure_session(conn, opts)

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

Deletes a response cookie
delete_resp_header(conn, key)

Deletes a response header
delete_session(conn, key)

Deletes session for given key
fetch_cookies(conn, opts \\ [])

Fetches cookies from the request headers
fetch_params(conn, opts \\ [])

Fetches parameters from the query string
fetch_session(conn, opts \\ [])

Fetches session from session store. Will also fetch cookies
get_req_header(conn, key)

Gets a request header
get_resp_header(conn, key)

Gets a response header
get_session(conn, key)

Returns session value for given key
halt(conn)

Halts the Plug stack by preventing further plugs downstream from being invoked
put_private(conn, key, value)

Assigns a new private key and value in the connection
put_resp_content_type(conn, content_type, charset \\ "utf-8")

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

Puts a new response header
put_session(conn, key, value)

Puts specified value in session for 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 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 given status and body

Types ↑

adapter :: {module, term}

assigns :: %{atom => any}

before_send :: [(t -> t)]

body :: iodata | nil

cookies :: %{binary => binary} | Plug.Conn.Unfetched.t

halted :: boolean

headers :: [{binary, binary}]

host :: binary

int_status :: non_neg_integer | nil

method :: binary

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

params :: %{binary => param}

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

query_string :: String.t

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, cookies: cookies, host: host, method: method, params: params | Plug.Conn.Unfetched.t, path_info: segments, port: 0 .. 65335, private: assigns, query_string: query_string, peer: peer, remote_ip: :inet.ip_address, req_cookies: cookies, req_headers: headers, 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)
(function) # ↑

Specs:

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

Assigns a new key and value in the connection.

Examples

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

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, returns {:ok, conn} in case of success, otherwise {:error, reason}.

configure_session(conn, opts)
(function) # ↑

Specs:

Configures 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;
delete_resp_cookie(conn, key, opts \\ [])
(function) # ↑

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.

delete_resp_header(conn, key)
(function) # ↑

Specs:

  • delete_resp_header(t, binary) :: t

Deletes a response header.

delete_session(conn, key)
(function) # ↑

Specs:

  • delete_session(t, any) :: t

Deletes session for given key.

fetch_cookies(conn, opts \\ [])
(function) # ↑

Specs:

Fetches cookies from the request headers.

fetch_params(conn, opts \\ [])
(function) # ↑

Specs:

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

fetch_session(conn, opts \\ [])
(function) # ↑

Specs:

Fetches session from session store. Will also fetch cookies.

get_req_header(conn, key)
(function) # ↑

Specs:

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

Gets a request header.

get_resp_header(conn, key)
(function) # ↑

Specs:

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

Gets a response header.

get_session(conn, key)
(function) # ↑

Specs:

  • get_session(t, any) :: any

Returns session value for given key.

halt(conn)
(function) # ↑

Specs:

  • halt(t) :: t

Halts the Plug stack by preventing further plugs downstream from being invoked

put_private(conn, key, value)
(function) # ↑

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 (assigns). It is recommended for libraries/frameworks to prefix the keys by 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
put_resp_content_type(conn, content_type, charset \\ "utf-8")
(function) # ↑

Specs:

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

Puts the content-type response header taking into account the charset.

put_resp_cookie(conn, key, value, opts \\ [])
(function) # ↑

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;
  • :secure - if the cookie must be sent only over https;
put_resp_header(conn, key, value)
(function) # ↑

Specs:

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

Puts a new response header.

put_session(conn, key, value)
(function) # ↑

Specs:

  • put_session(t, any, any) :: t

Puts specified value in session for given key.

put_status(conn, status)
(function) # ↑

Specs:

Stores the given status code in the connection.

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

read_body(conn, opts \\ [])
(function) # ↑

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 15000ms;

Example

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

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

resp(conn, status, body)
(function) # ↑

Specs:

Sets the response to given status and body.

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

send_chunked(conn, status)
(function) # ↑

Specs:

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

Sends the response headers as a chunked response.

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

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

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 was not yet :sent and sets its state to :sent afterwards. Otherwise raises Plug.Conn.AlreadySentError.

send_resp(conn)
(function) # ↑

Specs:

  • send_resp(t) :: t | no_return

Sends a response to the client.

It expects the connection state is to be :set, otherwise raises ArgumentError for :unset connections or Plug.Conn.AlreadySentError if it was already sent.

At the end sets the connection state to :sent.

send_resp(conn, status, body)
(function) # ↑

Specs:

Sends a response with given status and body.

See send_resp/1 for more information.