AshHooks.Worker (AshHooks v3.3.0)

Copy Markdown View Source

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.

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 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.

Summary

Functions

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.

Functions

resolve_config(config, args)

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