Documentation
¶
Overview ¶
Package tasks provides the Hanzo Tasks client for Go applications.
Drop-in replacement for Base's Tasks() / Cron():
// Before (Base cron):
e.App.Tasks().Add("settlement", "*/30 * * * * *", func() { ... })
// After (Hanzo Tasks):
tasks.Default().Add("settlement", "30s", func() { ... })
Add() accepts both Go duration strings ("30s", "5m", "1h", "24h") and standard 5-field cron expressions ("0 3 * * *", "0 0 5 1,4,7,10 *", "*/5 * * * *"). Anything that parses as a Go duration is treated as an interval; anything else is treated as a cron expression.
If TASKS_URL is set, schedules run as durable Hanzo Tasks workflows (retries, dead letter, audit trail). If not, runs locally via goroutine timer (dev mode, same behaviour as cron but no persistence).
If zapAddr is set, ZAP binary transport is preferred over HTTP for submitting tasks (lower latency, same semantics). HTTP is fallback.
Package tasks provides the Hanzo Tasks client for Go applications.
Two methods, two use cases:
client := tasks.New(os.Getenv("TASKS_URL"), os.Getenv("TASKS_ZAP"), nil)
client.Add("settlement.process", "30s", fn) // recurring schedule (duration)
client.Add("audit.archive", "0 3 * * *", fn) // recurring schedule (cron)
client.Now("webhook.deliver", payload) // fire once immediately
Transport priority: ZAP (binary, low-latency) > HTTP > local goroutine. When TASKS_ZAP is set, tasks submit over ZAP binary protocol. When TASKS_URL is set, tasks submit over HTTP as fallback. When neither is set, tasks run locally via goroutine timers (dev mode).
Integration with Hanzo Base:
app.Tasks().Add("cleanup", "1h", fn)
app.Tasks().Now("email.send", payload)
Index ¶
Constants ¶
const ( OpcodeTaskSubmit uint16 = 0x0050 // one-shot task OpcodeTaskSchedule uint16 = 0x0051 // recurring schedule )
ZAP opcodes for task submission.
Variables ¶
This section is empty.
Functions ¶
func SetDefault ¶ added in v1.9.4
func SetDefault(c *Client)
SetDefault installs the process-wide task client. main() should call this once during boot. Subsequent callers use Default() to dispatch tasks.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client manages both one-shot tasks and recurring schedules.
func Default ¶ added in v1.9.4
func Default() *Client
Default returns the process-wide client. If SetDefault was never called, lazily creates a client from TASKS_URL / TASKS_ZAP env vars so callers that register schedules before main() finished wiring still work. main() may replace this with a handler-bound client via SetDefault.
func New ¶
New creates a Client. If both tasksURL and zapAddr are empty, everything runs locally. If zapAddr is set, ZAP transport is preferred. HTTP is fallback.
func (*Client) Add ¶
Add registers a recurring task.
spec is either a Go duration ("30s", "5m", "1h") or a standard 5-field cron expression ("0 3 * * *", "*/5 * * * *", "0 14 8 * *"). The fn runs on that cadence. If TASKS_URL is set, creates a durable Hanzo Tasks schedule so retries, dead-letter and audit are handled server-side. Otherwise runs locally.
tasks.Default().Add("settlement.process", "30s", func() { ... })
tasks.Default().Add("audit.archive", "0 3 * * *", func() { ... })
type EmbedConfig ¶ added in v1.33.1
type EmbedConfig struct {
DataDir string // workflow + task persistence dir; "" → "./tasks-data"
ZAPPort int // _tasks._tcp listener; 0 picks ephemeral
Namespace string // default namespace; "" → "default"
Logger *slog.Logger // nil → slog.Default()
}
EmbedConfig configures the in-process Tasks server.
type Embedded ¶ added in v1.33.1
type Embedded struct {
// contains filtered or unexported fields
}
Embedded is the handle to a running in-process Tasks server.
func Embed ¶ added in v1.33.1
func Embed(ctx context.Context, cfg EmbedConfig) (*Embedded, error)
Embed starts the in-process Tasks server. Stop before exit.
func (*Embedded) HTTPHandler ¶ added in v1.37.2
HTTPHandler returns the browser-only JSON shim. Each route maps to the same model function the ZAP handler uses, so the two transports can never drift.
Source Files