Process-free configuration for calls to Absurd.SQL.
A client identifies a caller-owned Postgrex queryable and carries safe defaults. It does not own a connection pool, install database objects, or start workers.
Registered Absurd.Task modules provide their stable task name and queue.
Explicit string names support tasks implemented by another Absurd SDK when
the queue is supplied. Spawn results can then be passed directly to fetch,
await, retry, and cancellation operations.
With a database containing the supported schema, a typical flow is:
client = Absurd.Client.new!(db: MyApp.AbsurdDB, queue: "email")
:ok = Absurd.Client.create_queue(client)
{:ok, spawned} =
Absurd.Client.spawn(
client,
MyApp.SendEmail,
%{"user_id" => "usr_123"},
idempotency_key: "email:usr_123"
)
{:ok, terminal} =
Absurd.Client.await_task_result(client, spawned, timeout: 30_000)Examples
iex> {:ok, client} = Absurd.Client.new(db: self())
iex> {client.queue, client.default_max_attempts}
{"default", 5}
iex> match?({:error, %Absurd.Error{kind: :validation}}, Absurd.Client.new(db: self(), queue: ""))
trueSummary
Types
A Postgrex pool, connection, registered name, or checked-out connection.
An immutable Absurd client value.
A task module, stable task name, spawn result, or task identifier.
Functions
Polls until a task reaches a terminal state.
Cancels a task while leaving already-started external effects cooperative.
Creates the client's default queue.
Creates a named queue with default storage and maintenance policy.
Creates a named queue with storage and maintenance options.
Returns the default maximum number of task attempts.
Returns the default queue used by new clients.
Drops the client's default queue if it exists.
Drops a named queue if it exists.
Emits a first-write-wins event on the selected or default queue.
Fetches the current result snapshot for a task.
Returns the default queue's policy, or nil when it does not exist.
Returns a named queue's policy, or nil when it does not exist.
Lists every Absurd queue visible to the client's database connection.
Builds an immutable client around a caller-owned Postgrex queryable.
Builds a client and raises ArgumentError when its static configuration is
invalid.
Retries a failed task.
Updates the default queue's official maintenance-policy fields.
Updates a named queue's official maintenance-policy fields.
Spawns a registered task module or explicit stable task name.
Types
@type queryable() :: GenServer.server()
A Postgrex pool, connection, registered name, or checked-out connection.
@type t() :: %Absurd.Client{ db: queryable(), default_max_attempts: pos_integer(), hooks: module() | nil, query_options: keyword(), queue: String.t() }
An immutable Absurd client value.
@type task_reference() :: module() | String.t() | Absurd.SpawnResult.t() | binary()
A task module, stable task name, spawn result, or task identifier.
Functions
@spec await_task_result(t(), Absurd.SpawnResult.t() | binary(), keyword()) :: {:ok, Absurd.TaskResult.t()} | {:error, Absurd.Error.t()}
Polls until a task reaches a terminal state.
Polling starts at 50 milliseconds and doubles to at most one second. The
:timeout is an Elixir duration in milliseconds or :infinity; timing out
does not cancel the durable task.
@spec cancel_task(t(), Absurd.SpawnResult.t() | binary(), keyword()) :: :ok | {:error, Absurd.Error.t()}
Cancels a task while leaving already-started external effects cooperative.
@spec create_queue(t()) :: :ok | {:error, Absurd.Error.t()}
Creates the client's default queue.
Queue creation accepts :storage_mode and the official queue-policy fields.
@spec create_queue(t(), String.t()) :: :ok | {:error, Absurd.Error.t()}
Creates a named queue with default storage and maintenance policy.
@spec create_queue(t(), String.t(), keyword()) :: :ok | {:error, Absurd.Error.t()}
Creates a named queue with storage and maintenance options.
@spec default_max_attempts() :: pos_integer()
Returns the default maximum number of task attempts.
@spec default_queue() :: String.t()
Returns the default queue used by new clients.
@spec drop_queue(t()) :: :ok | {:error, Absurd.Error.t()}
Drops the client's default queue if it exists.
@spec drop_queue(t(), String.t()) :: :ok | {:error, Absurd.Error.t()}
Drops a named queue if it exists.
@spec emit_event(t(), String.t(), Absurd.JSON.value(), keyword()) :: :ok | {:error, Absurd.Error.t()}
Emits a first-write-wins event on the selected or default queue.
@spec fetch_task_result(t(), Absurd.SpawnResult.t() | binary(), keyword()) :: {:ok, Absurd.TaskResult.t() | nil} | {:error, Absurd.Error.t()}
Fetches the current result snapshot for a task.
Passing an Absurd.SpawnResult uses its queue. Passing a task ID uses the
client queue unless :queue is supplied. An unknown task returns {:ok, nil}.
@spec get_queue_policy(t()) :: {:ok, Absurd.QueuePolicy.t() | nil} | {:error, Absurd.Error.t()}
Returns the default queue's policy, or nil when it does not exist.
@spec get_queue_policy(t(), String.t()) :: {:ok, Absurd.QueuePolicy.t() | nil} | {:error, Absurd.Error.t()}
Returns a named queue's policy, or nil when it does not exist.
@spec list_queues(t()) :: {:ok, [String.t()]} | {:error, Absurd.Error.t()}
Lists every Absurd queue visible to the client's database connection.
@spec new(keyword()) :: {:ok, t()} | {:error, Absurd.Error.t()}
Builds an immutable client around a caller-owned Postgrex queryable.
Options
:db- required Postgrex queryable;:queue- default queue, initially"default";:default_max_attempts- positive integer, initially5;:hooks- optional module implementingAbsurd.Hooks;:query_options- options passed to Postgrex queries.
Unknown options are rejected.
Builds a client and raises ArgumentError when its static configuration is
invalid.
@spec retry_task(t(), Absurd.SpawnResult.t() | binary(), keyword()) :: {:ok, Absurd.SpawnResult.t()} | {:error, Absurd.Error.t()}
Retries a failed task.
:max_attempts overrides the retry limit. :spawn_new creates a new logical
task rather than extending the failed task in place.
@spec set_queue_policy(t(), keyword()) :: :ok | {:error, Absurd.Error.t()}
Updates the default queue's official maintenance-policy fields.
@spec set_queue_policy(t(), String.t(), keyword()) :: :ok | {:error, Absurd.Error.t()}
Updates a named queue's official maintenance-policy fields.
@spec spawn(t(), module() | String.t(), Absurd.JSON.value(), keyword()) :: {:ok, Absurd.SpawnResult.t()} | {:error, Absurd.Error.t()}
Spawns a registered task module or explicit stable task name.
A raw task name requires :queue. Registered modules use their task metadata;
a queue override must equal the registered queue. Per-spawn defaults take
precedence over task metadata and then the client maximum-attempt default.