diff --git a/internal/app/controlplane/definitions.go b/internal/app/controlplane/definitions.go index a02921ca0..937eeaea0 100644 --- a/internal/app/controlplane/definitions.go +++ b/internal/app/controlplane/definitions.go @@ -5,11 +5,8 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow" ) -const ( - objectSchema = `{"type":"object"}` - arraySchema = `{"type":"array"}` -) - +// Schemas are not declared here: each Definition names its document type, and +// Definition.Descriptor derives the JSON Schema from it (internal/app/controlplane/schema.go). func builtinDefinitions(steps workflow.StepRegistry) []Definition { definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition()} definitions = append(definitions, modelDefinitions()...) diff --git a/internal/app/controlplane/model_settings.go b/internal/app/controlplane/model_settings.go index c344f81d2..9d7878190 100644 --- a/internal/app/controlplane/model_settings.go +++ b/internal/app/controlplane/model_settings.go @@ -23,8 +23,8 @@ type providerDocument struct { func modelDefinitions() []Definition { return []Definition{ - {Kind: ProviderSettingsKind, Title: "Providers", ApplyMode: "restart-required", Schema: objectSchema, Seed: seedProviders, Validate: validateProviders}, - {Kind: ModelRoleAssignmentsKind, Title: "Model role assignments", ApplyMode: "restart-required", Schema: objectSchema, Seed: func(cfg config.Config) any { return cfg.Models }, Validate: validateModelRoles}, + {Kind: ProviderSettingsKind, Title: "Providers", ApplyMode: "restart-required", Document: map[string]providerDocument{}, Seed: seedProviders, Validate: validateProviders}, + {Kind: ModelRoleAssignmentsKind, Title: "Model role assignments", ApplyMode: "restart-required", Document: map[string]string{}, Seed: func(cfg config.Config) any { return cfg.Models }, Validate: validateModelRoles}, } } diff --git a/internal/app/controlplane/operational_settings.go b/internal/app/controlplane/operational_settings.go index 3c951380a..572693aeb 100644 --- a/internal/app/controlplane/operational_settings.go +++ b/internal/app/controlplane/operational_settings.go @@ -42,16 +42,16 @@ type pluginSettings struct { func operationalDefinitions() []Definition { return []Definition{ - {Kind: RepositoryPoliciesKind, Title: "Repository policies", ApplyMode: "restart-required", Schema: arraySchema, Seed: func(cfg config.Config) any { return cfg.Repos }, Validate: validateRepositories}, - {Kind: ChannelSettingsKind, Title: "Channel settings", ApplyMode: "restart-required", Schema: objectSchema, Seed: seedChannels, Validate: validateChannels, Normalize: normalizeChannels}, - {Kind: SchedulingPolicyKind, Title: "Scheduling policy", ApplyMode: "restart-required", Schema: objectSchema, Seed: func(cfg config.Config) any { + {Kind: RepositoryPoliciesKind, Title: "Repository policies", ApplyMode: "restart-required", Document: []config.Repo{}, Seed: func(cfg config.Config) any { return cfg.Repos }, Validate: validateRepositories}, + {Kind: ChannelSettingsKind, Title: "Channel settings", ApplyMode: "restart-required", Document: channelSettings{}, Seed: seedChannels, Validate: validateChannels, Normalize: normalizeChannels}, + {Kind: SchedulingPolicyKind, Title: "Scheduling policy", ApplyMode: "restart-required", Document: schedulingPolicy{}, Seed: func(cfg config.Config) any { return schedulingPolicy{PollInterval: cfg.PollInterval.Std().String(), MaxRetries: cfg.MaxRetries, Label: &cfg.Label, Dispatch: cfg.Dispatch} }, Validate: validateScheduling}, - {Kind: ToolSettingsKind, Title: "Tool and MCP settings", ApplyMode: "restart-required", Schema: objectSchema, Seed: seedTools, Validate: validateTools}, - {Kind: PluginSettingsKind, Title: "Plugin settings", ApplyMode: "restart-required", Schema: objectSchema, Seed: func(cfg config.Config) any { + {Kind: ToolSettingsKind, Title: "Tool and MCP settings", ApplyMode: "restart-required", Document: toolSettings{}, Seed: seedTools, Validate: validateTools}, + {Kind: PluginSettingsKind, Title: "Plugin settings", ApplyMode: "restart-required", Document: pluginSettings{}, Seed: func(cfg config.Config) any { return pluginSettings{cfg.PluginDir, cfg.ModuleDir, cfg.SecretEngineDir, cfg.SkillsDir} }, Validate: validatePluginSettings}, - {Kind: ContainerRuntimePoliciesKind, Title: "Container runtime policies", ApplyMode: "restart-required", Schema: objectSchema, Seed: func(cfg config.Config) any { return cfg.Containers }, Validate: validateContainers}, + {Kind: ContainerRuntimePoliciesKind, Title: "Container runtime policies", ApplyMode: "restart-required", Document: config.ContainerConfig{}, Seed: func(cfg config.Config) any { return cfg.Containers }, Validate: validateContainers}, } } diff --git a/internal/app/controlplane/personas.go b/internal/app/controlplane/personas.go index 097528ab9..aba1613be 100644 --- a/internal/app/controlplane/personas.go +++ b/internal/app/controlplane/personas.go @@ -13,7 +13,7 @@ func personaDefinition() Definition { return Definition{ Kind: PersonasKind, Title: "Personas", - Schema: objectSchema, + Document: agent.PersonaCollection{}, ApplyMode: "live", Seed: func(config.Config) any { return agent.ShippedPersonas() }, Validate: func(input []byte) error { diff --git a/internal/app/controlplane/registry.go b/internal/app/controlplane/registry.go index 86648d0e6..eada7eb79 100644 --- a/internal/app/controlplane/registry.go +++ b/internal/app/controlplane/registry.go @@ -14,9 +14,14 @@ import ( ) type Definition struct { - Kind string - Title string - Schema string + Kind string + Title string + // Document is a zero value of the resource's document type. The descriptor's + // JSON Schema is derived from it (see schemaJSON) rather than written out + // here, so the schema cannot drift from the document it describes. Nil means + // the definition names no document, which is why bareObjectSchema still + // exists as a fallback. + Document any ApplyMode string Seed func(config.Config) any Validate func([]byte) error @@ -27,7 +32,7 @@ type Definition struct { } func (d Definition) Descriptor() *pb.ResourceDescriptor { - descriptor := &pb.ResourceDescriptor{Kind: d.Kind, Title: d.Title, SchemaJson: d.Schema, Commands: []string{"replace"}, ApplyMode: d.ApplyMode} + descriptor := &pb.ResourceDescriptor{Kind: d.Kind, Title: d.Title, SchemaJson: schemaJSON(d.Document), Commands: []string{"replace"}, ApplyMode: d.ApplyMode} if d.Defaults != nil { if defaults, err := json.Marshal(d.Defaults()); err == nil { descriptor.DefaultsJson = string(defaults) diff --git a/internal/app/controlplane/schedules.go b/internal/app/controlplane/schedules.go index 0af23b750..bbc0fe2ff 100644 --- a/internal/app/controlplane/schedules.go +++ b/internal/app/controlplane/schedules.go @@ -17,7 +17,7 @@ func scheduleDefinition() Definition { return Definition{ Kind: SchedulesKind, Title: "Schedules", - Schema: arraySchema, + Document: []cronstore.JobSpec{}, ApplyMode: "live", Seed: func(config.Config) any { return []cronstore.JobSpec{} }, Validate: func(input []byte) error { diff --git a/internal/app/controlplane/schema.go b/internal/app/controlplane/schema.go new file mode 100644 index 000000000..0be6a1240 --- /dev/null +++ b/internal/app/controlplane/schema.go @@ -0,0 +1,149 @@ +package controlplane + +import ( + "encoding/json" + "reflect" + "strings" + "time" + + "github.com/samcharles93/archie-core/internal/config" +) + +// 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 ( + configDurationType = reflect.TypeOf(config.Duration(0)) + channelDurationType = reflect.TypeOf(channelDuration(0)) + timeType = reflect.TypeOf(time.Time{}) +) + +// 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 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. + return map[string]any{"type": "string", "format": "duration"} + case 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 i := range t.NumField() { + field := t.Field(i) + 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 + } + for name, property := range embedded { + properties[name] = property + } + 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 +} diff --git a/internal/app/controlplane/schema_test.go b/internal/app/controlplane/schema_test.go new file mode 100644 index 000000000..26686ff31 --- /dev/null +++ b/internal/app/controlplane/schema_test.go @@ -0,0 +1,179 @@ +package controlplane + +import ( + "encoding/json" + "reflect" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/config" +) + +type schemaFixtureNested struct { + Prompt string `json:"prompt"` +} + +type schemaFixtureEmbedded struct { + Shared string `json:"shared"` +} + +type schemaFixture struct { + schemaFixtureEmbedded + Name string `json:"name" title:"Display name"` + Skipped string `json:"-"` + Untagged string // no json tag: the document key is the Go name + Count int `json:"count"` + Ratio float64 `json:"ratio"` + Enabled bool `json:"enabled"` + Window config.Duration `json:"window"` + Lifetime channelDuration `json:"lifetime"` + When time.Time `json:"when"` + Tags []string `json:"tags"` + Roles map[string]string `json:"roles"` + Nested schemaFixtureNested `json:"nested"` + Hinted string `json:"hinted" format:"duration" doc:"A hint."` + + unexported string +} + +// TestSchemaDerivesKeysTypesAndAnnotations pins the derivation itself, including +// the two rules that are easy to get subtly wrong: a field with no json tag is +// described by the Go name the document actually stores, and a duration is a +// string with a format rather than the integer its Go type would suggest. +func TestSchemaDerivesKeysTypesAndAnnotations(t *testing.T) { + expected := map[string]any{ + "type": "object", + "properties": map[string]any{ + "shared": map[string]any{"type": "string"}, + "name": map[string]any{"type": "string", "title": "Display name"}, + "Untagged": map[string]any{"type": "string"}, + "count": map[string]any{"type": "integer"}, + "ratio": map[string]any{"type": "number"}, + "enabled": map[string]any{"type": "boolean"}, + "window": map[string]any{"type": "string", "format": "duration"}, + "lifetime": map[string]any{"type": "string", "format": "duration"}, + "when": map[string]any{"type": "string", "format": "date-time"}, + "tags": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, + "roles": map[string]any{"type": "object", "additionalProperties": map[string]any{"type": "string"}}, + "nested": map[string]any{"type": "object", "properties": map[string]any{"prompt": map[string]any{"type": "string"}}}, + "hinted": map[string]any{"type": "string", "format": "duration", "description": "A hint."}, + }, + } + var got map[string]any + // The unexported field is populated rather than left blank, so the + // assertion below proves it is omitted even when it carries a value. + if err := json.Unmarshal([]byte(schemaJSON(schemaFixture{unexported: "not in the document"})), &got); err != nil { + t.Fatalf("unmarshal derived schema: %v", err) + } + if !reflect.DeepEqual(got, expected) { + t.Fatalf("derived schema =\n%#v\nwant\n%#v", got, expected) + } + properties, ok := got["properties"].(map[string]any) + if !ok { + t.Fatalf("derived schema has no properties object: %#v", got) + } + if _, present := properties["Skipped"]; present { + t.Error(`json:"-" field is described, so the schema names a key the document never stores`) + } + if _, present := properties["unexported"]; present { + t.Error("unexported field is described") + } +} + +// TestEveryResourceDescriptorDerivesProperties is the regression guard for the +// defect this replaced: twelve definitions each advertised a bare +// {"type":"object"} or {"type":"array"}, so no descriptor carried a single field +// for the Web UI to label, describe or format. Every kind here must describe +// something, and this walks the catalogue the constructor production uses rather +// than the definitions in isolation. +func TestEveryResourceDescriptorDerivesProperties(t *testing.T) { + server := testServer(t, nil) + catalog, err := server.Catalog(t.Context(), nil) + if err != nil { + t.Fatalf("Catalog: %v", err) + } + describing := 0 + for _, descriptor := range catalog.Resources { + if descriptor.SchemaJson == "" { + // Domain-managed kinds (identities, captures, mappings, bindings) + // carry commands rather than a document this side validates. + continue + } + describing++ + var schema map[string]any + if err := json.Unmarshal([]byte(descriptor.SchemaJson), &schema); err != nil { + t.Errorf("%s: schema is not JSON: %v", descriptor.Kind, err) + continue + } + switch schema["type"] { + case "object": + // A fixed document describes properties; a keyed collection + // (providers, model roles) describes additionalProperties and has + // no fixed keys by design. Either is a described document; neither + // is the bare object this guard exists to catch. + properties, hasProperties := schema["properties"].(map[string]any) + _, hasAdditional := schema["additionalProperties"].(map[string]any) + if (!hasProperties || len(properties) == 0) && !hasAdditional { + t.Errorf("%s: object schema describes no fields: %s", descriptor.Kind, descriptor.SchemaJson) + } + case "array": + if _, ok := schema["items"].(map[string]any); !ok { + t.Errorf("%s: array schema describes no items: %s", descriptor.Kind, descriptor.SchemaJson) + } + default: + t.Errorf("%s: schema type = %#v, want object or array", descriptor.Kind, schema["type"]) + } + } + if describing == 0 { + t.Fatal("no descriptor advertised a schema: the guard asserted nothing") + } +} + +// 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 +// by anyone remembering to write it down. +func TestChannelSettingsDescriptorFormatsTheRateLimitWindow(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 { + Properties struct { + RateLimit struct { + Properties struct { + Window struct { + Type string `json:"type"` + Format string `json:"format"` + } `json:"window"` + MaxRequests struct { + Type string `json:"type"` + } `json:"max_requests"` + } `json:"properties"` + } `json:"rate_limit"` + Email struct { + Properties map[string]struct { + Type string `json:"type"` + } `json:"properties"` + } `json:"email"` + } `json:"properties"` + } + for _, descriptor := range catalog.Resources { + if descriptor.Kind != ChannelSettingsKind { + continue + } + if err := json.Unmarshal([]byte(descriptor.SchemaJson), &schema); err != nil { + t.Fatalf("unmarshal channel-settings schema: %v", err) + } + } + if schema.Properties.RateLimit.Properties.Window.Format != "duration" { + t.Errorf("rate_limit.window format = %q, want \"duration\"", schema.Properties.RateLimit.Properties.Window.Format) + } + if schema.Properties.RateLimit.Properties.MaxRequests.Type != "integer" { + t.Errorf("rate_limit.max_requests type = %q, want \"integer\"", schema.Properties.RateLimit.Properties.MaxRequests.Type) + } + if len(schema.Properties.Email.Properties) == 0 { + t.Error("email describes no properties, want listen_addr and relay_addr") + } +} diff --git a/internal/app/controlplane/workflow_definitions.go b/internal/app/controlplane/workflow_definitions.go index 72c5dae20..25dc3aa86 100644 --- a/internal/app/controlplane/workflow_definitions.go +++ b/internal/app/controlplane/workflow_definitions.go @@ -31,7 +31,7 @@ func workflowDefinitionsDefinition(steps workflow.StepRegistry) Definition { return Definition{ Kind: WorkflowDefinitionsKind, Title: "Workflow definitions", - Schema: objectSchema, + Document: workflow.WorkflowDefinitionCollection{}, ApplyMode: "live", Seed: func(config.Config) any { return workflow.ShippedDefinitions() diff --git a/internal/app/controlplane/workflow_settings.go b/internal/app/controlplane/workflow_settings.go index 6f2b70a1f..f92f67fb0 100644 --- a/internal/app/controlplane/workflow_settings.go +++ b/internal/app/controlplane/workflow_settings.go @@ -44,7 +44,7 @@ func (s *Server) ImportWorkflowExecutionSettings(ctx context.Context, settings w func workflowDefinition() Definition { return Definition{ - Kind: WorkflowExecutionSettingsKind, Title: "Workflow execution settings", ApplyMode: "live", Schema: objectSchema, + Kind: WorkflowExecutionSettingsKind, Title: "Workflow execution settings", ApplyMode: "live", Document: executionSettingsDocument{}, Seed: func(cfg config.Config) any { return executionSettingsDocument{cfg.Budgets.MaxSteps, int64(time.Duration(cfg.Budgets.WallClock) / time.Second), cfg.Budgets.GateMaxFailures} },