# `AshHooks.Worker`
[🔗](https://github.com/baselabs/ash_hooks/blob/v3.3.0/lib/ash_hooks/worker.ex#L1)

Defines an Oban worker in the consuming application. Define the worker in
your application when Oban is installed. The package also compiles and works
without Oban; use `AshHooks.Delivery.run/2` for direct delivery.

<!-- not-run: This worker requires host delivery and endpoint resources, a secret resolver, and an Oban instance. -->

    defmodule MyApp.WebhookDeliveryWorker do
      use AshHooks.Worker,
        deliveries: MyApp.OutboundDelivery,
        endpoints: MyApp.WebhookEndpoint,
        secret_resolver: {MyApp.Secrets, :webhook_secret},
        queue: :webhooks,
        oban: MyApp.Oban
    end

Consumers pass `enqueue: {MyApp.WebhookDeliveryWorker, :enqueue}` to
`AshHooks.dispatch/4`; the generated `enqueue/2` is that seam.

Multitenant jobs store the row's tenant in `args["tenant"]`. The tenant must
survive Oban's JSON encoding unchanged: strings (UUIDs and slugs) and integers
do; an atom arrives as a string. Pair a custom `parse_attribute` with
`tenant_from_attribute` so the stored attribute and job tenant round-trip.
Use `args->>'tenant'`, the tenant's text form, in the runtime role's job
policies. The queue engine needs separate policies over all job and peer rows.

Enqueue inserts in a bounded phase after the delivery persists. Configure
the Oban instance with the ledger's repo to share its tenant binding. When
PostgreSQL job tables use forced row security, configure the `oban:` instance
with queues, plugins, peer leadership, and staging disabled. Run
queues and maintenance through a second instance on an engine-role repo
with the same prefix and PostgreSQL notifier. `perform/1` binds its own
tenant phases through the ledger repo. See the
[row-level security guide](row-security.md) for SQL and supervision entries.

Options:

  * `:deliveries`, `:endpoints` (required): the consumer's resource
    modules carrying the `AshHooks.OutboundDelivery` / `AshHooks.Endpoint`
    extensions.
  * `:attempts` (optional): the consumer's resource module carrying
    `AshHooks.OutboundAttempt`: when set, every delivery attempt records
    a durable history row (time, outcome, classified reason, HTTP
    status, latency, the signing key reference; per-endpoint-opt-in
    response capture) beside the delivery row. A history write failure
    never fails the send; it surfaces as
    `[:ash_hooks, :attempt, :record_failed]` telemetry.
  * `:secret_resolver` (optional, `{m, f}`): resolves an endpoint's
    secret reference: `f(ref) :: {:ok, secret_binary} | {:error, term}`.
    The returned value signs the Standard Webhooks envelope
    (`whsk_` selects Ed25519; `whsec_` selects HMAC-SHA256); legacy envelopes,
    when the signing mode uses them, are
    signed from the endpoint's `legacy_secret_ref` /
    `legacy_previous_secret_ref` references through this same resolver.
    Custody slots use the endpoint resource's custodian and kind markers;
    no worker custodian option is needed. Omit this resolver when every slot
    uses custody or the endpoint declares its own byte resolver.
    `key_material: :custody_only` refuses this option at compile time.
  * `:tenant_aware_secrets` (optional, default `false`): switches the
    resolver contract to 2-arity: `f(ref, tenant)`. The tenant is the
    run's args-threaded tenant (the delivery row's tenant, serialized at
    enqueue). Explicit, no arity magic: the default 1-arity contract is
    unchanged.
  * `:snippet_redactor` (`{m, f}`, optional): a consumer callback run
    on the raw captured body ahead of the package's snippet floor
    (domain-specific tokens need raw input). Only consulted on per-call
    `snippet_capture: true` diagnostic runs; a crash or invalid return
    degrades to the sanitized summary, never raw bytes. The capture
    flag is not a macro option. Enable diagnostic capture through a direct
    `AshHooks.Delivery.run/2` call.
  * `:destination_policy` (`{module, function}`, optional): the public
    send-time destination policy seam (`AshHooks.DestinationPolicy`):
    the callback receives the endpoint's URL and a context map
    (`%{endpoint_id:, tenant:}`) and returns `:allow` (skip the packaged
    SSRF gate; pair it with the adapter's validation override for
    destinations that check would refuse), `:deny` (terminal
    `destination_denied`), or `:default` (the packaged tri-state check
    runs unchanged). A crashing or out-of-vocabulary callback is
    contained as a retryable `destination_policy_failed`. A configured
    policy takes precedence over the boolean `:ssrf_check` seam.
  * `:transport`: the per-endpoint delivery transport resolver, a
    `{module, function}` called with the endpoint record and tenant (a
    function literal is refused at compile time; the direct delivery
    config also accepts a 2-arity function), returning an
    `AshHooks.Transport` module for one endpoint's
    deliveries (a developer's local forwarder behind a CLI "listen"
    command, for example), or `nil` to keep the HTTP adapter. The same signing,
    attempts, and telemetry apply. A transport module must export `request/5`.
    A resolver that raises, throws, exits, or returns an invalid value
    refuses the attempt as a retryable `transport_resolution` failure,
    without falling back to HTTP or storing or emitting error contents.
  * `:http`: the `AshHooks.Http` adapter (default `AshHooks.Http.Bounded`).
  * `:retryable_statuses`: optional literal list of HTTP statuses/ranges
    that replaces the ordinary retry set. Omit it for 408/429/5xx. 2xx success,
    redirect refusal, and 410 disablement stay fixed.
  * `:delivery_headers`: optional `{module, function}` called with
    `(delivery, endpoint, tenant)` before each send. Return binary header
    pairs. Package signing, content-type, and framing headers cannot be
    overridden. Callback/validation failures retry without sending.
  * `:certificate_pin`: optional `{module, function}` called with
    `(endpoint, tenant)` each attempt. Return a pin supported by
    `AshHooks.Http.Bounded` or `nil` for off. Pin failure is non-retryable;
    a configured pin requires the bounded adapter and HTTPS. Computed
    host-wide pins can also be returned in `:http_opts`.
  * `:http_opts`: adapter options as a literal keyword list or a
    `{module, function, args}` callback resolved inside each job's monitored
    delivery deadline. Consumer-trusted config: a literal `timeout:` here
    must stay below `:attempt_timeout` (the macro refuses a larger one),
    and `validate_destination: false` (the test seam loopback listeners
    use) disables the adapter's resolve-and-pin defense, leaving only the
    driver's send-time destination check. The macro refuses to compile a
    literal bypass outside `:test`; never ship it to production.
  * `:oban`: the Oban instance name (default the unnamed instance).
  * `:queue` (default `:ash_hooks`), `:timeout` (35,000 ms), and
    `:max_attempts` (20): Oban Worker options. The job timeout must be
    greater than `:attempt_timeout + :finalization_allowance`, and Oban's
    `:max_attempts` must exceed `:delivery_max_attempts`: error-class
    results (attempt timeout, driver crash, endpoint read errors) consume
    Oban executions in step with row attempts while snooze-class results
    consume none, so only the row ceiling may decide dead-letter.
  * `:attempt_timeout` (25,000 ms) and `:finalization_allowance` (5,000 ms):
    the driver deadline and extra send-lease interval. The attempt budget
    includes endpoint lookup, secret resolution, signing, destination and
    DNS checks, HTTP, and result persistence. A literal `:http_opts`
    `timeout:` must stay below `:attempt_timeout` (the macro refuses a
    larger one; an `{m, f, a}` bundle resolves per-perform and cannot be
    compile-checked). Keep application clocks
    synchronized because lease comparisons use the application clock.
  * `:delivery_max_attempts` (default 10), `:base_backoff_seconds` (2),
    `:max_backoff_seconds` (3600), `:retry_after_cap_seconds` (86_400):
    the row-driven retry policy. Every budget option must be a positive
    integer and `:max_backoff_seconds` at least `:base_backoff_seconds`.
    For direct `AshHooks.Delivery.run/2` calls,
    `:delivery_max_attempts` becomes `:max_attempts`; the other retry option
    names and defaults are unchanged. Omitted worker options use these defaults;
    explicit `nil` budgets are rejected. Direct runner retry options use the
    defaults when omitted or `nil`. The `Retry-After` cap is
    the maximum delay a receiver can request on each attempt. A large
    `Retry-After` can keep a delivery and its job pending for up to the cap
    on each attempt. The default permits 24 hours per attempt.
    Lower the cap when failures need to reach the attempt
    limit sooner. The cap does not alter exponential backoff.
  * `:runtime_config` (`{module, function}`, optional): resolves the
    worker-timing options PER PERFORM: `f(job_args) :: keyword()` returns
    overrides for `:delivery_max_attempts`, `:base_backoff_seconds`,
    `:max_backoff_seconds`, `:retry_after_cap_seconds`, `:attempt_timeout`,
    and `:finalization_allowance`, merged over the compiled defaults (the
    compiled values are defaults; overrides may be lower or higher while
    staying within the compiled job timeout and attempt limits). The Oban job
    `:timeout` and `:max_attempts` stay compile-time (they are Oban Worker
    options baked into the generated module), so the compile-time misfit
    checks re-run at runtime against every resolved set: an override that
    overruns the baked job envelope, meets or exceeds the Oban attempt
    ceiling, is not a positive integer, inverts the backoff ladder,
    collides a literal `:http_opts` `timeout:` with a lowered
    `:attempt_timeout`, or names an unknown key fails
    `perform/1` with `{:error, {:invalid_runtime_config, reason}}` BEFORE
    any delivery work; the row is untouched, Oban re-drives the job, and
    a `[:ash_hooks, :worker, :invalid_runtime_config]` telemetry event
    carries the reason. A callback that raises or returns a non-keyword
    is contained the same way (`:callback_failed`). Raise the compiled
    `:timeout`/`:max_attempts` ceilings to the maximum you will ever
    resolve at runtime, then lower per run.

