atomic-lockfile 0.0.1-security → 1.4.2

package/src/logger/noop.ts

@@ -0,0 +1,13 @@
+import type { Logger, LogLevel } from '../types/logger.js';
+
+export const noopLogger: Logger = {
+  silent: () => undefined,
+  error: () => undefined,
+  warn: () => undefined,
+  info: () => undefined,
+  debug: () => undefined,
+  trace: () => undefined,
+  child: () => noopLogger,
+  setLevel: () => undefined,
+  getLevel: (): LogLevel => 'silent',
+};

package/src/meta/index.ts

@@ -0,0 +1,2 @@
+export * from './version.js';
+export * from './package.js';

package/src/meta/package.ts

@@ -0,0 +1,29 @@
+export const PACKAGE_NAME = 'atomic-lockfile';
+export const PACKAGE_DESCRIPTION = 'Atomic file-based locking with retry, TTL, heartbeat, PID tracking, stale detection, and multi-strategy support';
+export const PACKAGE_HOMEPAGE = 'https://github.com/atomic-lockfile/atomic-lockfile';
+export const PACKAGE_LICENSE = 'MIT';
+export const PACKAGE_AUTHOR = 'atomic-lockfile contributors';
+
+export const PACKAGE_CAPABILITIES = [
+  'atomic-write',
+  'ttl',
+  'heartbeat',
+  'pid-tracking',
+  'stale-detection',
+  'retry',
+  'backoff',
+  'multi-strategy',
+  'multi-adapter',
+  'events',
+  'hooks',
+  'middleware',
+  'plugins',
+  'cli',
+  'sync-api',
+  'async-api',
+  'esm',
+  'cjs',
+  'typescript',
+] as const;
+
+export type PackageCapability = (typeof PACKAGE_CAPABILITIES)[number];

package/src/meta/version.ts

@@ -0,0 +1,26 @@
+export const VERSION = '1.0.0';
+export const VERSION_MAJOR = 1;
+export const VERSION_MINOR = 0;
+export const VERSION_PATCH = 0;
+export const VERSION_PRERELEASE: string | null = null;
+export const VERSION_BUILD: string | null = null;
+
+export function parseVersion(versionStr: string): { major: number; minor: number; patch: number } {
+  const [major = 0, minor = 0, patch = 0] = versionStr.split('.').map(Number);
+  return { major, minor, patch };
+}
+
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (pa.major !== pb.major) return pa.major > pb.major ? 1 : -1;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor ? 1 : -1;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch ? 1 : -1;
+  return 0;
+}
+
+export function isCompatibleVersion(required: string, current = VERSION): boolean {
+  const r = parseVersion(required);
+  const c = parseVersion(current);
+  return c.major === r.major && (c.minor > r.minor || (c.minor === r.minor && c.patch >= r.patch));
+}

package/src/middleware/index.ts

@@ -0,0 +1,18 @@
+export { withLoggingMiddleware } from './logging.js';
+export { createMetricsCollector } from './metrics.js';
+export type { LockMetrics } from './metrics.js';
+export { withTimeoutMiddleware, createTimeoutSignal } from './timeout.js';
+export { withRetryMiddleware, withNoRetryMiddleware, withInfiniteRetryMiddleware } from './retry.js';
+
+import type { AcquireOptions } from '../types/options.js';
+
+export type Middleware = (options: AcquireOptions) => AcquireOptions;
+
+export function composeMiddleware(...middlewares: Middleware[]): Middleware {
+  return (options: AcquireOptions) =>
+    middlewares.reduceRight((opts, mw) => mw(opts), options);
+}
+
+export function applyMiddleware(options: AcquireOptions, ...middlewares: Middleware[]): AcquireOptions {
+  return composeMiddleware(...middlewares)(options);
+}

package/src/middleware/logging.ts

@@ -0,0 +1,21 @@
+import type { AcquireOptions } from '../types/options.js';
+import { getLogger } from '../logger/index.js';
+
+export function withLoggingMiddleware(options: AcquireOptions): AcquireOptions {
+  const logger = getLogger();
+  return {
+    ...options,
+    onAcquired: (lockPath) => {
+      logger.info('Lock acquired', { lockPath });
+      options.onAcquired?.(lockPath);
+    },
+    onRetry: (attempt, error) => {
+      logger.warn('Retrying lock acquisition', { attempt, error: error.message });
+      options.onRetry?.(attempt, error);
+    },
+    onStale: (lockPath) => {
+      logger.warn('Stale lock detected', { lockPath });
+      options.onStale?.(lockPath);
+    },
+  };
+}

