Plug.Conn

Parsed documentation:
View on GitHub
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

Those fields contain request information:

* `host` - the requested host as a binary, example: `"www.example.com"`
* `method` - the request method as a binary, example: `"GET"`
* `path_info` - the path split into segments, example: `["hello", "world"]`
* `script_name` - the initial portion of the URL's path that corresponds to the application
  routing, as segments, example: ["sub","app"]. It can be used to recover the `full_path/1`
* `port` - the requested port as an integer, example: `80`
* `peer` - the actual TCP peer that connected, example: `{{127, 0, 0, 1}, 12345}`. Often this
  is not the actual IP and port of the client, but rather of a load-balancer or request-router.
* `remote_ip` - the IP of the client, example: `{151, 236, 219, 228}`. This field is meant to
  be overwritten by plugs that understand e.g. the `X-Forwarded-For` header or HAProxy's PROXY
  protocol. It defaults to peer's IP.
* `req_headers` - the request headers as a list, example: `[{"content-type", "text/plain"}]`
* `scheme` - the request scheme as an atom, example: `:http`
* `query_string` - the request query string as a binary, example: `"foo=bar"`

## Fetchable fields

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

* `cookies`- the request cookies with the response cookies
* `params` - the request params
* `req_cookies` - the request cookies (without the response ones)

## Response fields

Those fields contain response information:

* `resp_body` - the response body, by default is an empty string. It is set
  to nil after the response is set, except for test connections.
* `resp_charset` - the response charset, defaults to "utf-8"
* `resp_cookies` - the response cookies with their name and options
* `resp_headers` - the response headers as a dict, by default `cache-control`
  is set to `"max-age=0, private, must-revalidate"`
* `status` - the response status

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

* `assigns` - shared user data as a dict
* `owner` - the Elixir process that owns the connection
* `halted` - the boolean status on whether the pipeline was halted
* `secret_key_base` - a secret key used to verify and encrypt cookies.
  the field must be set manually whenever one of those features are used.
  This data must be kept in the connection and never used directly, always
  use `Plug.Crypto.KeyGenerator.generate/3` to derive keys from it
* `state` - the connection state

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.

* `adapter` - holds the adapter information in a tuple
* `private` - shared library data as a dict
Suggestions:
Please help! Open an issue on GitHub if this assessment is incorrect.