README
¶
togo-framework/scheduler
Task scheduler for togo — cron & recurring jobs, dispatched over the queue.
Install
togo install togo-framework/scheduler
scheduler is the togo answer to Laravel's Scheduler / Celery Beat / Rails recurring jobs. Register a job once, schedule it with a cron expression or a fluent helper, and the scheduler dispatches it over the kernel Queue on time — with overlap prevention and run history built in.
How it works
- Register a named job handler (
scheduler.Register). - Schedule it with a cron expression or a helper (
Service.Schedule). - On each tick the job is dispatched onto the togo Queue so the work runs on a worker, not the cron goroutine. With no queue configured it runs inline.
- A job whose previous run is still in flight is skipped (overlap prevention) and recorded as
skipped. - Every run is recorded (
done/failed/skipped) and panics are recovered into errors.
Usage
package jobs
import (
"context"
"github.com/togo-framework/scheduler"
"github.com/togo-framework/togo"
)
func init() {
// 1. Register handlers (from any plugin's init() or Boot).
scheduler.Register("cleanup", func(ctx context.Context) error {
return purgeExpired(ctx)
})
scheduler.Register("digest", func(ctx context.Context) error {
return sendDailyDigest(ctx)
})
}
// 2. Schedule them once the kernel is booted.
func Schedule(k *togo.Kernel) {
s, ok := scheduler.FromKernel(k)
if !ok {
return
}
s.Schedule("cleanup", scheduler.EveryFiveMinutes) // "*/5 * * * *"
s.Schedule("digest", scheduler.DailyAt(9, 0)) // 09:00 every day
}
Cadence helpers
| Helper | Cron |
|---|---|
EveryMinute |
* * * * * |
EveryFiveMinutes / EveryTenMinutes / EveryFifteenMin / EveryThirtyMin |
*/N * * * * |
Hourly / Daily / Weekly / Monthly |
period start |
DailyAt(hour, minute) |
m h * * * |
HourlyAt(minute) |
m * * * * |
WeeklyOn(weekday, hour, minute) |
m h * * wd |
Every("30s") |
@every 30s (sub-minute / macros) |
Any standard 5-field cron expression or robfig macro (@hourly, @every 1h30m, …) works too.
Managing schedules
s.Pause("digest") // stop firing (keeps the schedule)
s.Resume("digest")
s.Trigger(ctx, "cleanup") // run now, ad-hoc
s.Unschedule("cleanup") // remove the schedule
jobs := s.Jobs() // []ScheduledJob{name, spec, paused}
runs := s.Runs() // recent run history (done/failed/skipped)
Configuration
No required env. The scheduler uses the kernel Queue when present (install togo install togo-framework/queue + a worker) so jobs run off-request; otherwise jobs run inline on the cron goroutine.
Documentation
¶
Overview ¶
Package scheduler runs recurring jobs on a cron schedule, dispatched over the togo queue (Laravel Scheduler / Celery Beat for togo).
Register a job handler once, then schedule it with a cron expression or a fluent helper. On each tick the scheduler dispatches the job over the kernel Queue (so long jobs never block) — or runs it inline when no queue is configured. Overlap is prevented (a job is skipped if its previous run is still in flight) and every run is recorded for inspection.
scheduler.Register("cleanup", func(ctx context.Context) error { return purge(ctx) })
s, _ := scheduler.FromKernel(k)
s.Schedule("cleanup", scheduler.EveryFiveMinutes)
Index ¶
- Constants
- func DailyAt(hour, minute int) string
- func Every(dur string) string
- func HourlyAt(minute int) string
- func Register(name string, fn JobFunc)
- func Registered(name string) bool
- func WeeklyOn(weekday, hour, minute int) string
- type JobFunc
- type Run
- type ScheduledJob
- type Service
- func (s *Service) Jobs() []ScheduledJob
- func (s *Service) Pause(name string)
- func (s *Service) Resume(name string)
- func (s *Service) Runs() []Run
- func (s *Service) Schedule(name, spec string) error
- func (s *Service) Stop()
- func (s *Service) Trigger(ctx context.Context, name string) error
- func (s *Service) Unschedule(name string)
Constants ¶
const ( EveryMinute = "* * * * *" EveryFiveMinutes = "*/5 * * * *" EveryTenMinutes = "*/10 * * * *" EveryFifteenMin = "*/15 * * * *" EveryThirtyMin = "*/30 * * * *" Hourly = "0 * * * *" Daily = "0 0 * * *" Weekly = "0 0 * * 0" Monthly = "0 0 1 * *" )
Common cron cadences (standard 5-field cron, minute resolution).
const ( StatusDone = "done" StatusFailed = "failed" StatusSkipped = "skipped" // previous run still in flight (overlap prevented) )
Run status values.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
Register registers a named job handler. Call it from a plugin's init() or Boot; schedule the job later with Service.Schedule.
func Registered ¶
Registered reports whether a job handler with this name exists.
Types ¶
type Run ¶
type Run struct {
Job string `json:"job"`
Status string `json:"status"`
Started time.Time `json:"started"`
Finished *time.Time `json:"finished,omitempty"`
Error string `json:"error,omitempty"`
}
Run is a single execution of a scheduled job.
type ScheduledJob ¶
type ScheduledJob struct {
Name string `json:"name"`
Spec string `json:"spec"`
Paused bool `json:"paused"`
}
ScheduledJob describes a configured schedule.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the scheduler runtime stored on the kernel (k.Get("scheduler")).
func FromKernel ¶
FromKernel returns the scheduler Service registered on the kernel.
func (*Service) Jobs ¶
func (s *Service) Jobs() []ScheduledJob
Jobs returns the configured schedules.
func (*Service) Schedule ¶
Schedule adds (or replaces) a cron schedule for a registered job. spec is a standard 5-field cron expression ("*/5 * * * *") or a macro ("@every 30s", "@daily"). Use the Every*/Daily* helpers for common cadences.
func (*Service) Unschedule ¶
Unschedule removes a job's schedule (the handler stays registered).
Source Files