fix(workspacegate): strict --readonly never creates workspace gate files (#7672)

* fix(workspacegate): strict --readonly never creates workspace gate files

Strict --readonly is mutation-free by policy (effectiveRootStorePolicy),
but the command chokepoint took its SHARED workspace gates with
O_CREATE|O_RDWR. On a workspace no bd command had gated yet, a strict
readonly command therefore left <project>/.beads.gate.lock and the
physical-root gate file (.beads/embeddeddolt.gate.lock or
.beads/dolt.gate.lock) behind.

Add workspacegate.Options.ReadOnly. A Shared acquisition with it opens
the gate file O_RDONLY (the idiom ExclusiveHolder already uses) and never
creates it. A gate file that does not exist means nothing has ever been
gated there, so Acquire succeeds with an empty handle whose Release is a
no-op. An existing gate file is held SHARED as before, so maintenance
still sees the command and a live exclusive holder still makes it wait
and then refuses it. The option is ignored for Exclusive: maintenance has
to be able to create the file it locks.

ReadOnly composes with the fair, bounded waiting from #7225 without
changes to it: the writer-fairness probe (ExclusiveQueued) already opens
the intent file read-only and treats a missing one as nothing queued, so
a waiting ReadOnly acquisition creates no .intent or .info file either.
readonly_wait_test.go pins that seam.

The chokepoint passes ReadOnly: readonlyMode in the SHARED branch. Every
other command keeps creating the gate files, which is what makes it
visible to maintenance. Residual, documented at the chokepoint: on a
workspace that has never been gated, a strict readonly command is
invisible to a maintenance operation that starts while it runs.

Ported from the versioned-beads integration fork (donnabox):
0c86e2b205 (red tests), bac6ff95dc (fix), b7a4f96a5a (fair-wait tests),
2af5a664dc (BUILD.bazel registration), and the #7225 conflict resolution
in 9d128f8c51. The fork's `--readonly backup restore` refusal
(6ac79d6207) is a separate change and is not included.

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): release the previous command's workspace gate before acquiring

acquireCommandWorkspaceGates stored its new handle over whatever
workspaceGateHandle already held. cobra skips PersistentPostRunE when
RunE fails, so in a process that runs more than one command (tests,
embedders) a command could start with the previous command's handle
still set. Two things then went wrong:

- on the paths that take no new gate (no .beads on disk, a failed or
  fail-open acquisition) the stale handle stayed set, so the previous
  workspace stayed held for the whole command;
- on a successful acquisition the stale handle was overwritten without
  being released, so its flock stayed held on the previous workspace
  until the garbage collector closed the file, and a maintenance
  operation there was turned away by a command that had finished.

Release any held handle first. In a single-command bd process the handle
is always nil at that point, so this is a no-op there.

Ported from the versioned-beads integration fork (donnabox): 3a25b42ed1
(cherry-pick of ad87442c92). The test
TestAcquireCommandWorkspaceGatesReleasesThePreviousCommandsHold is new
here and covers the successful-acquisition case the fork's tests do not.

Co-authored-by: Donna Box <dbox@boxenllc.com>
Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(cli): close a stale store before the leading gate release

Review fixups for #7672, apply-fixes iteration 1.

The leading releaseWorkspaceGates() that the second commit added to the
chokepoint was the only production release without a
closeStoreBeforeGateRelease() first. When an in-process command's RunE
fails, Cobra skips PersistentPostRunE. The next command in the same
process then dropped that command's gates while its store and provider
were still open, and later overwrote and leaked them. Close them first,
as every other release path does. The current command assigns
store/uowProvider only after the chokepoint, so anything set there
belongs to the previous command. Only multi-command processes (tests,
embedders) are affected; production runs one command per process.

A strict --readonly hold on a never-gated workspace locks nothing. The
chokepoint still exported this PID in BEADS_GATE_SHARED_HOLDER_PID, so bd
children skipped the writer-fairness queue behind a parent that blocks
no exclusive acquirer. Add Handle.Empty and MultiHandle.Empty, and
advertise only when at least one gate is actually locked.

Tests:
- A regression test runs the chokepoint over a stub store and provider.
  It pins that both close while the previous command's gate is still
  held.
- A marker test forces advertiseSharedHoldEnabled on. It pins that a
  hold of nothing is not advertised, and that the hold is advertised
  once the gate files exist.
- The strict-readonly chokepoint subtests now require a handle that
  holds nothing. SHARED fail-open leaves no handle, so these subtests
  now fail the review's W2 mutant, which passed them before.
- A package test covers Empty.

The posture comment now says the gate follows the strict flag only.
Allowlisted reads and --dry-run/--inspect previews still create the gate
files.

Not changed: `bd --readonly backup restore` still creates gate files on
its exclusive acquisition. This PR covers shared gates only. Sibling #7673
refuses a strict-readonly restore before it takes the exclusive gate.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Donna Box <dbox@boxenllc.com>
Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
This commit is contained in:
Julian Knutsen 2026-10-19 04:31:00 +00:00 • committed by GitHub
commit e24940e0c1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 781 additions and 4 deletions

View file

@ -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
`<project>/.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

View file

@ -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

View file

@ -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)
}
}

View file

@ -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"],
)

View file

@ -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 {

View file

@ -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.

View file

@ -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)
}
}