cron

robfig/cron is the de facto cron job scheduler for Go, letting programs register functions or Job implementations against standard cron expressions (* * * * *) or shorthand descriptors like @hourly and @every 1h30m. The scheduler runs entirely on the Go standard library — no external dependencies — coordinating a single background goroutine with channel-based synchronization so entries can be added, removed, or snapshotted safely from other goroutines while the cron loop is running.

Version 3 (the current major version, imported as github.com/robfig/cron/v3) rebuilt the library’s construction API around functional options (cron.New(cron.WithSeconds(), cron.WithChain(...))) and introduced a Chain/JobWrapper decorator system that lets callers compose cross-cutting behaviors — panic recovery, skip-if-still-running, delay-if-still-running, and structured logging — around any job without subclassing.

What You Get

• A Cron scheduler type supporting AddFunc/AddJob, Remove, Entries, Start/Run, and a context-returning Stop for graceful shutdown
• Standard 5-field cron parsing by default, with an opt-in 6-field seconds format for Quartz-style schedules via WithSeconds()
• Shorthand schedule descriptors (@yearly, @monthly, @weekly, @daily, @hourly, @every <duration>)
• A Chain/JobWrapper middleware system with built-in Recover, DelayIfStillRunning, and SkipIfStillRunning wrappers
• Per-schedule timezone support via CRON_TZ= prefix or a custom Location, correctly handling DST transitions
• A pluggable Logger interface compatible with the go-logr ecosystem, with PrintfLogger/VerbosePrintfLogger adapters for the standard log package

Common Use Cases

• Running periodic maintenance tasks (cache eviction, cleanup jobs, report generation) inside a long-running Go service
• Scheduling recurring background jobs in a self-hosted application without pulling in an external job queue or message broker
• Building internal tooling that needs cron-like scheduling embedded directly in a single Go binary
• Coordinating multiple periodic tasks with different timezones within one process using per-entry CRON_TZ overrides
• Wrapping scheduled jobs with panic recovery and overlap protection in production services via the Chain API

Under The Hood

Architecture

The Cron type (cron.go) coordinates its entry list through unbuffered channels — add, remove, snapshot, and stop — so the single background goroutine running run() never races with callers invoking AddFunc, Remove, or Entries from other goroutines. Each Entry pairs a Schedule (the SpecSchedule bitmask type in spec.go, or a ConstantDelaySchedule for @every) with a WrappedJob, produced by passing the user’s Job through the configured Chain (chain.go) at registration time. The run() loop sorts entries by next-fire time and sleeps on a single time.Timer sized to the soonest entry, re-evaluating on each wake, add, or remove. A ScheduleParser interface (parser.go) decouples spec-string parsing from the scheduler itself, so WithParser/WithSeconds can swap in alternate grammars without touching Cron. Changing the bitmask representation in SpecSchedule would require lockstep changes to both the six-field parser and every Next() calculation.

Tech Stack

The module (github.com/robfig/cron/v3, go.mod targets Go 1.12) has zero third-party runtime dependencies — it uses only the standard library (context, sort, sync, time, fmt, runtime, log, os, strings). There is no build tooling beyond go build/go test; a .travis.yml runs the test suite in CI. The Logger interface is deliberately shaped to be compatible with github.com/go-logr/logr without requiring it as a dependency.

Code Quality

Test coverage is extensive relative to the implementation — roughly 1,700 lines of tests (cron_test.go, parser_test.go, spec_test.go, chain_test.go, constantdelay_test.go, option_test.go) against under 1,500 lines of source. parser_test.go and spec_test.go use table-driven tests covering every field type, special character (* / , - ?), and explicit DST-transition fixtures; cron_test.go exercises concurrent add/remove/stop behavior. Exported types carry godoc comments, Parse functions return typed errors rather than panicking, and naming is consistent and idiomatic Go. No dedicated example test files or CONTRIBUTING guide were found, and there is no linter configuration beyond go vet/go test in CI.

API Design The v3 rewrite replaced ad-hoc field setters with functional options (cron.New(cron.WithSeconds(), cron.WithChain(cron.Recover(logger)))), keeping the zero-value-friendly cron.New() as the common case. The Job/FuncJob pair lets callers register either a plain func() or a type implementing Run(), and the Chain/JobWrapper decorator pattern gives users a composable way to layer panic recovery, overlap protection, and logging onto jobs without wrapper boilerplate — an ergonomic touch that’s uncommon in scheduling libraries of this size. The underlying cron semantics follow the well-known standard format rather than introducing anything novel.