Files
archie/docs/prds/service-registry.md
T

113 lines
5.9 KiB
Markdown

# Service registry — one declaration per service
**Status:** Draft
**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`
struct-field instruction.
**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
**name**, in three layers:
| Layer | Location | What is hard-coded |
| ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |
| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == ""` branches |
| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `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`) and `gatewayResolvedToken`
(`chat_service.go`) 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`) 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. `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.
- `listen` is the default listen address, feeding the existing
flag → `[services.<name>].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.<name>]`.
- A typo'd `[services.gatway]` is **reported** (`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.
The typo is not silently ignored either way; the behaviour was measured.
- Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go`,
`setup_test.go`, 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.