// Package scheduling decides when scheduled jobs run and with what // concurrency. Storage and delivery are behind JobSource and Runner. package scheduling import ( "context" "errors" "fmt" "strings" "time" ) // Pool is how a job's runs are dispatched relative to other jobs. type Pool string const ( // PoolParallel runs the job concurrently with every other job, bounded // only by the engine's MaxParallel cap. PoolParallel Pool = "parallel" // PoolSequential runs the job on a single shared worker, one at a time, // in the order the source returned them. Use it for jobs that contend // for a resource that tolerates no concurrency. PoolSequential Pool = "sequential" ) // Validate rejects an unknown pool. The empty pool is valid and means // PoolSequential: an unlabelled job is assumed to want the safer of the two, // because wrongly serialising a job costs latency while wrongly parallelising // one costs correctness. func (p Pool) Validate() error { switch p { case "", PoolParallel, PoolSequential: return nil default: return fmt.Errorf("scheduling: unknown pool %q", string(p)) } } // resolve maps the empty pool onto its documented default. func (p Pool) resolve() Pool { if p == "" { return PoolSequential } return p } // Job is one claimed run as handed to the engine. type Job struct { // ID is the schedule id. It is the overlap key: while a run of the // schedule is queued or in flight, another claimed run of it is skipped. ID string // RunID is the claimed run the outcome is recorded against. RunID int64 // Pool selects the dispatch pool. Empty means PoolSequential. Pool Pool // Detail is the schedule name, recorded on emitted events. Detail string ScheduledFor time.Time BuiltIn bool } // Validate checks the fields the engine relies on. func (j Job) Validate() error { if strings.TrimSpace(j.ID) == "" { return errors.New("scheduling: job id must be non-empty") } return j.Pool.Validate() } // JobSource claims the runs due at an instant and records how each ended. type JobSource interface { Due(ctx context.Context, now time.Time) ([]Job, error) // Finish records a run's result: RunSucceeded, RunFailed with err, or // RunSkipped when the schedule's previous run was still going. Finish(ctx context.Context, job Job, result RunResult, err error) error } // Runner executes one due job. Implementations must respect ctx: the engine // bounds every run with JobTimeout and cancels on shutdown, but a Runner that // ignores cancellation can still delay Stop up to Stop's own deadline. type Runner interface { Run(ctx context.Context, job Job) error } // Clock is injectable time: Now for timestamps and After for the tick sleep. // Loop timing is tested against a fake clock, never wall-clock sleeps. type Clock interface { Now() time.Time After(d time.Duration) <-chan time.Time } type systemClock struct{} func (systemClock) Now() time.Time { return time.Now() } func (systemClock) After(d time.Duration) <-chan time.Time { return time.After(d) } // Sink is the narrow event contract the engine needs. It matches // events.Bus's emitter shape without importing it — the domain declares what // it needs and app wires the implementation in. type Sink interface { Emit(kind, detail string, data map[string]any) }