Struct Delivery 

pub struct Delivery {
    pub run_id: RunId,
    pub headers: HashMap<String, String>,
    pub job_id: String,
    pub attempts: u32,
    pub max_attempts: u32,
    pub cancel_token: CancellationToken,
    pub lease: LeaseHandle,
    pub memo: Memo,
    pub run_memo: Memo,
    pub effects: EffectsHandle,
    pub kv: KvReadHandle,
}

The delivery a handler runs under: the identity of the run and of the queue job delivering it, the attempt count and the delivery’s handles. Step and jobs::JobContext dereference to it. It holds handles only; no queue is reachable through it.

Constructed by the runtime. A test constructs one with Delivery::detached and assigns the fields it needs.

Fields

run_id: RunId

Caller-visible run identifier (the value passed to or generated by crate::RunSpec).

headers: HashMap<String, String>

Submitter-supplied metadata, threaded through every step of the run. Reserved workflow.* headers are stripped before the handler sees them.

job_id: String

The Taquba job ID of this delivery, useful for tracing.

attempts: u32

How many times Taquba has attempted this delivery. 1 on the first attempt; >1 after a lease expiry / nack retry.

max_attempts: u32

The attempt limit: a transient failure on the attempt numbered max_attempts ends the run.

cancel_token: CancellationToken

Cooperative cancellation signal for the run. The runtime cancels this token when crate::WorkflowRuntime::cancel is called while this delivery is in flight, so a long-running handler (e.g. an LLM call, a slow HTTP request) can short-circuit instead of running to completion. Typical use:

tokio::select! {
    out = do_slow_work(step) => out,
    _ = step.cancel_token.cancelled() => {
        Ok(StepOutcome::Cancel { reason: "cooperative".into() })
    }
}

Handlers that ignore the token remain correct: the runtime still discards the outcome of a cancelled step and fires the terminal hook with crate::TerminalStatus::Cancelled. Watching the token only reduces cancellation latency for slow steps; it doesn’t change semantics.

The token is a child of the claim’s cancellation token. A re-delivery of this step observes is_cancelled() == true immediately, because the queue re-fires the claim’s cancellation token from the job’s persisted cancellation. Cancelling this token leaves the claim’s token uncancelled, so the runtime does not treat the step as externally cancelled.

lease: LeaseHandle

The lease handle of this delivery. A long-running handler calls LeaseHandle::ensure_at_least at progress points (or once, with a slow call’s timeout, before issuing it) so the step is not re-queued while it still runs. A detached handle’s calls succeed without effect.

memo: Memo

Per-step durable key-value store, scoped to this step’s (run_id, step_number). Use to memoize expensive within-step side effects (LLM calls, paid APIs) so an at-least-once retry of this step doesn’t re-pay for work the prior attempt already did:

let response = match step.memo.get("llm").await? {
    Some(cached) => deserialize(&cached),
    None => {
        let fresh = llm.complete(&prompt).await?;
        step.memo.put("llm", &serialize(&fresh)).await?;
        fresh
    }
};

See Memo for the full API.

run_memo: Memo

Run-scoped durable key-value store, shared by every step of the run. Entries live beside the per-step Delivery::memo entries and are removed with them when the run’s retention expires. Use it for values a later step reads back, such as an accumulating journal; the durable channel for the next step’s input is StepOutcome::Continue’s payload.

effects: EffectsHandle

Application KV effects for this step. Writes and deletes staged here are applied in the same transaction as the settlement that commits the returned outcome, so application state cannot diverge from the run’s transition on a crash:

step.effects.put(format!("app/runs/{}", step.run_id), b"done".to_vec())?;
Ok(StepOutcome::Succeed { result })

See EffectsHandle for the staging rules.

kv: KvReadHandle

Read access to the caller KV namespace. A committed value (an earlier step’s applied effect, a crate::RunSpec::effects write, a direct taquba::Queue::kv_put) is readable here. Effects staged by this step become readable only after it settles. The intended use is a read-then-stage marker check:

if step.kv.get(b"app/indexed/doc-1").await?.is_none() {
    index_document(&step.payload).await?; // idempotent
    step.effects.put("app/indexed/doc-1", b"1".to_vec())?;
}

See KvReadHandle for the read semantics.

Implementations

impl Delivery

pub fn is_last_attempt(&self) -> bool

Whether this attempt is the last: a transient StepError returned from it dead-letters the step and ends the run.

pub fn detached() -> Self

A delivery bound to no queue, for tests: run detached, attempt 1 of 3, no headers, a new cancellation token, detached lease, effects and KV handles, and memos over an in-memory object store.

Trait Implementations

impl Clone for Delivery

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Delivery

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.