> ## Documentation index
> Fetch the complete documentation index at: https://goncordia.docs7.io/llms.txt
> Ask it with GET https://goncordia.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# Periodic and cron jobs

> Schedules, cron expressions, time zones, and catch-up

`CronScheduler` enqueues jobs on a schedule. Pair it with a `WorkerPool` that processes them.

```go
import "github.com/kirimatt/goncordia/v2/core"

cs := goncordia.NewCronScheduler(d, []goncordia.PeriodicJob{
    {
        ID:       "hourly-cleanup", // stable ID enables durable cursor + deduplication
        StartAt:  time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
        Schedule: core.Every(time.Hour),
        Args:     CleanupArgs{},
        CatchUp:  goncordia.CronCatchUpAll,
    },
    {
        Schedule: core.Every(24 * time.Hour),
        Args:     ReportArgs{},
        Opts:     &core.InsertOpts{Queue: "low-priority"},
    },
}, goncordia.CronConfig{
    TickInterval: time.Second, // how often to check for due jobs
    LeaderName:   "hourly-maintenance",
    LeaderTTL:    30 * time.Second,
    MaxCatchUp:   100,
})

go cs.Start(ctx)   // blocks; cancel ctx to stop
go wp.Start(ctx)   // worker pool processes the enqueued jobs
```

## Custom schedule

```go
// core.ScheduleFunc adapts any function to the Schedule interface.
sched := core.ScheduleFunc(func(last time.Time) time.Time {
    if last.IsZero() {
        return time.Time{} // run immediately on first tick
    }
    // Business-hours only: next run at 09:00 the following day
    next := last.Add(24 * time.Hour)
    next = time.Date(next.Year(), next.Month(), next.Day(), 9, 0, 0, 0, next.Location())
    return next
})
```

## Cron expressions and time zones

```go
newYork, _ := time.LoadLocation("America/New_York")
weekdayMorning, err := core.Cron("30 9 * * 1-5", newYork)

cs := goncordia.NewCronScheduler(d, []goncordia.PeriodicJob{
    {Schedule: weekdayMorning, Args: ReportArgs{}},
}, goncordia.CronConfig{})
```

`core.Cron` accepts standard five-field expressions and evaluates calendar
boundaries in the supplied location, including daylight-saving transitions.
Pass `nil` to use UTC. Invalid expressions return an error during setup.

## Notes

- The scheduler fires each job on the **first tick** after `Start`, then respects the interval.
- A job with an empty `ID` uses that legacy process-local behavior. For durable
  scheduling, provide a stable `ID` and `StartAt`; the first occurrence is
  `Schedule.Next(StartAt)`.
- Durable cursors are persisted by the driver and advanced with compare-and-swap
  after enqueue. Each occurrence uses a permanent uniqueness key, so leader
  failover or a crash between enqueue and cursor advancement cannot duplicate it.
- `CronCatchUpAll` enqueues missed occurrences up to `MaxCatchUp` per tick,
  `CronCatchUpLatest` keeps only the latest, and `CronSkipMissed` drops old
  occurrences while still enqueueing an occurrence reached on the current tick.
- `CronScheduler` only *enqueues* — workers run via `WorkerPool`.
- Multiple scheduler instances are safe: only the current lease holder enqueues jobs.
- Scheduler shutdown releases leadership only when that scheduler instance still
  owns the lease; a stale instance cannot resign a newer leader.
