# `AshHooks.BodyReader`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/body_reader.ex#L5)

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](README.md#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.

# `put_raw_body`

```elixir
@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`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
