Crate sepp_rs 

A Rust client for the sepp job queue.

This client provides both halves of the job queue API:

• Producers enqueue jobs with a SeppClient — one at a time, in best-effort batches or atomic batches.
• Consumers reserve jobs and report their outcome. The low-level reserve / ack / nack calls give you full manual control, while the high-level Worker runs the whole reserve → process → ack loop for you with bounded concurrency, optional lease auto-extension, graceful shutdown and metrics.

Quickstart

As this crate uses tonic, the client is async only and requires a tokio runtime.

Enqueue a job, then run a worker that processes it:

use std::time::Duration;
use sepp_rs::client::SeppClient;
use sepp_rs::worker::Worker;
use sepp_rs::{EnqueueRequest, Payload};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SeppClient::connect("http://127.0.0.1:50051").await?;

    // Producer: enqueue a job onto the `emails` queue.
    let ack = client
        .enqueue(
            EnqueueRequest::new("emails", "send_welcome")?
                .with_payload(Payload::new(b"{\"user\":42}".to_vec(), "application/json")),
        )
        .await?;
    println!("enqueued job {}", ack.job_id);

    // Consumer: process `send_welcome` jobs from the `emails` queue. A handler
    // returns `Ok(())` to ack the job, or a `HandlerError` to nack it.
    Worker::new(client, ["emails"], Duration::from_secs(30))?
        .handle("send_welcome", |payload, ctx| async move {
            println!("processing job {}", ctx.id);
            Ok(())
        })?
        .run()
        .await;

    Ok(())
}

Concepts

Queues and job types. Every job is enqueued onto a named queue and tagged with a job_type. Workers reserve from one or more queues and dispatch each job to the handler registered for its job_type.

Payload. Every job can carry an opaque blob of bytes plus an encoding hint. You can use this to transport any data you want as long as producers and workers agree on the encoding. For a primitive key-value map, use custom instead.

Leases and redelivery. A reserved job is leased to the worker for a bounded duration. The worker must ack, nack, or extend the lease before it expires; otherwise the server redelivers the job to another worker (with attempt incremented) until max_attempts is reached and it is dead-lettered. Worker can extend leases automatically — see with_auto_extend.

Feature flags

• opentelemetry (enabled by default) — emit OpenTelemetry-compatible tracing spans and metrics, and propagate W3C trace context from the producer’s enqueue span to the worker’s process span. The host application still owns the exporter; see the traced example.
• tls — enable TLS for the transport via the tls_* methods on SeppClientBuilder.

Modules

client

The gRPC client: connecting, enqueuing, reserving, and lease management.

worker

A high-level worker that runs the reserve → process → ack/nack loop.

Structs

DeadLetterRecord

A dead-lettered job retained by the server, returned by drain_dead_letters.

EnqueueAck

Confirmation that a job was accepted by the server.

EnqueueRequest

A job to enqueue, built fluently.

Job

A reserved job: its optional Payload and its JobCtx.

JobCtx

Everything about a reserved job except its payload: identity, delivery metadata, and the handle needed to manage its lease.

JobValidationError

A single job’s rejection within an atomic batch, paired with its position in the request so the caller can identify which job failed.

Payload

The opaque body of a job, plus an encoding hint.

Priority

A job priority in the range 0..=9, where higher values are dequeued first.

PriorityOutOfRange

Returned by Priority::new when the value is greater than 9.

ReserveOptions

Parameters for a reserve call.

ServerInfo

The server’s version, capabilities, and limits, as returned by get_server_info.

TraceContext

A W3C Trace Context attached to a job, used to link a producer’s trace to the worker that processes the job.

Enums

AtomicEnqueueError

The error type of enqueue_atomic.

DeadLetterCause

Why a job was moved to the server’s dead-letter store.

EnqueueRequestBuilderError

Returned by EnqueueRequest::new when the queue or job type is empty.

JobConversionError

Returned when a job received from the server cannot be decoded into a Job.

JobRejection

Why the server refused a single job.

Primitive

A JSON-primitive value stored in a job’s custom metadata map.

ReserveOptionsError

Returned by ReserveOptions constructors and setters on invalid input.

ServerInfoError

Returned when a get_server_info response cannot be decoded into a ServerInfo.

TraceContextError

Returned by TraceContext::new when the traceparent is not a well-formed W3C value.