Go tasks

Define typed JSON tasks and create durable envelopes.

type GenerateInvoice struct {
    InvoiceID string `json:"invoice_id"`
}

func (GenerateInvoice) Kind() string { return "invoice.generate" }

payload, err := json.Marshal(GenerateInvoice{InvoiceID: "inv-42"})
if err != nil { return err }
envelope := headgate.Envelope{
    ID: "invoice-job-42",
    Kind: GenerateInvoice{}.Kind(),
    SchemaVersion: 1,
    Fingerprint: headgate.Fingerprint(GenerateInvoice{}.Kind(), payload),
    Payload: payload,
    Queue: "billing",
    PartitionKey: "tenant-7",
}

Kind() is a durable public identifier. Keep it stable. Implement Versioned with Version() and Upcast() when deployed payloads evolve, and set Envelope.SchemaVersion explicitly. Matching versions use JSON decoding; other nonzero versions use Upcast. Without Versioned, missing fields may silently decode to zero values.

See Task versioning for a complete welcome-email v1 → v2 → v3 example, required-field validation, and rolling-deployment guidance.