Skip to content
Python
13.7 KB
Raw Blame
import { AsyncLocalStorage } from "node:async_hooks";
import { randomUUID } from "node:crypto";
import { constants, type Stats } from "node:fs";
import * as fs from "node:fs/promises";
import path from "node:path";
import {
  type BackgroundOperationLedger,
  type BackgroundOperationSnapshot,
  type BackgroundOwner,
  validateBackgroundOwner,
  validateBackgroundSnapshot,
  validateBackgroundTransition,
} from "./background-operation.js";

const MAX_BYTES = 256 * 1024;
const READ = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
const CREATE =
  constants.O_WRONLY |
  constants.O_CREAT |
  constants.O_EXCL |
  constants.O_NOFOLLOW;
type Identity = { dev: number; ino: number };
type Binding = BackgroundOwner & {
  schemaVersion: 1;
  dataDev: number;
  dataIno: number;
};
type Lease = {
  active: boolean;
  poisoned: boolean;
  tail: Promise<void>;
  identity: Identity;
  nonce: string;
};

/** One stable data-instance owner; this module never performs service actions.
 * Lock directories are persistent fences, not age/PID-based takeover candidates.
 */
export class PersistentBackgroundOperationLedger
  implements BackgroundOperationLedger
{
  readonly durability = "persistent" as const;
  private readonly context = new AsyncLocalStorage<Lease>();
  private readonly directory: string;
  private constructor(
    private readonly dataDir: string,
    private readonly binding: Binding,
    private readonly rootIdentity: Identity,
    private readonly directoryIdentity: Identity,
  ) {
    this.directory = path.join(dataDir, "background-operations");
  }

  static async initialize(
    dataDir: string,
    owner: BackgroundOwner,
  ): Promise<PersistentBackgroundOperationLedger> {
    const checked = checkedOwner(owner);
    const root = await checkedRoot(dataDir);
    const directory = path.join(dataDir, "background-operations");
    await fs.mkdir(directory, { mode: 0o700 });
    const info = await fs.lstat(directory);
    privateDirectory(info);
    const binding: Binding = {
      schemaVersion: 1,
      ...checked,
      dataDev: root.dev,
      dataIno: root.ino,
    };
    const ledger = new PersistentBackgroundOperationLedger(
      dataDir,
      binding,
      root,
      info,
    );
    await ledger.checkDirectories();
    await writeNew(path.join(directory, "owner.json"), JSON.stringify(binding));
    await syncDirectory(directory, info);
    await syncDirectory(dataDir, root);
    await ledger.check();
    return ledger;
  }

  static async open(
    dataDir: string,
    owner: BackgroundOwner,
  ): Promise<PersistentBackgroundOperationLedger> {
    const checked = checkedOwner(owner);
    const root = await checkedRoot(dataDir);
    const directory = path.join(dataDir, "background-operations");
    const info = await fs.lstat(directory);
    privateDirectory(info);
    const { value } = await readJson(path.join(directory, "owner.json"), 2048);
    const expected: Binding = {
      schemaVersion: 1,
      ...checked,
      dataDev: root.dev,
      dataIno: root.ino,
    };
    if (canonical(value) !== canonical(expected)) fail("owner_mismatch");
    const ledger = new PersistentBackgroundOperationLedger(
      dataDir,
      expected,
      root,
      info,
    );
    await ledger.check();
    return ledger;
  }

  async exclusive<T>(
    owner: BackgroundOwner,
    run: () => Promise<T>,
  ): Promise<T> {
    this.matchOwner(owner);
    await this.check();
    const lock = path.join(this.directory, "execution.lock");
    try {
      await fs.mkdir(lock, { mode: 0o700 });
    } catch (error) {
      if (hasCode(error, "EEXIST")) fail("recovery_required");
      throw error;
    }
    const identity = await fs.lstat(lock);
    privateDirectory(identity);
    const lease: Lease = {
      active: true,
      poisoned: false,
      tail: Promise.resolve(),
      identity,
      nonce: randomUUID(),
    };
    // Failed acquisition stays fenced; do not clean an unverified/partially durable lock.
    await writeNew(
      path.join(lock, "owner.json"),
      JSON.stringify(this.lockOwner(lease)),
    );
    await syncDirectory(lock, identity);
    await syncDirectory(this.directory, this.directoryIdentity);
    await this.checkLease(lease);
    try {
      return await this.context.run(lease, run);
    } finally {
      lease.active = false;
      await lease.tail;
      if (lease.poisoned) fail("recovery_required");
      await this.checkLease(lease);
      await fs.unlink(path.join(lock, "owner.json"));
      await fs.rmdir(lock);
      await syncDirectory(this.directory, this.directoryIdentity);
    }
  }

  async load(
    owner: BackgroundOwner,
  ): Promise<BackgroundOperationSnapshot | null> {
    this.matchOwner(owner);
    return (await this.readState())?.snapshot ?? null;
  }

  async commit(
    owner: BackgroundOwner,
    expectedRevision: number | null,
    next: BackgroundOperationSnapshot,
  ): Promise<void> {
    this.matchOwner(owner);
    const value = validateBackgroundSnapshot(next, this.owner());
    if (
      expectedRevision !== null &&
      (!Number.isSafeInteger(expectedRevision) ||
        expectedRevision < 1 ||
        expectedRevision >= Number.MAX_SAFE_INTEGER)
    )
      fail("revision_conflict");
    if (value.revision !== (expectedRevision ?? 0) + 1)
      fail("revision_conflict");
    const lease = this.context.getStore();
    if (!lease?.active || lease.poisoned) fail("lock_required");
    const operation = lease.tail.then(() =>
      this.publish(lease, expectedRevision, value),
    );
    lease.tail = operation.then(
      () => {},
      () => {},
    );
    return operation;
  }

  private async readState(): Promise<{
    snapshot: BackgroundOperationSnapshot;
    identity: Stats;
  } | null> {
    await this.check();
    let entry: Awaited<ReturnType<typeof readJson>>;
    try {
      entry = await readJson(
        path.join(this.directory, "state.json"),
        MAX_BYTES,
      );
    } catch (error) {
      await this.check();
      if (hasCode(error, "ENOENT")) return null;
      throw error;
    }
    const snapshot = validateBackgroundSnapshot(entry.value, this.owner());
    await this.check();
    return { snapshot, identity: entry.identity };
  }

  private async publish(
    lease: Lease,
    expected: number | null,
    next: BackgroundOperationSnapshot,
  ): Promise<void> {
    if (lease.poisoned) fail("recovery_required");
    await this.checkLease(lease);
    const current = await this.readState();
    if ((current?.snapshot.revision ?? null) !== expected)
      fail("revision_conflict");
    validateBackgroundTransition(current?.snapshot ?? null, next, this.owner());
    const target = path.join(this.directory, "state.json");
    const temporary = path.join(this.directory, `.pending-${randomUUID()}`);
    let identity: Identity | null = null;
    let published = false;
    try {
      identity = await writeNew(temporary, JSON.stringify(next));
      await this.checkLease(lease);
      if (current) {
        const latest = await readJson(target, MAX_BYTES);
        if (
          !sameFile(latest.identity, current.identity) ||
          canonical(latest.value) !== canonical(current.snapshot)
        )
          fail("revision_conflict");
        await fs.rename(temporary, target);
      } else {
        await fs.link(temporary, target);
        published = true;
        await fs.unlink(temporary);
      }
      published = true;
      await syncDirectory(this.directory, this.directoryIdentity);
      await this.checkLease(lease);
      const stored = await readJson(target, MAX_BYTES);
      if (
        !same(identity, stored.identity) ||
        canonical(stored.value) !== canonical(next)
      )
        fail("publication_changed");
    } catch (error) {
      if (published) lease.poisoned = true;
      throw error;
    } finally {
      if (identity) {
        await this.checkDirectories();
        const remaining = await fs.lstat(temporary).catch((error) => {
          if (hasCode(error, "ENOENT")) return null;
          throw error;
        });
        if (remaining) {
          if (!same(remaining, identity)) fail("recovery_required");
          privateFile(remaining);
          await fs.unlink(temporary);
        }
      }
    }
  }

  private owner(): BackgroundOwner {
    return { userId: this.binding.userId, runtimeId: this.binding.runtimeId };
  }
  private lockOwner(lease: Lease) {
    return { ...this.owner(), pid: process.pid, nonce: lease.nonce };
  }
  private matchOwner(owner: BackgroundOwner) {
    const checked = checkedOwner(owner);
    if (
      checked.userId !== this.binding.userId ||
      checked.runtimeId !== this.binding.runtimeId
    )
      fail("owner_mismatch");
  }
  private async checkDirectories(): Promise<void> {
    const root = await checkedRoot(this.dataDir);
    const directory = await fs.lstat(this.directory);
    privateDirectory(directory);
    if (
      !same(root, this.rootIdentity) ||
      !same(directory, this.directoryIdentity)
    )
      fail("directory_changed");
  }
  private async check(): Promise<void> {
    await this.checkDirectories();
    const { value } = await readJson(
      path.join(this.directory, "owner.json"),
      2048,
    );
    if (canonical(value) !== canonical(this.binding)) fail("owner_mismatch");
    await this.checkDirectories();
  }
  private async checkLease(lease: Lease): Promise<void> {
    await this.check();
    const lock = path.join(this.directory, "execution.lock");
    const info = await fs.lstat(lock);
    privateDirectory(info);
    if (!same(info, lease.identity)) fail("recovery_required");
    const { value } = await readJson(path.join(lock, "owner.json"), 2048);
    if (canonical(value) !== canonical(this.lockOwner(lease)))
      fail("recovery_required");
  }
}

