View Source Plug.Conn.Adapter behaviour (Plug v1.16.0)

Specification of the connection adapter API implemented by webservers.

Summary

Callbacks

Sends a chunk in the chunked response.

Returns the HTTP protocol and its version.

Returns peer information such as the address, port and ssl cert.

Send an informational response to the client.

Push a resource to the client.

Reads the request body.

Sends the given status, headers as the beginning of a chunked response to the client.

Sends the given status, headers and file as a response back to the client.

Sends the given status, headers and body as a response back to the client.

Attempt to upgrade the connection with the client.

Functions

Function used by adapters to create a new connection.

Types

@type http_protocol() :: :"HTTP/1" | :"HTTP/1.1" | :"HTTP/2" | atom()
@type payload() :: term()
@type peer_data() :: %{
  address: :inet.ip_address(),
  port: :inet.port_number(),
  ssl_cert: binary() | nil
}

Callbacks

@callback chunk(payload(), body :: Plug.Conn.body()) ::
  :ok | {:ok, sent_body :: binary() | nil, payload()} | {:error, term()}

Sends a chunk in the chunked response.

If the request has method "HEAD", the adapter should not send the response to the client.

Webservers are advised to return nil as the sent_body, since the complete sent body depends on the sum of all calls to this function. However, the test implementation tracks the overall body and payload so it can be used during testing.

Link to this callback

get_http_protocol(payload)

View Source
@callback get_http_protocol(payload()) :: http_protocol()

Returns the HTTP protocol and its version.

@callback get_peer_data(payload()) :: peer_data()

Returns peer information such as the address, port and ssl cert.

Link to this callback

inform(payload, status, headers)

View Source
@callback inform(payload(), status :: Plug.Conn.status(), headers :: Keyword.t()) ::
  :ok | {:ok, payload()} | {:error, term()}

Send an informational response to the client.

If the adapter does not support inform, then {:error, :not_supported} should be returned.

Link to this callback

push(payload, path, headers)

View Source
@callback push(payload(), path :: String.t(), headers :: Keyword.t()) ::
  :ok | {:error, term()}

Push a resource to the client.

If the adapter does not support server push then {:error, :not_supported} should be returned.

Link to this callback

read_req_body(payload, options)

View Source
@callback read_req_body(payload(), options :: Keyword.t()) ::
  {:ok, data :: binary(), payload()}
  | {:more, data :: binary(), payload()}
  | {:error, term()}

Reads the request body.

Read the docs in Plug.Conn.read_body/2 for the supported options and expected behaviour.

Link to this callback

send_chunked(payload, status, headers)

View Source
@callback send_chunked(
  payload(),
  status :: Plug.Conn.status(),
  headers :: Plug.Conn.headers()
) ::
  {:ok, sent_body :: binary() | nil, payload()}

Sends the given status, headers as the beginning of a chunked response to the client.

Webservers are advised to return nil as the sent_body, since this function does not actually produce a body. However, the test implementation returns an empty binary as the body in order to be consistent with the built-up body returned by subsequent calls to the test implementation's chunk/2 function

Link to this callback

send_file(payload, status, headers, file, offset, length)

View Source
@callback send_file(
  payload(),
  status :: Plug.Conn.status(),
  headers :: Plug.Conn.headers(),
  file :: binary(),
  offset :: integer(),
  length :: integer() | :all
) :: {:ok, sent_body :: binary() | nil, payload()}

Sends the given status, headers and file as a response back to the client.

If the request has method "HEAD", the adapter should not send the response to the client.

Webservers are advised to return nil as the sent_body, as the body can no longer be manipulated. However, the test implementation returns the actual body so it can be used during testing.

Link to this callback

send_resp(payload, status, headers, body)

View Source
@callback send_resp(
  payload(),
  status :: Plug.Conn.status(),
  headers :: Plug.Conn.headers(),
  body :: Plug.Conn.body()
) :: {:ok, sent_body :: binary() | nil, payload()}

Sends the given status, headers and body as a response back to the client.

If the request has method "HEAD", the adapter should not send the response to the client.

Webservers are advised to return nil as the sent_body, as the body can no longer be manipulated. However, the test implementation returns the actual body so it can be used during testing.

Link to this callback

upgrade(payload, protocol, opts)

View Source
@callback upgrade(payload(), protocol :: atom(), opts :: term()) ::
  {:ok, payload()} | {:error, term()}

Attempt to upgrade the connection with the client.

If the adapter does not support the indicated upgrade, then {:error, :not_supported} should be be returned.

If the adapter supports the indicated upgrade but is unable to proceed with it (due to a negotiation error, invalid opts being passed to this function, or some other reason), then an arbitrary error may be returned. Note that an adapter does not need to process the actual upgrade within this function; it is a wholly supported failure mode for an adapter to attempt the upgrade process later in the connection lifecycle and fail at that point.

Functions

Link to this function

conn(adapter, method, uri, remote_ip, req_headers)

View Source

Function used by adapters to create a new connection.