feat(workspacegate): shared physical-root resolver, beads.OpenGated, and CLI gate wiring (part 2) (#5093)

* feat(workspacegate): wire the gate through a shared physical-root resolver, OpenGated, and the CLI (part 2)

Part 2 of the workspace-gate work started in #5046, which landed the
internal/workspacegate primitive and deliberately held back OpenGated
because its private physical-root derivation was wrong in exactly the
ways review found: it skipped the store's real mode resolution and
silently skipped the physical gate on metadata-less workspaces.

internal/doltserver.ResolvePhysicalRoots is now the one shared answer
to 'which local directory will this workspace's store actually open':
side-effect free (never triggers configfile.Load's legacy-migration
write, never mkdirs the shared-server tree), central-config aware
(the dolt_mode inheritance that previously existed only inside
storage/dolt/open.go), correct for embedded (embeddeddolt, where
ResolveDoltDir answers dolt/), proxied (env > client-info sidecar >
default, hoisted out of package main so it cannot diverge), shared
(no-mkdir path), remote backends (workspace gate only), and the
supported no-metadata layouts (embeddeddolt-then-dolt stat probe).

beads.OpenGated gives library consumers a store that holds SHARED
workspace+physical gates for its lifetime. The CLI acquires at one
chokepoint after workspace resolution - SHARED for store-opening
commands, EXCLUSIVE for backup restore - and in-command for the
noDbCommands that replace state: init, migrate from-*-to-* (both
source and destination roots, ahead of migrate.lock per the normative
lock order), and bootstrap.

Posture is deliberate and asymmetric: SHARED acquisition failures that
are not contention warn once and continue ungated (the gate is
cooperative; normal commands must not brick existing deployments),
while contention aborts with the holder's identity, and EXCLUSIVE
failures of any kind refuse - maintenance must not pretend to a fence
it does not hold. Known residual: discovery-path config loads before
the chokepoint can still fire the legacy-migration write; deferring
that is follow-up scope alongside doctor, secondary-target opens, and
bd dolt set.

Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AQHiBWVPSXDCcUSG9EGw9d

* fix(workspacegate): nil store on failed factory open before gate-release cleanup

newDoltStore's concrete factory branches (e.g. server-mode dolt.New) return
a typed-nil pointer on error; assigning it to the storage.DoltStorage
interface makes 'store != nil' true in closeStoreBeforeGateRelease, which
then calls Close on a nil receiver and panics (SIGSEGV observed in
TestPersistentPreRunHonorsSkipStoreAnnotation, verify run 20260727T000727Z).
No store was opened on that path, so drop the value before the error return.

Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P3JtQ3ukoVmfg6LCKcKBBh

* fix(workspacegate): address review — unparam, gate-busy lock classification, bootstrap dolt-dir gating

Three fixes from the adversarial review of gastownhall/beads#5093
(see reports/2026-07-26-reviewer-dispatch-sweep.md, "#5093" section):

- unparam (CI lint fail): drop the dead PhysicalRoots return value from
  buildWorkspaceGateSet; both call sites already discarded it, and the
  code comments already document that provenance is deliberately not
  surfaced in user-facing errors. Updated both callers.

- TestEmbeddedInitConcurrent regression (CI test fail): the new EXCLUSIVE
  workspace gate in cmd/bd/init.go short-circuits before the embedded
  Dolt flock is ever attempted, so a losing concurrent `bd init` now
  reports gate-busy output that isEmbeddedLockOutput did not recognize.
  Taught isEmbeddedLockOutput to also match workspacegate.ErrBusy's
  "workspace gate busy" text, and added a deterministic
  TestInitGateBusyClassifiedAsLockContention that holds the gate
  in-process and exercises the exact classification path, independent of
  subprocess race timing.

- Bootstrap dolt-dir gating gap: executeBootstrapPlan gated
  plan.BeadsDir's resolved physical roots but not
  doltserver.ResolveDoltDir(plan.BeadsDir), the directory
  executeInitAction/executeRestoreAction/executeJSONLImportAction
  actually open. Pass it as an extraRoot, mirroring how bd init passes
  its own resolved db path.

Also fixes a locally-discovered flake in
TestChokepointSharedExcludesMigrateExclusive: acquireMigrateGates now
threads the package-global rootCtx into acquireExclusiveWorkspaceGates,
so a prior in-process test that ran the full command path (which sets
rootCtx via setupGracefulShutdown and cancels it via rootCancel() without
resetting the var) can leak an already-canceled context into this test.
Pin rootCtx to nil for the test's duration, matching the isolation
pattern already used elsewhere in this file. Reproduced deterministically
by injecting a canceled context before the fix, confirmed neutralized
after.

TestEmbeddedInitConcurrent itself still does not reproduce the CI
gate-busy symptom on this dev machine (10/10 processes succeed within
the 5s exclusive-gate wait, so the test's own "at least 1 lock error"
assertion still fails locally) — that is a machine-speed-dependent
property of the test's contention window, not the classification bug;
the classification fix is independently verified by the new deterministic
test and by code inspection of workspacegate.ErrBusy's text.

Agent-Signature: claude-fable-5-high on behalf of matt wilkie

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
matt wilkie 2026-07-31 01:41:20 -07:00 • committed by GitHub
commit 6d81e1c73a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 1900 additions and 30 deletions

123
beads.go
View file

@ -9,13 +9,20 @@ package beads
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"time"
"github.com/steveyegge/beads/internal/beads"
"github.com/steveyegge/beads/internal/configfile"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/workspacegate"
)
// Storage is the interface for beads storage operations
@ -263,6 +270,117 @@ func OpenFromConfig(ctx context.Context, beadsDir string) (Storage, error) {
return dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
}
// OpenGated is OpenFromConfig plus participation in the workspace
// operation gate: it holds SHARED gates — the workspace gate and the
// physical database-root gate(s) — for the storage's lifetime (released by
// Close), so maintenance operations such as mode migration can DETECT
// this consumer and refuse to run over it, instead of running blind. The
// gate cannot force a holder out (there is no drain signal); it makes
// cooperating consumers visible and excludes new ones. Both levels matter:
// distinct workspaces can share one physical Dolt root, and a
// workspace-only gate would let maintenance replace that root under a
// consumer from another workspace. Library consumers that use the ungated
// Open/OpenFromConfig are invisible to the gate, and gate-aware
// maintenance operations refuse to proceed on workspaces they cannot
// prove quiet — prefer OpenGated in long-lived embedders.
//
// The physical roots are the UNION of doltserver.ResolvePhysicalRoots
// (the side-effect-free CLI-parity resolver: embedded engine's
// embeddeddolt dir, shared-server dir, proxied-server client info) and
// doltserver.LibraryOpenRootPath (the root the library open below —
// which applies central-config defaults and is server-only — will
// actually use), so the gated directory always includes the one this
// store opens. A resolver failure is
// deliberately not fatal here: the same failure will surface from the
// storage open below with a better error, and the workspace gate alone
// still covers the workspace-level maintenance conflicts. For a remote
// server backend there is no local physical root and only the workspace
// gate is taken.
//
// wait bounds how long to poll for the gates when a maintenance
// operation holds one exclusively; zero means fail fast. A busy gate is
// reported as ErrGateBusy (match with errors.Is).
func OpenGated(ctx context.Context, beadsDir string, wait time.Duration) (Storage, error) {
wsGate, err := workspacegate.ForWorkspace(beadsDir)
if err != nil {
return nil, err
}
gates := []workspacegate.Gate{wsGate}
// Gate the UNION of the CLI-parity resolver roots and the root the
// library open path below will actually use (they differ: the library
// path is server-only and applies central-config defaults, so an
// embedded-metadata workspace still opens at DatabasePath). Over-gating
// an extra root under a SHARED hold is benign; under-gating is the bug.
// All gates go into the ONE AcquireAll — never nested.
var roots []string
if pr, rerr := doltserver.ResolvePhysicalRoots(beadsDir); rerr == nil {
roots = append(roots, pr.Roots...)
}
roots = append(roots, doltserver.LibraryOpenRootPath(beadsDir))
for _, root := range roots {
// A root whose PARENT does not exist yet cannot be gated
// (workspacegate requires the gate file's parent) and cannot
// be holding data either; skip it rather than fail the open.
if _, serr := os.Stat(filepath.Dir(root)); serr != nil {
continue
}
physGate, gErr := workspacegate.ForPhysicalRoot(root)
if gErr != nil {
return nil, gErr
}
gates = append(gates, physGate)
}
h, err := workspacegate.AcquireAll(ctx, workspacegate.Shared,
workspacegate.Options{Wait: wait}, gates...)
if err != nil {
return nil, err
}
st, err := dolt.NewFromConfigWithOptions(ctx, beadsDir, &dolt.Config{CreateIfMissing: true})
if err != nil {
rerr := h.Release()
return nil, errors.Join(err, rerr)
}
return &gatedStorage{DoltStorage: st, gate: h}, nil
}
// gatedStorage ties shared gate handles to the storage lifetime: the
// gates are held exactly as long as the store is open. Per the decorator
// contract documented on AsIssueClaimer, it embeds storage.DoltStorage —
// the full engine interface, not the narrow Storage — so every capability
// assertion (RemoteStore, SyncStore, VersionControlReader, EventQuerier,
// ...) keeps working when an embedder switches from OpenFromConfig to
// OpenGated, and it exposes Unwrap for the cmd/bd optional interfaces
// that genuinely need storage.UnwrapStore.
type gatedStorage struct {
storage.DoltStorage
gate *workspacegate.MultiHandle
}
var _ storage.DoltStorage = (*gatedStorage)(nil)
// Unwrap exposes the inner store for storage.UnwrapStore, matching
// HookFiringStore's decorator shape.
func (g *gatedStorage) Unwrap() storage.DoltStorage { return g.DoltStorage }
// Close closes the store, then releases the gates — but only on a clean
// close. A failed or timed-out close can leave in-flight queries against
// the database, and releasing the gates then would let an exclusive
// maintenance operation start against storage that has not quiesced; in
// that case the flocks are deliberately left to die with the process.
func (g *gatedStorage) Close() error {
if err := g.DoltStorage.Close(); err != nil {
// Say so out loud: a long-lived embedder that ignores this error
// would otherwise silently keep excluding exclusive maintenance
// for the rest of the process lifetime.
fmt.Fprintf(os.Stderr,
"warning: beads store close failed; workspace gates deliberately retained until process exit: %v\n", err)
return err
}
return g.gate.Release()
}
// FindDatabasePath finds the beads database in the current directory tree
func FindDatabasePath() string {
return beads.FindDatabasePath()
@ -381,6 +499,11 @@ var (
ErrSelfDependency = domain.ErrSelfDependency
ErrDependencyCycle = domain.ErrDependencyCycle
ErrFieldTooLong = types.ErrFieldTooLong
// ErrGateBusy is returned by OpenGated when a maintenance operation
// holds the workspace or physical-root gate exclusively and the wait
// budget ran out. Alias of the internal sentinel so errors.Is works
// across the package boundary.
ErrGateBusy = workspacegate.ErrBusy
)
// DependencyTypeConflictError is returned by AddDependency when an edge of a

176
beads_gated_test.go Normal file
View file

@ -0,0 +1,176 @@
package beads_test
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads"
"github.com/steveyegge/beads/internal/workspacegate"
)
// OpenGated must fail fast (never reaching the storage open) while a
// maintenance operation holds the workspace gate exclusively, and must
// not leak a shared gate handle when the underlying storage open fails.
// Both paths are environment-independent: neither needs a working store.
func TestOpenGatedGateSemantics(t *testing.T) {
dir := t.TempDir()
beadsDir := filepath.Join(dir, ".beads")
if err := os.Mkdir(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
gate, err := workspacegate.ForWorkspace(beadsDir)
if err != nil {
t.Fatal(err)
}
// Exclusive holder (simulating a mode migration) blocks OpenGated,
// matchable through the exported alias.
h, err := gate.Acquire(context.Background(), workspacegate.Exclusive,
workspacegate.Options{Reason: "test migration"})
if err != nil {
t.Fatal(err)
}
if _, err := beads.OpenGated(context.Background(), beadsDir, 0); !errors.Is(err, beads.ErrGateBusy) {
t.Fatalf("OpenGated under exclusive gate: err = %v, want ErrGateBusy", err)
}
if err := h.Release(); err != nil {
t.Fatal(err)
}
// Error path: a storage-open failure must release the shared gates
// taken on the way in. A beadsDir that is a regular file cannot open
// in any mode or environment.
badDir := filepath.Join(dir, "bad")
if err := os.Mkdir(badDir, 0o755); err != nil {
t.Fatal(err)
}
badBeads := filepath.Join(badDir, ".beads")
if err := os.WriteFile(badBeads, []byte("not a dir"), 0o600); err != nil {
t.Fatal(err)
}
if _, err := beads.OpenGated(context.Background(), badBeads, 0); err == nil {
t.Fatal("OpenGated on a file-as-.beads unexpectedly succeeded")
}
badGate, err := workspacegate.ForWorkspace(badBeads)
if err != nil {
t.Fatal(err)
}
h3, err := badGate.Acquire(context.Background(), workspacegate.Exclusive, workspacegate.Options{})
if err != nil {
t.Fatalf("gate still held after failed OpenGated: %v", err)
}
_ = h3.Release()
}
// OpenGated must gate the LIBRARY open path's root, not only the
// CLI-parity resolver's: an embedded-metadata workspace is opened by the
// library path (server-only, DatabasePath-derived) at .beads/dolt, so an
// exclusive holder on that root must block OpenGated even though the
// resolver alone would only gate .beads/embeddeddolt. Environment
// independent: gate acquisition happens before the storage open.
func TestOpenGatedGatesLibraryRoot(t *testing.T) {
dir := t.TempDir()
beadsDir := filepath.Join(dir, ".beads")
if err := os.Mkdir(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"),
[]byte(`{"backend":"dolt","database":"beads.db","dolt_mode":"embedded"}`), 0o600); err != nil {
t.Fatal(err)
}
// Neutralize any host central config: it must not be able to move the
// library root out from under this assertion.
t.Setenv("BEADS_CENTRAL_CONFIG", filepath.Join(dir, "no-central.json"))
t.Setenv("BEADS_DOLT_DATA_DIR", "")
libGate, err := workspacegate.ForPhysicalRoot(filepath.Join(beadsDir, "dolt"))
if err != nil {
t.Fatal(err)
}
h, err := libGate.Acquire(context.Background(), workspacegate.Exclusive,
workspacegate.Options{Reason: "test holder on library-path root"})
if err != nil {
t.Fatal(err)
}
defer func() { _ = h.Release() }()
if _, err := beads.OpenGated(context.Background(), beadsDir, 0); !errors.Is(err, beads.ErrGateBusy) {
t.Fatalf("OpenGated with EX holder on the library-path root: err = %v, want ErrGateBusy", err)
}
}
// With a working store, OpenGated holds SHARED gates for the storage
// lifetime: other shared holders (a second cooperating consumer) coexist,
// an exclusive acquirer is excluded until Close, and the decorator must
// not amputate extended capabilities (the contract on AsIssueClaimer).
func TestOpenGatedLifecycle(t *testing.T) {
skipIfNoDoltServer(t)
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.Mkdir(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
metadata := fmt.Sprintf(`{"backend":"dolt","database":"dolt","dolt_mode":"server","dolt_server_host":"127.0.0.1","dolt_server_port":%d}`, testServerPort)
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(metadata), 0o644); err != nil {
t.Fatal(err)
}
gate, err := workspacegate.ForWorkspace(beadsDir)
if err != nil {
t.Fatal(err)
}
st, err := beads.OpenGated(context.Background(), beadsDir, 0)
if err != nil {
t.Fatalf("OpenGated: %v", err)
}
// Decorator contract: an embedder switching from OpenFromConfig to
// OpenGated keeps every As*/interface assertion working.
if _, ok := beads.AsIssueClaimer(st); !ok {
t.Error("OpenGated store lost IssueClaimer")
}
if _, ok := beads.AsEventQuerier(st); !ok {
t.Error("OpenGated store lost EventQuerier")
}
if _, ok := beads.AsBlockedQuerier(st); !ok {
t.Error("OpenGated store lost BlockedQuerier")
}
if _, ok := st.(beads.RemoteStore); !ok {
t.Error("OpenGated store lost RemoteStore")
}
if _, ok := st.(beads.SyncStore); !ok {
t.Error("OpenGated store lost SyncStore")
}
if _, ok := st.(beads.VersionControlReader); !ok {
t.Error("OpenGated store lost VersionControlReader")
}
// Shared holders coexist: a second cooperating consumer (equivalent to
// a concurrent OpenGated) acquires the same workspace gate SHARED
// while the first store is open.
shared2, err := gate.Acquire(context.Background(), workspacegate.Shared, workspacegate.Options{})
if err != nil {
t.Fatalf("second shared holder blocked while OpenGated storage open: %v", err)
}
_ = shared2.Release()
// The shared gate is held for the storage lifetime: exclusive
// acquisition fails while open, succeeds after a clean Close.
if _, err := gate.Acquire(context.Background(), workspacegate.Exclusive, workspacegate.Options{}); !errors.Is(err, beads.ErrGateBusy) {
t.Fatalf("exclusive while OpenGated storage open: err = %v, want ErrGateBusy", err)
}
if err := st.Close(); err != nil {
t.Fatalf("Close: %v", err)
}
h2, err := gate.Acquire(context.Background(), workspacegate.Exclusive, workspacegate.Options{})
if err != nil {
t.Fatalf("gate still held after Close: %v", err)
}
_ = h2.Release()
}

View file

@ -539,6 +539,29 @@ func executeBootstrapPlan(plan BootstrapPlan, cfg *configfile.Config, nonInterac
ctx := context.Background()
// Workspace operation gate: every bootstrap action below replaces or
// creates workspace state (sync/restore/jsonl-import/init), and
// bootstrap is a skip-store command that the PersistentPreRunE
// chokepoint never gates. This is the single point where the target
// workspace is known and no state has been touched yet, so acquire the
// workspace + physical-root gates EXCLUSIVELY here for the rest of the
// plan execution. Exclusive failures are hard errors: bootstrap
// refuses to run over live bd activity rather than pretend.
//
// The resolved PhysicalRoots for plan.BeadsDir do not necessarily cover
// the directory the actions below actually open — executeInitAction,
// executeRestoreAction, and executeJSONLImportAction all open
// doltserver.ResolveDoltDir(plan.BeadsDir) directly (e.g. .beads/dolt
// for an embedded-metadata workspace). Pass it as an extraRoot,
// mirroring how bd init passes its own resolved db path, so the
// physical directory bootstrap writes is actually gated.
gateHandle, gateErr := acquireExclusiveWorkspaceGates(ctx, plan.BeadsDir, "bd bootstrap "+plan.Action,
doltserver.ResolveDoltDir(plan.BeadsDir))
if gateErr != nil {
return fmt.Errorf("bd bootstrap refuses to run over live bd activity on this workspace: %w", gateErr)
}
defer func() { _ = gateHandle.Release() }()
switch plan.Action {
case "sync":
return executeSyncAction(ctx, plan, cfg)

View file

@ -838,6 +838,34 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
initDBDirAbs = filepath.Clean(initDBDir)
}
// Workspace operation gate: bd init REPLACES/creates workspace state,
// so it holds the workspace gate (plus any resolvable physical-root
// gates, e.g. a shared-server dolt dir) EXCLUSIVELY for the rest of
// init. init is in noDbCommands, so the PersistentPreRunE chokepoint
// never covers it — this is its own acquisition site. The workspace
// gate file lives BESIDE .beads (<parent>/.beads.gate.lock), so it
// works before .beads exists; the acquisition must come before any
// directory writes below, and before acquireEmbeddedLock (lock
// ordering: gates rank before every other beads lock).
initDBPathAbs, err := filepath.Abs(initDBPath)
if err != nil {
initDBPathAbs = filepath.Clean(initDBPath)
}
// Physical-root gates guard DIRECTORIES. With --db the path can be
// a database FILE; gating it verbatim would create
// <file>.gate.lock and leave the directory that actually holds the
// data ungated, so normalize to the containing directory. A
// nonexistent path is assumed to be a directory (the default
// resolver paths are all dolt data dirs).
if fi, statErr := os.Stat(initDBPathAbs); statErr == nil && !fi.IsDir() {
initDBPathAbs = filepath.Dir(initDBPathAbs)
}
initGateHandle, gateErr := acquireExclusiveWorkspaceGates(rootCtx, beadsDirAbs, "bd init", initDBPathAbs)
if gateErr != nil {
return fmt.Errorf("bd init refuses to run over live bd activity on this workspace: %w", gateErr)
}
defer func() { _ = initGateHandle.Release() }()
// Always create local .beads/ when using default location (CWD/.beads).
// The local directory is needed for metadata.json, config.yaml,
// .gitignore, and hooks — regardless of where dolt data lives.

View file

@ -110,11 +110,20 @@ func envWithout(env []string, name string) []string {
return out
}
// isEmbeddedLockOutput recognizes every "another process holds the lock"
// outcome for concurrent bd commands against the same embedded workspace:
// the embedded Dolt flock's own messages, and the workspacegate EXCLUSIVE
// contention message (workspacegate.ErrBusy = "workspace gate busy"). The
// gate is acquired BEFORE the embedded flock is ever attempted, so a losing
// concurrent `bd init` today reports gate contention rather than a flock
// error — both are the same class of outcome from the caller's point of
// view: another bd process holds the lock, retry later.
func isEmbeddedLockOutput(out string) bool {
out = strings.ToLower(out)
return strings.Contains(out, "one writer at a time") ||
strings.Contains(out, "database is locked") ||
strings.Contains(out, "locked by another dolt process")
strings.Contains(out, "locked by another dolt process") ||
strings.Contains(out, "workspace gate busy")
}
func runCommandBuffers(t *testing.T, cmd *exec.Cmd) (stdout, stderr bytes.Buffer, err error) {
@ -1863,8 +1872,14 @@ func TestEmbeddedInit(t *testing.T) {
})
}
// TestEmbeddedInitConcurrent verifies the exclusive flock prevents concurrent
// writers. Exactly one process should succeed; the rest get the lock error.
// TestEmbeddedInitConcurrent verifies concurrent `bd init` writers are
// serialized rather than corrupting the workspace. The EXCLUSIVE workspace
// gate (see acquireExclusiveWorkspaceGates in cmd/bd/init.go) is acquired
// before the embedded Dolt flock is ever attempted, so contention here
// normally surfaces as gate-busy output rather than a flock error; either is
// classified by isEmbeddedLockOutput as the same "another process holds the
// lock" outcome. At least one process must succeed and at least one must
// see a lock/gate-busy outcome; unexpected errors still fail the test.
func TestEmbeddedInitConcurrent(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt init tests")
@ -1965,3 +1980,44 @@ func TestEmbeddedInitConcurrent(t *testing.T) {
}
}
}
// TestInitGateBusyClassifiedAsLockContention pins the fix for
// TestEmbeddedInitConcurrent's regression: a losing concurrent `bd init`
// that fails because another process holds the workspace gate EXCLUSIVELY
// (rather than hitting the embedded Dolt flock, which the gate now
// short-circuits before it is ever attempted) must still be classified as
// lock contention by isEmbeddedLockOutput, not as an unexpected failure.
// Deterministic and fast: it holds the gate in-process instead of racing
// subprocesses against a wall-clock deadline, so unlike
// TestEmbeddedInitConcurrent it does not depend on the winner's init being
// slow enough to exhaust another process's wait budget.
func TestInitGateBusyClassifiedAsLockContention(t *testing.T) {
resetGateTestEnv(t)
t.Cleanup(releaseWorkspaceGates)
beadsDir := newGateTestWorkspace(t)
oldWait := exclusiveGateWait
exclusiveGateWait = 10 * time.Millisecond
t.Cleanup(func() { exclusiveGateWait = oldWait })
// Simulate the winner: hold the workspace gate EXCLUSIVELY for the
// duration of its init, exactly as cmd/bd/init.go does.
winner, err := acquireExclusiveWorkspaceGates(context.Background(), beadsDir, "test winner init")
if err != nil {
t.Fatalf("winner acquisition: %v", err)
}
defer func() { _ = winner.Release() }()
// Simulate the loser: bd init's own acquisition call, and its own
// error-wrapping (cmd/bd/init.go: "bd init refuses to run over live bd
// activity on this workspace: %w").
_, gateErr := acquireExclusiveWorkspaceGates(context.Background(), beadsDir, "bd init")
if gateErr == nil {
t.Fatal("loser acquisition under a live exclusive holder must fail")
}
loserOutput := fmt.Errorf("bd init refuses to run over live bd activity on this workspace: %w", gateErr).Error()
if !isEmbeddedLockOutput(loserOutput) {
t.Fatalf("gate-busy loser output not classified as lock contention: %q", loserOutput)
}
}

