Documentation
¶
Overview ¶
Package pilock implements Pi's proper-lockfile directory-lock protocol for shared stores. Ports packages/coding-agent/src/core/auth-storage.ts Ports packages/coding-agent/src/core/trust-manager.ts
Index ¶
Constants ¶
const ( SyncAttempts = 10 SyncDelay = 20 * time.Millisecond // proper-lockfile 4.1.2 lib/lockfile.js:208. SyncStale = 10 * time.Second )
Pi 1.2.0 auth-storage.ts:81-95,117-155, settings-manager.ts:195-215 and trust-manager.ts:137-164.
Variables ¶
var ErrLegacyLocked = fmt.Errorf("%w by an older PiG process; stop the older PiG before upgrading", ErrLocked)
ErrLegacyLocked reports an older PiG writer; acquisition uses the same retry budget as directory contention.
var ErrLocked = errors.New("Lock file is already being held")
ErrLocked reports contention under Pi's directory protocol. Its text is proper-lockfile 4.1.2's ELOCKED message (lib/lockfile.js:53,68), which Pi's stores rethrow unchanged.
Functions ¶
func RemoveHeldLocks ¶
func RemoveHeldLocks()
RemoveHeldLocks removes the lock directory of every lock this process still holds, ignoring failures. It is proper-lockfile's process-exit hook (lib/lockfile.js:331-337), which Node runs on every exit including an uncaught exception. Go has no exit hook, so a caller that ends the process without returning through Release calls it first.
Types ¶
type AcquireOptions ¶
type AcquireOptions struct {
Stale, Update, Retry, Wait time.Duration
// OnCompromised is proper-lockfile's onCompromised: it receives the error when the heartbeat finds the lock removed, replaced or not refreshed within Stale. A nil value only cancels Context, which is the behavior auth storage needs. The callback runs on the heartbeat goroutine after Context is cancelled.
OnCompromised func(error)
}
AcquireOptions selects the stale, heartbeat, and bounded retry intervals of a directory lock.
type CompromisedError ¶
type CompromisedError struct {
Cause error
}
CompromisedError is the ECOMPROMISED error that proper-lockfile 4.1.2 passes to onCompromised (lib/lockfile.js:119-138,153-156,185-201). Cause is the failed stat or utime, or nil when the lock directory's mtime is no longer ours.
func (*CompromisedError) Code ¶
func (*CompromisedError) Code() string
Code is the error code proper-lockfile assigns to every compromise (lib/lockfile.js:121,137,155).
func (*CompromisedError) Error ¶
func (e *CompromisedError) Error() string
Error is the Node message: the fs error text `<CODE>: <description>, <syscall> '<path>'`, or lib/lockfile.js:136's message when the mtime changed.
func (*CompromisedError) Inspect ¶
func (e *CompromisedError) Inspect() string
Inspect renders the error as Node's util.inspect does when a throw from a timer reaches the uncaught-exception handler, without the stack frames of the JavaScript source.
func (*CompromisedError) Unwrap ¶
func (e *CompromisedError) Unwrap() []error
Unwrap keeps errors.Is matching the compromise itself and the file-system failure behind it.
type Lock ¶
type Lock struct {
// contains filtered or unexported fields
}
Lock owns a directory and its mtime heartbeat. Compromise cancels its operation context; Release joins the heartbeat and removes only the owned directory.
func Acquire ¶
Acquire follows Pi's cancellable auth acquisition loop, FileAuthStorageBackend.acquireLockAsync (auth-storage.ts:117-155), reclaiming stale idle legacy sidecars. It retries ELOCKED until its 30 s deadline and, on Windows, EPERM at most maxEPERMRetries times; both share one backoff. The caller owns the returned lock until Release.
func AcquireAuthSync ¶
AcquireAuthSync is FileAuthStorageBackend.acquireLockSyncWithRetry (auth-storage.ts:81-95), the synchronous auth loop: ten attempts 20 ms apart that retry ELOCKED and, on Windows, EPERM. It reclaims stale idle legacy sidecars.
func AcquireSync ¶
AcquireSync is the settings and trust loop, settings-manager.ts acquireLockSyncWithRetry and trust-manager.ts acquireTrustLockSync: ten attempts 20 ms apart that retry only ELOCKED. It reclaims stale idle legacy sidecars. Ports packages/coding-agent/src/core/settings-manager.ts
func AcquireWithOptions ¶
AcquireWithOptions acquires a proper-lockfile directory with caller-selected fixed retry and heartbeat intervals. It is proper-lockfile 4.1.2's lock with a retries option (lib/lockfile.js:231-240): the retry module retries every failed attempt, whatever its error, so EPERM from a mkdir that Windows refuses while another process's release is still pending deletion waits like ELOCKED. When Wait ends it returns the retry module's mainError, the most frequent error message with ties going to the later error.
func (*Lock) Check ¶
Check refuses a write after cancellation or after the lock has been removed or replaced.
func (*Lock) Compromised ¶
Compromised reports that the lock has been removed or replaced, without the caller's cancellation. It is withLockAsync's throwIfCompromised, which Pi applies after a write (auth-storage.ts:168-172,189).