Files
kandev/apps/backend/internal/settingscatalog/catalog.go
T
2026-09-10 11:35:46 +01:00

485 lines
16 KiB
Go

// Package settingscatalog owns the process-wide metadata contract for agent
// accessible settings. It deliberately does not read persistence or call a
// domain service. Domain adapters provide the values and mutations.
package settingscatalog
import (
"fmt"
"sort"
"strconv"
"strings"
"unicode"
)
const (
MaxSearchQueryLength = 256
MaxSearchResults = 50
DefaultSearchLimit = 20
MaxChangedFields = 50
)
type SupportStatus string
const (
SupportSupported SupportStatus = "supported"
SupportReadOnly SupportStatus = "read_only"
SupportException SupportStatus = "exception"
SupportPending SupportStatus = "pending"
SupportUnavailable SupportStatus = "unavailable"
)
type Classification string
const (
ClassificationWritable Classification = "writable"
ClassificationComputed Classification = "computed"
ClassificationAction Classification = "action"
ClassificationException Classification = "exception"
)
type Scope string
const (
ScopeCaller Scope = "caller"
ScopeWorkspace Scope = "workspace"
ScopeResource Scope = "resource"
ScopeInstallation Scope = "installation"
)
type MatchReason string
const (
MatchExact MatchReason = "exact"
MatchPrefix MatchReason = "prefix"
MatchAlias MatchReason = "alias"
MatchDescription MatchReason = "description"
MatchDomain MatchReason = "domain"
)
type ResourceTarget struct {
ResourceType string `json:"resource_type"`
ResourceID *string `json:"resource_id,omitempty"`
WorkspaceID *string `json:"workspace_id,omitempty"`
}
type TargetRules struct {
Scope Scope `json:"scope"`
Singleton bool `json:"singleton,omitempty"`
RequiresResourceID bool `json:"requires_resource_id,omitempty"`
RequiresWorkspaceID bool `json:"requires_workspace_id,omitempty"`
AllowsWorkspaceID bool `json:"allows_workspace_id,omitempty"`
}
type FieldDescriptor struct {
Key string `json:"key"`
FieldPath string `json:"field_path"`
Label string `json:"label"`
Description string `json:"description"`
Aliases []string `json:"aliases,omitempty"`
JSONType string `json:"json_type"`
Nullable bool `json:"nullable,omitempty"`
Support SupportStatus `json:"support"`
Classification Classification `json:"classification"`
Owner string `json:"owner"`
Writable bool `json:"writable,omitempty"`
Validator string `json:"validator,omitempty"`
Authority string `json:"authority,omitempty"`
Sensitive bool `json:"sensitive,omitempty"`
Replacement bool `json:"replacement,omitempty"`
DefaultBehavior string `json:"default_behavior,omitempty"`
ChangeTiming string `json:"change_timing,omitempty"`
Dependencies []string `json:"dependencies,omitempty"`
SettingsHref string `json:"settings_href,omitempty"`
ExceptionReason string `json:"exception_reason,omitempty"`
Recovery string `json:"recovery,omitempty"`
Schema map[string]any `json:"schema,omitempty"`
}
type OperationDescriptor struct {
Name string `json:"name"`
Binding string `json:"binding"`
Authority string `json:"authority,omitempty"`
Options map[string]any `json:"options,omitempty"`
Description string `json:"description,omitempty"`
}
type DomainDescriptor struct {
Domain string `json:"domain"`
ResourceType string `json:"resource_type"`
Label string `json:"label"`
Description string `json:"description"`
Owner string `json:"owner"`
Scope Scope `json:"scope"`
Target TargetRules `json:"target"`
Fields []FieldDescriptor `json:"fields"`
Operations []OperationDescriptor `json:"operations,omitempty"`
SettingsHref string `json:"settings_href,omitempty"`
}
type Registry struct {
domainsByType map[string]DomainDescriptor
fieldsByKey map[string]FieldDescriptor
domainByField map[string]DomainDescriptor
fields []FieldDescriptor
}
type SearchRequest struct {
Query string
Domain string
ResourceType string
Limit int
Cursor string
}
type SearchItem struct {
Key string `json:"key"`
Label string `json:"label"`
Description string `json:"description"`
ResourceType string `json:"resource_type"`
FieldPath string `json:"field_path"`
Support SupportStatus `json:"support"`
MatchReason MatchReason `json:"match_reason"`
SettingsHref string `json:"settings_href,omitempty"`
}
type SearchResponse struct {
Items []SearchItem `json:"items"`
NextCursor string `json:"next_cursor,omitempty"`
CoveredDomains []string `json:"covered_domains"`
}
func NewRegistry(domains []DomainDescriptor) (*Registry, error) {
registry := &Registry{
domainsByType: make(map[string]DomainDescriptor, len(domains)),
fieldsByKey: make(map[string]FieldDescriptor),
domainByField: make(map[string]DomainDescriptor),
}
for _, domain := range domains {
if err := validateDomain(domain); err != nil {
return nil, err
}
if _, exists := registry.domainsByType[domain.ResourceType]; exists {
return nil, fmt.Errorf("duplicate resource type %q", domain.ResourceType)
}
registry.domainsByType[domain.ResourceType] = cloneDomain(domain)
for _, field := range domain.Fields {
if _, exists := registry.fieldsByKey[field.Key]; exists {
return nil, fmt.Errorf("duplicate setting key %q", field.Key)
}
registry.fieldsByKey[field.Key] = cloneField(field)
registry.domainByField[field.Key] = registry.domainsByType[domain.ResourceType]
registry.fields = append(registry.fields, cloneField(field))
}
}
sort.Slice(registry.fields, func(i, j int) bool { return registry.fields[i].Key < registry.fields[j].Key })
return registry, nil
}
//nolint:cyclop // Catalog validation checks independent target and field invariants in one pass.
func validateDomain(domain DomainDescriptor) error {
if strings.TrimSpace(domain.Domain) == "" {
return fmt.Errorf("domain owner is required for %q", domain.ResourceType)
}
if strings.TrimSpace(domain.ResourceType) == "" {
return fmt.Errorf("resource type is required")
}
if strings.TrimSpace(domain.Owner) == "" {
return fmt.Errorf("owner is required for resource type %q", domain.ResourceType)
}
if domain.Target.Singleton && (domain.Target.RequiresResourceID || domain.Target.RequiresWorkspaceID) {
return fmt.Errorf("singleton target %q cannot require selectors", domain.ResourceType)
}
if domain.Target.RequiresWorkspaceID && domain.Target.RequiresResourceID && !domain.Target.AllowsWorkspaceID {
return fmt.Errorf("resource target %q must explicitly allow workspace selector", domain.ResourceType)
}
seenPaths := make(map[string]struct{}, len(domain.Fields))
for _, field := range domain.Fields {
if strings.TrimSpace(field.Key) == "" || strings.TrimSpace(field.FieldPath) == "" {
return fmt.Errorf("setting key and field path are required for resource type %q", domain.ResourceType)
}
if strings.TrimSpace(field.Owner) == "" {
return fmt.Errorf("setting %q is missing an owner", field.Key)
}
if _, exists := seenPaths[field.FieldPath]; exists {
return fmt.Errorf("duplicate field path %q in resource type %q", field.FieldPath, domain.ResourceType)
}
seenPaths[field.FieldPath] = struct{}{}
if field.Writable {
if field.Support != SupportSupported || field.Classification != ClassificationWritable ||
strings.TrimSpace(field.Validator) == "" || strings.TrimSpace(field.Authority) == "" {
return fmt.Errorf("writable setting %q requires supported classification, validator, and authority", field.Key)
}
}
if field.Support == SupportException && strings.TrimSpace(field.ExceptionReason) == "" {
return fmt.Errorf("exception setting %q requires a reason", field.Key)
}
}
return nil
}
//nolint:cyclop // Search validates bounds, ranks fields, and applies stable pagination as one operation.
func (r *Registry) Search(request SearchRequest) (SearchResponse, error) {
query := strings.TrimSpace(request.Query)
if len([]rune(query)) > MaxSearchQueryLength {
return SearchResponse{}, fmt.Errorf("query exceeds %d characters", MaxSearchQueryLength)
}
limit, err := boundedLimit(request.Limit)
if err != nil {
return SearchResponse{}, err
}
offset, err := parseCursor(request.Cursor)
if err != nil {
return SearchResponse{}, err
}
queryTokens := tokenize(query)
type ranked struct {
item SearchItem
score int
}
rankedItems := make([]ranked, 0, len(r.fields))
for _, field := range r.fields {
domain, ok := r.domainForField(field.Key)
if !ok || (request.Domain != "" && request.Domain != domain.Domain) ||
(request.ResourceType != "" && request.ResourceType != domain.ResourceType) {
continue
}
reason, score, matched := matchField(field, domain, query, queryTokens)
if !matched {
continue
}
rankedItems = append(rankedItems, ranked{item: SearchItem{
Key: field.Key,
Label: field.Label,
Description: field.Description,
ResourceType: domain.ResourceType,
FieldPath: field.FieldPath,
Support: field.Support,
MatchReason: reason,
SettingsHref: field.SettingsHref,
}, score: score})
}
sort.SliceStable(rankedItems, func(i, j int) bool {
if rankedItems[i].score != rankedItems[j].score {
return rankedItems[i].score > rankedItems[j].score
}
return rankedItems[i].item.Key < rankedItems[j].item.Key
})
response := SearchResponse{CoveredDomains: r.CoveredDomains()}
if offset >= len(rankedItems) {
return response, nil
}
end := offset + limit
if end > len(rankedItems) {
end = len(rankedItems)
}
response.Items = make([]SearchItem, 0, end-offset)
for _, match := range rankedItems[offset:end] {
response.Items = append(response.Items, match.item)
}
if end < len(rankedItems) {
response.NextCursor = strconv.Itoa(end)
}
return response, nil
}
func (r *Registry) Find(key string) (FieldDescriptor, DomainDescriptor, bool) {
field, ok := r.fieldsByKey[key]
if !ok {
return FieldDescriptor{}, DomainDescriptor{}, false
}
domain, ok := r.domainForField(key)
return field, domain, ok
}
func (r *Registry) Domain(resourceType string) (DomainDescriptor, bool) {
domain, ok := r.domainsByType[resourceType]
return cloneDomain(domain), ok
}
func (r *Registry) Domains() []DomainDescriptor {
domains := make([]DomainDescriptor, 0, len(r.domainsByType))
for _, domain := range r.domainsByType {
domains = append(domains, cloneDomain(domain))
}
sort.Slice(domains, func(i, j int) bool { return domains[i].ResourceType < domains[j].ResourceType })
return domains
}
func (r *Registry) CoveredDomains() []string {
domains := r.Domains()
result := make([]string, 0, len(domains))
for _, domain := range domains {
result = append(result, domain.Domain)
}
return result
}
//nolint:cyclop // Target validation applies the complete singleton and selector contract.
func (r *Registry) ValidateTarget(target ResourceTarget) error {
if strings.TrimSpace(target.ResourceType) == "" {
return fmt.Errorf("resource_type is required")
}
domain, ok := r.domainsByType[target.ResourceType]
if !ok {
return fmt.Errorf("unknown resource type %q", target.ResourceType)
}
if domain.Target.Singleton && (target.ResourceID != nil || target.WorkspaceID != nil) {
return fmt.Errorf("resource type %q does not accept resource selectors", target.ResourceType)
}
if domain.Target.RequiresResourceID && (target.ResourceID == nil || strings.TrimSpace(*target.ResourceID) == "") {
return fmt.Errorf("resource_id is required for %q", target.ResourceType)
}
if !domain.Target.RequiresResourceID && target.ResourceID != nil {
return fmt.Errorf("resource type %q does not accept resource_id", target.ResourceType)
}
if domain.Target.RequiresWorkspaceID && (target.WorkspaceID == nil || strings.TrimSpace(*target.WorkspaceID) == "") {
return fmt.Errorf("workspace_id is required for %q", target.ResourceType)
}
if !domain.Target.AllowsWorkspaceID && !domain.Target.RequiresWorkspaceID && target.WorkspaceID != nil {
return fmt.Errorf("resource type %q does not accept workspace_id", target.ResourceType)
}
return nil
}
// RuntimeFlagAgentMutable reports whether the compact settings boundary may
// persist an override for a runtime flag. Interactive administration retains
// the separate ability to change installation authentication settings.
func RuntimeFlagAgentMutable(key string) bool {
return strings.TrimSpace(key) != "features.auth"
}
// FieldForTarget applies target-specific policy to a catalog field. The
// runtime flag catalog is shared across keys, but authentication enablement is
// intentionally interactive-only for agent mutations.
func FieldForTarget(field FieldDescriptor, target *ResourceTarget) FieldDescriptor {
if target == nil || target.ResourceType != "runtime_flag" || target.ResourceID == nil ||
field.FieldPath != "override" || RuntimeFlagAgentMutable(*target.ResourceID) {
return field
}
field.Support = SupportException
field.Classification = ClassificationException
field.Writable = false
field.ExceptionReason = "Authentication enablement requires the interactive administration flow."
field.Recovery = "Use the interactive authentication settings control and restart the installation."
return field
}
func (r *Registry) domainForField(key string) (DomainDescriptor, bool) {
domain, ok := r.domainByField[key]
return domain, ok
}
func matchField(field FieldDescriptor, domain DomainDescriptor, query string, queryTokens []string) (MatchReason, int, bool) {
if query == "" {
return MatchDomain, 1, true
}
normalizedQuery := strings.ToLower(query)
key := strings.ToLower(field.Key)
label := strings.ToLower(field.Label)
if normalizedQuery == key || normalizedQuery == label {
return MatchExact, 1000, true
}
if strings.HasPrefix(key, normalizedQuery) || strings.HasPrefix(label, normalizedQuery) {
return MatchPrefix, 800, true
}
for _, alias := range field.Aliases {
if strings.HasPrefix(strings.ToLower(alias), normalizedQuery) {
return MatchAlias, 600, true
}
}
metadata := strings.ToLower(strings.Join(append([]string{field.Description, domain.Description}, field.Aliases...), " "))
for _, token := range queryTokens {
if !strings.Contains(metadata, token) {
return "", 0, false
}
}
if len(queryTokens) > 0 {
return MatchDescription, 400, true
}
return "", 0, false
}
func tokenize(value string) []string {
var tokens []string
var current strings.Builder
flush := func() {
if current.Len() > 0 {
tokens = append(tokens, strings.ToLower(current.String()))
current.Reset()
}
}
for _, char := range strings.ToLower(value) {
if unicode.IsLetter(char) || unicode.IsDigit(char) {
current.WriteRune(char)
continue
}
flush()
}
flush()
return tokens
}
func boundedLimit(limit int) (int, error) {
if limit == 0 {
return DefaultSearchLimit, nil
}
if limit < 1 || limit > MaxSearchResults {
return 0, fmt.Errorf("limit must be between 1 and %d", MaxSearchResults)
}
return limit, nil
}
func parseCursor(cursor string) (int, error) {
if cursor == "" {
return 0, nil
}
offset, err := strconv.Atoi(cursor)
if err != nil || offset < 0 {
return 0, fmt.Errorf("cursor must be a non-negative offset")
}
return offset, nil
}
func cloneField(field FieldDescriptor) FieldDescriptor {
field.Aliases = append([]string(nil), field.Aliases...)
field.Dependencies = append([]string(nil), field.Dependencies...)
field.Schema = cloneJSONMap(field.Schema)
return field
}
func cloneJSONMap(source map[string]any) map[string]any {
if source == nil {
return nil
}
result := make(map[string]any, len(source))
for key, value := range source {
result[key] = cloneJSONValue(value)
}
return result
}
func cloneJSONValue(value any) any {
switch typed := value.(type) {
case map[string]any:
return cloneJSONMap(typed)
case []any:
result := make([]any, len(typed))
for index, item := range typed {
result[index] = cloneJSONValue(item)
}
return result
default:
return value
}
}
func cloneDomain(domain DomainDescriptor) DomainDescriptor {
fields := domain.Fields
domain.Fields = make([]FieldDescriptor, len(fields))
for i, field := range fields {
domain.Fields[i] = cloneField(field)
}
domain.Operations = append([]OperationDescriptor(nil), domain.Operations...)
return domain
}