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.<name>]. Also records the open [chat.*] section naming question in the migration decision register, where it is blocked on a decision rather than on evidence.
This commit is contained in:
1 parent
095284678a
commit
6a965ecbd5
3 files changed
+130
-9
No files matched your search
@@ -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.
|
||||
@@ -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.<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]` 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.
|
||||
@@ -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.<name>]`. 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
|
||||
|
||||
Reference in new issue
Block a user