Merge pull request #883 from samcharles93/docs/service-registry

Docs/service registry
This commit is contained in:
sam authored and GitHub committed 2026-09-19 03:25:10 +10:00
commit ba1712e8bf
7 files changed
+266 -28

No files matched your search

+1 -1
View File
@@ -183,7 +183,7 @@ structures found in legacy packages.
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
and degrade health without terminating the process.
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
Authority is `docs/prds/state-store-contract.md` (rev. 2c) -- read it before
Authority is `docs/prds/state-store-contract.md` (rev. 2d) -- read it before
changing this package or its callers.
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
+22 -14
View File
@@ -549,22 +549,30 @@ an explicit operator decision.
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
a separate process.
- Because `[services.state]` is **not** in `config.example.toml` today (the gateway's own
section is also missing — documentation debt), **add `[services.state]`** with a commented
`target` to `config.example.toml` in the same change that introduces the config field, so the
seam is visible to operators.
- Composition root: `internal/app/archied/bootstrap.go`. Base path = the local `*store.Store`
(already opened by `openProductionTaskStore`); if `cfg.Services.State.Target != ""`, dial gRPC
and assign `b.stateStore = staterpc.NewClient(conn)` (with the token from config/secret).
- **Empty `Target` → startup error** (corrected in rev. 2d). This bullet previously said an
empty `Target` opens a local `*store.Store` adapter. That default was withdrawn when the
State Store was extracted (§12 step 7): the standalone `archie-state-store` process
exclusively owns `archie.db`, so both `archied` and `archie-gateway` now reject an empty
target (`internal/app/archied/bootstrap.go` and `state_store_client.go`: `services.state.target
is required`). **Set `Target` → dial gRPC** with `*staterpc.Client`; no client opens the
database itself. This differs from the gateway, where `Target` is defaulted to
`127.0.0.1:8585` because `archie-gateway` is already a separate process whose client and
server share one default.
- `[services.state]` is present and **uncommented** in `config.example.toml`, with `target`
marked REQUIRED, because the value is now load-bearing for every client. (This bullet
previously instructed adding the section with a commented-out `target`; that advice is
withdrawn, since a commented target cannot boot.)
- Composition root: `internal/app/archied/bootstrap.go` (the daemon) and
`internal/app/archieui/config.go` (the UI process) both read `cfg.Services.Get("state")` and
dial the remote State Store. `openProductionTaskStore` is **not** called from the daemon: it
lives in the standalone `archie-state-store` process (`internal/app/archied/state_store.go`),
which is the only path that opens `archie.db`.
> **Mode fork, decided.** The gateway uses a single `target` address (no enum). The State Store
> boundary uses the same seam for symmetry, but with the opposite default (local, not remote)
> because the State Store is not yet extracted. No `mode` field is added. A companion
> `STATE_STORE_TOKEN` secret (or a `[services.state] target_token` key) carries authentication.
> boundary uses the same seam for symmetry, and **both now require a non-empty `target`**: the
> State Store's local-store default was withdrawn when the process was extracted (§12 step 7).
> No `mode` field is added. A companion `STATE_STORE_TOKEN` secret (or a
> `[services.state] target_token` key) carries authentication.
---
+7
View File
@@ -32,6 +32,9 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
Hosted: map[string]ImageHostedProvider{"openai": {Enabled: true}},
Local: map[string]ImageLocalProvider{"sdxl": {Enabled: true}},
},
Services: Services{
ServiceNameState: {Target: "127.0.0.1:9090", TargetToken: "secret"},
},
}
got := orig.Clone()
@@ -52,6 +55,7 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
*got.Tools.WebFetch.Enabled = false
got.Image.Hosted["openai"] = ImageHostedProvider{Enabled: false}
got.Image.Local["sdxl"] = ImageLocalProvider{Enabled: false}
got.Services[ServiceNameState] = ServiceConnection{Target: "changed"}
if orig.Models["builder"] != "m" {
t.Error("Models map is shared")
@@ -95,4 +99,7 @@ func TestConfigCloneDeepCopiesReferenceFields(t *testing.T) {
if !orig.Image.Local["sdxl"].Enabled {
t.Error("Image.Local map is shared")
}
if orig.Services[ServiceNameState].TargetToken != "secret" {
t.Error("Services map is shared")
}
}
+5
View File
@@ -665,6 +665,11 @@ func (c Config) Clone() Config {
c.Memory.ProviderConfig = maps.Clone(c.Memory.ProviderConfig)
c.Image.Hosted = maps.Clone(c.Image.Hosted)
c.Image.Local = maps.Clone(c.Image.Local)
// Services is a map of structs, so the header is shared by the value copy
// above and yaml.Unmarshal writes keys into whatever map it is handed. Without
// this line an overlay -- or a dashboard PATCH -- rewrites the PUBLISHED
// snapshot in place, which is the mutation Clone exists to prevent.
c.Services = maps.Clone(c.Services)
if c.Tools.WebFetch.Enabled != nil {
v := *c.Tools.WebFetch.Enabled
c.Tools.WebFetch.Enabled = &v
+151 -1
View File
@@ -2,6 +2,9 @@ package configuration
import (
"fmt"
"maps"
"reflect"
"strings"
"gopkg.in/yaml.v3"
@@ -18,11 +21,26 @@ import (
// dashboard PATCH path calls it on a copy of the published config and
// validates the materialised result before persisting. Either way the
// caller owns the cfg value -- pass a copy when the base must survive.
//
// overrides is read, never mutated.
func ApplyOverlayValues(cfg *config.Config, overrides map[string]any) error {
if len(overrides) == 0 {
return nil
}
data, err := yaml.Marshal(overrides)
// yaml gives a struct field the field-level treatment promised above, but a
// map VALUE is decoded into a fresh zero value: an entry the overlay only
// partially addresses would lose every field it does not name, so an
// operator changing services.state.target alone would silently drop
// target_token. Fold the fields the overlay omits forward out of the entry
// cfg already holds, leaving the decode a complete entry to read. Doing it
// here, once, is what makes the promise hold for every map of structs
// (services, image.hosted, image.local, providers) instead of at each
// field's reader.
folded, err := foldOverrides(reflect.ValueOf(cfg), overrides)
if err != nil {
return err
}
data, err := yaml.Marshal(folded)
if err != nil {
return fmt.Errorf("%w: encoding config overlay: %w", ErrUnreadable, err)
}
@@ -31,3 +49,135 @@ func ApplyOverlayValues(cfg *config.Config, overrides map[string]any) error {
}
return nil
}
// foldOverrides returns doc with the fields its map entries omit carried
// forward from the entries cfg already holds. It descends through structs, so
// {"image": {"hosted": {...}}} folds the same way as an override written at the
// top level.
//
// Only mapping-valued map entries need it: yaml keeps the entries a map of
// scalars does not name, and a struct field it does not name keeps its value.
func foldOverrides(cfg reflect.Value, doc map[string]any) (map[string]any, error) {
if cfg.Kind() == reflect.Pointer {
if cfg.IsNil() {
return doc, nil
}
cfg = cfg.Elem()
}
if cfg.Kind() != reflect.Struct {
return doc, nil
}
out := make(map[string]any, len(doc))
maps.Copy(out, doc)
for key, value := range out {
field, ok := yamlField(cfg, key)
if !ok {
continue
}
sub, ok := value.(map[string]any)
if !ok {
continue // a scalar replaces the whole field, and the decode says so
}
switch field.Kind() {
case reflect.Struct:
folded, err := foldOverrides(field, sub)
if err != nil {
return nil, err
}
out[key] = folded
case reflect.Map:
folded, err := foldMapEntries(field, sub)
if err != nil {
return nil, err
}
out[key] = folded
}
}
return out, nil
}
// foldMapEntries returns one map field's override with each entry the overlay
// names carried forward from the entry of the same key in cfg.
func foldMapEntries(field reflect.Value, doc map[string]any) (map[string]any, error) {
if field.IsNil() || field.Type().Key().Kind() != reflect.String {
return doc, nil
}
out := make(map[string]any, len(doc))
maps.Copy(out, doc)
for key, value := range out {
entry, ok := value.(map[string]any)
if !ok {
continue
}
existing := field.MapIndex(reflect.ValueOf(key).Convert(field.Type().Key()))
if !existing.IsValid() {
continue // an entry the overlay introduces has no earlier fields
}
carried, err := asMapping(existing)
if err != nil {
return nil, err
}
if carried == nil {
continue // not a mapping, so the overlay replaces it wholesale
}
out[key] = mergeMapping(carried, entry)
}
return out, nil
}
// asMapping renders one config value as the mapping the decode will read it
// back as, which is what lets the fields an override omits be carried forward.
// It returns nil when the value does not encode to a mapping.
func asMapping(value reflect.Value) (map[string]any, error) {
data, err := yaml.Marshal(value.Interface())
if err != nil {
return nil, fmt.Errorf("%w: encoding config overlay: %w", ErrUnreadable, err)
}
// Decoding into any cannot fail for marshalled output; a value that is not
// a mapping simply yields no mapping.
var generic any
_ = yaml.Unmarshal(data, &generic)
mapping, _ := generic.(map[string]any)
return mapping, nil
}
// mergeMapping layers override over base: mappings merge key by key, anything
// else replaces, matching how the decode treats a struct field versus a scalar.
// It allocates rather than mutating either argument.
func mergeMapping(base, override map[string]any) map[string]any {
out := make(map[string]any, len(base)+len(override))
maps.Copy(out, base)
for key, value := range override {
if over, ok := value.(map[string]any); ok {
if under, ok := base[key].(map[string]any); ok {
out[key] = mergeMapping(under, over)
continue
}
}
out[key] = value
}
return out
}
// yamlField returns the field of struct v that the decode reads key into. The
// yaml tag is the one consulted because the decode below is yaml's.
func yamlField(v reflect.Value, key string) (reflect.Value, bool) {
t := v.Type()
for i := range t.NumField() {
field := t.Field(i)
if field.PkgPath != "" {
continue // unexported, so the decoder cannot write it
}
name, _, _ := strings.Cut(field.Tag.Get("yaml"), ",")
if name == "-" {
continue
}
if name == "" {
name = strings.ToLower(field.Name)
}
if name == key {
return v.Field(i), true
}
}
return reflect.Value{}, false
}
@@ -2,6 +2,7 @@ package configuration
import (
"log/slog"
"maps"
"os"
"path/filepath"
"testing"
@@ -38,7 +39,7 @@ func TestApplyOverlayValuesFieldLevelMerge(t *testing.T) {
// must not clear target_token, because dropping the token silently removes
// authentication for a non-loopback State Store. The existing field-level test
// only covers one level (budgets.max_steps); these cases go two levels deep into
// a struct of structs, which is the shape Services has.
// a map of structs, which is the shape Services has.
func TestApplyOverlayValuesPreservesOmittedNestedFields(t *testing.T) {
tests := []struct {
name string
@@ -48,21 +49,27 @@ func TestApplyOverlayValuesPreservesOmittedNestedFields(t *testing.T) {
}{
{
name: "target-only overlay keeps the token",
start: config.Services{State: config.ServiceConnection{Target: "127.0.0.1:50051", TargetToken: "secret"}},
overlay: map[string]any{"services": map[string]any{"state": map[string]any{"target": "10.0.0.5:50051"}}},
want: config.Services{State: config.ServiceConnection{Target: "10.0.0.5:50051", TargetToken: "secret"}},
start: config.Services{config.ServiceNameState: {Target: "127.0.0.1:50051", TargetToken: "secret"}},
overlay: map[string]any{"services": map[string]any{config.ServiceNameState: map[string]any{"target": "10.0.0.5:50051"}}},
want: config.Services{config.ServiceNameState: {Target: "10.0.0.5:50051", TargetToken: "secret"}},
},
{
name: "token-only overlay keeps the target",
start: config.Services{State: config.ServiceConnection{Target: "10.0.0.5:50051", TargetToken: "old"}},
overlay: map[string]any{"services": map[string]any{"state": map[string]any{"target_token": "rotated"}}},
want: config.Services{State: config.ServiceConnection{Target: "10.0.0.5:50051", TargetToken: "rotated"}},
start: config.Services{config.ServiceNameState: {Target: "10.0.0.5:50051", TargetToken: "old"}},
overlay: map[string]any{"services": map[string]any{config.ServiceNameState: map[string]any{"target_token": "rotated"}}},
want: config.Services{config.ServiceNameState: {Target: "10.0.0.5:50051", TargetToken: "rotated"}},
},
{
name: "sibling service is untouched",
start: config.Services{Gateway: config.ServiceConnection{Target: "127.0.0.1:50052"}, State: config.ServiceConnection{Target: "a", TargetToken: "t"}},
overlay: map[string]any{"services": map[string]any{"state": map[string]any{"target": "b"}}},
want: config.Services{Gateway: config.ServiceConnection{Target: "127.0.0.1:50052"}, State: config.ServiceConnection{Target: "b", TargetToken: "t"}},
start: config.Services{config.ServiceNameGateway: {Target: "127.0.0.1:50052"}, config.ServiceNameState: {Target: "a", TargetToken: "t"}},
overlay: map[string]any{"services": map[string]any{config.ServiceNameState: map[string]any{"target": "b"}}},
want: config.Services{config.ServiceNameGateway: {Target: "127.0.0.1:50052"}, config.ServiceNameState: {Target: "b", TargetToken: "t"}},
},
{
name: "an entry the overlay introduces decodes in full",
start: config.Services{},
overlay: map[string]any{"services": map[string]any{config.ServiceNameState: map[string]any{"target": "127.0.0.1:50051", "target_token": "fresh"}}},
want: config.Services{config.ServiceNameState: {Target: "127.0.0.1:50051", TargetToken: "fresh"}},
},
}
@@ -72,13 +79,75 @@ func TestApplyOverlayValuesPreservesOmittedNestedFields(t *testing.T) {
if err := ApplyOverlayValues(&cfg, tt.overlay); err != nil {
t.Fatalf("ApplyOverlayValues: %v", err)
}
if cfg.Services != tt.want {
if !maps.Equal(cfg.Services, tt.want) {
t.Errorf("Services = %+v, want %+v", cfg.Services, tt.want)
}
})
}
}
// TestApplyOverlayValuesMergesEveryMapEntry pins that the preservation above is
// a property of ApplyOverlayValues rather than of Services. yaml.v3 decodes a
// map value into a fresh zero value, so every map[string]struct field loses the
// fields an override omits; Services, image.hosted and providers are the three
// the configuration has, so a fix that named one of them would leave the other
// two silently zeroing operator settings.
func TestApplyOverlayValuesMergesEveryMapEntry(t *testing.T) {
tests := []struct {
name string
start config.Config
overlay map[string]any
check func(t *testing.T, cfg config.Config)
}{
{
name: "image.hosted entry keeps the fields the overlay omits",
start: config.Config{Image: config.ImageConfig{Hosted: map[string]config.ImageHostedProvider{
"minimax": {Enabled: true, Class: "minimax", APIKeyEnv: "MINIMAX_API_KEY"},
}}},
overlay: map[string]any{"image": map[string]any{"hosted": map[string]any{
"minimax": map[string]any{"base_url": "https://api.example"},
}}},
check: func(t *testing.T, cfg config.Config) {
t.Helper()
want := map[string]config.ImageHostedProvider{
"minimax": {Enabled: true, Class: "minimax", APIKeyEnv: "MINIMAX_API_KEY", BaseURL: "https://api.example"},
}
if !maps.Equal(cfg.Image.Hosted, want) {
t.Errorf("Image.Hosted = %+v, want %+v", cfg.Image.Hosted, want)
}
},
},
{
name: "providers entry keeps the fields the overlay omits",
start: config.Config{Providers: map[string]config.Provider{
"anthropic": {Class: "anthropic", APIKeyEnv: "ANTHROPIC_API_KEY"},
}},
overlay: map[string]any{"providers": map[string]any{
"anthropic": map[string]any{"base_url": "https://proxy.example"},
}},
check: func(t *testing.T, cfg config.Config) {
t.Helper()
want := map[string]config.Provider{
"anthropic": {Class: "anthropic", APIKeyEnv: "ANTHROPIC_API_KEY", BaseURL: "https://proxy.example"},
}
if !maps.Equal(cfg.Providers, want) {
t.Errorf("Providers = %+v, want %+v", cfg.Providers, want)
}
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cfg := tt.start
if err := ApplyOverlayValues(&cfg, tt.overlay); err != nil {
t.Fatalf("ApplyOverlayValues: %v", err)
}
tt.check(t, cfg)
})
}
}
func TestLoaderApplyOverlayLayersDefaultsValidatesAndRecordsProvenance(t *testing.T) {
path := filepath.Join(t.TempDir(), "config.toml")
if err := os.WriteFile(path, []byte("bot_user = \"widget\"\n[[repos]]\nowner = \"acme\"\nname = \"app\"\n"), 0o600); err != nil {
-1
View File
@@ -202,7 +202,6 @@ func compareArtifacts(relative string, expected, committed []byte) []string {
return problems
}
// obsoleteArtifacts reports committed generated files in the artifact's
// obsoleteArtifacts reports files present in a directory docsgen owns that the
// generator no longer produces, so a renamed or deleted artifact cannot linger
// as dead documentation. A directory docsgen does not own is never judged: its