schedule

package
v0.23.1 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package schedule provides explicit recurring job definitions and scheduler lifecycle.

Index

Constants

View Source
const (
	DefaultMisfireGrace     = 15 * time.Minute
	DefaultPollInterval     = 15 * time.Second
	DefaultOperationTimeout = 5 * time.Second
	MaxNameBytes            = 128
)

Variables

View Source
var ErrDefinitionConflict = errors.New("schedule: durable definition conflicts with code")

Functions

func MustRegister

func MustRegister(registry *Registry, definition Definition)

func Register

func Register(registry *Registry, definition Definition) error

Register adds a definition without runtime discovery.

Types

type Config

type Config struct {
	PollInterval     time.Duration
	OperationTimeout time.Duration
	Observer         Observer
}

Config bounds scheduler polling, framework I/O, and callbacks that cooperate with context cancellation. OperationTimeout cannot preempt arbitrary Go code.

type Definition

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

Definition is an immutable recurring typed-job contract.

func Define

func Define[P any](name, expression string, target job.Definition[P], factory Factory[P], options ...Option) (Definition, error)

Define validates and binds a recurring typed-job definition.

func MustDefine

func MustDefine[P any](name, expression string, target job.Definition[P], factory Factory[P], options ...Option) Definition

MustDefine panics when a package-level definition is invalid.

func (Definition) Expression

func (definition Definition) Expression() string

func (Definition) Fingerprint

func (definition Definition) Fingerprint() string

func (Definition) JobName

func (definition Definition) JobName() string

func (Definition) JobPolicy

func (definition Definition) JobPolicy() job.Policy

JobPolicy returns a defensive copy of the effective target-job policy.

func (Definition) MisfireGrace

func (definition Definition) MisfireGrace() time.Duration

func (Definition) Name

func (definition Definition) Name() string

func (Definition) Next

func (definition Definition) Next(after time.Time) time.Time

Next returns the next matching UTC occurrence strictly after after.

func (Definition) Queue

func (definition Definition) Queue() string

func (Definition) TimeZone

func (definition Definition) TimeZone() string

type Event

type Event struct {
	Name        string
	Outcome     Outcome
	ScheduledAt time.Time
	JobID       job.ID
	At          time.Time
}

Event is payload-free durable scheduler lifecycle metadata.

type Factory

type Factory[P any] struct {
	// contains filtered or unexported fields
}

Factory is an opaque typed schedule payload strategy.

func Dynamic

func Dynamic[P any](factory func(Occurrence) (P, error)) Factory[P]

Dynamic binds an occurrence-aware typed payload factory. Its implementation is governed by the schedule's versioned name rather than function identity.

func DynamicContext added in v0.14.2

func DynamicContext[P any](factory func(context.Context, Occurrence) (P, error)) Factory[P]

DynamicContext binds a cancellation-aware occurrence payload factory. Its implementation shares Dynamic's versioned strategy marker, so adopting it does not change an existing schedule definition's fingerprint.

func Static

func Static[P any](payload P) Factory[P]

Static snapshots a payload as canonical encoding/json bytes. Later mutation of the supplied value cannot change dispatched schedule payloads.

type MaterializeFunc

type MaterializeFunc func(context.Context, job.Executor, Occurrence) (job.DispatchResult, error)

MaterializeFunc dispatches the selected occurrence through the executor for the store's current transaction.

type Observer

type Observer interface {
	Observe(context.Context, Event)
}

Observer receives immutable schedule events after durable materialization returns successfully.

func SlogObserver

func SlogObserver(logger *slog.Logger) Observer

SlogObserver emits payload-free schedule decisions through structured logs.

type ObserverFunc

type ObserverFunc func(context.Context, Event)

ObserverFunc adapts a function to Observer.

func (ObserverFunc) Observe

func (observer ObserverFunc) Observe(ctx context.Context, event Event)

type Occurrence

type Occurrence struct {
	Schedule    string
	ScheduledAt time.Time
	TimeZone    string
	// contains filtered or unexported fields
}

Occurrence identifies one cron minute. ScheduledAt is always UTC.

func (Occurrence) LocalTime

func (occurrence Occurrence) LocalTime() time.Time

LocalTime returns the occurrence in its declared location.

type Option

type Option func(*definitionSettings) error

Option changes one schedule definition.

func MisfireGrace

func MisfireGrace(grace time.Duration) Option

MisfireGrace sets the inclusive coalescing window.

func TimeZone

func TimeZone(name string) Option

TimeZone evaluates civil cron fields in one explicit IANA location.

type Outcome

type Outcome string

Outcome describes one durable schedule decision.

const (
	OutcomeNotDue            Outcome = "not_due"
	OutcomeEnqueued          Outcome = "enqueued"
	OutcomeOverlapSuppressed Outcome = "overlap_suppressed"
	OutcomeMisfireSkipped    Outcome = "misfire_skipped"
	OutcomeContended         Outcome = "contended"
)

type Registry

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

Registry contains explicit code-owned schedule definitions.

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Definitions

func (registry *Registry) Definitions() []Definition

Definitions returns deterministic immutable definition values.

func (*Registry) Names

func (registry *Registry) Names() []string

type Result

type Result struct {
	Name        string
	Outcome     Outcome
	ScheduledAt time.Time
	JobID       job.ID
}

Result describes one scheduler decision. A zero ScheduledAt means that no concrete occurrence was selected.

type Scheduler

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

Scheduler materializes due definitions into the durable job queue.

func NewScheduler

func NewScheduler(store Store, registry *Registry, dispatcher job.Dispatcher, config Config) (*Scheduler, error)

func (*Scheduler) DroppedObserverEvents

func (scheduler *Scheduler) DroppedObserverEvents() uint64

DroppedObserverEvents reports events discarded because the configured observer did not keep up with the bounded serialized delivery queue.

func (*Scheduler) Run

func (scheduler *Scheduler) Run(ctx context.Context) error

Run evaluates immediately and then polls until cancellation. Cancellation is a normal daemon shutdown.

func (*Scheduler) RunOnce

func (scheduler *Scheduler) RunOnce(ctx context.Context) ([]Result, error)

RunOnce evaluates each registered definition once in stable name order.

type Status

type Status struct {
	Name             string
	Expression       string
	TimeZone         string
	JobName          string
	Queue            string
	MisfireGrace     time.Duration
	Fingerprint      string
	NextRunAt        time.Time
	LastEvaluatedAt  *time.Time
	LastCursorAt     *time.Time
	LastOccurrenceAt *time.Time
	LastJobID        job.ID
	LastOutcome      Outcome
	CreatedAt        *time.Time
	UpdatedAt        *time.Time
}

Status combines the current code-owned definition with its durable state. Nil timestamps mean that the scheduler has not recorded that transition.

type Store

type Store interface {
	Materialize(context.Context, Definition, MaterializeFunc) (Result, error)
	List(context.Context, []Definition) ([]Status, error)
}

Store is the replaceable durable coordination boundary. Materialize must invoke dispatch and advance its cursor in one atomic transaction.

Directories

Path Synopsis
Package postgres provides the inspectable PostgreSQL schedule store.
Package postgres provides the inspectable PostgreSQL schedule store.

Jump to

Keyboard shortcuts

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