Documentation
¶
Overview ¶
Package scheduler provides distributed job scheduling.
Features:
- Cron-based scheduling via robfig/cron (5-field, @hourly/@daily/@weekly, @every)
- One-time delayed jobs
- Optional distributed locking via pkg/concurrency/distlock for single execution
- Optional job persistence via Store (MemoryStore for tests/single-node)
Usage:
store := scheduler.NewMemoryStore()
locker := distlockmemory.New() // or nil for single-node
sched := scheduler.New(store, locker)
sched.Schedule("daily-report", "0 0 * * *", generateReportJob)
sched.Start(ctx)
Index ¶
- type InstrumentedScheduler
- func (i *InstrumentedScheduler) DisableJob(name string) error
- func (i *InstrumentedScheduler) EnableJob(name string) error
- func (i *InstrumentedScheduler) GetJob(name string) (*Job, error)
- func (i *InstrumentedScheduler) ListJobs() []*Job
- func (i *InstrumentedScheduler) RunNow(ctx context.Context, name string) (*JobExecution, error)
- func (i *InstrumentedScheduler) Schedule(name, schedule string, handler JobFunc) error
- func (i *InstrumentedScheduler) ScheduleOnce(name string, runAt time.Time, handler JobFunc) error
- func (i *InstrumentedScheduler) SetTickInterval(d time.Duration)
- func (i *InstrumentedScheduler) Start(ctx context.Context) error
- func (i *InstrumentedScheduler) Stop()
- func (i *InstrumentedScheduler) Underlying() *Scheduler
- type Job
- type JobExecution
- type JobFunc
- type JobStatus
- type MemoryStore
- func (s *MemoryStore) DeleteJob(ctx context.Context, name string) error
- func (s *MemoryStore) GetJob(ctx context.Context, name string) (*Job, error)
- func (s *MemoryStore) ListExecutions(ctx context.Context, jobName string) ([]*JobExecution, error)
- func (s *MemoryStore) ListJobs(ctx context.Context) ([]*Job, error)
- func (s *MemoryStore) SaveExecution(ctx context.Context, jobName string, exec *JobExecution) error
- func (s *MemoryStore) SaveJob(ctx context.Context, job *Job) error
- type Scheduler
- func (s *Scheduler) DisableJob(name string) error
- func (s *Scheduler) EnableJob(name string) error
- func (s *Scheduler) GetJob(name string) (*Job, error)
- func (s *Scheduler) ListJobs() []*Job
- func (s *Scheduler) RunNow(ctx context.Context, name string) (*JobExecution, error)
- func (s *Scheduler) Schedule(name, schedule string, handler JobFunc) error
- func (s *Scheduler) ScheduleOnce(name string, runAt time.Time, handler JobFunc) error
- func (s *Scheduler) SetTickInterval(d time.Duration)
- func (s *Scheduler) Start(ctx context.Context) error
- func (s *Scheduler) Stop()
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InstrumentedScheduler ¶
type InstrumentedScheduler struct {
// contains filtered or unexported fields
}
InstrumentedScheduler wraps Scheduler with logging and OpenTelemetry spans.
func NewInstrumentedScheduler ¶
func NewInstrumentedScheduler(next *Scheduler) *InstrumentedScheduler
NewInstrumentedScheduler creates an instrumented scheduler wrapper.
func (*InstrumentedScheduler) DisableJob ¶
func (i *InstrumentedScheduler) DisableJob(name string) error
DisableJob disables a job.
func (*InstrumentedScheduler) EnableJob ¶
func (i *InstrumentedScheduler) EnableJob(name string) error
EnableJob enables a job.
func (*InstrumentedScheduler) GetJob ¶
func (i *InstrumentedScheduler) GetJob(name string) (*Job, error)
GetJob retrieves a job by name.
func (*InstrumentedScheduler) ListJobs ¶
func (i *InstrumentedScheduler) ListJobs() []*Job
ListJobs returns all registered jobs.
func (*InstrumentedScheduler) RunNow ¶
func (i *InstrumentedScheduler) RunNow(ctx context.Context, name string) (*JobExecution, error)
RunNow immediately executes a job with tracing.
func (*InstrumentedScheduler) Schedule ¶
func (i *InstrumentedScheduler) Schedule(name, schedule string, handler JobFunc) error
Schedule registers a cron job with observability.
func (*InstrumentedScheduler) ScheduleOnce ¶
ScheduleOnce registers a one-time job with observability.
func (*InstrumentedScheduler) SetTickInterval ¶
func (i *InstrumentedScheduler) SetTickInterval(d time.Duration)
SetTickInterval delegates to the underlying scheduler.
func (*InstrumentedScheduler) Start ¶
func (i *InstrumentedScheduler) Start(ctx context.Context) error
Start begins the scheduler loop.
func (*InstrumentedScheduler) Stop ¶
func (i *InstrumentedScheduler) Stop()
Stop stops the scheduler.
func (*InstrumentedScheduler) Underlying ¶
func (i *InstrumentedScheduler) Underlying() *Scheduler
Underlying returns the wrapped scheduler.
type Job ¶
type Job struct {
// ID is the unique job identifier.
ID string
// Name is the job name.
Name string
// Schedule is the cron expression or "once" for one-time.
Schedule string
// NextRun is the next scheduled run time.
NextRun time.Time
// LastRun is the last run time.
LastRun time.Time
// LastStatus is the last execution status.
LastStatus JobStatus
// Timeout is the job timeout.
Timeout time.Duration
// Enabled indicates if the job is active.
Enabled bool
// CreatedAt is when the job was created.
CreatedAt time.Time
}
Job represents a scheduled job.
type JobExecution ¶
type JobExecution struct {
// ID is the execution ID.
ID string
// JobID is the job being executed.
JobID string
// Status is the execution status.
Status JobStatus
// Error is the error message (if failed).
Error string
// StartedAt is when execution started.
StartedAt time.Time
// CompletedAt is when execution completed.
CompletedAt time.Time
}
JobExecution represents a job execution instance.
type MemoryStore ¶
type MemoryStore struct {
// contains filtered or unexported fields
}
MemoryStore is an in-process Store suitable for tests and single-node use.
func NewMemoryStore ¶
func NewMemoryStore() *MemoryStore
NewMemoryStore creates an empty in-memory job store.
func (*MemoryStore) DeleteJob ¶
func (s *MemoryStore) DeleteJob(ctx context.Context, name string) error
DeleteJob implements Store.
func (*MemoryStore) ListExecutions ¶
func (s *MemoryStore) ListExecutions(ctx context.Context, jobName string) ([]*JobExecution, error)
ListExecutions implements Store.
func (*MemoryStore) ListJobs ¶
func (s *MemoryStore) ListJobs(ctx context.Context) ([]*Job, error)
ListJobs implements Store.
func (*MemoryStore) SaveExecution ¶
func (s *MemoryStore) SaveExecution(ctx context.Context, jobName string, exec *JobExecution) error
SaveExecution implements Store.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler manages scheduled jobs.
func New ¶
New creates a scheduler.
store may be nil (ephemeral in-memory maps only). Prefer NewMemoryStore for persistence across restarts within a process, or a durable Store implementation. locker may be nil (no distributed locking; fine for single-node). Pass a pkg/concurrency/distlock.Locker (e.g. memory or Redis adapter) so only one node runs each due job.
func (*Scheduler) DisableJob ¶
DisableJob disables a job.
func (*Scheduler) RunNow ¶
RunNow immediately executes a job (still respects distributed locking when configured).
func (*Scheduler) ScheduleOnce ¶
ScheduleOnce schedules a one-time job.
func (*Scheduler) SetTickInterval ¶
SetTickInterval overrides the polling interval (useful in tests).
type Store ¶
type Store interface {
// SaveJob upserts a job by Name.
SaveJob(ctx context.Context, job *Job) error
// GetJob retrieves a job by name.
GetJob(ctx context.Context, name string) (*Job, error)
// ListJobs returns all persisted jobs.
ListJobs(ctx context.Context) ([]*Job, error)
// DeleteJob removes a job by name.
DeleteJob(ctx context.Context, name string) error
// SaveExecution appends an execution record for a job name.
SaveExecution(ctx context.Context, jobName string, exec *JobExecution) error
// ListExecutions returns executions for a job name.
ListExecutions(ctx context.Context, jobName string) ([]*JobExecution, error)
}
Store persists scheduled jobs and their executions. Implementations may back Redis, SQL, or in-process memory.