AshHooks.BodyReader (AshHooks v3.3.0)

Copy Markdown View Source

Endpoint body_reader that caches the raw, pre-parser request bytes for signature verification.

Configure it as the body_reader of the endpoint's Plug.Parsers, {AshHooks.BodyReader, :read_body, []} (the installer patches this; a router plug cannot recover pre-parse bytes). The README's Mounting the plug section shows the endpoint and router; the test suite compiles and runs that example as written.

AshHooks.Plug retrieves the cached bytes through raw_body/1 automatically. Custom pipelines may pass raw_body(conn) to AshHooks.Ingress.ingest/4. Signature schemes sign over the exact wire bytes, so any re-encoding (parsed params, JSON roundtrip) would break verification. Without a preceding parser, AshHooks.Plug can read the request body itself.

The reader is endpoint-wide by default: every parsed request (not only webhook routes) carries a second copy of its body in the connection cache for the request lifetime, bounded by the parser's :length. To scope the memory cost to the webhook routes, pass :only path prefixes as the reader's arguments, {AshHooks.BodyReader, :read_body, [only: ["/webhooks"]]}. Only requests whose path starts with one of the prefixes are cached; everything else passes through with zero retained bytes.

A host with its own endpoint reader does not need a second reader. Call put_raw_body/2 from that reader (configured as Plug.Parsers' body_reader), or before parsing, with the complete body exactly as sent. Never supply a partial body or reconstruct bytes from parsed params. The storage key is an implementation detail; use put_raw_body/2 and raw_body/1 to exchange bytes.

Summary

Functions

Stores the complete, exact request body for signature verification.

Returns the stored exact request bytes, or nil when none have been stored.

body_reader entry point. Plug.Parsers invokes the configured MFA as apply(mod, fun, [conn, opts | extra_args]); extras arrive as a THIRD positional argument, so the arity-3 clause is the one the parser calls; opts and extra merge.

Functions

put_raw_body(conn, bytes)

@spec put_raw_body(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Stores the complete, exact request body for signature verification.

Call this from a host's own Plug.Parsers body_reader, or before parsing, with the whole body as sent. Never supply a partial or re-encoded body. Returns the updated connection. Raises ArgumentError unless bytes is a binary; an empty binary is a valid body.

raw_body(conn)

@spec raw_body(Plug.Conn.t()) :: binary() | nil

Returns the stored exact request bytes, or nil when none have been stored.

Use after the endpoint body reader has completed, or after a host has stored the complete body with put_raw_body/2. The connection storage key is private.

read_body(conn, opts, extra \\ [])

@spec read_body(Plug.Conn.t(), keyword(), keyword() | {atom(), term()}) ::
  {:ok, binary(), Plug.Conn.t()}
  | {:more, binary(), Plug.Conn.t()}
  | {:error, term()}

body_reader entry point. Plug.Parsers invokes the configured MFA as apply(mod, fun, [conn, opts | extra_args]); extras arrive as a THIRD positional argument, so the arity-3 clause is the one the parser calls; opts and extra merge.