worker generators
Four generators scaffold the worker side: events, listeners and scheduled jobs. New projects already include the cmd/worker binary; add worker retrofits it into older ones.
add event
go tool gpsystem add event <module> <name>
Creates internal/modules/<module>/events/<name>.go (an event struct + EventName()) and, on the module's first event, wires an outbox events.Dispatcher into its Dependencies and constructs it in both cmd/<module>/main.go and cmd/worker/main.go. Idempotent: a second event reuses the dispatcher. Records the event in gpsystem.yaml.
go tool gpsystem add event orders orderPlaced
Then add fields to the generated struct and dispatch it from a service inside Transactor.WithinTransaction (see events).
add listener
go tool gpsystem add listener <module> <event> <name> [--queue <queue>]
Creates a listener stub in <module> and registers it in listeners/register.go. <event> is name for an event the module owns, or producer.name to subscribe to another module's event.
| Flag | Meaning |
|---|---|
--queue | asynq queue the listener runs on (default: the default queue) |
go tool gpsystem add listener orders orderPlaced sendConfirmationEmail --queue emails
go tool gpsystem add listener shipping orders.orderPlaced reserveStock # cross-module
The event must already exist (add event first). Each listener is an independent, retried task: implement the body idempotently.
add job
go tool gpsystem add job <module> <name> --cron "0 3 * * *"
Creates a job handler stub and schedules it in jobs/register.go. --cron accepts 5-field cron specs and asynq descriptors (@every 30m, @daily).
go tool gpsystem add job orders expireStaleCarts --cron "0 * * * *"
add worker
go tool gpsystem add worker
Retrofits the whole worker layer into a project generated before the worker feature: the cmd/worker binary, each module's listeners/ and jobs/ subpackages, the outbox migration, and the Redis/worker config. New projects and new module already include it, so you only need this once on an older project. For a compose.yml / .env.example that lack the anchors, it prints the block to paste rather than failing (those files are not compiled).
What gets wired
| Generator | Creates | Wires (at // gpsystem:* anchors) |
|---|---|---|
add event | events/<name>.go | Dispatcher field in register.go; its construction in cmd/<module> and cmd/worker |
add listener | listeners/<name>.go | events.Listen(...) in listeners/register.go |
add job | jobs/<name>.go | sched.Job(...) in jobs/register.go |
add worker | cmd/worker, listeners//jobs/ subpackage per module, outbox migration | worker/redis config; each module into the worker main |
On a project generated before the worker subpackages existed, add listener and add job stop with guidance: move the old listeners.go / jobs.go from the module root to listeners/register.go / jobs/register.go first.
upgrade templates re-syncs only the copied oapi-codegen templates; it does not touch the worker scaffold. Use add worker to introduce the worker layer into an existing project.add mail scaffolds a mail notifier (internal/modules/<module>/mail/) and, on a project's first notifier, wires mail.Mailer into every entry point. A mail notifier is typically called from a listener generated here; see the contact-email worked example.