Files
archie/internal/domain/scheduling/contract.go
T
sam 0cb8374269 feat(scheduling): ticker engine with configurable interval and pools
Adds internal/domain/scheduling, the timing half of the cron/scheduling
epic (archie-core-1786637496320-249-be6d9a20): a tick loop that asks a
JobSource what is due at a configurable cadence and dispatches each due
job to the pool it declares.

The package owns *when* a scheduled job runs and nothing else. The job
store, blueprints and delivery routing are separate issues in that epic,
so the engine declares the two contracts it needs from them (JobSource,
Runner) and names no implementation. That is what lets the timing
behaviour be tested against a fake clock with no store, no NATS and no
model.

Behaviour worth stating explicitly, because each is load-bearing:

- The source is authoritative about what is due. The engine applies no
  schedule arithmetic of its own, so cron expressions, fixed intervals
  and catch-up windows stay the store's decision.
- A job never overlaps itself. While a run is queued or in flight, later
  ticks reporting the same ID are skipped rather than stacked, so a job
  slower than the interval runs back-to-back instead of fanning out.
- The pools do not interfere: a blocked sequential job cannot delay a
  parallel one, and a saturated parallel cap cannot delay the sequential
  worker. They share only the tick.
- An empty Pool means sequential, not parallel. Wrongly serialising a
  job costs latency; wrongly parallelising one costs correctness.
- Every failure is contained and reported: source error, job error, job
  panic and job timeout each emit an event and leave the loop running.
- Stop drains gracefully. Run contexts descend from Background rather
  than the loop context, so halting the loop stops new work without
  yanking the context out from under a run already in progress; the
  caller's deadline is what eventually cancels those.
- An engine is single-use. Restarting after Stop is refused because Stop
  leaves the dropped backlog and the claims of runs it did not wait for
  behind, and a restart would re-run stale queued jobs while permanently
  suppressing the claimed ones.

internal/events gains job_run/job_error: a scheduled run has no task and
no chat turn behind it, so without those kinds a job that fired, stalled
or failed is invisible everywhere.
2026-08-24 13:28:45 +10:00

115 lines
4.2 KiB
Go

// Package scheduling is the ticker engine: the timing half of archied's
// cron/scheduling capability (epic archie-core-1786637496320-249-be6d9a20).
// It owns one job and one job only — deciding *when* a scheduled job runs,
// and with what concurrency — and nothing about where jobs are stored, how
// they are authored, or how their output is delivered.
//
// The split is deliberate. A job store (file-backed, cross-process locked)
// and a delivery router are separate issues in that epic; this package
// declares the two contracts it needs from them (JobSource, Runner) and
// names no implementation. That is what lets the timing behaviour — pool
// semantics, overlap suppression, per-run timeouts, bounded shutdown — be
// tested against a fake clock with no store, no NATS and no model.
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 yields the jobs eligible to run at a given instant. The engine
// calls Due once per tick and treats it as authoritative: it applies no
// schedule arithmetic of its own, so a source is free to implement cron
// expressions, fixed intervals or catch-up windows without the engine
// changing.
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)
}