pilock

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
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

View Source
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.

View Source
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

func Acquire(ctx context.Context, path string) (*Lock, error)

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

func AcquireAuthSync(path string) (*Lock, error)

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

func AcquireSync(path string) (*Lock, error)

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.

func AcquireWithOptions

func AcquireWithOptions(ctx context.Context, path string, options AcquireOptions) (*Lock, error)

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

func (l *Lock) Check() error

Check refuses a write after cancellation or after the lock has been removed or replaced.

func (*Lock) Compromised

func (l *Lock) Compromised() error

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).

func (*Lock) Context

func (l *Lock) Context() context.Context

Context cancels with the caller or when another process compromises the lock.

func (*Lock) Release

func (l *Lock) Release() error

Release joins the heartbeat before removing the owned directory. Like proper-lockfile's release, its result is the removal's, whether or not the caller's context was cancelled. Repeated calls return the same result.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL