Merge pull request #828 from samcharles93/feat/cron-scheduling-config

feat(config): [scheduling] block, its translator, and the events-bus sink adapter
This commit is contained in:
sam authored and GitHub committed 2026-09-15 00:26:59 +10:00
commit 71c890b89b
11 files changed
+527 -32

No files matched your search

+36
View File
@@ -333,6 +333,42 @@ gate_max_failures = 5
# rate_per_second = 1.0 # per-remote-address token bucket
# rate_burst = 5
# The cron/scheduling ticker engine: how often scheduled jobs are checked,
# how many may run at once, and how long one may run. The engine polls a job
# store for what is due and dispatches each due job to the delivery it names
# -- so nothing here schedules anything by itself, it only tunes the timing.
# Absent is valid: every field defaults independently, and a section naming
# only one of them still gets the defaults for the other two.
#
# Zero (or absent) takes the default named below. A NEGATIVE value is a
# startup error, not a clamp: running something other than what was written
# is how a misconfiguration stays invisible. Zero cannot mean "off" here for
# the same reason it cannot in [tools.tool_policy] -- it is indistinguishable
# from an unset key.
# [scheduling]
# interval = "60s" # tick cadence: how often due jobs are checked.
# # Absent/zero means 1m. The finest granularity a
# # cron-style schedule needs, and polling a local
# # job store that often costs nothing.
# max_parallel = 4 # caps simultaneous parallel-pool runs, so a store
# # reporting many jobs due at once (the first tick
# # after long downtime, typically) cannot launch an
# # unbounded fan-out. Absent/zero means 4. It does
# # not bound the sequential pool, which is one by
# # definition.
# job_timeout = "1h" # bounds one run. Absent/zero means 1h. A job that
# # has not finished in an hour is stuck, and leaving
# # it in flight would suppress every later run of the
# # same job forever.
# events_sink = "none" # "bus" publishes each run and failure on the event
# # stream, which is what the dashboard timeline reads;
# # "none" (the default, same as leaving it unset)
# # leaves the engine unobservable -- a scheduled run
# # has no task or chat turn behind it, so with no
# # sink nothing anywhere records that it fired.
# # Any other value is a startup error, so a typo
# # cannot silently turn observability off.
# Playbook-binding at-rest encryption: [bindings].encryption_key resolves a
# 32-byte high-entropy key through the secret registry (engine + key) and seals
# each binding's HMAC secret in the SQLite bindings.secret column with AES-256-
+38
View File
@@ -0,0 +1,38 @@
package archied
import (
"fmt"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/cronevents"
)
// schedulingConfig translates external input into the domain-owned engine
// configuration and connects the selected event infrastructure.
func schedulingConfig(input configuration.SchedulingInput, bus *events.Bus) (scheduling.EngineConfig, error) {
cfg := scheduling.DefaultEngineConfig()
if input.Interval != 0 {
cfg.Interval = input.Interval.Std()
}
if input.MaxParallel != 0 {
cfg.MaxParallel = input.MaxParallel
}
if input.JobTimeout != 0 {
cfg.JobTimeout = input.JobTimeout.Std()
}
switch input.EventsSink {
case "", configuration.EventsSinkNone:
case configuration.EventsSinkBus:
cfg.Events = cronevents.New(bus)
default:
return scheduling.EngineConfig{}, fmt.Errorf("%w: scheduling.events_sink %q (want %q or %q)",
configuration.ErrInvalidInput, input.EventsSink, configuration.EventsSinkBus, configuration.EventsSinkNone)
}
if err := cfg.Validate(); err != nil {
return scheduling.EngineConfig{}, fmt.Errorf("%w: %w", configuration.ErrInvalidInput, err)
}
return cfg, nil
}
+86
View File
@@ -0,0 +1,86 @@
package archied
import (
"errors"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
func TestSchedulingConfigTranslatesExternalInput(t *testing.T) {
tests := []struct {
name string
input configuration.SchedulingInput
wantInterval time.Duration
wantMaxParallel int
wantJobTimeout time.Duration
}{
{
name: "defaults",
wantInterval: time.Minute,
wantMaxParallel: 4,
wantJobTimeout: time.Hour,
},
{
name: "configured",
input: configuration.SchedulingInput{
Interval: configuration.Duration(30 * time.Second),
MaxParallel: 2,
JobTimeout: configuration.Duration(5 * time.Minute),
},
wantInterval: 30 * time.Second,
wantMaxParallel: 2,
wantJobTimeout: 5 * time.Minute,
},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
got, err := schedulingConfig(tc.input, nil)
if err != nil {
t.Fatal(err)
}
if got.Interval != tc.wantInterval || got.MaxParallel != tc.wantMaxParallel || got.JobTimeout != tc.wantJobTimeout {
t.Errorf("schedulingConfig() = %+v, want interval=%v max_parallel=%d job_timeout=%v",
got, tc.wantInterval, tc.wantMaxParallel, tc.wantJobTimeout)
}
})
}
}
func TestSchedulingConfigRejectsInvalidInput(t *testing.T) {
tests := []configuration.SchedulingInput{
{Interval: configuration.Duration(-time.Second)},
{MaxParallel: -1},
{JobTimeout: configuration.Duration(-time.Second)},
{EventsSink: "kafka"},
}
for _, input := range tests {
if _, err := schedulingConfig(input, nil); !errors.Is(err, configuration.ErrInvalidInput) {
t.Errorf("schedulingConfig(%+v) error = %v, want ErrInvalidInput", input, err)
}
}
}
func TestSchedulingConfigSelectsEventSink(t *testing.T) {
bus := events.NewBus()
t.Cleanup(bus.Close)
for _, mode := range []string{"", configuration.EventsSinkNone} {
cfg, err := schedulingConfig(configuration.SchedulingInput{EventsSink: mode}, bus)
if err != nil {
t.Fatal(err)
}
if cfg.Events != nil {
t.Errorf("events_sink %q produced a sink", mode)
}
}
cfg, err := schedulingConfig(configuration.SchedulingInput{EventsSink: configuration.EventsSinkBus}, bus)
if err != nil {
t.Fatal(err)
}
if cfg.Events == nil {
t.Fatal("events_sink bus produced no sink")
}
}
+25 -22
View File
@@ -10,20 +10,10 @@ import (
"github.com/samcharles93/archie-core/internal/events"
)
// Defaults for the tunables an operator may leave unset.
const (
// DefaultInterval is the tick cadence when none is configured. A minute
// is the finest granularity a cron-style schedule needs, and polling a
// local job store that often costs nothing.
DefaultInterval = time.Minute
// DefaultMaxParallel caps concurrent parallel-pool runs. It exists so a
// store that reports many jobs due at once (the first tick after a long
// downtime, typically) cannot launch an unbounded fan-out.
DefaultMaxParallel = 4
// DefaultJobTimeout bounds one run. A scheduled job that has not
// finished in an hour is stuck, and leaving it in flight would suppress
// every later run of the same job forever.
DefaultJobTimeout = time.Hour
defaultInterval = time.Minute
defaultMaxParallel = 4
defaultJobTimeout = time.Hour
)
// Event kinds emitted by the engine, re-exported so callers of this package
@@ -49,14 +39,15 @@ const sequentialQueueDepth = 256
// take the documented defaults.
type EngineConfig struct {
// Interval is the tick cadence: how often the engine asks its source
// what is due. Zero uses DefaultInterval; negative is an error.
// what is due. Zero uses the value from DefaultEngineConfig; negative
// is an error.
Interval time.Duration
// MaxParallel caps simultaneous parallel-pool runs. Zero uses
// DefaultMaxParallel. It does not bound the sequential pool, which is
// one by definition.
// the value from DefaultEngineConfig. It does not bound the sequential
// pool, which is one by definition.
MaxParallel int
// JobTimeout bounds a single run via context deadline. Zero uses
// DefaultJobTimeout.
// the value from DefaultEngineConfig.
JobTimeout time.Duration
// Clock is injectable time. Nil uses the system clock.
Clock Clock
@@ -65,7 +56,18 @@ type EngineConfig struct {
Events Sink
}
func (c EngineConfig) validate() error {
// DefaultEngineConfig returns the domain-owned defaults for the engine's
// operator-selectable runtime settings.
func DefaultEngineConfig() EngineConfig {
return EngineConfig{
Interval: defaultInterval,
MaxParallel: defaultMaxParallel,
JobTimeout: defaultJobTimeout,
}
}
// Validate rejects unusable engine settings.
func (c EngineConfig) Validate() error {
switch {
case c.Interval < 0:
return fmt.Errorf("scheduling: interval must not be negative, got %v", c.Interval)
@@ -79,14 +81,15 @@ func (c EngineConfig) validate() error {
// withDefaults returns the config with zero values replaced.
func (c EngineConfig) withDefaults() EngineConfig {
d := DefaultEngineConfig()
if c.Interval == 0 {
c.Interval = DefaultInterval
c.Interval = d.Interval
}
if c.MaxParallel == 0 {
c.MaxParallel = DefaultMaxParallel
c.MaxParallel = d.MaxParallel
}
if c.JobTimeout == 0 {
c.JobTimeout = DefaultJobTimeout
c.JobTimeout = d.JobTimeout
}
if c.Clock == nil {
c.Clock = systemClock{}
@@ -134,7 +137,7 @@ func NewEngine(source JobSource, runner Runner, cfg EngineConfig) (*Engine, erro
if runner == nil {
return nil, errors.New("scheduling: runner must not be nil")
}
if err := cfg.validate(); err != nil {
if err := cfg.Validate(); err != nil {
return nil, err
}
cfg = cfg.withDefaults()
+6 -6
View File
@@ -332,14 +332,14 @@ func TestNewEngineAppliesDefaults(t *testing.T) {
if err != nil {
t.Fatalf("NewEngine: %v", err)
}
if got := e.Interval(); got != DefaultInterval {
t.Errorf("interval = %v, want %v", got, DefaultInterval)
if got := e.Interval(); got != time.Minute {
t.Errorf("interval = %v, want 1m", got)
}
if got := e.MaxParallel(); got != DefaultMaxParallel {
t.Errorf("max parallel = %d, want %d", got, DefaultMaxParallel)
if got := e.MaxParallel(); got != 4 {
t.Errorf("max parallel = %d, want 4", got)
}
if got := e.JobTimeout(); got != DefaultJobTimeout {
t.Errorf("job timeout = %v, want %v", got, DefaultJobTimeout)
if got := e.JobTimeout(); got != time.Hour {
t.Errorf("job timeout = %v, want 1h", got)
}
}
@@ -19,6 +19,9 @@ type Document struct {
// It stays for now so this package can own loading without every
// consumer changing at once. Delete when internal/config is dissolved.
Config config.Config
// Scheduling is the decoded [scheduling] input. Application composition
// translates it into domain-owned scheduling.EngineConfig.
Scheduling SchedulingInput
// Provenance lists the files that produced Config, in precedence order.
Provenance Provenance
@@ -138,6 +141,9 @@ func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Documen
if err := ApplyOverlayValues(&next.Config, overrides); err != nil {
return nil, err
}
if err := applySchedulingOverlay(&next.Scheduling, overrides); err != nil {
return nil, err
}
next.Provenance.record(Origin{Path: "config_overlay (runtime)", Role: RoleMain, Layer: LayerOverlay})
return l.finalize(&next)
}
@@ -148,12 +154,18 @@ func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) {
if err := decodeConfigFile(basePath, &doc.Config); err != nil {
return nil, err
}
if err := decodeSchedulingFile(basePath, &doc.Scheduling); err != nil {
return nil, err
}
doc.Provenance.record(Origin{Path: basePath, Role: RoleMain, Layer: LayerBase})
if overlayPath != "" {
if err := decodeConfigFile(overlayPath, &doc.Config); err != nil {
return nil, err
}
if err := decodeSchedulingFile(overlayPath, &doc.Scheduling); err != nil {
return nil, err
}
doc.Provenance.record(Origin{Path: overlayPath, Role: RoleMain, Layer: LayerOverlay})
}
@@ -202,7 +214,7 @@ func (l *Loader) loadDir(doc *Document, dir string, layer Layer) error {
switch path, isYAMLFile, ok := files.main(); {
case ok:
if err := l.decodeMain(&doc.Config, path, isYAMLFile); err != nil {
if err := l.decodeMain(doc, path, isYAMLFile); err != nil {
return err
}
doc.Provenance.record(Origin{Path: path, Role: RoleMain, Layer: layer})
@@ -230,11 +242,17 @@ func (l *Loader) loadDir(doc *Document, dir string, layer Layer) error {
}
// decodeMain decodes the daemon-level file in whichever format it uses.
func (l *Loader) decodeMain(cfg *config.Config, path string, isYAMLFile bool) error {
func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool) error {
if isYAMLFile {
return decodeYAML(path, cfg)
if err := decodeYAML(path, &doc.Config); err != nil {
return err
}
return decodeSchedulingFile(path, &doc.Scheduling)
}
return decodeTOML(path, cfg)
if err := decodeTOML(path, &doc.Config); err != nil {
return err
}
return decodeSchedulingFile(path, &doc.Scheduling)
}
// finalize applies defaults, then validates. The order matters: validation
@@ -0,0 +1,66 @@
package configuration
import (
"fmt"
"time"
"gopkg.in/yaml.v3"
)
// SchedulingInput is the external [scheduling] input document. It deliberately
// contains no runtime defaults or domain dependencies; application composition
// translates it into scheduling.EngineConfig.
type SchedulingInput struct {
Interval Duration `toml:"interval" yaml:"interval"`
MaxParallel int `toml:"max_parallel" yaml:"max_parallel"`
JobTimeout Duration `toml:"job_timeout" yaml:"job_timeout"`
EventsSink string `toml:"events_sink" yaml:"events_sink"`
}
// Duration is a textual duration at the configuration boundary.
type Duration time.Duration
func (d *Duration) UnmarshalText(text []byte) error {
value, err := time.ParseDuration(string(text))
if err != nil {
return err
}
*d = Duration(value)
return nil
}
func (d Duration) Std() time.Duration { return time.Duration(d) }
const (
EventsSinkBus = "bus"
EventsSinkNone = "none"
)
type schedulingDocument struct {
Scheduling SchedulingInput `toml:"scheduling" yaml:"scheduling"`
}
func decodeSchedulingFile(path string, target *SchedulingInput) error {
doc := schedulingDocument{Scheduling: *target}
if err := decodeConfigFile(path, &doc); err != nil {
return err
}
*target = doc.Scheduling
return nil
}
func applySchedulingOverlay(target *SchedulingInput, overrides map[string]any) error {
if len(overrides) == 0 {
return nil
}
data, err := yaml.Marshal(overrides)
if err != nil {
return fmt.Errorf("%w: encoding scheduling overlay: %w", ErrUnreadable, err)
}
doc := schedulingDocument{Scheduling: *target}
if err := yaml.Unmarshal(data, &doc); err != nil {
return fmt.Errorf("%w: parsing scheduling overlay: %w", ErrUnreadable, err)
}
*target = doc.Scheduling
return nil
}
@@ -0,0 +1,77 @@
package configuration
import (
"os"
"path/filepath"
"testing"
"time"
)
func writeSchedulingConfig(t *testing.T, section string) string {
t.Helper()
path := filepath.Join(t.TempDir(), "config.toml")
if err := os.WriteFile(path, []byte("bot_user = \"widget\"\n"+section), 0o600); err != nil {
t.Fatal(err)
}
return path
}
func TestLoaderDecodesSchedulingInputSeparatelyFromRuntimeConfig(t *testing.T) {
doc, err := New(nil).File(writeSchedulingConfig(t, `
[scheduling]
interval = "30s"
max_parallel = 2
job_timeout = "5m"
events_sink = "bus"
`))
if err != nil {
t.Fatal(err)
}
if got := doc.Scheduling.Interval.Std(); got != 30*time.Second {
t.Errorf("Interval = %v, want 30s", got)
}
if got := doc.Scheduling.MaxParallel; got != 2 {
t.Errorf("MaxParallel = %d, want 2", got)
}
if got := doc.Scheduling.JobTimeout.Std(); got != 5*time.Minute {
t.Errorf("JobTimeout = %v, want 5m", got)
}
if got := doc.Scheduling.EventsSink; got != EventsSinkBus {
t.Errorf("EventsSink = %q, want %q", got, EventsSinkBus)
}
}
func TestLoaderLeavesAbsentSchedulingInputUnset(t *testing.T) {
doc, err := New(nil).File(writeSchedulingConfig(t, ""))
if err != nil {
t.Fatal(err)
}
if doc.Scheduling != (SchedulingInput{}) {
t.Errorf("Scheduling = %+v, want zero external input", doc.Scheduling)
}
}
func TestSchedulingFileOverlayKeepsUnspecifiedBaseFields(t *testing.T) {
base := writeSchedulingConfig(t, "[scheduling]\ninterval = \"30s\"\nmax_parallel = 2\n")
overlay := filepath.Join(t.TempDir(), "overlay.toml")
if err := os.WriteFile(overlay, []byte("[scheduling]\njob_timeout = \"5m\"\n"), 0o600); err != nil {
t.Fatal(err)
}
doc, err := New(nil).Overlay(base, overlay)
if err != nil {
t.Fatal(err)
}
if doc.Scheduling.Interval.Std() != 30*time.Second || doc.Scheduling.MaxParallel != 2 || doc.Scheduling.JobTimeout.Std() != 5*time.Minute {
t.Errorf("Scheduling = %+v, want merged input", doc.Scheduling)
}
}
func TestExampleConfigLeavesSchedulingAtDefaults(t *testing.T) {
doc, err := New(nil).File(filepath.Join("..", "..", "..", "config.example.toml"))
if err != nil {
t.Fatal(err)
}
if doc.Scheduling != (SchedulingInput{}) {
t.Errorf("Scheduling = %+v, want commented example to remain unset", doc.Scheduling)
}
}
@@ -0,0 +1,80 @@
package cronevents
import (
"context"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/events"
)
// chanClock is a deterministic scheduling.Clock: one tick per value sent on
// ch, so the test drives the engine instead of waiting on wall-clock time.
// After returns the same channel every time, and the engine re-arms only when
// it is called again -- so nothing fires unless the test says so.
type chanClock struct{ ch chan time.Time }
func (c chanClock) Now() time.Time { return time.Time{} }
func (c chanClock) After(time.Duration) <-chan time.Time { return c.ch }
// staticSource reports the same due jobs on every tick.
type staticSource []scheduling.Job
func (s staticSource) Due(context.Context, time.Time) ([]scheduling.Job, error) { return s, nil }
type okRunner struct{}
func (okRunner) Run(context.Context, scheduling.Job) error { return nil }
// TestEngineSinkPublishesRealRunOnTheBus is the end-to-end proof of the
// adapter: the engine's own emission, over the bus, as an event the
// dashboard's timeline can read. It runs a real engine on a driven clock --
// no sleeps, no wall-clock deadlines -- so the only thing under test is the
// wiring between Emit and Publish.
func TestEngineSinkPublishesRealRunOnTheBus(t *testing.T) {
bus := events.NewBus()
t.Cleanup(bus.Close)
sub := bus.Subscribe(4)
sink := New(bus)
clock := chanClock{ch: make(chan time.Time, 1)}
engine, err := scheduling.NewEngine(
staticSource{{ID: "daily", Pool: scheduling.PoolParallel, Detail: "daily status summary"}},
okRunner{},
scheduling.EngineConfig{Interval: time.Minute, Clock: clock, Events: sink},
)
if err != nil {
t.Fatalf("NewEngine: %v", err)
}
if err := engine.Start(t.Context()); err != nil {
t.Fatalf("Start: %v", err)
}
t.Cleanup(func() {
// WithoutCancel: t.Context() is cancelled before this cleanup runs,
// and a cancelled ctx would only make Stop give up at once.
ctx, cancel := context.WithTimeout(context.WithoutCancel(t.Context()), 10*time.Second)
defer cancel()
if err := engine.Stop(ctx); err != nil {
t.Errorf("Stop: %v", err)
}
})
clock.ch <- time.Time{} // one tick
select {
case got := <-sub.C:
if got.Kind != scheduling.KindJobRun {
t.Errorf("Kind = %q, want %q", got.Kind, scheduling.KindJobRun)
}
if got.Detail != "daily status summary" {
t.Errorf("Detail = %q, want the engine's job detail", got.Detail)
}
if got.Data["job"] != "daily" {
t.Errorf("Data[job] = %v, want %q", got.Data["job"], "daily")
}
case <-time.After(10 * time.Second):
t.Fatal("no job_run event reached the bus: the engine's run is unobservable")
}
}
@@ -0,0 +1,25 @@
// Package cronevents adapts the daemon's event bus to scheduling.Sink.
package cronevents
import (
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/events"
)
// New returns a scheduling sink over bus. A nil bus yields a nil sink.
func New(bus *events.Bus) scheduling.Sink {
if bus == nil {
return nil
}
return busSink{bus: bus}
}
type busSink struct {
bus *events.Bus
}
func (s busSink) Emit(kind, detail string, data map[string]any) {
s.bus.Publish(events.Event{Kind: kind, Detail: detail, Data: data})
}
var _ scheduling.Sink = busSink{}
@@ -0,0 +1,66 @@
package cronevents
import (
"testing"
"github.com/samcharles93/archie-core/internal/domain/scheduling"
"github.com/samcharles93/archie-core/internal/events"
)
// TestSinkPublishesEmitAsJobEvent: the engine's emitted event is the only
// trace a scheduled run leaves (a job has no task, no chat turn and no
// workflow behind it), so the adapter has to carry Kind, Detail and Data
// across unchanged and must not borrow a task-scoped identity it does not
// have.
func TestSinkPublishesEmitAsJobEvent(t *testing.T) {
bus := events.NewBus()
t.Cleanup(bus.Close)
sub := bus.Subscribe(4)
sink := New(bus)
if sink == nil {
t.Fatal("New(bus) = nil, want a sink over the bus")
}
// The shape the engine builds for a completed run
// (internal/domain/scheduling/ticker.go runJob).
sink.Emit(scheduling.KindJobRun, "nightly status", map[string]any{
"job": "nightly-status",
"pool": string(scheduling.PoolSequential),
"duration_ms": int64(12),
})
select {
case got := <-sub.C:
if got.Kind != scheduling.KindJobRun {
t.Errorf("Kind = %q, want %q", got.Kind, scheduling.KindJobRun)
}
if got.Detail != "nightly status" {
t.Errorf("Detail = %q, want unchanged \"nightly status\"", got.Detail)
}
if got.Data["job"] != "nightly-status" {
t.Errorf("Data[job] = %v, want unchanged \"nightly-status\"", got.Data["job"])
}
if got.Data["duration_ms"] != int64(12) {
t.Errorf("Data[duration_ms] = %v, want unchanged 12", got.Data["duration_ms"])
}
// The bus stamps publish time when the event carries none.
if got.At.IsZero() {
t.Error("At is zero: a timeline cannot place an event with no timestamp")
}
if got.TaskID != 0 || got.Repo != "" || got.Issue != 0 || got.Workflow != "" || got.Stage != "" {
t.Errorf("event carries task-scoped identity it has none of: %+v", got)
}
default:
t.Fatal("Emit published no event: the dashboard timeline would see nothing")
}
}
// A missing bus cannot produce an adapter; composition decides whether that
// is acceptable for the selected event mode.
func TestSinkIsNilWithoutABus(t *testing.T) {
sink := New(nil)
if sink != nil {
t.Errorf("New(nil) = %#v, want a nil sink", sink)
}
}