Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.6 KB
Raw Blame
/** Stable OS locks for cooperating writers on one owner host. No TTL takeover. */
import { mkdir } from 'node:fs/promises';
import { mkdirSync } from 'node:fs';
import { dirname, isAbsolute } from 'node:path';
import { setTimeout as delay } from 'node:timers/promises';
import { constants as osConstants } from 'node:os';
import { familySync, GLIBC, MUSL } from 'detect-libc';

export interface NativeExportPublisher {
  beginExport(absoluteDestination: string): object;
  publishExportFile(handle: object, relativePath: string, data: Buffer): void;
  /** Publishes a staged regular file (absolute path, leaf links refused) copied in bounded reads, never held whole. */
  publishExportFileFrom(handle: object, relativePath: string, absoluteSource: string): void;
  completeExport(handle: object): void;
  closeExport(handle: object): void;
}

interface NativeBinding extends NativeExportPublisher {
  target: string;
  openLock(path: string): object;
  tryLock(handle: object): boolean;
  close(handle: object): void;
  openIpcMutex?(name: string): object;
  removeWindowsUnixSocket?(handle: object, path: string): boolean;
}

export class NativeLockUnavailableError extends Error {
  readonly code = 'writer_lock_unavailable';
  /** #6305: 'open' when this process could not create or open the lock file itself (its directory or the file), as opposed to an addon, close or IPC failure. */
  readonly stage?: 'open';
  /** #6305: the OS error behind the failure (`EACCES`, `EISDIR`, `os_error_5`), when the cause names one. */
  readonly osError?: string;
  constructor(message = 'Native writer locking is unavailable on this host', cause?: unknown, stage?: 'open') {
    const osError = nativeLockOsError(cause);
    super(osError ? `${message} (${osError})` : message, { cause });
    this.name = 'NativeLockUnavailableError';
    if (stage) this.stage = stage;
    if (osError) this.osError = osError;
  }
}

/** #6305: this process could not create or open the lock file; a busy lock returns null instead. */
/** #6305: the OS error of the last lock-open failure per worktree, so the consumer's release line names it (the request's blocked_reason cannot). */
const openFailures = new Map<string, string>();
export function noteLockOpenFailure(worktreeId: string, error: unknown): void {
  const os = error instanceof NativeLockUnavailableError ? error.osError : undefined;
  if (os) openFailures.set(worktreeId, os); else openFailures.delete(worktreeId);
}
export function lockOpenOsError(worktreeId: string | null | undefined): string | null { return worktreeId ? openFailures.get(worktreeId) ?? null : null; }
export function isLockOpenFailure(error: unknown): error is NativeLockUnavailableError {
  return error instanceof NativeLockUnavailableError && error.stage === 'open';
}

/** A node:fs error code, or the native addon's `(OS error N)` as its errno name (`os_error_N` when the platform has no name). */
export function nativeLockOsError(cause: unknown): string | undefined {
  const code = (cause as { code?: unknown } | null)?.code;
  if (typeof code === 'string' && /^E[A-Z0-9]+$/.test(code)) return code;
  const match = /\(OS error (\d+)\)/.exec(cause instanceof Error ? cause.message : '');
  if (!match || match[1] === '0') return undefined;
  const errno = Number(match[1]);
  if (process.platform === 'win32') return `os_error_${errno}`;
  return Object.entries(osConstants.errno).find(([, value]) => value === errno)?.[0] ?? `os_error_${errno}`;
}

export interface NativeLockHandle {
  /** True after release. A released handle must not authorize further work. */
  readonly released: boolean;
  /** Idempotent. Closing the OS handle releases its lock without unlinking. */
  release(): Promise<void>;
}

/** #6530: a lock taken by {@link acquireNativeLockSync}; release is synchronous and idempotent. */
export interface NativeLockSyncHandle {
  readonly released: boolean;
  release(): void;
}

export interface NativeLockOptions {
  /** A zero budget tries once. Defaults to five seconds. */
  timeoutMs?: number;
  /** Delay between nonblocking attempts; defaults to 25 ms. */
  pollMs?: number;
  signal?: AbortSignal;
}

let bindingPromise: Promise<NativeBinding> | undefined;
let bindingLoaded: NativeBinding | undefined;
const windowsSocketRemovers = new WeakMap<NativeLockHandle, (path: string) => boolean>();

async function loadBinding(): Promise<NativeBinding> {
  return loadBindingSync();
}

