Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for the Awa worker client.

Implementations

impl ClientBuilder

pub fn new(pool: PgPool) -> Self

pub fn queue(self, name: impl Into<String>, config: QueueConfig) -> Self

Add a queue with its configuration.

pub fn queue_descriptor( self, name: impl Into<String>, descriptor: QueueDescriptor, ) -> Self

Attach descriptive metadata (display name, description, owner, docs URL, tags, extra JSON) to a queue so it appears labelled in the admin API and UI. The queue must also be declared via queue; otherwise build fails with BuildError::QueueDescriptorWithoutQueue.

pub fn job_kind_descriptor<T: JobArgs>( self, descriptor: JobKindDescriptor, ) -> Self

Attach descriptive metadata to a typed job kind. The kind string is taken from JobArgs::kind on T.

pub fn job_kind_descriptor_kind( self, kind: impl Into<String>, descriptor: JobKindDescriptor, ) -> Self

Attach descriptive metadata to a job kind by string name. Useful when the kind is known dynamically (e.g. from language bridges).

pub fn register<T, F, Fut>(self, handler: F) -> Self

where T: JobArgs + DeserializeOwned + Send + Sync + 'static, F: Fn(T, &JobContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<JobResult, JobError>> + Send + Sync + 'static,

Register a typed worker.

The worker handles jobs of type T where T: JobArgs + DeserializeOwned. The handler function receives the deserialized args and job context.

pub fn on_event<T, F, Fut>(self, handler: F) -> Self

where T: JobArgs + DeserializeOwned + Send + Sync + 'static, F: Fn(JobEvent<T>) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Register a typed lifecycle event handler for a job kind.

Handlers run only after the corresponding DB state transition commits. They are best-effort in-process hooks, not a durable workflow mechanism. Capture any shared dependencies you need in the closure environment.

pub fn on_event_kind<F, Fut>(self, kind: impl Into<String>, handler: F) -> Self

where F: Fn(UntypedJobEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Register an untyped lifecycle event handler for a specific job kind.

Use this with register_worker(...) or for cross-cutting logic that doesn’t need typed args.

pub fn register_worker(self, worker: impl Worker + 'static) -> Self

Register a raw worker implementation.

pub fn state<T: Any + Send + Sync + Clone>(self, value: T) -> Self

Add shared state accessible via ctx.extract::<T>().

pub fn heartbeat_interval(self, interval: Duration) -> Self

Set the heartbeat interval (default: 30s).

pub fn promote_interval(self, interval: Duration) -> Self

Set the scheduled/retryable promotion interval (default: 250ms).

pub fn heartbeat_rescue_interval(self, interval: Duration) -> Self

Set the stale-heartbeat rescue interval (default: 30s).

pub fn heartbeat_staleness(self, staleness: Duration) -> Self

Set how long a heartbeat must be stale before the job is rescued (default: 90s).

Should be at least 3× the heartbeat interval to avoid false rescues.

pub fn deadline_rescue_interval(self, interval: Duration) -> Self

Set the deadline rescue interval (default: 30s).

pub fn callback_rescue_interval(self, interval: Duration) -> Self

Set the callback-timeout rescue interval (default: 30s).

pub fn leader_election_interval(self, interval: Duration) -> Self

Set the leader election retry interval (default: 10s).

Controls how often a non-leader instance retries acquiring the maintenance advisory lock. Lower values are useful in tests.

pub fn leader_check_interval(self, interval: Duration) -> Self

Set the leader connection health-check interval (default: 30s).

pub fn global_max_workers(self, max: u32) -> Self

Set a global maximum worker count across all queues (enables weighted mode).

When set, each queue gets min_workers guaranteed permits plus a share of the remaining overflow capacity based on weight.

pub fn completed_retention(self, retention: Duration) -> Self

Set retention for completed jobs (default: 24h).

pub fn failed_retention(self, retention: Duration) -> Self

Set retention for failed/cancelled jobs (default: 72h).

pub fn descriptor_retention(self, retention: Duration) -> Self

How long a descriptor catalog row can go un-refreshed before the maintenance leader deletes it (default: 30 days). Pass Duration::ZERO to disable — the catalog will then accumulate rows indefinitely. See MaintenanceService::descriptor_retention.

pub fn cleanup_batch_size(self, batch_size: i64) -> Self

Set the maximum number of jobs to delete per cleanup pass (default: 1000).

pub fn cleanup_interval(self, interval: Duration) -> Self

Set the cleanup interval (default: 60s).

pub fn queue_retention( self, queue: impl Into<String>, policy: RetentionPolicy, ) -> Self

Set a per-queue retention override.

pub fn runtime_snapshot_interval(self, interval: Duration) -> Self

Set how often runtime observability snapshots are published (default: 10s).

pub fn queue_stats_interval(self, interval: Duration) -> Self

Set how often queue depth/lag metrics are published (default: 30s).

pub fn periodic(self, job: PeriodicJob) -> Self

Register a periodic (cron) job schedule.

The schedule is synced to the database by the leader and evaluated every second. When a fire is due, a job is atomically enqueued.

pub fn build(self) -> Result<Client, BuildError>

Build the client.