scheduler

package
v0.0.0-...-fcd67d8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: MIT Imports: 13 Imported by: 0

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

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

func (i *InstrumentedScheduler) ScheduleOnce(name string, runAt time.Time, handler JobFunc) error

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

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 JobFunc

type JobFunc func(ctx context.Context) error

JobFunc is the function signature for jobs.

type JobStatus

type JobStatus string

JobStatus represents the status of a job execution.

const (
	JobStatusPending   JobStatus = "pending"
	JobStatusRunning   JobStatus = "running"
	JobStatusCompleted JobStatus = "completed"
	JobStatusFailed    JobStatus = "failed"
	JobStatusSkipped   JobStatus = "skipped"
)

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) GetJob

func (s *MemoryStore) GetJob(ctx context.Context, name string) (*Job, error)

GetJob 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.

func (*MemoryStore) SaveJob

func (s *MemoryStore) SaveJob(ctx context.Context, job *Job) error

SaveJob implements Store.

type Scheduler

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

Scheduler manages scheduled jobs.

func New

func New(store Store, locker distlock.Locker) *Scheduler

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

func (s *Scheduler) DisableJob(name string) error

DisableJob disables a job.

func (*Scheduler) EnableJob

func (s *Scheduler) EnableJob(name string) error

EnableJob enables a job.

func (*Scheduler) GetJob

func (s *Scheduler) GetJob(name string) (*Job, error)

GetJob retrieves a job by name.

func (*Scheduler) ListJobs

func (s *Scheduler) ListJobs() []*Job

ListJobs returns all registered jobs.

func (*Scheduler) RunNow

func (s *Scheduler) RunNow(ctx context.Context, name string) (*JobExecution, error)

RunNow immediately executes a job (still respects distributed locking when configured).

func (*Scheduler) Schedule

func (s *Scheduler) Schedule(name, schedule string, handler JobFunc) error

Schedule registers a job with a cron schedule.

func (*Scheduler) ScheduleOnce

func (s *Scheduler) ScheduleOnce(name string, runAt time.Time, handler JobFunc) error

ScheduleOnce schedules a one-time job.

func (*Scheduler) SetTickInterval

func (s *Scheduler) SetTickInterval(d time.Duration)

SetTickInterval overrides the polling interval (useful in tests).

func (*Scheduler) Start

func (s *Scheduler) Start(ctx context.Context) error

Start begins the scheduler loop.

func (*Scheduler) Stop

func (s *Scheduler) Stop()

Stop stops the scheduler.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址