Documentation
¶
Overview ¶
Package tasks provides a durable task client for Hanzo Tasks.
Drop-in replacement for Base's Cron():
// Before (cron):
e.App.Cron().Add("settlement", "*/30 * * * * *", func() { ... })
// After (tasks — duration):
app.Tasks().Add("settlement", "30s", fn)
// After (tasks — cron expression):
app.Tasks().Add("daily-cleanup", "0 3 * * *", fn)
Accepts both Go duration strings ("30s", "5m", "1h") and cron expressions ("0 3 * * *", "0 0 * * 1", "0 0 5 1,4,7,10 *"). Detection is automatic: if time.ParseDuration succeeds, it's a duration; otherwise it's cron.
If TASKS_URL is set, schedules run as durable Temporal workflows (retries, dead letter, audit trail). If not, runs locally via goroutine timer (dev mode, same behavior 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:
app.Tasks().Add("settlement", "30s", fn) // recurring (duration)
app.Tasks().Add("daily-cleanup", "0 3 * * *", fn) // recurring (cron)
app.Tasks().Now("webhook.deliver", payload) // fire once immediately
Add() auto-detects duration strings vs cron expressions. Transport: ZAP (binary) > HTTP > local goroutine.
Index ¶
- Constants
- type Client
- func (c *Client) ActiveTickerCount() int
- func (c *Client) Add(name, schedule string, fn func()) error
- func (c *Client) HasJob(name string) bool
- func (c *Client) Now(taskType string, payload map[string]any) error
- func (c *Client) PauseAll()
- func (c *Client) Remove(name string)
- func (c *Client) RemoveAll()
- func (c *Client) ResumeAll()
- func (c *Client) Run(name string) bool
- func (c *Client) Schedules() []Schedule
- func (c *Client) Stop()
- func (c *Client) Total() int
- type Handler
- type Schedule
Constants ¶
const ( OpcodeTaskSubmit uint16 = 0x0050 // one-shot task OpcodeTaskSchedule uint16 = 0x0051 // recurring schedule )
ZAP opcodes for task submission.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client manages both one-shot tasks and recurring schedules.
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) ActiveTickerCount ¶ added in v0.46.0
ActiveTickerCount returns the number of schedules currently ticking locally. Remote (server-side) schedules are counted as active when registered. Used by the legacy cron.HasStarted() accessor.
func (*Client) Add ¶
Add registers a recurring task. schedule is either a Go duration string ("30s", "5m", "1h") or a cron expression ("0 3 * * *", "0 0 * * 1"). Detection is automatic via time.ParseDuration.
app.Tasks().Add("settlement", "30s", fn) // every 30 seconds
app.Tasks().Add("daily-cleanup", "0 3 * * *", fn) // daily at 3am UTC
app.Tasks().Add("weekly-report", "0 0 * * 1", fn) // mondays at midnight
Re-adding with the same name replaces the previous schedule.
func (*Client) HasJob ¶ added in v0.46.0
HasJob reports whether a schedule with the given name is registered.
func (*Client) Now ¶
Enqueue submits a one-shot task for durable execution. Prefers ZAP transport when zapAddr is configured, falls back to HTTP.
func (*Client) PauseAll ¶ added in v0.46.0
func (c *Client) PauseAll()
PauseAll cancels every local tick goroutine but leaves registry entries intact. Use ResumeAll to restart them. Remote (server-side) schedules are untouched — they keep firing unless explicitly Removed.
This is the backing for the legacy cron.Cron.Stop() semantics (stop ticking without losing jobs).
func (*Client) Remove ¶ added in v0.46.0
Remove cancels a named schedule. No-op if the schedule is not registered. For remote schedules, also sends a DELETE to the tasks server.
func (*Client) RemoveAll ¶ added in v0.46.0
func (c *Client) RemoveAll()
RemoveAll cancels every registered schedule and clears the registry. For remote schedules, issues best-effort DELETE to the tasks server.
func (*Client) ResumeAll ¶ added in v0.46.0
func (c *Client) ResumeAll()
ResumeAll restarts tick goroutines for every local entry that has an associated callback but no active ticker. Remote entries are untouched.
This is the backing for the legacy cron.Cron.Start() semantics.
func (*Client) Run ¶ added in v0.46.0
Run invokes the locally registered callback for a schedule, if any. Returns true if a callback was found and executed, false otherwise. Used by the admin "run now" endpoint.
func (*Client) Schedules ¶ added in v0.46.0
Schedules returns a snapshot of all registered schedules. The returned slice is safe for the caller to mutate.
Source Files