RequestSeal.Req (RequestSeal v0.2.0)

Copy Markdown View Source

Optional Req final-attempt signing and verification before body decoding.

attach/2 requires sign, signer, and explicit verify: :none or a map containing policy, label, and a nonnegative max_stream_bytes. The specification is documented in RequestSeal.Finch. Optional signing_timeout defaults to 5,000 ms; clock to system seconds; request_body to :as_is or explicit {:retain, max}. Retention replaces a stream with replayable bytes before transport. Every attempt removes only this adapter's previously appended values, then regenerates parameters.

redirect defaults to :same_origin; {:allow, [origin]} permits explicit cross-origin targets. Allowed cross-origin requests strip authorization, cookie, proxy-authorization, and caller-declared credential_headers, even with Req's redirect_trusted. credential_headers defaults to [] and accepts at most 64 HTTP header names of at most 256 bytes, case insensitive. Origin includes scheme, host, and port. Req's own redirect/retry choices still govern whether another attempt runs. Signing must remain the last request step; a later step rejects before transport. Only Req's Finch adapter is supported; framework hooks that can mutate transport bytes after signing reject.

When required, verification is the first response step, before retry, HTTP errors, redirect, digest auth, decompression, or decoding. Each intermediate response must satisfy the selected policy: unsigned 3xx/5xx responses fail closed without redirecting or retrying. It uses the exact sent Message once per response. verification/1 retrieves the result stored in response private metadata. A rejection returns a bounded RequestSeal.Adapter.Error with :response_rejected, never a response body.

into: :self and :legacy_self reject. All verified delivery, including synchronous responses, uses a collector with explicit max_stream_bytes: overflow stops transport before complete buffering with :limit. Chunks are buffered within that bound and hashed when policy requires content integrity; automatic streams refuse caller-selected representation hashing. The original destination receives chunks only after verification. Collectables are opened only after success. Req checksum wrappers with streaming destinations reject. Verified delivery also refuses Req cache handling, http_errors: :raise, and custom response steps before verification, since these can consume or expose unverified bodies. With verify: :none, ordinary synchronous delivery retains Req's semantics without a verification claim. Unknown/duplicate options reject. No pool, server, or background fetch starts.

Supported Req options (checked at attachment, before request steps, and at final signing): user_agent, compressed, range, base_url, params, path_params, path_params_style, auth (except digest), form, form_multipart, json, compress_body, checksum, raw, http_errors, decode_body, decoders, decode_json, redirect, redirect_trusted, redirect_log_level, max_redirects, retry, retry_delay, retry_log_level, max_retries, cache, cache_dir, finch, request_timeout, receive_timeout, pool_timeout, follow_redirects, location_trusted, and redact_auth. URL, method, headers, body, and into are Req struct fields. Verification imposes the delivery restrictions described above. finch accepts only an explicit caller-owned name and optional pool_timeout, receive_timeout, and request_timeout; configure trusted pool connections when starting the caller-owned pool. Caller-supplied Host, connection overrides, proxies, UNIX sockets, Finch private metadata and pool options, IPv6 overrides, and Req's aws_sigv4 option reject with :invalid_options.

Summary

Functions

attach(request, opts)

@spec attach(Req.Request.t(), keyword()) ::
  {:ok, Req.Request.t()} | {:error, RequestSeal.Adapter.Error.t()}

verification(arg1)

@spec verification(Req.Response.t()) :: {:ok, RequestSeal.Verification.t()} | :error