From 6a965ecbd53dbe86ceabe885c207ae1b43a2b0c7 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 18 Sep 2026 19:53:56 +1000 Subject: [PATCH 1/3] docs(prds): design the service registry and revise the state store contract A service is already one Go type (config.ServiceConnection); what is duplicated is its name, across the struct fields in internal/config/services.go, the default branches in infrastructure/configuration/defaults.go, and every consumer's field access. The drift that permits is already in the tree: the two token resolvers are identical apart from their env var name, and gateway.Target is defaulted while state.Target is a startup error with nothing stating that asymmetry in one place. Key services by name and carry the asymmetry as registration data, so a new service is one RegisterService line rather than an edit in three layers. An empty target default means the operator must supply one, which replaces the required/defaulted split without a branch. The TOML shape is unchanged. state-store-contract.md section 10 mandated the opposite, so it is revised to rev. 2d in the same change rather than left contradicting the design; its own summary already described the seam as [services.]. Also records the open [chat.*] section naming question in the migration decision register, where it is blocked on a decision rather than on evidence. --- docs/architecture/migration-decisions.md | 16 ++++ docs/prds/service-registry.md | 101 +++++++++++++++++++++++ docs/prds/state-store-contract.md | 22 +++-- 3 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/prds/service-registry.md diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index 6c1e84825..43733161a 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -529,3 +529,19 @@ config DTO translation will land, so it unblocks the dissolution above. per area when the decisions are already dictated by `dependencies-and-contracts.md`. That is the ceremony pattern this project deliberately avoids. + +## OPEN — `[chat.*]` config section naming + +`configuration.md:160` already states the position: `ChatConfig` holds "separate +channel instance settings... there is no chat-wide settings owner". The config +section name has not followed, so a settings block named for a product surface +owns what the architecture calls channel state. + +Two candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The +second reads as a domain path, and no config section in this repo is currently +named after a domain package, so adopting it sets a precedent for every other +section rather than fixing one name. + +Blocked on a maintainer decision, not on evidence. This is a rename with an +operator-visible TOML break, so it should land with the `internal/config` +dissolution recorded above rather than on its own. diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md new file mode 100644 index 000000000..f62a957ba --- /dev/null +++ b/docs/prds/service-registry.md @@ -0,0 +1,101 @@ +# Service registry — one declaration per service + +**Status:** Design, pre-implementation. Supersedes `state-store-contract.md` §10's +`State ServiceConnection` struct-field instruction (revised to rev. 2d in the same change). + +## Problem + +A service is already one Go type, `config.ServiceConnection`. What is duplicated is its +**name**, in three layers: + +| Layer | Location | What is hard-coded | +|---|---|---| +| Declaration | `internal/config/services.go:4-14` | `Gateway` and `State` as struct fields | +| Defaulting | `internal/infrastructure/configuration/defaults.go:74-82` | three `if cfg.Services.X.Y == ""` branches | +| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go:80-81` | `cfg.Services.State` / `cfg.Services.Gateway` field access | + +Adding a service means editing all three. The drift this permits is already visible: +`stateStoreResolvedToken` (`state_store_client.go:17-23`) and `gatewayResolvedToken` +(`chat_service.go:20-26`) are byte-identical apart from the env var name, and +`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing +stating that asymmetry in one place. + +`resolveServiceListen(service, flagValue, configured)` (`listen.go:24-34`) is already +name-parameterised. It is the shape the rest should follow. + +## Decision + +**Key services by name, and carry per-service asymmetry as registration data.** + +### 1. Declaration collapses to a map + +```go +// internal/config/services.go +type Services map[string]ServiceConnection +``` + +`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile, +`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]` +decodes without a code edit, satisfying criterion 5. + +### 2. Registration is the single entry point + +```go +// internal/config/servicespec.go +func RegisterService(context, name, target, listen, tokenEnv string) +``` + +registered once per service, at package init in `internal/config`: + +```go +RegisterService("both", "gateway", "127.0.0.1:8585", "127.0.0.1:8585", "GATEWAY_TOKEN") +RegisterService("client", "state", "", "127.0.0.1:9090", "STATE_STORE_TOKEN") +``` + +Positional, five strings, as the story specifies. Each argument is data the current code +states in prose or in a branch: + +- `context` is `client`, `server`, or `both`, and decides which fields must resolve + non-empty. A `server` or `both` service must end with a `listen`; a `client` or `both` + service must end with a `target`. +- `target` is the **default**, and an empty default means the operator must supply one. + That single convention replaces the `state.target` required / `gateway.target` defaulted + asymmetry with no branch: `state` registers `""`, `gateway` registers an address. +- `listen` is the default listen address, feeding the existing + flag → `[services.].listen` → default precedence unchanged. +- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one. + +### 3. Defaulting and consumption become loops and lookups + +`applyDefaults` iterates the registry instead of naming services. Consumers read +`cfg.Services.Get("state")`, returning a `ServiceConnection` plus the spec, so +`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into +`Services.ResolvedToken(name, secrets)`. + +## Criteria satisfied + +1. Declared once, in the `RegisterService` call. +2. No second location can contradict it; the map has no per-service fields to disagree with. +3. Registration is the entry point, with the five fields a service has. +4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit. +5. The set of services is registry data, not a struct definition. + +## Scope and risk + +- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts + its own ratified authority. Its summary (`:7`) already says `[services.]`. +- A typo'd `[services.gatway]` currently fails to decode into a known field and is silently + ignored either way. The registry makes strict rejection of unregistered names possible, + but that is **not** in scope here; it would break criterion 5's open extensibility. +- Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go:82`, + `setup_test.go:278`, and others). They move to `Get`, mechanically. +- No wire contract, no RPC, and no persisted format is touched. The 42-RPC State Store + contract is unaffected. + +## Acceptance + +- Adding a third service is a one-line diff plus its consumer, proven by a test that + registers a throwaway service and asserts its defaults and token fallback resolve. +- `grep -rn 'Services\.\(State\|Gateway\)' --include='*.go'` returns nothing. +- The existing `services_test.go` default and precedence assertions pass unchanged in + behaviour, rewritten only to the new accessor. diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index b9ec56e97..f51cd95d3 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -1,6 +1,9 @@ # State Store — contract boundary & transport (ratification) -**Status:** Ratified (rev. 2c). Rev. 1 was marked *conditionally ratified*; the three +**Status:** Ratified (rev. 2d). Rev. 2d revises §10 only: the `State ServiceConnection` +struct-field instruction is withdrawn in favour of name-keyed services +(`docs/prds/service-registry.md`). The contract, its 42 RPCs, and the listener topology are +unchanged. Rev. 1 was marked *conditionally ratified*; the three reviewer conditions it raised are resolved (rev. 2), and the two third-pass findings are resolved here: (a) the stale Q3 migration wording in `service-decomposition.md` (`store.WorkflowStore`, `mode = "inproc" | "remote"`) now matches the ratified ownership split @@ -535,16 +538,17 @@ an explicit operator decision. **Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.** -- `internal/config/services.go` gains a `State ServiceConnection` field: +- **Revised (rev. 2d).** This section previously instructed that + `internal/config/services.go` gain a `State ServiceConnection` *struct field*. That + instruction is withdrawn: naming each service as a field is the duplication + `docs/prds/service-registry.md` removes, and this document's own summary (`:7`) already + describes the seam as `[services.]`. Services are keyed by name: ```go - type Services struct { - Gateway ServiceConnection `toml:"gateway" yaml:"gateway"` - State ServiceConnection `toml:"state" yaml:"state"` - } - type ServiceConnection struct { - Target string `toml:"target" yaml:"target"` - } + type Services map[string]ServiceConnection ``` + registered once via `RegisterService(context, name, target, listen, tokenEnv)`. The TOML + shape below is unchanged, so nothing else in this section is affected; read + `cfg.Services.Get("state")` wherever it says `cfg.Services.State`. - **Empty `Target` → local** `*store.Store` adapter (the default; State Store not yet extracted). **Set `Target` → dial gRPC** and use `*staterpc.Client`. This differs from the gateway, where `Target` is always defaulted to `127.0.0.1:8585` because the gateway is already From 5aedc28aae33051c3e1a3f23be788b27d35e135b Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 18 Sep 2026 23:32:21 +1000 Subject: [PATCH 2/3] feat(config): key services by name through a registry Services was a struct with one field per service, so each service's name was stated three times: the field, the loader's defaulting branch, and every consumer's field access. Adding one meant editing all three, and nothing stopped them disagreeing. The drift was already there: stateStoreResolvedToken and gatewayResolvedToken were identical apart from the env var each hard-coded. Services becomes map[string]ServiceConnection, and RegisterService declares a service once with the five fields it has. Everything that differs between services is now an argument rather than a branch elsewhere: an empty registered target means the operator must supply one, which is how services.state.target stays required while the gateway's is defaulted, and the registered token env var replaces the two copied resolvers with Services.ResolvedToken. Defaulting iterates the registry, so a new service needs no loader edit. Consumers read Services.Get(name). Keeping a typo'd section reported took explicit work. [services.gatway] used to land in toml.MetaData.Undecoded() because the struct had no such field; a map decodes any section, so it would have loaded silently and left the daemon dialing the default. unregisteredServiceKeys asks the registry which names are real, and the test for it fails with an empty UnknownKeys when that check is removed. The TOML shape is unchanged, so no deployment profile, config.example.toml or install.sh edit is needed. Refs: archie-core-u23g --- docs/prds/service-registry.md | 14 +- internal/app/archied/bootstrap.go | 10 +- internal/app/archied/chat_service.go | 18 +-- internal/app/archied/chat_service_test.go | 26 ++-- .../archied/chat_store_composition_test.go | 6 +- internal/app/archied/gateway.go | 4 +- internal/app/archied/setup_test.go | 2 +- internal/app/archied/state_store.go | 5 +- internal/app/archied/state_store_client.go | 19 +-- .../app/archied/state_store_client_test.go | 10 +- .../archied/state_store_regression_test.go | 2 +- internal/app/archieui/config.go | 4 +- internal/app/archieui/config_test.go | 2 +- internal/config/services.go | 61 +++++--- internal/config/services_test.go | 133 ++++++++++++++++++ internal/config/servicespec.go | 106 ++++++++++++++ internal/daemon/daemon_test.go | 2 +- .../infrastructure/configuration/defaults.go | 50 ++++--- .../infrastructure/configuration/loader.go | 19 ++- .../configuration/services_test.go | 98 ++++++++++++- .../configuration/validate_test.go | 2 +- 21 files changed, 478 insertions(+), 115 deletions(-) create mode 100644 internal/config/services_test.go create mode 100644 internal/config/servicespec.go diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md index f62a957ba..19d5dcd2b 100644 --- a/docs/prds/service-registry.md +++ b/docs/prds/service-registry.md @@ -3,6 +3,10 @@ **Status:** Design, pre-implementation. Supersedes `state-store-contract.md` §10's `State ServiceConnection` struct-field instruction (revised to rev. 2d in the same change). +**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited +below exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of +that branch: `RegisterService`'s `listen` argument has nothing to carry without it. + ## Problem A service is already one Go type, `config.ServiceConnection`. What is duplicated is its @@ -84,9 +88,13 @@ states in prose or in a branch: - `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts its own ratified authority. Its summary (`:7`) already says `[services.]`. -- A typo'd `[services.gatway]` currently fails to decode into a known field and is silently - ignored either way. The registry makes strict rejection of unregistered names possible, - but that is **not** in scope here; it would break criterion 5's open extensibility. +- A typo'd `[services.gatway]` is **reported today** (`UnknownKeys = [services.gatway, + services.gatway.target]`), because the struct form leaves it in `toml.MetaData.Undecoded()`. + A map decodes any section, so preserving that is a requirement, not an optional extra: + `unregisteredServiceKeys` asks the registry which names exist. This costs nothing in + extensibility, because the answer comes from registration data rather than a fixed list. + (An earlier draft of this document claimed the typo was silently ignored either way. It + was not; the behaviour was measured.) - Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go:82`, `setup_test.go:278`, and others). They move to `Get`, mechanically. - No wire contract, no RPC, and no persisted format is touched. The 42-RPC State Store diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index a0749444c..18af46638 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -345,18 +345,18 @@ func (b *boot) openStores(ctx context.Context) error { // the STATE_STORE_TOKEN secret (§10). It runs after openStores has resolved // b.secrets, and before setupObservability / buildDaemon wire consumers. func (b *boot) openStateStoreAdapter() error { - target := strings.TrimSpace(b.cfg.Services.State.Target) + target := strings.TrimSpace(b.cfg.Services.Get(config.ServiceNameState).Target) if target == "" { return fmt.Errorf("services.state.target is required: archied/archie-gateway no longer own archie.db; the standalone archie-state-store process owns it (docs/prds/state-store-contract.md §12 step 7)") } - client, cleanup, err := composeStateStoreClient(b.cfg.Services.State, b.secrets) + client, cleanup, err := composeStateStoreClient(b.cfg.Services, b.secrets) if err != nil { b.log.Error("state store adapter", "err", err) return err } b.stateStore = client b.stateStoreGrants = &staterpc.GrantIssuer{Client: client} - b.stateStoreToken = stateStoreResolvedToken(b.cfg.Services.State, b.secrets) + b.stateStoreToken = b.cfg.Services.ResolvedToken(config.ServiceNameState, b.secrets.Getenv) b.addCleanup(cleanup) return nil } @@ -578,7 +578,7 @@ func (b *boot) setupLLMAndChat() error { b.setupChatRuntime(cfg) b.setupEmbeddings(cfg, log) - contract, cleanup, err := composeChatContract(cfg.Services.Gateway, b.secrets) + contract, cleanup, err := composeChatContract(cfg.Services, b.secrets) if err != nil { return err } @@ -1356,7 +1356,7 @@ func (b *boot) buildDaemon() { b.d = &daemon.Daemon{ Cfg: b.cfgHolder, ConnectedNATS: daemon.NATSEndpoint{URL: b.natsURL, Token: b.natsToken}, - ConnectedStateStore: daemon.StateStoreEndpoint{URL: strings.TrimSpace(b.cfg.Services.State.Target), Token: b.stateStoreToken}, + ConnectedStateStore: daemon.StateStoreEndpoint{URL: strings.TrimSpace(b.cfg.Services.Get(config.ServiceNameState).Target), Token: b.stateStoreToken}, Store: b.stateStore, Bus: b.bus, Forge: b.forgeClient, diff --git a/internal/app/archied/chat_service.go b/internal/app/archied/chat_service.go index 85bb6d2ef..5b56b6eb7 100644 --- a/internal/app/archied/chat_service.go +++ b/internal/app/archied/chat_service.go @@ -12,32 +12,20 @@ import ( "github.com/samcharles93/archie-core/internal/secret" ) -// gatewayResolvedToken returns the Bearer [REDACTED] a Gateway client -// presents: the explicit [services.gateway].target_token key, then the -// GATEWAY_TOKEN secret/env. The server side (RunGateway) resolves the same -// value, so a distributed consumer and the gateway agree without sharing -// any other configuration. -func gatewayResolvedToken(settings config.ServiceConnection, secrets *secret.Registry) string { - token := settings.TargetToken - if token == "" { - token = secrets.Getenv("GATEWAY_TOKEN") - } - return token -} - // composeChatContract dials the standalone archie-gateway, the sole owner of // ChatContract, from the daemon's own configuration key. Token resolution is // the daemon's (it owns the config keys and the secret registry); the dial // itself and the fail-closed non-loopback rule belong to the transport, so // they come from gatewayrpc.Dial. -func composeChatContract(settings config.ServiceConnection, secrets *secret.Registry, options ...grpc.DialOption) (gateway.ChatContract, func(), error) { +func composeChatContract(services config.Services, secrets *secret.Registry, options ...grpc.DialOption) (gateway.ChatContract, func(), error) { + settings := services.Get(config.ServiceNameGateway) if strings.TrimSpace(settings.Target) == "" { return nil, nil, fmt.Errorf("services.gateway.target is required") } // Assigned through a typed variable rather than returned directly: a // direct forward would hand a failed dial's nil *Client back as a // non-nil ChatContract interface. - client, cleanup, err := gatewayrpc.Dial(settings.Target, gatewayResolvedToken(settings, secrets), options...) + client, cleanup, err := gatewayrpc.Dial(settings.Target, services.ResolvedToken(config.ServiceNameGateway, secrets.Getenv), options...) if err != nil { return nil, nil, err } diff --git a/internal/app/archied/chat_service_test.go b/internal/app/archied/chat_service_test.go index d4540341b..8bac5cdfd 100644 --- a/internal/app/archied/chat_service_test.go +++ b/internal/app/archied/chat_service_test.go @@ -19,10 +19,10 @@ import ( func TestComposeChatContractRejectsInvalidSettings(t *testing.T) { for _, tt := range []struct { name string - settings config.ServiceConnection + settings config.Services }{ - {name: "missing target", settings: config.ServiceConnection{}}, - {name: "blank target", settings: config.ServiceConnection{Target: " \t\n"}}, + {name: "missing target", settings: config.Services{}}, + {name: "blank target", settings: config.Services{config.ServiceNameGateway: {Target: " \t\n"}}}, } { t.Run(tt.name, func(t *testing.T) { chat, cleanup, err := composeChatContract(tt.settings, &secret.Registry{}) @@ -41,7 +41,7 @@ func TestComposeChatContractRejectsInvalidSettings(t *testing.T) { func TestComposeChatContractNonLoopbackFailsClosed(t *testing.T) { _, _, err := composeChatContract( - config.ServiceConnection{Target: "gateway.example.com:8585"}, + config.Services{config.ServiceNameGateway: {Target: "gateway.example.com:8585"}}, &secret.Registry{}, ) if err == nil { @@ -67,7 +67,7 @@ func TestComposeChatContractRemoteAndCleanup(t *testing.T) { }) chat, cleanup, err := composeChatContract( - config.ServiceConnection{Target: listener.Addr().String()}, + config.Services{config.ServiceNameGateway: {Target: listener.Addr().String()}}, &secret.Registry{}, ) if err != nil { @@ -95,18 +95,22 @@ func TestComposeChatContractRemoteAndCleanup(t *testing.T) { } } +// TestGatewayResolvedToken pins the daemon-side wiring rather than the +// precedence rule itself: config.Services.ResolvedToken owns the rule and is +// tested there, but only this level proves the gateway reads it through the +// secret registry and lands on the env var its registration names. func TestGatewayResolvedToken(t *testing.T) { - if got := gatewayResolvedToken(config.ServiceConnection{TargetToken: "file-token"}, &secret.Registry{}); got != "file-token" { + secrets := &secret.Registry{} + explicit := config.Services{config.ServiceNameGateway: {TargetToken: "file-token"}} + if got := explicit.ResolvedToken(config.ServiceNameGateway, secrets.Getenv); got != "file-token" { t.Fatalf("resolved token = %q, want file-token", got) } t.Setenv("GATEWAY_TOKEN", "environment-token") - if got := gatewayResolvedToken(config.ServiceConnection{}, &secret.Registry{}); got != "environment-token" { + empty := config.Services{config.ServiceNameGateway: {}} + if got := empty.ResolvedToken(config.ServiceNameGateway, secrets.Getenv); got != "environment-token" { t.Fatalf("resolved token = %q, want environment-token", got) } - if got := gatewayResolvedToken( - config.ServiceConnection{TargetToken: "file-token"}, - &secret.Registry{}, - ); got != "file-token" { + if got := explicit.ResolvedToken(config.ServiceNameGateway, secrets.Getenv); got != "file-token" { t.Fatalf("explicit target_token should win over the environment, got %q", got) } } diff --git a/internal/app/archied/chat_store_composition_test.go b/internal/app/archied/chat_store_composition_test.go index 28b358516..8165ff00f 100644 --- a/internal/app/archied/chat_store_composition_test.go +++ b/internal/app/archied/chat_store_composition_test.go @@ -11,8 +11,10 @@ import ( ) func TestRemoteChatCompositionPreservesChannelTurnLedger(t *testing.T) { - cfg := config.Config{DBPath: filepath.Join(t.TempDir(), "tasks.db")} - cfg.Services.Gateway.Target = "127.0.0.1:1" + cfg := config.Config{ + DBPath: filepath.Join(t.TempDir(), "tasks.db"), + Services: config.Services{config.ServiceNameGateway: {Target: "127.0.0.1:1"}}, + } st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state-store.db")) if err != nil { t.Fatal(err) diff --git a/internal/app/archied/gateway.go b/internal/app/archied/gateway.go index 03950d314..ba5101185 100644 --- a/internal/app/archied/gateway.go +++ b/internal/app/archied/gateway.go @@ -36,13 +36,13 @@ type GatewayOptions struct { // inventing a value -- resolveServiceListen explains why an empty address is an // error rather than a default. func gatewayListenAndToken(b *boot, options GatewayOptions) (listen, token string, err error) { - listen, err = resolveServiceListen("gateway", options.Listen, b.cfg.Services.Gateway.Listen) + listen, err = resolveServiceListen("gateway", options.Listen, b.cfg.Services.Get(config.ServiceNameGateway).Listen) if err != nil { return "", "", err } token = options.Token if token == "" { - token = gatewayResolvedToken(b.cfg.Services.Gateway, b.secrets) + token = b.cfg.Services.ResolvedToken(config.ServiceNameGateway, b.secrets.Getenv) } return listen, token, nil } diff --git a/internal/app/archied/setup_test.go b/internal/app/archied/setup_test.go index c3348e084..7e9e69e6f 100644 --- a/internal/app/archied/setup_test.go +++ b/internal/app/archied/setup_test.go @@ -275,7 +275,7 @@ func TestRunSetup_GeneratedConfigSatisfiesDaemonRequirements(t *testing.T) { } // openStateStoreAdapter refuses an empty target, so this is the difference // between a config that boots and one that does not. - if doc.Config.Services.State.Target == "" { + if doc.Config.Services.Get(config.ServiceNameState).Target == "" { t.Error("generated config leaves services.state.target empty; the daemon would not boot") } if doc.Config.BotUser == "" { diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 278a320a9..4602e9620 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -19,6 +19,7 @@ import ( "google.golang.org/grpc" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/health" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/readiness" @@ -56,7 +57,7 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { if err := b.loadConfig(ctx, options.Config, options.Overlay, false); err != nil { return err } - listen, err := resolveServiceListen("state", options.Listen, b.cfg.Services.State.Listen) + listen, err := resolveServiceListen("state", options.Listen, b.cfg.Services.Get(config.ServiceNameState).Listen) if err != nil { return err } @@ -67,7 +68,7 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { token := options.Token if token == "" { - token = stateStoreResolvedToken(b.cfg.Services.State, b.secrets) + token = b.cfg.Services.ResolvedToken(config.ServiceNameState, b.secrets.Getenv) } grants := &staterpc.TaskGrants{} //nolint:contextcheck // grpc.StreamServerInterceptor has no context.Context parameter; TaskGrants.StreamInterceptor derives its context from stream.Context() instead diff --git a/internal/app/archied/state_store_client.go b/internal/app/archied/state_store_client.go index 3e5c31694..61820b122 100644 --- a/internal/app/archied/state_store_client.go +++ b/internal/app/archied/state_store_client.go @@ -9,28 +9,15 @@ import ( "github.com/samcharles93/archie-core/internal/secret" ) -// stateStoreResolvedToken returns the bearer token a State Store client -// presents: the explicit [services.state].target_token key, then the -// STATE_STORE_TOKEN secret/env. The daemon injects the same token into agent -// containers as STATE_STORE_TOKEN so the agent authenticates to the same -// remote store the daemon dials. -func stateStoreResolvedToken(settings config.ServiceConnection, secrets *secret.Registry) string { - token := settings.TargetToken - if token == "" { - token = secrets.Getenv("STATE_STORE_TOKEN") - } - return token -} - // composeStateStoreClient dials the State Store gRPC service the daemon's own // capture/mapping/binding consumers call. Token resolution is the daemon's // (it owns the config keys and the secret registry); the dial itself and the // fail-closed non-loopback rule (§9) belong to the transport, so they come // from staterpc.Dial. -func composeStateStoreClient(settings config.ServiceConnection, secrets *secret.Registry) (*staterpc.Client, func(), error) { - target := strings.TrimSpace(settings.Target) +func composeStateStoreClient(services config.Services, secrets *secret.Registry) (*staterpc.Client, func(), error) { + target := strings.TrimSpace(services.Get(config.ServiceNameState).Target) if target == "" { return nil, nil, fmt.Errorf("services.state.target is required") } - return staterpc.Dial(target, stateStoreResolvedToken(settings, secrets)) + return staterpc.Dial(target, services.ResolvedToken(config.ServiceNameState, secrets.Getenv)) } diff --git a/internal/app/archied/state_store_client_test.go b/internal/app/archied/state_store_client_test.go index 780859524..5fabfd7e4 100644 --- a/internal/app/archied/state_store_client_test.go +++ b/internal/app/archied/state_store_client_test.go @@ -9,7 +9,7 @@ import ( ) func TestComposeStateStoreClientRequiresTarget(t *testing.T) { - _, _, err := composeStateStoreClient(config.ServiceConnection{}, &secret.Registry{}) + _, _, err := composeStateStoreClient(config.Services{}, &secret.Registry{}) if err == nil { t.Fatal("empty target should error") } @@ -29,7 +29,7 @@ func TestComposeStateStoreClientNonLoopbackFailsClosed(t *testing.T) { {name: "hostname without token", target: "store.example.com:9090"}, } { t.Run(tt.name, func(t *testing.T) { - _, _, err := composeStateStoreClient(config.ServiceConnection{Target: tt.target}, &secret.Registry{}) + _, _, err := composeStateStoreClient(config.Services{config.ServiceNameState: {Target: tt.target}}, &secret.Registry{}) if err == nil { t.Fatalf("non-loopback %q without a token should fail closed (docs/prds/state-store-contract.md §9)", tt.target) } @@ -38,7 +38,7 @@ func TestComposeStateStoreClientNonLoopbackFailsClosed(t *testing.T) { } func TestComposeStateStoreClientLoopbackSucceeds(t *testing.T) { - st, cleanup, err := composeStateStoreClient(config.ServiceConnection{Target: "127.0.0.1:9090"}, &secret.Registry{}) + st, cleanup, err := composeStateStoreClient(config.Services{config.ServiceNameState: {Target: "127.0.0.1:9090"}}, &secret.Registry{}) if err != nil { t.Fatalf("loopback without token should succeed: %v", err) } @@ -54,7 +54,7 @@ func TestComposeStateStoreClientLoopbackSucceeds(t *testing.T) { func TestComposeStateStoreClientTokenFromTargetToken(t *testing.T) { // Non-loopback with a configured token must not fail closed; the interceptor // is what carries it, so the client is dialable. - st, _, err := composeStateStoreClient(config.ServiceConnection{Target: "0.0.0.0:9090", TargetToken: "secret"}, &secret.Registry{}) + st, _, err := composeStateStoreClient(config.Services{config.ServiceNameState: {Target: "0.0.0.0:9090", TargetToken: "secret"}}, &secret.Registry{}) if err != nil { t.Fatalf("non-loopback with a token should succeed: %v", err) } @@ -79,7 +79,7 @@ func TestOpenStateStoreAdapterRemoteFailsClosed(t *testing.T) { t.Setenv("STATE_STORE_TOKEN", "") b := newBootstrap() b.secrets = &secret.Registry{} - b.cfg.Services.State = config.ServiceConnection{Target: "0.0.0.0:9090"} + b.cfg.Services = config.Services{config.ServiceNameState: {Target: "0.0.0.0:9090"}} if err := b.openStateStoreAdapter(); err == nil { t.Fatal("non-loopback without a token should fail closed") } diff --git a/internal/app/archied/state_store_regression_test.go b/internal/app/archied/state_store_regression_test.go index 6c5ae8005..7410709fc 100644 --- a/internal/app/archied/state_store_regression_test.go +++ b/internal/app/archied/state_store_regression_test.go @@ -44,7 +44,7 @@ func TestExternalServicesDoNotRequireBridgeNetwork(t *testing.T) { cfg := config.Config{} cfg.NATS.Mode = config.NATSModeExternal cfg.Containers.Network = "host" - cfg.Services.State.Target = "state.example.test:9090" + cfg.Services = config.Services{config.ServiceNameState: {Target: "state.example.test:9090"}} pool, _, cleanup := startContainers(t.Context(), cfg, slog.New(slog.DiscardHandler)) defer cleanup() if pool == nil { diff --git a/internal/app/archieui/config.go b/internal/app/archieui/config.go index 343b7a5d4..bd4776755 100644 --- a/internal/app/archieui/config.go +++ b/internal/app/archieui/config.go @@ -77,8 +77,8 @@ func project(cfg config.Config) projection { return projection{ listen: cfg.Web.Listen, trustForwardedHeaders: cfg.Web.TrustForwardedHeaders, - gateway: ServiceTarget{Target: cfg.Services.Gateway.Target, Token: cfg.Services.Gateway.TargetToken}, - state: ServiceTarget{Target: cfg.Services.State.Target, Token: cfg.Services.State.TargetToken}, + gateway: ServiceTarget{Target: cfg.Services.Get(config.ServiceNameGateway).Target, Token: cfg.Services.Get(config.ServiceNameGateway).TargetToken}, + state: ServiceTarget{Target: cfg.Services.Get(config.ServiceNameState).Target, Token: cfg.Services.Get(config.ServiceNameState).TargetToken}, capture: CaptureOptions{ Retention: cfg.Capture.Retention.Std(), MaxEvents: cfg.Capture.MaxEvents, diff --git a/internal/app/archieui/config_test.go b/internal/app/archieui/config_test.go index c70dc1bf6..5c495530a 100644 --- a/internal/app/archieui/config_test.go +++ b/internal/app/archieui/config_test.go @@ -47,7 +47,7 @@ target_token = "state-token" // TestResolveReadsOnlyTheAllowlistedConfigProjection pins the maintainer's // decision for this bead: the UI process does read config.toml, but only -// Services.Gateway.{Target,TargetToken}, Services.State.{Target,TargetToken} +// Services.Get("gateway").{Target,TargetToken} and the same for "state" // and Web.{Listen,TrustForwardedHeaders}. Options has no field that could // carry anything else, so this asserts the six values arrive and the daemon's // own settings have nowhere to land. diff --git a/internal/config/services.go b/internal/config/services.go index 071ec5352..c8d753d26 100644 --- a/internal/config/services.go +++ b/internal/config/services.go @@ -1,30 +1,53 @@ package config -// Services selects contract adapters at application composition time. -type Services struct { - Gateway ServiceConnection `toml:"gateway" yaml:"gateway"` - // State selects the State Store contract adapter. The State Store is its - // own process (cmd/archie-state-store) and owns archie.db; an empty Target - // is a startup error in archied/archie-gateway, which no longer serve a - // local store (docs/prds/state-store-contract.md §12 step 7). The daemon - // and agent dial the remote StateStoreService and present target_token - // when the target is non-loopback. Token resolution mirrors the daemon's: - // the explicit key, then the STATE_STORE_TOKEN secret/env var. - State ServiceConnection `toml:"state" yaml:"state"` +// Services maps a registered service name to its connection settings, keyed by +// the [services.] section it was decoded from. +// +// It was a struct with one field per service. That stated each service's name +// three times over -- here, in the loader's defaulting branches, and at every +// consumer's field access -- so a new service meant editing all three and +// nothing prevented them disagreeing. Which names are legitimate now comes +// from RegisterService; see ServiceSpec. +type Services map[string]ServiceConnection + +// Get returns the connection configured for name, or the zero value when the +// configuration carries no section for it. A registered service always has an +// entry once defaults have been applied. +func (s Services) Get(name string) ServiceConnection { + return s[name] } -// ServiceConnection is a contract adapter's gRPC address plus the bearer -// token a client presents when the target is non-loopback. A client reads only -// Target and TargetToken; Listen belongs to the process that owns the service. -// The struct does not itself register services or start listeners. Changes -// require a daemon restart. +// ResolvedToken is the bearer token a client presents when dialling name: the +// explicit target_token if set, otherwise the environment variable the service +// registered. getenv is passed in rather than read directly so this stays free +// of internal/secret, which imports this package. +// +// This replaces two resolvers that were identical apart from the variable name +// each hard-coded. +func (s Services) ResolvedToken(name string, getenv func(string) string) string { + if token := s[name].TargetToken; token != "" { + return token + } + spec, ok := LookupService(name) + if !ok || spec.TokenEnv == "" { + return "" + } + return getenv(spec.TokenEnv) +} + +// ServiceConnection is a service's gRPC addresses plus the bearer token a +// client presents when the target is non-loopback. A client reads only Target +// and TargetToken; Listen belongs to the process that owns the service. The +// struct does not itself register services or start listeners. Changes require +// a daemon restart. type ServiceConnection struct { Target string `toml:"target" yaml:"target"` // Listen is the address the process that OWNS this service binds // (archie-state-store, archie-gateway). It is read only by that process; - // every client ignores it. Defaulted, so a loaded config is never empty - // here -- an empty address reaches net.Listen as "any free port", which - // would silently move the service off the address its clients dial. + // every client ignores it. Defaulted from the service's registration, so + // a loaded config is never empty here -- an empty address reaches + // net.Listen as "any free port", which would silently move the service + // off the address its clients dial. Listen string `toml:"listen" yaml:"listen"` // TargetToken is the bearer token a client (daemon or agent) presents // when dialing a non-loopback service target, and the standalone diff --git a/internal/config/services_test.go b/internal/config/services_test.go new file mode 100644 index 000000000..9cf877f0a --- /dev/null +++ b/internal/config/services_test.go @@ -0,0 +1,133 @@ +package config_test + +import ( + "testing" + + "github.com/samcharles93/archie-core/internal/config" +) + +// TestRegisterServiceIsTheSingleDeclaration pins criterion 3 of +// docs/prds/service-registry.md: a service is declared by one call carrying the +// five fields it actually has, and every later layer reads that declaration +// rather than restating the name. +func TestRegisterServiceIsTheSingleDeclaration(t *testing.T) { + config.RegisterService(config.ServiceBoth, "widget", "127.0.0.1:7001", "127.0.0.1:7002", "WIDGET_TOKEN") + + spec, ok := config.LookupService("widget") + if !ok { + t.Fatal("LookupService(widget) = false, want the service just registered") + } + if spec.Context != config.ServiceBoth { + t.Errorf("Context = %q, want %q", spec.Context, config.ServiceBoth) + } + if spec.Target != "127.0.0.1:7001" { + t.Errorf("Target = %q, want the registered default", spec.Target) + } + if spec.Listen != "127.0.0.1:7002" { + t.Errorf("Listen = %q, want the registered default", spec.Listen) + } + if spec.TokenEnv != "WIDGET_TOKEN" { + t.Errorf("TokenEnv = %q, want the registered env var", spec.TokenEnv) + } +} + +// TestBuiltInServicesAreRegistered pins that the two services the daemon ships +// are declared through the same entry point as any other, with the asymmetry +// the old struct form left unstated: state has no default target, so the +// operator must supply one, while gateway does. +func TestBuiltInServicesAreRegistered(t *testing.T) { + state, ok := config.LookupService("state") + if !ok { + t.Fatal("LookupService(state) = false, want the State Store registered") + } + if state.Target != "" { + t.Errorf("state Target default = %q, want empty: services.state.target is operator-supplied", state.Target) + } + if state.Listen == "" { + t.Error("state Listen default is empty, want an address: an empty listen reaches net.Listen as any free port") + } + if state.TokenEnv != "STATE_STORE_TOKEN" { + t.Errorf("state TokenEnv = %q, want STATE_STORE_TOKEN", state.TokenEnv) + } + + gateway, ok := config.LookupService("gateway") + if !ok { + t.Fatal("LookupService(gateway) = false, want the Gateway registered") + } + if gateway.Target == "" { + t.Error("gateway Target default is empty, want an address: the gateway target is defaulted, not operator-supplied") + } + if gateway.TokenEnv != "GATEWAY_TOKEN" { + t.Errorf("gateway TokenEnv = %q, want GATEWAY_TOKEN", gateway.TokenEnv) + } +} + +// TestUnregisteredServiceIsNotFound keeps the registry the authority on which +// names exist, which is what lets the loader report a typo'd [services.gatway] +// as an unknown key once Services is a map that would otherwise swallow it. +func TestUnregisteredServiceIsNotFound(t *testing.T) { + if _, ok := config.LookupService("gatway"); ok { + t.Error("LookupService(gatway) = true, want false for an unregistered name") + } +} + +// TestServicesGetReturnsTheNamedConnection pins lookup by name, which replaced +// per-service struct field access, so adding a service needs no new field. +func TestServicesGetReturnsTheNamedConnection(t *testing.T) { + services := config.Services{ + "state": {Target: "10.0.0.1:9090", Listen: "0.0.0.0:9090", TargetToken: "explicit"}, + } + got := services.Get("state") + if got.Target != "10.0.0.1:9090" { + t.Errorf("Get(state).Target = %q, want the configured target", got.Target) + } + if services.Get("absent") != (config.ServiceConnection{}) { + t.Error("Get(absent) returned a non-zero connection, want the zero value") + } +} + +// TestResolvedTokenPrefersTheExplicitKey pins the precedence the two +// hand-copied resolvers used: the config key wins, and the registered env var +// is only a fallback. +func TestResolvedTokenPrefersTheExplicitKey(t *testing.T) { + config.RegisterService(config.ServiceClient, "widget-explicit", "", "127.0.0.1:7003", "WIDGET_EXPLICIT_TOKEN") + services := config.Services{"widget-explicit": {TargetToken: "from-config"}} + + getenv := func(string) string { return "from-env" } + if got := services.ResolvedToken("widget-explicit", getenv); got != "from-config" { + t.Errorf("ResolvedToken = %q, want the explicit target_token to win", got) + } +} + +// TestResolvedTokenFallsBackToTheRegisteredEnvVar is the half that the old +// stateStoreResolvedToken and gatewayResolvedToken duplicated, differing only +// in the env var name they hard-coded. +func TestResolvedTokenFallsBackToTheRegisteredEnvVar(t *testing.T) { + config.RegisterService(config.ServiceClient, "widget-env", "", "127.0.0.1:7004", "WIDGET_ENV_TOKEN") + services := config.Services{"widget-env": {}} + + var asked string + getenv := func(name string) string { + asked = name + return "from-env" + } + if got := services.ResolvedToken("widget-env", getenv); got != "from-env" { + t.Errorf("ResolvedToken = %q, want the env fallback", got) + } + if asked != "WIDGET_ENV_TOKEN" { + t.Errorf("read env var %q, want the name from the registration", asked) + } +} + +// TestResolvedTokenOfUnregisteredServiceHasNoEnvFallback keeps an unknown name +// from reaching os.Getenv("") and returning something surprising. +func TestResolvedTokenOfUnregisteredServiceHasNoEnvFallback(t *testing.T) { + services := config.Services{"gatway": {}} + getenv := func(string) string { + t.Error("getenv called for an unregistered service, want no env fallback") + return "leaked" + } + if got := services.ResolvedToken("gatway", getenv); got != "" { + t.Errorf("ResolvedToken = %q, want empty", got) + } +} diff --git a/internal/config/servicespec.go b/internal/config/servicespec.go new file mode 100644 index 000000000..0b6816458 --- /dev/null +++ b/internal/config/servicespec.go @@ -0,0 +1,106 @@ +package config + +import ( + "sort" + "sync" +) + +// Service contexts. The context decides which addresses a service must end up +// with: a process that owns a service needs a listen address, and a process +// that dials one needs a target. +const ( + // ServiceClient is dialled but not hosted by this repository. + ServiceClient = "client" + // ServiceServer is hosted but not dialled. + ServiceServer = "server" + // ServiceBoth is hosted by one of our processes and dialled by others. + ServiceBoth = "both" +) + +// ServiceSpec is everything the codebase knows about one service that is not +// operator input. It exists so a service is declared once: the name, its +// defaults, and the environment variable its token falls back to were +// previously a struct field, a defaulting branch, and a hand-copied resolver +// in three separate packages, with nothing keeping them in step. +type ServiceSpec struct { + // Context is ServiceClient, ServiceServer, or ServiceBoth. + Context string + // Name is the [services.] section and the key callers look up. + Name string + // Target is the default dial address. Empty means there is no default + // and the operator must supply one, which is how "services.state.target + // is required" is stated without a branch that names the service. + Target string + // Listen is the default bind address for the process that owns the + // service. It is never empty for a hosted service: an empty address + // reaches net.Listen as "any free port", silently moving the service + // off the address its clients dial. + Listen string + // TokenEnv names the environment variable a client falls back to when + // [services.].target_token is empty. + TokenEnv string +} + +// Registered service names. They live beside the registrations below so the +// spelling a consumer looks up and the spelling that was registered are the +// same token, not two string literals that a typo can separate. +const ( + ServiceNameGateway = "gateway" + ServiceNameState = "state" +) + +var ( + serviceRegistryMu sync.RWMutex + serviceRegistry = map[string]ServiceSpec{} +) + +// RegisterService declares one service. It is the single entry point the +// design calls for: adding a service is this call plus its consumer, with no +// new struct field, defaulting branch, or accessor anywhere else. +// +// Re-registering a name replaces the previous spec, so a test can install a +// throwaway service without disturbing the built-ins. +func RegisterService(context, name, target, listen, tokenEnv string) { + serviceRegistryMu.Lock() + defer serviceRegistryMu.Unlock() + serviceRegistry[name] = ServiceSpec{ + Context: context, + Name: name, + Target: target, + Listen: listen, + TokenEnv: tokenEnv, + } +} + +// LookupService returns the spec registered for name. The registry is the +// authority on which service names exist, which is what lets the loader still +// report a typo'd [services.gatway] once Services is a map that would +// otherwise decode any section at all. +func LookupService(name string) (ServiceSpec, bool) { + serviceRegistryMu.RLock() + defer serviceRegistryMu.RUnlock() + spec, ok := serviceRegistry[name] + return spec, ok +} + +// RegisteredServices returns every spec, ordered by name so defaulting and +// validation run in a stable order regardless of map iteration. +func RegisteredServices() []ServiceSpec { + serviceRegistryMu.RLock() + defer serviceRegistryMu.RUnlock() + out := make([]ServiceSpec, 0, len(serviceRegistry)) + for _, spec := range serviceRegistry { + out = append(out, spec) + } + sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) + return out +} + +func init() { + // The two services this repository ships. Everything that differs + // between them is an argument here, not a branch somewhere else: the + // gateway's target is defaulted while the State Store's is supplied by + // the operator, and each falls back to its own token variable. + RegisterService(ServiceBoth, ServiceNameGateway, "127.0.0.1:8585", "127.0.0.1:8585", "GATEWAY_TOKEN") + RegisterService(ServiceClient, ServiceNameState, "", "127.0.0.1:9090", "STATE_STORE_TOKEN") +} diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 0d1ced73b..a97719212 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -1666,7 +1666,7 @@ func configWithCanarySecrets() config.Config { Tools: config.ToolsConfig{Policy: config.ToolPolicy{MaxResultChars: 12000, SpillDir: "/tmp/spill"}}, NATS: config.NATSConfig{Mode: "external", URL: "nats://127.0.0.1:4222", TokenEnv: canaryNATSTokenEnv}, Chat: config.ChatConfig{Operator: "sam", Telegram: config.TelegramConfig{TokenEnv: "TELEGRAM_TOKEN", Token: secret.SecretRef{Engine: "bws", Key: canaryTelegramToken}}}, - Services: config.Services{State: config.ServiceConnection{Target: "127.0.0.1:50051", TargetToken: canaryStateStoreToken}}, + Services: config.Services{config.ServiceNameState: {Target: "127.0.0.1:50051", TargetToken: canaryStateStoreToken}}, ModelLimits: map[string]config.ModelLimits{ "openai/gpt-4": {ContextWindow: 128000, MaxOutputTokens: 4096}, }, diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index 6d06a43d7..a60cd2512 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -12,18 +12,9 @@ import ( // Defaults applied to absent input. Named so a reader can find the value // without reading the code that applies it. const ( - defaultPollInterval = 60 * time.Second - defaultDiffCapLines = 400 - defaultWebListen = "127.0.0.1:8484" // "off" disables - // defaultGatewayAddr is where archie-gateway binds and, by default, where - // clients look for it. One constant for both so a default deployment's - // client and server cannot drift onto different ports. - defaultGatewayAddr = "127.0.0.1:8585" - // defaultStateListen is the state store's bind address. There is - // deliberately no default for [services.state].target: an empty target is - // a startup error in the daemon and the gateway, which no longer serve a - // local store (docs/prds/state-store-contract.md). - defaultStateListen = "127.0.0.1:9090" + defaultPollInterval = 60 * time.Second + defaultDiffCapLines = 400 + defaultWebListen = "127.0.0.1:8484" // "off" disables defaultMaxRetries = 3 defaultForgeType = "github" defaultForgeHost = "https://github.com" @@ -71,15 +62,7 @@ const ( // input was to not call them. Splitting them means defaults can be applied, // inspected, and reasoned about independently of whether the result is valid. func (l *Loader) applyDefaults(cfg *config.Config) { - if cfg.Services.Gateway.Target == "" { - cfg.Services.Gateway.Target = defaultGatewayAddr - } - if cfg.Services.Gateway.Listen == "" { - cfg.Services.Gateway.Listen = defaultGatewayAddr - } - if cfg.Services.State.Listen == "" { - cfg.Services.State.Listen = defaultStateListen - } + applyServiceDefaults(cfg) if cfg.Health.Listen == "" { cfg.Health.Listen = defaultHealthListen } @@ -94,6 +77,31 @@ func (l *Loader) applyDefaults(cfg *config.Config) { applyMemoryDefaults(cfg) } +// applyServiceDefaults fills each registered service's absent addresses from +// its registration. It iterates the registry rather than naming services, so a +// new service needs no branch here -- only its RegisterService call. +// +// A registered service always ends with an entry, so later code can read +// cfg.Services.Get(name) without distinguishing "absent section" from +// "section with every field defaulted". An empty registered Target is a +// service whose target the operator must supply, and stays empty for +// validation to reject rather than being defaulted to something dialable. +func applyServiceDefaults(cfg *config.Config) { + if cfg.Services == nil { + cfg.Services = config.Services{} + } + for _, spec := range config.RegisteredServices() { + conn := cfg.Services[spec.Name] + if conn.Target == "" { + conn.Target = spec.Target + } + if conn.Listen == "" { + conn.Listen = spec.Listen + } + cfg.Services[spec.Name] = conn + } +} + // applyMemoryDefaults fills an absent engine choice with the builtin // engine, so "nothing configured" and "explicitly builtin" are the same // resolved state everywhere after this point -- validateMemory and every diff --git a/internal/infrastructure/configuration/loader.go b/internal/infrastructure/configuration/loader.go index 2ad08f4cb..d64e52fb5 100644 --- a/internal/infrastructure/configuration/loader.go +++ b/internal/infrastructure/configuration/loader.go @@ -210,6 +210,23 @@ func unknownKeys(a, b []string) []string { return out } +// unregisteredServiceKeys reports [services.] sections naming a service +// nobody registered. +// +// Undecoded() cannot see these. Services is a map, so TOML decodes any section +// under [services] into it successfully, and a typo'd [services.gatway] would +// load clean where the previous struct form reported it. The registry is the +// authority on which names exist, so ask it. +func unregisteredServiceKeys(services config.Services) []string { + var out []string + for name := range services { + if _, ok := config.LookupService(name); !ok { + out = append(out, "services."+name) + } + } + return out +} + // sortedUnique returns keys sorted and de-duplicated, so Document.UnknownKeys // is deterministic across a base+overlay load that happens to name the same // stray key in both files. @@ -322,7 +339,7 @@ func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool) error { // judges the effective configuration, including values the operator never // wrote. func (l *Loader) finalize(doc *Document) (*Document, error) { - doc.UnknownKeys = sortedUnique(doc.UnknownKeys) + doc.UnknownKeys = sortedUnique(append(doc.UnknownKeys, unregisteredServiceKeys(doc.Config.Services)...)) l.applyDefaults(&doc.Config) if err := Validate(&doc.Config); err != nil { return nil, err diff --git a/internal/infrastructure/configuration/services_test.go b/internal/infrastructure/configuration/services_test.go index 7b75ebeda..b4896d045 100644 --- a/internal/infrastructure/configuration/services_test.go +++ b/internal/infrastructure/configuration/services_test.go @@ -3,7 +3,11 @@ package configuration import ( "os" "path/filepath" + "slices" + "strings" "testing" + + "github.com/samcharles93/archie-core/internal/config" ) func TestLoadGatewayServiceTarget(t *testing.T) { @@ -22,8 +26,8 @@ func TestLoadGatewayServiceTarget(t *testing.T) { if err != nil { t.Fatal(err) } - if cfg.Services.Gateway.Target != tt.wantTarget { - t.Fatalf("target = %q, want %q", cfg.Services.Gateway.Target, tt.wantTarget) + if cfg.Services.Get(config.ServiceNameGateway).Target != tt.wantTarget { + t.Fatalf("target = %q, want %q", cfg.Services.Get(config.ServiceNameGateway).Target, tt.wantTarget) } }) } @@ -61,11 +65,11 @@ func TestLoadServiceListens(t *testing.T) { if err != nil { t.Fatal(err) } - if cfg.Services.State.Listen != tt.wantState { - t.Fatalf("state listen = %q, want %q", cfg.Services.State.Listen, tt.wantState) + if cfg.Services.Get(config.ServiceNameState).Listen != tt.wantState { + t.Fatalf("state listen = %q, want %q", cfg.Services.Get(config.ServiceNameState).Listen, tt.wantState) } - if cfg.Services.Gateway.Listen != tt.wantGateway { - t.Fatalf("gateway listen = %q, want %q", cfg.Services.Gateway.Listen, tt.wantGateway) + if cfg.Services.Get(config.ServiceNameGateway).Listen != tt.wantGateway { + t.Fatalf("gateway listen = %q, want %q", cfg.Services.Get(config.ServiceNameGateway).Listen, tt.wantGateway) } }) } @@ -98,3 +102,85 @@ func TestLoadHealthListen(t *testing.T) { }) } } + +// TestRegisteredServiceDefaultsNeedNoLoaderEdit pins criterion 4 of +// docs/prds/service-registry.md. A service registered anywhere gets its +// defaults applied here without this package naming it, which is the whole +// point of iterating the registry instead of writing one branch per service. +func TestRegisteredServiceDefaultsNeedNoLoaderEdit(t *testing.T) { + config.RegisterService(config.ServiceBoth, "loadertest", "127.0.0.1:7101", "127.0.0.1:7102", "LOADERTEST_TOKEN") + + path := filepath.Join(t.TempDir(), "config.toml") + if err := os.WriteFile(path, []byte("bot_user = 'widget'\n"), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + if err != nil { + t.Fatal(err) + } + got := cfg.Services.Get("loadertest") + if got.Target != "127.0.0.1:7101" { + t.Errorf("target = %q, want the registered default", got.Target) + } + if got.Listen != "127.0.0.1:7102" { + t.Errorf("listen = %q, want the registered default", got.Listen) + } +} + +// TestStateTargetIsNotDefaulted keeps the asymmetry the registry now carries as +// data: the gateway's target is defaulted, the State Store's is operator +// input, and defaulting it to something dialable would turn a missing +// required value into a connection attempt against the wrong host. +func TestStateTargetIsNotDefaulted(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + if err := os.WriteFile(path, []byte("bot_user = 'widget'\n"), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + if err != nil { + t.Fatal(err) + } + if got := cfg.Services.Get(config.ServiceNameState).Target; got != "" { + t.Errorf("state target = %q, want empty", got) + } +} + +// TestUnregisteredServiceSectionIsReported is the regression this change had to +// avoid introducing. Services was a struct, so [services.gatway] landed in +// Undecoded() and was reported. As a map it decodes cleanly, so without the +// registry check a typo'd service section would load silently and the daemon +// would dial the default instead. +func TestUnregisteredServiceSectionIsReported(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + src := minimalValidConfigTOML + "[services.gatway]\ntarget = '127.0.0.1:1'\n" + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + doc, err := New(nil).File(path) + if err != nil { + t.Fatalf("File: %v (an unknown key must not fail the load)", err) + } + if !slices.Contains(doc.UnknownKeys, "services.gatway") { + t.Errorf("UnknownKeys = %v, want it to contain %q", doc.UnknownKeys, "services.gatway") + } +} + +// TestRegisteredServiceSectionIsNotReported is the other half: a real service +// section must not be flagged just because the map would accept anything. +func TestRegisteredServiceSectionIsNotReported(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + src := minimalValidConfigTOML + "[services.state]\ntarget = '127.0.0.1:9090'\n" + if err := os.WriteFile(path, []byte(src), 0o600); err != nil { + t.Fatal(err) + } + doc, err := New(nil).File(path) + if err != nil { + t.Fatal(err) + } + for _, k := range doc.UnknownKeys { + if strings.HasPrefix(k, "services.") { + t.Errorf("UnknownKeys = %v, want no services.* entry for a registered service", doc.UnknownKeys) + break + } + } +} diff --git a/internal/infrastructure/configuration/validate_test.go b/internal/infrastructure/configuration/validate_test.go index 993e71dd9..79b4972d8 100644 --- a/internal/infrastructure/configuration/validate_test.go +++ b/internal/infrastructure/configuration/validate_test.go @@ -27,7 +27,7 @@ func minimalValidConfig() config.Config { Image: "ghcr.io/samcharles93/archie-agent:latest", }, Services: config.Services{ - Gateway: config.ServiceConnection{Target: "127.0.0.1:8585"}, + config.ServiceNameGateway: {Target: "127.0.0.1:8585"}, }, } } From 42bfd3551452c49d2e222e26577657172d0ded8d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 19 Sep 2026 01:50:25 +1000 Subject: [PATCH 3/3] fix(config): enforce the service context at registration ServiceSpec.Context documented which addresses a service must end up with, but nothing read it, so a typo'd context was accepted and meant nothing. Review caught it as scaffolding that looked load-bearing. RegisterService now validates it: an unknown context, or a hosted (server/both) service registered with no default listen address, panics. Registrations come from this repository's own init(), never from operator input, so an invalid one is a programming error with no caller positioned to handle an error return, and failing at process start beats a service binding where nobody dials. Services.RequireTarget replaces the same check and message hand-written in composeStateStoreClient and composeChatContract. An empty registered default target is what declares a target operator-supplied, so the requirement belongs to the registry rather than to each consumer. It stays a lazy check at composition time rather than becoming load-time validation: a process that never dials a service must still load a configuration that omits it. The review's stated failure mode does not occur. A hosted service with an empty listen does not reach net.Listen as an ephemeral port; resolveServiceListen returns "no listen address" and archied refuses to start. The defect was the inert field, not a silent bind. Refs: archie-core-u23g --- docs/prds/service-registry.md | 7 +- internal/app/archied/chat_service.go | 11 +-- internal/app/archied/state_store_client.go | 9 +-- internal/config/services.go | 21 +++++ internal/config/services_test.go | 92 ++++++++++++++++++++++ internal/config/servicespec.go | 24 ++++++ 6 files changed, 149 insertions(+), 15 deletions(-) diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md index 19d5dcd2b..6afe622fc 100644 --- a/docs/prds/service-registry.md +++ b/docs/prds/service-registry.md @@ -60,8 +60,11 @@ Positional, five strings, as the story specifies. Each argument is data the curr states in prose or in a branch: - `context` is `client`, `server`, or `both`, and decides which fields must resolve - non-empty. A `server` or `both` service must end with a `listen`; a `client` or `both` - service must end with a `target`. + non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with + no default `listen`, panics at registration. Registrations come from this repository's + own `init()`, never from operator input, so an invalid one is a programming error with + no caller positioned to handle an error return. A documented-but-unread `Context` would + be worse than no field at all. - `target` is the **default**, and an empty default means the operator must supply one. That single convention replaces the `state.target` required / `gateway.target` defaulted asymmetry with no branch: `state` registers `""`, `gateway` registers an address. diff --git a/internal/app/archied/chat_service.go b/internal/app/archied/chat_service.go index 5b56b6eb7..0fd194303 100644 --- a/internal/app/archied/chat_service.go +++ b/internal/app/archied/chat_service.go @@ -1,9 +1,6 @@ package archied import ( - "fmt" - "strings" - "google.golang.org/grpc" "github.com/samcharles93/archie-core/internal/config" @@ -18,14 +15,14 @@ import ( // itself and the fail-closed non-loopback rule belong to the transport, so // they come from gatewayrpc.Dial. func composeChatContract(services config.Services, secrets *secret.Registry, options ...grpc.DialOption) (gateway.ChatContract, func(), error) { - settings := services.Get(config.ServiceNameGateway) - if strings.TrimSpace(settings.Target) == "" { - return nil, nil, fmt.Errorf("services.gateway.target is required") + target, err := services.RequireTarget(config.ServiceNameGateway) + if err != nil { + return nil, nil, err } // Assigned through a typed variable rather than returned directly: a // direct forward would hand a failed dial's nil *Client back as a // non-nil ChatContract interface. - client, cleanup, err := gatewayrpc.Dial(settings.Target, services.ResolvedToken(config.ServiceNameGateway, secrets.Getenv), options...) + client, cleanup, err := gatewayrpc.Dial(target, services.ResolvedToken(config.ServiceNameGateway, secrets.Getenv), options...) if err != nil { return nil, nil, err } diff --git a/internal/app/archied/state_store_client.go b/internal/app/archied/state_store_client.go index 61820b122..d8e8e4a96 100644 --- a/internal/app/archied/state_store_client.go +++ b/internal/app/archied/state_store_client.go @@ -1,9 +1,6 @@ package archied import ( - "fmt" - "strings" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/secret" @@ -15,9 +12,9 @@ import ( // fail-closed non-loopback rule (§9) belong to the transport, so they come // from staterpc.Dial. func composeStateStoreClient(services config.Services, secrets *secret.Registry) (*staterpc.Client, func(), error) { - target := strings.TrimSpace(services.Get(config.ServiceNameState).Target) - if target == "" { - return nil, nil, fmt.Errorf("services.state.target is required") + target, err := services.RequireTarget(config.ServiceNameState) + if err != nil { + return nil, nil, err } return staterpc.Dial(target, services.ResolvedToken(config.ServiceNameState, secrets.Getenv)) } diff --git a/internal/config/services.go b/internal/config/services.go index c8d753d26..eda25ffb2 100644 --- a/internal/config/services.go +++ b/internal/config/services.go @@ -1,5 +1,10 @@ package config +import ( + "fmt" + "strings" +) + // Services maps a registered service name to its connection settings, keyed by // the [services.] section it was decoded from. // @@ -35,6 +40,22 @@ func (s Services) ResolvedToken(name string, getenv func(string) string) string return getenv(spec.TokenEnv) } +// RequireTarget returns the dial address for name, or an error naming the +// config key when the operator has not supplied one. +// +// A service registered with an empty default target is one the operator must +// configure, so this is the registry's own contract rather than a consumer's +// private rule. It stays a lazy check at composition time, not a load-time +// validation: a process that never dials a given service must still be able to +// load a configuration that omits it. +func (s Services) RequireTarget(name string) (string, error) { + target := strings.TrimSpace(s[name].Target) + if target == "" { + return "", fmt.Errorf("services.%s.target is required", name) + } + return target, nil +} + // ServiceConnection is a service's gRPC addresses plus the bearer token a // client presents when the target is non-loopback. A client reads only Target // and TargetToken; Listen belongs to the process that owns the service. The diff --git a/internal/config/services_test.go b/internal/config/services_test.go index 9cf877f0a..10325fbbe 100644 --- a/internal/config/services_test.go +++ b/internal/config/services_test.go @@ -1,6 +1,8 @@ package config_test import ( + "fmt" + "strings" "testing" "github.com/samcharles93/archie-core/internal/config" @@ -131,3 +133,93 @@ func TestResolvedTokenOfUnregisteredServiceHasNoEnvFallback(t *testing.T) { t.Errorf("ResolvedToken = %q, want empty", got) } } + +// mustPanic runs fn and returns the recovered value, or fails if fn returned +// normally. Registration errors are programming errors in this repository's +// own init(), not operator input, so they abort the process rather than +// returning an error nobody is positioned to handle. +func mustPanic(t *testing.T, fn func()) (recovered any) { + t.Helper() + defer func() { recovered = recover() }() + fn() + t.Fatal("RegisterService returned normally, want a panic") + return nil +} + +// TestRegisterServiceRejectsAnUnknownContext makes Context load-bearing. It +// documented which addresses a service must end up with, but nothing read it, +// so a typo'd context was accepted and silently meant nothing. +func TestRegisterServiceRejectsAnUnknownContext(t *testing.T) { + got := mustPanic(t, func() { + config.RegisterService("clientt", "widget-badcontext", "", "127.0.0.1:7005", "T") + }) + if !strings.Contains(fmt.Sprint(got), "clientt") { + t.Errorf("panic = %v, want it to name the invalid context", got) + } +} + +// TestRegisterServiceRejectsAHostedServiceWithNoListen pins the requirement +// Context exists to express: a service this repository hosts must have a +// default bind address, because an empty one reaches net.Listen as "any free +// port". +func TestRegisterServiceRejectsAHostedServiceWithNoListen(t *testing.T) { + for _, hosted := range []string{config.ServiceServer, config.ServiceBoth} { + t.Run(hosted, func(t *testing.T) { + got := mustPanic(t, func() { + config.RegisterService(hosted, "widget-nolisten-"+hosted, "127.0.0.1:1", "", "T") + }) + if !strings.Contains(fmt.Sprint(got), "listen") { + t.Errorf("panic = %v, want it to name the missing listen address", got) + } + }) + } +} + +// TestRegisterServiceAcceptsAClientWithNoTargetDefault keeps the State Store's +// own shape legal: a dialled-only service may register an empty target, which +// is how "the operator must supply this" is stated. +func TestRegisterServiceAcceptsAClientWithNoTargetDefault(t *testing.T) { + defer func() { + if r := recover(); r != nil { + t.Fatalf("RegisterService panicked on a legal client registration: %v", r) + } + }() + config.RegisterService(config.ServiceClient, "widget-clientok", "", "127.0.0.1:7006", "T") +} + +// TestRequireTargetReportsAnAbsentOperatorSuppliedTarget moves the "target is +// required" check off two hand-written consumer copies and onto the registry, +// which is what declared the target operator-supplied in the first place. +func TestRequireTargetReportsAnAbsentOperatorSuppliedTarget(t *testing.T) { + for _, tt := range []struct { + name string + target string + want string + wantErr bool + }{ + {name: "absent", wantErr: true}, + {name: "blank", target: " \t\n", wantErr: true}, + {name: "set", target: "10.0.0.1:9090", want: "10.0.0.1:9090"}, + {name: "set with padding", target: " 10.0.0.1:9090 ", want: "10.0.0.1:9090"}, + } { + t.Run(tt.name, func(t *testing.T) { + services := config.Services{config.ServiceNameState: {Target: tt.target}} + got, err := services.RequireTarget(config.ServiceNameState) + if tt.wantErr { + if err == nil { + t.Fatal("RequireTarget returned no error for an empty target") + } + if !strings.Contains(err.Error(), "services.state.target") { + t.Errorf("error = %v, want it to name the config key", err) + } + return + } + if err != nil { + t.Fatalf("RequireTarget: %v", err) + } + if got != tt.want { + t.Errorf("RequireTarget = %q, want %q", got, tt.want) + } + }) + } +} diff --git a/internal/config/servicespec.go b/internal/config/servicespec.go index 0b6816458..900aebf01 100644 --- a/internal/config/servicespec.go +++ b/internal/config/servicespec.go @@ -1,7 +1,9 @@ package config import ( + "fmt" "sort" + "strings" "sync" ) @@ -60,7 +62,29 @@ var ( // // Re-registering a name replaces the previous spec, so a test can install a // throwaway service without disturbing the built-ins. +// +// It panics on a registration that cannot be honoured. Registrations come from +// this repository's own init(), never from operator input, so an invalid one is +// a programming error: there is no caller positioned to handle an error return, +// and failing at process start is better than a service that binds somewhere +// nobody dials. Context is enforced here rather than merely documented, so +// "hosted" genuinely implies a bind address. func RegisterService(context, name, target, listen, tokenEnv string) { + switch context { + case ServiceClient, ServiceServer, ServiceBoth: + default: + panic(fmt.Sprintf( + "config.RegisterService(%q): unknown context %q, want %q, %q or %q", + name, context, ServiceClient, ServiceServer, ServiceBoth, + )) + } + if context != ServiceClient && strings.TrimSpace(listen) == "" { + panic(fmt.Sprintf( + "config.RegisterService(%q): a %q service needs a default listen address; "+ + "an empty one reaches net.Listen as \"any free port\"", + name, context, + )) + } serviceRegistryMu.Lock() defer serviceRegistryMu.Unlock() serviceRegistry[name] = ServiceSpec{