atomic-lockfile 0.0.1-security → 1.4.2

package/src/errors/ConflictError.ts

@@ -0,0 +1,28 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+import type { LockData } from '../types/lock.js';
+
+export class ConflictError extends LockError {
+  public override name = 'ConflictError';
+  public readonly holderData: LockData | null;
+
+  constructor(path: string, lockPath: string, holderData: LockData | null) {
+    super(
+      ERROR_CODES.LOCK_CONFLICT,
+      path,
+      lockPath,
+      holderData
+        ? `Lock on "${path}" is held by PID ${holderData.pid} on ${holderData.hostname}`
+        : `Lock on "${path}" is already held`,
+    );
+    this.holderData = holderData;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      holderData: this.holderData,
+    };
+  }
+}

package/src/errors/IOError.ts

@@ -0,0 +1,39 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class IOError extends LockError {
+  public override name = 'IOError';
+  public readonly operation: string;
+  public readonly syscall: string | undefined;
+  public readonly errno: number | undefined;
+
+  constructor(
+    path: string,
+    lockPath: string,
+    operation: string,
+    cause: Error,
+    syscall?: string,
+    errno?: number,
+  ) {
+    super(
+      ERROR_CODES.LOCK_IO,
+      path,
+      lockPath,
+      `I/O error during "${operation}" on "${lockPath}": ${cause.message}`,
+      cause,
+    );
+    this.operation = operation;
+    this.syscall = syscall;
+    this.errno = errno;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      operation: this.operation,
+      syscall: this.syscall,
+      errno: this.errno,
+    };
+  }
+}

package/src/errors/LockError.ts

@@ -0,0 +1,39 @@
+import type { ErrorCode } from '../constants/errors.js';
+import { ERROR_MESSAGES } from '../constants/errors.js';
+
+export class LockError extends Error {
+  public override name: string = 'LockError';
+  public readonly code: ErrorCode;
+  public readonly path: string;
+  public readonly lockPath: string;
+  public readonly timestamp: number;
+  public override readonly cause: Error | undefined;
+
+  constructor(
+    code: ErrorCode,
+    path: string,
+    lockPath: string,
+    message?: string,
+    cause?: Error,
+  ) {
+    super(message ?? ERROR_MESSAGES[code]);
+    this.code = code;
+    this.path = path;
+    this.lockPath = lockPath;
+    this.timestamp = Date.now();
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      path: this.path,
+      lockPath: this.lockPath,
+      timestamp: this.timestamp,
+      cause: this.cause?.message,
+    };
+  }
+}

package/src/errors/PermissionError.ts

@@ -0,0 +1,35 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class PermissionError extends LockError {
+  public override name = 'PermissionError';
+  public readonly operation: string;
+  public readonly requiredMode: string;
+
+  constructor(
+    path: string,
+    lockPath: string,
+    operation: string,
+    requiredMode: string,
+    cause?: Error,
+  ) {
+    super(
+      ERROR_CODES.LOCK_PERMISSION,
+      path,
+      lockPath,
+      `Permission denied: cannot perform "${operation}" on "${lockPath}" (requires ${requiredMode})`,
+      cause,
+    );
+    this.operation = operation;
+    this.requiredMode = requiredMode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      operation: this.operation,
+      requiredMode: this.requiredMode,
+    };
+  }
+}

package/src/errors/StaleError.ts

@@ -0,0 +1,41 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class StaleError extends LockError {
+  public override name = 'StaleError';
+  public readonly staleAgeMs: number;
+  public readonly actualAgeMs: number;
+  public readonly stalePid: number;
+  public readonly staleHostname: string;
+
+  constructor(
+    path: string,
+    lockPath: string,
+    staleAgeMs: number,
+    actualAgeMs: number,
+    stalePid: number,
+    staleHostname: string,
+  ) {
+    super(
+      ERROR_CODES.LOCK_STALE,
+      path,
+      lockPath,
+      `Lock on "${path}" is stale: held by PID ${stalePid} on ${staleHostname} for ${actualAgeMs}ms (threshold: ${staleAgeMs}ms)`,
+    );
+    this.staleAgeMs = staleAgeMs;
+    this.actualAgeMs = actualAgeMs;
+    this.stalePid = stalePid;
+    this.staleHostname = staleHostname;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      staleAgeMs: this.staleAgeMs,
+      actualAgeMs: this.actualAgeMs,
+      stalePid: this.stalePid,
+      staleHostname: this.staleHostname,
+    };
+  }
+}

