Workers

Periodic background jobs

1: Purge

Workers are periodic background jobs that run inside the xodbox process on a configurable schedule. They are the complement to Notifiers: notifiers react to inbound events in real time; workers run independently of traffic and operate on the captured data (pruning old records, aggregating stats, etc.).

Workers are registered in xodbox.yaml under a top-level workers: key, following the same key: value map convention used by handlers and notifiers.

Schedule expressions

The schedule key accepts any robfig/cron v3 expression:

Expression	Meaning
`@daily`	Once a day at midnight
`@hourly`	Once an hour
`@every 30m`	Every 30 minutes
`@every 6h`	Every 6 hours
`0 2 * * *`	Standard 5-field cron (daily at 02:00)
`/15 * * *`	Every 15 minutes

Behaviour

If a worker is still running when its next tick fires, the new tick is silently skipped — there is no pileup.
A worker error is logged but does not stop the scheduler; the worker will run again on the next tick.
Workers are shut down gracefully: on SIGINT/SIGTERM xodbox cancels the context passed to Run and waits for any in-flight run to complete before exiting.

Example

workers:
  ## Docs: https://defektive.github.io/xodbox/docs/pkg/workers/purge/
  - worker: purge
    schedule: "@daily"
    max_age_days: "30"

Available workers

Worker	Description
`purge`	Delete interactions older than N days

1 - Purge

Delete old interactions on a schedule

Deletes interaction records older than a configurable number of days. Run this to keep the SQLite database from growing unbounded during long-running engagements.

Configuration

Key	Required	Default	Notes
`worker`	yes	—	Must be `purge`.
`schedule`	no	`@daily`	Cron expression or `@every` interval. See Workers.
`max_age_days`	no	`30`	Interactions older than this many days are deleted. Must be ≥ 1.

Example

workers:
  # Delete interactions older than 14 days, every night at 02:00.
  - worker: purge
    schedule: "0 2 * * *"
    max_age_days: "14"

Notes

Uses GORM soft-delete (sets deleted_at), so the rows are not immediately reclaimed by SQLite. Run VACUUM manually if you need to shrink the file on disk after a large purge.
max_age_days: "0" (or any non-positive value) is silently ignored and the 30-day default is used instead.