Behaviour for adapters that process request bodies and alter the conn.
Summary
Types
Type for marshal context that contains type information for marshalling request body values from strings to their proper types.
Type for a function that encapsulates the logic for validating a request body.
Callbacks
Fetches and processes the request body.
Compile-time check to see if the validator is valid for the given requestBody subschema.
Functions
Utility function that grabs request bodies.
Types
@type marshal_context() :: map() | nil
Type for marshal context that contains type information for marshalling request body values from strings to their proper types.
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.
Callbacks
@callback fetch(Plug.Conn.t(), validator(), marshal_context(), opts :: keyword()) :: {:ok, Plug.Conn.t()} | {:error, keyword()}
Fetches and processes the request body.
The marshal_context parameter contains type information extracted from the schema that can be used to convert string values to their proper types (e.g., "42" to 42).
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.
Functions
@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
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 c:fetch/3 function
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.