Files
archie/internal/infrastructure/controlplanestore/schema.go
T

156 lines
5.2 KiB
Go

package controlplanestore
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
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 marshals as a duration string.
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 derives a resource's JSON Schema from its document type: keys,
// types and tag annotations. It never emits required.
func schemaJSON(document any, extensions map[string]any) string {
if document == nil {
return bareObjectSchema
}
schema := schemaOf(reflect.TypeOf(document), "json")
maps.Copy(schema, extensions)
encoded, err := json.Marshal(schema)
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)
}
// settingsSchema is the JSON Schema of a workflow step's settings type, keyed by
// its yaml tags because step settings are written in YAML. Nil means the step
// takes no settings.
func settingsSchema(settings any) map[string]any {
if settings == nil {
return nil
}
return schemaOf(reflect.TypeOf(settings), "yaml")
}
// schemaOf is the JSON Schema for one type, following the keyTag struct tags
// for keys and the Go type for everything else.
func schemaOf(t reflect.Type, keyTag string) 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, keyTag)
case reflect.Slice, reflect.Array:
return map[string]any{"type": "array", "items": schemaOf(t.Elem(), keyTag)}
case reflect.Map:
return map[string]any{"type": "object", "additionalProperties": schemaOf(t.Elem(), keyTag)}
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"}
case reflect.Interface:
return map[string]any{} // any JSON value
default:
return map[string]any{"type": "string"}
}
}
func objectSchemaOf(t reflect.Type, keyTag string) 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, keyTag)["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, keyTag)
if !ok {
continue
}
properties[name] = documented(schemaOf(field.Type, keyTag), 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, keyTag string) (string, bool) {
name, _, _ := strings.Cut(field.Tag.Get(keyTag), ",")
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
}
}
if values := field.Tag.Get("enum"); values != "" {
schema["enum"] = strings.Split(values, ",")
}
return schema
}