atomic-lockfile 0.0.1-security → 1.4.2

package/src/registry/local.ts

@@ -0,0 +1,37 @@
+import type { LockHandle } from '../types/lock.js';
+
+const localHandles = new Map<string, LockHandle>();
+
+export function registerHandle(handle: LockHandle): void {
+  localHandles.set(handle.lockPath, handle);
+}
+
+export function unregisterHandle(lockPath: string): void {
+  localHandles.delete(lockPath);
+}
+
+export function getHandle(lockPath: string): LockHandle | undefined {
+  return localHandles.get(lockPath);
+}
+
+export function hasHandle(lockPath: string): boolean {
+  return localHandles.has(lockPath);
+}
+
+export function getAllHandles(): LockHandle[] {
+  return [...localHandles.values()];
+}
+
+export function getActiveHandles(): LockHandle[] {
+  return getAllHandles().filter((h) => h.acquired);
+}
+
+export async function releaseAllHandles(): Promise<void> {
+  const handles = [...localHandles.values()];
+  await Promise.allSettled(handles.map((h) => h.release()));
+  localHandles.clear();
+}
+
+export function clearRegistry(): void {
+  localHandles.clear();
+}

package/src/strategies/advisory.ts

@@ -0,0 +1,21 @@
+import type { StrategyDefinition } from '../types/strategy.js';
+
+export const advisoryStrategy: StrategyDefinition = {
+  name: 'advisory',
+  description: 'Cooperative locking — processes agree not to write when a lock is held.',
+  allowsConcurrent: false,
+  requiresKernel: false,
+  crossProcess: true,
+  crossMachine: false,
+  supports: {
+    ttl: true,
+    heartbeat: false,
+    shared: false,
+    upgrade: false,
+    downgrade: false,
+  },
+};
+
+export function isAdvisoryLockRespected(): boolean {
+  return true;
+}

package/src/strategies/exclusive.ts

@@ -0,0 +1,21 @@
+import type { StrategyDefinition } from '../types/strategy.js';
+
+export const exclusiveStrategy: StrategyDefinition = {
+  name: 'exclusive',
+  description: 'Only one process may hold the lock at a time. All others are blocked.',
+  allowsConcurrent: false,
+  requiresKernel: false,
+  crossProcess: true,
+  crossMachine: false,
+  supports: {
+    ttl: true,
+    heartbeat: true,
+    shared: false,
+    upgrade: false,
+    downgrade: false,
+  },
+};
+
+export function isExclusiveCompatible(strategy: string): boolean {
+  return strategy === 'exclusive';
+}

package/src/strategies/index.ts

@@ -0,0 +1,31 @@
+export { exclusiveStrategy } from './exclusive.js';
+export { sharedStrategy } from './shared.js';
+export { advisoryStrategy } from './advisory.js';
+export { optimisticStrategy } from './optimistic.js';
+
+import type { LockStrategy, StrategyDefinition } from '../types/strategy.js';
+import { exclusiveStrategy } from './exclusive.js';
+import { sharedStrategy } from './shared.js';
+import { advisoryStrategy } from './advisory.js';
+import { optimisticStrategy } from './optimistic.js';
+
+const strategyRegistry = new Map<LockStrategy, StrategyDefinition>([
+  ['exclusive', exclusiveStrategy],
+  ['shared', sharedStrategy],
+  ['advisory', advisoryStrategy],
+  ['optimistic', optimisticStrategy],
+]);
+
+export function getStrategy(name: LockStrategy): StrategyDefinition {
+  const strategy = strategyRegistry.get(name);
+  if (!strategy) throw new Error(`Unknown strategy: "${name}"`);
+  return strategy;
+}
+
+export function listStrategies(): LockStrategy[] {
+  return [...strategyRegistry.keys()];
+}
+
+export function isStrategyAvailable(name: LockStrategy): boolean {
+  return strategyRegistry.has(name);
+}

package/src/strategies/optimistic.ts

