Files
archie/internal/app/controlplane/schema.go
T
sam 84450ac96c 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}.
2026-09-22 04:22:46 +10:00

163 lines
6.0 KiB
Go

package controlplane
import (
"encoding/json"
"maps"
"reflect"
"strings"
"time"
)
// bareObjectSchema is what a descriptor advertises when its definition names no
// document. It is the fallback, not the norm: a descriptor with no properties is
// what left the Web UI with nothing to label, describe or format a field with
// (archie-core-2xs6).
const bareObjectSchema = `{"type":"object"}`
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.
//
// Derivation is the point. A hand-written schema beside a struct drifts the
// moment a field is added, and nothing catches it, because the document and its
// schema are never compared -- which is exactly how twelve descriptors came to
// advertise `{"type":"object"}` and no field metadata at all.
//
// It describes structure only: keys, types, and the `format`, `title` and `doc`
// annotations a field declares in its own tags. It deliberately emits no prose
// of its own. Field descriptions already have one home in this tree
// (internal/webui/config_schema.go, keyed by dotted config path), and a second
// would be two places to keep the same fact true.
//
// `required` is never emitted. An empty string is a legitimate value for nearly
// every field here -- a blank workspace, a disabled rate limit -- so calling most
// fields required would invite a client to enforce something the document does
// not mean.
func schemaJSON(document any) string {
if document == nil {
return bareObjectSchema
}
encoded, err := json.Marshal(schemaOf(reflect.TypeOf(document)))
if err != nil {
// Unreachable: the tree below holds only strings, maps, slices and
// booleans. A boot must not fail over documentation, so degrade to the
// shape descriptors carried before this existed rather than panic.
return bareObjectSchema
}
return string(encoded)
}
// schemaOf is the JSON Schema for one type, following json tags for keys and the
// Go type for everything else.
func schemaOf(t reflect.Type) map[string]any {
for t.Kind() == reflect.Pointer {
t = t.Elem()
}
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 t == timeType:
return map[string]any{"type": "string", "format": "date-time"}
}
switch t.Kind() {
case reflect.Struct:
return objectSchemaOf(t)
case reflect.Slice, reflect.Array:
return map[string]any{"type": "array", "items": schemaOf(t.Elem())}
case reflect.Map:
return map[string]any{"type": "object", "additionalProperties": schemaOf(t.Elem())}
case reflect.Bool:
return map[string]any{"type": "boolean"}
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
return map[string]any{"type": "integer"}
case reflect.Float32, reflect.Float64:
return map[string]any{"type": "number"}
default:
return map[string]any{"type": "string"}
}
}
func objectSchemaOf(t reflect.Type) map[string]any {
properties := map[string]any{}
for field := range t.Fields() {
if field.Anonymous {
// encoding/json promotes an embedded struct's fields into the
// enclosing object, so the schema lists them there too. Dropping
// them would leave document keys nothing describes.
embedded, ok := schemaOf(field.Type)["properties"].(map[string]any)
if !ok {
continue
}
maps.Copy(properties, embedded)
continue
}
if field.PkgPath != "" {
continue // unexported: not part of any document
}
name, ok := documentKey(field)
if !ok {
continue
}
properties[name] = documented(schemaOf(field.Type), field)
}
return map[string]any{"type": "object", "properties": properties}
}
// documentKey is the key a field carries in its document: the json tag's name,
// or the Go field name when the tag declares none, because that fallback is what
// encoding/json uses and therefore what the document really holds. Reporting the
// tag instead of the fallback would describe a document nobody stores.
func documentKey(field reflect.StructField) (string, bool) {
name, _, _ := strings.Cut(field.Tag.Get("json"), ",")
switch name {
case "-":
return "", false
case "":
return field.Name, true
default:
return name, true
}
}
// documented layers the three annotations a field declares in its own tags over
// the derived type.
func documented(schema map[string]any, field reflect.StructField) map[string]any {
for _, annotation := range []struct{ tag, key string }{
{"title", "title"},
{"format", "format"},
{"doc", "description"},
} {
if value := field.Tag.Get(annotation.tag); value != "" {
schema[annotation.key] = value
}
}
return schema
}