Operations Primitives

Wahoo provides provider-neutral contracts for operations code. It does not ship a queue, cloud adapter, SMTP client, payment provider, or billing system.

Work in progress: Do not use Wahoo in production yet.

Jobs

Use jobs.Runner with an application queue adapter. It pulls work only when a worker is free, keeps no in-memory backlog, and sets a 5-minute per-job deadline by default.

runner, err := jobs.New(source, handler, jobs.Config{
    Workers:    4,
    JobTimeout: 2 * time.Minute,
})
if err != nil {
    return err
}
return runner.Run(ctx)

The queue adapter must define acknowledgement, retry delay, maximum attempts, dead-letter behavior, retention, and transactional outbox handling. Run workers as a workload separate from public HTTP.

Storage

storage.Store defines bounded object operations. The application authorizes opaque object keys and chooses S3, GCS, R2, local storage, or another adapter. Do not expose provider keys or provider ACLs to browsers.

Mail

mail.Message validates recipients and body bounds before an application mail.Sender sends it. Queue and retry mail from an application job handler. Do not add unbounded attachments to the mail path.

Audit Events

audit.Event stores a bounded, immutable business event. Include the actor, target, outcome, and Wahoo request ID. The application owns retention, redaction, storage transactions, and audit-log access rules.

Webhooks

Use webhook.Verifier to verify raw payload HMAC-SHA256 signatures with a bounded body and freshness window.

body, err := verifier.ReadBody(r.Body)
if err != nil {
    return err
}
_, err = verifier.Verify(r.Header.Get("Webhook-Signature"), body)

Verification proves authenticity and bounded freshness. The application must atomically record provider delivery IDs and process events idempotently to prevent replay.

Entitlements And Billing

entitlement.Decide evaluates normalized feature grants. billing.Provider defines checkout and normalized subscription access. billing.UsageRecorder records an idempotent metered event.

checkout, err := provider.CreateCheckout(ctx, billing.CheckoutRequest{
    CustomerID: "cus_123",
    PriceID:    "price_team",
    SuccessURL: "https://app.example.com/billing/success",
    CancelURL:  "https://app.example.com/billing/cancel",
})

The application owns provider credentials, checkout authorization, webhook reconciliation, invoices, tax, payment recovery, usage aggregation, and conversion from subscription state to entitlement grants.