Plug v1.10.0 Plug.Conn.Adapter behaviour View Source

Specification of the connection adapter API implemented by webservers.

All adapters are required to emit the proper plug_adapter.request.start, plug_adapter.request.stop and plug_adapter.request.failure telemetry events on every request.

Link to this section Summary

Types

http_protocol()

payload()

peer_data()

Callbacks

chunk(payload, arg2)

Sends a chunk in the chunked response.

get_http_protocol(payload)

Returns the HTTP protocol and its version.

get_peer_data(payload)

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

inform(payload, arg2, headers)

Send an informational response to the client.

push(payload, path, headers)

Push a resource to the client.

read_req_body(payload, options)

Reads the request body.

send_chunked(payload, arg2, arg3)

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

send_file(payload, arg2, arg3, file, offset, length)

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

send_resp(payload, arg2, arg3, arg4)

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

Link to this section Types

http_protocol()

http_protocol() :: :"HTTP/1" | :"HTTP/1.1" | :"HTTP/2" | atom()

payload()

payload() :: term()

peer_data()

peer_data() :: %{
  address: :inet.ip_address(),
  port: :inet.port_number(),
  ssl_cert: binary() | nil
}

Link to this section Callbacks

chunk(payload, arg2)

chunk(payload(), Plug.Conn.body()) ::
  :ok | {:ok, sent_body :: binary(), 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 :ok and not modify any further state for each chunk. However, the test implementation returns the actual body and payload so it can be used during testing.

get_http_protocol(payload)

get_http_protocol(payload()) :: http_protocol()

Returns the HTTP protocol and its version.

get_peer_data(payload)

get_peer_data(payload()) :: peer_data()

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

inform(payload, arg2, headers)

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

Send an informational response to the client.

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

push(payload, path, headers)

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.

read_req_body(payload, options)

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.

send_chunked(payload, arg2, arg3)

send_chunked(payload(), Plug.Conn.status(), 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, as the body can no longer be manipulated. However, the test implementation returns the actual body so it can be used during testing.

send_file(payload, arg2, arg3, file, offset, length)

send_file(
  payload(),
  Plug.Conn.status(),
  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.

send_resp(payload, arg2, arg3, arg4)

send_resp(payload(), Plug.Conn.status(), Plug.Conn.headers(), 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.