@@ -0,0 +1,29 @@
+import type { StrategyDefinition } from '../types/strategy.js';
+
+export const optimisticStrategy: StrategyDefinition = {
+  name: 'optimistic',
+  description: 'Assume no conflict; detect conflicts on write and retry.',
+  allowsConcurrent: true,
+  requiresKernel: false,
+  crossProcess: true,
+  crossMachine: true,
+  supports: {
+    ttl: false,
+    heartbeat: false,
+    shared: true,
+    upgrade: false,
+    downgrade: false,
+  },
+};
+
+export interface OptimisticVersion {
+  version: number;
+  etag: string;
+}
+
+export function createOptimisticVersion(data: string): OptimisticVersion {
+  return {
+    version: Date.now(),
+    etag: Buffer.from(data).toString('base64'),
+  };
+}

package/src/strategies/shared.ts

@@ -0,0 +1,23 @@
+import type { StrategyDefinition } from '../types/strategy.js';
+
+export const sharedStrategy: StrategyDefinition = {
+  name: 'shared',
+  description: 'Multiple readers may hold the lock simultaneously; writers require exclusivity.',
+  allowsConcurrent: true,
+  requiresKernel: false,
+  crossProcess: true,
+  crossMachine: false,
+  supports: {
+    ttl: true,
+    heartbeat: true,
+    shared: true,
+    upgrade: true,
+    downgrade: true,
+  },
+};
+
+export function countSharedHolders(lockDir: string, extension: string): Promise<number> {
+  return import('node:fs').then(({ promises }) =>
+    promises.readdir(lockDir).then((files: string[]) => files.filter((f: string) => f.endsWith(extension)).length),
+  );
+}

package/src/sync/check.ts

@@ -0,0 +1,43 @@
+import { accessSync, readFileSync, statSync, constants } from 'node:fs';
+import { resolveLockPath } from '../utils/path.js';
+import { safeDeserializeLockData } from '../utils/serialize.js';
+import { DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+import type { LockFile } from '../types/lock.js';
+
+export function checkSync(filePath: string, lockExtension = DEFAULT_LOCK_EXTENSION): LockFile {
+  const lockPath = resolveLockPath(filePath, lockExtension);
+
+  try {
+    accessSync(lockPath, constants.F_OK);
+  } catch {
+    return { path: filePath, lockPath, data: null, exists: false, readable: false, writable: false, stale: false, expired: false, ageMs: 0 };
+  }
+
+  let raw: string | null = null;
+  try {
+    raw = readFileSync(lockPath, 'utf-8');
+  } catch { /* ignore */ }
+
+  const data = raw ? safeDeserializeLockData(raw) : null;
+
+  let ageMs = 0;
+  try {
+    ageMs = Date.now() - statSync(lockPath).mtimeMs;
+  } catch { /* ignore */ }
+
+  return {
+    path: filePath,
+    lockPath,
+    data,
+    exists: true,
+    readable: raw !== null,
+    writable: true,
+    stale: false,
+    expired: false,
+    ageMs,
+  };
+}
+
+export function isLockedSync(filePath: string, lockExtension = DEFAULT_LOCK_EXTENSION): boolean {
+  return checkSync(filePath, lockExtension).exists;
+}

package/src/sync/index.ts

@@ -0,0 +1,3 @@
+export { lockSync, tryLockSync } from './lock.js';
+export { unlockSync, forceUnlockSync } from './unlock.js';
+export { checkSync, isLockedSync } from './check.js';

package/src/sync/lock.ts

@@ -0,0 +1,38 @@
+import { writeFileSync, accessSync, unlinkSync, constants } from 'node:fs';
+import { resolveLockPath } from '../utils/path.js';
+import { buildLockData } from '../core/buildLockData.js';
+import { serializeLockData } from '../utils/serialize.js';
+import { ConflictError } from '../errors/ConflictError.js';
+import { DEFAULT_LOCK_EXTENSION, DEFAULT_ADAPTER } from '../constants/defaults.js';
+import type { AcquireOptions } from '../types/options.js';
+
+export function lockSync(filePath: string, options: AcquireOptions = {}): { lockPath: string; release: () => void } {
+  const lockPath = resolveLockPath(filePath, options.lockExtension ?? DEFAULT_LOCK_EXTENSION);
+  const data = buildLockData(options);
+  const content = serializeLockData(data);
+
+  try {
+    accessSync(lockPath, constants.F_OK);
+    throw new ConflictError(filePath, lockPath, null);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code !== 'ENOENT') throw err;
+  }
+
+  writeFileSync(lockPath, content, { encoding: 'utf-8', flag: 'wx' });
+
+  return {
+    lockPath,
+    release: () => {
+      try { unlinkSync(lockPath); } catch { /* ignore */ }
+    },
+  };
+}
+
+export function tryLockSync(filePath: string, options?: AcquireOptions): ReturnType<typeof lockSync> | null {
+  try {
+    return lockSync(filePath, options);
+  } catch {
+    return null;
+  }
+}

