From 57d8d48279f4bc98847507d44dce211b0db6f7d8 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 14 Sep 2026 10:51:36 +0000 Subject: [PATCH 1/4] feat(config): add [scheduling] config block The cron ticker engine had no path from operator input to runtime. Add the four settings its EngineConfig is built from, as a declared type rather than loose root fields: interval, max_parallel, job_timeout, events_sink Every field is optional and defaults independently, so an absent section is valid and resolves to the engine's own documented constants. Zero means "unset, give me the default", which is why a negative value is a startup error rather than a clamp -- it is the only way an operator can name an unusable value deliberately, and running something other than what was written is how a misconfiguration stays invisible. events_sink is a simple on/off, "bus" or "none": the engine's Sink contract is the bus's emitter shape and there is exactly one bus in the process, so a named-sink registry would be scaffolding with one entry. Absent resolves to "none", the same shape applyMemoryDefaults and applyNATSDefaults use, so a resolved config has one spelling for "not publishing" rather than two that happen to mean the same thing. config.example.toml documents the block in the house style, commented out like [[repos]] and [capture]: a live example would be a default the operator never chose. --- config.example.toml | 36 +++++++++++++++++++++++++ internal/config/config.go | 57 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) diff --git a/config.example.toml b/config.example.toml index 4e276270f..a278cc71f 100644 --- a/config.example.toml +++ b/config.example.toml @@ -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- diff --git a/internal/config/config.go b/internal/config/config.go index 3a3a99f8c..7f0618363 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -516,6 +516,12 @@ type Config struct { Capture CaptureConfig `toml:"capture" yaml:"capture"` Bindings BindingsConfig `toml:"bindings" yaml:"bindings"` + // Scheduling configures the cron/scheduling ticker engine + // (internal/domain/scheduling). Absent is valid: every field + // defaults independently, so an empty section and no section at + // all produce the same resolved engine configuration. + Scheduling SchedulingConfig `toml:"scheduling" yaml:"scheduling"` + // Memory holds memory provider configuration (from config.memory.yaml). Memory MemoryConfig `toml:"memory" yaml:"memory"` @@ -777,6 +783,57 @@ type CaptureConfig struct { RateBurst int `toml:"rate_burst" yaml:"rate_burst"` } +// SchedulingConfig configures the cron/scheduling ticker engine +// (internal/domain/scheduling, epic +// archie-core-1786637496320-249-be6d9a20). Every field is optional and +// defaults independently, so an absent [scheduling] section is valid and +// resolves to the engine's own documented defaults. +// +// Zero and negative are therefore NOT the same thing here, the same +// distinction config.ToolPolicy and config.CaptureConfig make: zero is +// "unset, give me the default", which leaves negative as the only way an +// operator can name an unusable value deliberately. A negative value is a +// startup error -- a negative interval cannot be a tick cadence, and the +// values are rejected rather than clamped because silently running +// something other than what was written is how a misconfiguration stays +// invisible. +type SchedulingConfig struct { + // Interval is the tick cadence: how often the engine asks its job + // source what is due. Zero or absent means the engine's own + // scheduling.DefaultInterval (one minute); a configured value is + // used as-is. Negative is a startup error. + Interval Duration `toml:"interval" yaml:"interval"` + // MaxParallel caps simultaneous parallel-pool runs. Zero or absent + // means scheduling.DefaultMaxParallel. It does not bound the + // sequential pool, which is one by definition. Negative is a + // startup error. + MaxParallel int `toml:"max_parallel" yaml:"max_parallel"` + // JobTimeout bounds one run via context deadline. Zero or absent + // means scheduling.DefaultJobTimeout. Negative is a startup error. + JobTimeout Duration `toml:"job_timeout" yaml:"job_timeout"` + // EventsSink selects whether the engine's run and error events are + // published on the daemon's event stream. "bus" publishes them; + // absent resolves to "none", which leaves the engine's Events nil -- + // a configuration the engine documents as valid: it still runs, it + // is just unobservable. Any other value is a startup error, so a + // typo cannot silently disable observability. + EventsSink string `toml:"events_sink" yaml:"events_sink"` +} + +// EventsSink mode values for SchedulingConfig.EventsSink. The zero value +// (empty) resolves to EventsSinkNone; these are the explicit spellings, +// shared with validation so the two cannot drift. +const ( + // EventsSinkBus publishes the engine's run and error events on the + // daemon's in-process event bus, which is what the dashboard's + // timeline reads. + EventsSinkBus = "bus" + // EventsSinkNone disables emission. It is the documented way to say + // that without relying on an absent key, and it leaves the engine's + // Events nil -- valid, and unobservable. + EventsSinkNone = "none" +) + // BindingsConfig configures the playbook-binding store (t2db). When // EncryptionKey is unset, binding secrets are persisted as plaintext // (legacy behaviour); when set, they are AES-256-GCM encrypted at rest From 4d838b9fb136003d343320afab8804b26cd668dd Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 14 Sep 2026 10:51:41 +0000 Subject: [PATCH 2/4] feat(configuration): translate [scheduling] into scheduling.EngineConfig The engine needs a fully-resolved configuration, not zero values it has to second-guess. Add the translator the wiring slice then hands to internal/app/archied: - TranslateScheduling resolves unset tunables from the domain's own Default* constants rather than a second copy here, so the two cannot drift. - A negative tunable is reported as a startup error wrapping ErrInvalidInput, matching validateCapture and validatePollInterval. Clamping was rejected: it runs something other than what the operator wrote, which is how a misconfiguration stays invisible. - Events and Clock stay nil. This package owns no bus and no clock -- attaching them is composition -- and the engine documents a nil sink as a valid configuration: it still runs, it is just unobservable. applySchedulingDefaults and validateScheduling keep defaulting and validation separate, the split applyDefaults' own doc explains: the load path applies both, Validate applies only the latter. TDD: the translator tests were written first and failed on assertions (Interval = 0s, want 1m0s; negative values accepted silently), not on compilation. --- .../infrastructure/configuration/defaults.go | 1 + .../configuration/scheduling.go | 96 +++++++ .../configuration/scheduling_test.go | 262 ++++++++++++++++++ .../infrastructure/configuration/validate.go | 7 + 4 files changed, 366 insertions(+) create mode 100644 internal/infrastructure/configuration/scheduling.go create mode 100644 internal/infrastructure/configuration/scheduling_test.go diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index 396eb038c..6854ef38c 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -75,6 +75,7 @@ func (l *Loader) applyDefaults(cfg *config.Config) { applyContainerDefaults(cfg) applyToolPolicyDefaults(cfg) applyCaptureDefaults(cfg) + applySchedulingDefaults(cfg) applyNATSDefaults(cfg) applyMemoryDefaults(cfg) } diff --git a/internal/infrastructure/configuration/scheduling.go b/internal/infrastructure/configuration/scheduling.go new file mode 100644 index 000000000..14ee4ee8e --- /dev/null +++ b/internal/infrastructure/configuration/scheduling.go @@ -0,0 +1,96 @@ +package configuration + +import ( + "fmt" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/scheduling" +) + +// DefaultScheduling returns the defaults an absent [scheduling] section +// resolves to, taken from the engine's own documented constants rather than +// restated here -- one answer for "unset", owned by the domain that acts on +// it. [applySchedulingDefaults] fills a decoded config with them. +func DefaultScheduling() config.SchedulingConfig { + return config.SchedulingConfig{ + Interval: config.Duration(scheduling.DefaultInterval), + MaxParallel: scheduling.DefaultMaxParallel, + JobTimeout: config.Duration(scheduling.DefaultJobTimeout), + EventsSink: config.EventsSinkNone, + } +} + +// applySchedulingDefaults resolves an absent [scheduling] section. Every field +// defaults independently, so a section naming only max_parallel still gets a +// cadence and a run timeout, and "nothing configured" is one resolved state +// rather than two that happen to mean the same thing. +// +// A negative value is left alone for [validateScheduling] to reject. +func applySchedulingDefaults(cfg *config.Config) { + d := DefaultScheduling() + if cfg.Scheduling.Interval == 0 { + cfg.Scheduling.Interval = d.Interval + } + if cfg.Scheduling.MaxParallel == 0 { + cfg.Scheduling.MaxParallel = d.MaxParallel + } + if cfg.Scheduling.JobTimeout == 0 { + cfg.Scheduling.JobTimeout = d.JobTimeout + } + if cfg.Scheduling.EventsSink == "" { + cfg.Scheduling.EventsSink = d.EventsSink + } +} + +// validateScheduling rejects unusable engine tunables. applySchedulingDefaults +// fills every zero value, so this only fires on an explicitly negative one -- +// the engine's own contract documents "negative is an error" for a reason: +// a negative interval cannot be a tick cadence, and clamping it would run +// something other than what the operator wrote, which is how a +// misconfiguration stays invisible. It also rejects an unknown events_sink +// spelling, so a typo cannot silently leave a deployment unobservable. +func validateScheduling(cfg *config.Config) error { + switch { + case cfg.Scheduling.Interval < 0: + return fmt.Errorf("%w: scheduling.interval must not be negative, got %s", ErrInvalidInput, cfg.Scheduling.Interval.Std()) + case cfg.Scheduling.MaxParallel < 0: + return fmt.Errorf("%w: scheduling.max_parallel must not be negative, got %d", ErrInvalidInput, cfg.Scheduling.MaxParallel) + case cfg.Scheduling.JobTimeout < 0: + return fmt.Errorf("%w: scheduling.job_timeout must not be negative, got %s", ErrInvalidInput, cfg.Scheduling.JobTimeout.Std()) + } + // Empty is valid input here (applySchedulingDefaults resolves it to + // "none" before this runs on the real load path); it is not "unknown". + if sink := cfg.Scheduling.EventsSink; sink != "" && !oneOf(sink, eventsSinkModes) { + return fmt.Errorf("%w: scheduling.events_sink %q (want %s)", ErrInvalidInput, sink, list(eventsSinkModes)) + } + return nil +} + +// TranslateScheduling turns the operator's [scheduling] input into the +// engine's own configuration type, fully resolved: an unset tunable becomes +// the engine's documented default, so the engine receives what the daemon +// means rather than zero values it has to second-guess. +// +// Clock and Events are deliberately left nil. This package owns no clock (the +// engine's system clock is the deployment's answer, not an operator's) and no +// bus: attaching the sink is composition, and a nil Events is a configuration +// the engine documents as valid -- it still runs, it is just unobservable. +// +// A negative tunable, or an unknown events_sink, is reported rather than +// repaired, so a bad file stops startup instead of running something the +// operator did not ask for. +func TranslateScheduling(cfg config.SchedulingConfig) (scheduling.EngineConfig, error) { + holder := config.Config{Scheduling: cfg} + if err := validateScheduling(&holder); err != nil { + return scheduling.EngineConfig{}, err + } + // Resolve through the same applier the load path uses, so a hand-built + // config and a decoded file cannot resolve differently. + applySchedulingDefaults(&holder) + + return scheduling.EngineConfig{ + Interval: holder.Scheduling.Interval.Std(), + MaxParallel: holder.Scheduling.MaxParallel, + JobTimeout: holder.Scheduling.JobTimeout.Std(), + }, nil +} diff --git a/internal/infrastructure/configuration/scheduling_test.go b/internal/infrastructure/configuration/scheduling_test.go new file mode 100644 index 000000000..1f1b2feda --- /dev/null +++ b/internal/infrastructure/configuration/scheduling_test.go @@ -0,0 +1,262 @@ +package configuration + +import ( + "errors" + "os" + "path/filepath" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/scheduling" +) + +// writeSchedulingConfig writes a config file whose only content beyond the +// fields every check requires is the given [scheduling] fragment. +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 +} + +// TestTranslateSchedulingResolvesZeroValuesToEngineDefaults pins the +// translator to the engine's own documented constants: the domain has one +// answer for "unset", and a second copy of those numbers here would be free +// to drift from it. +func TestTranslateSchedulingResolvesZeroValuesToEngineDefaults(t *testing.T) { + eng, err := TranslateScheduling(config.SchedulingConfig{}) + if err != nil { + t.Fatalf("TranslateScheduling(zero value) = %v, want nil", err) + } + if got := eng.Interval; got != scheduling.DefaultInterval { + t.Errorf("Interval = %v, want %v", got, scheduling.DefaultInterval) + } + if got := eng.MaxParallel; got != scheduling.DefaultMaxParallel { + t.Errorf("MaxParallel = %d, want %d", got, scheduling.DefaultMaxParallel) + } + if got := eng.JobTimeout; got != scheduling.DefaultJobTimeout { + t.Errorf("JobTimeout = %v, want %v", got, scheduling.DefaultJobTimeout) + } + // Events stays nil: this package owns no bus, and the engine documents a + // nil sink as a valid configuration -- it still runs, it is just + // unobservable. Attaching one is the composition slice's job. + if eng.Events != nil { + t.Errorf("Events = %v, want nil for an absent events_sink", eng.Events) + } +} + +func TestTranslateSchedulingKeepsConfiguredValues(t *testing.T) { + eng, err := TranslateScheduling(config.SchedulingConfig{ + Interval: config.Duration(30 * time.Second), + MaxParallel: 2, + JobTimeout: config.Duration(5 * time.Minute), + }) + if err != nil { + t.Fatalf("TranslateScheduling(configured) = %v, want nil", err) + } + if got := eng.Interval; got != 30*time.Second { + t.Errorf("Interval = %v, want unchanged 30s", got) + } + if got := eng.MaxParallel; got != 2 { + t.Errorf("MaxParallel = %d, want unchanged 2", got) + } + if got := eng.JobTimeout; got != 5*time.Minute { + t.Errorf("JobTimeout = %v, want unchanged 5m", got) + } +} + +// TestTranslateSchedulingRejectsNegativeValues: the engine's own contract +// documents "negative is an error". A clamp would run something other than +// what the operator wrote, which is how a misconfiguration stays invisible, +// so the translator reports it and lets startup fail. +func TestTranslateSchedulingRejectsNegativeValues(t *testing.T) { + tests := []struct { + name string + cfg config.SchedulingConfig + }{ + {name: "interval", cfg: config.SchedulingConfig{Interval: config.Duration(-time.Second)}}, + {name: "max_parallel", cfg: config.SchedulingConfig{MaxParallel: -1}}, + {name: "job_timeout", cfg: config.SchedulingConfig{JobTimeout: config.Duration(-time.Minute)}}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + _, err := TranslateScheduling(tc.cfg) + if err == nil { + t.Fatalf("TranslateScheduling(negative %s) = nil error, want a startup error", tc.name) + } + if !errors.Is(err, ErrInvalidInput) { + t.Errorf("TranslateScheduling(negative %s) = %v, want it to wrap ErrInvalidInput", tc.name, err) + } + }) + } +} + +// TestLoadSchedulingBlockDecodesAllFourFields pins the four toml keys: the +// translator is only reachable from operator input through them. +func TestLoadSchedulingBlockDecodesAllFourFields(t *testing.T) { + path := writeSchedulingConfig(t, ` +[scheduling] +interval = "30s" +max_parallel = 2 +job_timeout = "5m" +events_sink = "bus" +`) + cfg, err := loadFile(path) + if err != nil { + t.Fatalf("loadFile() = %v, want nil", err) + } + if got := cfg.Scheduling.Interval.Std(); got != 30*time.Second { + t.Errorf("Scheduling.Interval = %v, want 30s", got) + } + if got := cfg.Scheduling.MaxParallel; got != 2 { + t.Errorf("Scheduling.MaxParallel = %d, want 2", got) + } + if got := cfg.Scheduling.JobTimeout.Std(); got != 5*time.Minute { + t.Errorf("Scheduling.JobTimeout = %v, want 5m", got) + } + if got := cfg.Scheduling.EventsSink; got != config.EventsSinkBus { + t.Errorf("Scheduling.EventsSink = %q, want %q", got, config.EventsSinkBus) + } + + eng, err := TranslateScheduling(cfg.Scheduling) + if err != nil { + t.Fatalf("TranslateScheduling(loaded) = %v, want nil", err) + } + if eng.Interval != 30*time.Second || eng.MaxParallel != 2 || eng.JobTimeout != 5*time.Minute { + t.Errorf("loaded engine config = %+v, want {30s 2 5m}", eng) + } +} + +// TestLoadAbsentSchedulingSectionResolvesEngineDefaults covers the operator +// who never writes the section at all -- the common case. Both the loaded +// section and the translated engine config must be fully resolved, so +// "nothing configured" and "configured with the defaults" are one state. +func TestLoadAbsentSchedulingSectionResolvesEngineDefaults(t *testing.T) { + cfg, err := loadFile(writeSchedulingConfig(t, "")) + if err != nil { + t.Fatalf("loadFile() = %v, want nil", err) + } + if got := cfg.Scheduling.Interval.Std(); got != scheduling.DefaultInterval { + t.Errorf("Scheduling.Interval = %v, want %v", got, scheduling.DefaultInterval) + } + if got := cfg.Scheduling.MaxParallel; got != scheduling.DefaultMaxParallel { + t.Errorf("Scheduling.MaxParallel = %d, want %d", got, scheduling.DefaultMaxParallel) + } + if got := cfg.Scheduling.JobTimeout.Std(); got != scheduling.DefaultJobTimeout { + t.Errorf("Scheduling.JobTimeout = %v, want %v", got, scheduling.DefaultJobTimeout) + } + + eng, err := TranslateScheduling(cfg.Scheduling) + if err != nil { + t.Fatalf("TranslateScheduling(loaded) = %v, want nil", err) + } + if eng.Interval != scheduling.DefaultInterval { + t.Errorf("Interval = %v, want %v", eng.Interval, scheduling.DefaultInterval) + } + if eng.MaxParallel != scheduling.DefaultMaxParallel { + t.Errorf("MaxParallel = %d, want %d", eng.MaxParallel, scheduling.DefaultMaxParallel) + } + if eng.JobTimeout != scheduling.DefaultJobTimeout { + t.Errorf("JobTimeout = %v, want %v", eng.JobTimeout, scheduling.DefaultJobTimeout) + } +} + +// TestLoadRejectsNegativeSchedulingValues puts the negative-value rule on the +// load path, not just in the translator: a file edit that breaks a running +// deployment (a SIGHUP reload) must be refused with the operator's mistake +// named, rather than applied as a negative cadence. +func TestLoadRejectsNegativeSchedulingValues(t *testing.T) { + tests := []struct { + name string + section string + }{ + {name: "interval", section: "[scheduling]\ninterval = \"-1m\"\n"}, + {name: "max_parallel", section: "[scheduling]\nmax_parallel = -1\n"}, + {name: "job_timeout", section: "[scheduling]\njob_timeout = \"-1h\"\n"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + _, err := loadFile(writeSchedulingConfig(t, tc.section)) + if err == nil { + t.Fatalf("loadFile(negative %s) = nil, want a load failure", tc.name) + } + if !errors.Is(err, ErrInvalidInput) { + t.Errorf("loadFile(negative %s) = %v, want it to wrap ErrInvalidInput", tc.name, err) + } + }) + } +} + +// TestLoadAcceptsEveryDocumentedEventsSinkSpelling pins the on/off +// vocabulary: "bus" publishes on the event stream, and "none" means no sink. +// An absent key resolves to "none" rather than staying empty, the same shape +// applyMemoryDefaults and applyNATSDefaults use -- a resolved config has one +// spelling for "not publishing", not two that happen to mean it. "off" is +// deliberately not a third spelling: a near-miss must be rejected, not +// guessed at. +func TestLoadAcceptsEveryDocumentedEventsSinkSpelling(t *testing.T) { + tests := []struct { + name string + section string + want string + }{ + {name: "absent", section: "", want: config.EventsSinkNone}, + {name: "none", section: "[scheduling]\nevents_sink = \"none\"\n", want: config.EventsSinkNone}, + {name: "bus", section: "[scheduling]\nevents_sink = \"bus\"\n", want: config.EventsSinkBus}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + cfg, err := loadFile(writeSchedulingConfig(t, tc.section)) + if err != nil { + t.Fatalf("loadFile(events_sink %s) = %v, want nil", tc.name, err) + } + if got := cfg.Scheduling.EventsSink; got != tc.want { + t.Errorf("Scheduling.EventsSink = %q, want %q", got, tc.want) + } + }) + } +} + +// TestLoadRejectsUnknownEventsSink: a typo must not silently leave the +// engine unobservable, which is exactly what an unrecognised value would do +// if it defaulted to off. +func TestLoadRejectsUnknownEventsSink(t *testing.T) { + _, err := loadFile(writeSchedulingConfig(t, "[scheduling]\nevents_sink = \"kafka\"\n")) + if err == nil { + t.Fatal("loadFile(unknown events_sink) = nil, want a load failure") + } + if !errors.Is(err, ErrInvalidInput) { + t.Errorf("loadFile(unknown events_sink) = %v, want it to wrap ErrInvalidInput", err) + } +} + +// TestExampleConfigSchedulingSectionIsDocumentationOnly checks the shipped +// template the way an operator's first run will: whatever the [scheduling] +// block documents, the file must load and resolve to the documented state, +// and the block must stay dormant (no live section) the same way [[repos]] +// does -- a live example is a default an operator never chose. +func TestExampleConfigSchedulingSectionIsDocumentationOnly(t *testing.T) { + cfg, err := loadFile(filepath.Join("..", "..", "..", "config.example.toml")) + if err != nil { + t.Fatalf("loadFile(config.example.toml) = %v, want nil", err) + } + eng, err := TranslateScheduling(cfg.Scheduling) + if err != nil { + t.Fatalf("TranslateScheduling(example) = %v, want nil", err) + } + if eng.Interval != scheduling.DefaultInterval { + t.Errorf("Interval = %v, want the documented default %v", eng.Interval, scheduling.DefaultInterval) + } + if eng.MaxParallel != scheduling.DefaultMaxParallel { + t.Errorf("MaxParallel = %d, want the documented default %d", eng.MaxParallel, scheduling.DefaultMaxParallel) + } + if eng.JobTimeout != scheduling.DefaultJobTimeout { + t.Errorf("JobTimeout = %v, want the documented default %v", eng.JobTimeout, scheduling.DefaultJobTimeout) + } + if eng.Events != nil { + t.Errorf("Events = %v, want nil: the example section is commented out, so no sink is configured", eng.Events) + } +} diff --git a/internal/infrastructure/configuration/validate.go b/internal/infrastructure/configuration/validate.go index 5e833b4ea..991428077 100644 --- a/internal/infrastructure/configuration/validate.go +++ b/internal/infrastructure/configuration/validate.go @@ -35,6 +35,10 @@ var ( natsModes = []string{config.NATSModeEmbedded, config.NATSModeExternal} forgeIntakes = []string{config.ForgeIntakePoll, config.ForgeIntakeWebhook, config.ForgeIntakeBoth} memoryEngines = []string{memoryEngineBuiltin} + // eventsSinkModes are the explicit [scheduling].events_sink spellings. + // The empty string also means "no sink" but is resolved by + // applySchedulingDefaults before validation, so it is not listed here. + eventsSinkModes = []string{config.EventsSinkBus, config.EventsSinkNone} ) // Validate runs the same checks Loader applies before accepting a config, @@ -89,6 +93,9 @@ func validate(cfg *config.Config) error { if err := validateImage(cfg); err != nil { return err } + if err := validateScheduling(cfg); err != nil { + return err + } return validateCapture(cfg) } From a2cca6088e74377f91df285c4e2e278d2ff9e449 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 14 Sep 2026 10:51:47 +0000 Subject: [PATCH 3/4] feat(cronevents): adapt the events bus to scheduling.Sink A scheduled run has no task, no chat turn and no workflow behind it, so its emitted events are the only trace it leaves -- and the engine's Sink is the emitter shape of a bus it deliberately does not import. Something has to turn one into the other; this is that seam. - Sink(mode, bus) returns a sink over the bus for "bus", and nil for "none"/absent or a nil bus. Nil rather than a no-op sink keeps "emission is off" visible to whoever reads the composition, and it is the configuration the engine documents as valid: it still runs, it is just unobservable. - The published event carries the engine's own Kind/Detail/Data and no task-scoped identity. A cron run has none, and borrowing the emitting daemon's would attach it to an unrelated task's timeline. - An unrecognised mode is an error; the loader rejects it first, but a hand-built config must not silently disable observability. TDD: the sink tests were written first and failed on assertions (Sink("bus") returned nil; an unknown mode was accepted), not on compilation. The end-to-end test drives a real engine on an injected clock and subscribes to the bus, so the Emit -> Publish path is proven rather than assumed -- no sleeps, no wall-clock deadlines. --- .../infrastructure/cronevents/engine_test.go | 84 +++++++++++++++ internal/infrastructure/cronevents/sink.go | 68 ++++++++++++ .../infrastructure/cronevents/sink_test.go | 102 ++++++++++++++++++ 3 files changed, 254 insertions(+) create mode 100644 internal/infrastructure/cronevents/engine_test.go create mode 100644 internal/infrastructure/cronevents/sink.go create mode 100644 internal/infrastructure/cronevents/sink_test.go diff --git a/internal/infrastructure/cronevents/engine_test.go b/internal/infrastructure/cronevents/engine_test.go new file mode 100644 index 000000000..1035a475a --- /dev/null +++ b/internal/infrastructure/cronevents/engine_test.go @@ -0,0 +1,84 @@ +package cronevents + +import ( + "context" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/config" + "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, err := Sink(config.EventsSinkBus, bus) + if err != nil { + t.Fatalf("Sink(%q, bus) = %v, want nil", config.EventsSinkBus, err) + } + 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") + } +} diff --git a/internal/infrastructure/cronevents/sink.go b/internal/infrastructure/cronevents/sink.go new file mode 100644 index 000000000..1dbf14eaf --- /dev/null +++ b/internal/infrastructure/cronevents/sink.go @@ -0,0 +1,68 @@ +// Package cronevents is the observability half of archied's cron/scheduling +// capability: it adapts the daemon's in-process event bus to the ticker +// engine's narrow emission contract. +// +// The domain's engine (internal/domain/scheduling) declares what it needs -- +// Emit(kind, detail, data) -- and names no bus, which is what lets its timing +// behaviour be tested without one. This package is the other side of that +// seam: the bus exists (internal/events), and something has to turn one shape +// into the other. +// +// The adapter is deliberately thin, and deliberately tolerant of a missing +// bus: a scheduled run has no task, no chat turn and no workflow behind it, so +// these events are the only trace it leaves, and the engine documents a nil +// sink as a valid configuration (it still runs, it is just unobservable). +// Which leaves the operator's choice -- publish or not -- and the daemon's +// ability to answer it, as the only two inputs. +package cronevents + +import ( + "fmt" + + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/scheduling" + "github.com/samcharles93/archie-core/internal/events" +) + +// Sink builds the scheduling.Sink for the configured [scheduling].events_sink +// mode, over the daemon's event bus. +// +// config.EventsSinkBus (and a non-nil bus) yields a sink that publishes each +// emitted event on the bus. "" and config.EventsSinkNone, or a nil bus, +// yield a nil sink -- the engine tolerates that by design, and returning nil +// rather than a no-op sink keeps "emission is off" visible to whoever reads +// the composition. +// +// An unrecognised mode is an error: the loader rejects such a value first, but +// a hand-built config must not silently disable observability either. +func Sink(mode string, bus *events.Bus) (scheduling.Sink, error) { + switch mode { + case "", config.EventsSinkNone: + return nil, nil + case config.EventsSinkBus: + if bus == nil { + return nil, nil + } + return busSink{bus: bus}, nil + default: + return nil, fmt.Errorf("cronevents: unknown events_sink %q (want %q or %q)", + mode, config.EventsSinkBus, config.EventsSinkNone) + } +} + +// busSink publishes the engine's emission on the bus. The event carries the +// engine's own shape -- Kind, Detail and Data, exactly as emitted -- and no +// task-scoped identity, because a scheduled run has none: borrowing the +// emitting daemon's would attach a cron run's event to some unrelated task's +// timeline. Bus.Publish stamps the timestamp and fans out to bounded, +// dropping subscriber buffers, so a stalled dashboard connection cannot +// backpressure a scheduled run. +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{} diff --git a/internal/infrastructure/cronevents/sink_test.go b/internal/infrastructure/cronevents/sink_test.go new file mode 100644 index 000000000..ed4669bfa --- /dev/null +++ b/internal/infrastructure/cronevents/sink_test.go @@ -0,0 +1,102 @@ +package cronevents + +import ( + "testing" + + "github.com/samcharles93/archie-core/internal/config" + "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, err := Sink(config.EventsSinkBus, bus) + if err != nil { + t.Fatalf("Sink(%q, bus) = %v, want nil", config.EventsSinkBus, err) + } + if sink == nil { + t.Fatalf("Sink(%q, bus) = nil, want a sink over the bus", config.EventsSinkBus) + } + + // 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") + } +} + +// TestSinkIsNilWhenEmissionIsOff: an absent or explicitly disabled sink must +// come back nil, which is the engine's documented "still runs, just +// unobservable" configuration. +func TestSinkIsNilWhenEmissionIsOff(t *testing.T) { + bus := events.NewBus() + t.Cleanup(bus.Close) + + for _, mode := range []string{"", config.EventsSinkNone} { + sink, err := Sink(mode, bus) + if err != nil { + t.Errorf("Sink(%q, bus) = %v, want nil", mode, err) + continue + } + if sink != nil { + t.Errorf("Sink(%q, bus) = %#v, want a nil sink", mode, sink) + } + } +} + +// TestSinkIsNilWithoutABus: a deployment that turned emission on still has +// nothing to publish to when the daemon has no bus, so the sink degrades to +// the engine's nil-sink tolerance rather than panicking on first emit. +func TestSinkIsNilWithoutABus(t *testing.T) { + sink, err := Sink(config.EventsSinkBus, nil) + if err != nil { + t.Fatalf("Sink(%q, nil bus) = %v, want nil", config.EventsSinkBus, err) + } + if sink != nil { + t.Errorf("Sink(%q, nil bus) = %#v, want a nil sink", config.EventsSinkBus, sink) + } +} + +// TestSinkRejectsUnknownMode: unreachable through the loader, which rejects +// the value first -- but a hand-built config must not silently disable +// observability either. +func TestSinkRejectsUnknownMode(t *testing.T) { + if _, err := Sink("kafka", events.NewBus()); err == nil { + t.Fatal("Sink(\"kafka\") = nil error, want an unknown-mode failure") + } +} From 355e1c64b2b2d77459d58befbe5a90844cb48adb Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Mon, 14 Sep 2026 23:25:09 +1000 Subject: [PATCH 4/4] fix(scheduling): respect configuration ownership --- internal/app/archied/scheduling.go | 38 +++ internal/app/archied/scheduling_test.go | 86 ++++++ internal/config/config.go | 57 ---- internal/domain/scheduling/ticker.go | 47 ++-- internal/domain/scheduling/ticker_test.go | 12 +- .../infrastructure/configuration/defaults.go | 1 - .../infrastructure/configuration/loader.go | 26 +- .../configuration/scheduling.go | 130 ++++----- .../configuration/scheduling_test.go | 251 +++--------------- .../infrastructure/configuration/validate.go | 7 - .../infrastructure/cronevents/engine_test.go | 6 +- internal/infrastructure/cronevents/sink.go | 55 +--- .../infrastructure/cronevents/sink_test.go | 48 +--- 13 files changed, 273 insertions(+), 491 deletions(-) create mode 100644 internal/app/archied/scheduling.go create mode 100644 internal/app/archied/scheduling_test.go diff --git a/internal/app/archied/scheduling.go b/internal/app/archied/scheduling.go new file mode 100644 index 000000000..52a0a04fa --- /dev/null +++ b/internal/app/archied/scheduling.go @@ -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 +} diff --git a/internal/app/archied/scheduling_test.go b/internal/app/archied/scheduling_test.go new file mode 100644 index 000000000..6c9d0c496 --- /dev/null +++ b/internal/app/archied/scheduling_test.go @@ -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") + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 7f0618363..3a3a99f8c 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -516,12 +516,6 @@ type Config struct { Capture CaptureConfig `toml:"capture" yaml:"capture"` Bindings BindingsConfig `toml:"bindings" yaml:"bindings"` - // Scheduling configures the cron/scheduling ticker engine - // (internal/domain/scheduling). Absent is valid: every field - // defaults independently, so an empty section and no section at - // all produce the same resolved engine configuration. - Scheduling SchedulingConfig `toml:"scheduling" yaml:"scheduling"` - // Memory holds memory provider configuration (from config.memory.yaml). Memory MemoryConfig `toml:"memory" yaml:"memory"` @@ -783,57 +777,6 @@ type CaptureConfig struct { RateBurst int `toml:"rate_burst" yaml:"rate_burst"` } -// SchedulingConfig configures the cron/scheduling ticker engine -// (internal/domain/scheduling, epic -// archie-core-1786637496320-249-be6d9a20). Every field is optional and -// defaults independently, so an absent [scheduling] section is valid and -// resolves to the engine's own documented defaults. -// -// Zero and negative are therefore NOT the same thing here, the same -// distinction config.ToolPolicy and config.CaptureConfig make: zero is -// "unset, give me the default", which leaves negative as the only way an -// operator can name an unusable value deliberately. A negative value is a -// startup error -- a negative interval cannot be a tick cadence, and the -// values are rejected rather than clamped because silently running -// something other than what was written is how a misconfiguration stays -// invisible. -type SchedulingConfig struct { - // Interval is the tick cadence: how often the engine asks its job - // source what is due. Zero or absent means the engine's own - // scheduling.DefaultInterval (one minute); a configured value is - // used as-is. Negative is a startup error. - Interval Duration `toml:"interval" yaml:"interval"` - // MaxParallel caps simultaneous parallel-pool runs. Zero or absent - // means scheduling.DefaultMaxParallel. It does not bound the - // sequential pool, which is one by definition. Negative is a - // startup error. - MaxParallel int `toml:"max_parallel" yaml:"max_parallel"` - // JobTimeout bounds one run via context deadline. Zero or absent - // means scheduling.DefaultJobTimeout. Negative is a startup error. - JobTimeout Duration `toml:"job_timeout" yaml:"job_timeout"` - // EventsSink selects whether the engine's run and error events are - // published on the daemon's event stream. "bus" publishes them; - // absent resolves to "none", which leaves the engine's Events nil -- - // a configuration the engine documents as valid: it still runs, it - // is just unobservable. Any other value is a startup error, so a - // typo cannot silently disable observability. - EventsSink string `toml:"events_sink" yaml:"events_sink"` -} - -// EventsSink mode values for SchedulingConfig.EventsSink. The zero value -// (empty) resolves to EventsSinkNone; these are the explicit spellings, -// shared with validation so the two cannot drift. -const ( - // EventsSinkBus publishes the engine's run and error events on the - // daemon's in-process event bus, which is what the dashboard's - // timeline reads. - EventsSinkBus = "bus" - // EventsSinkNone disables emission. It is the documented way to say - // that without relying on an absent key, and it leaves the engine's - // Events nil -- valid, and unobservable. - EventsSinkNone = "none" -) - // BindingsConfig configures the playbook-binding store (t2db). When // EncryptionKey is unset, binding secrets are persisted as plaintext // (legacy behaviour); when set, they are AES-256-GCM encrypted at rest diff --git a/internal/domain/scheduling/ticker.go b/internal/domain/scheduling/ticker.go index 587f028bf..690c405eb 100644 --- a/internal/domain/scheduling/ticker.go +++ b/internal/domain/scheduling/ticker.go @@ -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() diff --git a/internal/domain/scheduling/ticker_test.go b/internal/domain/scheduling/ticker_test.go index f3c06f398..0c6d104c8 100644 --- a/internal/domain/scheduling/ticker_test.go +++ b/internal/domain/scheduling/ticker_test.go @@ -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) } } diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index 6854ef38c..396eb038c 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -75,7 +75,6 @@ func (l *Loader) applyDefaults(cfg *config.Config) { applyContainerDefaults(cfg) applyToolPolicyDefaults(cfg) applyCaptureDefaults(cfg) - applySchedulingDefaults(cfg) applyNATSDefaults(cfg) applyMemoryDefaults(cfg) } diff --git a/internal/infrastructure/configuration/loader.go b/internal/infrastructure/configuration/loader.go index bac412c51..fbe6b1bfe 100644 --- a/internal/infrastructure/configuration/loader.go +++ b/internal/infrastructure/configuration/loader.go @@ -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 diff --git a/internal/infrastructure/configuration/scheduling.go b/internal/infrastructure/configuration/scheduling.go index 14ee4ee8e..64a4347c8 100644 --- a/internal/infrastructure/configuration/scheduling.go +++ b/internal/infrastructure/configuration/scheduling.go @@ -2,95 +2,65 @@ package configuration import ( "fmt" + "time" - "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/domain/scheduling" + "gopkg.in/yaml.v3" ) -// DefaultScheduling returns the defaults an absent [scheduling] section -// resolves to, taken from the engine's own documented constants rather than -// restated here -- one answer for "unset", owned by the domain that acts on -// it. [applySchedulingDefaults] fills a decoded config with them. -func DefaultScheduling() config.SchedulingConfig { - return config.SchedulingConfig{ - Interval: config.Duration(scheduling.DefaultInterval), - MaxParallel: scheduling.DefaultMaxParallel, - JobTimeout: config.Duration(scheduling.DefaultJobTimeout), - EventsSink: config.EventsSinkNone, - } +// 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"` } -// applySchedulingDefaults resolves an absent [scheduling] section. Every field -// defaults independently, so a section naming only max_parallel still gets a -// cadence and a run timeout, and "nothing configured" is one resolved state -// rather than two that happen to mean the same thing. -// -// A negative value is left alone for [validateScheduling] to reject. -func applySchedulingDefaults(cfg *config.Config) { - d := DefaultScheduling() - if cfg.Scheduling.Interval == 0 { - cfg.Scheduling.Interval = d.Interval - } - if cfg.Scheduling.MaxParallel == 0 { - cfg.Scheduling.MaxParallel = d.MaxParallel - } - if cfg.Scheduling.JobTimeout == 0 { - cfg.Scheduling.JobTimeout = d.JobTimeout - } - if cfg.Scheduling.EventsSink == "" { - cfg.Scheduling.EventsSink = d.EventsSink - } -} +// Duration is a textual duration at the configuration boundary. +type Duration time.Duration -// validateScheduling rejects unusable engine tunables. applySchedulingDefaults -// fills every zero value, so this only fires on an explicitly negative one -- -// the engine's own contract documents "negative is an error" for a reason: -// a negative interval cannot be a tick cadence, and clamping it would run -// something other than what the operator wrote, which is how a -// misconfiguration stays invisible. It also rejects an unknown events_sink -// spelling, so a typo cannot silently leave a deployment unobservable. -func validateScheduling(cfg *config.Config) error { - switch { - case cfg.Scheduling.Interval < 0: - return fmt.Errorf("%w: scheduling.interval must not be negative, got %s", ErrInvalidInput, cfg.Scheduling.Interval.Std()) - case cfg.Scheduling.MaxParallel < 0: - return fmt.Errorf("%w: scheduling.max_parallel must not be negative, got %d", ErrInvalidInput, cfg.Scheduling.MaxParallel) - case cfg.Scheduling.JobTimeout < 0: - return fmt.Errorf("%w: scheduling.job_timeout must not be negative, got %s", ErrInvalidInput, cfg.Scheduling.JobTimeout.Std()) - } - // Empty is valid input here (applySchedulingDefaults resolves it to - // "none" before this runs on the real load path); it is not "unknown". - if sink := cfg.Scheduling.EventsSink; sink != "" && !oneOf(sink, eventsSinkModes) { - return fmt.Errorf("%w: scheduling.events_sink %q (want %s)", ErrInvalidInput, sink, list(eventsSinkModes)) +func (d *Duration) UnmarshalText(text []byte) error { + value, err := time.ParseDuration(string(text)) + if err != nil { + return err } + *d = Duration(value) return nil } -// TranslateScheduling turns the operator's [scheduling] input into the -// engine's own configuration type, fully resolved: an unset tunable becomes -// the engine's documented default, so the engine receives what the daemon -// means rather than zero values it has to second-guess. -// -// Clock and Events are deliberately left nil. This package owns no clock (the -// engine's system clock is the deployment's answer, not an operator's) and no -// bus: attaching the sink is composition, and a nil Events is a configuration -// the engine documents as valid -- it still runs, it is just unobservable. -// -// A negative tunable, or an unknown events_sink, is reported rather than -// repaired, so a bad file stops startup instead of running something the -// operator did not ask for. -func TranslateScheduling(cfg config.SchedulingConfig) (scheduling.EngineConfig, error) { - holder := config.Config{Scheduling: cfg} - if err := validateScheduling(&holder); err != nil { - return scheduling.EngineConfig{}, err - } - // Resolve through the same applier the load path uses, so a hand-built - // config and a decoded file cannot resolve differently. - applySchedulingDefaults(&holder) +func (d Duration) Std() time.Duration { return time.Duration(d) } - return scheduling.EngineConfig{ - Interval: holder.Scheduling.Interval.Std(), - MaxParallel: holder.Scheduling.MaxParallel, - JobTimeout: holder.Scheduling.JobTimeout.Std(), - }, nil +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 } diff --git a/internal/infrastructure/configuration/scheduling_test.go b/internal/infrastructure/configuration/scheduling_test.go index 1f1b2feda..59c4a382c 100644 --- a/internal/infrastructure/configuration/scheduling_test.go +++ b/internal/infrastructure/configuration/scheduling_test.go @@ -1,18 +1,12 @@ package configuration import ( - "errors" "os" "path/filepath" "testing" "time" - - "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/domain/scheduling" ) -// writeSchedulingConfig writes a config file whose only content beyond the -// fields every check requires is the given [scheduling] fragment. func writeSchedulingConfig(t *testing.T, section string) string { t.Helper() path := filepath.Join(t.TempDir(), "config.toml") @@ -22,241 +16,62 @@ func writeSchedulingConfig(t *testing.T, section string) string { return path } -// TestTranslateSchedulingResolvesZeroValuesToEngineDefaults pins the -// translator to the engine's own documented constants: the domain has one -// answer for "unset", and a second copy of those numbers here would be free -// to drift from it. -func TestTranslateSchedulingResolvesZeroValuesToEngineDefaults(t *testing.T) { - eng, err := TranslateScheduling(config.SchedulingConfig{}) - if err != nil { - t.Fatalf("TranslateScheduling(zero value) = %v, want nil", err) - } - if got := eng.Interval; got != scheduling.DefaultInterval { - t.Errorf("Interval = %v, want %v", got, scheduling.DefaultInterval) - } - if got := eng.MaxParallel; got != scheduling.DefaultMaxParallel { - t.Errorf("MaxParallel = %d, want %d", got, scheduling.DefaultMaxParallel) - } - if got := eng.JobTimeout; got != scheduling.DefaultJobTimeout { - t.Errorf("JobTimeout = %v, want %v", got, scheduling.DefaultJobTimeout) - } - // Events stays nil: this package owns no bus, and the engine documents a - // nil sink as a valid configuration -- it still runs, it is just - // unobservable. Attaching one is the composition slice's job. - if eng.Events != nil { - t.Errorf("Events = %v, want nil for an absent events_sink", eng.Events) - } -} - -func TestTranslateSchedulingKeepsConfiguredValues(t *testing.T) { - eng, err := TranslateScheduling(config.SchedulingConfig{ - Interval: config.Duration(30 * time.Second), - MaxParallel: 2, - JobTimeout: config.Duration(5 * time.Minute), - }) - if err != nil { - t.Fatalf("TranslateScheduling(configured) = %v, want nil", err) - } - if got := eng.Interval; got != 30*time.Second { - t.Errorf("Interval = %v, want unchanged 30s", got) - } - if got := eng.MaxParallel; got != 2 { - t.Errorf("MaxParallel = %d, want unchanged 2", got) - } - if got := eng.JobTimeout; got != 5*time.Minute { - t.Errorf("JobTimeout = %v, want unchanged 5m", got) - } -} - -// TestTranslateSchedulingRejectsNegativeValues: the engine's own contract -// documents "negative is an error". A clamp would run something other than -// what the operator wrote, which is how a misconfiguration stays invisible, -// so the translator reports it and lets startup fail. -func TestTranslateSchedulingRejectsNegativeValues(t *testing.T) { - tests := []struct { - name string - cfg config.SchedulingConfig - }{ - {name: "interval", cfg: config.SchedulingConfig{Interval: config.Duration(-time.Second)}}, - {name: "max_parallel", cfg: config.SchedulingConfig{MaxParallel: -1}}, - {name: "job_timeout", cfg: config.SchedulingConfig{JobTimeout: config.Duration(-time.Minute)}}, - } - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - _, err := TranslateScheduling(tc.cfg) - if err == nil { - t.Fatalf("TranslateScheduling(negative %s) = nil error, want a startup error", tc.name) - } - if !errors.Is(err, ErrInvalidInput) { - t.Errorf("TranslateScheduling(negative %s) = %v, want it to wrap ErrInvalidInput", tc.name, err) - } - }) - } -} - -// TestLoadSchedulingBlockDecodesAllFourFields pins the four toml keys: the -// translator is only reachable from operator input through them. -func TestLoadSchedulingBlockDecodesAllFourFields(t *testing.T) { - path := writeSchedulingConfig(t, ` +func TestLoaderDecodesSchedulingInputSeparatelyFromRuntimeConfig(t *testing.T) { + doc, err := New(nil).File(writeSchedulingConfig(t, ` [scheduling] interval = "30s" max_parallel = 2 job_timeout = "5m" events_sink = "bus" -`) - cfg, err := loadFile(path) +`)) if err != nil { - t.Fatalf("loadFile() = %v, want nil", err) + t.Fatal(err) } - if got := cfg.Scheduling.Interval.Std(); got != 30*time.Second { - t.Errorf("Scheduling.Interval = %v, want 30s", got) + if got := doc.Scheduling.Interval.Std(); got != 30*time.Second { + t.Errorf("Interval = %v, want 30s", got) } - if got := cfg.Scheduling.MaxParallel; got != 2 { - t.Errorf("Scheduling.MaxParallel = %d, want 2", got) + if got := doc.Scheduling.MaxParallel; got != 2 { + t.Errorf("MaxParallel = %d, want 2", got) } - if got := cfg.Scheduling.JobTimeout.Std(); got != 5*time.Minute { - t.Errorf("Scheduling.JobTimeout = %v, want 5m", got) + if got := doc.Scheduling.JobTimeout.Std(); got != 5*time.Minute { + t.Errorf("JobTimeout = %v, want 5m", got) } - if got := cfg.Scheduling.EventsSink; got != config.EventsSinkBus { - t.Errorf("Scheduling.EventsSink = %q, want %q", got, config.EventsSinkBus) - } - - eng, err := TranslateScheduling(cfg.Scheduling) - if err != nil { - t.Fatalf("TranslateScheduling(loaded) = %v, want nil", err) - } - if eng.Interval != 30*time.Second || eng.MaxParallel != 2 || eng.JobTimeout != 5*time.Minute { - t.Errorf("loaded engine config = %+v, want {30s 2 5m}", eng) + if got := doc.Scheduling.EventsSink; got != EventsSinkBus { + t.Errorf("EventsSink = %q, want %q", got, EventsSinkBus) } } -// TestLoadAbsentSchedulingSectionResolvesEngineDefaults covers the operator -// who never writes the section at all -- the common case. Both the loaded -// section and the translated engine config must be fully resolved, so -// "nothing configured" and "configured with the defaults" are one state. -func TestLoadAbsentSchedulingSectionResolvesEngineDefaults(t *testing.T) { - cfg, err := loadFile(writeSchedulingConfig(t, "")) +func TestLoaderLeavesAbsentSchedulingInputUnset(t *testing.T) { + doc, err := New(nil).File(writeSchedulingConfig(t, "")) if err != nil { - t.Fatalf("loadFile() = %v, want nil", err) + t.Fatal(err) } - if got := cfg.Scheduling.Interval.Std(); got != scheduling.DefaultInterval { - t.Errorf("Scheduling.Interval = %v, want %v", got, scheduling.DefaultInterval) - } - if got := cfg.Scheduling.MaxParallel; got != scheduling.DefaultMaxParallel { - t.Errorf("Scheduling.MaxParallel = %d, want %d", got, scheduling.DefaultMaxParallel) - } - if got := cfg.Scheduling.JobTimeout.Std(); got != scheduling.DefaultJobTimeout { - t.Errorf("Scheduling.JobTimeout = %v, want %v", got, scheduling.DefaultJobTimeout) + if doc.Scheduling != (SchedulingInput{}) { + t.Errorf("Scheduling = %+v, want zero external input", doc.Scheduling) } +} - eng, err := TranslateScheduling(cfg.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.Fatalf("TranslateScheduling(loaded) = %v, want nil", err) + t.Fatal(err) } - if eng.Interval != scheduling.DefaultInterval { - t.Errorf("Interval = %v, want %v", eng.Interval, scheduling.DefaultInterval) - } - if eng.MaxParallel != scheduling.DefaultMaxParallel { - t.Errorf("MaxParallel = %d, want %d", eng.MaxParallel, scheduling.DefaultMaxParallel) - } - if eng.JobTimeout != scheduling.DefaultJobTimeout { - t.Errorf("JobTimeout = %v, want %v", eng.JobTimeout, scheduling.DefaultJobTimeout) + 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) } } -// TestLoadRejectsNegativeSchedulingValues puts the negative-value rule on the -// load path, not just in the translator: a file edit that breaks a running -// deployment (a SIGHUP reload) must be refused with the operator's mistake -// named, rather than applied as a negative cadence. -func TestLoadRejectsNegativeSchedulingValues(t *testing.T) { - tests := []struct { - name string - section string - }{ - {name: "interval", section: "[scheduling]\ninterval = \"-1m\"\n"}, - {name: "max_parallel", section: "[scheduling]\nmax_parallel = -1\n"}, - {name: "job_timeout", section: "[scheduling]\njob_timeout = \"-1h\"\n"}, - } - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - _, err := loadFile(writeSchedulingConfig(t, tc.section)) - if err == nil { - t.Fatalf("loadFile(negative %s) = nil, want a load failure", tc.name) - } - if !errors.Is(err, ErrInvalidInput) { - t.Errorf("loadFile(negative %s) = %v, want it to wrap ErrInvalidInput", tc.name, err) - } - }) - } -} - -// TestLoadAcceptsEveryDocumentedEventsSinkSpelling pins the on/off -// vocabulary: "bus" publishes on the event stream, and "none" means no sink. -// An absent key resolves to "none" rather than staying empty, the same shape -// applyMemoryDefaults and applyNATSDefaults use -- a resolved config has one -// spelling for "not publishing", not two that happen to mean it. "off" is -// deliberately not a third spelling: a near-miss must be rejected, not -// guessed at. -func TestLoadAcceptsEveryDocumentedEventsSinkSpelling(t *testing.T) { - tests := []struct { - name string - section string - want string - }{ - {name: "absent", section: "", want: config.EventsSinkNone}, - {name: "none", section: "[scheduling]\nevents_sink = \"none\"\n", want: config.EventsSinkNone}, - {name: "bus", section: "[scheduling]\nevents_sink = \"bus\"\n", want: config.EventsSinkBus}, - } - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - cfg, err := loadFile(writeSchedulingConfig(t, tc.section)) - if err != nil { - t.Fatalf("loadFile(events_sink %s) = %v, want nil", tc.name, err) - } - if got := cfg.Scheduling.EventsSink; got != tc.want { - t.Errorf("Scheduling.EventsSink = %q, want %q", got, tc.want) - } - }) - } -} - -// TestLoadRejectsUnknownEventsSink: a typo must not silently leave the -// engine unobservable, which is exactly what an unrecognised value would do -// if it defaulted to off. -func TestLoadRejectsUnknownEventsSink(t *testing.T) { - _, err := loadFile(writeSchedulingConfig(t, "[scheduling]\nevents_sink = \"kafka\"\n")) - if err == nil { - t.Fatal("loadFile(unknown events_sink) = nil, want a load failure") - } - if !errors.Is(err, ErrInvalidInput) { - t.Errorf("loadFile(unknown events_sink) = %v, want it to wrap ErrInvalidInput", err) - } -} - -// TestExampleConfigSchedulingSectionIsDocumentationOnly checks the shipped -// template the way an operator's first run will: whatever the [scheduling] -// block documents, the file must load and resolve to the documented state, -// and the block must stay dormant (no live section) the same way [[repos]] -// does -- a live example is a default an operator never chose. -func TestExampleConfigSchedulingSectionIsDocumentationOnly(t *testing.T) { - cfg, err := loadFile(filepath.Join("..", "..", "..", "config.example.toml")) +func TestExampleConfigLeavesSchedulingAtDefaults(t *testing.T) { + doc, err := New(nil).File(filepath.Join("..", "..", "..", "config.example.toml")) if err != nil { - t.Fatalf("loadFile(config.example.toml) = %v, want nil", err) + t.Fatal(err) } - eng, err := TranslateScheduling(cfg.Scheduling) - if err != nil { - t.Fatalf("TranslateScheduling(example) = %v, want nil", err) - } - if eng.Interval != scheduling.DefaultInterval { - t.Errorf("Interval = %v, want the documented default %v", eng.Interval, scheduling.DefaultInterval) - } - if eng.MaxParallel != scheduling.DefaultMaxParallel { - t.Errorf("MaxParallel = %d, want the documented default %d", eng.MaxParallel, scheduling.DefaultMaxParallel) - } - if eng.JobTimeout != scheduling.DefaultJobTimeout { - t.Errorf("JobTimeout = %v, want the documented default %v", eng.JobTimeout, scheduling.DefaultJobTimeout) - } - if eng.Events != nil { - t.Errorf("Events = %v, want nil: the example section is commented out, so no sink is configured", eng.Events) + if doc.Scheduling != (SchedulingInput{}) { + t.Errorf("Scheduling = %+v, want commented example to remain unset", doc.Scheduling) } } diff --git a/internal/infrastructure/configuration/validate.go b/internal/infrastructure/configuration/validate.go index 991428077..5e833b4ea 100644 --- a/internal/infrastructure/configuration/validate.go +++ b/internal/infrastructure/configuration/validate.go @@ -35,10 +35,6 @@ var ( natsModes = []string{config.NATSModeEmbedded, config.NATSModeExternal} forgeIntakes = []string{config.ForgeIntakePoll, config.ForgeIntakeWebhook, config.ForgeIntakeBoth} memoryEngines = []string{memoryEngineBuiltin} - // eventsSinkModes are the explicit [scheduling].events_sink spellings. - // The empty string also means "no sink" but is resolved by - // applySchedulingDefaults before validation, so it is not listed here. - eventsSinkModes = []string{config.EventsSinkBus, config.EventsSinkNone} ) // Validate runs the same checks Loader applies before accepting a config, @@ -93,9 +89,6 @@ func validate(cfg *config.Config) error { if err := validateImage(cfg); err != nil { return err } - if err := validateScheduling(cfg); err != nil { - return err - } return validateCapture(cfg) } diff --git a/internal/infrastructure/cronevents/engine_test.go b/internal/infrastructure/cronevents/engine_test.go index 1035a475a..ef9fc4cc0 100644 --- a/internal/infrastructure/cronevents/engine_test.go +++ b/internal/infrastructure/cronevents/engine_test.go @@ -5,7 +5,6 @@ import ( "testing" "time" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/scheduling" "github.com/samcharles93/archie-core/internal/events" ) @@ -39,10 +38,7 @@ func TestEngineSinkPublishesRealRunOnTheBus(t *testing.T) { t.Cleanup(bus.Close) sub := bus.Subscribe(4) - sink, err := Sink(config.EventsSinkBus, bus) - if err != nil { - t.Fatalf("Sink(%q, bus) = %v, want nil", config.EventsSinkBus, err) - } + 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"}}, diff --git a/internal/infrastructure/cronevents/sink.go b/internal/infrastructure/cronevents/sink.go index 1dbf14eaf..7fc4a05c5 100644 --- a/internal/infrastructure/cronevents/sink.go +++ b/internal/infrastructure/cronevents/sink.go @@ -1,62 +1,19 @@ -// Package cronevents is the observability half of archied's cron/scheduling -// capability: it adapts the daemon's in-process event bus to the ticker -// engine's narrow emission contract. -// -// The domain's engine (internal/domain/scheduling) declares what it needs -- -// Emit(kind, detail, data) -- and names no bus, which is what lets its timing -// behaviour be tested without one. This package is the other side of that -// seam: the bus exists (internal/events), and something has to turn one shape -// into the other. -// -// The adapter is deliberately thin, and deliberately tolerant of a missing -// bus: a scheduled run has no task, no chat turn and no workflow behind it, so -// these events are the only trace it leaves, and the engine documents a nil -// sink as a valid configuration (it still runs, it is just unobservable). -// Which leaves the operator's choice -- publish or not -- and the daemon's -// ability to answer it, as the only two inputs. +// Package cronevents adapts the daemon's event bus to scheduling.Sink. package cronevents import ( - "fmt" - - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/scheduling" "github.com/samcharles93/archie-core/internal/events" ) -// Sink builds the scheduling.Sink for the configured [scheduling].events_sink -// mode, over the daemon's event bus. -// -// config.EventsSinkBus (and a non-nil bus) yields a sink that publishes each -// emitted event on the bus. "" and config.EventsSinkNone, or a nil bus, -// yield a nil sink -- the engine tolerates that by design, and returning nil -// rather than a no-op sink keeps "emission is off" visible to whoever reads -// the composition. -// -// An unrecognised mode is an error: the loader rejects such a value first, but -// a hand-built config must not silently disable observability either. -func Sink(mode string, bus *events.Bus) (scheduling.Sink, error) { - switch mode { - case "", config.EventsSinkNone: - return nil, nil - case config.EventsSinkBus: - if bus == nil { - return nil, nil - } - return busSink{bus: bus}, nil - default: - return nil, fmt.Errorf("cronevents: unknown events_sink %q (want %q or %q)", - mode, config.EventsSinkBus, config.EventsSinkNone) +// 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} } -// busSink publishes the engine's emission on the bus. The event carries the -// engine's own shape -- Kind, Detail and Data, exactly as emitted -- and no -// task-scoped identity, because a scheduled run has none: borrowing the -// emitting daemon's would attach a cron run's event to some unrelated task's -// timeline. Bus.Publish stamps the timestamp and fans out to bounded, -// dropping subscriber buffers, so a stalled dashboard connection cannot -// backpressure a scheduled run. type busSink struct { bus *events.Bus } diff --git a/internal/infrastructure/cronevents/sink_test.go b/internal/infrastructure/cronevents/sink_test.go index ed4669bfa..ae03f7f78 100644 --- a/internal/infrastructure/cronevents/sink_test.go +++ b/internal/infrastructure/cronevents/sink_test.go @@ -3,7 +3,6 @@ package cronevents import ( "testing" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/scheduling" "github.com/samcharles93/archie-core/internal/events" ) @@ -18,12 +17,9 @@ func TestSinkPublishesEmitAsJobEvent(t *testing.T) { t.Cleanup(bus.Close) sub := bus.Subscribe(4) - sink, err := Sink(config.EventsSinkBus, bus) - if err != nil { - t.Fatalf("Sink(%q, bus) = %v, want nil", config.EventsSinkBus, err) - } + sink := New(bus) if sink == nil { - t.Fatalf("Sink(%q, bus) = nil, want a sink over the bus", config.EventsSinkBus) + t.Fatal("New(bus) = nil, want a sink over the bus") } // The shape the engine builds for a completed run @@ -60,43 +56,11 @@ func TestSinkPublishesEmitAsJobEvent(t *testing.T) { } } -// TestSinkIsNilWhenEmissionIsOff: an absent or explicitly disabled sink must -// come back nil, which is the engine's documented "still runs, just -// unobservable" configuration. -func TestSinkIsNilWhenEmissionIsOff(t *testing.T) { - bus := events.NewBus() - t.Cleanup(bus.Close) - - for _, mode := range []string{"", config.EventsSinkNone} { - sink, err := Sink(mode, bus) - if err != nil { - t.Errorf("Sink(%q, bus) = %v, want nil", mode, err) - continue - } - if sink != nil { - t.Errorf("Sink(%q, bus) = %#v, want a nil sink", mode, sink) - } - } -} - -// TestSinkIsNilWithoutABus: a deployment that turned emission on still has -// nothing to publish to when the daemon has no bus, so the sink degrades to -// the engine's nil-sink tolerance rather than panicking on first emit. +// A missing bus cannot produce an adapter; composition decides whether that +// is acceptable for the selected event mode. func TestSinkIsNilWithoutABus(t *testing.T) { - sink, err := Sink(config.EventsSinkBus, nil) - if err != nil { - t.Fatalf("Sink(%q, nil bus) = %v, want nil", config.EventsSinkBus, err) - } + sink := New(nil) if sink != nil { - t.Errorf("Sink(%q, nil bus) = %#v, want a nil sink", config.EventsSinkBus, sink) - } -} - -// TestSinkRejectsUnknownMode: unreachable through the loader, which rejects -// the value first -- but a hand-built config must not silently disable -// observability either. -func TestSinkRejectsUnknownMode(t *testing.T) { - if _, err := Sink("kafka", events.NewBus()); err == nil { - t.Fatal("Sink(\"kafka\") = nil error, want an unknown-mode failure") + t.Errorf("New(nil) = %#v, want a nil sink", sink) } }