diff --git a/Taskfile.yml b/Taskfile.yml index 31325af9a..f6497f410 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -192,6 +192,10 @@ tasks: proxying /api and /events through to archie-ui on :8484 + The gRPC ports come from [services.state].listen and [services.gateway].listen in + deployments/dev.toml, each paired with the target that dials it. Move them there + when the host already owns one: cockpit binds 9090 by default. + Open http://localhost:5173 -- not :8484. The Vite server is the one with hot reload; :8484 serves the last built dist/ and will look stale. diff --git a/cmd/archie-gateway/main.go b/cmd/archie-gateway/main.go index dfa6bd83c..e9c8c9989 100644 --- a/cmd/archie-gateway/main.go +++ b/cmd/archie-gateway/main.go @@ -24,7 +24,7 @@ func run() int { var options archied.GatewayOptions flag.StringVar(&options.Config, "config", filepath.Join(base, "archie", "config.toml"), "configuration file or directory") flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory") - flag.StringVar(&options.Listen, "listen", "127.0.0.1:8585", "gateway gRPC listen address") + flag.StringVar(&options.Listen, "listen", "", "gateway gRPC listen address (defaults to [services.gateway].listen, else 127.0.0.1:8585)") flag.StringVar(&options.Token, "token", "", "Bearer [REDACTED] required for a non-loopback listener (defaults to [services.gateway].target_token)") flag.Parse() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) diff --git a/cmd/archie-state-store/main.go b/cmd/archie-state-store/main.go index 7a1f27426..130956aad 100644 --- a/cmd/archie-state-store/main.go +++ b/cmd/archie-state-store/main.go @@ -31,7 +31,7 @@ func run() int { var options archied.StateStoreOptions flag.StringVar(&options.Config, "config", filepath.Join(base, "archie", "config.toml"), "configuration file or directory") flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory") - flag.StringVar(&options.Listen, "listen", "127.0.0.1:9090", "state store gRPC listen address") + flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)") flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)") flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)") flag.Parse() diff --git a/cmd/archie-state-store/main_test.go b/cmd/archie-state-store/main_test.go index f00f5376f..c844fbeb9 100644 --- a/cmd/archie-state-store/main_test.go +++ b/cmd/archie-state-store/main_test.go @@ -85,9 +85,10 @@ func buildBinary(t *testing.T, dir string) string { } // writeMinimalConfig writes a config.toml that passes configuration.Validate -// while keeping the process minimal: the standalone binary reads its gRPC -// listen address from -listen, not from [services.state].target, so the config -// only needs the fields validation requires plus the db_path it owns. The +// while keeping the process minimal: the standalone binary takes its gRPC +// listen address from -listen or [services.state].listen, never from the +// target, so the config only needs the fields validation requires plus the +// db_path it owns. The // forge token resolves from an env var, so no real credential is needed. func writeMinimalConfig(t *testing.T, dir string) string { t.Helper() @@ -108,6 +109,27 @@ name = "widget" return cfg } +// writeConfigWithServiceListen is writeMinimalConfig plus the +// [services.state] block that lets a test supply the listen address through +// configuration instead of the -listen flag. +func writeConfigWithServiceListen(t *testing.T, dir string) string { + t.Helper() + cfg := writeMinimalConfig(t, dir) + f, err := os.OpenFile(cfg, os.O_APPEND|os.O_WRONLY, 0o600) + if err != nil { + t.Fatalf("open config to append: %v", err) + } + defer func() { + if err := f.Close(); err != nil { + t.Fatalf("close config: %v", err) + } + }() + if _, err := f.WriteString("\n[services.state]\nlisten = \"127.0.0.1:0\"\n"); err != nil { + t.Fatalf("append [services.state]: %v", err) + } + return cfg +} + // syncBuffer is a concurrency-safe buffer for a subprocess's stdout/stderr: // the os/exec goroutine writes while the test goroutine reads (to parse the // log and to report it on failure). A plain strings.Builder races under @@ -158,7 +180,12 @@ func startStateStoreProcess(t *testing.T, bin, cfg string) *stateStoreProcess { // credential interceptors on both the unary and the streaming surface. func startStateStore(t *testing.T, bin, cfg, listen, token string) *stateStoreProcess { t.Helper() - args := []string{"-config", cfg, "-listen", listen, "-ready-addr", "127.0.0.1:0"} + args := []string{"-config", cfg, "-ready-addr", "127.0.0.1:0"} + if listen != "" { + // An empty listen means "pass no -listen at all". A test uses that to + // prove the bound address came from [services.state].listen. + args = append(args, "-listen", listen) + } if token != "" { // An explicit -token wins over [services.state].target_token and the // STATE_STORE_TOKEN secret, so the process authenticates callers with @@ -291,14 +318,29 @@ func capture(source, body string) store.CapturedEvent { // adapter, error-sentinel fidelity across the wire, the not-found-as-(nil,nil) // convention, and single-owner SQLite (the binary owns the one archie.db file // and the consumer dials gRPC without opening any store file). +// +// It also takes its listen address from [services.state].listen rather than +// -listen, so the startup path every deployment uses is covered by the process +// that exercises the most: before that key existed the address came from a flag +// default with no config key, so a host that already owned the port (cockpit +// owns 9090 by default) could only be retargeted by passing -listen and +// hand-writing an overlay whose target matched -- and the failure read as a +// code fault, "address already in use" in the store and a gRPC handshake error +// in every client. func TestStateStoreRealProcessSmoke(t *testing.T) { if testing.Short() { t.Skip("real-process smoke test builds and execs the binary; skip under -short") } dir := t.TempDir() bin := buildBinary(t, dir) - cfg := writeMinimalConfig(t, dir) - st := startStateStoreProcess(t, bin, cfg) + cfg := writeConfigWithServiceListen(t, dir) + st := startStateStore(t, bin, cfg, "", "") + if st.addr == "" { + t.Fatalf("no bound gRPC address in the log:\n%s", st.log.String()) + } + if !strings.Contains(st.log.String(), `"listen":"127.0.0.1:0"`) { + t.Fatalf("the resolved listen was not the configured address:\n%s", st.log.String()) + } cl := dial(t, st.addr) ctx := t.Context() diff --git a/config.example.toml b/config.example.toml index f9f3efa89..c8a818558 100644 --- a/config.example.toml +++ b/config.example.toml @@ -304,6 +304,11 @@ gate_max_failures = 5 # docs/prds/state-store-contract.md). [services.gateway] target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remote once set) +# listen = "127.0.0.1:8585" # The address archie-gateway BINDS. Read only by the +# # archie-gateway process; every client ignores it. Defaults +# # to the target above, so a default deployment's client and +# # server cannot drift onto different ports. Set it when the +# # host already owns that port. # target_token = "..." # Bearer [REDACTED] for a NON-loopback listener. A loopback listener # # (127.0.0.1/::1/localhost) needs no token. A non-loopback # # listener without a token fails closed, as does a @@ -316,6 +321,11 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch # # in-process: the standalone archie-state-store process # # owns the single SQLite file (docs/prds/state-store-contract.md # # §10/§12 step 7). An empty target is a startup error. +# listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that +# # process; every client ignores it. Defaults to the target +# # above, so a default deployment's client and server cannot +# # drift onto different ports. Move it when the host already +# # owns 9090 (cockpit binds it by default). # target_token = "..." # bearer token for a NON-loopback target. A loopback target # # (127.0.0.1/::1/localhost) needs no token. A non-loopback # # target without a token fails closed (docs/prds/state-store-contract.md diff --git a/deployments/dev.toml b/deployments/dev.toml index 0e21a71e6..c03d4bc07 100644 --- a/deployments/dev.toml +++ b/deployments/dev.toml @@ -11,16 +11,20 @@ [web] listen = "127.0.0.1:8484" -# `task dev` also runs archie-state-store on its -listen default -# (127.0.0.1:9090, loopback, no token) via dev:state-store -- point archied, -# archie-gateway and archie-ui at it so a fresh dev checkout works without -# hand-editing the installed config.toml +# `task dev` runs archie-state-store via dev:state-store, which passes no +# -listen, so the listen below is the port the store binds. It must agree with +# the target: these two lines are the only place that pair is stated. Move them +# when the host already owns 9090 (cockpit binds it by default) -- before the +# listen key existed the collision could only be worked around by hand-writing +# a matching target and passing -listen, and it read as a code fault. # (docs/prds/state-store-contract.md §12 step 7). [services.state] target = "127.0.0.1:9090" +listen = "127.0.0.1:9090" -# `task dev` runs archie-gateway on its -listen default (127.0.0.1:8585, -# loopback, no token). Stated explicitly so the value archie-ui dials is -# visible next to the State Store one. +# `task dev` runs archie-gateway via dev:gateway, which also passes no -listen: +# the listen below is what it binds. Stated explicitly so the value archie-ui +# dials is visible next to the State Store one. [services.gateway] -target = "127.0.0.1:8585" \ No newline at end of file +target = "127.0.0.1:8585" +listen = "127.0.0.1:8585" \ No newline at end of file diff --git a/docs/architecture/configuration.md b/docs/architecture/configuration.md index 29d708155..4f7f90d0a 100644 --- a/docs/architecture/configuration.md +++ b/docs/architecture/configuration.md @@ -162,6 +162,7 @@ existing structure combines different owners. | listen/relay addresses | email config | Email adapter instance settings. | | webhook target | `Notify` | Notification adapter instance settings. | | web listen address | `Web` | Web transport settings. | +| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. | | index directory and database path | `Indexing` | Index infrastructure settings, derived from storage settings unless explicitly overridden. | | forge, dispatch, models, providers, containers, memory, tools, indexing and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. | | owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. | diff --git a/internal/app/archied/gateway.go b/internal/app/archied/gateway.go index e21c5aea3..03950d314 100644 --- a/internal/app/archied/gateway.go +++ b/internal/app/archied/gateway.go @@ -29,6 +29,24 @@ type GatewayOptions struct { Token string } +// gatewayListenAndToken resolves the two per-listener inputs RunGateway needs: +// the address it binds and the bearer token a non-loopback bind validates. +// +// Both are flag-first and config-second, and both fail closed rather than +// 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) + if err != nil { + return "", "", err + } + token = options.Token + if token == "" { + token = gatewayResolvedToken(b.cfg.Services.Gateway, b.secrets) + } + return listen, token, nil +} + // RunGateway owns conversation persistence, model runtime and tool-provider // lifecycles. Task-store adapters access the State Store contract (remote // *staterpc.Client via [services.state].target), not archie.db directly: the @@ -85,16 +103,16 @@ func RunGateway(ctx context.Context, options GatewayOptions) error { if err != nil { return err } - gatewayToken := options.Token - if gatewayToken == "" { - gatewayToken = gatewayResolvedToken(b.cfg.Services.Gateway, b.secrets) - } - //nolint:contextcheck // grpc.StreamServerInterceptor has no context.Context parameter; gatewayrpc.StreamServerInterceptor derives its context from stream.Context() instead - opts, loopback, err := gatewayServerOpts(options.Listen, gatewayToken) + listen, gatewayToken, err := gatewayListenAndToken(b, options) if err != nil { return err } - listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", options.Listen) + //nolint:contextcheck // grpc.StreamServerInterceptor has no context.Context parameter; gatewayrpc.StreamServerInterceptor derives its context from stream.Context() instead + opts, loopback, err := gatewayServerOpts(listen, gatewayToken) + if err != nil { + return err + } + listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", listen) if err != nil { return fmt.Errorf("listen for gateway: %w", err) } diff --git a/internal/app/archied/listen.go b/internal/app/archied/listen.go new file mode 100644 index 000000000..d8a5fa3b0 --- /dev/null +++ b/internal/app/archied/listen.go @@ -0,0 +1,34 @@ +package archied + +import ( + "fmt" + "strings" +) + +// resolveServiceListen picks the address a service listener binds: the -listen +// flag when it was given, else the address the configuration names. +// +// Both services this repository runs used to take their address from a flag +// default alone, with no config key. The port a service binds and the port its +// clients dial were therefore two separate facts -- the flag default (or a +// hand-passed -listen) and [services.].target -- with nothing keeping +// them in step. On a host that already owned the default (cockpit owns 9090) +// retargeting meant hand-writing an overlay and passing a matching flag, and +// the failure looked like a code fault: the listener died with "address already +// in use" while every client reported a gRPC handshake error against whatever +// else held the port. +// +// An empty result is an error, never a fallback: net.Listen treats "" as "any +// free port", so defaulting here would bind the service somewhere its clients +// do not look and report success while doing it. +func resolveServiceListen(service, flagValue, configured string) (string, error) { + if v := strings.TrimSpace(flagValue); v != "" { + return v, nil + } + if v := strings.TrimSpace(configured); v != "" { + return v, nil + } + return "", fmt.Errorf( + "%s: no listen address: pass -listen or set [services.%s].listen", service, service, + ) +} diff --git a/internal/app/archied/listen_test.go b/internal/app/archied/listen_test.go new file mode 100644 index 000000000..8fc22ed95 --- /dev/null +++ b/internal/app/archied/listen_test.go @@ -0,0 +1,58 @@ +package archied + +import "testing" + +// TestResolveServiceListen pins the precedence: an explicit -listen wins, else +// the configured address, and an address is never invented. +// +// The error cases are the ones that matter. net.Listen reads "" as "any free +// port", so defaulting here would bind the service somewhere its clients do not +// look and report success while doing it -- the exact failure this helper exists +// to make impossible. +func TestResolveServiceListen(t *testing.T) { + for _, tt := range []struct { + name, flagValue, configured, want string + wantErr bool + }{ + { + name: "the flag wins over the configured address", + flagValue: "127.0.0.1:9191", configured: "127.0.0.1:9090", + want: "127.0.0.1:9191", + }, + { + name: "the configured address is used when no flag was passed", + configured: "127.0.0.1:9191", + want: "127.0.0.1:9191", + }, + { + name: "a whitespace flag is not an address", + flagValue: " ", configured: "127.0.0.1:9191", + want: "127.0.0.1:9191", + }, + { + name: "both empty is an error, never a silent ephemeral port", + wantErr: true, + }, + { + name: "whitespace on both sides is an error too", + flagValue: " ", configured: "\t", + wantErr: true, + }, + } { + t.Run(tt.name, func(t *testing.T) { + got, err := resolveServiceListen("state", tt.flagValue, tt.configured) + if tt.wantErr { + if err == nil { + t.Fatalf("err = nil, want an error; got %q", got) + } + return + } + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if got != tt.want { + t.Fatalf("listen = %q, want %q", got, tt.want) + } + }) + } +} diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index d2f2eea3f..278a320a9 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -56,7 +56,11 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { if err := b.loadConfig(ctx, options.Config, options.Overlay, false); err != nil { return err } - b.log = b.log.With("component", "state-store") + listen, err := resolveServiceListen("state", options.Listen, b.cfg.Services.State.Listen) + if err != nil { + return err + } + b.log = b.log.With("component", "state-store", "listen", listen) if err := b.openStateStore(ctx); err != nil { return err } @@ -67,11 +71,11 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error { } grants := &staterpc.TaskGrants{} //nolint:contextcheck // grpc.StreamServerInterceptor has no context.Context parameter; TaskGrants.StreamInterceptor derives its context from stream.Context() instead - opts, loopback, err := stateStoreServerOpts(options.Listen, token, grants) + opts, loopback, err := stateStoreServerOpts(listen, token, grants) if err != nil { return err } - listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", options.Listen) + listener, err := (&net.ListenConfig{}).Listen(ctx, "tcp", listen) if err != nil { return fmt.Errorf("listen for state store: %w", err) } diff --git a/internal/config/services.go b/internal/config/services.go index 6f9e03057..071ec5352 100644 --- a/internal/config/services.go +++ b/internal/config/services.go @@ -14,10 +14,18 @@ type Services struct { } // ServiceConnection is a contract adapter's gRPC address plus the bearer -// token a client presents when the target is non-loopback. It does not -// register services or start listeners. Changes require a daemon restart. +// 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. + 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 // archie-state-store server validates. Empty means no token, which is diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index 396eb038c..6d06a43d7 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -12,9 +12,18 @@ 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 + 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" defaultMaxRetries = 3 defaultForgeType = "github" defaultForgeHost = "https://github.com" @@ -63,7 +72,13 @@ const ( // 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 = "127.0.0.1:8585" + 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 } if cfg.Health.Listen == "" { cfg.Health.Listen = defaultHealthListen diff --git a/internal/infrastructure/configuration/services_test.go b/internal/infrastructure/configuration/services_test.go index b5e1efd7c..7b75ebeda 100644 --- a/internal/infrastructure/configuration/services_test.go +++ b/internal/infrastructure/configuration/services_test.go @@ -29,6 +29,48 @@ func TestLoadGatewayServiceTarget(t *testing.T) { } } +// TestLoadServiceListens: both gRPC services this repository runs bind an +// address the configuration names. They used to be flag-only, so a host that +// already owned the default port (cockpit owns 9090) could only be retargeted +// by passing -listen and hand-writing an overlay whose target matched -- two +// files to keep in step, and nothing to keep them there. +func TestLoadServiceListens(t *testing.T) { + for _, tt := range []struct { + name, section, wantState, wantGateway string + }{ + {name: "defaults", wantState: "127.0.0.1:9090", wantGateway: "127.0.0.1:8585"}, + { + name: "explicit listens", + section: "[services.state]\nlisten = '127.0.0.1:9191'\n[services.gateway]\nlisten = '127.0.0.1:8686'", + wantState: "127.0.0.1:9191", + wantGateway: "127.0.0.1:8686", + }, + { + name: "state listen alone leaves the gateway default", + section: "[services.state]\nlisten = '127.0.0.1:9191'", + wantState: "127.0.0.1:9191", + wantGateway: "127.0.0.1:8585", + }, + } { + t.Run(tt.name, func(t *testing.T) { + path := filepath.Join(t.TempDir(), "config.toml") + if err := os.WriteFile(path, []byte("bot_user = 'widget'\n"+tt.section), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + 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.Gateway.Listen != tt.wantGateway { + t.Fatalf("gateway listen = %q, want %q", cfg.Services.Gateway.Listen, tt.wantGateway) + } + }) + } +} + // TestLoadHealthListen: the daemon's liveness surface is not optional. The // update watchdog restarts archied and asks whether it came back, and only // archied can answer that -- the dashboard's /healthz belongs to the