Skip to content

v0.18.0

Choose a tag to compare

@github-actions github-actions released this 28 Oct 18:15
· 212 commits to main since this release
v0.18.0
32bfe9f

Feature release. The additions are new API and opt-in parse options; the default parser keeps its behaviour except for the three fixes below, and the minimum Go version stays at 1.26.

Heads-up: SpecSchedule gains a DSTSkip field. Code in another package that builds a SpecSchedule with an unkeyed struct literal (values without field names) no longer compiles until it adds one more value. Code that gets its schedules from a parser, or uses field names, is not affected.

Running a job once across several instances

Several scheduler instances that run the same jobs can now coordinate through a shared Locker. The interface is in the library; the store (Redis, PostgreSQL, …) stays in your code. ADR-025 records the decisions.

  • SkipDuplicateRuns(locker, name, ttl, logger) runs each scheduled time once across all instances. It reserves name@<scheduled time in UTC> before the run and keeps the reservation after it, so an instance with a late clock cannot run the same time again. By @CybotTM (#437).
  • SkipWhileLocked(locker, key, ttl, logger) skips a run while another run on any instance holds the same key, for example a resource name, and releases the key when the run ends, also after a panic. By @CybotTM (#439).
  • NewMemoryLocker(clock) is a Locker for one process and for tests (#437).
  • NewConcurrencyGroups() with MaxConcurrent and MaxConcurrentSkip share a concurrency limit by name within one process, between jobs that do not share one wrapper value. By @CybotTM (#438).
  • docs/DISTRIBUTED_LOCKING_GUIDE.md now builds on these wrappers and explains why a lock named after the job and released after the run does not deduplicate. Its PostgreSQL pattern releases the advisory lock on the connection that took it (#439).

Schedules

  • Union(schedules...) and ParseUnion(parser, specs...) run one entry on several cron expressions. A time that two expressions share runs the job once. By @CybotTM (#436).
  • @every_aligned 1h runs at every multiple of the interval since 1970-01-01 00:00 UTC, so a restart does not delay the job and all instances compute the same times, which SkipDuplicateRuns needs. @every_start 1h counts from the start, as plain @every does by default. The AlignEvery parse option lets an application make plain @every aligned. ADR-026 records the decisions. By @CybotTM (#440).

Parse options for existing crontabs

All of them are opt-in; the default parser is unchanged. Thanks to @norman-abramovitz for asking in #427 whether robfig/cron behaviour belongs in the scheduler at all, before these options landed.

  • LenientSteps accepts steps at or above the range size (*/60, 0-5/10) and a step on Sunday-as-7 (7/2), as robfig/cron and Vixie cron do. Contributed by @riki137 (#419).
  • StrictDays rejects a day of month that occurs in none of the selected months, such as 0 0 30 2 *, at parse time instead of letting Next return the zero time after a five-year search. Contributed by @riki137 (#421).
  • StepWildcard: with DowOrDom, a stepped star (*/2) in a day field still counts as unrestricted, as in Vixie cron and cronie. Contributed by @riki137 (#420).
  • RobfigCompat parses and schedules specs like robfig/cron v3. It combines DowOrDom with LenientSteps, EveryRoundUp (round an interval below the minimum up instead of rejecting it) and DSTSkip (skip a time in the spring-forward gap instead of running it in the hour after). The three are also usable on their own. Contributed by @mrueg (#426).

Fixes

  • @every 1h and other intervals no longer lose a regular run on the DST fall-back day. In America/New_York, @every 1h was scheduled 2 times instead of 3 across the fall-back hour of 2026-11-01. Calendar specs keep the duplicate guard. By @CybotTM (#440).
  • A wraparound range whose start is above the field maximum or whose end is below the field minimum is a parse error. 0 25-1 * * * and 0 0 5-0 * * parsed in 0.17.0 (#419).
  • With a fractional WithMinEveryInterval minimum, an interval is no longer truncated below that minimum. With 1500ms, @every 1700ms ran every 1s in 0.17.0 and runs every 2s now (#426).

Full changelog: v0.17.0...v0.18.0