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