Typed handlers

Register task kinds, decode payload versions, access job context, and return outcomes.

The registry maps durable task kinds to typed handlers. Registration validates kind names, aliases, and collisions before a worker starts polling. Payload versions are decoded when the job executes; registration does not validate all historical payload shapes.

Rust

#[derive(serde::Serialize, serde::Deserialize, headgate::Task)]
#[task(kind = "mail.deliver", version = 1)]
struct DeliverMail { recipient: String }

registry.register::<DeliverMail, _, _>(|ctx: headgate::JobCtx, task| async move {
    ctx.log(format!("deliver to {}", task.recipient));
    Ok(())
})?;

Context data

Handlers can read job identity, attempt metadata, worker metadata, application extensions, and a producer client tied to the same runtime. Context cancellation means the process is shutting down, an operator cancelled the job, or the lease was lost.

Treat cancellation as a hard stop. A handler that ignores it still cannot checkpoint or ack over a newer lease holder, but it may continue external side effects unnecessarily.

Payload evolution

Keep task kinds stable and declare schema versions explicitly in producer envelopes. Use application-defined upcasters for old payloads and aliases for kind renames. A codec failure becomes undecodable; it does not burn retries that cannot repair bytes. Go version checks require the optional Versioned interface; a plain JSON task does not enforce them automatically.

Task versioning: v1 to v3

Rename a field, add a required field, implement Go and Rust upcasters, and deploy readers before writers. Includes runnable examples and rejection tests.