Query Builder

Contents

Overview

sequenceDiagram
    participant Caller
    participant writeJsonAtomic
    participant FileSystem
    participant Lock

    Caller->>Lock: withLock(fn)
    Lock-->>Caller: lock acquired
    Caller->>writeJsonAtomic: writeJsonAtomic(path, data)
    writeJsonAtomic->>FileSystem: create temp file (UUID name)
    FileSystem-->>writeJsonAtomic: fd opened
    writeJsonAtomic->>FileSystem: write JSON + fsync
    FileSystem-->>writeJsonAtomic: bytes flushed
    writeJsonAtomic->>FileSystem: rename temp → target
    FileSystem-->>writeJsonAtomic: rename complete
    writeJsonAtomic-->>Caller: success
    Caller->>Lock: release lock

The sequence diagram above shows the atomic write flow. A UUID-named temp file is created in the same directory as the target, data is written and flushed with fsync, then a single rename() call atomically replaces the target. If any step fails, the temp file is cleaned up and the original target remains untouched.

Decision Points

How It Works

The query builder layer is split across six files, each responsible for a specific I/O pattern. All share the same principle: never expose a partially-written or unvalidated artifact to callers.

Simple JSON I/O (json-file.ts)

The simplest layer provides loadJsonFile and saveJsonFile for single-file reads and writes. saveJsonFile always sets mode 0o600 (owner-only read/write) to prevent accidental exposure of sensitive data.

async function loadJsonFile(
  pathname: string
): Promise<unknown | undefined> {
  try {
    const raw = await fs.readFile(pathname, "utf-8");
    return JSON.parse(raw);
  } catch {
    return undefined;
  }
}

async function saveJsonFile(
  pathname: string,
  data: unknown
): Promise<void> {
  const json = JSON.stringify(data, null, 2);
  await fs.writeFile(pathname, json, { mode: 0o600 });
}

Atomic JSON/Text I/O (json-files.ts)

The atomic layer introduces writeJsonAtomic and writeTextAtomic, which follow the write-to-temp–fsync–rename pattern. A UUID-based temp filename prevents collisions when multiple processes target the same file.

import { randomUUID } from "node:crypto";

async function writeJsonAtomic(
  filePath: string,
  value: unknown,
  options?: { mode?: number }
): Promise<void> {
  const dir = path.dirname(filePath);
  const tmpPath = path.join(dir, `.tmp-${randomUUID()}.json`);
  const fd = await fs.open(tmpPath, "w", options?.mode ?? 0o600);
  try {
    const json = JSON.stringify(value, null, 2);
    await fd.writeFile(json);
    await fd.sync();
    await fd.close();
    await fs.rename(tmpPath, filePath);
  } catch (err) {
    await fd.close().catch(() => {});
    await fs.unlink(tmpPath).catch(() => {});
    throw err;
  }
}

async function writeTextAtomic(
  filePath: string,
  text: string,
  options?: { mode?: number }
): Promise<void> {
  const dir = path.dirname(filePath);
  const tmpPath = path.join(dir, `.tmp-${randomUUID()}.txt`);
  const fd = await fs.open(tmpPath, "w", options?.mode ?? 0o600);
  try {
    await fd.writeFile(text);
    await fd.sync();
    await fd.close();
    await fs.rename(tmpPath, filePath);
  } catch (err) {
    await fd.close().catch(() => {});
    await fs.unlink(tmpPath).catch(() => {});
    throw err;
  }
}

function createAsyncLock(): {
  withLock: <T>(fn: () => Promise<T>) => Promise<T>;
} {
  let chain = Promise.resolve();
  return {
    withLock<T>(fn: () => Promise<T>): Promise<T> {
      const next = chain.then(fn);
      chain = next.then(() => {}, () => {});
      return next;
    },
  };
}

Safe File Access (fs-safe.ts)

The safe file access layer validates every path against a workspace root before opening a file descriptor. It rejects symlinks, paths that escape the root, and files that exceed size limits.

Safe Open Validation Chain

flowchart TD
    A["openFileWithinRoot(root, filePath)"] --> B{"Path contains null bytes or is empty?"}
    B -- Yes --> C["Return: invalid-path"]
    B -- No --> D["Resolve to absolute path"]
    D --> E{"Resolved path starts with root?"}
    E -- No --> F["Return: outside-workspace"]
    E -- Yes --> G["lstat the path"]
    G --> H{"Path exists?"}
    H -- No --> I["Return: not-found"]
    H -- Yes --> J{"Is symlink?"}
    J -- Yes --> K["Return: symlink"]
    J -- No --> L{"Is regular file?"}
    L -- No --> M["Return: not-file"]
    L -- Yes --> N["Open with O_RDONLY | O_NOFOLLOW"]
    N --> O["fstat the fd"]
    O --> P{"realpath matches resolved?"}
    P -- No --> Q["Close fd, return: path-mismatch"]
    P -- Yes --> R{"File size within limit?"}
    R -- No --> S["Close fd, return: too-large"]
    R -- Yes --> T["Return: SafeOpenResult"]