function loadBindingSync(): NativeBinding {
  if (bindingLoaded) return bindingLoaded;
  const arch = process.arch;
  if (arch !== 'x64' && arch !== 'arm64') throw new NativeLockUnavailableError(`Native writer locking does not support ${process.platform}/${arch}`);
  let binding: NativeBinding;
  let target: string;
  try {
    if (process.platform === 'linux') {
      const libc = familySync();
      if (libc !== GLIBC && libc !== MUSL) throw new NativeLockUnavailableError('Cannot identify the Linux C runtime for writer locking');
      target = `linux-${arch}-${libc}`;
      // Literal requires are intentional: Bun embeds each .node asset in its
      // compiled executables. Dynamic prebuild discovery does not embed them.
      if (libc === GLIBC) binding = arch === 'x64'
        ? require('../../../native/locks/prebuilds/linux-x64-glibc.node')
        : require('../../../native/locks/prebuilds/linux-arm64-glibc.node');
      else binding = arch === 'x64'
        ? require('../../../native/locks/prebuilds/linux-x64-musl.node')
        : require('../../../native/locks/prebuilds/linux-arm64-musl.node');
    } else if (process.platform === 'darwin') {
      target = `darwin-${arch}`;
      binding = arch === 'x64'
        ? require('../../../native/locks/prebuilds/darwin-x64.node')
        : require('../../../native/locks/prebuilds/darwin-arm64.node');
    } else if (process.platform === 'win32') {
      target = `win32-${arch}`;
      binding = arch === 'x64'
        ? require('../../../native/locks/prebuilds/win32-x64.node')
        : require('../../../native/locks/prebuilds/win32-arm64.node');
    } else throw new NativeLockUnavailableError(`Native writer locking does not support ${process.platform}/${arch}`);
    if (binding.target !== target || typeof binding.openLock !== 'function' || typeof binding.tryLock !== 'function' || typeof binding.close !== 'function') {
      throw new NativeLockUnavailableError('Installed native writer lock addon has the wrong target or ABI');
    }
    if (process.platform === 'win32' && (typeof binding.openIpcMutex !== 'function' || typeof binding.removeWindowsUnixSocket !== 'function')) {
      throw new NativeLockUnavailableError('Installed native writer lock addon lacks Windows IPC support');
    }
    bindingLoaded = binding;
    return binding;
  } catch (cause) {
    if (cause instanceof NativeLockUnavailableError) throw cause;
    throw new NativeLockUnavailableError('Cannot load the native writer lock addon; reinstall this GBrain version', cause);
  }
}

/** Lazy so a nonowner Postgres server can still accept writes and serve reads. */
export async function nativeLockCapability(): Promise<{ target: string; napi: 3 }> {
  const binding = await (bindingPromise ??= loadBinding());
  return { target: binding.target, napi: 3 };
}

export async function nativeExportPublisher(): Promise<NativeExportPublisher> {
  const binding = await (bindingPromise ??= loadBinding());
  if (typeof binding.beginExport !== 'function' || typeof binding.publishExportFile !== 'function' || typeof binding.publishExportFileFrom !== 'function' ||
      typeof binding.completeExport !== 'function' || typeof binding.closeExport !== 'function') {
    throw new NativeLockUnavailableError('Installed native addon lacks safe export publication support');
  }
  return binding;
}

function budget(value: number | undefined, fallback: number, minimum: number): number {
  const result = value ?? fallback;
  if (!Number.isFinite(result) || result < minimum || result > 2 ** 31 - 1) throw new RangeError(`Native lock duration must be between ${minimum} and ${2 ** 31 - 1} milliseconds`);
  return result;
}

/** The caller supplies a stable absolute path outside the mutable worktree. */
export async function acquireNativeLock(path: string, options: NativeLockOptions = {}): Promise<NativeLockHandle | null> {
  if (!isAbsolute(path) || path.includes('\0')) throw new TypeError('Native lock path must be absolute and contain no NUL');
  const timeoutMs = budget(options.timeoutMs, 5000, 0);
  const pollMs = budget(options.pollMs, 25, 1);
  const { signal } = options;
  signal?.throwIfAborted();
  const binding = await (bindingPromise ??= loadBinding());
  let handle: object;
  try {
    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
    signal?.throwIfAborted();
    handle = binding.openLock(path);
  } catch (cause) {
    if (signal?.aborted) throw signal.reason;
    throw new NativeLockUnavailableError('Cannot open the stable writer lock file', cause, 'open');
  }
  let released = false;
  const release = async () => {
    if (released) return;
    released = true;
    try { binding.close(handle); }
    catch (cause) { throw new NativeLockUnavailableError('Cannot close the writer lock handle; this host must stop publishing', cause); }
  };
  const deadline = performance.now() + timeoutMs;
  try {
    for (;;) {
      signal?.throwIfAborted();
      let acquired: boolean;
      try { acquired = binding.tryLock(handle); }
      catch (cause) { throw new NativeLockUnavailableError('The OS could not acquire the writer lock', cause); }
      if (acquired) {
        const guard = { get released() { return released; }, release };
        if (process.platform === 'win32') windowsSocketRemovers.set(guard, socketPath => {
          if (path !== `${socketPath}.bind.lock`) throw new NativeLockUnavailableError('The retained claim belongs to another IPC path');
          return binding.removeWindowsUnixSocket!(handle, socketPath);
        });
        return guard;
      }
      const remaining = deadline - performance.now();
      if (remaining <= 0) { await release(); return null; }
      await delay(Math.min(pollMs, remaining), undefined, { signal });
    }
  } catch (error) {
    await release();
    throw error;
  }
}

