README
¶
Cron
The cron library is a cron job library for Go.
It is a fork of robfig/cron with some improvements.
Thanks to robfig/cron for the original work, and thanks to all the contributors.
[!IMPORTANT]
v4.xmay introduce situations that are not backward compatible.The reason for this is that we are using
v4.xas a transitional version. In this version, we will try to improve the functionality of the components as much as possible until the release ofv5.x.When releasing a new version, backward compatibility is the default behavior. If there are any incompatibilities, they will be indicated in the release notes.
Installation
go get github.com/flc1125/go-cron/v4
Usage
package main
import (
"context"
"github.com/flc1125/go-cron/v4"
"github.com/flc1125/go-cron/middleware/nooverlapping/v4"
"github.com/flc1125/go-cron/middleware/recovery/v4"
)
func main() {
c := cron.New(
cron.WithSeconds(), // if you want to use seconds, you can use this option
cron.WithMiddleware(
recovery.New(), // recover panic
nooverlapping.New(), // prevent job overlapping
),
cron.WithContext(context.Background()), // use custom context
// ... other options
)
// use middleware
c.Use(recovery.New(), nooverlapping.New()) // use middleware
// add job
entryID, _ := c.AddJob("* * * * * *", cron.JobFunc(func(ctx context.Context) error {
// do something
return nil
}))
_ = entryID
// add func
_, _ = c.AddFunc("* * * * * *", func(ctx context.Context) error {
// do something
return nil
}, recovery.New(), nooverlapping.New()) // use middleware for this job
// start cron
c.Start()
// stop cron
c.Stop()
}
Middleware
- recovery: Recovers from panics in job execution, ensuring system stability.
- delayoverlapping: Delays execution of overlapping jobs instead of running them concurrently.
- nooverlapping: Prevents concurrent execution of the same job.
- distributednooverlapping: Prevents concurrent execution across multiple instances using distributed locking.
- otel: Provides OpenTelemetry integration for job execution tracing.
License
- The MIT License (MIT). Please see License File for more information.
- The original work is licensed under the MIT License (MIT). Please see robfig/cron License File
Documentation
¶
Overview ¶
Package cron provides a cron job scheduler for Go applications.
This package is a fork of robfig/cron with significant improvements including context support, middleware system, better error handling, and enhanced scheduling capabilities.
Basic Usage ¶
Creating and starting a basic cron scheduler:
c := cron.New()
c.AddFunc("0 30 * * * *", func(ctx context.Context) error {
fmt.Println("Every hour on the half hour")
return nil
})
c.Start()
Schedule Format ¶
The scheduler supports both standard 5-field cron expressions and extended 6-field expressions with seconds:
Standard (5-field): "30 * * * *" (every hour at 30 minutes) Extended (6-field): "0 30 * * * *" (every hour at 30 minutes, 0 seconds)
Field order: [second] minute hour day month weekday
Special characters:
- * : matches any value
- , : value list separator
- - : range of values
- / : step values
- @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly : predefined schedules
Jobs and Functions ¶
Jobs can be added in multiple ways:
// Add a function
c.AddFunc("* * * * *", func(ctx context.Context) error {
// Job implementation
return nil
})
// Add a Job interface implementation
c.AddJob("* * * * *", cron.JobFunc(func(ctx context.Context) error {
// Job implementation
return nil
}))
// Custom Job implementation
type MyJob struct{}
func (j MyJob) Run(ctx context.Context) error {
// Job implementation
return nil
}
c.AddJob("* * * * *", MyJob{})
Middleware System ¶
The package provides a flexible middleware system for job execution:
c := cron.New(
cron.WithMiddleware(
recovery.New(), // Recover from panics
nooverlapping.New(), // Prevent job overlapping
),
)
// Apply middleware to specific jobs
c.AddFunc("* * * * *", myFunc, recovery.New())
// Use middleware on running cron
c.Use(recovery.New(), nooverlapping.New())
Available middleware:
- recovery: Recovers from panics in job execution
- nooverlapping: Prevents concurrent execution of the same job
- delayoverlapping: Delays overlapping job execution
- distributednooverlapping: Distributed job overlap prevention
- otel: OpenTelemetry integration for tracing
Configuration Options ¶
The cron scheduler can be configured with various options:
c := cron.New( cron.WithSeconds(), // Enable seconds field cron.WithLocation(time.UTC), // Set timezone cron.WithContext(ctx), // Set context cron.WithLogger(myLogger), // Custom logger cron.WithParser(myParser), // Custom parser )
Context Support ¶
All jobs receive a context.Context parameter, enabling:
- Cancellation and timeout handling
- Value passing between middleware and jobs
- Graceful shutdown coordination
Lifecycle Management ¶
c := cron.New()
// Add jobs
entryID, err := c.AddFunc("* * * * *", myFunc)
if err != nil {
// Handle error
}
// Start the scheduler
c.Start()
// Remove jobs
c.Remove(entryID)
// Stop the scheduler (waits for running jobs)
c.Stop()
// Get current entries
entries := c.Entries()
Error Handling ¶
Jobs can return errors, which are handled by the configured logger:
c.AddFunc("* * * * *", func(ctx context.Context) error {
if err := doSomething(); err != nil {
return fmt.Errorf("job failed: %w", err)
}
return nil
})
Thread Safety ¶
The cron scheduler is thread-safe and can be safely accessed from multiple goroutines. All public methods are protected by appropriate synchronization.
Index ¶
- Variables
- func Version() string
- func WithEntryContext(ctx context.Context, entry *Entry) context.Context
- type ConstantDelaySchedule
- type Cron
- func (c *Cron) AddFunc(spec string, cmd func(ctx context.Context) error, middlewares ...Middleware) (EntryID, error)
- func (c *Cron) AddJob(spec string, cmd Job, middlewares ...Middleware) (EntryID, error)
- func (c *Cron) Entries() []Entry
- func (c *Cron) Entry(id EntryID) Entry
- func (c *Cron) IsRunning() bool
- func (c *Cron) Location() *time.Location
- func (c *Cron) Remove(id EntryID)
- func (c *Cron) Run()
- func (c *Cron) Schedule(schedule Schedule, cmd Job, middlewares ...Middleware) EntryID
- func (c *Cron) Start()
- func (c *Cron) Stop() context.Context
- func (c *Cron) Use(middleware ...Middleware)
- type Entry
- type EntryID
- type EntryOption
- type Job
- type JobFunc
- type Logger
- type Middleware
- type NoopJob
- type Option
- type ParseOption
- type Parser
- type Schedule
- type ScheduleParser
- type SpecSchedule
Constants ¶
This section is empty.
Variables ¶
var DefaultLogger = PrintfLogger(log.New(os.Stdout, "cron: ", log.LstdFlags))
DefaultLogger is used by Cron if none is specified.
var DiscardLogger = PrintfLogger(log.New(io.Discard, "", 0))
DiscardLogger can be used by callers to discard all log messages.
Functions ¶
Types ¶
type ConstantDelaySchedule ¶
ConstantDelaySchedule represents a simple recurring duty cycle, e.g. "Every 5 minutes". It does not support jobs more frequent than once a second.
func Every ¶
func Every(duration time.Duration) ConstantDelaySchedule
Every returns a crontab Schedule that activates once every duration. Delays of less than a second are not supported (will round up to 1 second). Any fields less than a Second are truncated.
type Cron ¶
type Cron struct {
// contains filtered or unexported fields
}
Cron keeps track of any number of entries, invoking the associated func as specified by the schedule. It may be started, stopped, and the entries may be inspected while running.
func New ¶
New returns a new Cron job runner, modified by the given options.
Available Settings
Time Zone Description: The time zone in which schedules are interpreted Default: time.Local Parser Description: Parser converts cron spec strings into cron.Schedules. Default: Accepts this spec: https://en.wikipedia.org/wiki/Cron Chain Description: Wrap submitted jobs to customize behavior. Default: A chain that recovers panics and logs them to stderr.
See "cron.With*" to modify the default behavior.
func (*Cron) AddFunc ¶
func (c *Cron) AddFunc(spec string, cmd func(ctx context.Context) error, middlewares ...Middleware) (EntryID, error)
AddFunc adds a func to the Cron to be run on the given schedule. The spec is parsed using the time zone of this Cron instance as the default. An opaque id is returned that can be used to later remove it.
func (*Cron) AddJob ¶
AddJob adds a Job to the Cron to be run on the given schedule. The spec is parsed using the time zone of this Cron instance as the default. An opaque id is returned that can be used to later remove it.
func (*Cron) Schedule ¶
func (c *Cron) Schedule(schedule Schedule, cmd Job, middlewares ...Middleware) EntryID
Schedule adds a Job to the Cron to be run on the given schedule. The job is wrapped with the configured Chain.
func (*Cron) Start ¶
func (c *Cron) Start()
Start the cron scheduler in its own goroutine, or no-op if already started.
func (*Cron) Stop ¶
Stop stops the cron scheduler if it is running; otherwise it does nothing. A context is returned so the caller can wait for running jobs to complete.
func (*Cron) Use ¶
func (c *Cron) Use(middleware ...Middleware)
Use adds a middleware to the chain of all jobs.
type Entry ¶
type Entry struct {
// contains filtered or unexported fields
}
Entry consists of a schedule and the func to execute on that schedule.
func EntryFromContext ¶
EntryFromContext returns the EntryID from the context.
func NewEntry ¶ added in v4.4.0
func NewEntry(id EntryID, schedule Schedule, job Job, opts ...EntryOption) *Entry
NewEntry creates a new entry with the given schedule and job.
func (*Entry) WrappedJob ¶
type EntryOption ¶
type EntryOption func(*Entry)
func WithEntryMiddlewares ¶
func WithEntryMiddlewares(middlewares ...Middleware) EntryOption
type Logger ¶
type Logger interface {
// Info logs routine messages about cron's operation.
Info(msg string, keysAndValues ...any)
// Error logs an error condition.
Error(err error, msg string, keysAndValues ...any)
}
Logger is the interface used in this package for logging, so that any backend can be plugged in. It is a subset of the github.com/go-logr/logr interface.
func PrintfLogger ¶
PrintfLogger wraps a Printf-based logger (such as the standard library "log") into an implementation of the Logger interface which logs errors only.
func VerbosePrintfLogger ¶
VerbosePrintfLogger wraps a Printf-based logger (such as the standard library "log") into an implementation of the Logger interface which logs everything.
type Middleware ¶
Middleware is a function that wraps a Job to provide additional functionality.
func Chain ¶
func Chain(m ...Middleware) Middleware
Chain is a helper function to compose Middlewares. It returns a Middleware that applies the Middlewares in order.
Chain(m1, m2, m3) => m1(m2(m3(job)))
func NoopMiddleware ¶
func NoopMiddleware() Middleware
NoopMiddleware returns a Middleware that does nothing. It is useful for testing and for composing with other Middlewares.
type NoopJob ¶
type NoopJob struct{}
NoopJob is a job that does nothing. it is useful for testing and examples.
type Option ¶
type Option func(*Cron)
Option represents a modification to the default behavior of a Cron.
func WithContext ¶
WithContext overrides the context used by the Cron.
func WithLocation ¶
WithLocation overrides the timezone of the cron instance.
func WithMiddleware ¶
func WithMiddleware(middlewares ...Middleware) Option
WithMiddleware specifies Middleware to apply to all jobs added to this cron.
func WithParser ¶
func WithParser(p ScheduleParser) Option
WithParser overrides the parser used for interpreting job schedules.
func WithSeconds ¶
func WithSeconds() Option
WithSeconds overrides the parser used for interpreting job schedules to include a seconds field as the first one.
type ParseOption ¶
type ParseOption int
ParseOption Configuration options for creating a parser. Most options specify which fields should be included, while others enable features. If a field is not included the parser will assume a default value. These options do not change the order fields are parse in.
const ( Second ParseOption = 1 << iota // Seconds field, default 0 SecondOptional // Optional seconds field, default 0 Minute // Minutes field, default 0 Hour // Hours field, default 0 Dom // Day of month field, default * Month // Month field, default * Dow // Day of week field, default * DowOptional // Optional day of week field, default * Descriptor // Allow descriptors such as @monthly, @weekly, etc. )
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser A custom Parser that can be configured.
func NewParser ¶
func NewParser(options ParseOption) Parser
NewParser creates a Parser with custom options.
It panics if more than one Optional is given, since it would be impossible to correctly infer which optional is provided or missing in general.
Examples
// Standard parser without descriptors
specParser := NewParser(Minute | Hour | Dom | Month | Dow)
sched, err := specParser.Parse("0 0 15 */3 *")
// Same as above, just excludes time fields
specParser := NewParser(Dom | Month | Dow)
sched, err := specParser.Parse("15 */3 *")
// Same as above, just makes Dow optional
specParser := NewParser(Dom | Month | DowOptional)
sched, err := specParser.Parse("15 */3")
type Schedule ¶
type Schedule interface {
// Next returns the next activation time, later than the given time.
// Next is invoked initially, and then each time the job is run.
Next(time.Time) time.Time
}
Schedule describes a job's duty cycle.
func ParseStandard ¶
ParseStandard returns a new crontab schedule representing the given standardSpec (https://en.wikipedia.org/wiki/Cron). It requires 5 entries representing: minute, hour, day of month, month and day of week, in that order. It returns a descriptive error if the spec is not valid.
It accepts
- Standard crontab specs, e.g. "* * * * ?"
- Descriptors, e.g. "@midnight", "@every 1h30m"
type ScheduleParser ¶
ScheduleParser is an interface for schedule spec parsers that return a Schedule
type SpecSchedule ¶
type SpecSchedule struct {
Second, Minute, Hour, Dom, Month, Dow uint64
// Override location for this schedule.
Location *time.Location
}
SpecSchedule specifies a duty cycle (to the second granularity), based on a traditional crontab specification. It is computed initially and stored as bit sets.
Source Files