WeKnora/internal/plugin/configschema/schema.go

220 lines
6.5 KiB
Go

// Package configschema describes configuration with a subset of JSON Schema
// (draft 2020-12) plus a few x- keywords for the UI, and handles the secret
// fields such a schema marks: encrypting them at rest, redacting them in
// responses and keeping them when an update sends the redaction back.
//
// One schema drives both the form the frontend renders and the server-side
// validation, replacing the per-integration field descriptors (model vendor
// ExtraField, web search config fields, hardcoded connector and IM forms).
package configschema
import (
"encoding/json"
"errors"
"fmt"
"regexp"
"sort"
)
// Types a schema node may declare.
const (
TypeObject = "object"
TypeString = "string"
TypeNumber = "number"
TypeInteger = "integer"
TypeBoolean = "boolean"
TypeArray = "array"
)
// Schema is one node of a configuration schema. The root is an object whose
// properties are the fields of a form.
type Schema struct {
Type string `json:"type,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
Default any `json:"default,omitempty"`
Const any `json:"const,omitempty"`
Enum []any `json:"enum,omitempty"`
// OneOf lists labelled choices: each entry carries a const and a title.
OneOf []*Schema `json:"oneOf,omitempty"`
MinLength *int `json:"minLength,omitempty"`
MaxLength *int `json:"maxLength,omitempty"`
Pattern string `json:"pattern,omitempty"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
// Format is "uri" or "email"; other formats are carried but not checked.
Format string `json:"format,omitempty"`
// Secret marks a string that is encrypted at rest, redacted in
// responses, and kept when an update sends the redaction back.
Secret bool `json:"x-secret,omitempty"`
// Widget picks the form control (password, textarea, select, switch,
// headers, ...). Empty means the frontend picks from the type; "hidden"
// keeps a field out of the form while still declaring it (a secret set
// by another flow, such as WeChat's QR binding).
Widget string `json:"x-widget,omitempty"`
Placeholder string `json:"x-placeholder,omitempty"`
// I18n carries localized title / description / placeholder:
// {"title": {"zh-CN": "..."}}.
I18n map[string]map[string]string `json:"x-i18n,omitempty"`
// I18nKeys names frontend locale keys for title / description /
// placeholder. Builtins use them; the frontend falls back to I18n and
// then to the plain text when a key is missing.
I18nKeys map[string]string `json:"x-i18n-keys,omitempty"`
// VisibleIf shows the field only while every listed sibling field
// equals the given value.
VisibleIf map[string]any `json:"x-visible-if,omitempty"`
Group string `json:"x-group,omitempty"`
// Order sorts fields in the form (lower first); ties sort by key.
Order int `json:"x-order,omitempty"`
// ModelTypes limits a model vendor field to some model types.
ModelTypes []string `json:"x-model-types,omitempty"`
}
// Object returns an empty object schema.
func Object() *Schema { return &Schema{Type: TypeObject, Properties: map[string]*Schema{}} }
// Set adds a property and returns the parent for chaining. A required
// property is also listed in Required.
func (s *Schema) Set(key string, prop *Schema, required bool) *Schema {
if s.Properties == nil {
s.Properties = map[string]*Schema{}
}
s.Properties[key] = prop
if required {
s.Required = append(s.Required, key)
}
return s
}
// OrderedKeys returns property keys sorted by x-order, then by key.
func (s *Schema) OrderedKeys() []string {
keys := make([]string, 0, len(s.Properties))
for k := range s.Properties {
keys = append(keys, k)
}
sort.Slice(keys, func(i, j int) bool {
oi, oj := s.Properties[keys[i]].Order, s.Properties[keys[j]].Order
if oi != oj {
return oi < oj
}
return keys[i] < keys[j]
})
return keys
}
// Parse decodes a schema and checks that it stays within the supported
// subset.
func Parse(data []byte) (*Schema, error) {
var s Schema
if err := json.Unmarshal(data, &s); err != nil {
return nil, fmt.Errorf("decode config schema: %w", err)
}
if err := s.Check(); err != nil {
return nil, err
}
return &s, nil
}
// Check verifies that a schema uses only what this package understands. The
// root must be an object, since a configuration is always a set of fields.
func (s *Schema) Check() error {
if s.Type != TypeObject {
return errors.New("config schema root must be an object")
}
var errs []error
s.check("", &errs)
return errors.Join(errs...)
}
func (s *Schema) check(path string, errs *[]error) {
fail := func(format string, args ...any) {
*errs = append(*errs, fmt.Errorf("%s: %s", displayPath(path), fmt.Sprintf(format, args...)))
}
switch s.Type {
case TypeObject:
for _, key := range s.Required {
if _, ok := s.Properties[key]; !ok {
fail("required field %q has no property", key)
}
}
for _, key := range s.OrderedKeys() {
s.Properties[key].check(joinPath(path, key), errs)
}
case TypeArray:
if s.Items == nil {
fail("array needs items")
} else {
if s.Items.containsSecret() {
fail("secrets inside arrays are not supported")
}
s.Items.check(path+"[]", errs)
}
case TypeString, TypeNumber, TypeInteger, TypeBoolean:
default:
fail("unsupported type %q", s.Type)
}
if s.Secret && s.Type != TypeString {
fail("x-secret is only allowed on strings")
}
if s.Pattern != "" {
if _, err := regexp.Compile(s.Pattern); err != nil {
fail("invalid pattern: %v", err)
}
}
for _, choice := range s.OneOf {
if choice.Const == nil {
fail("oneOf entries must carry a const")
}
}
}
func (s *Schema) containsSecret() bool {
if s.Secret {
return true
}
for _, p := range s.Properties {
if p.containsSecret() {
return true
}
}
return s.Items != nil && s.Items.containsSecret()
}
// SecretPaths lists the dotted paths of every secret field, sorted.
func (s *Schema) SecretPaths() []string {
var out []string
var walk func(n *Schema, path string)
walk = func(n *Schema, path string) {
if n.Secret {
out = append(out, path)
}
for key, p := range n.Properties {
walk(p, joinPath(path, key))
}
}
walk(s, "")
sort.Strings(out)
return out
}
func joinPath(parent, key string) string {
if parent == "" {
return key
}
return parent + "." + key
}
func displayPath(path string) string {
if path == "" {
return "(root)"
}
return path
}