package/src/sync/unlock.ts

@@ -0,0 +1,19 @@
+import { unlinkSync } from 'node:fs';
+import { resolveLockPath } from '../utils/path.js';
+import { DEFAULT_LOCK_EXTENSION } from '../constants/defaults.js';
+
+export function unlockSync(filePath: string, lockExtension = DEFAULT_LOCK_EXTENSION): void {
+  const lockPath = resolveLockPath(filePath, lockExtension);
+  try {
+    unlinkSync(lockPath);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code !== 'ENOENT') throw err;
+  }
+}
+
+export function forceUnlockSync(lockPath: string): void {
+  try {
+    unlinkSync(lockPath);
+  } catch { /* ignore */ }
+}

package/src/types/adapter.ts

@@ -0,0 +1,23 @@
+export type AdapterName = 'fs' | 'atomic' | 'flock' | 'mkdir' | 'symlink';
+
+export interface Adapter {
+  readonly name: AdapterName;
+  readonly atomic: boolean;
+  readonly crossPlatform: boolean;
+  acquire(lockPath: string, content: string): Promise<void>;
+  release(lockPath: string): Promise<void>;
+  check(lockPath: string): Promise<boolean>;
+  acquireSync?(lockPath: string, content: string): void;
+  releaseSync?(lockPath: string): void;
+  checkSync?(lockPath: string): boolean;
+}
+
+export interface AdapterCapabilities {
+  atomic: boolean;
+  crossPlatform: boolean;
+  supportsSync: boolean;
+  supportsShared: boolean;
+  requiresCleanup: boolean;
+}
+
+export type AdapterFactory = () => Adapter;

package/src/types/events.ts

@@ -0,0 +1,63 @@
+import type { LockData } from './lock.js';
+
+export type LockEventName =
+  | 'acquiring'
+  | 'acquired'
+  | 'releasing'
+  | 'released'
+  | 'refreshing'
+  | 'refreshed'
+  | 'stale'
+  | 'expired'
+  | 'conflict'
+  | 'retry'
+  | 'timeout'
+  | 'error';
+
+export interface LockEvent {
+  name: LockEventName;
+  path: string;
+  lockPath: string;
+  timestamp: number;
+  pid: number;
+}
+
+export interface AcquiredEvent extends LockEvent {
+  name: 'acquired';
+  data: LockData;
+  attempt: number;
+  elapsed: number;
+}
+
+export interface ReleasedEvent extends LockEvent {
+  name: 'released';
+  held: number;
+}
+
+export interface StaleEvent extends LockEvent {
+  name: 'stale';
+  data: LockData;
+  ageMs: number;
+}
+
+export interface RetryEvent extends LockEvent {
+  name: 'retry';
+  attempt: number;
+  delay: number;
+  error: Error;
+}
+
+export interface ErrorEvent extends LockEvent {
+  name: 'error';
+  error: Error;
+}
+
+export type AnyLockEvent =
+  | AcquiredEvent
+  | ReleasedEvent
+  | StaleEvent
+  | RetryEvent
+  | ErrorEvent
+  | LockEvent;
+
+export type LockEventHandler<T extends AnyLockEvent = AnyLockEvent> = (event: T) => void;

