Files
archie/internal/domain/scheduling/contract.go
T

101 lines
3.3 KiB
Go

// 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 due unit of scheduled work as handed to the engine. It carries
// identity and dispatch policy only: the schedule itself (cron expression,
// next-run time, catch-up policy) belongs to the job store behind JobSource,
// which is why the engine never sees one.
type Job struct {
// ID identifies the job across ticks. It is the overlap key: while a
// run with this ID is queued or in flight, later ticks that report the
// same ID are skipped rather than stacked.
ID string
// Pool selects the dispatch pool. Empty means PoolSequential.
Pool Pool
// Detail is a human-readable label recorded on emitted events so a run
// stays attributable without the engine knowing what the job does.
Detail string
}
// 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 returns the jobs due at an instant.
type JobSource interface {
Due(ctx context.Context, now time.Time) ([]Job, 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)
}