From db0787bb15c18a1b3a657ea52ae128bb8d67fc25 Mon Sep 17 00:00:00 2001 From: ecuthiell Date: Thu, 23 Jul 2026 19:09:33 -0600 Subject: [PATCH] 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 --- internal/linear/synclock.go | 43 +- internal/linear/synclock_info_inline.go | 23 + internal/linear/synclock_info_windows.go | 391 +++++++++ internal/linear/synclock_info_windows_test.go | 824 ++++++++++++++++++ 4 files changed, 1262 insertions(+), 19 deletions(-) create mode 100644 internal/linear/synclock_info_inline.go create mode 100644 internal/linear/synclock_info_windows.go create mode 100644 internal/linear/synclock_info_windows_test.go diff --git a/internal/linear/synclock.go b/internal/linear/synclock.go index c6d8e69c6..c744b1644 100644 --- a/internal/linear/synclock.go +++ b/internal/linear/synclock.go @@ -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. diff --git a/internal/linear/synclock_info_inline.go b/internal/linear/synclock_info_inline.go new file mode 100644 index 000000000..5542df136 --- /dev/null +++ b/internal/linear/synclock_info_inline.go @@ -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) +} diff --git a/internal/linear/synclock_info_windows.go b/internal/linear/synclock_info_windows.go new file mode 100644 index 000000000..afa9f854a --- /dev/null +++ b/internal/linear/synclock_info_windows.go @@ -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) +} diff --git a/internal/linear/synclock_info_windows_test.go b/internal/linear/synclock_info_windows_test.go new file mode 100644 index 000000000..ff2e0ae67 --- /dev/null +++ b/internal/linear/synclock_info_windows_test.go @@ -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) + } +}