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 holds the task+workflow persistence. Defaults to
// "./tasks-data". Share with Base by passing Base's data dir.
DataDir string
// ZAPPort is the _tasks._tcp listener. Default 9652. Set to 0
// to pick an ephemeral port; the chosen port is available via
// Embedded.ZAPPort() after Start.
ZAPPort int
// Namespace is the default namespace created on first boot.
// Defaults to "default".
Namespace string
}
EmbedConfig is the one place to configure an in-process tasks server. Every knob has a production default; callers only set what they want to change.
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 an in-process tasks server with the given config. Returns an Embedded handle; caller must call Stop before process exit to flush the data dir cleanly.
The server speaks ZAP on EmbedConfig.ZAPPort (default :9652, service type `_tasks._tcp`). No HTTP gateway is started — browsers don't talk to embedded servers. If you need the UI embedded too, mount Handler() at /_/tasks in your app's own HTTP router (gofiber or net/http both work via the fiber adaptor).
NB: this is the v0 embed contract. The storage layer currently still uses the Temporal persistence path internally; task #41 migrates it to a ZAP-native store so Embed becomes a pure stdlib+luxfi/zap binary with no upstream imports at all.
Source Files