package/src/middleware/metrics.ts

@@ -0,0 +1,44 @@
+import type { AcquireOptions } from '../types/options.js';
+
+export interface LockMetrics {
+  acquisitions: number;
+  failures: number;
+  retries: number;
+  totalAcquisitionMs: number;
+  staleDetections: number;
+}
+
+export function createMetricsCollector(): { metrics: LockMetrics; middleware: (opts: AcquireOptions) => AcquireOptions } {
+  const metrics: LockMetrics = {
+    acquisitions: 0,
+    failures: 0,
+    retries: 0,
+    totalAcquisitionMs: 0,
+    staleDetections: 0,
+  };
+
+  const startTimes = new Map<string, number>();
+
+  const middleware = (options: AcquireOptions): AcquireOptions => ({
+    ...options,
+    onAcquired: (lockPath) => {
+      metrics.acquisitions++;
+      const start = startTimes.get(lockPath);
+      if (start !== undefined) {
+        metrics.totalAcquisitionMs += Date.now() - start;
+        startTimes.delete(lockPath);
+      }
+      options.onAcquired?.(lockPath);
+    },
+    onRetry: (attempt, error) => {
+      metrics.retries++;
+      options.onRetry?.(attempt, error);
+    },
+    onStale: (lockPath) => {
+      metrics.staleDetections++;
+      options.onStale?.(lockPath);
+    },
+  });
+
+  return { metrics, middleware };
+}

package/src/middleware/retry.ts

@@ -0,0 +1,25 @@
+import type { AcquireOptions } from '../types/options.js';
+import { DEFAULT_RETRIES, DEFAULT_RETRY_DELAY, DEFAULT_RETRY_MAX_DELAY } from '../constants/defaults.js';
+
+export function withRetryMiddleware(options: AcquireOptions): AcquireOptions {
+  return {
+    retries: DEFAULT_RETRIES,
+    retryDelay: DEFAULT_RETRY_DELAY,
+    retryBackoff: 'exponential',
+    retryMaxDelay: DEFAULT_RETRY_MAX_DELAY,
+    ...options,
+  };
+}
+
+export function withNoRetryMiddleware(options: AcquireOptions): AcquireOptions {
+  return { ...options, retries: 0 };
+}
+
+export function withInfiniteRetryMiddleware(options: AcquireOptions, maxDelayMs = DEFAULT_RETRY_MAX_DELAY): AcquireOptions {
+  return {
+    ...options,
+    retries: Infinity,
+    retryBackoff: 'exponential',
+    retryMaxDelay: maxDelayMs,
+  };
+}

package/src/middleware/timeout.ts

@@ -0,0 +1,34 @@
+import type { AcquireOptions } from '../types/options.js';
+import { DEFAULT_TIMEOUT } from '../constants/defaults.js';
+
+export function withTimeoutMiddleware(
+  options: AcquireOptions,
+  defaultTimeoutMs = DEFAULT_TIMEOUT,
+): AcquireOptions {
+  if (options.timeout !== undefined) return options;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), defaultTimeoutMs);
+
+  const existingSignal = options.signal;
+  if (existingSignal) {
+    existingSignal.addEventListener('abort', () => {
+      clearTimeout(timer);
+      controller.abort();
+    });
+  }
+
+  return {
+    ...options,
+    timeout: defaultTimeoutMs,
+    signal: controller.signal,
+  };
+}
+
+export function createTimeoutSignal(ms: number): { signal: AbortSignal; cancel: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  return {
+    signal: controller.signal,
+    cancel: () => clearTimeout(timer),
+  };
+}

package/src/platform/darwin.ts

@@ -0,0 +1,19 @@
+import { isMacOS } from '../utils/platform.js';
+
+export function assertDarwin(): void {
+  if (!isMacOS()) throw new Error('This operation is only supported on macOS');
+}
+
+export function getDarwinTempDir(): string {
+  return process.env['TMPDIR'] ?? '/tmp';
+}
+
+export function isSandboxed(): boolean {
+  return !!process.env['APP_SANDBOX_CONTAINER_ID'];
+}
+
+export function getContainerTempDir(): string | null {
+  return process.env['APP_SANDBOX_CONTAINER_ID']
+    ? `${process.env['HOME']}/tmp`
+    : null;
+}

package/src/platform/index.ts

