Plug

v1.7.2

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

Specification of the connection adapter API implemented by webservers

Link to this section Summary

Types

http_protocol()
payload()
peer_data()

Callbacks

chunk(payload, arg1)

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, arg1, 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, arg1, arg2)

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

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

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

send_resp(payload, arg1, arg2, arg3)

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

Link to this section Types

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

Link to this section Callbacks

Link to this callback chunk(payload, arg1) View Source 
chunk(payload(), Plug.Conn.status()) ::
  :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.

Link to this callback get_http_protocol(payload) View Source 
get_http_protocol(payload()) :: http_protocol()

Returns the HTTP protocol and its version.

Link to this callback get_peer_data(payload) View Source 
get_peer_data(payload()) :: peer_data()

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

Link to this callback inform(payload, arg1, headers) View Source 
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.

Link to this callback push(payload, path, headers) View Source 
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 
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, arg1, arg2) View Source 
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.

Link to this callback send_file(payload, arg1, arg2, file, offset, length) View Source 
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.

Link to this callback send_resp(payload, arg1, arg2, arg3) View Source 
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.