Files
archie/internal/app/controlplane/schema.go
T
sam 0e94196052 refactor(scheduling): delete the legacy file-backed cronstore
The schedules feature no longer runs on it: jobs live in the state store
as the schedules control-plane document, read and written through the
control-plane client (scheduleResourceStore), and the legacy jobs.json
migration into that document has run its course. What remained of
internal/infrastructure/cronstore was 1,600 lines of file store, OS-level
cross-process locking and schema-versioned JSON envelope -- plus the
schedule vocabulary held hostage inside it.

The vocabulary moves to internal/domain/scheduling, which is where
migration-decisions already said a schedules vocabulary belongs: a domain
vocabulary package must not import infrastructure. JobSpec, Target,
Payload, the kind constants, Schedule and Duration move unchanged -- same
wire shape, same JSON tags -- with the two sentinel errors callers
matched outside the package (ErrJobNotFound, ErrScheduleUnsupported) and
ErrInvalidSpec, which the schedule arithmetic itself raises. The store's
own sentinels die with the store.

The legacy migration path (migrateLegacySchedules, readLegacyJobs) goes
with it: its only dependency was cronstore.Open, and its work is done.

crondelivery keeps its consumer-owned contracts; the compile-time
assertions that pinned *cronstore.Store move to the production
implementation, scheduleResourceStore, in internal/app/archied. The
package's fixtures swap the real file store for an in-memory one with
the same Get/MarkRun/Due semantics, so the run-recording acceptance test
still asserts against real schedule arithmetic.

A future storage backend (PocketBase) implements the same vocabulary.
2026-09-23 01:40:22 +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 scheduling.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 scheduling.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
}