Struct Worker 

pub struct Worker { /* private fields */ }

A job-processing loop built on a SeppClient.

Configure it fluently — queues and lease duration via new, then with_* tuning and one handle call per job type — and start it with run. run consumes the worker and only returns after a ShutdownHandle is triggered and in-flight jobs have drained.

Each reserved job runs on its own task, bounded by with_max_in_flight. A job whose job_type has no registered handler is nacked for retry with an attempt-based backoff (min(2^attempt, 60) seconds), so a worker that does have the handler — e.g. one running the next deploy — can pick it up instead of this worker burning through the job’s attempts.

Implementations

impl Worker

pub fn new( client: SeppClient, queues: impl IntoIterator<Item = impl Into<String>>, lease_duration: Duration, ) -> Result<Self, WorkerBuilderError>

Creates a worker that reserves from queues with the given lease duration.

Sensible defaults are applied: up to 16 jobs in flight, a 1s backoff after a failed reserve, no lease auto-extension, and a generated worker_id derived from the hostname and PID. Register at least one handler with handle before run.

pub fn with_wait_timeout(self, wait: Duration) -> Self

Sets the long-poll wait timeout for each reserve. See ReserveOptions::with_wait_timeout.

Panics

Panics if wait is zero. The server would answer every reserve immediately, turning the poll loop into back-to-back RPCs.

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

Caps how many jobs a single reserve may return. The worker already limits this to its free in-flight capacity, so set this only to request fewer.

Panics

Panics if max is 0. The server requires max_jobs >= 1 and would reject every reserve, hanging the worker.

pub fn shutdown_handle(&self) -> ShutdownHandle

Returns a ShutdownHandle for stopping the worker. Obtain it before calling run, which consumes self.

pub fn with_auto_extend(self) -> Self

Enables automatic lease extension while a handler runs, using a heartbeat interval of one third of the lease duration. Use with caution: if the handler hangs indefinitely, the lease will be extended forever.

With this on, long-running handlers keep their lease alive without calling JobCtx::extend themselves. If the server reassigns the lease anyway, the handler task is aborted to avoid double processing.

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

Like with_auto_extend but with an explicit heartbeat interval (floored at 1ms). The interval should be comfortably shorter than the lease duration.

pub fn with_max_in_flight(self, max_in_flight: usize) -> Self

Sets the maximum number of jobs processed concurrently (default 16). Values below 1 are treated as 1.

pub fn with_reserve_error_backoff(self, backoff: Duration) -> Self

Sets how long to wait after a failed reserve before retrying (default 1s), preventing a hot loop when the server is unreachable.

pub fn with_worker_id( self, worker_id: impl Into<String>, ) -> Result<Self, WorkerBuilderError>

Overrides the auto-generated worker id. Must be non-empty.

pub fn handle<F, Fut>( self, job_type: &str, h: F, ) -> Result<Self, WorkerBuilderError>

where F: Fn(Option<Payload>, Arc<JobCtx>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), HandlerError>> + Send + 'static,

Registers the handler for a job_type.

The handler receives the job’s optional Payload and an Arc<JobCtx>, and returns Ok(()) to ack or a HandlerError to nack. Returns WorkerBuilderError::DuplicateHandler if a handler is already registered for this type.

pub fn with_catch_all_handler<F, Fut>(self, h: F) -> Self

where F: Fn(Option<Payload>, Arc<JobCtx>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), HandlerError>> + Send + 'static,

Registers a catch-all handler for job types without a specific handler.

pub fn replace_handler<F, Fut>(self, job_type: &str, h: F) -> Self

where F: Fn(Option<Payload>, Arc<JobCtx>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), HandlerError>> + Send + 'static,

Registers a handler, overwriting any existing one for the same job_type instead of erroring.

pub fn remove_handler(self, job_type: &str) -> Self

Unregisters the handler for a job_type, if any. Jobs of an unhandled type are nacked for retry with an attempt-based backoff.

pub async fn run(self)

Runs the reserve → process → ack/nack loop until shutdown.

Consumes the worker and does not return until a ShutdownHandle is triggered and all in-flight jobs have finished draining. Shutdown cancels a still-pending reserve promptly, but a reserve that has already completed with jobs at the shutdown boundary still has those jobs processed as part of the drain — they are leased to this worker either way. Reserve errors are logged and retried after with_reserve_error_backoff; they do not stop the loop. Take a shutdown_handle beforehand to be able to stop it.

The drain wait is unbounded: a handler that never returns blocks the return of run indefinitely (and with with_auto_extend its lease is kept alive the whole time). If a handler’s work can hang, bound it yourself, e.g. with tokio::time::timeout.