package/src/errors/TimeoutError.ts

@@ -0,0 +1,28 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class TimeoutError extends LockError {
+  public override name = 'TimeoutError';
+  public readonly timeoutMs: number;
+  public readonly attempts: number;
+
+  constructor(path: string, lockPath: string, timeoutMs: number, attempts: number) {
+    super(
+      ERROR_CODES.LOCK_TIMEOUT,
+      path,
+      lockPath,
+      `Timed out after ${timeoutMs}ms and ${attempts} attempt(s) waiting for lock on "${path}"`,
+    );
+    this.timeoutMs = timeoutMs;
+    this.attempts = attempts;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      timeoutMs: this.timeoutMs,
+      attempts: this.attempts,
+    };
+  }
+}

package/src/errors/ValidationError.ts

@@ -0,0 +1,28 @@
+import { LockError } from './LockError.js';
+import { ERROR_CODES } from '../constants/errors.js';
+
+export class ValidationError extends LockError {
+  public override name = 'ValidationError';
+  public readonly field: string;
+  public readonly received: unknown;
+
+  constructor(path: string, lockPath: string, field: string, received: unknown, reason: string) {
+    super(
+      ERROR_CODES.LOCK_VALIDATION,
+      path,
+      lockPath,
+      `Validation failed for field "${field}": ${reason} (received: ${JSON.stringify(received)})`,
+    );
+    this.field = field;
+    this.received = received;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return {
+      ...super.toJSON(),
+      field: this.field,
+      received: this.received,
+    };
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,28 @@
+export { LockError } from './LockError.js';
+export { TimeoutError } from './TimeoutError.js';
+export { StaleError } from './StaleError.js';
+export { ConflictError } from './ConflictError.js';
+export { ValidationError } from './ValidationError.js';
+export { PermissionError } from './PermissionError.js';
+export { IOError } from './IOError.js';
+export { AbortError } from './AbortError.js';
+
+export function isLockError(err: unknown): err is import('./LockError.js').LockError {
+  return err instanceof Error && err.name.endsWith('Error') && 'code' in err && 'lockPath' in err;
+}
+
+export function isConflictError(err: unknown): err is import('./ConflictError.js').ConflictError {
+  return err instanceof Error && err.name === 'ConflictError';
+}
+
+export function isTimeoutError(err: unknown): err is import('./TimeoutError.js').TimeoutError {
+  return err instanceof Error && err.name === 'TimeoutError';
+}
+
+export function isStaleError(err: unknown): err is import('./StaleError.js').StaleError {
+  return err instanceof Error && err.name === 'StaleError';
+}
+
+export function isAbortError(err: unknown): err is import('./AbortError.js').AbortError {
+  return err instanceof Error && err.name === 'AbortError';
+}

package/src/events/emitter.ts

@@ -0,0 +1,50 @@
+import type { AnyLockEvent, LockEventHandler, LockEventName } from '../types/events.js';
+
+type HandlerMap = Map<LockEventName | '*', Set<LockEventHandler>>;
+
+export class LockEventEmitter {
+  private readonly handlers: HandlerMap = new Map();
+
+  on<T extends AnyLockEvent>(event: LockEventName | '*', handler: LockEventHandler<T>): this {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler as LockEventHandler);
+    return this;
+  }
+
+  off<T extends AnyLockEvent>(event: LockEventName | '*', handler: LockEventHandler<T>): this {
+    this.handlers.get(event)?.delete(handler as LockEventHandler);
+    return this;
+  }
+
+  once<T extends AnyLockEvent>(event: LockEventName | '*', handler: LockEventHandler<T>): this {
+    const wrapper: LockEventHandler = (e) => {
+      handler(e as T);
+      this.off(event, wrapper);
+    };
+    return this.on(event, wrapper);
+  }
+
+  emit(event: AnyLockEvent): void {
+    const specific = this.handlers.get(event.name);
+    const wildcard = this.handlers.get('*');
+    specific?.forEach((h) => h(event));
+    wildcard?.forEach((h) => h(event));
+  }
+
+  removeAllListeners(event?: LockEventName | '*'): this {
+    if (event) {
+      this.handlers.delete(event);
+    } else {
+      this.handlers.clear();
+    }
+    return this;
+  }
+
+  listenerCount(event: LockEventName | '*'): number {
+    return this.handlers.get(event)?.size ?? 0;
+  }
+}
+
+export const globalEmitter = new LockEventEmitter();

package/src/events/index.ts

@@ -0,0 +1,2 @@
+export { LockEventEmitter, globalEmitter } from './emitter.js';
+export * from './types.js';

package/src/events/types.ts

@@ -0,0 +1,16 @@
+export type { LockEventName, LockEvent, AcquiredEvent, ReleasedEvent, StaleEvent, RetryEvent, ErrorEvent, AnyLockEvent, LockEventHandler } from '../types/events.js';
+
+export const LOCK_EVENT_NAMES = [
+  'acquiring',
+  'acquired',
+  'releasing',
+  'released',
+  'refreshing',
+  'refreshed',
+  'stale',
+  'expired',
+  'conflict',
+  'retry',
+  'timeout',
+  'error',
+] as const;

package/src/hooks/afterLock.ts

@@ -0,0 +1,24 @@
+import type { LockHandle } from '../types/lock.js';
+
+export type AfterLockHook = (handle: LockHandle) => void | Promise<void>;
+
+const afterLockHooks: AfterLockHook[] = [];
+
+export function addAfterLockHook(hook: AfterLockHook): void {
+  afterLockHooks.push(hook);
+}
+
+export function removeAfterLockHook(hook: AfterLockHook): void {
+  const idx = afterLockHooks.indexOf(hook);
+  if (idx !== -1) afterLockHooks.splice(idx, 1);
+}
+
+export async function runAfterLockHooks(handle: LockHandle): Promise<void> {
+  for (const hook of afterLockHooks) {
+    await hook(handle);
+  }
+}
+
+export function clearAfterLockHooks(): void {
+  afterLockHooks.length = 0;
+}

package/src/hooks/afterUnlock.ts

@@ -0,0 +1,24 @@
+import type { LockHandle } from '../types/lock.js';
+
+export type AfterUnlockHook = (handle: LockHandle) => void | Promise<void>;
+
+const afterUnlockHooks: AfterUnlockHook[] = [];
+
+export function addAfterUnlockHook(hook: AfterUnlockHook): void {
+  afterUnlockHooks.push(hook);
+}
+
+export function removeAfterUnlockHook(hook: AfterUnlockHook): void {
+  const idx = afterUnlockHooks.indexOf(hook);
+  if (idx !== -1) afterUnlockHooks.splice(idx, 1);
+}
+
+export async function runAfterUnlockHooks(handle: LockHandle): Promise<void> {
+  for (const hook of afterUnlockHooks) {
+    await hook(handle);
+  }
+}
+
+export function clearAfterUnlockHooks(): void {
+  afterUnlockHooks.length = 0;
+}

package/src/hooks/beforeLock.ts

@@ -0,0 +1,28 @@
+import type { AcquireOptions } from '../types/options.js';
+
+export type BeforeLockHook = (path: string, lockPath: string, options: AcquireOptions) => void | Promise<void>;
+
+const beforeLockHooks: BeforeLockHook[] = [];
+
+export function addBeforeLockHook(hook: BeforeLockHook): void {
+  beforeLockHooks.push(hook);
+}
+
+export function removeBeforeLockHook(hook: BeforeLockHook): void {
+  const idx = beforeLockHooks.indexOf(hook);
+  if (idx !== -1) beforeLockHooks.splice(idx, 1);
+}
+
+export async function runBeforeLockHooks(
+  path: string,
+  lockPath: string,
+  options: AcquireOptions,
+): Promise<void> {
+  for (const hook of beforeLockHooks) {
+    await hook(path, lockPath, options);
+  }
+}
+
+export function clearBeforeLockHooks(): void {
+  beforeLockHooks.length = 0;
+}

package/src/hooks/beforeUnlock.ts

@@ -0,0 +1,24 @@
+import type { LockHandle } from '../types/lock.js';
+
+export type BeforeUnlockHook = (handle: LockHandle) => void | Promise<void>;
+
+const beforeUnlockHooks: BeforeUnlockHook[] = [];
+
+export function addBeforeUnlockHook(hook: BeforeUnlockHook): void {
+  beforeUnlockHooks.push(hook);
+}
+
+export function removeBeforeUnlockHook(hook: BeforeUnlockHook): void {
+  const idx = beforeUnlockHooks.indexOf(hook);
+  if (idx !== -1) beforeUnlockHooks.splice(idx, 1);
+}
+
+export async function runBeforeUnlockHooks(handle: LockHandle): Promise<void> {
+  for (const hook of beforeUnlockHooks) {
+    await hook(handle);
+  }
+}
+
+export function clearBeforeUnlockHooks(): void {
+  beforeUnlockHooks.length = 0;
+}

package/src/hooks/index.ts

@@ -0,0 +1,25 @@
+export * from './beforeLock.js';
+export * from './afterLock.js';
+export * from './beforeUnlock.js';
+export * from './afterUnlock.js';
+export * from './onError.js';
+export * from './onStale.js';
+export * from './onTimeout.js';
+
+import { clearBeforeLockHooks } from './beforeLock.js';
+import { clearAfterLockHooks } from './afterLock.js';
+import { clearBeforeUnlockHooks } from './beforeUnlock.js';
+import { clearAfterUnlockHooks } from './afterUnlock.js';
+import { clearOnErrorHooks } from './onError.js';
+import { clearOnStaleHooks } from './onStale.js';
+import { clearOnTimeoutHooks } from './onTimeout.js';
+
+export function clearAllHooks(): void {
+  clearBeforeLockHooks();
+  clearAfterLockHooks();
+  clearBeforeUnlockHooks();
+  clearAfterUnlockHooks();
+  clearOnErrorHooks();
+  clearOnStaleHooks();
+  clearOnTimeoutHooks();
+}

package/src/hooks/onError.ts

@@ -0,0 +1,22 @@
+export type OnErrorHook = (error: Error, path: string, lockPath: string) => void | Promise<void>;
+
+const onErrorHooks: OnErrorHook[] = [];
+
+export function addOnErrorHook(hook: OnErrorHook): void {
+  onErrorHooks.push(hook);
+}
+
+export function removeOnErrorHook(hook: OnErrorHook): void {
+  const idx = onErrorHooks.indexOf(hook);
+  if (idx !== -1) onErrorHooks.splice(idx, 1);
+}
+
+export async function runOnErrorHooks(error: Error, path: string, lockPath: string): Promise<void> {
+  for (const hook of onErrorHooks) {
+    await hook(error, path, lockPath);
+  }
+}
+
+export function clearOnErrorHooks(): void {
+  onErrorHooks.length = 0;
+}

package/src/hooks/onStale.ts

@@ -0,0 +1,24 @@
+import type { LockData } from '../types/lock.js';
+
+export type OnStaleHook = (lockPath: string, data: LockData, ageMs: number) => void | Promise<void>;
+
+const onStaleHooks: OnStaleHook[] = [];
+
+export function addOnStaleHook(hook: OnStaleHook): void {
+  onStaleHooks.push(hook);
+}
+
+export function removeOnStaleHook(hook: OnStaleHook): void {
+  const idx = onStaleHooks.indexOf(hook);
+  if (idx !== -1) onStaleHooks.splice(idx, 1);
+}
+
+export async function runOnStaleHooks(lockPath: string, data: LockData, ageMs: number): Promise<void> {
+  for (const hook of onStaleHooks) {
+    await hook(lockPath, data, ageMs);
+  }
+}
+
+export function clearOnStaleHooks(): void {
+  onStaleHooks.length = 0;
+}

package/src/hooks/onTimeout.ts

@@ -0,0 +1,27 @@
+export type OnTimeoutHook = (path: string, lockPath: string, timeoutMs: number, attempts: number) => void | Promise<void>;
+
+const onTimeoutHooks: OnTimeoutHook[] = [];
+
+export function addOnTimeoutHook(hook: OnTimeoutHook): void {
+  onTimeoutHooks.push(hook);
+}
+
+export function removeOnTimeoutHook(hook: OnTimeoutHook): void {
+  const idx = onTimeoutHooks.indexOf(hook);
+  if (idx !== -1) onTimeoutHooks.splice(idx, 1);
+}
+
+export async function runOnTimeoutHooks(
+  path: string,
+  lockPath: string,
+  timeoutMs: number,
+  attempts: number,
+): Promise<void> {
+  for (const hook of onTimeoutHooks) {
+    await hook(path, lockPath, timeoutMs, attempts);
+  }
+}
+
+export function clearOnTimeoutHooks(): void {
+  onTimeoutHooks.length = 0;
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from './types/index.js';
+export * from './errors/index.js';
+export * from './constants/index.js';
+
+export { acquireLock, isLocked, getLockState, checkLock, listLocks, cleanupLocks } from './core/index.js';
+export type { CleanupResult } from './core/index.js';
+
+export { withLock, withLockResult } from './promise/withLock.js';
+export { lock, tryLock, lockWithTimeout } from './promise/lock.js';
+
+export { lockSync, tryLockSync } from './sync/lock.js';
+export { unlockSync, forceUnlockSync } from './sync/unlock.js';
+export { checkSync, isLockedSync } from './sync/check.js';
+
+export * from './adapters/index.js';
+export * from './strategies/index.js';
+export * from './middleware/index.js';
+export * from './plugins/index.js';
+export * from './events/index.js';
+export * from './hooks/index.js';
+export * from './logger/index.js';
+export * from './config/index.js';
+export * from './meta/index.js';
+export * from './registry/index.js';
+export * from './platform/index.js';

package/src/logger/console.ts

@@ -0,0 +1,39 @@
+import type { Logger, LogLevel } from '../types/logger.js';
+
+const LOG_LEVEL_MAP: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5,
+};
+
+export function createConsoleLogger(level: LogLevel = 'info', prefix = '[atomic-lockfile]'): Logger {
+  let currentLevel = level;
+  const shouldLog = (l: LogLevel): boolean => LOG_LEVEL_MAP[l] <= LOG_LEVEL_MAP[currentLevel];
+
+  const log = (l: LogLevel, message: string, context?: Record<string, unknown>): void => {
+    if (!shouldLog(l)) return;
+    const ts = new Date().toISOString();
+    const line = `${ts} ${prefix} [${l.toUpperCase()}] ${message}`;
+    const output = context ? `${line} ${JSON.stringify(context)}` : line;
+    if (l === 'error') console.error(output);
+    else if (l === 'warn') console.warn(output);
+    else console.log(output);
+  };
+
+  const logger: Logger = {
+    silent: (m, c) => log('silent', m, c),
+    error: (m, c) => log('error', m, c),
+    warn: (m, c) => log('warn', m, c),
+    info: (m, c) => log('info', m, c),
+    debug: (m, c) => log('debug', m, c),
+    trace: (m, c) => log('trace', m, c),
+    child: (ctx) => createConsoleLogger(currentLevel, `${prefix}[${JSON.stringify(ctx)}]`),
+    setLevel: (l) => { currentLevel = l; },
+    getLevel: () => currentLevel,
+  };
+
+  return logger;
+}

package/src/logger/debug.ts

@@ -0,0 +1,29 @@
+import type { Logger, LogLevel } from '../types/logger.js';
+
+const NAMESPACE = 'atomic-lockfile';
+
+export function createDebugLogger(namespace = NAMESPACE): Logger {
+  const isEnabled = (): boolean => {
+    const debug = process.env['DEBUG'] ?? '';
+    return debug === '*' || debug.split(',').some((ns: string) => ns.trim() === namespace || ns.trim() === `${namespace}:*`);
+  };
+
+  const log = (level: LogLevel, message: string, context?: Record<string, unknown>): void => {
+    if (!isEnabled()) return;
+    const prefix = `${namespace}:${level}`;
+    const ts = Date.now();
+    process.stderr.write(`  ${prefix} +${ts} ${message}${context ? ' ' + JSON.stringify(context) : ''}\n`);
+  };
+
+  return {
+    silent: (m, c) => log('silent', m, c),
+    error: (m, c) => log('error', m, c),
+    warn: (m, c) => log('warn', m, c),
+    info: (m, c) => log('info', m, c),
+    debug: (m, c) => log('debug', m, c),
+    trace: (m, c) => log('trace', m, c),
+    child: (ctx) => createDebugLogger(`${namespace}:${Object.values(ctx).join(':')}`),
+    setLevel: () => undefined,
+    getLevel: (): LogLevel => 'debug',
+  };
+}

package/src/logger/index.ts

@@ -0,0 +1,20 @@
+export { noopLogger } from './noop.js';
+export { createConsoleLogger } from './console.js';
+export { createDebugLogger } from './debug.js';
+
+import { noopLogger } from './noop.js';
+import type { Logger } from '../types/logger.js';
+
+let globalLogger: Logger = noopLogger;
+
+export function getLogger(): Logger {
+  return globalLogger;
+}
+
+export function setLogger(logger: Logger): void {
+  globalLogger = logger;
+}
+
+export function resetLogger(): void {
+  globalLogger = noopLogger;
+}