diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dbfca8b0..ea893eb2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -763,6 +763,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- **Strict `--readonly` no longer creates workspace gate files.** A + `bd --readonly` command took its shared workspace gates with + create-if-missing, so on a workspace no bd command had gated yet it left + `/.beads.gate.lock` and the physical-root gate file + (`.beads/embeddeddolt.gate.lock` or `.beads/dolt.gate.lock`) behind, although + strict readonly promises not to mutate the workspace. It now opens an + existing gate file read-only and holds it shared as before, so a maintenance + operation still sees it and a running one still makes it wait; when no gate + file exists it holds nothing. Every other command still creates the files. - **`bd init --server --external` no longer starts a Dolt server of its own.** Init builds its store config by hand and turned auto-start on for every server init, so an `--external` init that named no port launched a diff --git a/cmd/bd/workspace_gate.go b/cmd/bd/workspace_gate.go index e4ed66b22..acb54e39b 100644 --- a/cmd/bd/workspace_gate.go +++ b/cmd/bd/workspace_gate.go @@ -48,6 +48,17 @@ import ( // so would treating an interrupted wait as fail-open. // - EXCLUSIVE failures of any kind are hard errors: maintenance refuses // rather than pretends. +// - Strict --readonly is mutation-free (effectiveRootStorePolicy), so its +// SHARED hold opens the gate files read-only and never creates them (see +// workspacegate.Options.ReadOnly). A gate file that does not exist means +// nothing has ever been gated there, so the command proceeds holding +// nothing; an existing one is held SHARED like any other command's. +// Residual: on a workspace that has never been gated, a strict readonly +// command is invisible to a maintenance operation that starts while it +// runs. Every other command keeps creating the files, which is what makes +// it visible. The gate follows the strict flag only: allowlisted reads +// and --dry-run/--inspect previews also open the store read-only, but +// they keep creating the files, so they stay visible too. // // Known residual (PR-B2 scope, documented honestly): the pre-chokepoint // DISCOVERY code paths (configfile.Load at main.go's early config probe and @@ -389,6 +400,13 @@ func buildWorkspaceGateSet(beadsDir string, extraRoots ...string) ([]workspacega // 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 { + // A process can execute more than one command in tests and embedded uses. + // Never carry the preceding command's handle into an absent-workspace or + // failed acquisition path, where no new gate is held. Gates outlive the + // store, so close whatever store the preceding command left open before + // its gates drop; this command opens its own only after this point. + closeStoreBeforeGateRelease() + releaseWorkspaceGates() exclusive := commandNeedsExclusiveGate(cmd) // No workspace on disk: nothing to guard, and the store-open path will @@ -423,6 +441,9 @@ func acquireCommandWorkspaceGates(ctx context.Context, cmd *cobra.Command, beads opts = workspacegate.Options{ Wait: sharedWait, IgnoreQueuedExclusive: workspacegate.InheritedSharedHold(), + // readonlyMode is already resolved here. Strict readonly promises not to + // mutate the workspace, so its SHARED hold must not create gate files. + ReadOnly: readonlyMode, } if sharedWait > 0 { opts.OnWait, stopNotice = delayedGateNotice() @@ -472,7 +493,10 @@ func acquireCommandWorkspaceGates(ctx context.Context, cmd *cobra.Command, beads return nil } workspaceGateHandle = h - if !exclusive { + // A strict readonly hold on a never-gated workspace locks nothing, so it + // blocks no exclusive acquirer and gives a child nothing to stand behind: + // advertising it would let the child skip the queue for no reason. + if !exclusive && !h.Empty() { advertiseSharedHold() } return nil diff --git a/cmd/bd/workspace_gate_test.go b/cmd/bd/workspace_gate_test.go index ab85176fe..b55106a3b 100644 --- a/cmd/bd/workspace_gate_test.go +++ b/cmd/bd/workspace_gate_test.go @@ -4,7 +4,9 @@ import ( "context" "errors" "os" + "os/exec" "path/filepath" + "slices" "strconv" "strings" "sync" @@ -13,6 +15,8 @@ import ( "time" "github.com/spf13/cobra" + "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/storage/uow" "github.com/steveyegge/beads/internal/workspacegate" ) @@ -93,6 +97,10 @@ func TestAcquireCommandWorkspaceGatesAbsentWorkspace(t *testing.T) { t.Cleanup(releaseWorkspaceGates) list := &cobra.Command{Use: "list"} + before := newGateTestWorkspace(t) + if err := acquireCommandWorkspaceGates(context.Background(), list, before); err != nil || workspaceGateHandle == nil { + t.Fatalf("initial command must hold a gate: %v", err) + } 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) @@ -102,6 +110,109 @@ func TestAcquireCommandWorkspaceGatesAbsentWorkspace(t *testing.T) { } } +// A process that runs more than one command (tests, embedders) must not keep +// the previous command's SHARED hold once the next command takes its own +// gates: otherwise the first workspace stays held, and a maintenance +// operation there is turned away by a command that has already finished. +func TestAcquireCommandWorkspaceGatesReleasesThePreviousCommandsHold(t *testing.T) { + resetGateTestEnv(t) + t.Cleanup(releaseWorkspaceGates) + list := &cobra.Command{Use: "list"} + ctx := context.Background() + + first := newGateTestWorkspace(t) + if err := acquireCommandWorkspaceGates(ctx, list, first); err != nil || workspaceGateHandle == nil { + t.Fatalf("first command must hold a gate: %v", err) + } + second := newGateTestWorkspace(t) + if err := acquireCommandWorkspaceGates(ctx, list, second); err != nil || workspaceGateHandle == nil { + t.Fatalf("second command must hold a gate: %v", err) + } + + gate, err := workspacegate.ForWorkspace(first) + if err != nil { + t.Fatal(err) + } + holder, err := gate.Acquire(ctx, workspacegate.Exclusive, workspacegate.Options{Reason: "test maintenance"}) + if err != nil { + t.Fatalf("exclusive acquire on the first command's workspace once the second command holds its own gates: %v, want success", err) + } + _ = holder.Release() +} + +// gateCloseProbeStore and gateCloseProbeProvider stand in for the store and +// provider a previous command left open; Close runs the test's probe. +type gateCloseProbeStore struct { + storage.DoltStorage + onClose func() +} + +func (s *gateCloseProbeStore) Close() error { + s.onClose() + return nil +} + +type gateCloseProbeProvider struct { + uow.UnitOfWorkProvider + onClose func() +} + +func (p *gateCloseProbeProvider) Close(context.Context) error { + p.onClose() + return nil +} + +// When a command's RunE fails, Cobra skips PersistentPostRunE, so the store it +// opened is still open when the same process runs its next command. Before the +// next chokepoint drops the previous command's gates it must close that store +// and provider: gates outlive the store, or an exclusive maintenance operation +// could start against storage that has not quiesced. +func TestAcquireCommandWorkspaceGatesClosesThePreviousCommandsStoreFirst(t *testing.T) { + resetGateTestEnv(t) + t.Cleanup(releaseWorkspaceGates) + originalStore, originalProvider := store, uowProvider + t.Cleanup(func() { store, uowProvider = originalStore, originalProvider }) + list := &cobra.Command{Use: "list"} + ctx := context.Background() + + first := newGateTestWorkspace(t) + if err := acquireCommandWorkspaceGates(ctx, list, first); err != nil || workspaceGateHandle == nil { + t.Fatalf("first command must hold a gate: %v", err) + } + gate, err := workspacegate.ForWorkspace(first) + if err != nil { + t.Fatal(err) + } + // Each close records whether the first command's gate was still held. + var closes []string + probe := func(what string) func() { + return func() { + h, err := gate.Acquire(ctx, workspacegate.Exclusive, workspacegate.Options{}) + switch { + case errors.Is(err, workspacegate.ErrBusy): + closes = append(closes, what+" closed under the gate") + case err == nil: + _ = h.Release() + closes = append(closes, what+" closed after the gate dropped") + default: + t.Errorf("probing the first command's gate when its %s closed: %v", what, err) + } + } + } + store = &gateCloseProbeStore{onClose: probe("store")} + uowProvider = &gateCloseProbeProvider{onClose: probe("provider")} + + if err := acquireCommandWorkspaceGates(ctx, list, newGateTestWorkspace(t)); err != nil { + t.Fatalf("second command: %v", err) + } + if want := []string{"provider closed under the gate", "store closed under the gate"}; !slices.Equal(closes, want) { + t.Fatalf("the previous command's storage: %v, want %v", closes, want) + } + if store != nil || uowProvider != nil { + t.Fatal("the previous command's store and provider must not survive into the next command") + } +} + // holdWorkspaceGateExclusive takes beadsDir's workspace gate exclusively, // as a maintenance operation (init/restore/migrate) would. func holdWorkspaceGateExclusive(t *testing.T, beadsDir string) *workspacegate.Handle { @@ -134,11 +245,15 @@ func countGateNotices(t *testing.T) *atomic.Int32 { func TestAcquireCommandWorkspaceGatesBlockedByExclusiveHolder(t *testing.T) { resetGateTestEnv(t) t.Cleanup(releaseWorkspaceGates) + list := &cobra.Command{Use: "list"} + prior := newGateTestWorkspace(t) + if err := acquireCommandWorkspaceGates(context.Background(), list, prior); err != nil || workspaceGateHandle == nil { + t.Fatalf("initial command must hold a gate: %v", err) + } beadsDir := newGateTestWorkspace(t) t.Setenv(sharedGateWaitEnv, "300ms") holdWorkspaceGateExclusive(t, beadsDir) - list := &cobra.Command{Use: "list"} var err error start := time.Now() stderr := captureStderr(t, func() { @@ -393,6 +508,45 @@ func TestSharedHoldAdvertisedToChildren(t *testing.T) { } } +// A strict readonly command on a never-gated workspace holds nothing, so it +// must not advertise a shared hold: a child trusting the marker would skip the +// writer-fairness queue for a maintenance operation this process does not +// block. Once the gate files exist the strict readonly hold is real, and it is +// advertised like any other. +func TestSharedHoldAdvertisedOnlyWhenAGateIsHeld(t *testing.T) { + resetGateTestEnv(t) + advertiseSharedHoldEnabled = true + t.Cleanup(func() { advertiseSharedHoldEnabled = false }) + t.Cleanup(releaseWorkspaceGates) + beadsDir := newGateTestWorkspace(t) + list := &cobra.Command{Use: "list"} + ctx := context.Background() + + setReadonlyMode(t, true) + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err != nil { + t.Fatal(err) + } + if got := os.Getenv(workspacegate.InheritedHoldEnv); got != "" { + t.Fatalf("%s while a strict readonly command holds nothing = %q, want it left empty", workspacegate.InheritedHoldEnv, got) + } + releaseWorkspaceGates() + + // A normal command materializes the gate files. + setReadonlyMode(t, false) + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err != nil { + t.Fatal(err) + } + releaseWorkspaceGates() + + setReadonlyMode(t, true) + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err != nil { + t.Fatal(err) + } + if got, want := os.Getenv(workspacegate.InheritedHoldEnv), strconv.Itoa(os.Getpid()); got != want { + t.Fatalf("%s while a strict readonly command holds existing gates = %q, want %q", workspacegate.InheritedHoldEnv, got, want) + } +} + func TestSharedGateWaitEnv(t *testing.T) { for _, tc := range []struct { raw, hook string @@ -806,3 +960,180 @@ func TestEnvWithoutSharedHoldMarker(t *testing.T) { t.Fatal("envWithoutSharedHoldMarker dropped unrelated variables") } } + +// setReadonlyMode pins strict --readonly for one test, as PersistentPreRunE +// leaves readonlyMode by the time it acquires the gates. +func setReadonlyMode(t *testing.T, on bool) { + t.Helper() + original := readonlyMode + readonlyMode = on + t.Cleanup(func() { readonlyMode = original }) +} + +// newGateTestServerWorkspace is newGateTestWorkspace for a local-server +// workspace: its physical root is .beads/dolt, not .beads/embeddeddolt. +func newGateTestServerWorkspace(t *testing.T) string { + t.Helper() + beadsDir := filepath.Join(t.TempDir(), ".beads") + if err := os.MkdirAll(filepath.Join(beadsDir, "dolt"), 0o755); err != nil { + t.Fatal(err) + } + meta := `{"backend":"dolt","database":"beads.db","dolt_mode":"server"}` + if err := os.WriteFile(filepath.Join(beadsDir, "metadata.json"), []byte(meta), 0o600); err != nil { + t.Fatal(err) + } + return beadsDir +} + +// dirEntryNames lists dir's immediate entries by name, so a test can prove a +// command left the directory exactly as it found it. +func dirEntryNames(t *testing.T, dir string) []string { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + names := make([]string, 0, len(entries)) + for _, e := range entries { + names = append(names, e.Name()) + } + return names +} + +// Strict --readonly is mutation-free (effectiveRootStorePolicy), so taking the +// command's gates must not create any gate file: not the workspace gate beside +// .beads, and not the physical-root gate inside it (.beads/embeddeddolt for an +// embedded workspace, .beads/dolt for a local server one). +func TestAcquireCommandWorkspaceGatesStrictReadonlyCreatesNoGateFiles(t *testing.T) { + layouts := []struct { + name string + build func(*testing.T) string + }{ + {"embedded", newGateTestWorkspace}, + {"local server", newGateTestServerWorkspace}, + } + for _, tc := range layouts { + t.Run(tc.name, func(t *testing.T) { + resetGateTestEnv(t) + t.Cleanup(releaseWorkspaceGates) + setReadonlyMode(t, true) + beadsDir := tc.build(t) + projectDir := filepath.Dir(beadsDir) + projectBefore, beadsBefore := dirEntryNames(t, projectDir), dirEntryNames(t, beadsDir) + + list := &cobra.Command{Use: "list"} + if err := acquireCommandWorkspaceGates(context.Background(), list, beadsDir); err != nil { + t.Fatalf("strict readonly acquisition on a never-gated workspace: %v", err) + } + // SHARED fail-open also returns nil and creates nothing; it is + // told apart by running with no handle at all. + if workspaceGateHandle == nil { + t.Fatal("strict readonly acquisition on a never-gated workspace ran ungated, want a handle that holds nothing") + } + if !workspaceGateHandle.Empty() { + t.Fatal("strict readonly acquisition on a never-gated workspace locked a gate file") + } + if got := dirEntryNames(t, projectDir); !slices.Equal(got, projectBefore) { + t.Errorf("strict readonly changed %s\n before: %v\n after: %v", projectDir, projectBefore, got) + } + if got := dirEntryNames(t, beadsDir); !slices.Equal(got, beadsBefore) { + t.Errorf("strict readonly changed %s\n before: %v\n after: %v", beadsDir, beadsBefore, got) + } + }) + } +} + +// Not creating a gate file must not mean not honoring one. Once a workspace's +// gate files exist (any normal bd command creates them), a strict readonly +// command still holds them SHARED — so maintenance sees it and refuses to run +// over it — and is still refused while maintenance holds the gate. +func TestAcquireCommandWorkspaceGatesStrictReadonlyStillHonorsExistingGates(t *testing.T) { + resetGateTestEnv(t) + t.Cleanup(releaseWorkspaceGates) + beadsDir := newGateTestWorkspace(t) + list := &cobra.Command{Use: "list"} + ctx := context.Background() + + // A normal command materializes the gate files. + setReadonlyMode(t, false) + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err != nil { + t.Fatal(err) + } + releaseWorkspaceGates() + + setReadonlyMode(t, true) + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err != nil { + t.Fatalf("strict readonly acquisition against existing gate files: %v", err) + } + gate, err := workspacegate.ForWorkspace(beadsDir) + if err != nil { + t.Fatal(err) + } + if _, err := gate.Acquire(ctx, workspacegate.Exclusive, workspacegate.Options{}); !errors.Is(err, workspacegate.ErrBusy) { + t.Fatalf("exclusive acquire while a strict readonly command is running: err = %v, want ErrBusy", err) + } + releaseWorkspaceGates() + + holder, err := gate.Acquire(ctx, workspacegate.Exclusive, workspacegate.Options{Reason: "test maintenance"}) + if err != nil { + t.Fatalf("exclusive acquire after the strict readonly command released: %v", err) + } + defer func() { _ = holder.Release() }() + // Bound the shared wait: resetGateTestEnv clears it, which means the 30s default. + t.Setenv(sharedGateWaitEnv, "300ms") + if err := acquireCommandWorkspaceGates(ctx, list, beadsDir); err == nil { + t.Fatal("strict readonly acquisition under a foreign exclusive holder must abort, got nil error") + } +} + +// Only STRICT readonly skips creating the gate files. A normal command keeps +// creating them: that is what makes it visible to a maintenance operation that +// starts later (the exclusive acquirer locks the same file), so the first gate +// holder on a workspace cannot go unseen. +func TestAcquireCommandWorkspaceGatesNormalCommandStillCreatesGateFiles(t *testing.T) { + resetGateTestEnv(t) + t.Cleanup(releaseWorkspaceGates) + setReadonlyMode(t, false) + beadsDir := newGateTestWorkspace(t) + + list := &cobra.Command{Use: "list"} + if err := acquireCommandWorkspaceGates(context.Background(), list, beadsDir); err != nil { + t.Fatal(err) + } + for _, gateFile := range []string{ + filepath.Join(filepath.Dir(beadsDir), ".beads.gate.lock"), + filepath.Join(beadsDir, "embeddeddolt.gate.lock"), + } { + if _, err := os.Stat(gateFile); err != nil { + t.Errorf("a normal command must create its gate file: %v", err) + } + } +} + +// End to end: the real `bd --readonly` leaves no gate file behind. The +// in-process tests above pin acquireCommandWorkspaceGates; this one pins that +// the command line reaches it with strict readonly already resolved. +func TestStrictReadonlyCommandCreatesNoGateFiles(t *testing.T) { + bdBin := buildBDForInitTests(t) + beadsDir := newGateTestServerWorkspace(t) + projectDir := filepath.Dir(beadsDir) + + cmd := exec.Command(bdBin, "--readonly", "list") + cmd.Dir = projectDir + cmd.Env = hermeticInitEnv(t.TempDir(), "BEADS_DIR="+beadsDir, "BEADS_DOLT_AUTO_START=0") + // No Dolt server sits behind this workspace, so the command is expected to + // fail when it opens the store; only what it left on disk matters here. + out, _ := cmd.CombinedOutput() + + var gateFiles []string + for _, dir := range []string{projectDir, beadsDir} { + for _, name := range dirEntryNames(t, dir) { + if strings.Contains(name, ".gate.lock") { + gateFiles = append(gateFiles, filepath.Join(dir, name)) + } + } + } + if len(gateFiles) != 0 { + t.Fatalf("bd --readonly created gate files %v\noutput: %s", gateFiles, out) + } +} diff --git a/internal/workspacegate/BUILD.bazel b/internal/workspacegate/BUILD.bazel index 85a5fefdf..4928df002 100644 --- a/internal/workspacegate/BUILD.bazel +++ b/internal/workspacegate/BUILD.bazel @@ -10,7 +10,10 @@ go_library( go_test( name = "workspacegate_test", - srcs = ["gate_test.go"], + srcs = [ + "gate_test.go", + "readonly_wait_test.go", + ], embed = [":workspacegate"], deps = ["//internal/testutil/bazeltest"], ) diff --git a/internal/workspacegate/gate.go b/internal/workspacegate/gate.go index 754c14400..d0d27516c 100644 --- a/internal/workspacegate/gate.go +++ b/internal/workspacegate/gate.go @@ -112,6 +112,15 @@ type Options struct { // effort, from the advisory sidecar). AcquireAll fires it at most // once across the whole gate set. OnWait func(holder string) + // ReadOnly makes a SHARED acquisition free of side effects, for commands + // that promise not to mutate the workspace (strict --readonly). The gate + // file is opened O_RDONLY and never created: a gate file that does not + // exist means nothing has ever been gated here (the reading ExclusiveHolder + // uses), so Acquire succeeds holding nothing. An existing file is held + // SHARED as usual, so maintenance still sees the holder and a live + // exclusive holder still turns it away. Ignored for Exclusive: a + // maintenance operation has to be able to create the file it locks. + ReadOnly bool // IgnoreQueuedExclusive makes a waiting Shared acquisition skip the // writer-fairness check. Set it only when an ANCESTOR process already // holds this gate shared (see InheritedSharedHold): the queued @@ -372,6 +381,11 @@ type Handle struct { // Mode reports how this handle was acquired. func (h *Handle) Mode() Mode { return h.mode } +// Empty reports whether the acquisition locked nothing: a ReadOnly shared +// acquisition of a gate file that does not exist (see Options.ReadOnly). An +// empty handle blocks no acquirer. Release does not change the answer. +func (h *Handle) Empty() bool { return h == nil || h.f == nil } + // Release drops the lock and closes the file handle. For exclusive // handles it also best-effort removes the holder-info sidecar. The gate // file itself is intentionally never removed: deleting a lock file that @@ -382,6 +396,11 @@ func (h *Handle) Release() error { return nil } h.once.Do(func() { + if h.f == nil { + // A ReadOnly acquisition of a gate file that does not exist: + // nothing was locked, so there is nothing to drop. + return + } var errs []error if h.mode == Exclusive { // Remove the sidecar BEFORE unlocking: after the unlock a new @@ -455,6 +474,9 @@ func (h *Handle) Release() error { // Lock order is unchanged in substance: the intent lock of a gate is taken // only while acquiring that gate, so it slots directly before the gate in // AcquireAll's sorted total order and cannot form a cycle. +// +// A Shared acquisition with Options.ReadOnly never creates the gate file: +// see that option for what it holds instead. func (g Gate) Acquire(ctx context.Context, mode Mode, opts Options) (*Handle, error) { if g.path == "" { return nil, errors.New("workspacegate: zero Gate; use ForWorkspace/ForPhysicalRoot") @@ -475,8 +497,20 @@ func (g Gate) Acquire(ctx context.Context, mode Mode, opts Options) (*Handle, er } deadline := time.Now().Add(opts.Wait) - f, err := os.OpenFile(g.path, os.O_CREATE|os.O_RDWR, 0o600) + // An exclusive acquirer always has to create the file it locks, so + // ReadOnly applies to shared acquisition only. + readOnly := opts.ReadOnly && mode == Shared + flag := os.O_CREATE | os.O_RDWR + if readOnly { + flag = os.O_RDONLY + } + f, err := os.OpenFile(g.path, flag, 0o600) if err != nil { + if readOnly && os.IsNotExist(err) { + // No gate file: nothing has ever gated here, so there is no + // holder to see and nothing to hold. + return &Handle{gate: g, mode: mode}, nil + } return nil, fmt.Errorf("workspacegate: open gate %s: %w", g.path, err) } @@ -705,6 +739,21 @@ type MultiHandle struct { handles []*Handle } +// Empty reports whether the acquisition locked no gate at all: every gate in +// the set was a ReadOnly acquisition of a gate file that does not exist (see +// Handle.Empty). +func (m *MultiHandle) Empty() bool { + if m == nil { + return true + } + for _, h := range m.handles { + if !h.Empty() { + return false + } + } + return true +} + // Release drops every held gate in reverse order. Idempotent. func (m *MultiHandle) Release() error { if m == nil { diff --git a/internal/workspacegate/gate_test.go b/internal/workspacegate/gate_test.go index 391a6d50d..eb5ddd100 100644 --- a/internal/workspacegate/gate_test.go +++ b/internal/workspacegate/gate_test.go @@ -322,6 +322,184 @@ func TestExclusiveHolderDoesNotDisturbSharedAcquirers(t *testing.T) { <-done } +// A ReadOnly shared acquisition on a workspace that has never been gated must +// succeed and create nothing: an absent gate file means nothing has ever been +// gated here (the reading ExclusiveHolder already uses), so there is no holder +// to observe and nothing to hold. This is what lets a strict --readonly +// command stay mutation-free. +func TestReadOnlySharedAcquireCreatesNothing(t *testing.T) { + g, dir := testGate(t) + + h, err := g.Acquire(context.Background(), Shared, Options{ReadOnly: true}) + if err != nil { + t.Fatalf("ReadOnly shared Acquire on a never-gated workspace: %v, want success (nothing to hold)", err) + } + for i := 1; i <= 2; i++ { + if err := h.Release(); err != nil { + t.Fatalf("Release #%d of the ReadOnly handle: %v", i, err) + } + } + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + var created []string + for _, e := range entries { + created = append(created, e.Name()) + } + if len(created) != 0 { + t.Fatalf("ReadOnly Acquire created %v in %s, want nothing", created, dir) + } +} + +// Against a gate file that already exists, a ReadOnly shared acquisition is a +// real shared hold — it coexists with other shared holders, is refused by a +// live exclusive holder, and keeps an exclusive acquirer out until released. +// Dropping the create must not make strict readonly commands invisible to +// maintenance. +func TestReadOnlySharedAcquireHoldsExistingGate(t *testing.T) { + g, _ := testGate(t) + // Materialize the gate file once, as any workspace that has run bd has. + h0 := mustAcquire(t, g, Shared, Options{}) + _ = h0.Release() + + h := mustAcquire(t, g, Shared, Options{ReadOnly: true}) + other := mustAcquire(t, g, Shared, Options{}) + _ = other.Release() + if _, err := g.Acquire(context.Background(), Exclusive, Options{}); !errors.Is(err, ErrBusy) { + t.Fatalf("exclusive under a ReadOnly shared holder: err = %v, want ErrBusy", err) + } + if err := h.Release(); err != nil { + t.Fatalf("Release: %v", err) + } + + hEx := mustAcquire(t, g, Exclusive, Options{Reason: "after the ReadOnly holder left"}) + defer hEx.Release() + if _, err := g.Acquire(context.Background(), Shared, Options{ReadOnly: true}); !errors.Is(err, ErrBusy) { + t.Fatalf("ReadOnly shared under an exclusive holder: err = %v, want ErrBusy", err) + } +} + +// The gate file is opened O_RDONLY, not merely without O_CREATE: a strict +// readonly command in a sandbox whose gate file it cannot write must still be +// able to hold it (flock does not need a writable descriptor). +func TestReadOnlySharedAcquireNeedsNoWriteAccess(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("POSIX permission bits do not gate opens on Windows") + } + if os.Geteuid() == 0 { + t.Skip("root ignores file permission bits") + } + g, _ := testGate(t) + h0 := mustAcquire(t, g, Shared, Options{}) + _ = h0.Release() + if err := os.Chmod(g.Path(), 0o400); err != nil { + t.Fatal(err) + } + + h, err := g.Acquire(context.Background(), Shared, Options{ReadOnly: true}) + if err != nil { + t.Fatalf("ReadOnly shared Acquire on a read-only gate file: %v, want success", err) + } + _ = h.Release() +} + +// ReadOnly applies to shared acquisition only: an exclusive acquirer has to be +// able to create the gate file it locks, so the option cannot suppress that. +func TestReadOnlyOptionIgnoredForExclusive(t *testing.T) { + g, _ := testGate(t) + + h, err := g.Acquire(context.Background(), Exclusive, Options{ReadOnly: true, Reason: "readonly is ignored"}) + if err != nil { + t.Fatalf("exclusive Acquire with ReadOnly set: %v", err) + } + defer h.Release() + if _, err := os.Stat(g.Path()); err != nil { + t.Fatalf("exclusive Acquire must create the gate file it locks: %v", err) + } + if _, err := g.Acquire(context.Background(), Shared, Options{}); !errors.Is(err, ErrBusy) { + t.Fatalf("shared under that exclusive holder: err = %v, want ErrBusy", err) + } +} + +// AcquireAll passes the option to every gate: gates whose file exists are held +// shared, gates whose file does not are skipped and stay absent — for the +// workspace gate beside .beads and the physical-root gate inside it alike. +func TestAcquireAllReadOnlySkipsAbsentGates(t *testing.T) { + dir := t.TempDir() + beadsDir := filepath.Join(dir, ".beads") + if err := os.MkdirAll(beadsDir, 0o755); err != nil { + t.Fatal(err) + } + ws, err := ForWorkspace(beadsDir) + if err != nil { + t.Fatal(err) + } + root, err := ForPhysicalRoot(filepath.Join(beadsDir, "embeddeddolt")) + if err != nil { + t.Fatal(err) + } + // Only the workspace gate has ever been used. + h0 := mustAcquire(t, ws, Shared, Options{}) + _ = h0.Release() + + m, err := AcquireAll(context.Background(), Shared, Options{ReadOnly: true}, ws, root) + if err != nil { + t.Fatalf("AcquireAll with ReadOnly over an existing and an absent gate: %v", err) + } + if _, err := ws.Acquire(context.Background(), Exclusive, Options{}); !errors.Is(err, ErrBusy) { + t.Fatalf("exclusive on the existing workspace gate under AcquireAll: err = %v, want ErrBusy", err) + } + if err := m.Release(); err != nil { + t.Fatalf("Release: %v", err) + } + if _, err := os.Lstat(root.Path()); !os.IsNotExist(err) { + t.Fatalf("AcquireAll with ReadOnly created the absent physical-root gate %s (stat err: %v)", root.Path(), err) + } +} + +// Empty separates a ReadOnly acquisition that locked nothing from a real +// hold: callers use it to decide whether there is a hold to tell anyone about. +// One gate file that exists makes the whole set a real hold. +func TestEmptyReportsWhetherAnythingIsLocked(t *testing.T) { + never, _ := testGate(t) // never gated: its file stays absent + used, _ := testGate(t) // gated once, below + readOnly := Options{ReadOnly: true} + + if !(*Handle)(nil).Empty() || !(*MultiHandle)(nil).Empty() { + t.Fatal("a nil handle must report Empty") + } + absent, err := AcquireAll(context.Background(), Shared, readOnly, never, used) + if err != nil { + t.Fatalf("ReadOnly AcquireAll over two absent gates: %v", err) + } + if !absent.Empty() { + t.Fatal("ReadOnly AcquireAll over two absent gates reported a hold, want Empty") + } + _ = absent.Release() + + h0 := mustAcquire(t, used, Shared, Options{}) + if h0.Empty() { + t.Fatal("a plain shared acquisition reported Empty") + } + _ = h0.Release() + if h0.Empty() { + t.Fatal("Release changed Empty; it reports the acquisition, not the current state") + } + + partial, err := AcquireAll(context.Background(), Shared, readOnly, never, used) + if err != nil { + t.Fatalf("ReadOnly AcquireAll over an absent and an existing gate: %v", err) + } + defer partial.Release() + if partial.Empty() { + t.Fatal("ReadOnly AcquireAll holding the existing gate reported Empty") + } + if _, err := os.Lstat(never.Path()); !os.IsNotExist(err) { + t.Fatalf("the absent gate %s must stay absent (stat err: %v)", never.Path(), err) + } +} + // A cancelled context must surface as the context error even in // fail-fast mode (Wait == 0), so callers can tell shutdown from // contention. diff --git a/internal/workspacegate/readonly_wait_test.go b/internal/workspacegate/readonly_wait_test.go new file mode 100644 index 000000000..18b623d06 --- /dev/null +++ b/internal/workspacegate/readonly_wait_test.go @@ -0,0 +1,183 @@ +package workspacegate + +import ( + "context" + "errors" + "os" + "slices" + "testing" + "time" +) + +// A strict-readonly SHARED acquisition (Options.ReadOnly) and a waiting one +// (Options.Wait, with its writer-fairness intent queue) meet in exactly one +// place: a ReadOnly acquisition with Wait > 0. The ReadOnly tests in +// gate_test.go are all wait-less, so the tests below pin that seam: waiting +// must not make a ReadOnly acquisition create anything (no gate file, no +// intent file, no holder-info sidecar), and ReadOnly must not change how long +// a shared acquisition waits for an exclusive holder. +// +// None of them touches maxIntentHold or any other package variable a test +// shortens, and none runs in parallel with anything. + +// gateDirEntries lists dir's entries by name (os.ReadDir sorts them), so a +// test can prove an acquisition left the gate's directory as it found it. +func gateDirEntries(t *testing.T, dir string) []string { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + names := make([]string, 0, len(entries)) + for _, e := range entries { + names = append(names, e.Name()) + } + return names +} + +// (i) The gate file exists and no intent file does: a waiting ReadOnly shared +// acquisition takes the gate on its first attempt (OnWait never fires) and +// creates nothing beside it: no .intent, no .intent.info, no .info. +func TestReadOnlyWaitingSharedAcquireOfExistingGateCreatesNothing(t *testing.T) { + g, dir := testGate(t) + // Materialize the gate file the way any ordinary command does. + _ = mustAcquire(t, g, Shared, Options{}).Release() + before := gateDirEntries(t, dir) + if _, err := os.Stat(g.Path()); err != nil { + t.Fatalf("precondition: the gate file must exist: %v", err) + } + if _, err := os.Stat(g.intentPath()); !os.IsNotExist(err) { + t.Fatalf("precondition: no intent file may exist, stat err = %v", err) + } + + const wait = time.Second + var waited []string + start := time.Now() + h, err := g.Acquire(context.Background(), Shared, Options{ + ReadOnly: true, + Wait: wait, + OnWait: func(holder string) { waited = append(waited, holder) }, + }) + elapsed := time.Since(start) + if err != nil { + t.Fatalf("waiting ReadOnly shared Acquire of a free, existing gate: %v", err) + } + defer func() { _ = h.Release() }() + if len(waited) != 0 { + t.Errorf("the first attempt did not take the free gate: OnWait fired with %q", waited) + } + if elapsed >= wait { + t.Errorf("took %s, want far under its %s budget: nothing was holding the gate", elapsed, wait) + } + if h.f == nil { + t.Fatal("handle holds no file: against an existing gate file a ReadOnly acquisition is a real shared hold") + } + if got := gateDirEntries(t, dir); !slices.Equal(got, before) { + t.Errorf("waiting ReadOnly acquisition changed %s\n before: %v\n after: %v", dir, before, got) + } + // It is a real shared hold: a maintenance operation is turned away. + if _, err := g.Acquire(context.Background(), Exclusive, Options{}); !errors.Is(err, ErrBusy) { + t.Fatalf("exclusive Acquire under the ReadOnly shared holder: err = %v, want ErrBusy", err) + } + if err := h.Release(); err != nil { + t.Fatalf("Release: %v", err) + } + if got := gateDirEntries(t, dir); !slices.Equal(got, before) { + t.Errorf("after release %s\n before: %v\n after: %v", dir, before, got) + } +} + +// (ii) No gate file: nothing has ever gated here. A waiting ReadOnly shared +// acquisition returns at once with an empty handle (it holds no file and has +// nothing to wait for) and leaves the directory exactly as it was: it neither +// creates the gate file nor waits for one to appear. +func TestReadOnlyWaitingSharedAcquireOfMissingGateHoldsNothing(t *testing.T) { + g, dir := testGate(t) + before := gateDirEntries(t, dir) + if len(before) != 0 { + t.Fatalf("precondition: %s must start empty, has %v", dir, before) + } + + const wait = time.Second + var waited []string + start := time.Now() + h, err := g.Acquire(context.Background(), Shared, Options{ + ReadOnly: true, + Wait: wait, + OnWait: func(holder string) { waited = append(waited, holder) }, + }) + elapsed := time.Since(start) + if err != nil { + t.Fatalf("waiting ReadOnly shared Acquire with no gate file: %v, want success holding nothing", err) + } + if h == nil || h.f != nil { + t.Fatalf("handle = %+v, want an empty handle (no gate file was opened)", h) + } + if h.Mode() != Shared { + t.Errorf("handle mode = %s, want %s", h.Mode(), Shared) + } + if len(waited) != 0 { + t.Errorf("OnWait fired with %q: with no gate file there is nothing to wait for", waited) + } + if elapsed >= wait { + t.Errorf("took %s, want far under its %s budget: a missing gate file is answered before any retry", elapsed, wait) + } + if got := gateDirEntries(t, dir); !slices.Equal(got, before) { + t.Errorf("waiting ReadOnly acquisition changed %s\n before: %v\n after: %v", dir, before, got) + } + for i := 1; i <= 2; i++ { + if err := h.Release(); err != nil { + t.Fatalf("Release #%d of the empty handle: %v", i, err) + } + } + if got := gateDirEntries(t, dir); !slices.Equal(got, before) { + t.Errorf("after release %s\n before: %v\n after: %v", dir, before, got) + } +} + +// (iii) The gate file exists and is held EXCLUSIVELY: a waiting ReadOnly +// shared acquisition waits out its own budget, exactly like any shared +// acquisition, and then fails with ErrBusy. ReadOnly is not special-cased: +// it neither fails at once nor waits longer (the shared default is 30s, the +// init budget 60s). It also creates nothing while it waits, which is where +// the fairness probe (ExclusiveQueued) meets ReadOnly: the probe opens the +// intent file read-only and treats a missing one as "nothing queued". +func TestReadOnlyWaitingSharedAcquireUnderExclusiveHolderWaitsItsBudget(t *testing.T) { + g, dir := testGate(t) + holder := mustAcquire(t, g, Exclusive, Options{Reason: "test maintenance"}) + defer func() { _ = holder.Release() }() + before := gateDirEntries(t, dir) + + const wait = 300 * time.Millisecond + waited := 0 + start := time.Now() + h, err := g.Acquire(context.Background(), Shared, Options{ + ReadOnly: true, + Wait: wait, + OnWait: func(string) { waited++ }, + }) + elapsed := time.Since(start) + if !errors.Is(err, ErrBusy) { + if h != nil { + _ = h.Release() + } + t.Fatalf("waiting ReadOnly shared Acquire under an exclusive holder: err = %v, want ErrBusy", err) + } + // Acquire's deadline is taken after start, and it reports ErrBusy only + // once that deadline has passed, so this lower bound is exact. + if elapsed < wait { + t.Errorf("gave up after %s, before its %s budget ran out: ReadOnly must wait like any shared acquisition", elapsed, wait) + } + // The loop overshoots by at most one poll interval (100ms by default). + // The ceiling is far more generous than that so a loaded host cannot make + // this flaky; it still catches any special-cased budget. + if limit := wait + 2*time.Second; elapsed > limit { + t.Errorf("gave up after %s, want about its %s budget (at most %s)", elapsed, wait, limit) + } + if waited != 1 { + t.Errorf("OnWait fired %d times, want once (after the first busy attempt)", waited) + } + if got := gateDirEntries(t, dir); !slices.Equal(got, before) { + t.Errorf("waiting ReadOnly acquisition changed %s\n before: %v\n after: %v", dir, before, got) + } +}