The validation chain above runs on every openFileWithinRoot() call. Seven distinct error codes cover every failure mode, from null-byte injection to TOCTOU race conditions (the fstat + realpath double-check after open). The O_NOFOLLOW flag prevents the kernel from silently following symlinks.

Annotated Code Walkthrough

Walk through the safe file open and atomic write paths step by step.

type SafeOpenErrorCode =
  | "invalid-path"
  | "not-found"
  | "outside-workspace"
  | "symlink"
  | "not-file"
  | "path-mismatch"
  | "too-large";

interface SafeOpenResult {
  handle: FileHandle;
  realPath: string;
  stat: Stats;
}

type SafeOpenOutcome =
  | { ok: true; result: SafeOpenResult }
  | { ok: false; code: SafeOpenErrorCode };

import { constants } from "node:fs";

async function openFileWithinRoot(
  rootPath: string,
  filePath: string,
  options?: { maxBytes?: number }
): Promise<SafeOpenOutcome> {
  if (!filePath || filePath.includes("\0")) {
    return { ok: false, code: "invalid-path" };
  }
  const resolved = path.resolve(rootPath, filePath);
  if (!resolved.startsWith(rootPath + path.sep) &&
      resolved !== rootPath) {
    return { ok: false, code: "outside-workspace" };
  }
  let lstatResult: Stats;
  try {
    lstatResult = await fs.lstat(resolved);
  } catch {
    return { ok: false, code: "not-found" };
  }
  if (lstatResult.isSymbolicLink()) {
    return { ok: false, code: "symlink" };
  }
  if (!lstatResult.isFile()) {
    return { ok: false, code: "not-file" };
  }
  const fd = await fs.open(
    resolved,
    constants.O_RDONLY | constants.O_NOFOLLOW
  );
  const realResolved = await fs.realpath(resolved);
  if (realResolved !== resolved) {
    await fd.close();
    return { ok: false, code: "path-mismatch" };
  }
  const fdStat = await fd.stat();
  if (options?.maxBytes && fdStat.size > options.maxBytes) {
    await fd.close();
    return { ok: false, code: "too-large" };
  }
  return {
    ok: true,
    result: { handle: fd, realPath: realResolved, stat: fdStat },
  };
}

async function enqueueDelivery(
  queueDir: string,
  payload: QueuedDeliveryPayload
): Promise<QueuedDelivery> {
  const delivery: QueuedDelivery = {
    ...payload,
    id: randomUUID(),
    enqueuedAt: Date.now(),
    retryCount: 0,
  };
  const filePath = path.join(queueDir, `${delivery.id}.json`);
  await writeJsonAtomic(filePath, delivery);
  return delivery;
}

async function ackDelivery(
  queueDir: string,
  id: string
): Promise<void> {
  const filePath = path.join(queueDir, `${id}.json`);
  await fs.unlink(filePath);
}

async function failDelivery(
  queueDir: string,
  id: string,
  error: string
): Promise<void> {
  const filePath = path.join(queueDir, `${id}.json`);
  const raw = await loadJsonFile(filePath);
  if (!raw) return;
  const delivery = raw as QueuedDelivery;
  delivery.retryCount += 1;
  delivery.lastAttemptAt = Date.now();
  delivery.lastError = error;
  const deliveredPath = path.join(
    queueDir, `${id}.delivered`
  );
  await writeJsonAtomic(filePath, delivery);
}

let sqliteModule: typeof import("node:sqlite") | null = null;

async function requireNodeSqlite(): Promise<
  typeof import("node:sqlite")
> {
  if (sqliteModule) return sqliteModule;
  try {
    sqliteModule = await import("node:sqlite");
    return sqliteModule;
  } catch {
    throw new Error(
      "node:sqlite is not available in this runtime. " +
      "Ensure you are running Node.js 22.5+ with " +
      "--experimental-sqlite enabled."
    );
  }
}

Edge Cases & Error Handling

Configuration

Related Topics

See also:

• store overview — the parent sub-module page
• Data Models — the type definitions that these I/O functions read and write
• State Migrations — uses atomic writes for safe file moves during migration

Directory Map

src/infra/store/
├── json-file.ts               ← loadJsonFile(), saveJsonFile() (simple I/O)
├── json-files.ts              ← readJsonFile(), writeJsonAtomic(), writeTextAtomic(), createAsyncLock()
├── node-sqlite.ts             ← requireNodeSqlite() dynamic import
├── fs-safe.ts                 ← SafeOpenErrorCode, openFileWithinRoot(), readFileWithinRoot()
├── file-lock.ts               ← File locking primitives for cross-process coordination
├── archive.ts                 ← ZIP/TAR extraction with ArchiveExtractLimits
└── delivery-queue.ts          ← enqueueDelivery(), ackDelivery(), failDelivery()