fix(linear): correlate Windows sync lock diagnostics (#4990)

Windows LockFileEx prevents contenders from reading inline owner metadata from the fully locked primary guard. Keep that guard as the sole lock authority and preserve the existing Unix path unchanged.

On Windows, publish a strict fixed-size owner record only after taking a random generation-specific byte lease on a stable sidecar handle. Contenders require an exact live process incarnation, shared lease probes, and a stable reread and reprobe before reporting details. Missing, stale, torn, mixed-version, or otherwise uncertain metadata remains generic and never authorizes reclaim.

Invalidate and release diagnostics before the primary guard, while making every sidecar failure best-effort. Cover shared-probe concurrency, stale-live and process-reuse defenses, crash phases, failure injection, open readers, and repeated handoffs.

Agent-Signature: codex-tui-gpt-5.6-sol-ultra on behalf of Ewen Cuthiell
This commit is contained in:
ecuthiell 2026-07-23 19:09:33 -06:00 • committed by GitHub
commit db0787bb15
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 1262 additions and 19 deletions

View file

@ -14,13 +14,15 @@ import (
const syncLockFilename = ".linear-sync.lock"
// SyncLock serializes concurrent bd linear sync invocations within a workspace.
// It combines a PID-annotated lock file with flock for robust mutual exclusion.
// The persistent kernel lock is authoritative. Platform-specific metadata only
// improves contention diagnostics.
type SyncLock struct {
path string
file *os.File
infoPath string
file *os.File
metadata syncLockMetadata
}
// SyncLockInfo contains metadata written into the lock file.
// SyncLockInfo contains advisory metadata published while the sync lock is held.
type SyncLockInfo struct {
PID int
Started time.Time
@ -31,6 +33,7 @@ type SyncLockInfo struct {
// an error immediately when the lock is held by another live process.
func AcquireSyncLock(beadsDir string, wait bool) (*SyncLock, error) {
lockPath := filepath.Join(beadsDir, syncLockFilename)
infoPath := syncLockMetadataPath(beadsDir, lockPath)
if err := os.MkdirAll(beadsDir, 0755); err != nil {
return nil, fmt.Errorf("creating beads directory: %w", err)
@ -49,7 +52,7 @@ func AcquireSyncLock(beadsDir string, wait bool) (*SyncLock, error) {
} else {
if err := lockfile.FlockExclusiveNonBlocking(f); err != nil {
if lockfile.IsLocked(err) || err == lockfile.ErrLockBusy {
info := readLockInfo(lockPath)
info := readContendedSyncLockInfo(infoPath)
_ = f.Close()
return nil, &SyncLockHeldError{Info: info}
}
@ -58,31 +61,33 @@ func AcquireSyncLock(beadsDir string, wait bool) (*SyncLock, error) {
}
}
if err := writeLockInfo(f); err != nil {
metadata, err := publishSyncLockInfo(f, infoPath)
if err != nil {
_ = lockfile.FlockUnlock(f)
_ = f.Close()
return nil, fmt.Errorf("writing lock info: %w", err)
}
return &SyncLock{path: lockPath, file: f}, nil
return &SyncLock{infoPath: infoPath, file: f, metadata: metadata}, nil
}
// Release releases the sync lock. The lock file is NOT removed — removing it
// after unlocking creates a race where a blocked waiter acquires the old inode
// while a new process creates a fresh file at the same path, splitting lock
// identity. Instead the file is truncated while still holding the flock, then
// the flock is released. The stable path is reused by subsequent Acquire calls.
// Release releases the sync lock. The kernel-lock file is NOT removed — doing
// so after unlocking creates a race where a blocked waiter acquires the old
// inode while a new process creates a fresh file at the same path, splitting
// lock identity. On Unix, inline owner metadata is truncated while still
// holding the lock. On Windows, a separate advisory record is cleared while
// still holding the authoritative guard.
func (l *SyncLock) Release() error {
if l == nil || l.file == nil {
return nil
}
// Clear diagnostic metadata while still holding the flock so no reader
// observes a stale PID after we unlock. Truncate failure is non-fatal
// (metadata-only), but we capture it to surface if unlock/close succeed.
var truncErr error
if err := l.file.Truncate(0); err != nil {
truncErr = fmt.Errorf("clearing lock metadata: %w", err)
// Clear or invalidate diagnostic metadata before releasing the authoritative
// lock. Platform helpers preserve Unix errors and make Windows diagnostics
// best-effort.
var metadataErr error
if err := clearSyncLockInfo(l.file, l.infoPath, &l.metadata); err != nil {
metadataErr = fmt.Errorf("clearing lock metadata: %w", err)
}
unlockErr := lockfile.FlockUnlock(l.file)
@ -95,7 +100,7 @@ func (l *SyncLock) Release() error {
if closeErr != nil {
return closeErr
}
return truncErr
return metadataErr
}
// SyncLockHeldError is returned when the lock is held by another process.

View file

@ -0,0 +1,23 @@
//go:build !windows
package linear
import "os"
type syncLockMetadata struct{}
func syncLockMetadataPath(_ string, lockPath string) string {
return lockPath
}
func readContendedSyncLockInfo(path string) *SyncLockInfo {
return readLockInfo(path)
}
func publishSyncLockInfo(f *os.File, _ string) (syncLockMetadata, error) {
return syncLockMetadata{}, writeLockInfo(f)
}
func clearSyncLockInfo(f *os.File, _ string, _ *syncLockMetadata) error {
return f.Truncate(0)
}

View file

@ -0,0 +1,391 @@
//go:build windows
package linear
import (
"crypto/rand"
"crypto/sha256"
"encoding/binary"
"errors"
"io"
"os"
"path/filepath"
"syscall"
"time"
"golang.org/x/sys/windows"
)
const (
syncLockInfoFilename = ".linear-sync.info.lock"
syncLockRecordSize = 512
syncLockRecordVersion uint16 = 2
syncLockRecordMagicOffset = 0
syncLockRecordVersionOffset = 8
syncLockRecordSizeOffset = 10
syncLockRecordPIDOffset = 12
syncLockRecordStartedOffset = 16
syncLockRecordProcessCreatedOffset = 24
syncLockRecordGenerationAOffset = 32
syncLockRecordGenerationBOffset = 48
syncLockRecordChecksumOffset = 64
syncLockRecordPaddingOffset = 96
syncLockGenerationSize = 16
syncLockChecksumSize = sha256.Size
syncLockLeaseOffsetBase = uint64(4096)
syncLockLeaseOffsetMask = uint64(1<<62 - 1)
syncLockGenerationRetries = 8
)
var syncLockRecordMagic = [8]byte{'B', 'D', 'L', 'I', 'N', 'F', 'O', '2'}
type syncLockGeneration [syncLockGenerationSize]byte
type syncLockRecord struct {
info SyncLockInfo
processCreated uint64
generation syncLockGeneration
}
type syncLockMetadata struct {
file *os.File
leaseOffset uint64
leaseHeld bool
ops syncLockWindowsOps
}
type syncLockWindowsOps struct {
openFile func(string, int, os.FileMode) (*os.File, error)
readRandom func([]byte) (int, error)
writeAt func(*os.File, []byte, int64) (int, error)
tryLockGenerationByte func(*os.File, uint64, bool) (bool, error)
unlockGenerationByte func(*os.File, uint64) error
closeFile func(*os.File) error
currentProcessCreation func() (uint64, error)
}
var defaultSyncLockWindowsOps = syncLockWindowsOps{
openFile: os.OpenFile,
readRandom: rand.Read,
writeAt: func(f *os.File, data []byte, offset int64) (int, error) {
return f.WriteAt(data, offset)
},
tryLockGenerationByte: tryLockSyncGenerationByte,
unlockGenerationByte: unlockSyncGenerationByte,
closeFile: func(f *os.File) error {
return f.Close()
},
currentProcessCreation: func() (uint64, error) {
return processCreationFiletime(windows.CurrentProcess())
},
}
func syncLockMetadataPath(beadsDir, _ string) string {
return filepath.Join(beadsDir, syncLockInfoFilename)
}
func publishSyncLockInfo(primary *os.File, path string) (syncLockMetadata, error) {
// Inline metadata cannot be read through Windows' full-range primary lock.
// Clearing legacy content is advisory and must not affect primary ownership.
_ = primary.Truncate(0)
return publishSyncLockInfoWithOps(path, defaultSyncLockWindowsOps), nil
}
func publishSyncLockInfoWithOps(path string, ops syncLockWindowsOps) syncLockMetadata {
sidecar, err := ops.openFile(path, os.O_CREATE|os.O_RDWR, 0600) // #nosec G304 -- path is constrained to the beads directory.
if err != nil {
return syncLockMetadata{}
}
// Once the primary is ours, no cooperating owner can still own its old
// diagnostic generation. Invalidate that record before preparing the next
// generation so setup gaps always degrade to generic contention.
var zeros [syncLockRecordSize]byte
_, _ = ops.writeAt(sidecar, zeros[:], 0)
processCreated, err := ops.currentProcessCreation()
if err != nil || processCreated == 0 {
_ = ops.closeFile(sidecar)
return syncLockMetadata{}
}
started := time.Now().UTC()
for range syncLockGenerationRetries {
var generation syncLockGeneration
n, randomErr := ops.readRandom(generation[:])
if randomErr != nil || n != len(generation) || generation.isZero() {
_ = ops.closeFile(sidecar)
return syncLockMetadata{}
}
leaseOffset := generation.leaseOffset()
acquired, lockErr := ops.tryLockGenerationByte(sidecar, leaseOffset, true)
if lockErr != nil {
_ = ops.closeFile(sidecar)
return syncLockMetadata{}
}
if !acquired {
continue
}
record := syncLockRecord{
info: SyncLockInfo{
PID: os.Getpid(),
Started: started,
},
processCreated: processCreated,
generation: generation,
}
encoded := record.marshal()
written, writeErr := ops.writeAt(sidecar, encoded[:], 0)
if writeErr != nil || written != len(encoded) {
_, _ = ops.writeAt(sidecar, zeros[:], 0)
_ = ops.unlockGenerationByte(sidecar, leaseOffset)
_ = ops.closeFile(sidecar)
return syncLockMetadata{}
}
return syncLockMetadata{
file: sidecar,
leaseOffset: leaseOffset,
leaseHeld: true,
ops: ops,
}
}
_ = ops.closeFile(sidecar)
return syncLockMetadata{}
}
func clearSyncLockInfo(_ *os.File, _ string, metadata *syncLockMetadata) error {
if metadata == nil || metadata.file == nil {
return nil
}
// Invalidate the record before releasing its generation lease. Every step is
// best-effort and completes before the authoritative primary is released.
var zeros [syncLockRecordSize]byte
_, _ = metadata.ops.writeAt(metadata.file, zeros[:], 0)
if metadata.leaseHeld {
_ = metadata.ops.unlockGenerationByte(metadata.file, metadata.leaseOffset)
metadata.leaseHeld = false
}
_ = metadata.ops.closeFile(metadata.file)
metadata.file = nil
return nil
}
func readContendedSyncLockInfo(path string) *SyncLockInfo {
sidecar, err := os.Open(path) // #nosec G304 -- path is constrained to the beads directory.
if err != nil {
return nil
}
defer func() { _ = sidecar.Close() }()
record, first, ok := readSyncLockRecord(sidecar)
if !ok {
return nil
}
process, ok := openMatchingSyncLockProcess(record)
if !ok {
return nil
}
defer func() { _ = windows.CloseHandle(process) }()
active, err := probeSyncGenerationLease(sidecar, record.generation.leaseOffset())
if err != nil || !active {
return nil
}
secondRecord, second, ok := readSyncLockRecord(sidecar)
if !ok || first != second || record.generation != secondRecord.generation {
return nil
}
active, err = probeSyncGenerationLease(sidecar, secondRecord.generation.leaseOffset())
if err != nil || !active || !processHandleIsRunning(process) {
return nil
}
info := record.info
return &info
}
func (record syncLockRecord) marshal() [syncLockRecordSize]byte {
var encoded [syncLockRecordSize]byte
copy(encoded[syncLockRecordMagicOffset:], syncLockRecordMagic[:])
binary.LittleEndian.PutUint16(encoded[syncLockRecordVersionOffset:], syncLockRecordVersion)
binary.LittleEndian.PutUint16(encoded[syncLockRecordSizeOffset:], syncLockRecordSize)
binary.LittleEndian.PutUint32(encoded[syncLockRecordPIDOffset:], uint32(record.info.PID))
binary.LittleEndian.PutUint64(encoded[syncLockRecordStartedOffset:], uint64(record.info.Started.UnixNano()))
binary.LittleEndian.PutUint64(encoded[syncLockRecordProcessCreatedOffset:], record.processCreated)
copy(encoded[syncLockRecordGenerationAOffset:], record.generation[:])
copy(encoded[syncLockRecordGenerationBOffset:], record.generation[:])
checksum := sha256.Sum256(encoded[:])
copy(encoded[syncLockRecordChecksumOffset:], checksum[:])
return encoded
}
func readSyncLockRecord(f *os.File) (syncLockRecord, [syncLockRecordSize]byte, bool) {
var encoded [syncLockRecordSize]byte
n, err := f.ReadAt(encoded[:], 0)
if err != nil && !errors.Is(err, io.EOF) {
return syncLockRecord{}, encoded, false
}
if n != len(encoded) {
return syncLockRecord{}, encoded, false
}
record, ok := parseSyncLockRecord(encoded)
return record, encoded, ok
}
func parseSyncLockRecord(encoded [syncLockRecordSize]byte) (syncLockRecord, bool) {
if [8]byte(encoded[syncLockRecordMagicOffset:syncLockRecordVersionOffset]) != syncLockRecordMagic {
return syncLockRecord{}, false
}
if binary.LittleEndian.Uint16(encoded[syncLockRecordVersionOffset:]) != syncLockRecordVersion ||
binary.LittleEndian.Uint16(encoded[syncLockRecordSizeOffset:]) != syncLockRecordSize {
return syncLockRecord{}, false
}
pid := binary.LittleEndian.Uint32(encoded[syncLockRecordPIDOffset:])
startedUnixNano := int64(binary.LittleEndian.Uint64(encoded[syncLockRecordStartedOffset:]))
processCreated := binary.LittleEndian.Uint64(encoded[syncLockRecordProcessCreatedOffset:])
if pid == 0 || pid > uint32(1<<31-1) || startedUnixNano <= 0 || processCreated == 0 {
return syncLockRecord{}, false
}
var generationA, generationB syncLockGeneration
copy(generationA[:], encoded[syncLockRecordGenerationAOffset:syncLockRecordGenerationBOffset])
copy(generationB[:], encoded[syncLockRecordGenerationBOffset:syncLockRecordChecksumOffset])
if generationA.isZero() || generationA != generationB {
return syncLockRecord{}, false
}
for _, value := range encoded[syncLockRecordPaddingOffset:] {
if value != 0 {
return syncLockRecord{}, false
}
}
var checksum [syncLockChecksumSize]byte
copy(checksum[:], encoded[syncLockRecordChecksumOffset:syncLockRecordPaddingOffset])
checksumInput := encoded
clear(checksumInput[syncLockRecordChecksumOffset:syncLockRecordPaddingOffset])
expected := sha256.Sum256(checksumInput[:])
if checksum != expected {
return syncLockRecord{}, false
}
return syncLockRecord{
info: SyncLockInfo{
PID: int(pid),
Started: time.Unix(0, startedUnixNano).UTC(),
},
processCreated: processCreated,
generation: generationA,
}, true
}
func (generation syncLockGeneration) isZero() bool {
return generation == syncLockGeneration{}
}
func (generation syncLockGeneration) leaseOffset() uint64 {
digest := sha256.Sum256(generation[:])
return syncLockLeaseOffsetBase + (binary.LittleEndian.Uint64(digest[:8]) & syncLockLeaseOffsetMask)
}
func tryLockSyncGenerationByte(f *os.File, offset uint64, exclusive bool) (bool, error) {
flags := uint32(windows.LOCKFILE_FAIL_IMMEDIATELY)
if exclusive {
flags |= windows.LOCKFILE_EXCLUSIVE_LOCK
}
err := windows.LockFileEx(
windows.Handle(f.Fd()),
flags,
0,
1,
0,
overlappedAt(offset),
)
if err == nil {
return true, nil
}
if isSyncGenerationLockConflict(err) {
return false, nil
}
return false, err
}
func unlockSyncGenerationByte(f *os.File, offset uint64) error {
return windows.UnlockFileEx(
windows.Handle(f.Fd()),
0,
1,
0,
overlappedAt(offset),
)
}
func probeSyncGenerationLease(f *os.File, offset uint64) (bool, error) {
acquired, err := tryLockSyncGenerationByte(f, offset, false)
if err != nil {
return false, err
}
if !acquired {
return true, nil
}
if err := unlockSyncGenerationByte(f, offset); err != nil {
return false, err
}
return false, nil
}
func isSyncGenerationLockConflict(err error) bool {
return errors.Is(err, windows.ERROR_LOCK_VIOLATION) || errors.Is(err, syscall.EWOULDBLOCK)
}
func overlappedAt(offset uint64) *windows.Overlapped {
return &windows.Overlapped{
Offset: uint32(offset),
OffsetHigh: uint32(offset >> 32),
}
}
func processCreationFiletime(process windows.Handle) (uint64, error) {
var created, exited, kernel, user windows.Filetime
if err := windows.GetProcessTimes(process, &created, &exited, &kernel, &user); err != nil {
return 0, err
}
return uint64(created.HighDateTime)<<32 | uint64(created.LowDateTime), nil
}
func openMatchingSyncLockProcess(record syncLockRecord) (windows.Handle, bool) {
process, err := windows.OpenProcess(
windows.SYNCHRONIZE|windows.PROCESS_QUERY_LIMITED_INFORMATION,
false,
uint32(record.info.PID),
)
if err != nil {
return 0, false
}
created, err := processCreationFiletime(process)
if err != nil || created != record.processCreated || !processHandleIsRunning(process) {
_ = windows.CloseHandle(process)
return 0, false
}
return process, true
}
func processHandleIsRunning(process windows.Handle) bool {
status, err := windows.WaitForSingleObject(process, 0)
return err == nil && status == uint32(windows.WAIT_TIMEOUT)
}

View file

@ -0,0 +1,824 @@
//go:build windows
package linear
import (
"bufio"
"bytes"
"crypto/sha256"
"errors"
"fmt"
"io"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"testing"
"time"
"github.com/steveyegge/beads/internal/lockfile"
"golang.org/x/sys/windows"
)
const (
syncLockHelperModeEnv = "BD_TEST_LINEAR_SYNC_LOCK_HELPER_MODE"
syncLockHelperDirEnv = "BD_TEST_LINEAR_SYNC_LOCK_HELPER_DIR"
)
func TestSyncLockWindowsRecordRoundTripAndStrictValidation(t *testing.T) {
record := currentSyncLockRecord(t, generationForTest(0x11))
encoded := record.marshal()
parsed, ok := parseSyncLockRecord(encoded)
if !ok {
t.Fatal("valid record did not parse")
}
if parsed.info.PID != record.info.PID ||
parsed.info.Started.UnixNano() != record.info.Started.UnixNano() ||
parsed.processCreated != record.processCreated ||
parsed.generation != record.generation {
t.Fatalf("record changed across round trip: got %+v, want %+v", parsed, record)
}
mutations := map[string]func(*[syncLockRecordSize]byte){
"magic": func(data *[syncLockRecordSize]byte) { data[syncLockRecordMagicOffset] ^= 0xff },
"version": func(data *[syncLockRecordSize]byte) { data[syncLockRecordVersionOffset]++ },
"record size": func(data *[syncLockRecordSize]byte) { data[syncLockRecordSizeOffset]-- },
"zero PID": func(data *[syncLockRecordSize]byte) { clear(data[syncLockRecordPIDOffset:syncLockRecordStartedOffset]) },
"zero lock start": func(data *[syncLockRecordSize]byte) {
clear(data[syncLockRecordStartedOffset:syncLockRecordProcessCreatedOffset])
},
"zero process creation": func(data *[syncLockRecordSize]byte) {
clear(data[syncLockRecordProcessCreatedOffset:syncLockRecordGenerationAOffset])
},
"zero generation": func(data *[syncLockRecordSize]byte) {
clear(data[syncLockRecordGenerationAOffset:syncLockRecordChecksumOffset])
},
"duplicate generation mismatch": func(data *[syncLockRecordSize]byte) { data[syncLockRecordGenerationBOffset] ^= 0xff },
"nonzero padding": func(data *[syncLockRecordSize]byte) { data[syncLockRecordPaddingOffset] = 1 },
}
for name, mutate := range mutations {
t.Run(name, func(t *testing.T) {
corrupt := encoded
mutate(&corrupt)
resignSyncLockRecord(&corrupt)
if _, ok := parseSyncLockRecord(corrupt); ok {
t.Fatal("invalid record parsed successfully")
}
})
}
t.Run("checksum", func(t *testing.T) {
corrupt := encoded
corrupt[syncLockRecordChecksumOffset] ^= 0xff
if _, ok := parseSyncLockRecord(corrupt); ok {
t.Fatal("checksum mismatch parsed successfully")
}
})
t.Run("weak textual sidecar", func(t *testing.T) {
var weak [syncLockRecordSize]byte
copy(weak[:], "pid=1234\nstarted=2026-01-01T00:00:00Z\n")
if _, ok := parseSyncLockRecord(weak); ok {
t.Fatal("weak textual sidecar parsed as a v2 record")
}
})
t.Run("partial record", func(t *testing.T) {
path := filepath.Join(t.TempDir(), syncLockInfoFilename)
if err := os.WriteFile(path, encoded[:syncLockRecordPaddingOffset], 0600); err != nil {
t.Fatalf("write partial record: %v", err)
}
f, err := os.Open(path) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open partial record: %v", err)
}
defer f.Close()
if _, _, ok := readSyncLockRecord(f); ok {
t.Fatal("partial record parsed successfully")
}
})
}
func TestSyncLockWindowsLeaseOffsetBounds(t *testing.T) {
maxOffset := syncLockLeaseOffsetBase + syncLockLeaseOffsetMask
for _, seed := range []byte{0x01, 0x7f, 0xff} {
offset := generationForTest(seed).leaseOffset()
if offset < syncLockLeaseOffsetBase || offset > maxOffset {
t.Fatalf("generation %#x lease offset = %d, want [%d, %d]",
seed, offset, syncLockLeaseOffsetBase, maxOffset)
}
if offset < syncLockRecordSize {
t.Fatalf("generation %#x lease offset %d overlaps the %d-byte metadata record",
seed, offset, syncLockRecordSize)
}
}
}
func TestSyncLockWindowsOverlappedOffsetSplit(t *testing.T) {
const offset = uint64(0x1122334455667788)
overlapped := overlappedAt(offset)
if overlapped.Offset != 0x55667788 {
t.Fatalf("low offset = %#x, want %#x", overlapped.Offset, uint32(0x55667788))
}
if overlapped.OffsetHigh != 0x11223344 {
t.Fatalf("high offset = %#x, want %#x", overlapped.OffsetHigh, uint32(0x11223344))
}
}
func TestSyncLockWindowsValidOwnerLifecycle(t *testing.T) {
dir := t.TempDir()
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("acquire lock: %v", err)
}
if lock.metadata.file == nil || !lock.metadata.leaseHeld {
t.Fatal("Windows owner did not retain its generation lease")
}
record, _, ok := readSyncLockRecord(lock.metadata.file)
if !ok {
t.Fatal("published record did not validate")
}
if record.info.PID != os.Getpid() {
t.Fatalf("record PID = %d, want %d", record.info.PID, os.Getpid())
}
created, err := processCreationFiletime(windows.CurrentProcess())
if err != nil {
t.Fatalf("query current process creation time: %v", err)
}
if record.processCreated != created {
t.Fatalf("record process creation = %d, want %d", record.processCreated, created)
}
held := contendForSyncLock(t, dir)
if held.Info == nil || held.Info.PID != os.Getpid() ||
held.Info.Started.UnixNano() != record.info.Started.UnixNano() {
t.Fatalf("valid owner diagnostics = %+v, want %+v", held.Info, record.info)
}
infoPath := filepath.Join(dir, syncLockInfoFilename)
leaseOffset := record.generation.leaseOffset()
if err := lock.Release(); err != nil {
t.Fatalf("release lock: %v", err)
}
sidecar, err := os.Open(infoPath) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open released sidecar: %v", err)
}
defer sidecar.Close()
stat, err := sidecar.Stat()
if err != nil {
t.Fatalf("stat released sidecar: %v", err)
}
if stat.Size() != syncLockRecordSize {
t.Fatalf("sidecar size = %d, want fixed metadata size %d", stat.Size(), syncLockRecordSize)
}
var cleared [syncLockRecordSize]byte
if n, err := sidecar.ReadAt(cleared[:], 0); err != nil || n != len(cleared) {
t.Fatalf("read cleared sidecar: n=%d err=%v", n, err)
}
if cleared != [syncLockRecordSize]byte{} {
t.Fatal("release did not invalidate the fixed metadata region")
}
active, err := probeSyncGenerationLease(sidecar, leaseOffset)
if err != nil {
t.Fatalf("probe released generation: %v", err)
}
if active {
t.Fatal("generation lease remained active after release")
}
}
func TestSyncLockMetadataReaderDoesNotBlockLifecycle(t *testing.T) {
dir := t.TempDir()
seed, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("seed sidecar: %v", err)
}
if err := seed.Release(); err != nil {
t.Fatalf("release seed lock: %v", err)
}
infoPath := filepath.Join(dir, syncLockInfoFilename)
reader, err := os.Open(infoPath) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open persistent reader: %v", err)
}
defer reader.Close()
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("open reader blocked publication: %v", err)
}
if _, _, ok := readSyncLockRecord(reader); !ok {
t.Fatal("persistent reader did not observe the published record")
}
if err := lock.Release(); err != nil {
t.Fatalf("open reader blocked invalidation or release: %v", err)
}
var cleared [syncLockRecordSize]byte
if n, err := reader.ReadAt(cleared[:], 0); err != nil || n != len(cleared) {
t.Fatalf("read invalidated record through persistent reader: n=%d err=%v", n, err)
}
if cleared != [syncLockRecordSize]byte{} {
t.Fatal("persistent reader did not observe record invalidation")
}
}
func TestAcquireSyncLockWindowsRejectsUncorrelatedMetadata(t *testing.T) {
t.Run("missing sidecar", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
assertGenericSyncLockContention(t, dir)
})
t.Run("weak sidecar record", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
path := filepath.Join(dir, syncLockInfoFilename)
if err := os.WriteFile(path, []byte("pid=1234\nstarted=2026-01-01T00:00:00Z\n"), 0600); err != nil {
t.Fatalf("write weak record: %v", err)
}
assertGenericSyncLockContention(t, dir)
})
t.Run("partial record", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
encoded := currentSyncLockRecord(t, generationForTest(0x21)).marshal()
path := filepath.Join(dir, syncLockInfoFilename)
if err := os.WriteFile(path, encoded[:syncLockRecordPaddingOffset], 0600); err != nil {
t.Fatalf("write partial record: %v", err)
}
assertGenericSyncLockContention(t, dir)
})
t.Run("corrupt record", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
encoded := currentSyncLockRecord(t, generationForTest(0x22)).marshal()
encoded[syncLockRecordChecksumOffset] ^= 0xff
writeSyncLockRecordForTest(t, dir, encoded)
assertGenericSyncLockContention(t, dir)
})
t.Run("old primary owner with live stale strong sidecar", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
encoded := currentSyncLockRecord(t, generationForTest(0x23)).marshal()
writeSyncLockRecordForTest(t, dir, encoded)
assertGenericSyncLockContention(t, dir)
})
t.Run("matching lease with process creation mismatch", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
record := currentSyncLockRecord(t, generationForTest(0x24))
record.processCreated++
writeSyncLockRecordForTest(t, dir, record.marshal())
holdGenerationLeaseForTest(t, dir, record.generation)
assertGenericSyncLockContention(t, dir)
})
t.Run("different generation lease", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
record := currentSyncLockRecord(t, generationForTest(0x25))
writeSyncLockRecordForTest(t, dir, record.marshal())
holdGenerationLeaseForTest(t, dir, generationForTest(0x26))
assertGenericSyncLockContention(t, dir)
})
t.Run("dead PID with matching lease", func(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
record := currentSyncLockRecord(t, generationForTest(0x27))
record.info.PID = 2147483647
writeSyncLockRecordForTest(t, dir, record.marshal())
holdGenerationLeaseForTest(t, dir, record.generation)
assertGenericSyncLockContention(t, dir)
})
}
func TestSyncLockWindowsSharedProbesCannotAuthenticateEachOther(t *testing.T) {
path := filepath.Join(t.TempDir(), syncLockInfoFilename)
if err := os.WriteFile(path, make([]byte, syncLockRecordSize), 0600); err != nil {
t.Fatalf("create sidecar: %v", err)
}
first, err := os.Open(path) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open first probe: %v", err)
}
defer first.Close()
second, err := os.Open(path) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open second probe: %v", err)
}
defer second.Close()
offset := generationForTest(0x31).leaseOffset()
firstAcquired, err := tryLockSyncGenerationByte(first, offset, false)
if err != nil || !firstAcquired {
t.Fatalf("first shared probe: acquired=%v err=%v", firstAcquired, err)
}
defer unlockSyncGenerationByte(first, offset)
secondAcquired, err := tryLockSyncGenerationByte(second, offset, false)
if err != nil || !secondAcquired {
t.Fatalf("second shared probe did not coexist: acquired=%v err=%v", secondAcquired, err)
}
if err := unlockSyncGenerationByte(second, offset); err != nil {
t.Fatalf("unlock second shared probe: %v", err)
}
}
func TestSyncLockWindowsConcurrentContendersRejectFreeStaleGeneration(t *testing.T) {
dir := t.TempDir()
holdPrimarySyncLock(t, dir)
record := currentSyncLockRecord(t, generationForTest(0x32))
writeSyncLockRecordForTest(t, dir, record.marshal())
const contenders = 32
start := make(chan struct{})
results := make(chan error, contenders)
var ready sync.WaitGroup
ready.Add(contenders)
for range contenders {
go func() {
ready.Done()
<-start
_, err := AcquireSyncLock(dir, false)
results <- err
}()
}
ready.Wait()
close(start)
for range contenders {
err := <-results
held, ok := err.(*SyncLockHeldError)
if !ok {
t.Fatalf("contender error = %T %v, want SyncLockHeldError", err, err)
}
if held.Info != nil {
t.Fatalf("concurrent shared probe authenticated stale metadata: %+v", held.Info)
}
}
}
func TestSyncLockWindowsDiagnosticFailuresDoNotAffectPrimary(t *testing.T) {
t.Run("sidecar open failure", func(t *testing.T) {
dir := t.TempDir()
if err := os.Mkdir(filepath.Join(dir, syncLockInfoFilename), 0700); err != nil {
t.Fatalf("create directory at sidecar path: %v", err)
}
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("sidecar open failure prevented primary acquisition: %v", err)
}
assertGenericSyncLockContention(t, dir)
if err := lock.Release(); err != nil {
t.Fatalf("sidecar open failure prevented primary release: %v", err)
}
})
t.Run("all generation bytes busy", func(t *testing.T) {
dir := t.TempDir()
if err := os.MkdirAll(dir, 0755); err != nil {
t.Fatalf("create lock directory: %v", err)
}
path := filepath.Join(dir, syncLockInfoFilename)
blocker, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open sidecar blocker: %v", err)
}
if err := lockfile.FlockExclusiveNonBlocking(blocker); err != nil {
_ = blocker.Close()
t.Fatalf("lock full sidecar range: %v", err)
}
defer func() {
_ = lockfile.FlockUnlock(blocker)
_ = blocker.Close()
}()
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("lease collision prevented primary acquisition: %v", err)
}
if lock.metadata.file != nil {
t.Fatal("diagnostic metadata survived exhaustive lease collision")
}
assertGenericSyncLockContention(t, dir)
if err := lock.Release(); err != nil {
t.Fatalf("lease collision prevented primary release: %v", err)
}
})
t.Run("short metadata write", func(t *testing.T) {
dir := t.TempDir()
primary := holdPrimarySyncLock(t, dir)
path := filepath.Join(dir, syncLockInfoFilename)
generation := generationForTest(0x41)
ops := defaultSyncLockWindowsOps
ops.readRandom = deterministicGenerationReader(generation)
ops.writeAt = func(f *os.File, data []byte, offset int64) (int, error) {
if len(data) == syncLockRecordSize && [8]byte(data[:8]) == syncLockRecordMagic {
n, _ := f.WriteAt(data[:syncLockRecordPaddingOffset], offset)
return n, io.ErrShortWrite
}
return f.WriteAt(data, offset)
}
metadata := publishSyncLockInfoWithOps(path, ops)
if metadata.file != nil {
t.Fatal("short record write retained a diagnostic lease")
}
assertGenericSyncLockContention(t, dir)
sidecar, err := os.Open(path) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open failed-publication sidecar: %v", err)
}
defer sidecar.Close()
active, err := probeSyncGenerationLease(sidecar, generation.leaseOffset())
if err != nil || active {
t.Fatalf("failed publication retained lease: active=%v err=%v", active, err)
}
runtime.KeepAlive(primary)
})
t.Run("clear unlock and close errors", func(t *testing.T) {
dir := t.TempDir()
primary := holdPrimarySyncLock(t, dir)
path := filepath.Join(dir, syncLockInfoFilename)
generation := generationForTest(0x42)
releasing := false
ops := defaultSyncLockWindowsOps
ops.readRandom = deterministicGenerationReader(generation)
ops.writeAt = func(f *os.File, data []byte, offset int64) (int, error) {
if releasing {
return 0, errors.New("injected clear failure")
}
return f.WriteAt(data, offset)
}
ops.unlockGenerationByte = func(f *os.File, offset uint64) error {
err := unlockSyncGenerationByte(f, offset)
if err != nil {
return err
}
return errors.New("injected unlock report")
}
ops.closeFile = func(f *os.File) error {
err := f.Close()
if err != nil {
return err
}
return errors.New("injected close report")
}
metadata := publishSyncLockInfoWithOps(path, ops)
if metadata.file == nil {
t.Fatal("failed to publish fixture metadata")
}
releasing = true
if err := clearSyncLockInfo(primary, path, &metadata); err != nil {
t.Fatalf("diagnostic release errors escaped helper: %v", err)
}
if metadata.file != nil {
t.Fatal("diagnostic metadata retained a closed handle")
}
assertGenericSyncLockContention(t, dir)
})
}
func TestSyncLockWindowsReleaseInvalidatesBeforePrimaryUnlock(t *testing.T) {
dir := t.TempDir()
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("acquire owner: %v", err)
}
if err := clearSyncLockInfo(lock.file, lock.infoPath, &lock.metadata); err != nil {
t.Fatalf("invalidate diagnostics: %v", err)
}
assertGenericSyncLockContention(t, dir)
if err := lock.Release(); err != nil {
t.Fatalf("release primary after diagnostic phase: %v", err)
}
}
func TestSyncLockWindowsSubprocessPhases(t *testing.T) {
if os.Getenv(syncLockHelperModeEnv) != "" {
t.Skip("parent-only test")
}
tests := []struct {
mode string
expectInfo bool
}{
{mode: "primary"},
{mode: "lease"},
{mode: "partial"},
{mode: "complete", expectInfo: true},
}
for _, tt := range tests {
t.Run(tt.mode, func(t *testing.T) {
dir := t.TempDir()
helper := startSyncLockHelper(t, dir, tt.mode)
defer helper.stop()
held := contendForSyncLock(t, dir)
if tt.expectInfo {
if held.Info == nil || held.Info.PID != helper.cmd.Process.Pid {
t.Fatalf("complete helper diagnostics = %+v, want PID %d", held.Info, helper.cmd.Process.Pid)
}
} else if held.Info != nil {
t.Fatalf("%s phase exposed uncorrelated metadata: %+v", tt.mode, held.Info)
}
helper.stop()
lock := acquireSyncLockEventually(t, dir, 5*time.Second)
if err := lock.Release(); err != nil {
t.Fatalf("release successor after %s crash: %v", tt.mode, err)
}
})
}
}
func TestSyncLockWindowsSubprocessHelper(t *testing.T) {
mode := os.Getenv(syncLockHelperModeEnv)
if mode == "" {
return
}
dir := os.Getenv(syncLockHelperDirEnv)
if dir == "" {
t.Fatal("helper directory is empty")
}
var primary, sidecar *os.File
var owner *SyncLock
var leaseOffset uint64
switch mode {
case "complete":
var err error
owner, err = AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("helper acquire complete owner: %v", err)
}
defer owner.Release()
case "primary", "lease", "partial":
if err := os.MkdirAll(dir, 0755); err != nil {
t.Fatalf("helper create directory: %v", err)
}
var err error
primary, err = os.OpenFile(filepath.Join(dir, syncLockFilename), os.O_CREATE|os.O_RDWR, 0600)
if err != nil {
t.Fatalf("helper open primary: %v", err)
}
if err := lockfile.FlockExclusiveNonBlocking(primary); err != nil {
t.Fatalf("helper lock primary: %v", err)
}
defer func() {
_ = lockfile.FlockUnlock(primary)
_ = primary.Close()
}()
if mode != "primary" {
sidecar, err = os.OpenFile(filepath.Join(dir, syncLockInfoFilename), os.O_CREATE|os.O_RDWR, 0600)
if err != nil {
t.Fatalf("helper open sidecar: %v", err)
}
generation := generationForTest(0x51)
leaseOffset = generation.leaseOffset()
acquired, err := tryLockSyncGenerationByte(sidecar, leaseOffset, true)
if err != nil || !acquired {
t.Fatalf("helper acquire generation: acquired=%v err=%v", acquired, err)
}
defer func() {
_ = unlockSyncGenerationByte(sidecar, leaseOffset)
_ = sidecar.Close()
}()
if mode == "partial" {
record := currentSyncLockRecord(t, generation)
encoded := record.marshal()
if n, err := sidecar.WriteAt(encoded[:syncLockRecordPaddingOffset], 0); err != nil || n != syncLockRecordPaddingOffset {
t.Fatalf("helper write partial record: n=%d err=%v", n, err)
}
}
}
default:
t.Fatalf("unknown helper mode %q", mode)
}
fmt.Println("READY")
_, _ = io.Copy(io.Discard, os.Stdin)
runtime.KeepAlive(owner)
runtime.KeepAlive(primary)
runtime.KeepAlive(sidecar)
runtime.KeepAlive(leaseOffset)
}
func TestSyncLockWindowsRepeatedHandoffs(t *testing.T) {
dir := t.TempDir()
for i := 0; i < 100; i++ {
lock, err := AcquireSyncLock(dir, false)
if err != nil {
t.Fatalf("iteration %d acquire: %v", i, err)
}
held := contendForSyncLock(t, dir)
if held.Info == nil || held.Info.PID != os.Getpid() {
t.Fatalf("iteration %d diagnostics = %+v", i, held.Info)
}
if err := lock.Release(); err != nil {
t.Fatalf("iteration %d release: %v", i, err)
}
}
}
func currentSyncLockRecord(t *testing.T, generation syncLockGeneration) syncLockRecord {
t.Helper()
created, err := processCreationFiletime(windows.CurrentProcess())
if err != nil {
t.Fatalf("query current process creation: %v", err)
}
return syncLockRecord{
info: SyncLockInfo{
PID: os.Getpid(),
Started: time.Now().UTC(),
},
processCreated: created,
generation: generation,
}
}
func generationForTest(value byte) syncLockGeneration {
var generation syncLockGeneration
for i := range generation {
generation[i] = value
}
return generation
}
func resignSyncLockRecord(data *[syncLockRecordSize]byte) {
clear(data[syncLockRecordChecksumOffset:syncLockRecordPaddingOffset])
checksum := sha256.Sum256(data[:])
copy(data[syncLockRecordChecksumOffset:], checksum[:])
}
func writeSyncLockRecordForTest(t *testing.T, dir string, encoded [syncLockRecordSize]byte) {
t.Helper()
path := filepath.Join(dir, syncLockInfoFilename)
if err := os.WriteFile(path, encoded[:], 0600); err != nil {
t.Fatalf("write sidecar record: %v", err)
}
}
func holdPrimarySyncLock(t *testing.T, dir string) *os.File {
t.Helper()
if err := os.MkdirAll(dir, 0755); err != nil {
t.Fatalf("create lock directory: %v", err)
}
path := filepath.Join(dir, syncLockFilename)
f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open primary lock: %v", err)
}
if err := lockfile.FlockExclusiveNonBlocking(f); err != nil {
_ = f.Close()
t.Fatalf("acquire primary lock: %v", err)
}
t.Cleanup(func() {
_ = lockfile.FlockUnlock(f)
_ = f.Close()
})
return f
}
func holdGenerationLeaseForTest(t *testing.T, dir string, generation syncLockGeneration) *os.File {
t.Helper()
path := filepath.Join(dir, syncLockInfoFilename)
f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0600) // #nosec G304 -- test path is under t.TempDir.
if err != nil {
t.Fatalf("open sidecar lease: %v", err)
}
offset := generation.leaseOffset()
acquired, err := tryLockSyncGenerationByte(f, offset, true)
if err != nil || !acquired {
_ = f.Close()
t.Fatalf("acquire sidecar lease: acquired=%v err=%v", acquired, err)
}
t.Cleanup(func() {
_ = unlockSyncGenerationByte(f, offset)
_ = f.Close()
})
return f
}
func contendForSyncLock(t *testing.T, dir string) *SyncLockHeldError {
t.Helper()
_, err := AcquireSyncLock(dir, false)
if err == nil {
t.Fatal("acquire should fail while primary lock is held")
}
held, ok := err.(*SyncLockHeldError)
if !ok {
t.Fatalf("contention error = %T %v, want SyncLockHeldError", err, err)
}
return held
}
func assertGenericSyncLockContention(t *testing.T, dir string) {
t.Helper()
held := contendForSyncLock(t, dir)
if held.Info != nil {
t.Fatalf("uncorrelated metadata produced owner diagnostics: %+v", held.Info)
}
}
func deterministicGenerationReader(generation syncLockGeneration) func([]byte) (int, error) {
return func(destination []byte) (int, error) {
return copy(destination, generation[:]), nil
}
}
type syncLockHelperProcess struct {
cmd *exec.Cmd
stdin io.WriteCloser
stderr *bytes.Buffer
}
func startSyncLockHelper(t *testing.T, dir, mode string) *syncLockHelperProcess {
t.Helper()
cmd := exec.Command(os.Args[0], "-test.run=^TestSyncLockWindowsSubprocessHelper$")
cmd.Env = append(os.Environ(),
syncLockHelperModeEnv+"="+mode,
syncLockHelperDirEnv+"="+dir,
)
stdin, err := cmd.StdinPipe()
if err != nil {
t.Fatalf("create helper stdin: %v", err)
}
stdout, err := cmd.StdoutPipe()
if err != nil {
t.Fatalf("create helper stdout: %v", err)
}
stderr := &bytes.Buffer{}
cmd.Stderr = stderr
if err := cmd.Start(); err != nil {
t.Fatalf("start helper: %v", err)
}
ready := make(chan string, 1)
go func() {
line, _ := bufio.NewReader(stdout).ReadString('\n')
ready <- strings.TrimSpace(line)
}()
select {
case line := <-ready:
if line != "READY" {
_ = cmd.Process.Kill()
_ = cmd.Wait()
t.Fatalf("helper readiness = %q, stderr=%s", line, stderr.String())
}
case <-time.After(10 * time.Second):
_ = cmd.Process.Kill()
_ = cmd.Wait()
t.Fatalf("helper readiness timed out, stderr=%s", stderr.String())
}
return &syncLockHelperProcess{cmd: cmd, stdin: stdin, stderr: stderr}
}
func (helper *syncLockHelperProcess) stop() {
if helper == nil || helper.cmd == nil {
return
}
_ = helper.cmd.Process.Kill()
_ = helper.stdin.Close()
_ = helper.cmd.Wait()
helper.cmd = nil
}
func acquireSyncLockEventually(t *testing.T, dir string, timeout time.Duration) *SyncLock {
t.Helper()
deadline := time.Now().Add(timeout)
for {
lock, err := AcquireSyncLock(dir, false)
if err == nil {
return lock
}
if _, ok := err.(*SyncLockHeldError); !ok {
t.Fatalf("successor acquire failed: %v", err)
}
if time.Now().After(deadline) {
t.Fatalf("primary lock remained busy after helper exit: %v", err)
}
time.Sleep(10 * time.Millisecond)
}
}