scheduling

Documentation

Overview

Package scheduling provides a task scheduler modelled on Laravel's Task Scheduling. Tasks run on a wall-clock cadence (every X minutes, every hour, every day at a fixed time, …) and are dispatched by a single in-process Runner.

No external cron parser is required — Laravel's most common expressions (EveryMinute, EveryFiveMinutes, Hourly, Daily, Weekly, Monthly, At "HH:MM", Cron expression) are expressed as small Schedule values that the Runner ticks against once per second.

Usage:

s := scheduling.New()
s.Job("cleanup-old-sessions", scheduling.Hourly(), func(ctx context.Context) error {
    return svc.PurgeStaleSessions(ctx)
})
s.Job("nightly-billing", scheduling.DailyAt("02:00"), runBilling)
s.Job("metrics-flush", scheduling.Every(5*time.Minute), flushMetrics)
go s.Run(ctx)

Index

• Variables
• type Runner
  • func New() *Runner
  • func (r *Runner) Job(name string, schedule Schedule, fn TaskFn)
  • func (r *Runner) Logger(fn func(string, ...any)) *Runner
  • func (r *Runner) Run(ctx context.Context) error
  • func (r *Runner) Stop()
  • func (r *Runner) Tasks() []TaskInfo
  • func (r *Runner) Tick(d time.Duration) *Runner
• type Schedule
  • func Daily() Schedule
  • func DailyAt(hhmm string) Schedule
  • func Every(interval time.Duration) Schedule
  • func EveryFiveMinutes() Schedule
  • func EveryMinute() Schedule
  • func Hourly() Schedule
  • func Monthly() Schedule
  • func Weekly() Schedule
• type TaskFn
• type TaskInfo

Variables

var ErrAlreadyRegistered = errors.New("scheduling: name already registered")

ErrAlreadyRegistered is reserved for drivers that detect duplicate task names at register-time when the panic-on-collision behaviour is unsuitable.

Types

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner orchestrates registered tasks.

func New

func New() *Runner

New returns a Runner ticking once per second.

func (*Runner) Job

func (r *Runner) Job(name string, schedule Schedule, fn TaskFn)

Job registers a task. Duplicate names panic to catch typos early.

func (*Runner) Logger

func (r *Runner) Logger(fn func(string, ...any)) *Runner

Logger installs a structured logger callback.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context) error

Run blocks until ctx is cancelled or Stop is called.

func (*Runner) Stop

func (r *Runner) Stop()

Stop signals Run to exit.

func (*Runner) Tasks

func (r *Runner) Tasks() []TaskInfo

Tasks returns metadata for each registered task. Useful for management endpoints / status pages.

func (*Runner) Tick

func (r *Runner) Tick(d time.Duration) *Runner

Tick overrides the polling interval (useful for tests).

type Schedule

type Schedule interface {
	Due(prev, now time.Time) bool
	String() string
}

Schedule decides whether a job is due at instant t. Implementations are stateless — the Runner remembers the last tick.

func Daily

func Daily() Schedule

Daily fires once per day at 00:00 local time.

func DailyAt

func DailyAt(hhmm string) Schedule

DailyAt fires once per day at the given "HH:MM" (local time).

func Every

func Every(interval time.Duration) Schedule

Every returns a Schedule that fires every interval starting from the moment the Runner first sees the job.

func EveryFiveMinutes

func EveryFiveMinutes() Schedule

EveryFiveMinutes is a convenience alias.

func EveryMinute

func EveryMinute() Schedule

EveryMinute is a convenience alias.

func Hourly

func Hourly() Schedule

Hourly fires once per hour at the top of the hour.

func Monthly

func Monthly() Schedule

Monthly fires once per month on the 1st at 00:00.

func Weekly

func Weekly() Schedule

Weekly fires once per week on Monday at 00:00.

type TaskFn

type TaskFn func(ctx context.Context) error

TaskFn is the work performed when a schedule fires.

type TaskInfo

type TaskInfo struct {
	Name     string
	Schedule string
	LastRun  time.Time
	Running  bool
}

TaskInfo is a snapshot of a registered task.