beads/internal/doltserver/servermode.go
mccraigmccraig of the clan mccraig a3a64a83d9
feat(doltserver): add fenced restart and remotesapi listener support (#6020)
* feat(config): model shared remotesapi endpoint

Agent-Signature: omp-gpt-5.6-unknown-reasoning on behalf of mccraigmccraig

* feat(doltserver): manage remotesapi lifecycle

Agent-Signature: omp-gpt-5.6-unknown-reasoning on behalf of mccraigmccraig

* test(doltserver): pin remotesapi lifecycle contracts

Agent-Signature: omp-gpt-5.6-unknown-reasoning on behalf of mccraigmccraig

* fix(doltserver): warn on auto-start remotesapi gap and reword remedy to stop/start

Review fixes for PR #6020 (bee-ghosttrack, 2026-09-03 / 2026-09-25):

- verifyRemotesAPIState guidance no longer names 'bd dolt restart', which
  does not exist in this PR's layer; it now prescribes
  'bd dolt stop && bd dolt start'. Test assertions updated to match.
- EnsureRunningDetailed's fast path warns and keeps serving SQL when a
  running server predates the configured remotesapi listener, instead of
  failing every bd command until a restart. Explicit lifecycle paths
  (Start, adoption) still fail hard. BEADS_DOLT_REMOTESAPI_PORT is a
  pre-existing federation knob, so this running-without-listener state is
  expected on upgrade, not a broken install. Pinned by an added
  EnsureRunningDetailed case in the existing lifecycle integration test.

Agent-Signature: omp-fable-5 on behalf of mccraigmccraig

* docs(changelog): document remotesapi listener rollout and wildcard-bind caveat

Review fixes for PR #6020 (items 2 and 3): BEADS_DOLT_REMOTESAPI_PORT
changes meaning with this PR (federation-check knob -> actually opens the
listener on the managed server), and the listener binds all interfaces
unauthenticated, unlike the 127.0.0.1 SQL listener. Both now land with the
mechanism: a CHANGELOG entry plus the same caveat on Config.RemotesAPIPort.

Agent-Signature: omp-fable-5 on behalf of mccraigmccraig

* fix(review): address adopt-pr review findings for #6020

Maintainer fixup for the four major findings in the attempt-1 synthesis,
plus the two cheap minors in the files already being touched.

major/Change Impact: cmd/bd/doctor/federation.go resolved the remotesapi
port from configfile alone, so a shared server launched from the
user-global dolt.remotesapi-port key was diagnosed against 8080 and
reported StatusError for a correct configuration. Resolve through
doltserver.ResolveRemotesAPIPort (the same chain the launcher uses) and
report a resolved 0 as "listener disabled" instead of dialing port 0.
This also gives the new exported resolver its first production caller.

major/Test Evidence: TestMain redirected HOME to an empty temp dir, which
hid dolt's identity file, so dolt init failed "Author identity unknown"
and TestRecoverPreV56DoltDir and TestEnsureDoltInit_WritesMarker silently
became skips. Configure a dolt identity inside the isolated home
(configureDoltIdentity mirrors lifecycle_integration_test.go's helper,
which this build tag cannot see). Both tests run and pass again; the two
skip messages now name the real cause instead of "dolt may not be
installed".

major/Resource Lifecycle: TestMain called SweepOrphanedTestServers(),
whose own doc says verbatim not to call it from TestMain because the
global arm can reap a still-running foreign suite's servers. Switch to
the suite-scoped pattern already used by testmain_integration_test.go:
SweepDeadSuiteRoots before the run, an owner marker on our own root, and
SweepSuiteTestServers after.

major/Debuggability: EnsureRunningDetailed took the exclusive lifecycle
flock unconditionally, including on the already-running fast path that
was lock-free before the lock unification, so one wedged holder could
hang every bd command on the machine silently and indefinitely. Check
IsRunning first and acquire only when a start is actually needed; the
slow path re-checks under the lock and releases before adopting, keeping
the 500ms ProbeRemotesAPI dial out of the exclusive region.
acquireLifecycleLock now follows the pre-unification two-step pattern:
try non-blocking, and announce on stderr before any blocking wait.

minor/Contract Fidelity: the TestMain comment claimed an isolation
boundary the code did not provide. Clear the operator's whole BEADS_*
namespace by prefix (preserving BEADS_TEST_*) so the claim is true.
Measured: with BEADS_DIR/BEADS_DOLT_SERVER_* exported the package failed
TestDefaultConfigReturnsZeroForStandalone,
TestDefaultConfigPortFileTakesPrecedence and
TestResolveServerMode_HostInferredExternal; it is now green bare.

minor/Test Evidence: add testmain_test.go to the go_test srcs via
make bazel-sync, so a bazel run gets the isolation TestMain too.

Iteration 2: the non-gating minors from the attempt-2 synthesis that
indict text this fixup introduced.

minor/Change Impact: the federation check resolved a mode-dependent port
without classifying the mode, so on a per-project server, which bd never
gives a remotesapi listener, it prescribed "bd dolt stop && bd dolt
start", a loop that reproduces the same error, and its disabled-listener
Detail named a shared server the workspace does not have. Classify once in
a new checkRemotesAPIListener helper (IsSharedServerModeForDir +
ResolveRemotesAPIPortForMode, the same resolution as before): the shared
arm keeps the restart remedy, the per-project arm names --remotesapi-port
<port> or shared-server mode.

minor/Test Evidence: TestCheckRemotesAPIListener covers the running-server
arm the three getter tests never reach: the user-global port, the env
override, and the per-mode remedy and disabled-listener Detail.
Mutation-checked: restoring the shared-only strings reddens exactly the
two per-project subtests; restoring configfile-only resolution reddens
five of six.

minor/Contract Fidelity: dolt reads its global config from DOLT_ROOT_PATH
before HOME, so an exported DOLT_ROOT_PATH broke the TestMain isolation
claim: TestRecoverPreV56DoltDir and TestEnsureDoltInit_WritesMarker went
back to skipping while dolt wrote into the operator's directory. Pin it to
the isolated root. Measured with an identity-less DOLT_ROOT_PATH exported:
both tests SKIP without the pin and PASS with it, and the operator's
directory stays empty.

Not taken: a guard test for the lock-free fast path (the prescribed live
non-dolt PID fixture cannot reach it, since IsRunning's isDoltProcess check
reports such a PID as not running; a real guard needs a real server in the
integration build), and the inert-sweep nit (no test in this build starts
a server, and pinning TMPDIR for the whole suite is broader than the nit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(doltserver): clear port env in target-overrides subtest

Merging main brought in check 2c (#5934): an env-supplied
BEADS_DOLT_SERVER_PORT / BEADS_DOLT_PORT classifies any target external.
ResolveServerModeForMode honors it, so DefaultConfig keeps main's
resolution, but that made this subtest's "want owned" depend on the
developer's shell. Under -tags integration, whose TestMain does not
scrub BEADS_*, it failed on any host exporting a port var, while the
PR head passed the same run. Clear both, as main's own owned-expecting
resolver tests do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

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

183 lines
7.7 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 ResolveServerModeForMode(beadsDir, IsSharedServerMode())
}
// ResolveServerModeForMode resolves lifecycle ownership for an
// already-classified target. BEADS_DOLT_SERVER_MODE remains authoritative;
// shared-server state comes from the caller's target classification rather
// than the active workspace.
func ResolveServerModeForMode(beadsDir string, sharedMode bool) ServerMode {
return resolveServerMode(beadsDir, sharedMode, 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, IsSharedServerMode(), false)
}
// resolveServerMode is the shared implementation behind ResolveServerMode,
// ResolveServerModeForMode and ResolveServerModeIgnoringPortEnv. sharedMode
// is the target's shared-server classification (check 2). 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, sharedMode, 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
}
if sharedMode {
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
}