feat(config): let the State Store and Gateway listen addresses be configured

Both gRPC listeners took their bind address from a -listen 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, and [services.<name>].target --
with nothing keeping them in step.

On a host that already owned the default the effect read as a code fault rather
than a port collision: the store died with "bind: address already in use" while
every client reported "state store: connection error ... error reading server
preface: EOF". Cockpit binds 9090 by default, so this is not hypothetical.
Verifying the dashboard on such a host needed a hand-written overlay plus a
matching -listen, two things to keep in step by hand.

- [services.state].listen and [services.gateway].listen now name the bind
  address. Precedence is -listen, then config, then a default applied by the
  loader. An empty result is a startup ERROR, never a fallback: net.Listen reads
  "" as "any free port", so defaulting there would bind the service somewhere no
  client looks and still report success.
- Both flag defaults become "" so configuration can win, mirroring how archie-ui
  already prefers [web].listen over its flag.
- Gateway listen defaults to the same constant as the gateway target, so a
  default deployment's client and server cannot drift onto different ports.
  [services.state].target still has no default: an empty target stays a startup
  error in the daemon and gateway, which no longer serve a local store.
- ServiceConnection gains the field. Its doc now says clients read only Target
  and TargetToken, and Listen belongs to the process that owns the service --
  the previous wording claimed the struct starts no listeners while carrying one.
- deployments/dev.toml states each port once, beside the target it must match, so
  `task dev` is retargetable on a host that owns 9090 by editing one overlay.

Tests. Unit: config defaults, explicit values, and precedence. Process: the
existing real-process smoke test now takes its listen from configuration instead
of -listen, so the end-to-end wiring is proven by the test that already starts
the binary, with no extra process. Both were verified load-bearing by mutation --
inverting the precedence fails the unit test, and making the app layer ignore
config fails the process test with "state: no listen address".

Verified: task check exit 0. Also documented in config.example.toml, the
configuration architecture table, and the `task dev` summary.
This commit is contained in:
sam committed 2026-09-18 19:15:02 +10:00
1 parent 7414713d61
commit b09be5515d
14 files changed
+272 -32

No files matched your search

+4
View File
@@ -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.
+1 -1
View File
@@ -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)
+1 -1
View File
@@ -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()
+48 -6
View File
@@ -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()
+10
View File
@@ -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
+12 -8
View File
@@ -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"
target = "127.0.0.1:8585"
listen = "127.0.0.1:8585"
+1
View File
@@ -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. |
+25 -7
View File
@@ -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)
}
+34
View File
@@ -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.<name>].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,
)
}
+58
View File
@@ -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)
}
})
}
}
+7 -3
View File
@@ -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)
}
+10 -2
View File
@@ -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
@@ -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
@@ -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