package/src/types/index.ts

@@ -0,0 +1,24 @@
+export type { LockData, LockHandle, LockFile, LockState } from './lock.js';
+export type {
+  AcquireOptions,
+  ReleaseOptions,
+  CheckOptions,
+  ListOptions,
+  GlobalOptions,
+  WithLockOptions,
+} from './options.js';
+export type { LockStrategy, StrategyDefinition, StrategyResult } from './strategy.js';
+export type { AdapterName, Adapter, AdapterCapabilities, AdapterFactory } from './adapter.js';
+export type { LogLevel, LogLevelNumber, LogEntry, Logger } from './logger.js';
+export type {
+  LockEventName,
+  LockEvent,
+  AcquiredEvent,
+  ReleasedEvent,
+  StaleEvent,
+  RetryEvent,
+  ErrorEvent,
+  AnyLockEvent,
+  LockEventHandler,
+} from './events.js';
+export type { LockStateSnapshot, GlobalState, ProcessState } from './state.js';

package/src/types/lock.ts

@@ -0,0 +1,40 @@
+export interface LockData {
+  pid: number;
+  hostname: string;
+  uid: number | null;
+  gid: number | null;
+  created: number;
+  updated: number;
+  expires: number | null;
+  ttl: number | null;
+  nonce: string;
+  version: number;
+  strategy: string;
+  meta: Record<string, unknown>;
+}
+
+export interface LockHandle {
+  readonly path: string;
+  readonly lockPath: string;
+  readonly data: LockData;
+  readonly acquired: boolean;
+  release(): Promise<void>;
+  refresh(): Promise<void>;
+  isStale(): boolean;
+  isExpired(): boolean;
+  toJSON(): LockData;
+}
+
+export interface LockFile {
+  path: string;
+  lockPath: string;
+  data: LockData | null;
+  exists: boolean;
+  readable: boolean;
+  writable: boolean;
+  stale: boolean;
+  expired: boolean;
+  ageMs: number;
+}
+
+export type LockState = 'unlocked' | 'locked' | 'stale' | 'expired' | 'unknown';

package/src/types/logger.ts

