diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 064da3a..843c112 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -15,6 +15,7 @@ contributor workflow and validation. | `examples/go-library/prepare` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and `Prepare`. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) | | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) | | `internal/backend` | Constructs each engine's immutable registry from the maintained built-in definitions and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) | +| `internal/catalog` | Strictly validates imported immutable maintained backend and profile catalog assets before runtime cutover. | [Catalog adapter](../../internal/catalog/catalog.go), [internal sources](sources.md#profiles-and-built-ins) | | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) | | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [endpoint invariant](../../internal/domain/endpoint.go) | | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) | diff --git a/docs/internal/sources.md b/docs/internal/sources.md index cdc4a69..0e4d2f3 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -65,6 +65,12 @@ inheritance. Configured consumer sources continue to use the lazy point lookup repositories described above; engine assembly still uses the embedded built-in catalog at this point. +`internal/catalog` validates the imported immutable OpenRouter and +Rakestrawhome asset modules as one private adapter boundary. It enforces their +manifest, layout, profile ownership, inheritance, and secret-safety rules +before returning raw catalog sources. The root engine continues to use the +embedded built-ins until runtime cutover. + The overlay repository consults the next repository only when the higher-precedence repository reports that a profile is absent. A reliably selected malformed profile stops fallback, while an unrelated malformed file diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 2760e3b..f098205 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -29,6 +29,8 @@ The implemented internal components consist of: constructs the default execution target; - `internal/filecatalog`, which discovers YAML files and provides source-path helpers for filesystem and `fs.FS` consumers; +- `internal/catalog`, which validates immutable external maintained-catalog + assets before they are eligible for engine assembly; - `internal/jsonvalue`, which validates and defensively copies JSON-compatible extra-parameter trees; - `internal/promptdef`, which loads and validates prompt definitions from diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1c616fb..bd9ff18 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -393,7 +393,7 @@ point-in-time semantics of consumer-configured profile sources. ## Stage 5: Add And Verify The Private Catalog Adapter -**Status:** Pending +**Status:** Complete ### Repository diff --git a/go.mod b/go.mod index 817da8d..658dae1 100644 --- a/go.mod +++ b/go.mod @@ -3,6 +3,8 @@ module gitea.maximumdirect.net/eric/promptkit go 1.25.5 require ( + gitea.maximumdirect.net/eric/promptkit-backend-openrouter v1.0.0 + gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome v1.0.0 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 gopkg.in/yaml.v3 v3.0.1 ) diff --git a/go.sum b/go.sum index 7e38d45..900e1c5 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,7 @@ +gitea.maximumdirect.net/eric/promptkit-backend-openrouter v1.0.0 h1:lc062euk2qseO//D762i3JaFyulDNML3eQQX7DkYTho= +gitea.maximumdirect.net/eric/promptkit-backend-openrouter v1.0.0/go.mod h1:AIa7kAu2mfrRQgcspe4L+DW51WqgnALQT60lqkEywJI= +gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome v1.0.0 h1:j9YY7wsTVjzke2kHH4YAzpU0oUpM+x+nXwl1IeS+2eg= +gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome v1.0.0/go.mod h1:4RNS+LILDg4JbS4Ts9Lwy1C92wauXJIbeQaalps4Koo= github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8= github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ= diff --git a/internal/backend/registry.go b/internal/backend/registry.go index a754b6e..59a0363 100644 --- a/internal/backend/registry.go +++ b/internal/backend/registry.go @@ -65,7 +65,7 @@ func NewRegistry(additions []domain.Backend) (*Registry, error) { return nil, fmt.Errorf("backend ID %q is already registered", definition.ID) } - normalized, err := normalizeBackend(definition) + normalized, err := NormalizeDefinition(definition) if err != nil { return nil, err } @@ -128,7 +128,8 @@ func (r *Registry) CapacityPolicies() map[string]domain.BackendCapacityPolicy { return policies } -func normalizeBackend(definition domain.Backend) (domain.Backend, error) { +// NormalizeDefinition validates and defensively copies one backend definition. +func NormalizeDefinition(definition domain.Backend) (domain.Backend, error) { endpoint, err := domain.NormalizeOpenAICompatibleBaseEndpoint(definition.Endpoint) if err != nil { return domain.Backend{}, fmt.Errorf("backend %q endpoint: %w", definition.ID, err) diff --git a/internal/catalog/catalog.go b/internal/catalog/catalog.go new file mode 100644 index 0000000..d26e04e --- /dev/null +++ b/internal/catalog/catalog.go @@ -0,0 +1,211 @@ +// Package catalog validates immutable maintained backend catalog assets. +package catalog + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "io/fs" + "path" + "strings" + + "gitea.maximumdirect.net/eric/promptkit/internal/backend" + "gitea.maximumdirect.net/eric/promptkit/internal/domain" + "gitea.maximumdirect.net/eric/promptkit/internal/profile" +) + +// Source identifies one immutable backend catalog asset tree. +type Source struct { + Name string + ExpectedBackendID string + FS fs.FS + Root string +} + +// Set is the validated maintained backend and raw profile catalog. +type Set struct { + Backends []domain.Backend + Profiles profile.Repository +} + +// Load validates and combines immutable catalog sources in source order. +func Load(sources ...Source) (Set, error) { + if len(sources) == 0 { + return Set{}, errors.New("at least one catalog source is required") + } + loaded := Set{Backends: make([]domain.Backend, 0, len(sources))} + names := map[string]bool{} + backendIDs := map[string]bool{} + profileIDs := map[string]bool{} + for _, source := range sources { + if err := validateSource(source, names); err != nil { + return Set{}, err + } + names[source.Name] = true + definition, err := loadBackend(source) + if err != nil { + return Set{}, err + } + if backendIDs[definition.ID] { + return Set{}, fmt.Errorf("catalog %s: duplicate backend ID %q", source.Name, definition.ID) + } + backendIDs[definition.ID] = true + repository, metadata, err := profile.LoadFSRepository(context.Background(), source.FS, path.Join(source.Root, "profiles")) + if err != nil { + return Set{}, fmt.Errorf("catalog %s: %w", source.Name, err) + } + if len(metadata) == 0 { + return Set{}, fmt.Errorf("catalog %s: profiles must not be empty", source.Name) + } + for _, entry := range metadata { + if profileIDs[entry.ID] { + return Set{}, fmt.Errorf("catalog %s: duplicate profile ID %q", source.Name, entry.ID) + } + if containsField(entry.ExplicitFields, "endpoint") || containsField(entry.ExplicitFields, "api_key_env") { + return Set{}, fmt.Errorf("catalog %s: %s contains connection metadata", source.Name, entry.Path) + } + value, err := repository.GetProfile(context.Background(), entry.ID) + if err != nil { + return Set{}, fmt.Errorf("catalog %s: %s: %w", source.Name, entry.Path, err) + } + if err := rejectSecretKeys(value.ExtraParams); err != nil { + return Set{}, fmt.Errorf("catalog %s: %s: prohibited extra parameter key", source.Name, entry.Path) + } + resolved, err := profile.NewResolvingRepository(repository).GetProfile(context.Background(), entry.ID) + if err != nil { + return Set{}, fmt.Errorf("catalog %s: %s: %w", source.Name, entry.Path, err) + } + if resolved.BackendID != definition.ID { + return Set{}, fmt.Errorf("catalog %s: %s selects backend %q", source.Name, entry.Path, resolved.BackendID) + } + profileIDs[entry.ID] = true + } + if loaded.Profiles == nil { + loaded.Profiles = repository + } else { + loaded.Profiles = profile.NewOverlayRepository(loaded.Profiles, repository) + } + loaded.Backends = append(loaded.Backends, definition) + } + return loaded, nil +} + +func validateSource(source Source, names map[string]bool) error { + if strings.TrimSpace(source.Name) == "" || source.Name != strings.TrimSpace(source.Name) { + return errors.New("catalog source name must not be blank") + } + if names[source.Name] { + return fmt.Errorf("duplicate catalog source name %q", source.Name) + } + if source.FS == nil { + return fmt.Errorf("catalog %s: filesystem is nil", source.Name) + } + if source.Root == "." || source.Root == "" || !fs.ValidPath(source.Root) { + return fmt.Errorf("catalog %s: asset root is invalid", source.Name) + } + if strings.TrimSpace(source.ExpectedBackendID) == "" { + return fmt.Errorf("catalog %s: expected backend ID is blank", source.Name) + } + return validateLayout(source) +} + +func validateLayout(source Source) error { + manifestPath := path.Join(source.Root, "backend.json") + profilesRoot := path.Join(source.Root, "profiles") + return fs.WalkDir(source.FS, source.Root, func(assetPath string, entry fs.DirEntry, err error) error { + if err != nil { + return err + } + if assetPath == source.Root || entry.IsDir() { + return nil + } + if assetPath == manifestPath || strings.HasPrefix(assetPath, profilesRoot+"/") && entry.Type().IsRegular() && strings.HasSuffix(assetPath, ".yml") { + return nil + } + return fmt.Errorf("catalog %s: invalid asset path %s", source.Name, assetPath) + }) +} + +func loadBackend(source Source) (domain.Backend, error) { + data, err := fs.ReadFile(source.FS, path.Join(source.Root, "backend.json")) + if err != nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: %w", source.Name, err) + } + type manifest struct { + SchemaVersion *int `json:"schema_version"` + ID *string `json:"id"` + Endpoint *string `json:"endpoint"` + APIKeyEnv *string `json:"api_key_env"` + ConcurrencyLimit *int `json:"concurrency_limit"` + QueueCapacity *int `json:"queue_capacity"` + ExtraParams json.RawMessage `json:"extra_params"` + } + decoder := json.NewDecoder(bytes.NewReader(data)) + decoder.DisallowUnknownFields() + var value manifest + if err := decoder.Decode(&value); err != nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: invalid manifest", source.Name) + } + var trailing any + if err := decoder.Decode(&trailing); !errors.Is(err, io.EOF) { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: invalid manifest", source.Name) + } + if value.SchemaVersion == nil || *value.SchemaVersion != 1 || value.ID == nil || value.Endpoint == nil || value.APIKeyEnv == nil || value.ConcurrencyLimit == nil || value.QueueCapacity == nil || value.ExtraParams == nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: required field is missing or unsupported", source.Name) + } + if *value.ID != source.ExpectedBackendID { + return domain.Backend{}, fmt.Errorf("catalog %s: backend ID does not match expected ID", source.Name) + } + var extraParams map[string]any + if string(value.ExtraParams) != "null" { + if err := json.Unmarshal(value.ExtraParams, &extraParams); err != nil || extraParams == nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: invalid extra parameters", source.Name) + } + } + if err := rejectSecretKeys(extraParams); err != nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: prohibited extra parameter key", source.Name) + } + normalized, err := backend.NormalizeDefinition(domain.Backend{ID: *value.ID, Endpoint: *value.Endpoint, APIKeyEnv: *value.APIKeyEnv, ExtraParams: extraParams, ConcurrencyLimit: *value.ConcurrencyLimit, QueueCapacity: *value.QueueCapacity, QueueCapacitySet: true}) + if err != nil { + return domain.Backend{}, fmt.Errorf("catalog %s: backend.json: %w", source.Name, err) + } + return normalized, nil +} + +func containsField(fields []string, target string) bool { + for _, field := range fields { + if field == target { + return true + } + } + return false +} + +func rejectSecretKeys(value map[string]any) error { + return rejectSecretValue(value) +} + +func rejectSecretValue(value any) error { + switch value := value.(type) { + case map[string]any: + for key, child := range value { + switch strings.ToLower(key) { + case "api_key", "apikey", "authorization", "credential", "credentials", "password", "secret", "token", "access_token": + return errors.New("prohibited key") + } + if err := rejectSecretValue(child); err != nil { + return err + } + } + case []any: + for _, child := range value { + if err := rejectSecretValue(child); err != nil { + return err + } + } + } + return nil +} diff --git a/internal/catalog/catalog_test.go b/internal/catalog/catalog_test.go new file mode 100644 index 0000000..78ecdc1 --- /dev/null +++ b/internal/catalog/catalog_test.go @@ -0,0 +1,100 @@ +package catalog + +import ( + "bytes" + "context" + "encoding/json" + "io/fs" + "os" + "path/filepath" + "sort" + "testing" + + openrouter "gitea.maximumdirect.net/eric/promptkit-backend-openrouter" + rakestrawhome "gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome" +) + +func TestLoadPublishedCatalogsMatchCompatibilityFixture(t *testing.T) { + loaded, err := Load( + Source{Name: "OpenRouter", ExpectedBackendID: "openrouter", FS: openrouter.FS(), Root: openrouter.Root}, + Source{Name: "Rakestrawhome", ExpectedBackendID: "rakestrawhome", FS: rakestrawhome.FS(), Root: rakestrawhome.Root}, + ) + if err != nil { + t.Fatalf("load published catalogs: %v", err) + } + expected := loadCompatibilityFixture(t) + actual := catalogValue(t, loaded, expected) + actualJSON, err := json.Marshal(actual) + if err != nil { + t.Fatalf("encode loaded catalogs: %v", err) + } + expectedJSON, err := json.Marshal(expected) + if err != nil { + t.Fatalf("encode compatibility fixture: %v", err) + } + if !bytes.Equal(actualJSON, expectedJSON) { + t.Fatalf("published catalogs differ from compatibility fixture: got %#v, want %#v", actual, expected) + } +} + +func TestLoadRejectsInvalidSources(t *testing.T) { + for name, sources := range map[string][]Source{ + "none": nil, + "blank name": {{Name: " ", ExpectedBackendID: "openrouter", FS: openrouter.FS(), Root: openrouter.Root}}, + "duplicate name": { + {Name: "same", ExpectedBackendID: "openrouter", FS: openrouter.FS(), Root: openrouter.Root}, + {Name: "same", ExpectedBackendID: "rakestrawhome", FS: rakestrawhome.FS(), Root: rakestrawhome.Root}, + }, + "nil filesystem": {{Name: "missing", ExpectedBackendID: "openrouter", Root: openrouter.Root}}, + } { + t.Run(name, func(t *testing.T) { + if _, err := Load(sources...); err == nil { + t.Fatal("expected error") + } + }) + } +} + +func loadCompatibilityFixture(t *testing.T) map[string]any { + t.Helper() + data, err := os.ReadFile(filepath.Join("..", "..", "testdata", "builtin-catalog-v1.json")) + if err != nil { + t.Fatalf("read fixture: %v", err) + } + var value map[string]any + if err := json.Unmarshal(data, &value); err != nil { + t.Fatalf("decode fixture: %v", err) + } + return value +} + +func catalogValue(t *testing.T, loaded Set, fixture map[string]any) map[string]any { + t.Helper() + backends := make([]any, 0, len(loaded.Backends)) + for _, backend := range loaded.Backends { + backends = append(backends, map[string]any{"id": backend.ID, "endpoint": backend.Endpoint, "api_key_env": backend.APIKeyEnv, "extra_params": interfaceValue(backend.ExtraParams), "concurrency_limit": backend.ConcurrencyLimit, "queue_capacity": backend.QueueCapacity, "queue_capacity_set": backend.QueueCapacitySet}) + } + sort.Slice(backends, func(left, right int) bool { + return backends[left].(map[string]any)["id"].(string) < backends[right].(map[string]any)["id"].(string) + }) + profiles := fixture["profiles"].([]any) + actualProfiles := make([]any, 0, len(profiles)) + for _, expected := range profiles { + id := expected.(map[string]any)["id"].(string) + profile, err := loaded.Profiles.GetProfile(context.Background(), id) + if err != nil { + t.Fatalf("load profile %q: %v", id, err) + } + actualProfiles = append(actualProfiles, map[string]any{"id": profile.ID, "base_profile": profile.BaseProfileID, "backend": profile.BackendID, "endpoint": profile.Endpoint, "model": profile.Model, "temperature": profile.Temperature, "max_tokens": profile.MaxTokens, "top_p": profile.TopP, "timeout_seconds": profile.TimeoutSeconds, "service_tier": profile.ServiceTier, "reasoning_effort": profile.ReasoningEffort, "api_key_env": profile.APIKeyEnv, "api_key_required": profile.APIKeyRequired, "extra_params": interfaceValue(profile.ExtraParams)}) + } + return map[string]any{"backends": backends, "profiles": actualProfiles} +} + +func interfaceValue(value map[string]any) any { + if value == nil { + return nil + } + return value +} + +var _ fs.FS = openrouter.FS()