Crate worklane 

Typed background jobs for Rust services.

worklane is the public-facing facade. Enqueue typed jobs with a Client and run handlers with a Worker over any Broker (for example the in-memory broker in the worklane-memory crate). Application code should usually depend on this crate plus one broker crate. Lower-level crates such as worklane-core are for broker implementations and optional integrations.

Core loop: typed payload -> envelope -> broker reserve -> dispatch by kind -> run handler -> ack / retry / fail / dead-letter.

Delivery is at-least-once: a job may run more than once (e.g. after a lease expiry or crash), so handlers must be idempotent.

Structs

Building

Configuration phase: handlers and options can be set. Reached by Worker::new; left by Worker::build.

Cancellation

A cooperative cancellation flag for a running job.

CircuitBreaker

Per-kind circuit-breaker state, shared across a worker’s in-flight tasks.

CircuitBreakerPolicy

Tuning for a CircuitBreaker.

ClaimCheck

Offloads oversized payloads to a PayloadStore and resolves the references back, implementing the Claim Check pattern.

Client

Enqueues typed jobs onto a broker.

DeadLetter

A job that exhausted its attempts (or failed unrecoverably), retained for inspection along with the last error message.

FanInPolicy

Tuning for a fan-in watcher’s poll loop, passed to Client::fan_in_with_policy.

FanInResults

The payload delivered to a fan-in callback: the caller’s context plus each dependency’s opaque output bytes, in dependency order.

FilePayloadStore

A filesystem-backed PayloadStore — the reference implementation.

JobAttemptEvent

The observer SPI, defined in worklane-core so telemetry integrations can depend on the contract without the facade. Re-exported here as the worker is what invokes it. A per-attempt in-flight event handed to a JobObserver.

JobBuilder

A builder for configuring and enqueuing a job with custom properties.

JobContext

Per-run context handed to a job handler.

JobEnvelope

The broker’s view of an enqueued job. The payload is opaque: the broker never inspects or deserializes it.

JobEvent

The observer SPI, defined in worklane-core so telemetry integrations can depend on the contract without the facade. Re-exported here as the worker is what invokes it. A finished-job event handed to a JobObserver.

JobId

A unique identifier for an enqueued job.

JobIdParseError

The error returned when JobId fails to parse from a string.

Lane

A validated lane identifier.

NewJob

A job to be enqueued: the lane it targets, its kind, an already-serialized payload, how many attempts it may take before being dead-lettered, and an optional delay before it becomes visible for reservation.

Next

The continuation handed to a Middleware: the remaining middleware chain, terminating at the job’s handler. Call run to proceed.

Ready

Execution phase: configuration is frozen and the worker can run. Reached only via Worker::build.

Reservation

A reserved job and the receipt required to resolve it.

ReservationReceipt

An opaque token proving authority to resolve a specific reservation.

RetryPolicy

Computes the delay before a failed job is retried, using capped exponential backoff: delay = min(base * factor^attempts, cap).

SystemClock

A real clock backed by Instant.

WallClock

A wall-clock time source anchored at the Unix epoch, guarded to be monotonic non-decreasing for the lifetime of the instance.

Worker

Runs registered job handlers, processing up to a configured concurrency of jobs at a time (default 1, i.e. strictly sequential).

Enums

Error

Errors produced by worklane operations.

JobOutcome

The observer SPI, defined in worklane-core so telemetry integrations can depend on the contract without the facade. Re-exported here as the worker is what invokes it. What ultimately happened to a job, reported to a JobObserver.

JobState

The state of a job returned by Broker::classify.

LaneError

The reason a lane name failed validation.

Constants

DEFAULT_LANE

The name of the default lane.

DEFAULT_MAX_ATTEMPTS

The default max_attempts applied to enqueued jobs. Re-exported from worklane-core so worklane::DEFAULT_MAX_ATTEMPTS is stable. The default max_attempts applied to enqueued jobs when a caller does not specify one. Brokers impose no retry policy themselves; this is the default the client- and scheduler-side enqueue paths apply.

DEFAULT_OFFLOAD_THRESHOLD

The default offload threshold: payloads larger than this are stored externally. 64 KiB comfortably inlines ordinary jobs while offloading genuinely large ones.

DEFAULT_POLL_INTERVAL

The default idle poll interval for Worker::run.

Traits

BatchEnqueue

Atomic batch enqueue — an optional Broker capability.

Broker

A backend-agnostic job store and lifecycle primitive.

Clock

A monotonic time source, abstracted so brokers derive time-based decisions (visibility, lease expiry, retry scheduling) from an injectable clock rather than reading wall-clock time directly.

DeadLetterStore

Dead-letter inspection and maintenance — an optional Broker capability.

Job

A typed background job.

JobObserver

The observer SPI, defined in worklane-core so telemetry integrations can depend on the contract without the facade. Re-exported here as the worker is what invokes it. Observes the outcome of every job a Worker resolves.

Middleware

A handler-dispatch interceptor. See Worker::with_middleware for registration and ordering.

PayloadStore

An external store for oversized job payloads (the Claim Check pattern).

QueueStats

Queue-depth statistics — an optional Broker capability.

ResultStore

A pluggable backend for storing opaque job results.

ScheduledStore

Optional schedule-claim store used by recurring schedulers.

WorkerState

Marks a Worker’s lifecycle phase (typestate). Sealed: the only states are Building and Ready.

Workflow

The Workflow extension trait. Provides building blocks for fan-in/fan-out topologies (sequences and fan-ins) built entirely in user-space over the core primitives.

Functions

from_payload

Deserialize a typed payload from bytes (JSON), mapping failures to Error::Serialization.

to_payload

Serialize a typed payload to bytes (JSON), mapping failures to Error::Serialization.

Type Aliases

HandlerError

A boxed error returned by a job handler.

HandlerResult

The result of running a job handler.

Result

A Result specialized to the worklane Error type.

Attribute Macros

async_trait

Re-exported so handlers can annotate their Job impl with #[worklane::async_trait].