apical
v0.2.1

View Source Apical.Plugs.RequestBody.Source behaviour (apical v0.2.1)

Behaviour for adapters that process request bodies and alter the conn.

Link to this section Summary

Types

validator()

Type for a function that encapsulates the logic for validating a request body.

Callbacks

fetch(t, validator, opts)
validate!(subschema, operation_id)

Compile-time check to see if the validator is valid for the given requestBody subschema.

Functions

fetch_body(conn, opts)

Utility function that grabs request bodies.

Link to this section Types

Link to this type

validator()

View Source 
@type validator() :: nil | {module(), atom()} | {module(), atom(), keyword()}

Type for a function that encapsulates the logic for validating a request body.

The function should return :ok if the body is valid, or {:error, keyword}

In the generic case, keyword should contain the key :message which determines what the request body error message will be.

For more specific cases, see the documentation for Exonerate which describes the fields available.

The default validator (if no validation is to be performed) will return :ok on any input.

Link to this section Callbacks

Link to this callback

fetch(t, validator, opts)

View Source 
@callback fetch(Plug.Conn.t(), validator(), opts :: keyword()) ::
  {:ok, Plug.Conn.t()} | {:error, keyword()}
Link to this callback

validate!(subschema, operation_id)

View Source 
@callback validate!(subschema :: map(), operation_id :: String.t()) :: :ok

Compile-time check to see if the validator is valid for the given requestBody subschema.

This may reject for any reason and should raise a CompileError if the validator cannot be used for that subschema.

Link to this section Functions

Link to this function

fetch_body(conn, opts)

View Source 
@spec fetch_body(
  Plug.Conn.t(),
  keyword()
) :: {:ok, body :: iodata(), Plug.Conn.t()} | {:error, any()}

Utility function that grabs request bodies.

Apical.Plugs.RequestBody.Source modules are expected to use this function if they need the request body, since it conforms to the options keyword that plug uses natively. This function will exhaust the ability of the conn to have its body fetched. Thus, the use of this function is not required

streaming-request-bodies

 Streaming request bodies

If the request body source plugin processes data in a streaming fashion, this function should not be used, instead manually call Plug.Conn.read_body/2 in your plugin's fetch/3 function

options

 options

:length (integer, default 8_000_000) - total maximum length of the request body. :read_length (integer, default 1_000_000) - maximum length of each chunk. :string (boolean, default false) - if true, the result will be a single binary, if false, the result may be an improper iolist.