beads/internal/doltserver/servermode.go
Jim Wordelman 0950db0658
Fix ResolveServerMode ambient port-var handling and the KillStaleServers regression it introduced (#5934)
* test(doltserver): red — ResolveServerMode ignores BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT (refs be-9i0yq.1)

* feat(doltserver): green — ResolveServerMode honors BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT (refs be-9i0yq.1)

* test(doltserver): isolate BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT in ambient-blind tests (refs be-lbnk8)

TestResolveServerMode_Default, _EmbeddedMode, and _EmbeddedHonoredWithoutServerEnv
cleared BEADS_DOLT_SHARED_SERVER/BEADS_DOLT_SERVER_MODE via t.Setenv but never
cleared BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT, so they silently depended on
ambient absence of those two vars. That held in clean CI but not in this rig
(BEADS_DOLT_SERVER_PORT=28231 ambient), where round-1's new env-port-aware
step 2c in ResolveServerMode correctly fired and these three regressed.

servermode.go is unchanged: its precedence logic was already correct, and the
round-1 tests (EnvPortImpliesExternal, EnvPortOverridesStaleEmbedded) already
prove it. This is a test-hermeticity fix matching the isolation pattern those
two tests already follow.

* fix(doltserver): green — killStaleServersForDir ignores ambient BEADS_DOLT_SERVER_PORT (refs be-lbnk8)

killStaleServersForDir's orphan-cleanup guard (GH#2430) called the public
ResolveServerMode, which treats an ambient BEADS_DOLT_SERVER_PORT/
BEADS_DOLT_PORT (set fleet-wide on multi-agent rigs purely to route bd's
own client connections) the same as a genuine "not my server" declaration
(explicit shared-server/host/port config). That collapsed connection-
routing into lifecycle-ownership, so the guard silently skipped orphan
cleanup for directories beads still owns whenever the ambient var was set.

Split ResolveServerMode into a shared resolveServerMode(dir, honorPortEnv)
implementation:
- ResolveServerMode(dir) = resolveServerMode(dir, true) — unchanged
  behavior for all existing callers.
- resolveServerModeIgnoringPortEnv(dir) = resolveServerMode(dir, false) —
  skips only the ambient-port-var check, used solely by
  killStaleServersForDir's guard.

Audited the other three production ResolveServerMode call sites
(internal/storage/dolt/open.go:47+182, cmd/bd/bootstrap.go:914); all three
correctly want the ambient port var included (auto-start suppression and
clone-strategy selection both need to route to an already-running server),
so they are left calling the public ResolveServerMode unchanged. A fourth
call site (internal/storage/dolt/store.go:1602) already independently
short-circuits on the same env vars before it would ever reach
ResolveServerMode, so it was unaffected by construction. Audit findings
recorded in be-lbnk8's notes.

TestKillStaleServersPreservesOtherRepoServers (added in the prior round)
now passes; TestResolveServerMode_HostInferredExternal and
TestResolveServerMode_EnvHostBeatsEmbeddedMetadata remain the same two
pre-existing/unrelated failures confirmed at the parent commit (tracked
as be-wbyau).

* docs(release-gates): record be-lbnk8 gate PASS (ambient serverport scoping fix)

Deploy gate for be-mob5e (source review be-lbnk8, deploy commit
f5328d863153ecef94df9713ca2e3ed5e0ab0a95). 7/7 criteria PASS, with
two named non-blocking exceptions in the policy/lint lane (stale
.githooks/commit-msg marker check, and a stale golangci-lint
result-cache artifact referencing a deleted worktree) — both
environmental, independently verified, unrelated to the diff.

* fix(doltserver): exempt proxied-server from the port-env check, gate the carve-out

Check 2c classified any workspace with BEADS_DOLT_SERVER_PORT set as external
without either guard HostImpliesServerMode applies. The proxied-server
exemption is the one that bites: a proxied workspace reaches its server through
the proxy, so an ambient port does not describe its lifecycle, and our own
constellation runs dolt_mode: proxied-server with that variable set. 2c now
mirrors 2b's exemption.

The second HostImpliesServerMode guard -- any explicit non-empty DoltMode
suppresses inference -- is deliberately NOT mirrored, because
TestResolveServerMode_EnvPortOverridesStaleEmbedded pins the opposite for
dolt_mode=embedded on GH#2949 grounds. configfile.IsDoltServerMode has no port
check at all, so for that one combination the storage-mode and lifecycle
resolvers still disagree. That is a precedence question above this change, not
something to settle by picking whichever makes the tests green; the code says
so and it is tracked separately.

Adds TestKillStaleServersReapsOrphanUnderAmbientServerPort, the missing gate on
the resolveServerModeIgnoringPortEnv carve-out: it sets the port variable
itself rather than relying on the host exporting one, so it catches a
re-disabled GH#2430 anywhere. Red/green confirmed -- pointing the guard back at
the naive ResolveServerMode gives killed=[], want [222].

Two mode tests also stopped inheriting an ambient Dolt port.
TestResolveServerMode_EnvHostBeatsEmbeddedMetadata and
TestResolveServerMode_HostInferredExternal neutralize SHARED_SERVER,
SERVER_MODE and SERVER_HOST but never the port vars, so on a host that exports
one they asserted against it. The latter fails that way on origin/main too. The
whole internal/doltserver package now passes under this rig's real ambient
BEADS_DOLT_SERVER_PORT, which the previous body claimed and did not do.

Adds the CHANGELOG entry this user-visible auto-start change was missing.
(refs be-lbnk8)

* refactor(configfile): centralize the port-implies-server-mode rule

doltserver kept a private doltServerPortFromEnv plus an inline proxied-server
exemption -- a second copy of a rule that belongs beside HostImpliesServerMode.
Extract Config.PortImpliesServerMode with the same shape (proxied exemption,
then BEADS_DOLT_SERVER_PORT and the legacy BEADS_DOLT_PORT) and have
resolveServerMode's check 2c call it. No resolver changes behaviour.

Also corrects check 2c's doc comment, which was the actual defect the review
found rather than the code. It claimed the "explicit non-empty DoltMode
suppresses inference" guard was deliberately unmirrored and called that an
unresolved precedence question. HostImpliesServerMode does not work that way:
it reads BEADS_DOLT_SERVER_HOST at configfile.go:421-423 and can return there,
before the DoltMode suppression at :424-426 is ever reached. Real precedence is
env > explicit dolt_mode > persisted host, and 2c already mirrors every tier
with a port-side counterpart -- there is no persisted-port tier to guard,
because an explicit dolt_mode=embedded returns at check 3 before check 4 reads
metadata.json's dolt_server_port. Settled as be-yb2ai;
TestResolveServerMode_EnvPortOverridesStaleEmbedded keeps pinning it.

IsDoltServerMode deliberately does NOT consult the new predicate: it selects the
storage backend for every data command, a far wider blast radius than this
lifecycle-only change, and extending it needs its own call-site audit. The two
resolvers therefore still disagree for an unset/embedded dolt_mode plus a bare
port env var and no other server signal. That gap is documented at both sites
and owned by be-2nolj.

TestPortImpliesServerMode covers the new predicate directly: 14 cases over env
precedence, invalid/zero/negative ports, env-beats-explicit-dolt_mode, and the
proxied-server exemption including case-insensitivity. (refs be-lbnk8)

* docs(changelog): say the ambient port marks external, not "no longer suppresses auto-start"

The headline claimed an ambient BEADS_DOLT_SERVER_PORT "no longer suppresses
auto-start". This PR does the opposite: check 2c yields ServerModeExternal for
that var, resolveAutoStart (internal/storage/dolt/open.go:223) returns false on
External, and ensureServerRunning (internal/doltserver/doltserver.go:969-985)
refuses to start with "auto-start is suppressed because the server is
externally managed".

Only the reap clause was true. The headline now states both halves as they
behave, matching the entry's own body text.

Review round 3 blocking point 1 (bee-ghosttrack).

* docs(dolt): note that an ambient server port marks the workspace external

docs/architecture/dolt.md presented BEADS_DOLT_SERVER_PORT purely as the port
knob, in both the server-mode connection table and the environment-variable
table. Since check 2c it is also a lifecycle assertion: on a plain
non-shared, non-proxied workspace it resolves ServerModeExternal, so
auto-start is suppressed and PortSourceEnv -- documented at
internal/doltserver/doltserver.go:630 as an authoritative user assertion --
is unreachable for a bd-owned auto-start. A user setting it to pick a port
gets the "externally managed" refusal instead of a server.

Both sites now say so. proxied-server is called out as exempt; shared-server
already resolves external at check 2, before 2c is reached.

Review round 3 non-blocking point 2 (bee-ghosttrack).

* docs(servermode): cite GH#6181 for the IsDoltServerMode gap, not an invisible bead

Both cross-references for the deferred resolver-precedence gap pointed at
be-2nolj, an internal bead id maintainers cannot see -- the reason review
round 3 asked for a GitHub issue. bee-ghosttrack opened GH#6181
("doltserver: ResolveServerMode and configfile.IsDoltServerMode must share
one inference gate") from this review, which is exactly that tracker, so the
comments now name it.

Comment-only; no behavior change.

Review round 3 point 2 follow-up (bee-ghosttrack).

* feat: green — Fix: PR #5934's env-port check reclassifies bd's own server as shared, so it refuses to migrate (refs be-4yy5e)

* chore: remove leaked internal release-gate doc from PR branch

  release-gates/be-lbnk8-serverport-ambient-scope-gate.md

Tracked our internal gc-management/beads-rig release-gate checklist and
should never have been committed to this upstream branch -- it's process
residue from our deploy tooling, not part of the change itself.

Per maintainer bee-ghosttrack's request during review of PR #6571. The
root cause (our deploy tooling auto-committing this file) is already fixed
as of gm-qatxl1; this branch predates that fix, so this commit is cleanup
only -- no other content on this branch is touched.

Ref: be-lk7o3

---------

Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 07:13:57 -07:00

176 lines
7.4 KiB
Go

package doltserver
import (
"fmt"
"os"
"strings"
"github.com/steveyegge/beads/internal/configfile"
)
// ServerMode describes who owns and manages the dolt sql-server lifecycle.
type ServerMode int
const (
// ServerModeOwned means beads auto-starts and manages the server.
// This is the default for standalone users with no explicit port config.
ServerModeOwned ServerMode = iota
// ServerModeExternal means the user manages the server lifecycle
// (e.g., systemd, Docker, Hosted Dolt, VPS). Beads never starts or
// stops the server. Determined when metadata.json has an explicit
// dolt_server_port or BEADS_DOLT_SHARED_SERVER is set.
ServerModeExternal
// ServerModeEmbedded is the legacy in-process embedded dolt path.
// Determined when metadata.json dolt_mode is "embedded".
ServerModeEmbedded
)
// String returns a human-readable label for the server mode.
func (m ServerMode) String() string {
switch m {
case ServerModeOwned:
return "owned"
case ServerModeExternal:
return "external"
case ServerModeEmbedded:
return "embedded"
default:
return fmt.Sprintf("ServerMode(%d)", int(m))
}
}
// ResolveServerMode determines the server mode from the given beadsDir.
// This is the single source of truth for how the server lifecycle is managed.
//
// Decision logic (checked in order):
// 1. BEADS_DOLT_SERVER_MODE=1 env var -> ServerModeExternal
// 2. BEADS_DOLT_SHARED_SERVER env var is set -> ServerModeExternal
// 2b. host-based inference (HostImpliesServerMode) -> ServerModeExternal
// 2c. BEADS_DOLT_SERVER_PORT / BEADS_DOLT_PORT env var -> ServerModeExternal
// 3. metadata.json dolt_mode == "embedded" -> ServerModeEmbedded
// 4. metadata.json has explicit dolt_server_port -> ServerModeExternal
// 5. default -> ServerModeOwned
//
// Runtime env vars (1, 2, 2c) take precedence over persisted metadata.json
// to prevent stale dolt_mode=embedded from silently overriding an active
// shared-server, server-mode, or env-supplied-port configuration (GH#2949).
//
// The function loads metadata.json only if the file exists, to avoid
// triggering the legacy config.json -> metadata.json migration side effect.
func ResolveServerMode(beadsDir string) ServerMode {
return resolveServerMode(beadsDir, true)
}
// ResolveServerModeIgnoringPortEnv is ResolveServerMode with check 2c
// (BEADS_DOLT_SERVER_PORT / BEADS_DOLT_PORT) skipped.
//
// Those env vars are also set ambiently on multi-agent rigs purely to route
// bd's own client connections to a shared coordination server; setting them
// does not disclaim beads' ownership of beadsDir's own local dolt server
// process the way checks 1/2/2b (and metadata.json check 4) genuinely do.
// Callers asking "should I auto-start a server" or "which server should I
// talk to" want the full ResolveServerMode — an ambient port var correctly
// means "route there instead of spawning a redundant one". Callers asking
// "am I allowed to manage/kill OS processes for this directory's server
// lifecycle" — killStaleServersForDir's orphan-cleanup guard (GH#2430) —
// must use this instead, or the ambient routing var falsely disables
// cleanup for a directory beads still owns.
//
// Exported for internal/storage/dolt's sharedServerDatabase (GH#6169):
// once ManagesLiveServerOnPort has PROVEN bd started and tracks the live
// server on cfg.ServerPort for cfg.BeadsDir, an ambient
// BEADS_DOLT_SERVER_PORT/BEADS_DOLT_PORT set purely for multi-agent
// connection routing must not override that proof and reclassify bd's own
// server as shared -- the same reasoning as the kill-guard above, applied
// to the migrate-on-open decision instead of the process-reaping one.
func ResolveServerModeIgnoringPortEnv(beadsDir string) ServerMode {
return resolveServerMode(beadsDir, false)
}
// resolveServerMode is the shared implementation behind ResolveServerMode
// and ResolveServerModeIgnoringPortEnv. honorPortEnv controls whether check
// 2c (BEADS_DOLT_SERVER_PORT / BEADS_DOLT_PORT) participates; see
// ResolveServerModeIgnoringPortEnv for why a caller would want it excluded.
func resolveServerMode(beadsDir string, honorPortEnv bool) ServerMode {
// 1. BEADS_DOLT_SERVER_MODE=1 env var -> external (explicit server mode)
if os.Getenv("BEADS_DOLT_SERVER_MODE") == "1" {
return ServerModeExternal
}
// 2. Shared server mode (env var or config.yaml) -> external.
// Must be checked before metadata.json so that a stale
// dolt_mode=embedded cannot override active shared-server intent.
if IsSharedServerMode() {
return ServerModeExternal
}
var fileCfg *configfile.Config
// Only load config if metadata.json exists (avoids legacy migration side effect)
metadataPath := configfile.ConfigPath(beadsDir)
if _, err := os.Stat(metadataPath); err == nil {
if cfg, loadErr := configfile.Load(beadsDir); loadErr == nil && cfg != nil {
fileCfg = cfg
}
}
// 2b. Host-based inference (GH#3545) -> external. Uses the same
// centralized rule as IsDoltServerMode (explicit-mode gates, env
// suppression, effective-host precedence, proxied exemption) so the
// storage-mode and lifecycle resolvers cannot disagree: a server
// that lives on another machine cannot have a bd-owned lifecycle.
// Runs before the embedded-metadata check because a runtime env
// host beats stale metadata (GH#2949).
hostCfg := fileCfg
if hostCfg == nil {
hostCfg = &configfile.Config{}
}
if hostCfg.HostImpliesServerMode() {
return ServerModeExternal
}
// 2c. Explicit server port via env var (BEADS_DOLT_SERVER_PORT, then
// the legacy BEADS_DOLT_PORT) -> external. Mirrors the deprecated
// GetDoltServerPort()'s own env precedence: the orchestrator sets
// these to signal a server address it manages, port included, so
// ResolveServerMode must agree instead of defaulting a
// port-only deployment to owned (ensureDoltInit would never run for
// it). Runs before the metadata.json checks for the same GH#2949
// reason as 1/2/2b: a runtime env var beats stale persisted metadata.
//
// Skipped when honorPortEnv is false — see resolveServerModeIgnoringPortEnv.
//
// Delegates to the same centralized rule as 2b rather than keeping a
// private copy: PortImpliesServerMode is shaped like HostImpliesServerMode
// (proxied exemption, then the env vars), so the storage-mode and
// lifecycle resolvers read one definition of the port rule.
//
// That a bare port env var outranks an explicit dolt_mode is deliberate
// and settled (be-yb2ai), not an asymmetry with 2b: HostImpliesServerMode
// checks BEADS_DOLT_SERVER_HOST *before* its DoltMode suppression and can
// return on it, so the real precedence there is env > explicit dolt_mode >
// persisted host. 2c mirrors every tier that has a port-side counterpart.
// TestResolveServerMode_EnvPortOverridesStaleEmbedded pins it.
//
// configfile.IsDoltServerMode deliberately does NOT consult this predicate
// — see the note there and GH#6181.
if honorPortEnv && hostCfg.PortImpliesServerMode() {
return ServerModeExternal
}
// 3. Explicit embedded mode in metadata.json
if fileCfg != nil && strings.ToLower(fileCfg.DoltMode) == configfile.DoltModeEmbedded &&
fileCfg.DoltMode != "" { // empty defaults to embedded in GetDoltMode, but we treat empty as "unset"
return ServerModeEmbedded
}
// 4. Explicit server port in metadata.json -> external
if fileCfg != nil && fileCfg.DoltServerPort > 0 {
return ServerModeExternal
}
// 5. Default: beads owns the server
return ServerModeOwned
}