@@ -0,0 +1,23 @@
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+export type LogLevelNumber = 0 | 1 | 2 | 3 | 4 | 5;
+
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: number;
+  context?: Record<string, unknown>;
+  error?: Error;
+}
+
+export interface Logger {
+  silent(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+  trace(message: string, context?: Record<string, unknown>): void;
+  child(context: Record<string, unknown>): Logger;
+  setLevel(level: LogLevel): void;
+  getLevel(): LogLevel;
+}

package/src/types/options.ts

@@ -0,0 +1,57 @@
+import type { LockStrategy } from './strategy.js';
+import type { AdapterName } from './adapter.js';
+import type { LogLevel } from './logger.js';
+
+export interface AcquireOptions {
+  retries?: number;
+  retryDelay?: number;
+  retryBackoff?: 'linear' | 'exponential' | 'fibonacci' | 'jitter';
+  retryMaxDelay?: number;
+  timeout?: number;
+  ttl?: number;
+  heartbeatInterval?: number;
+  staleAge?: number;
+  removeStale?: boolean;
+  strategy?: LockStrategy;
+  adapter?: AdapterName;
+  lockExtension?: string;
+  meta?: Record<string, unknown>;
+  signal?: AbortSignal;
+  onRetry?: (attempt: number, error: Error) => void;
+  onStale?: (lockPath: string) => void;
+  onAcquired?: (lockPath: string) => void;
+}
+
+export interface ReleaseOptions {
+  force?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface CheckOptions {
+  staleAge?: number;
+  strategy?: LockStrategy;
+  adapter?: AdapterName;
+}
+
+export interface ListOptions {
+  directory?: string;
+  recursive?: boolean;
+  includeStale?: boolean;
+  includeExpired?: boolean;
+  lockExtension?: string;
+}
+
+export interface GlobalOptions {
+  lockExtension?: string;
+  defaultTtl?: number;
+  defaultStaleAge?: number;
+  defaultRetries?: number;
+  defaultStrategy?: LockStrategy;
+  defaultAdapter?: AdapterName;
+  logLevel?: LogLevel;
+  tmpDir?: string;
+}
+
+export interface WithLockOptions extends AcquireOptions {
+  throwOnError?: boolean;
+}

package/src/types/state.ts

@@ -0,0 +1,36 @@
+import type { LockData, LockState } from './lock.js';
+import type { LockStrategy } from './strategy.js';
+import type { AdapterName } from './adapter.js';
+
+export interface LockStateSnapshot {
+  path: string;
+  lockPath: string;
+  state: LockState;
+  data: LockData | null;
+  strategy: LockStrategy;
+  adapter: AdapterName;
+  acquisitions: number;
+  releases: number;
+  failures: number;
+  totalHeldMs: number;
+  lastAcquired: number | null;
+  lastReleased: number | null;
+}
+
+export interface GlobalState {
+  activeLocks: Map<string, LockStateSnapshot>;
+  totalAcquisitions: number;
+  totalReleases: number;
+  totalFailures: number;
+  totalStaleDetections: number;
+  startedAt: number;
+}
+
+export interface ProcessState {
+  pid: number;
+  hostname: string;
+  uid: number | null;
+  gid: number | null;
+  locks: string[];
+  startedAt: number;
+}

package/src/types/strategy.ts

@@ -0,0 +1,31 @@
+export type LockStrategy =
+  | 'exclusive'
+  | 'shared'
+  | 'advisory'
+  | 'mandatory'
+  | 'optimistic'
+  | 'pessimistic';
+
+export interface StrategyDefinition {
+  name: LockStrategy;
+  description: string;
+  allowsConcurrent: boolean;
+  requiresKernel: boolean;
+  crossProcess: boolean;
+  crossMachine: boolean;
+  supports: {
+    ttl: boolean;
+    heartbeat: boolean;
+    shared: boolean;
+    upgrade: boolean;
+    downgrade: boolean;
+  };
+}
+
+export interface StrategyResult {
+  success: boolean;
+  strategy: LockStrategy;
+  elapsed: number;
+  retries: number;
+  error?: Error;
+}

package/src/utils/backoff.ts

@@ -0,0 +1,52 @@
+import { randomJitter } from './random.js';
+
+export type BackoffStrategy = 'linear' | 'exponential' | 'fibonacci' | 'jitter';
+
+export function computeBackoffDelay(
+  attempt: number,
+  baseDelayMs: number,
+  strategy: BackoffStrategy,
+  maxDelayMs: number,
+): number {
+  let delay: number;
+
+  switch (strategy) {
+    case 'linear':
+      delay = baseDelayMs * (attempt + 1);
+      break;
+    case 'exponential':
+      delay = baseDelayMs * Math.pow(2, attempt);
+      break;
+    case 'fibonacci':
+      delay = baseDelayMs * fibonacci(attempt + 1);
+      break;
+    case 'jitter':
+      delay = baseDelayMs * Math.pow(2, attempt) + randomJitter(50);
+      break;
+    default:
+      delay = baseDelayMs;
+  }
+
+  return Math.min(delay, maxDelayMs);
+}
+
+function fibonacci(n: number): number {
+  if (n <= 1) return n;
+  let a = 0, b = 1;
+  for (let i = 2; i <= n; i++) {
+    [a, b] = [b, a + b];
+  }
+  return b;
+}
+
+export function computeExponentialDelay(attempt: number, base: number, max: number): number {
+  return Math.min(base * Math.pow(2, attempt), max);
+}
+
+export function computeLinearDelay(attempt: number, base: number, max: number): number {
+  return Math.min(base * (attempt + 1), max);
+}
+
+export function computeJitteredDelay(base: number, jitterMaxMs: number): number {
+  return base + randomJitter(jitterMaxMs);
+}