function checkedOwner(owner: BackgroundOwner): BackgroundOwner {
  validateBackgroundOwner(owner);
  return { userId: owner.userId, runtimeId: owner.runtimeId };
}
async function checkedRoot(dataDir: string): Promise<Stats> {
  if (process.platform === "win32" || typeof process.getuid !== "function")
    fail("platform_unsupported");
  if (
    !path.isAbsolute(dataDir) ||
    path.resolve(dataDir) !== dataDir ||
    (await fs.realpath(dataDir)) !== dataDir
  )
    fail("directory_unsafe");
  const info = await fs.lstat(dataDir);
  privateDirectory(info);
  return info;
}
function privateDirectory(info: Stats) {
  if (
    !info.isDirectory() ||
    info.isSymbolicLink() ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o7777) !== 0o700
  )
    fail("directory_unsafe");
}
function privateFile(info: Stats) {
  if (
    !info.isFile() ||
    info.isSymbolicLink() ||
    info.nlink !== 1 ||
    info.uid !== process.getuid?.() ||
    (info.mode & 0o7777) !== 0o600
  )
    fail("file_unsafe");
}
function same(a: Identity, b: Identity) {
  return a.dev === b.dev && a.ino === b.ino;
}
function sameFile(a: Stats, b: Stats) {
  return (
    same(a, b) &&
    a.mode === b.mode &&
    a.uid === b.uid &&
    a.gid === b.gid &&
    a.nlink === b.nlink &&
    a.size === b.size &&
    a.mtimeMs === b.mtimeMs &&
    a.ctimeMs === b.ctimeMs
  );
}
async function readJson(
  file: string,
  maximum: number,
): Promise<{ value: unknown; identity: Stats }> {
  const handle = await fs.open(file, READ);
  try {
    const before = await handle.stat();
    privateFile(before);
    if (before.size > maximum) fail("size_exceeded");
    const buffer = Buffer.alloc(maximum + 1);
    let length = 0;
    while (length < buffer.length) {
      const { bytesRead } = await handle.read({
        buffer,
        offset: length,
        length: buffer.length - length,
        position: length,
      });
      if (!bytesRead) break;
      length += bytesRead;
    }
    const after = await handle.stat();
    privateFile(after);
    const named = await fs.lstat(file);
    privateFile(named);
    if (
      length > maximum ||
      length !== after.size ||
      !sameFile(before, after) ||
      !sameFile(after, named)
    )
      fail("file_changed");
    let value: unknown;
    try {
      value = JSON.parse(
        new TextDecoder("utf-8", { fatal: true }).decode(
          buffer.subarray(0, length),
        ),
      );
    } catch {
      return fail("invalid_json");
    }
    return { value, identity: after };
  } finally {
    await handle.close();
  }
}
async function writeNew(file: string, text: string): Promise<Identity> {
  if (Buffer.byteLength(text) > MAX_BYTES) fail("size_exceeded");
  const handle = await fs.open(file, CREATE, 0o600);
  try {
    await handle.writeFile(text, "utf8");
    await handle.sync();
    const info = await handle.stat();
    privateFile(info);
    if (!sameFile(info, await fs.lstat(file))) fail("file_changed");
    return info;
  } finally {
    await handle.close();
  }
}
async function syncDirectory(
  directory: string,
  expected: Identity,
): Promise<void> {
  const handle = await fs.open(
    directory,
    constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
  );
  try {
    const info = await handle.stat();
    privateDirectory(info);
    if (!same(info, expected)) fail("directory_changed");
    await handle.sync();
    const named = await fs.lstat(directory);
    privateDirectory(named);
    if (!same(info, named)) fail("directory_changed");
  } finally {
    await handle.close();
  }
}
function canonical(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
  if (value && typeof value === "object")
    return `{${Object.keys(value)
      .sort()
      .map(
        (key) =>
          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
      )
      .join(",")}}`;
  return JSON.stringify(value);
}
function hasCode(error: unknown, code: string) {
  return (
    !!error &&
    typeof error === "object" &&
    "code" in error &&
    error.code === code
  );
}
function fail(code: string): never {
  throw new Error(`background_operation_ledger_${code}`);
}