From f29169c2cf1df313e36f87df7ee0e696fa98fca1 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 04:22:46 +1000 Subject: [PATCH] fix(cronstore): write a schedule interval as a duration, not nanoseconds The schedules document stored interval as a bare time.Duration, so its JSON was the nanosecond count -- 1800000000000 for thirty minutes -- and the Web UI, which now derives field metadata from the document type, correctly rendered a number input. Same defect 02rm fixed for rate_limit.window, in the second stored time this tree has. Nobody should be asked for a count of nanoseconds to configure a schedule. cronstore.Duration writes the string time.ParseDuration reads and reads that, a nanosecond count, and nothing else: every schedule stored before this shape existed carries a count, in both the control plane's schedules resource and this package's own jobs table, which persists the spec as JSON. A value that parses as neither is refused rather than decoding as zero, because a zero interval is a job that never fires. The derived schema needed no change and gets it for free -- which exposed a fix the derivation itself needed: it classified durations by NAME, so cronstore.Duration derived as an integer. durationLike now asks the type instead -- does it expose the standard duration, and does it marshal as a quoted string -- so the next duration type is classified correctly rather than silently rendering as a number box. That failure mode was invisible until a live daemon showed it. normalizeSchedules already re-marshals, so a stored document converges on its next write while reads keep tolerating the count. Verified: cronstore, crondelivery, controlplane, scheduling, webui and archied suites, go vet ./..., go build ./..., golangci-lint run ./... (0 issues), docs:check. Against a live daemon (8484): the catalog serves schedule.interval as {type: string, format: duration}. --- .../archied/migrate_legacy_schedules_test.go | 2 +- internal/app/controlplane/channel_settings.go | 4 + internal/app/controlplane/schedules_test.go | 2 +- internal/app/controlplane/schema.go | 43 ++++++--- internal/app/controlplane/schema_test.go | 42 +++++++++ .../crondelivery/helpers_test.go | 4 +- .../crondelivery/router_test.go | 6 +- internal/infrastructure/cronstore/schedule.go | 54 ++++++++++- .../cronstore/schedule_duration_test.go | 91 +++++++++++++++++++ .../cronstore/store_review_test.go | 2 +- .../infrastructure/cronstore/store_test.go | 12 +-- 11 files changed, 229 insertions(+), 33 deletions(-) create mode 100644 internal/infrastructure/cronstore/schedule_duration_test.go diff --git a/internal/app/archied/migrate_legacy_schedules_test.go b/internal/app/archied/migrate_legacy_schedules_test.go index aa3eb9f0d..dcf35ddeb 100644 --- a/internal/app/archied/migrate_legacy_schedules_test.go +++ b/internal/app/archied/migrate_legacy_schedules_test.go @@ -83,7 +83,7 @@ func legacyJob(id, kind string, interval time.Duration) cronstore.JobSpec { stamped := time.Date(2026, 9, 1, 9, 0, 0, 0, time.UTC) return cronstore.JobSpec{ ID: id, Kind: kind, Detail: "legacy " + id, - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: interval}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(interval)}, NextRun: stamped, Created: stamped, Updated: stamped, } } diff --git a/internal/app/controlplane/channel_settings.go b/internal/app/controlplane/channel_settings.go index 7f76aa6d5..dc92eb731 100644 --- a/internal/app/controlplane/channel_settings.go +++ b/internal/app/controlplane/channel_settings.go @@ -125,6 +125,10 @@ func decodeRenamingLegacyKeys(data []byte, legacy map[string]string, v any) erro // those documents keep working without being re-saved. type channelDuration time.Duration +// Std is the standard-library duration, for arithmetic and for the marker +// schema.go uses to recognise a string-form duration (see durationLike). +func (d channelDuration) Std() time.Duration { return time.Duration(d) } + func (d channelDuration) MarshalJSON() ([]byte, error) { return json.Marshal(time.Duration(d).String()) } diff --git a/internal/app/controlplane/schedules_test.go b/internal/app/controlplane/schedules_test.go index bae0b5497..3a7d20f42 100644 --- a/internal/app/controlplane/schedules_test.go +++ b/internal/app/controlplane/schedules_test.go @@ -12,7 +12,7 @@ func TestScheduleDefinitionComputesFirstRunAndRejectsDuplicateIDs(t *testing.T) t.Parallel() definition := scheduleDefinition() - jobs := []cronstore.JobSpec{{ID: "daily", Kind: cronstore.KindWorkflow, Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: time.Hour}}} + jobs := []cronstore.JobSpec{{ID: "daily", Kind: cronstore.KindWorkflow, Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}}} input, err := json.Marshal(jobs) if err != nil { t.Fatal(err) diff --git a/internal/app/controlplane/schema.go b/internal/app/controlplane/schema.go index d28e57815..da181275f 100644 --- a/internal/app/controlplane/schema.go +++ b/internal/app/controlplane/schema.go @@ -6,8 +6,6 @@ import ( "reflect" "strings" "time" - - "github.com/samcharles93/archie-core/internal/config" ) // bareObjectSchema is what a descriptor advertises when its definition names no @@ -16,11 +14,28 @@ import ( // (archie-core-2xs6). const bareObjectSchema = `{"type":"object"}` -var ( - configDurationType = reflect.TypeFor[config.Duration]() - channelDurationType = reflect.TypeFor[channelDuration]() - timeType = reflect.TypeFor[time.Time]() -) +var timeType = reflect.TypeFor[time.Time]() + +// stdDuration is the marker this tree's string-form duration types satisfy: +// config.Duration, channelDuration and cronstore.Duration each expose the +// standard duration for arithmetic. +var stdDuration = reflect.TypeOf((*interface{ Std() time.Duration })(nil)).Elem() + +// durationLike reports whether t is a duration type that writes itself as the +// string time.ParseDuration reads, rather than as its nanosecond count. +// +// It asks the type rather than listing the ones that exist, because a list goes +// stale the moment a fourth duration type appears and the failure is silent in +// the worst direction: the field derives as an integer and a client renders a +// number box for a duration. That is exactly what the enumerated version of this +// function did to cronstore.Duration when the schedules interval became one. +func durationLike(t reflect.Type) bool { + if !t.Implements(stdDuration) { + return false + } + encoded, err := json.Marshal(reflect.Zero(t).Interface()) + return err == nil && len(encoded) > 0 && encoded[0] == '"' +} // schemaJSON renders the JSON Schema a resource descriptor advertises, derived // from the document type the definition owns rather than written out beside it. @@ -60,14 +75,14 @@ func schemaOf(t reflect.Type) map[string]any { for t.Kind() == reflect.Pointer { t = t.Elem() } - switch t { - case configDurationType, channelDurationType: - // Both marshal as the string time.ParseDuration reads, so the schema - // says so and a client can offer a duration affordance instead of a - // number box. This is the rule that reaches every duration field in the - // catalogue, not just the one that prompted it. + switch { + case durationLike(t): + // The type writes the string time.ParseDuration reads, so the schema says + // so and a client can offer a duration affordance instead of a number + // box. This rule reaches every duration field in the catalogue, not just + // the one that prompted it. return map[string]any{"type": "string", "format": "duration"} - case timeType: + case t == timeType: return map[string]any{"type": "string", "format": "date-time"} } switch t.Kind() { diff --git a/internal/app/controlplane/schema_test.go b/internal/app/controlplane/schema_test.go index e22a89c9a..31acd938b 100644 --- a/internal/app/controlplane/schema_test.go +++ b/internal/app/controlplane/schema_test.go @@ -136,6 +136,48 @@ func TestEveryResourceDescriptorDerivesProperties(t *testing.T) { } } +// TestSchedulesDescriptorFormatsTheInterval is the same payoff one document over: +// the schedules interval is a Duration now, so the derivation turns it into a +// formatted string with no schema authored for it (archie-core-4w0c). +func TestSchedulesDescriptorFormatsTheInterval(t *testing.T) { + server := testServer(t, nil) + catalog, err := server.Catalog(t.Context(), nil) + if err != nil { + t.Fatalf("Catalog: %v", err) + } + var schema struct { + Items struct { + Properties struct { + Schedule struct { + Properties struct { + Interval struct { + Type string `json:"type"` + Format string `json:"format"` + } `json:"interval"` + } `json:"properties"` + } `json:"schedule"` + } `json:"properties"` + } `json:"items"` + } + found := false + for _, descriptor := range catalog.Resources { + if descriptor.Kind != SchedulesKind { + continue + } + found = true + if err := json.Unmarshal([]byte(descriptor.SchemaJson), &schema); err != nil { + t.Fatalf("unmarshal schedules schema: %v", err) + } + } + if !found { + t.Fatal("schedules is not in the catalog") + } + interval := schema.Items.Properties.Schedule.Properties.Interval + if interval.Type != "string" || interval.Format != "duration" { + t.Errorf("schedule.interval = %+v, want a duration-formatted string: the document carries 30m0s, not nanoseconds", interval) + } +} + // TestChannelSettingsDescriptorFormatsTheRateLimitWindow is the concrete payoff: // the field that asked an operator for a nanosecond count now carries a format a // client can render an affordance for, and it arrives by derivation rather than diff --git a/internal/infrastructure/crondelivery/helpers_test.go b/internal/infrastructure/crondelivery/helpers_test.go index fcf528da4..b162db762 100644 --- a/internal/infrastructure/crondelivery/helpers_test.go +++ b/internal/infrastructure/crondelivery/helpers_test.go @@ -279,7 +279,7 @@ func chatSpec(id, chatID, text string) cronstore.JobSpec { ID: id, Detail: "test job " + id, Kind: cronstore.KindChat, - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: time.Hour}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}, Target: cronstore.Target{ChatID: chatID}, Payload: cronstore.Payload{Text: text}, } @@ -291,7 +291,7 @@ func workflowSpec(id, detail, body string) cronstore.JobSpec { ID: id, Detail: detail, Kind: cronstore.KindWorkflow, - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: time.Hour}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}, Payload: cronstore.Payload{Text: body}, } } diff --git a/internal/infrastructure/crondelivery/router_test.go b/internal/infrastructure/crondelivery/router_test.go index 1ef8940e5..8f85cf4d4 100644 --- a/internal/infrastructure/crondelivery/router_test.go +++ b/internal/infrastructure/crondelivery/router_test.go @@ -23,7 +23,7 @@ func routerFixture(t *testing.T, kind string) (*Router, *countingRunner, *counti ID: "routed", Detail: "routed job", Kind: kind, - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: time.Hour}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}, }) chat, workflow := &countingRunner{}, &countingRunner{} sink := &recordingSink{} @@ -120,7 +120,7 @@ func TestRouterNilSinkDoesNotPanicOnUnknownKind(t *testing.T) { createJob(t, s, cronstore.JobSpec{ ID: "routed", Kind: "teleport", - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: time.Hour}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(time.Hour)}, }) chat, workflow := &countingRunner{}, &countingRunner{} r, err := NewRouter(s, map[string]scheduling.Runner{ @@ -258,7 +258,7 @@ func TestDailyStatusSummaryEndToEnd(t *testing.T) { ID: "daily-status", Detail: "daily status summary", Kind: cronstore.KindChat, - Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: 24 * time.Hour}, + Schedule: cronstore.Schedule{Kind: cronstore.ScheduleInterval, Interval: cronstore.Duration(24 * time.Hour)}, Target: cronstore.Target{ChatID: chatID}, Payload: cronstore.Payload{Text: dailyStatusSummary}, // Due now: create it with a next_run in the past, the state a diff --git a/internal/infrastructure/cronstore/schedule.go b/internal/infrastructure/cronstore/schedule.go index a5fe4e1ba..f08ecfadb 100644 --- a/internal/infrastructure/cronstore/schedule.go +++ b/internal/infrastructure/cronstore/schedule.go @@ -1,10 +1,52 @@ package cronstore import ( + "encoding/json" "fmt" "time" ) +// Duration is a schedule interval as the document writes it: the human string +// time.ParseDuration reads, never a nanosecond count. It reads the count too, +// because every schedule stored before this shape existed carries one -- both in +// the control plane's schedules resource and in this package's own jobs table, +// which persists the spec as JSON. +// +// The type is deliberately local, as config.Duration is for the file document +// and channelDuration is in internal/app/controlplane: each document owns its own +// wire form, and what is actually worth unifying later is the legacy-count +// tolerance rather than the tag shape. +type Duration time.Duration + +func (d Duration) MarshalJSON() ([]byte, error) { + return json.Marshal(time.Duration(d).String()) +} + +func (d *Duration) UnmarshalJSON(data []byte) error { + var text string + if err := json.Unmarshal(data, &text); err == nil { + value, err := time.ParseDuration(text) + if err != nil { + return fmt.Errorf("%w: interval must be a Go duration string such as %q: %w", ErrInvalidSpec, "30m", err) + } + *d = Duration(value) + return nil + } + var nanos int64 + if err := json.Unmarshal(data, &nanos); err != nil { + return fmt.Errorf("%w: interval must be a Go duration string such as %q or a nanosecond count: %w", ErrInvalidSpec, "30m", err) + } + *d = Duration(nanos) + return nil +} + +// Std is the standard-library duration, for arithmetic and comparison. +func (d Duration) Std() time.Duration { return time.Duration(d) } + +// String renders the interval the way the document writes it, so an error +// message or a log line reads "30m0s" rather than 1800000000000. +func (d Duration) String() string { return time.Duration(d).String() } + // Schedule decides when a job is due. The Kind field selects which of // Interval, Cron, At the store uses to compute nextRun. Empty Kind // resolves to "interval" so the simplest recurring job needs no @@ -15,8 +57,10 @@ type Schedule struct { Kind string `json:"kind,omitempty"` // Interval is the period for ScheduleInterval. Required when Kind - // is ScheduleInterval; ignored otherwise. - Interval time.Duration `json:"interval,omitempty"` + // is ScheduleInterval; ignored otherwise. It is a Duration rather + // than a time.Duration so the document carries "30m0s" and not the + // nanosecond count that asked an operator to type 1800000000000. + Interval Duration `json:"interval,omitempty"` // Cron is the 5-field cron expression for ScheduleCron. Required // when Kind is ScheduleCron; ignored otherwise. @@ -98,9 +142,9 @@ func (s Schedule) firstRun(now time.Time) (time.Time, error) { switch s.resolve().Kind { case ScheduleInterval: if !s.Start.IsZero() { - return s.Start.Add(s.Interval), nil + return s.Start.Add(s.Interval.Std()), nil } - return now.Add(s.Interval), nil + return now.Add(s.Interval.Std()), nil case ScheduleOnce: if s.At == nil { return time.Time{}, fmt.Errorf("%w: once schedule has no at time", ErrScheduleUnsupported) @@ -127,7 +171,7 @@ func (s Schedule) Resolved() Schedule { return s.resolve() } func (s Schedule) nextRun(lastRun time.Time) (time.Time, error) { switch s.resolve().Kind { case ScheduleInterval: - return lastRun.Add(s.Interval), nil + return lastRun.Add(s.Interval.Std()), nil case ScheduleOnce: return time.Time{}, fmt.Errorf("%w: once schedule has no next run", ErrScheduleUnsupported) case ScheduleCron: diff --git a/internal/infrastructure/cronstore/schedule_duration_test.go b/internal/infrastructure/cronstore/schedule_duration_test.go new file mode 100644 index 000000000..c1457c685 --- /dev/null +++ b/internal/infrastructure/cronstore/schedule_duration_test.go @@ -0,0 +1,91 @@ +package cronstore + +import ( + "encoding/json" + "strings" + "testing" + "time" +) + +// TestScheduleIntervalWritesADurationString pins the document form: the interval +// an operator edits must read as a duration, not as the nanosecond count that +// asked them to type 1800000000000. +func TestScheduleIntervalWritesADurationString(t *testing.T) { + encoded, err := json.Marshal(Schedule{Kind: ScheduleInterval, Interval: Duration(30 * time.Minute)}) + if err != nil { + t.Fatalf("marshal: %v", err) + } + if got := string(encoded); !strings.Contains(got, `"interval":"30m0s"`) { + t.Errorf("marshalled schedule = %s, want interval as the string \"30m0s\"", got) + } + if strings.Contains(string(encoded), "1800000000000") { + t.Errorf("marshalled schedule = %s, want no nanosecond count", encoded) + } +} + +// TestScheduleIntervalReadsEveryStoredForm covers what the store already holds. +// Every schedule written before this shape existed carries a nanosecond count, in +// both the control plane's schedules resource and this package's own jobs table, +// and both have to keep working without being re-saved first. +func TestScheduleIntervalReadsEveryStoredForm(t *testing.T) { + for _, tt := range []struct { + name string + document string + expected time.Duration + }{ + {"legacy nanosecond count", `{"kind":"interval","interval":1800000000000}`, 30 * time.Minute}, + {"duration string", `{"kind":"interval","interval":"30m"}`, 30 * time.Minute}, + {"duration string, canonical", `{"kind":"interval","interval":"30m0s"}`, 30 * time.Minute}, + } { + t.Run(tt.name, func(t *testing.T) { + var schedule Schedule + if err := json.Unmarshal([]byte(tt.document), &schedule); err != nil { + t.Fatalf("unmarshal %s: %v", tt.document, err) + } + if schedule.Interval.Std() != tt.expected { + t.Errorf("Interval = %v, want %v", schedule.Interval, tt.expected) + } + if err := schedule.Validate(); err != nil { + t.Errorf("Validate() = %v, want the decoded schedule to be usable", err) + } + }) + } +} + +// TestScheduleIntervalRefusesWhatItCannotUse keeps the tolerance above from +// becoming indifference: a duration that does not parse must fail loudly rather +// than decode as zero, because a zero interval is a job that never fires. +func TestScheduleIntervalRefusesWhatItCannotUse(t *testing.T) { + for _, tt := range []struct{ name, document string }{ + {"an unparseable duration", `{"kind":"interval","interval":"soon"}`}, + {"a fractional count", `{"kind":"interval","interval":1.5}`}, + {"a null interval", `{"kind":"interval","interval":null}`}, + } { + t.Run(tt.name, func(t *testing.T) { + var schedule Schedule + if err := json.Unmarshal([]byte(tt.document), &schedule); err == nil { + t.Fatalf("unmarshal(%s) = nil, want a refusal: a silent zero interval never fires", tt.document) + } + }) + } +} + +// TestScheduleIntervalRoundTripsThroughTheStore pins the shape the jobs table +// keeps, since it persists the spec as JSON rather than as columns. +func TestScheduleIntervalRoundTripsThroughTheStore(t *testing.T) { + spec := JobSpec{ID: "nightly", Schedule: Schedule{Kind: ScheduleInterval, Interval: Duration(90 * time.Minute)}} + encoded, err := json.Marshal(spec) + if err != nil { + t.Fatalf("marshal: %v", err) + } + if !strings.Contains(string(encoded), `"interval":"1h30m0s"`) { + t.Fatalf("marshalled spec = %s, want the interval as \"1h30m0s\"", encoded) + } + var decoded JobSpec + if err := json.Unmarshal(encoded, &decoded); err != nil { + t.Fatalf("unmarshal: %v", err) + } + if decoded.Schedule.Interval.Std() != 90*time.Minute { + t.Errorf("round-tripped Interval = %v, want 1h30m0s", decoded.Schedule.Interval) + } +} diff --git a/internal/infrastructure/cronstore/store_review_test.go b/internal/infrastructure/cronstore/store_review_test.go index acc107e6c..19b87fea2 100644 --- a/internal/infrastructure/cronstore/store_review_test.go +++ b/internal/infrastructure/cronstore/store_review_test.go @@ -259,7 +259,7 @@ func TestCreateAndGetRoundTripWithUnicodeAndQuotes(t *testing.T) { Detail: "Hello\n\"世界\"\\back", Schedule: Schedule{ Kind: ScheduleInterval, - Interval: 30 * time.Minute, + Interval: Duration(30 * time.Minute), }, Payload: Payload{Text: " & 中文"}, } diff --git a/internal/infrastructure/cronstore/store_test.go b/internal/infrastructure/cronstore/store_test.go index f3bdbf06a..ec3694e34 100644 --- a/internal/infrastructure/cronstore/store_test.go +++ b/internal/infrastructure/cronstore/store_test.go @@ -50,7 +50,7 @@ func fixedIntervalSpec(id string, every time.Duration) JobSpec { Detail: "test job " + id, Schedule: Schedule{ Kind: ScheduleInterval, - Interval: every, + Interval: Duration(every), }, Payload: Payload{Text: "hello " + id}, } @@ -138,7 +138,7 @@ func TestCreateAndGetRoundTrip(t *testing.T) { Detail: "morning status", Schedule: Schedule{ Kind: ScheduleInterval, - Interval: 30 * time.Minute, + Interval: Duration(30 * time.Minute), }, Payload: Payload{Text: "status please"}, } @@ -228,7 +228,7 @@ func TestUpdatePreservesFieldsNotInPatch(t *testing.T) { Detail: "original detail", Schedule: Schedule{ Kind: ScheduleInterval, - Interval: 10 * time.Minute, + Interval: Duration(10 * time.Minute), }, Payload: Payload{Text: "original payload"}, }) @@ -247,7 +247,7 @@ func TestUpdatePreservesFieldsNotInPatch(t *testing.T) { if got.Pool != string(scheduling.PoolParallel) { t.Errorf("Pool = %q, want %q (merge must preserve)", got.Pool, scheduling.PoolParallel) } - if got.Schedule.Interval != 10*time.Minute { + if got.Schedule.Interval.Std() != 10*time.Minute { t.Errorf("Schedule.Interval = %v, want %v (merge must preserve)", got.Schedule.Interval, 10*time.Minute) } if got.Payload.Text != "original payload" { @@ -280,12 +280,12 @@ func TestUpdateRecomputesNextRunWhenScheduleChanges(t *testing.T) { // Change the interval; NextRun must move. if err := s.Update(context.Background(), "rs", Patch{ - Schedule: &Schedule{Kind: ScheduleInterval, Interval: 2 * time.Minute}, + Schedule: &Schedule{Kind: ScheduleInterval, Interval: Duration(2 * time.Minute)}, }); err != nil { t.Fatalf("Update: %v", err) } got, _, _ := s.Get(context.Background(), "rs") - if got.Schedule.Interval != 2*time.Minute { + if got.Schedule.Interval.Std() != 2*time.Minute { t.Errorf("Schedule.Interval = %v, want %v", got.Schedule.Interval, 2*time.Minute) } if !got.NextRun.Before(first.NextRun) {