Files
coder/coderd/schedule
Thomas Kosiewski 871eb9bd3e feat(coderd/schedule/cron): add Standard schedule constructor (#32063)
## Why

Automations store a five-field cron expression and an IANA time zone.
The scheduler and the management API will parse both with
`coderd/schedule/cron`, as the "Schedules" section of the [Automations
RFC](https://app.notion.com/p/3ded579be59281e39950e686df02fa3d) says.
This adds the parser they will call.

Part of CODAGT-1135.

## What changed

- `cron.Standard(spec, timeZone)` parses a five-field spec that runs on
the wall clock of an IANA zone. Every field can be restricted. It
returns an error for an empty spec, a wrong field count, a `CRON_TZ=` or
`TZ=` prefix, an empty or unknown zone, a zone name with an empty, `.`
or `..` segment such as `./localtime`, a name that starts with `posix/`
or `right/` (directories of zone data that some hosts have, with other
versions of the zones), `Local` (a Go name for the host's zone), a name
whose last segment is `localtime`, `posixrules` or `Factory` (files in a
host's zone data that are not zones), and a spec that never runs, such
as `0 0 30 2 *`.
- `Next` on a `Standard` schedule follows the RFC's daylight saving
rule. A repeated local time runs once, at its first instance. A
nonexistent local time runs at the first local time after the change.
`robfig/cron` does neither: in America/New_York it runs `30 1 * * *`
twice on 2026-11-01 and skips `30 2 * * *` on 2026-03-08. So `Standard`
walks the matching wall-clock readings and resolves each one to an
instant from the zone's UTC offsets. Every loop has a fixed bound, and
`Next` always returns a later time for a `Standard` schedule. It
searches at least 16 years ahead, past the eight years between two leap
days across 2100. `Weekly`, `Daily` and `TimeRange` keep their behavior.
- `Schedule.MinInterval()` returns the shortest distance between two
times of day at which the schedule runs, counted around the clock. One
time of day gives 24 hours. The management API will compare it with the
deployment's minimum interval.

## Scope

This PR adds no minimum interval policy and no configuration. Nothing
calls the new code yet. The scheduler loop and the API come in later
PRs.

## Tradeoffs

- `MinInterval` reads only the hour and minute fields, with no calendar.
The RFC allows a minimum interval of one minute to 24 hours, so the
value only has to be right below 24 hours, and a scan over the calendar
kept missing cases. While the zone's UTC offset does not change, no two
runs are closer than the value. The doc comment states two limits, and a
test pins each.
- A change of the UTC offset (daylight saving) can shorten a gap that
spans it by up to the size of the change: `1,58 1,3 * * *` in
America/New_York gives 57 minutes, and its runs on 2026-03-08 are 3
minutes apart.
- A pair of times across midnight counts even when the day fields never
match two days in a row: `0,58 0,23 * * 1` gives 2 minutes, but its runs
are 58 minutes apart at least, so a check can reject a schedule that the
minimum allows.
- The RFC rule, read as written, means a wildcard schedule such as `*/15
* * * *` does not run during the second pass of a repeated hour. In
America/New_York on 2026-11-01 it runs at 01:45 EDT and next at 02:00
EST.
- `Standard` resolves a reading from the zone's offsets and does not use
Go's zone period bounds, which are wrong after the last transition in a
zone's data.

## Live check

None. This is a library that nothing calls yet.

---
_Generated with [`xum`](https://github.com/coder/xum) • Model:
`anthropic:claude-sonnet-5-5` • Thinking: `xhigh`_
2026-11-12 14:32:30 +01:00
..