@@ -0,0 +1,6 @@
+export * from './unix.js';
+export * from './windows.js';
+export * from './darwin.js';
+export * from './linux.js';
+
+export { getPlatform, isWindows, isMacOS, isLinux, isUnix } from '../utils/platform.js';

package/src/platform/linux.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { isLinux } from '../utils/platform.js';
+
+export function assertLinux(): void {
+  if (!isLinux()) throw new Error('This operation is only supported on Linux');
+}
+
+export function getLinuxTempDir(): string {
+  return process.env['XDG_RUNTIME_DIR'] ?? '/tmp';
+}
+
+export function isContainerEnvironment(): boolean {
+  try {
+    return readFileSync('/proc/1/cgroup', 'utf-8').includes('docker')
+      || !!process.env['KUBERNETES_SERVICE_HOST'];
+  } catch {
+    return !!process.env['KUBERNETES_SERVICE_HOST'];
+  }
+}
+
+export function getLinuxKernelVersion(): string | null {
+  try {
+    return execSync('uname -r', { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function supportsInotify(): boolean {
+  return isLinux();
+}

package/src/platform/unix.ts

@@ -0,0 +1,36 @@
+import { isUnix } from '../utils/platform.js';
+
+export function assertUnix(): void {
+  if (!isUnix()) throw new Error('This operation is only supported on Unix-like systems');
+}
+
+export function getUnixFilePermissions(mode: number): string {
+  const octal = (mode & 0o777).toString(8).padStart(3, '0');
+  return octal;
+}
+
+export function canUseFlock(): boolean {
+  return isUnix();
+}
+
+export function canUseHardLinks(): boolean {
+  return isUnix();
+}
+
+export function getUnixUid(): number {
+  if (typeof process.getuid !== 'function') throw new Error('getuid not available');
+  return process.getuid();
+}
+
+export function getUnixGid(): number {
+  if (typeof process.getgid !== 'function') throw new Error('getgid not available');
+  return process.getgid();
+}
+
+export function isRootUser(): boolean {
+  try {
+    return getUnixUid() === 0;
+  } catch {
+    return false;
+  }
+}

package/src/platform/windows.ts

@@ -0,0 +1,26 @@
+import { isWindows } from '../utils/platform.js';
+
+export function assertWindows(): void {
+  if (!isWindows()) throw new Error('This operation is only supported on Windows');
+}
+
+export function getWindowsTempDir(): string {
+  return process.env['TEMP'] ?? process.env['TMP'] ?? 'C:\\Temp';
+}
+
+export function normalizeWindowsPath(filePath: string): string {
+  return filePath.replace(/\//g, '\\');
+}
+
+export function isUNCPath(filePath: string): boolean {
+  return filePath.startsWith('\\\\');
+}
+
+export function getWindowsDrive(filePath: string): string | null {
+  const match = /^([A-Za-z]):/.exec(filePath);
+  return match ? (match[1] ?? null) : null;
+}
+
+export function canUseWindowsNamedMutex(): boolean {
+  return isWindows();
+}

package/src/plugins/cleanup.ts

@@ -0,0 +1,45 @@
+import { promises as fsp } from 'node:fs';
+import { unlinkSafe } from '../utils/fs.js';
+import { CLEANUP_SIGNALS } from '../constants/signals.js';
+import type { CleanupSignal } from '../constants/signals.js';
+
+const registeredCleanup = new Set<string>();
+
+export function registerCleanupHandler(lockPath: string, onCleanup: (lockPath: string) => void): () => void {
+  registeredCleanup.add(lockPath);
+
+  const handler = (): void => {
+    if (registeredCleanup.has(lockPath)) {
+      onCleanup(lockPath);
+      registeredCleanup.delete(lockPath);
+    }
+  };
+
+  const signals: CleanupSignal[] = [...CLEANUP_SIGNALS];
+  signals.forEach((sig) => process.once(sig, handler));
+  process.once('exit', handler);
+
+  return () => {
+    signals.forEach((sig) => process.removeListener(sig, handler));
+    process.removeListener('exit', handler);
+    registeredCleanup.delete(lockPath);
+  };
+}
+
+export async function cleanupStaleLocks(directory: string, extension = '.lock'): Promise<string[]> {
+  const removed: string[] = [];
+  try {
+    const files = await fsp.readdir(directory);
+    for (const file of files) {
+      if (file.endsWith(extension)) {
+        await unlinkSafe(`${directory}/${file}`);
+        removed.push(file);
+      }
+    }
+  } catch { /* ignore */ }
+  return removed;
+}
+
+export function getRegisteredLocks(): string[] {
+  return [...registeredCleanup];
+}

package/src/plugins/heartbeat.ts

@@ -0,0 +1,42 @@
+import { promises as fsp } from 'node:fs';
+import type { LockData } from '../types/lock.js';
+import { serializeLockData } from '../utils/serialize.js';
+import { INTERVAL_HEARTBEAT } from '../constants/timeouts.js';
+
+export interface HeartbeatHandle {
+  stop(): void;
+  readonly running: boolean;
+}
+
+export function startHeartbeat(
+  lockPath: string,
+  getData: () => LockData,
+  intervalMs = INTERVAL_HEARTBEAT,
+  onError?: (err: Error) => void,
+): HeartbeatHandle {
+  let running = true;
+
+  const beat = async (): Promise<void> => {
+    if (!running) return;
+    try {
+      const data = getData();
+      const updated: LockData = { ...data, updated: Date.now() };
+      await fsp.writeFile(lockPath, serializeLockData(updated), 'utf-8');
+    } catch (err) {
+      onError?.(err as Error);
+    }
+    if (running) setTimeout(beat, intervalMs);
+  };
+
+  const timer = setTimeout(beat, intervalMs);
+
+  return {
+    stop() {
+      running = false;
+      clearTimeout(timer);
+    },
+    get running() {
+      return running;
+    },
+  };
+}

package/src/plugins/index.ts

@@ -0,0 +1,7 @@
+export { checkStale, shouldRemoveStale } from './stale.js';
+export type { StaleCheckResult } from './stale.js';
+export { startHeartbeat } from './heartbeat.js';
+export type { HeartbeatHandle } from './heartbeat.js';
+export { writePidFile, readPidFile, removePidFile, buildPidFilePath } from './pid.js';
+export { getTtlRemaining, isLockExpiredByTtl, buildTtlExpiry, ttlToHuman, validateTtl } from './ttl.js';
+export { registerCleanupHandler, cleanupStaleLocks, getRegisteredLocks } from './cleanup.js';

package/src/plugins/pid.ts

@@ -0,0 +1,26 @@
+import { promises as fsp } from 'node:fs';
+import { getCurrentPid } from '../utils/pid.js';
+
+export async function writePidFile(pidFilePath: string): Promise<void> {
+  await fsp.writeFile(pidFilePath, String(getCurrentPid()), 'utf-8');
+}
+
+export async function readPidFile(pidFilePath: string): Promise<number | null> {
+  try {
+    const content = await fsp.readFile(pidFilePath, 'utf-8');
+    const pid = parseInt(content.trim(), 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export async function removePidFile(pidFilePath: string): Promise<void> {
+  try {
+    await fsp.unlink(pidFilePath);
+  } catch { /* ignore */ }
+}
+
+export function buildPidFilePath(lockPath: string): string {
+  return `${lockPath}.pid`;
+}

package/src/plugins/stale.ts

@@ -0,0 +1,33 @@
+import type { LockData } from '../types/lock.js';
+import { isStale } from '../utils/time.js';
+import { isOrphanedPid } from '../utils/pid.js';
+import { isSameHost } from '../utils/hostname.js';
+import { DEFAULT_STALE_AGE } from '../constants/defaults.js';
+
+export interface StaleCheckResult {
+  isStale: boolean;
+  reason: 'age' | 'orphan' | 'expired' | null;
+  ageMs: number;
+}
+
+export function checkStale(data: LockData, staleAgeMs = DEFAULT_STALE_AGE): StaleCheckResult {
+  const ageMs = Date.now() - data.updated;
+
+  if (data.expires !== null && Date.now() > data.expires) {
+    return { isStale: true, reason: 'expired', ageMs };
+  }
+
+  if (isStale(data.updated, staleAgeMs)) {
+    return { isStale: true, reason: 'age', ageMs };
+  }
+
+  if (isSameHost(data.hostname) && isOrphanedPid(data.pid)) {
+    return { isStale: true, reason: 'orphan', ageMs };
+  }
+
+  return { isStale: false, reason: null, ageMs };
+}
+
+export function shouldRemoveStale(result: StaleCheckResult, removeStale: boolean): boolean {
+  return result.isStale && removeStale;
+}

package/src/plugins/ttl.ts

@@ -0,0 +1,27 @@
+import type { LockData } from '../types/lock.js';
+import { remainingTtlMs, isExpired } from '../utils/time.js';
+
+export function getTtlRemaining(data: LockData): number | null {
+  if (data.ttl === null) return null;
+  return remainingTtlMs(data.created, data.ttl);
+}
+
+export function isLockExpiredByTtl(data: LockData): boolean {
+  if (data.ttl === null) return false;
+  return isExpired(data.created, data.ttl);
+}
+
+export function buildTtlExpiry(ttlMs: number): number {
+  return Date.now() + ttlMs;
+}
+
+export function ttlToHuman(ttlMs: number): string {
+  if (ttlMs < 1000) return `${ttlMs}ms`;
+  if (ttlMs < 60_000) return `${(ttlMs / 1000).toFixed(1)}s`;
+  return `${(ttlMs / 60_000).toFixed(1)}m`;
+}
+
+export function validateTtl(ttlMs: number): void {
+  if (ttlMs <= 0) throw new RangeError(`TTL must be > 0, got ${ttlMs}`);
+  if (!Number.isFinite(ttlMs)) throw new RangeError(`TTL must be finite, got ${ttlMs}`);
+}

package/src/promise/index.ts

@@ -0,0 +1,2 @@
+export { lock, tryLock, lockWithTimeout } from './lock.js';
+export { withLock, withLockResult } from './withLock.js';

package/src/promise/lock.ts

@@ -0,0 +1,23 @@
+import type { AcquireOptions } from '../types/options.js';
+import type { LockHandle } from '../types/lock.js';
+import { acquireLock } from '../core/acquire.js';
+
+export function lock(path: string, options?: AcquireOptions): Promise<LockHandle> {
+  return acquireLock(path, options);
+}
+
+export function tryLock(path: string, options?: AcquireOptions): Promise<LockHandle | null> {
+  return acquireLock(path, { ...options, retries: 0 }).catch(() => null);
+}
+
+export function lockWithTimeout(
+  path: string,
+  timeoutMs: number,
+  options?: AcquireOptions,
+): Promise<LockHandle> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return acquireLock(path, { ...options, signal: controller.signal, timeout: timeoutMs }).finally(
+    () => clearTimeout(timer),
+  );
+}

package/src/promise/withLock.ts

@@ -0,0 +1,30 @@
+import type { WithLockOptions } from '../types/options.js';
+import { acquireLock } from '../core/acquire.js';
+
+export async function withLock<T>(
+  path: string,
+  fn: () => T | Promise<T>,
+  options: WithLockOptions = {},
+): Promise<T> {
+  const handle = await acquireLock(path, options);
+  try {
+    return await fn();
+  } finally {
+    await handle.release();
+  }
+}
+
+export async function withLockResult<T>(
+  path: string,
+  fn: () => T | Promise<T>,
+  options: WithLockOptions = {},
+): Promise<{ result: T; heldMs: number }> {
+  const start = Date.now();
+  const handle = await acquireLock(path, options);
+  try {
+    const result = await fn();
+    return { result, heldMs: Date.now() - start };
+  } finally {
+    await handle.release();
+  }
+}

package/src/registry/global.ts

@@ -0,0 +1,39 @@
+import type { LockStateSnapshot } from '../types/state.js';
+
+class GlobalLockRegistry {
+  private readonly locks = new Map<string, LockStateSnapshot>();
+
+  register(snapshot: LockStateSnapshot): void {
+    this.locks.set(snapshot.lockPath, snapshot);
+  }
+
+  unregister(lockPath: string): void {
+    this.locks.delete(lockPath);
+  }
+
+  get(lockPath: string): LockStateSnapshot | undefined {
+    return this.locks.get(lockPath);
+  }
+
+  has(lockPath: string): boolean {
+    return this.locks.has(lockPath);
+  }
+
+  getAll(): LockStateSnapshot[] {
+    return [...this.locks.values()];
+  }
+
+  getActive(): LockStateSnapshot[] {
+    return this.getAll().filter((s) => s.state === 'locked');
+  }
+
+  clear(): void {
+    this.locks.clear();
+  }
+
+  size(): number {
+    return this.locks.size;
+  }
+}
+
+export const globalRegistry = new GlobalLockRegistry();

package/src/registry/index.ts

@@ -0,0 +1,11 @@
+export { globalRegistry } from './global.js';
+export {
+  registerHandle,
+  unregisterHandle,
+  getHandle,
+  hasHandle,
+  getAllHandles,
+  getActiveHandles,
+  releaseAllHandles,
+  clearRegistry,
+} from './local.js';