/**
 * #6530: the same OS lock for synchronous callers (git write paths that run
 * inside sync code). Blocks the thread between attempts, so callers pass a
 * short budget.
 */
export function acquireNativeLockSync(path: string, options: { timeoutMs?: number; pollMs?: number } = {}): NativeLockSyncHandle | null {
  if (!isAbsolute(path) || path.includes('\0')) throw new TypeError('Native lock path must be absolute and contain no NUL');
  const timeoutMs = budget(options.timeoutMs, 5000, 0);
  const pollMs = budget(options.pollMs, 25, 1);
  const binding = loadBindingSync();
  let handle: object;
  try {
    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
    handle = binding.openLock(path);
  } catch (cause) {
    throw new NativeLockUnavailableError('Cannot open the stable writer lock file', cause, 'open');
  }
  let released = false;
  const releaseSync = () => {
    if (released) return;
    released = true;
    try { binding.close(handle); }
    catch (cause) { throw new NativeLockUnavailableError('Cannot close the writer lock handle; this host must stop publishing', cause); }
  };
  const sleeper = new Int32Array(new SharedArrayBuffer(4));
  const deadline = performance.now() + timeoutMs;
  try {
    for (;;) {
      let acquired: boolean;
      try { acquired = binding.tryLock(handle); }
      catch (cause) { throw new NativeLockUnavailableError('The OS could not acquire the writer lock', cause); }
      if (acquired) return { get released() { return released; }, release: releaseSync };
      const remaining = deadline - performance.now();
      if (remaining <= 0) { releaseSync(); return null; }
      Atomics.wait(sleeper, 0, 0, Math.min(pollMs, remaining));
    }
  } catch (error) {
    releaseSync();
    throw error;
  }
}

export function tryAcquireNativeLock(path: string): Promise<NativeLockHandle | null> {
  return acquireNativeLock(path, { timeoutMs: 0 });
}

/** Named pipes share one kernel identity across homes and Windows sessions. */
export async function tryAcquireNativeIpcMutex(name: string): Promise<NativeLockHandle | null> {
  if (process.platform !== 'win32' || !/^[\\/]{2}[.?][\\/]pipe[\\/][^\\/]/i.test(name) || name.includes('\0')) throw new TypeError('Expected a Windows named-pipe address');
  const binding = await (bindingPromise ??= loadBinding());
  let handle: object;
  try { handle = binding.openIpcMutex!(name); }
  catch (cause) { throw new NativeLockUnavailableError('Cannot open the Windows IPC binding claim', cause); }
  let released = false;
  const release = async () => {
    if (released) return;
    try { binding.close(handle); }
    catch (cause) { throw new NativeLockUnavailableError('Cannot close the Windows IPC binding claim; this host must stop publishing', cause); }
    released = true;
  };
  try {
    if (binding.tryLock(handle)) return { get released() { return released; }, release };
    await release();
    return null;
  } catch (cause) {
    await release();
    throw new NativeLockUnavailableError('Cannot acquire the Windows IPC binding claim', cause);
  }
}

/** The native side requires the same still-held opaque file-lock handle. */
export function removeNativeWindowsUnixSocket(path: string, claim: NativeLockHandle): boolean {
  const remove = windowsSocketRemovers.get(claim);
  if (process.platform !== 'win32' || claim.released || !remove || !isAbsolute(path) || path.includes('\0')) {
    throw new NativeLockUnavailableError('Cannot remove an IPC socket without its retained binding claim');
  }
  try { return remove(path); }
  catch (cause) { throw new NativeLockUnavailableError('Cannot verify and remove the stale Windows IPC socket', cause); }
}