Struct Client 

pub struct Client { /* private fields */ }

The Awa worker client — manages dispatchers, heartbeat, and maintenance.

Implementations

impl Client

pub fn builder(pool: PgPool) -> ClientBuilder

Create a new builder.

pub async fn start(&self) -> Result<(), AwaError>

Start the worker runtime. Spawns dispatchers, heartbeat, and maintenance.

pub async fn shutdown(&self, timeout: Duration)

Graceful shutdown with drain timeout.

Phased lifecycle:

1. Stop dispatchers (no new jobs claimed)
2. Signal in-flight jobs to cancel
3. Wait for dispatchers to exit
4. Drain in-flight jobs (heartbeat + maintenance still alive!)
5. Stop heartbeat + maintenance

pub fn pool(&self) -> &PgPool

Get the pool reference.

pub async fn resolve_callback( &self, callback_id: Uuid, payload: Option<Value>, default_action: DefaultAction, run_lease: Option<i64>, ) -> Result<ResolveOutcome, AwaError>

Resolve a pending external callback and dispatch the matching lifecycle event + ADR-029 follow-up specs.

The callback transition (Complete / Fail) and any registered on_completed_enqueue / on_exhausted_enqueue follow-up INSERTs commit in a single transaction. A follow-up INSERT failure (or a panic in the user-supplied closure) rolls the callback transition back; the caller sees an Err and can surface a retryable failure to the external sender so the callback can be redelivered. Ignored produces no transition; Resumed does not currently fire a follow-up spec because resume re-enters execution and the executor emits the eventual outcome event itself.

Prefer this over awa_model::admin::resolve_callback when you want Completed/Exhausted hooks or follow-up enqueues to fire for callback-driven outcomes. Hooks fire only in this process and only after the transaction commits.

pub async fn complete_external( &self, callback_id: Uuid, payload: Option<Value>, run_lease: Option<i64>, ) -> Result<JobRow, AwaError>

Complete a waiting job via its callback. The callback completion and any registered on_completed_enqueue follow-up INSERTs commit atomically. A spec INSERT failure rolls the completion back and returns Err so the external sender can retry. The in-process Completed hook fires after the transaction commits.

pub async fn fail_external( &self, callback_id: Uuid, error: &str, run_lease: Option<i64>, ) -> Result<JobRow, AwaError>

Fail a waiting job via its callback. The callback failure and any registered on_exhausted_enqueue follow-up INSERTs commit atomically. A spec INSERT failure rolls the failure back and returns Err so the external sender can retry. The in-process Exhausted hook fires after the transaction commits.

pub async fn retry_external( &self, callback_id: Uuid, run_lease: Option<i64>, ) -> Result<JobRow, AwaError>

Requeue a waiting job via its callback. The callback retry and any registered on_retried_enqueue follow-up INSERTs commit atomically. A spec INSERT failure rolls the retry back and returns Err so the external sender can retry. The in-process Retried hook fires after the transaction commits.

admin::retry_external_in_tx resets attempt to 0 as part of requeuing the job from scratch, so the returned JobRow no longer reflects the attempt that was being retried. The pre-retry attempt number is captured under the same row lock before the transition runs so the Retried event and spec context report the failed-attempt number — matching the inline Retried semantics where attempt is “the attempt that was retried”, not the post-transition value.

pub async fn health_check(&self) -> HealthCheck

Health check.