The generated enqueue uses `fields: [:args]` with the complete delivery
key, delivery and endpoint resource names, source, route, endpoint/event,
and tenant keys. Uniqueness has an infinite period over runnable states
(`available`, `scheduled`, `executing`, and `retryable`). Completed,
canceled, and discarded jobs therefore permit a later recovery trigger.
Enqueue succeeds only after Oban returns a persisted runnable job whose
identity args match the request. Oban.Basic may briefly report a uniqueness
conflict without the winning job's ID while its advisory-lock peer commits;
the generated path retries that result for at most twenty 5 ms waits, then
returns `{:error, :job_not_persisted}`. Before insertion it binds a deferred
route once with a compare-and-set update; a different stored route returns
`{:error, :dispatch_route_conflict}`.
Multitenant jobs store the row's tenant in `args["tenant"]`. The tenant must
survive Oban's JSON encoding unchanged: strings (UUIDs and slugs) and integers
do; an atom arrives as a string. Pair a custom `parse_attribute` with
`tenant_from_attribute` so the stored attribute and job tenant round-trip.
Use `args->>'tenant'`, the tenant's text form, in the runtime role's job
policies, alongside separate engine-role policies over all rows of
`oban_jobs` and `oban_peers`. A tenant-only policy cannot run the queue.

# `resolve_config`

```elixir
@spec resolve_config(keyword(), map()) ::
  {:ok, keyword()} | {:error, {:invalid_runtime_config, term()}}
```

Resolves a worker's delivery config for one perform: when the worker
declared `runtime_config: {module, function}`, the callback runs with
the job's args map (string keys, tenant included when the row carries
one) and its overrides are merged over the compiled defaults. Then
the compiled-budget misfit checks re-run as runtime validation.

Returns `{:ok, config}` (the driver-ready keyword list) or
`{:error, {:invalid_runtime_config, reason}}`, where `reason` is
`:callback_failed` (a crash or a non-keyword return, contained and never
raised through), `{:unknown_key, key}`, `:not_positive_integer`,
`:backoff_inversion`, `:envelope_exceeded` (the resolved attempt
deadline overruns the baked Oban job timeout, or a literal
`:http_opts` `timeout:` collides with a lowered `:attempt_timeout`),
or `:oban_ceiling_exceeded` (the resolved delivery ceiling reaches the
baked Oban job ceiling; only the row ceiling may decide dead-letter).
A rejection emits `[:ash_hooks, :worker, :invalid_runtime_config]` and
leaves the delivery row untouched.

---

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