Handler context

Access clients, dependency extractors, task data, output, and tracking inside handlers.

Typed handlers receive durable job metadata and a cancellation-aware context. The runtime also carries application extensions so handlers can obtain dependencies without global state.

Available job data

Handlers can inspect job ID, queue, partition, rate class, weight, attempt and crash counts, maximum attempts, deadline, and fencing identity. Payload decoding has already produced the typed task value.

Task-local typed data is non-persisted scratch state for middleware, extractors, and the handler in the same attempt. It does not survive a retry or process restart. Put durable state in a checkpoint, result, progress record, or application database instead.

Client from context

Workers install a producer client into handler context. Follow-on jobs therefore use the same validation, authorization, middleware, and store configuration as ordinary producers. This is convenient for small chains; use workflows when dependency state must be durable and inspectable.

Rust

let config = headgate::WorkerConfig {
    producer: Some(producer),
    ..Default::default()
};

registry.register::<ParentTask, _, _>(|ctx, parent| async move {
    ctx.client().enqueue(&[child_envelope(parent)]).await?;
    Ok(())
})?;

Dependency extractors

Handler extractors resolve typed dependencies from runtime extensions before calling the task function. Registration validates extractor shape at startup. Missing dependencies fail explicitly rather than appearing as a nil service during execution.

Rust

registry.register_extracted::<
    SendInvoice,
    (Data<DatabasePool>, Meta<Tenant>, Attempt, TaskId),
    _,
    _,
>(|ctx, task, (database, tenant, attempt, task_id)| async move {
    send_invoice(database, tenant, attempt, task_id, task).await
})?;

Progress, output, and results

• progress is the latest durable status for operators;
• mid-run output is appendable attempt output;
• logs describe each attempt;
• a result is the final durable return value.

Payloads and results are distinct. List endpoints redact payloads by default, and encrypted payloads do not automatically encrypt progress, output, logs, or results.

Typed handlers

Results and progress