gocron is a Go job scheduling package that enables developers to run Go functions at predetermined intervals with a fluent, easy-to-use API. The project is a fork of the original jasonlvhit/gocron repository and has evolved into a comprehensive scheduling solution maintained by the go-co-op organization. The package supports multiple job scheduling paradigms including duration-based intervals, random durations, cron expressions, and calendar-based scheduling for daily, weekly, and monthly recurrence patterns. Jobs can also be scheduled as one-time executions at specific times.
The scheduler architecture separates concerns into three core components: Job objects that encapsulate tasks and their parameters, a Scheduler that tracks all jobs and determines execution timing, and an Executor that handles the actual invocation of job tasks while managing complex execution requirements. This design enables flexible scheduling behavior through different interval timing modes, where jobs can calculate their next run time either from their scheduled start time for predictable cron-like behavior or from completion time for scenarios requiring consistent rest periods between executions, such as rate-limited API calls or resource-intensive operations.
Concurrency management is a significant feature of gocron, offering both per-job and scheduler-wide limiting capabilities. Jobs can operate in singleton mode to either skip overlapping executions or queue them for sequential processing. The scheduler itself can limit the total number of concurrent jobs across all tasks, with both reschedule and queue strategies available. For distributed deployments, gocron supports running multiple instances through elector and locker abstractions, allowing leader election patterns and per-job locking across instances. The project maintains separate repositories for different elector and locker implementations within the go-co-op organization.
The package provides comprehensive observability through event listeners that can trigger actions based on job lifecycle events, a logging interface compatible with various logging libraries, and a metrics collection system. The metrics system includes a Monitor interface for job execution metrics, a MonitorStatus interface for status and error tracking, and a SchedulerMonitor interface providing detailed scheduler and job lifecycle events. Available metrics track scheduler lifecycle events, job management, job execution flow, performance measurements including execution time and scheduling delay, and concurrency constraint violations.
Testing support is built into gocron through provided mocks using gomock and the ability to inject a FakeClock for time mocking, enabling deterministic testing of scheduled jobs. The package offers extensive configuration through job-level options, global job options applied to all jobs in a scheduler, and scheduler-level options.
The repository shares contributors with major projects including rust-lang/rust, ant-design/ant-design, and golang/go. A companion project, gocron-ui, provides a web dashboard for monitoring and managing gocron jobs in real time.