View file

@ -776,7 +776,7 @@ var rootCmd = &cobra.Command{
// No subcommand - show help
_ = cmd.Help() // Help() always returns nil for cobra commands
},
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
PersistentPreRunE: func(cmd *cobra.Command, args []string) (retErr error) {
applyNoColorFlag()
// Initialize CommandContext to hold runtime state (replaces scattered globals)
@ -1174,6 +1174,30 @@ var rootCmd = &cobra.Command{
beadsDir := resolveCommandBeadsDir(dbPath)
prepareSelectedCommandContext(beadsDir, true)
refreshBoundCommandConfig(cmd)
// Workspace operation gate: every command that reaches this point
// will open the store (the skipsStoreInit early return is above),
// so take the workspace + physical-root gates now, in the final
// mode (SHARED for normal commands, EXCLUSIVE for bd backup
// restore — there is no upgrade path). See workspace_gate.go for
// the fail-open/fail-closed posture. The handle is released in
// PersistentPostRunE after store close; if this PreRunE fails
// later, cobra never runs PostRunE, so the deferred release below
// covers the PreRunE error paths after acquisition.
if err := acquireCommandWorkspaceGates(rootCtx, cmd, beadsDir); err != nil {
return err
}
defer func() {
if retErr != nil {
// Gate-outlives-store: a PreRunE failure AFTER the store
// opened (cobra will skip PostRunE) must close the
// store/provider before the gates drop, or maintenance
// could start against un-quiesced storage.
closeStoreBeforeGateRelease()
releaseWorkspaceGates()
}
}()
if _, err := getDoltAutoCommitMode(); err != nil {
return HandleError("%v", err)
}
@ -1415,6 +1439,11 @@ var rootCmd = &cobra.Command{
storeIsReadOnly = doltCfg.ReadOnly
if err != nil {
// A failed factory can return a typed-nil concrete pointer,
// which the interface assignment above makes non-nil; the
// gate-release cleanup would then call Close on a nil
// receiver and panic. No store was opened, so drop it.
store = nil
// Check for fresh clone scenario
if handleFreshCloneError(err) {
return SilentExit()
@ -1509,6 +1538,17 @@ var rootCmd = &cobra.Command{
},
PersistentPostRunE: func(cmd *cobra.Command, args []string) error {
defer restoreChangeDirSelection()
// Release the workspace/physical-root gates on EVERY exit from
// PostRunE — deferred so the early error returns below cannot leak
// the handle past the function. Ordering is enforced, not assumed:
// the success path closes uowProvider/store itself (and nils them),
// making the close call here a no-op; on the early error returns
// the store is still open, so it is closed HERE, before the gates
// drop — gates must always outlive the store.
defer func() {
closeStoreBeforeGateRelease()
releaseWorkspaceGates()
}()
if proxiedServerMode {
if uowProvider != nil {
@ -1579,6 +1619,9 @@ var rootCmd = &cobra.Command{
if store != nil {
_ = store.Close() // Best effort cleanup
// Mark closed so the deferred gate-release cleanup above
// does not double-close it.
store = nil
}
}

View file

@ -162,6 +162,46 @@ func loadMigrateModeConfig(beadsDir string) (*configfile.Config, error) {
return cfg, nil
}
// migrateGateDestRoot resolves the physical root the DESTINATION mode of a
// dolt-mode migration will use, so the migration can gate it alongside the
// source's roots. Both proxied-server migration directions keep the data
// directory in place, so this is the shared dolt dir for --shared flows and
// the per-project dolt data dir otherwise — resolved side-effect-free (no
// mkdir) because gate planning must not create the tree it is guarding.
func migrateGateDestRoot(shared bool, beadsDir string) (string, error) {
if shared {
return doltserver.SharedDoltPath()
}
return doltserver.DoltDirPath(beadsDir), nil
}
// acquireMigrateGates takes the workspace gate plus the physical-root gates
// for BOTH the source mode's roots (via ResolvePhysicalRoots inside
// acquireExclusiveWorkspaceGates) and the destination mode's root, all
// EXCLUSIVE in one AcquireAll. It must run BEFORE acquireMigrateLock:
// the normative lock ordering is workspace gate(s) → physical-root gate(s)
// → migrate.lock → embedded .lock → proxy locks → dolt-server.lock.
func acquireMigrateGates(beadsDir string, shared bool, reason string) (func(), error) {
destRoot, err := migrateGateDestRoot(shared, beadsDir)
if err != nil {
return nil, HandleError("failed to resolve migration destination root: %v", err)
}
h, err := acquireExclusiveWorkspaceGates(rootCtx, beadsDir, reason, destRoot)
if err != nil {
return nil, HandleErrorWithHint(
fmt.Sprintf("cannot migrate while other bd activity holds this workspace: %v", err),
"wait for running bd commands to finish, then retry")
}
return func() { _ = h.Release() }, nil
}
// acquireMigrateLock takes the legacy per-workspace migrate.lock. Known
// hazard, deliberately left as-is: this lock file lives INSIDE .beads and is
// removed on release, which is exactly the split-inode pattern the
// workspacegate package documents as unsafe for operations that replace
// directories. The workspace/physical-root gates acquired above (see
// acquireMigrateGates) are the durable fence; replacing migrate.lock itself
// is out of scope here (PR-B2+).
func acquireMigrateLock(beadsDir string) (func(), error) {
lockPath := filepath.Join(beadsDir, migrateLockFileName)
lock, err := util.TryLock(lockPath)
@ -190,6 +230,11 @@ func runMigrateToProxiedServer(dryRun bool, idleTimeout time.Duration, shared bo
return err
}
if !dryRun {
releaseGates, err := acquireMigrateGates(beadsDir, shared, "bd migrate to proxied-server")
if err != nil {
return err
}
defer releaseGates()
releaseMigrateLock, err := acquireMigrateLock(beadsDir)
if err != nil {
return err
@ -277,6 +322,11 @@ func runMigrateFromProxiedServer(dryRun bool, shared bool) error {
return err
}
if !dryRun {
releaseGates, err := acquireMigrateGates(beadsDir, shared, "bd migrate from proxied-server")
if err != nil {
return err
}
defer releaseGates()
releaseMigrateLock, err := acquireMigrateLock(beadsDir)
if err != nil {
return err

View file

@ -203,18 +203,14 @@ func envOrAbsJoin(envName, beadsDir string) string {
return filepath.Join(beadsDir, p)
}
// resolveProxiedServerRootPath delegates to the exported implementation in
// internal/doltserver so the workspace-gate resolver and the proxy plumbing
// share one root derivation (env → client-info sidecar → default data dir)
// and cannot drift. Note the shared implementation resolves the default via
// the side-effect-free DoltDirPath — same path as proxiedServerRoot, but it
// never mkdirs the shared-server tree just to answer "where is the root".
func resolveProxiedServerRootPath(beadsDir string) (string, error) {
if p := envOrAbsJoin("BEADS_PROXIED_SERVER_ROOT_PATH", beadsDir); p != "" {
return p, nil
}
info, err := configfile.LoadProxiedServerClientInfo(beadsDir)
if err != nil {
return "", err
}
if p := info.ResolvedRootPath(beadsDir); p != "" {
return p, nil
}
return proxiedServerRoot(beadsDir), nil
return doltserver.ResolveProxiedServerRootPath(beadsDir)
}
func resolveProxiedServerConfigPath(beadsDir string) (path string, isCustom bool, err error) {

293
cmd/bd/workspace_gate.go Normal file
View file

@ -0,0 +1,293 @@
package main
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/doltserver"
"github.com/steveyegge/beads/internal/workspacegate"
)
// Workspace operation gate wiring (see internal/workspacegate).
//
// Every store-opening command holds the workspace gate (and the physical
// database-root gate(s)) SHARED for its store/provider lifetime, so
// maintenance operations — mode migration, backup restore, bd init — can
// hold them EXCLUSIVELY and refuse to run over live bd activity instead of
// running blind. Acquisition happens once at the PersistentPreRunE
// chokepoint with the final mode preselected (there is deliberately no
// SH→EX upgrade in workspacegate), and release happens in
// PersistentPostRunE after the store closes.
//
// Posture (deliberate, from the adversarial design review):
//
// - SHARED failures that are NOT contention (resolver error, gate file
// unbuildable, unsupported filesystem) warn once to stderr and continue
// UNGATED. The gate is cooperative; a normal `bd list` must never brick
// an existing deployment because its network mount cannot flock. Note
// the honest reading of fail-open: it means "not DETECTABLY contended",
// not "not contended" — e.g. EACCES on another OS user's 0600 gate file
// beside a cross-user shared root lands here and proceeds ungated even
// though that user may be mid-maintenance (workspacegate documents
// cross-user shared roots as unsupported).
// - ErrBusy on SHARED means an exclusive maintenance operation is live on
// this workspace: abort with an actionable error naming the holder
// (the gate's busy detail carries pid/reason/host from the advisory
// sidecar). Proceeding would race a migration/restore mid-replace.
// - EXCLUSIVE failures of any kind are hard errors: maintenance refuses
// rather than pretends.
//
// Known residual (PR-B2 scope, documented honestly): the pre-chokepoint
// DISCOVERY code paths (configfile.Load at main.go's early config probe and
// internal/beads.findDatabaseInBeadsDir) can perform the legacy
// config.json→metadata.json migration write BEFORE this gate is acquired —
// the chokepoint necessarily runs after workspace selection. Deferring that
// legacy write behind the gate is out of scope here.
// workspaceGateHandle is the gate set held for the current command, stored
// beside `store` because their lifetimes are paired: acquired just before
// the store-opening phase of PersistentPreRunE, released after store close
// in PersistentPostRunE. nil when the command runs ungated (skipsStoreInit
// path, fail-open posture, or no workspace on disk).
var workspaceGateHandle *workspacegate.MultiHandle
// exclusiveGateWait is how long EXCLUSIVE acquisitions poll before giving
// up: long enough to ride out a short-lived `bd list` finishing, short
// enough that a genuinely busy workspace fails with a clear message rather
// than hanging. SHARED acquisitions stay non-blocking (a live exclusive
// holder is a migration/restore — waiting seconds will not outlast it, and
// normal commands should fail fast with the holder's name). A var, not a
// const, so tests can shorten it.
var exclusiveGateWait = 5 * time.Second
// exclusiveGateOptions builds the acquisition options for an EXCLUSIVE
// hold: bounded wait, holder-info reason, and a single stderr note when the
// first attempt comes back busy so the wait does not look like a hang.
func exclusiveGateOptions(reason string) workspacegate.Options {
return workspacegate.Options{
Wait: exclusiveGateWait,
Reason: reason,
OnWait: func(holder string) {
if !quietFlag {
// %q: the holder string comes from another process's gate
// sidecar; quoting neutralizes terminal escape sequences a
// hostile or corrupt sidecar could smuggle into stderr.
fmt.Fprintf(os.Stderr, "waiting for other bd commands to finish (%q)...\n", holder) //nolint:gosec // G705: stderr, not a browser context; %q additionally neutralizes terminal escapes
}
},
}
}
// closeStoreBeforeGateRelease enforces "gates outlive the store" on the
// error exits: PersistentPostRunE's early returns (auto-commit/auto-export
// failures) and PersistentPreRunE failures after the store opened would
// otherwise release the gates while the store is still open, letting an
// exclusive maintenance operation start against storage that has not
// quiesced. Close whatever is still open, then release. The success paths
// nil out store/uowProvider after their own close, so this is a no-op
// there.
func closeStoreBeforeGateRelease() {
ctx := rootCtx
if ctx == nil {
ctx = context.Background()
}
if uowProvider != nil {
_ = uowProvider.Close(ctx) // Best effort: we are on an error exit already
uowProvider = nil
}
if store != nil {
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
_ = store.Close() // Best effort: we are on an error exit already
store = nil
}
}
// releaseWorkspaceGates drops the command's gate set. Idempotent and
// nil-safe (MultiHandle.Release is once-guarded per handle), so it is safe
// to call from every exit path — PersistentPostRunE's deferred cleanup and
// PersistentPreRunE's error paths both call it, and double release is a
// no-op.
func releaseWorkspaceGates() {
if workspaceGateHandle != nil {
_ = workspaceGateHandle.Release() // Best effort: the flock dies with the process anyway
workspaceGateHandle = nil
}
}
// commandNeedsExclusiveGate classifies the store-opening commands that
// REPLACE storage rather than use it. Currently only `bd backup restore`
// flows through the chokepoint and needs exclusivity; `bd init` and the
// `bd migrate from-*-to-*` family are in the skip-store lists and acquire
// their exclusive gates inside their own Run functions instead.
func commandNeedsExclusiveGate(cmd *cobra.Command) bool {
return cmd.Name() == "restore" && cmd.Parent() != nil && cmd.Parent().Name() == "backup"
}
// buildWorkspaceGateSet resolves the workspace gate plus the physical-root
// gates for whatever the open path will actually open, appending any
// extraRoots (used by migrate to cover the DESTINATION mode's root as well
// as the source's). Roots whose parent directory does not exist are skipped:
// workspacegate needs the gate file's parent, and a root whose parent is
// absent cannot be holding data anyone could clobber.
//
// The resolver's PhysicalRoots provenance is deliberately NOT returned: both
// callers discard it today, and the code comments at each call site already
// explain that provenance is intentionally not surfaced in user-facing
// errors (it names which directory got gated, not who holds it — the gate's
// own busy detail already names the holder).
func buildWorkspaceGateSet(beadsDir string, extraRoots ...string) ([]workspacegate.Gate, error) {
pr, err := doltserver.ResolvePhysicalRoots(beadsDir)
if err != nil {
return nil, err
}
wsGate, err := workspacegate.ForWorkspace(pr.BeadsDir)
if err != nil {
return nil, err
}
gates := []workspacegate.Gate{wsGate}
roots := append(append([]string{}, pr.Roots...), extraRoots...)
for _, root := range roots {
if _, serr := os.Stat(filepath.Dir(root)); serr != nil {
continue
}
g, gerr := workspacegate.ForPhysicalRoot(root)
if gerr != nil {
return nil, gerr
}
gates = append(gates, g)
}
return gates, nil
}
// acquireCommandWorkspaceGates is the chokepoint acquisition for
// store-opening commands, called from PersistentPreRunE right after the
// workspace is selected. It stores the handle in workspaceGateHandle on
// success; on the fail-open paths it returns nil with no handle.
func acquireCommandWorkspaceGates(ctx context.Context, cmd *cobra.Command, beadsDir string) error {
exclusive := commandNeedsExclusiveGate(cmd)
// No workspace on disk: nothing to guard, and the store-open path will
// produce its own (better) "no database found" error. Gating here would
// scatter .gate.lock files into arbitrary directories users run bd in.
if _, err := os.Stat(beadsDir); err != nil {
return nil
}
gates, err := buildWorkspaceGateSet(beadsDir)
if err != nil {
if exclusive {
return HandleErrorRespectJSON("workspace gate: %v", err)
}
if !quietFlag {
fmt.Fprintf(os.Stderr, "warning: workspace gate unavailable, continuing ungated: %v\n", err)
}
return nil
}
mode := workspacegate.Shared
opts := workspacegate.Options{}
if exclusive {
mode = workspacegate.Exclusive
opts = exclusiveGateOptions("bd backup restore")
}
h, err := workspacegate.AcquireAll(ctx, mode, opts, gates...)
if err != nil {
if errors.Is(err, workspacegate.ErrBusy) {
// Contention is never fail-open, in either mode — but the two
// modes are blocked by OPPOSITE kinds of holders, so the
// message must not claim "a maintenance operation" for both:
// a SHARED attempt is blocked only by an exclusive maintenance
// holder, while an EXCLUSIVE attempt (backup restore) is
// usually blocked by ordinary shared commands.
if exclusive {
return HandleErrorRespectJSON("other bd commands are using this workspace; wait for them to finish and retry: %v", err)
}
return HandleErrorRespectJSON("a maintenance operation is running on this workspace; retry when it completes: %v", err)
}
if exclusive {
return HandleErrorRespectJSON("workspace gate: %v", err)
}
if !quietFlag {
fmt.Fprintf(os.Stderr, "warning: workspace gate acquisition failed, continuing ungated: %v\n", err)
}
return nil
}
workspaceGateHandle = h
return nil
}
// acquireExclusiveWorkspaceGates is the maintenance-side acquisition used by
// bd init and bd migrate, which live on the skip-store path and therefore
// never reach the chokepoint. It takes the workspace gate plus the resolved
// physical roots (when .beads exists — bd init on a fresh directory has
// nothing to resolve yet) plus any extraRoots, all EXCLUSIVE in ONE
// AcquireAll (never nested — that is a workspacegate invariant). Failures
// are returned, not softened: maintenance refuses rather than pretends.
//
// Lock ordering (normative for the callers): workspace gate(s) →
// physical-root gate(s) → migrate.lock → embedded .lock → proxy locks →
// dolt-server.lock.
//
// Re-entrancy hazard for future callers: an EXCLUSIVE holder that shells
// out to git can re-enter bd through git hooks — the bd hook wrappers spawn
// `bd export`/similar, which flows through the chokepoint, attempts a
// SHARED acquisition against our own exclusive hold, and dies with ErrBusy.
// bd init is safe today because its git plumbing runs with
// `-c core.hooksPath=` / --no-verify; any future maintenance command that
// acquires these gates and then runs git must do the same, or the hook's
// child bd will fail (fail-closed, but confusing).
func acquireExclusiveWorkspaceGates(ctx context.Context, beadsDir, reason string, extraRoots ...string) (*workspacegate.MultiHandle, error) {
// Defense against callers that computed no workspace (bootstrap plans
// are the untrusted case): gating "" would resolve against the CWD and
// fence an arbitrary directory.
if strings.TrimSpace(beadsDir) == "" {
return nil, errors.New("workspace gate: empty beads directory")
}
// Normalize a nil context (tests and helpers call maintenance paths
// directly, before the process-level signal context exists); the
// workspacegate package also defends, but do not rely on callees.
if ctx == nil {
ctx = context.Background()
}
var gates []workspacegate.Gate
if _, err := os.Stat(beadsDir); err == nil {
var gerr error
gates, gerr = buildWorkspaceGateSet(beadsDir, extraRoots...)
if gerr != nil {
return nil, gerr
}
} else {
// .beads does not exist yet (bd init creating it): the workspace
// gate still works because its file lives BESIDE .beads in the
// project directory, which does exist. Physical-root gates for
// in-.beads roots are impossible (no parent) and unnecessary —
// exclusivity on the workspace gate already excludes every gated
// opener. Out-of-.beads extraRoots are still gated when their
// parent exists.
wsGate, werr := workspacegate.ForWorkspace(beadsDir)
if werr != nil {
return nil, werr
}
gates = []workspacegate.Gate{wsGate}
for _, root := range extraRoots {
if _, serr := os.Stat(filepath.Dir(root)); serr != nil {
continue
}
g, gerr := workspacegate.ForPhysicalRoot(root)
if gerr != nil {
return nil, gerr
}
gates = append(gates, g)
}
}
return workspacegate.AcquireAll(ctx, workspacegate.Exclusive,
exclusiveGateOptions(reason), gates...)
}

View file

@ -0,0 +1,197 @@
package main
import (
"context"
"os"
"path/filepath"
"testing"
"time"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/workspacegate"
)
// resetGateTestEnv pins every env var the physical-root resolver consults so
// a developer machine's beads setup (shared-server mode, custom data dirs,
// central config) cannot change which gates these tests acquire.
func resetGateTestEnv(t *testing.T) {
t.Helper()
for _, k := range []string{
"BEADS_DOLT_SERVER_MODE",
"BEADS_DOLT_SHARED_SERVER",
"BEADS_DOLT_DATA_DIR",
"BEADS_DOLT_SERVER_HOST",
"BEADS_PROXIED_SERVER_ROOT_PATH",
"BEADS_SHARED_SERVER_DIR",
} {
t.Setenv(k, "")
}
t.Setenv("BEADS_CENTRAL_CONFIG", filepath.Join(t.TempDir(), "no-central.json"))
}
func newGateTestWorkspace(t *testing.T) string {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
meta := `{"backend":"dolt","database":"beads.db","dolt_mode":"embedded"}`
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(meta), 0o600); err != nil {
t.Fatal(err)
}
return beadsDir
}
func TestCommandNeedsExclusiveGate(t *testing.T) {
root := &cobra.Command{Use: "bd"}
backup := &cobra.Command{Use: "backup"}
backupRestore := &cobra.Command{Use: "restore [path]"}
backup.AddCommand(backupRestore)
root.AddCommand(backup)
// Top-level `bd restore <issue-id>` is an ISSUE restore
// (cmd/bd/restore.go), not a database restore: it must stay SHARED.
issueRestore := &cobra.Command{Use: "restore [issue-id]"}
root.AddCommand(issueRestore)
list := &cobra.Command{Use: "list"}
root.AddCommand(list)
cases := []struct {
name string
cmd *cobra.Command
want bool
}{
{"backup restore is exclusive", backupRestore, true},
{"top-level issue restore is not", issueRestore, false},
{"list is not", list, false},
{"backup parent is not", backup, false},
{"root is not", root, false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := commandNeedsExclusiveGate(tc.cmd); got != tc.want {
t.Errorf("commandNeedsExclusiveGate(%s) = %v, want %v", tc.cmd.Name(), got, tc.want)
}
})
}
}
func TestAcquireCommandWorkspaceGatesAbsentWorkspace(t *testing.T) {
resetGateTestEnv(t)
t.Cleanup(releaseWorkspaceGates)
list := &cobra.Command{Use: "list"}
missing := filepath.Join(t.TempDir(), "nope", ".beads")
if err := acquireCommandWorkspaceGates(context.Background(), list, missing); err != nil {
t.Fatalf("absent beadsDir must be silently ungated, got %v", err)
}
if workspaceGateHandle != nil {
t.Error("absent beadsDir must leave no gate handle")
}
}
func TestAcquireCommandWorkspaceGatesBlockedByExclusiveHolder(t *testing.T) {
resetGateTestEnv(t)
t.Cleanup(releaseWorkspaceGates)
beadsDir := newGateTestWorkspace(t)
gate, err := workspacegate.ForWorkspace(beadsDir)
if err != nil {
t.Fatal(err)
}
holder, err := gate.Acquire(context.Background(), workspacegate.Exclusive,
workspacegate.Options{Reason: "test maintenance"})
if err != nil {
t.Fatal(err)
}
defer func() { _ = holder.Release() }()
list := &cobra.Command{Use: "list"}
if err := acquireCommandWorkspaceGates(context.Background(), list, beadsDir); err == nil {
t.Fatal("SHARED acquisition under a foreign exclusive holder must abort, got nil error")
}
if workspaceGateHandle != nil {
t.Error("failed acquisition must leave no gate handle")
}
}
func TestReleaseWorkspaceGatesIdempotent(t *testing.T) {
resetGateTestEnv(t)
beadsDir := newGateTestWorkspace(t)
list := &cobra.Command{Use: "list"}
if err := acquireCommandWorkspaceGates(context.Background(), list, beadsDir); err != nil {
t.Fatal(err)
}
if workspaceGateHandle == nil {
t.Fatal("expected a held gate handle")
}
releaseWorkspaceGates()
if workspaceGateHandle != nil {
t.Error("handle must be cleared on release")
}
// Second release must be a no-op, not a panic or double-unlock.
releaseWorkspaceGates()
// And the gate must actually be free again: an exclusive acquisition
// succeeds after release.
gate, err := workspacegate.ForWorkspace(beadsDir)
if err != nil {
t.Fatal(err)
}
h, err := gate.Acquire(context.Background(), workspacegate.Exclusive, workspacegate.Options{})
if err != nil {
t.Fatalf("gate still held after releaseWorkspaceGates: %v", err)
}
_ = h.Release()
}
// The cross-wiring guarantee: a chokepoint SHARED hold (a normal command
// mid-flight) excludes acquireMigrateGates' EXCLUSIVE acquisition on the
// same workspace. Also exercises the nil-rootCtx path inside
// acquireMigrateGates (tests have no process signal context), which used to
// panic before the nil-context normalization.
func TestChokepointSharedExcludesMigrateExclusive(t *testing.T) {
resetGateTestEnv(t)
t.Cleanup(releaseWorkspaceGates)
beadsDir := newGateTestWorkspace(t)
// rootCtx is a package global that production sets via
// setupGracefulShutdown() in PersistentPreRunE and cancels via
// rootCancel() in PersistentPostRunE WITHOUT resetting the var to nil —
// harmless in production (the process exits), but any earlier in-process
// test that exercises the full command path (Execute()) leaves rootCtx
// pointing at an already-canceled context for whatever test runs next in
// the same binary. acquireMigrateGates now threads rootCtx through to
// acquireExclusiveWorkspaceGates, so this test is sensitive to that
// leak: pin it to nil (the documented "no process signal context yet"
// case this test exercises) regardless of what ran before it.
oldRootCtx := rootCtx
rootCtx = nil
t.Cleanup(func() { rootCtx = oldRootCtx })
oldWait := exclusiveGateWait
exclusiveGateWait = 10 * time.Millisecond
t.Cleanup(func() { exclusiveGateWait = oldWait })
list := &cobra.Command{Use: "list"}
if err := acquireCommandWorkspaceGates(context.Background(), list, beadsDir); err != nil {
t.Fatal(err)
}
if workspaceGateHandle == nil {
t.Fatal("expected a held shared gate handle")
}
release, err := acquireMigrateGates(beadsDir, false, "test migrate")
if err == nil {
release()
t.Fatal("migrate EXCLUSIVE acquisition must fail while the chokepoint holds SHARED")
}
// After the shared holder releases, the migration proceeds.
releaseWorkspaceGates()
release, err = acquireMigrateGates(beadsDir, false, "test migrate")
if err != nil {
t.Fatalf("migrate acquisition after shared release: %v", err)
}
release()
}

View file

@ -288,21 +288,10 @@ func ResolveDoltDir(beadsDir string) string {
}
}
// Check env var first (highest priority)
if d := os.Getenv("BEADS_DOLT_DATA_DIR"); d != "" {
if filepath.IsAbs(d) {
return d
}
return filepath.Join(beadsDir, d)
}
// Only load config if metadata.json exists (avoids legacy migration side effect)
metadataPath := filepath.Join(beadsDir, "metadata.json")
if _, err := os.Stat(metadataPath); err == nil {
if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil {
return cfg.DatabasePath(beadsDir)
}
}
return filepath.Join(beadsDir, "dolt")
// Env var, metadata.json dolt_data_dir (stat-guarded), then default —
// shared with the side-effect-free DoltDirPath so the two resolvers
// cannot drift.
return projectDoltDirPath(beadsDir)
}
// Config holds the server configuration.

View file

@ -0,0 +1,389 @@
package doltserver
import (
"fmt"
"os"
"path/filepath"
"strings"
"github.com/steveyegge/beads/internal/configfile"
)
// PhysicalRoots describes the local physical database root(s) a store open
// for the given workspace will actually touch, so the workspace-gate wiring
// (cmd/bd chokepoint, bd init/migrate/restore, beads.OpenGated) can gate the
// directory the store will USE — not the directory any single existing
// resolver claims. That distinction is the whole reason this function exists:
// ResolveDoltDir reports .beads/dolt for embedded workspaces whose engine
// actually opens .beads/embeddeddolt, and central-config mode inheritance
// (~/.config/beads/server.json) is applied only deep inside the storage open
// path — a naive resolver that misses either would gate the wrong directory
// and let a migration replace a root out from under a live store.
type PhysicalRoots struct {
// BeadsDir is the absolute path of the workspace .beads directory
// the resolution was computed for.
BeadsDir string
// Roots are the absolute local physical DB roots to gate. Empty when
// the backend is remote (RemoteBackend true): bd opens no local files
// for a remote server, so there is nothing physical to gate — only
// the workspace gate applies.
Roots []string
// Mode is the connection mode the open path will actually use:
// "embedded" | "server" | "shared-server" | "proxied-server".
Mode string
// Provenance is a one-line human explanation of how Mode and Roots
// were decided, for busy/diagnostic messages ("why is bd gating that
// directory?").
Provenance string
// RemoteBackend is true when the backend is a server on a non-local
// host: workspace gate only, no physical gate.
RemoteBackend bool
}
// SharedDoltPath returns the dolt data directory path for the shared server
// (~/.beads/shared-server/dolt, or under BEADS_SHARED_SERVER_DIR) WITHOUT
// creating it. SharedDoltDir is the mkdir-on-first-use variant; resolution
// paths that must be side-effect free (gate planning, dry runs) use this one.
func SharedDoltPath() (string, error) {
dir, err := SharedServerPath()
if err != nil {
return "", err
}
return filepath.Join(dir, "dolt"), nil
}
// projectDoltDirPath resolves the per-project dolt data directory without
// consulting shared-server mode and without side effects:
// BEADS_DOLT_DATA_DIR env (absolute as-is, relative joined to beadsDir) →
// metadata.json dolt_data_dir via Config.DatabasePath (stat-guarded so the
// legacy config.json→metadata.json migration write in configfile.Load can
// never fire from a pure path resolution) → default beadsDir/dolt.
func projectDoltDirPath(beadsDir string) string {
if d := os.Getenv("BEADS_DOLT_DATA_DIR"); d != "" {
if filepath.IsAbs(d) {
return d
}
return filepath.Join(beadsDir, d)
}
// Only load config if metadata.json exists (avoids legacy migration side effect)
if _, err := os.Stat(configfile.ConfigPath(beadsDir)); err == nil {
if cfg, err := configfile.Load(beadsDir); err == nil && cfg != nil {
return cfg.DatabasePath(beadsDir)
}
}
return filepath.Join(beadsDir, "dolt")
}
// DoltDirPath is the side-effect-free twin of ResolveDoltDir: identical path
// resolution (shared-server dir wins, then env, then metadata, then
// beadsDir/dolt) but it never creates the shared-server directories.
// ResolveDoltDir keeps its mkdir-on-first-use behavior for callers that are
// about to start a server there; pure resolution (gate planning, proxied
// root fallback) must use this one so that merely ASKING where the data
// lives cannot create ~/.beads trees.
func DoltDirPath(beadsDir string) string {
if IsSharedServerMode() {
if dir, err := SharedDoltPath(); err == nil {
return dir
}
// Mirror ResolveDoltDir: an unresolvable shared dir (no home
// directory) falls through to per-project resolution.
}
return projectDoltDirPath(beadsDir)
}
// ResolveProxiedServerRootPath resolves the physical root directory of a
// proxied-server workspace. This logic used to live unexported in
// cmd/bd/proxied_server.go; it is exported here so the workspace-gate
// resolver and the CLI proxy plumbing share ONE implementation and cannot
// drift (a divergent copy would gate a different directory than the proxy
// actually serves). Precedence:
//
// 1. BEADS_PROXIED_SERVER_ROOT_PATH env (absolute as-is, relative joined
// to beadsDir);
// 2. the .beads/proxied_server_client_info.json sidecar's root_path
// (which migrate_dolt_mode writes — it can legitimately be the shared
// dir ~/.beads/shared-server/dolt or an arbitrary absolute path);
// 3. the default dolt data dir for the workspace (DoltDirPath).
//
// The fallback deliberately uses the side-effect-free DoltDirPath rather
// than ResolveDoltDir: the resolved path is identical, but resolution must
// not create shared-server directories as a side effect. Callers that start
// the proxy create the directory themselves when they actually need it.
func ResolveProxiedServerRootPath(beadsDir string) (string, error) {
if p := os.Getenv("BEADS_PROXIED_SERVER_ROOT_PATH"); p != "" {
if !filepath.IsAbs(p) {
p = filepath.Join(beadsDir, p)
}
return p, nil
}
info, err := configfile.LoadProxiedServerClientInfo(beadsDir)
if err != nil {
return "", err
}
if p := info.ResolvedRootPath(beadsDir); p != "" {
return p, nil
}
return DoltDirPath(beadsDir), nil
}
// applyCentralModeDefaults mirrors the central-config merge the LIBRARY open
// path performs (internal/storage/dolt/open.go applyCentralConfigDefaults):
// load ~/.config/beads/server.json (or BEADS_CENTRAL_CONFIG) and apply its
// server fields — DoltMode, host, port, user, TLS, never data dirs — as
// defaults for fields the project config leaves empty.
//
// This is deliberately NOT part of ResolvePhysicalRoots: the CLI's
// hand-built store selection in cmd/bd/main.go never consults the central
// config, so CLI gate planning must not either (it would gate a server root
// the CLI would not open). It exists for LibraryOpenRootPath, which mirrors
// the library path where the merge DOES apply.
//
// A missing central config is a silent no-op, and a BROKEN central config is
// also skipped (the open path warns and proceeds without it; this pure
// resolver stays quiet and mirrors the "proceed without" behavior so both
// paths land on the same mode).
func applyCentralModeDefaults(cfg *configfile.Config) {
centralPath := os.Getenv("BEADS_CENTRAL_CONFIG")
if centralPath == "" {
centralPath = configfile.DefaultCentralConfigPath()
}
if centralPath == "" {
return
}
centralCfg, err := configfile.LoadCentralConfig(centralPath)
if err != nil {
return
}
configfile.ApplyCentralDefaults(cfg, centralCfg)
}
// isRemoteServerHost reports whether a dolt server host points off-machine.
// Local spellings (empty, localhost, loopback — including the bracketed
// IPv6 form a host:port split leaves behind) mean bd may still manage local
// files for the server; anything else means the data lives elsewhere and
// there is no local physical root to gate. The local set mirrors the
// storage layer's isLocalHost (internal/storage/dolt/store.go) so gate
// planning and connection handling agree on what "local" means.
func isRemoteServerHost(host string) bool {
switch strings.ToLower(strings.TrimSpace(host)) {
case "", "localhost", "127.0.0.1", "::1", "[::1]":
return false
}
return true
}
// ResolvePhysicalRoots computes, WITHOUT side effects, the physical database
// root(s) that opening the given workspace would actually use, along with
// the effective connection mode. It exists for gate planning: workspace-gate
// acquisition must fence the same directory the store will open, and must be
// safe to call from paths (doctor, library consumers, dry runs) that have
// not consented to any writes.
//
// Side-effect freedom is load-bearing and non-obvious, because the obvious
// building blocks all write:
//
// - configfile.Load performs a legacy config.json→metadata.json MIGRATION
// WRITE when metadata.json is absent — so every Load here is guarded by
// an os.Stat of metadata.json first, exactly as ResolveServerMode does;
// - doltserver.SharedServerDir/SharedDoltDir MKDIR on first use — so the
// shared root comes from SharedServerPath/SharedDoltPath instead.
//
// Parity target — this function mirrors the CLI's hand-built store
// selection in cmd/bd/main.go, EXACTLY and only that. The LIBRARY open path
// (internal/storage/dolt/open.go via beads.OpenFromConfig) is broader: it
// substitutes DefaultConfig when metadata.json is absent and applies
// central-config defaults (~/.config/beads/server.json) either way, so it
// can land on server mode where the CLI lands on embedded. Consumers gating
// the library path (beads.OpenGated) must union these roots with
// LibraryOpenRootPath. Three copies of mode selection now exist (main.go,
// open.go, here); collapsing them into one exported ResolveEffectiveMode is
// deliberate follow-up scope, not this function's job — until then, CLI
// parity here is the conservative choice because the CLI is what acquires
// gates through the chokepoint, and gating a root the CLI will not open
// would exclude maintenance from the wrong directory.
//
// Mode decision (ordering is significant and each step cites the CLI
// behavior it mirrors):
//
// 1. proxied-server: metadata dolt_mode=proxied-server wins outright —
// main.go routes proxied workspaces to the proxy provider before the
// shared-server rescue, which explicitly excludes ProxiedServer. Root
// via ResolveProxiedServerRootPath.
// 2. shared-server: IsSharedServerMode (env BEADS_DOLT_SHARED_SERVER or
// config.yaml dolt.shared-server) wins over remaining metadata — a
// stale dolt_mode=embedded must not override active shared intent
// (mirrors ResolveDoltDir and the main.go no-config rescue, GH#3817).
// Root = SharedServerPath()/dolt, no mkdir. This is also the ONLY
// rescue the CLI applies when metadata.json is absent.
// 3. server: configfile.IsDoltServerMode only (env BEADS_DOLT_SERVER_MODE,
// metadata dolt_mode, config.yaml dolt.mode fallback). Deliberately NO
// dolt_server_port>0 heuristic: `bd init --server-port N` without
// --server writes dolt_mode=embedded AND a port, the CLI opens
// embeddeddolt, and ResolveServerMode itself gives an explicit
// dolt_mode=embedded precedence over the port. And deliberately NO
// central-config promotion — the CLI never applies central config. A
// remote host (dolt_server_host beyond the loopback/localhost set)
// means RemoteBackend=true and NO local roots; a local host roots at
// Config.DatabasePath semantics (BEADS_DOLT_DATA_DIR / dolt_data_dir /
// beadsDir/dolt).
// 4. embedded (metadata present, GetDoltMode default): root is
// beadsDir/embeddeddolt — hardcoded in the embedded engine
// (internal/storage/embeddeddolt), which is precisely where
// ResolveDoltDir is wrong (it reports beadsDir/dolt) and why this
// function does not reuse it wholesale.
// 5. no metadata.json: after the shared-server rescue, mirror the open
// path's discovery fallback (internal/beads findDatabaseInBeadsDir):
// an embeddeddolt/ dir means embedded, else a dolt/ dir means a
// server-layout workspace, else default to the embedded root (which
// may not exist yet — gating a not-yet-existing root is fine, the gate
// file lives beside it and workspacegate only requires the PARENT to
// exist). The CLI's nil-config branch honors no other env rescue.
//
// Roots are returned absolute. Symlink canonicalization is deliberately NOT
// performed here: workspacegate.ForPhysicalRoot canonicalizes the gate
// file's parent itself (and refuses symlinked roots), and resolving here too
// would double-handle and could disagree with the gate's own rules.
func ResolvePhysicalRoots(beadsDir string) (PhysicalRoots, error) {
abs, err := filepath.Abs(beadsDir)
if err != nil {
return PhysicalRoots{}, fmt.Errorf("resolving beads dir %s: %w", beadsDir, err)
}
abs = filepath.Clean(abs)
pr := PhysicalRoots{BeadsDir: abs}
// Side-effect-free config load: never trigger the legacy config.json
// migration. Absent metadata.json is treated as cfg == nil.
var cfg *configfile.Config
if _, statErr := os.Stat(configfile.ConfigPath(abs)); statErr == nil {
loaded, loadErr := configfile.Load(abs)
if loadErr != nil {
// A present-but-broken metadata.json is authoritative: the open
// path refuses to fall back, so gate planning refuses to guess.
return PhysicalRoots{}, fmt.Errorf("loading config for gate resolution: %w", loadErr)
}
cfg = loaded
}
addRoot := func(root string) error {
rootAbs, aerr := filepath.Abs(root)
if aerr != nil {
return fmt.Errorf("resolving physical root %s: %w", root, aerr)
}
pr.Roots = append(pr.Roots, filepath.Clean(rootAbs))
return nil
}
switch {
case cfg != nil && cfg.IsDoltProxiedServerMode():
pr.Mode = "proxied-server"
root, perr := ResolveProxiedServerRootPath(abs)
if perr != nil {
return PhysicalRoots{}, fmt.Errorf("resolving proxied-server root: %w", perr)
}
pr.Provenance = fmt.Sprintf("metadata.json dolt_mode=proxied-server; root %s via env/client-info/default", root)
if err := addRoot(root); err != nil {
return PhysicalRoots{}, err
}
case IsSharedServerMode():
pr.Mode = "shared-server"
root, serr := SharedDoltPath()
if serr != nil {
return PhysicalRoots{}, fmt.Errorf("resolving shared-server root: %w", serr)
}
pr.Provenance = fmt.Sprintf("shared-server mode active (BEADS_DOLT_SHARED_SERVER or config.yaml dolt.shared-server), overriding any metadata dolt_mode; root %s", root)
if err := addRoot(root); err != nil {
return PhysicalRoots{}, err
}
case cfg != nil && cfg.IsDoltServerMode():
pr.Mode = "server"
host := cfg.GetDoltServerHost()
if isRemoteServerHost(host) {
pr.RemoteBackend = true
pr.Provenance = fmt.Sprintf("server mode with remote host %s; no local physical root", host)
break
}
root := cfg.DatabasePath(abs)
pr.Provenance = fmt.Sprintf("server mode (env/metadata/config.yaml, local host); root %s via DatabasePath semantics", root)
if err := addRoot(root); err != nil {
return PhysicalRoots{}, err
}
case cfg != nil:
// GetDoltMode defaults empty to embedded; anything that is not one
// of the server flavors above opens the embedded engine, whose data
// dir is hardcoded to .beads/embeddeddolt.
pr.Mode = "embedded"
root := filepath.Join(abs, "embeddeddolt")
pr.Provenance = fmt.Sprintf("metadata.json dolt_mode=%q -> embedded; root %s (embedded engine hardcodes embeddeddolt)", cfg.DoltMode, root)
if err := addRoot(root); err != nil {
return PhysicalRoots{}, err
}
default:
// No metadata.json at all: mirror the open path's on-disk discovery.
embedded := filepath.Join(abs, "embeddeddolt")
doltDir := filepath.Join(abs, "dolt")
if fi, serr := os.Stat(embedded); serr == nil && fi.IsDir() {
pr.Mode = "embedded"
pr.Provenance = fmt.Sprintf("no metadata.json; embeddeddolt/ directory present; root %s", embedded)
if err := addRoot(embedded); err != nil {
return PhysicalRoots{}, err
}
} else if fi, serr := os.Stat(doltDir); serr == nil && fi.IsDir() {
pr.Mode = "server"
pr.Provenance = fmt.Sprintf("no metadata.json; dolt/ server-layout directory present; root %s", doltDir)
if err := addRoot(doltDir); err != nil {
return PhysicalRoots{}, err
}
} else {
// Nothing on disk yet: default to the embedded root the open
// path would create. Gating a not-yet-existing root is fine —
// the gate file lives beside it in .beads, and workspacegate
// only requires the gate file's parent directory to exist.
pr.Mode = "embedded"
pr.Provenance = fmt.Sprintf("no metadata.json and no data directories; defaulting to embedded root %s", embedded)
if err := addRoot(embedded); err != nil {
return PhysicalRoots{}, err
}
}
}
return pr, nil
}
// LibraryOpenRootPath returns the physical root the LIBRARY open path
// (internal/storage/dolt/open.go, reached via beads.OpenFromConfig and
// beads.OpenGated) would use for this workspace. It exists because that path
// is broader than the CLI selection ResolvePhysicalRoots mirrors: open.go
// substitutes DefaultConfig when metadata.json is absent and applies
// central-config defaults (which can inherit dolt_mode=server from
// ~/.config/beads/server.json) either way, then derives the root from
// Config.DatabasePath — it never opens the embedded engine at all, so even
// an embedded-metadata workspace is opened server-style at DatabasePath
// (.beads/dolt or dolt_data_dir). beads.OpenGated gates the UNION of this
// root and the resolver's roots: over-gating an extra root under a SHARED
// hold is benign, under-gating is the bug.
//
// Side-effect free, unlike open.go itself: the config load is stat-guarded,
// so the legacy config.json→metadata.json migration write open.go would
// trigger cannot fire from gate planning; absent metadata uses DefaultConfig
// in memory only.
func LibraryOpenRootPath(beadsDir string) string {
var cfg *configfile.Config
if _, err := os.Stat(configfile.ConfigPath(beadsDir)); err == nil {
if loaded, lerr := configfile.Load(beadsDir); lerr == nil && loaded != nil {
// Copy before the central merge: callers may hold their own
// loaded Config that must not observe inherited fields.
cfgCopy := *loaded
cfg = &cfgCopy
}
}
if cfg == nil {
cfg = configfile.DefaultConfig()
}
applyCentralModeDefaults(cfg)
return cfg.DatabasePath(beadsDir)
}

View file

@ -0,0 +1,496 @@
package doltserver
import (
"os"
"path/filepath"
"testing"
)
// resetPhysicalRootEnv neutralizes every env var ResolvePhysicalRoots (and
// the helpers under it) consults, so tests describe the mode themselves
// rather than inheriting the developer machine's beads setup. The central
// config is pointed at a nonexistent file for the same reason — a real
// ~/.config/beads/server.json on the host must not leak modes into tests.
func resetPhysicalRootEnv(t *testing.T) {
t.Helper()
for _, k := range []string{
"BEADS_DOLT_SERVER_MODE",
"BEADS_DOLT_SHARED_SERVER",
"BEADS_DOLT_DATA_DIR",
"BEADS_DOLT_SERVER_HOST",
"BEADS_PROXIED_SERVER_ROOT_PATH",
"BEADS_SHARED_SERVER_DIR",
} {
t.Setenv(k, "")
}
t.Setenv("BEADS_CENTRAL_CONFIG", filepath.Join(t.TempDir(), "no-such-central.json"))
}
func writeBeadsMetadata(t *testing.T, beadsDir, body string) {
t.Helper()
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}
func newTestBeadsDir(t *testing.T) string {
t.Helper()
beadsDir := filepath.Join(t.TempDir(), ".beads")
if err := os.MkdirAll(beadsDir, 0o755); err != nil {
t.Fatal(err)
}
return beadsDir
}
func assertSingleRoot(t *testing.T, pr PhysicalRoots, wantMode, wantRoot string) {
t.Helper()
if pr.Mode != wantMode {
t.Errorf("Mode = %q, want %q (provenance: %s)", pr.Mode, wantMode, pr.Provenance)
}
if len(pr.Roots) != 1 || pr.Roots[0] != filepath.Clean(wantRoot) {
t.Errorf("Roots = %v, want [%s] (provenance: %s)", pr.Roots, wantRoot, pr.Provenance)
}
if pr.RemoteBackend {
t.Errorf("RemoteBackend = true, want false (provenance: %s)", pr.Provenance)
}
if pr.Provenance == "" {
t.Error("Provenance is empty; every decision must explain itself")
}
}
func TestResolvePhysicalRootsEmbeddedMetadata(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"embedded"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
// The embedded engine hardcodes embeddeddolt — NOT the dolt/ dir that
// ResolveDoltDir reports for the same workspace. This divergence is the
// original review blocker the resolver exists to fix.
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
}
func TestResolvePhysicalRootsServerMetadata(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "dolt"))
}
func TestResolvePhysicalRootsServerDataDirConfig(t *testing.T) {
resetPhysicalRootEnv(t)
absData := filepath.Join(t.TempDir(), "fast-disk")
t.Run("relative", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server","dolt_data_dir":"mydata"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "mydata"))
})
t.Run("absolute", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server","dolt_data_dir":"`+jsonEscapePath(absData)+`"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", absData)
})
}
func TestResolvePhysicalRootsServerDataDirEnv(t *testing.T) {
resetPhysicalRootEnv(t)
t.Run("relative", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server"}`)
t.Setenv("BEADS_DOLT_DATA_DIR", "envdata")
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "envdata"))
})
t.Run("absolute", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server"}`)
absData := filepath.Join(t.TempDir(), "env-abs")
t.Setenv("BEADS_DOLT_DATA_DIR", absData)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", absData)
})
}
func TestResolvePhysicalRootsServerModeEnvOverridesEmbeddedMetadata(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
// Runtime env wins over stale persisted mode (GH#2949 semantics).
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"embedded"}`)
t.Setenv("BEADS_DOLT_SERVER_MODE", "1")
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "dolt"))
}
func TestResolvePhysicalRootsRemoteServer(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server","dolt_server_host":"db.example.com"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
if pr.Mode != "server" {
t.Errorf("Mode = %q, want server", pr.Mode)
}
if !pr.RemoteBackend {
t.Error("RemoteBackend = false, want true for non-local dolt_server_host")
}
if len(pr.Roots) != 0 {
t.Errorf("Roots = %v, want none for a remote backend", pr.Roots)
}
}
func TestResolvePhysicalRootsSharedServerWinsOverMetadata(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
// Stale dolt_mode=embedded must NOT override active shared intent
// (mirrors ResolveDoltDir and the main.go no-config rescue, GH#3817).
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"embedded"}`)
sharedParent := filepath.Join(t.TempDir(), "shared-server")
t.Setenv("BEADS_DOLT_SHARED_SERVER", "1")
t.Setenv("BEADS_SHARED_SERVER_DIR", sharedParent)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "shared-server", filepath.Join(sharedParent, "dolt"))
// Side-effect freedom: resolution must not have created the shared
// tree (SharedServerDir/SharedDoltDir mkdir on first use; the resolver
// must use the Path variants that do not).
if _, statErr := os.Stat(sharedParent); !os.IsNotExist(statErr) {
t.Errorf("shared server dir %s was created by pure resolution (stat err = %v)", sharedParent, statErr)
}
}
func TestResolvePhysicalRootsProxied(t *testing.T) {
resetPhysicalRootEnv(t)
meta := `{"database":"beads.db","dolt_mode":"proxied-server"}`
t.Run("env absolute", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, meta)
absRoot := filepath.Join(t.TempDir(), "proxy-root")
t.Setenv("BEADS_PROXIED_SERVER_ROOT_PATH", absRoot)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "proxied-server", absRoot)
})
t.Run("env relative", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, meta)
t.Setenv("BEADS_PROXIED_SERVER_ROOT_PATH", "relroot")
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "proxied-server", filepath.Join(beadsDir, "relroot"))
})
t.Run("client info sidecar", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, meta)
sidecarRoot := filepath.Join(t.TempDir(), "sidecar-root")
body := `{"root_path":"` + jsonEscapePath(sidecarRoot) + `"}`
if err := os.WriteFile(filepath.Join(beadsDir, "proxied_server_client_info.json"), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "proxied-server", sidecarRoot)
})
t.Run("fallback default data dir", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, meta)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "proxied-server", filepath.Join(beadsDir, "dolt"))
})
}
func TestResolvePhysicalRootsIgnoresCentralConfig(t *testing.T) {
resetPhysicalRootEnv(t)
// CLI parity: cmd/bd/main.go's hand-built store selection never applies
// central-config defaults, so the resolver must not either — a central
// dolt_mode=server must NOT promote a mode-less project workspace. The
// LIBRARY path is broader; that side is covered by LibraryOpenRootPath.
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db"}`)
centralPath := filepath.Join(t.TempDir(), "server.json")
if err := os.WriteFile(centralPath, []byte(`{"dolt_mode":"server"}`), 0o600); err != nil {
t.Fatal(err)
}
t.Setenv("BEADS_CENTRAL_CONFIG", centralPath)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
}
func TestResolvePhysicalRootsPortDoesNotPromoteEmbedded(t *testing.T) {
resetPhysicalRootEnv(t)
// `bd init --server-port N` without --server writes dolt_mode=embedded
// AND a port; the CLI opens embeddeddolt, and ResolveServerMode gives
// an explicit dolt_mode=embedded precedence over the port heuristic.
// The resolver must agree: no port>0 promotion.
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"embedded","dolt_server_port":3307}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
}
func TestResolvePhysicalRootsBracketedIPv6LoopbackIsLocal(t *testing.T) {
resetPhysicalRootEnv(t)
// "[::1]" is what a host:port split leaves behind for IPv6 loopback;
// treating it as remote would silently drop the physical gate. The
// local set mirrors the storage layer's isLocalHost.
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"server","dolt_server_host":"[::1]"}`)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "dolt"))
}
func TestLibraryOpenRootPath(t *testing.T) {
resetPhysicalRootEnv(t)
t.Run("embedded metadata still yields DatabasePath root", func(t *testing.T) {
// The library open path (dolt.NewFromConfigWithOptions) is
// server-only and derives its root from DatabasePath even for
// embedded-metadata workspaces — the exact under-gating the union
// in beads.OpenGated exists to cover.
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_mode":"embedded"}`)
if got, want := LibraryOpenRootPath(beadsDir), filepath.Join(beadsDir, "dolt"); got != want {
t.Errorf("LibraryOpenRootPath = %q, want %q", got, want)
}
})
t.Run("absent metadata uses DefaultConfig without migration", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
legacyPath := filepath.Join(beadsDir, "config.json")
if err := os.WriteFile(legacyPath, []byte(`{"database":"beads.db"}`), 0o600); err != nil {
t.Fatal(err)
}
if got, want := LibraryOpenRootPath(beadsDir), filepath.Join(beadsDir, "dolt"); got != want {
t.Errorf("LibraryOpenRootPath = %q, want %q", got, want)
}
if _, statErr := os.Stat(filepath.Join(beadsDir, "metadata.json")); !os.IsNotExist(statErr) {
t.Errorf("metadata.json was created by pure resolution (stat err = %v)", statErr)
}
if _, statErr := os.Stat(legacyPath); statErr != nil {
t.Errorf("legacy config.json was removed by pure resolution: %v", statErr)
}
})
t.Run("data dir config honored", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
writeBeadsMetadata(t, beadsDir, `{"database":"beads.db","dolt_data_dir":"fast"}`)
if got, want := LibraryOpenRootPath(beadsDir), filepath.Join(beadsDir, "fast"); got != want {
t.Errorf("LibraryOpenRootPath = %q, want %q", got, want)
}
})
}
func TestResolvePhysicalRootsNoMetadataFallbacks(t *testing.T) {
resetPhysicalRootEnv(t)
t.Run("embeddeddolt dir present", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
if err := os.MkdirAll(filepath.Join(beadsDir, "embeddeddolt"), 0o755); err != nil {
t.Fatal(err)
}
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
})
t.Run("dolt server-layout dir present", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
if err := os.MkdirAll(filepath.Join(beadsDir, "dolt"), 0o755); err != nil {
t.Fatal(err)
}
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "server", filepath.Join(beadsDir, "dolt"))
})
t.Run("nothing on disk defaults to embedded", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
// The root may not exist yet; gating a not-yet-existing root is
// fine (the gate file lives beside it in .beads).
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
})
t.Run("env server mode without metadata stays embedded", func(t *testing.T) {
// CLI parity: the nil-config branch in cmd/bd/main.go rescues ONLY
// shared-server mode; BEADS_DOLT_SERVER_MODE without metadata does
// not change what the CLI opens, so it must not change the gate.
beadsDir := newTestBeadsDir(t)
t.Setenv("BEADS_DOLT_SERVER_MODE", "1")
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
})
}
func TestResolvePhysicalRootsSideEffectFree(t *testing.T) {
resetPhysicalRootEnv(t)
beadsDir := newTestBeadsDir(t)
// Legacy layout: config.json present, metadata.json absent. An
// unguarded configfile.Load would MIGRATE (write metadata.json, delete
// config.json); pure resolution must not.
legacyPath := filepath.Join(beadsDir, "config.json")
if err := os.WriteFile(legacyPath, []byte(`{"database":"beads.db","dolt_mode":"server"}`), 0o600); err != nil {
t.Fatal(err)
}
pr, err := ResolvePhysicalRoots(beadsDir)
if err != nil {
t.Fatal(err)
}
if _, statErr := os.Stat(filepath.Join(beadsDir, "metadata.json")); !os.IsNotExist(statErr) {
t.Errorf("metadata.json was created by pure resolution (stat err = %v)", statErr)
}
if _, statErr := os.Stat(legacyPath); statErr != nil {
t.Errorf("legacy config.json was removed by pure resolution: %v", statErr)
}
// With the migration correctly NOT triggered, the legacy config is
// invisible and the no-metadata stat fallback applies.
assertSingleRoot(t, pr, "embedded", filepath.Join(beadsDir, "embeddeddolt"))
}
func TestResolveProxiedServerRootPath(t *testing.T) {
resetPhysicalRootEnv(t)
t.Run("env absolute wins", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
absRoot := filepath.Join(t.TempDir(), "abs-root")
t.Setenv("BEADS_PROXIED_SERVER_ROOT_PATH", absRoot)
got, err := ResolveProxiedServerRootPath(beadsDir)
if err != nil {
t.Fatal(err)
}
if got != absRoot {
t.Errorf("root = %q, want %q", got, absRoot)
}
})
t.Run("env relative joins beadsDir", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
t.Setenv("BEADS_PROXIED_SERVER_ROOT_PATH", "rel-root")
got, err := ResolveProxiedServerRootPath(beadsDir)
if err != nil {
t.Fatal(err)
}
if want := filepath.Join(beadsDir, "rel-root"); got != want {
t.Errorf("root = %q, want %q", got, want)
}
})
t.Run("sidecar then default", func(t *testing.T) {
beadsDir := newTestBeadsDir(t)
got, err := ResolveProxiedServerRootPath(beadsDir)
if err != nil {
t.Fatal(err)
}
if want := filepath.Join(beadsDir, "dolt"); got != want {
t.Errorf("default root = %q, want %q", got, want)
}
sidecarRoot := filepath.Join(t.TempDir(), "side-root")
body := `{"root_path":"` + jsonEscapePath(sidecarRoot) + `"}`
if err := os.WriteFile(filepath.Join(beadsDir, "proxied_server_client_info.json"), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
got, err = ResolveProxiedServerRootPath(beadsDir)
if err != nil {
t.Fatal(err)
}
if got != sidecarRoot {
t.Errorf("sidecar root = %q, want %q", got, sidecarRoot)
}
})
}
// jsonEscapePath escapes a filesystem path for embedding in a hand-written
// JSON string literal (Windows backslashes would otherwise be parsed as
// escape sequences).
func jsonEscapePath(p string) string {
out := make([]byte, 0, len(p))
for i := 0; i < len(p); i++ {
if p[i] == '\\' {
out = append(out, '\\', '\\')
} else {
out = append(out, p[i])
}
}
return string(out)
}

View file

@ -371,6 +371,13 @@ func (g Gate) Acquire(ctx context.Context, mode Mode, opts Options) (*Handle, er
if g.path == "" {
return nil, errors.New("workspacegate: zero Gate; use ForWorkspace/ForPhysicalRoot")
}
// Tolerate a nil context rather than panicking on ctx.Err below: gate
// acquisition sits on CLI plumbing paths (cobra hooks, migrate helpers)
// that tests and embedders invoke directly without the process-level
// signal context, and a nil-deref here kills the whole test binary.
if ctx == nil {
ctx = context.Background()
}
if err := ctx.Err(); err != nil {
return nil, fmt.Errorf("workspacegate: acquiring %s: %w", g.path, err)
}
@ -505,6 +512,10 @@ func (m *MultiHandle) Release() error {
// init lock, proxy locks, the dolt-server start lock, or schema GET_LOCK,
// and release it after those.
func AcquireAll(ctx context.Context, mode Mode, opts Options, gates ...Gate) (*MultiHandle, error) {
// See Acquire: nil contexts are normalized, not dereferenced.
if ctx == nil {
ctx = context.Background()
}
uniq := make(map[string]Gate, len(gates))
for _, g := range gates {
if g.path == "" {