Documentation
¶
Overview ¶
Package pilock implements Pi's proper-lockfile directory-lock protocol for shared stores. Ports packages/coding-agent/src/core/auth-storage.ts
Index ¶
Constants ¶
const ( SyncAttempts = 10 SyncDelay = 20 * time.Millisecond // proper-lockfile 4.1.2 lib/lockfile.js:208. SyncStale = 10 * time.Second )
Pi 0.87.1 auth-storage.ts:69-93,119-143 and settings-manager.ts:241-265.
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, reclaiming stale idle legacy sidecars. The caller owns the returned lock until Release.
func AcquireSync ¶
AcquireSync follows Pi's bounded synchronous acquisition loop, reclaiming stale idle legacy sidecars.
func AcquireWithOptions ¶
AcquireWithOptions acquires a proper-lockfile directory with caller-selected fixed retry and heartbeat intervals.
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).
Source Files