@dbx-tools/falkor-db 0.0.0-stage → 0.9.43

package/src/persistence/manager.ts

@@ -0,0 +1,322 @@
+/**
+ * Restore and change-aware durable backup lifecycle for embedded FalkorDB.
+ *
+ * Redis owns dirty detection and RDB creation. This manager only observes
+ * completed saves, stages immutable copies, and advances durable storage after
+ * a successful upload. Reuse it instead of adding application-local backup
+ * timers, manifest ordering, retry, or retention logic.
+ *
+ * @module
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { asyncUtils, log } from "@dbx-tools/shared-core";
+import {
+  enforceRetention,
+  LATEST_MANIFEST_PATH,
+  nextSnapshotSequence,
+  parseSnapshotManifest,
+  snapshotPath,
+  type SnapshotManifest,
+} from "./manifest.ts";
+import {
+  getPersistenceInfo,
+  waitForBackgroundSave,
+  type RedisPersistenceClient,
+  type RedisPersistenceInfo,
+} from "./redis-info.ts";
+import { stageSnapshot, verifySnapshot } from "./snapshot.ts";
+import type { VolumeStorage } from "./volume.ts";
+
+const logger = log.logger("falkor-db:persistence");
+const DEFAULT_RETRY_DELAYS_MS = [5_000, 15_000, 30_000, 60_000, 300_000] as const;
+
+/** Configuration for {@link FalkorPersistenceManager}. */
+export interface FalkorPersistenceOptions {
+  dataDir: string;
+  storage?: VolumeStorage;
+  pollIntervalMs?: number;
+  retention?: number;
+  retryDelaysMs?: readonly number[];
+  forceBackupOnShutdown?: boolean;
+  shutdownTimeoutMs?: number;
+  staleBackupWarningMs?: number;
+}
+
+/** Observable state for health reporting and metrics adapters. */
+export interface FalkorPersistenceStatus {
+  rdbLastSaveTime?: number;
+  rdbChangesSinceLastSave?: number;
+  backupLastSuccessTime?: string;
+  backupLastSequence?: number;
+  backupSizeBytes?: number;
+  backupDurationMs?: number;
+  backupFailures: number;
+  restoreDurationMs?: number;
+  restoreSnapshotSequence?: number;
+}
+
+/** Coordinates restore, RDB observation, durable upload, retry, and retention. */
+export class FalkorPersistenceManager {
+  private readonly dumpPath: string;
+  private readonly stagingDirectory: string;
+  private readonly statusValue: FalkorPersistenceStatus = { backupFailures: 0 };
+  private manifest: SnapshotManifest | undefined;
+  private redis: RedisPersistenceClient | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private backupPromise: Promise<void> | undefined;
+  private checkAgain = false;
+  private lastUploadedSaveTime = 0;
+  private retryAttempt = 0;
+  private retryAfter = 0;
+  private lastLoggedLocalSaveTime = 0;
+
+  constructor(private readonly options: FalkorPersistenceOptions) {
+    this.dumpPath = join(options.dataDir, "dump.rdb");
+    this.stagingDirectory = join(options.dataDir, ".dbx-tools-backups");
+  }
+
+  get status(): Readonly<FalkorPersistenceStatus> {
+    return { ...this.statusValue };
+  }
+
+  /** Restore `latest.json` before FalkorDB starts, or keep the local database. */
+  async restore(): Promise<SnapshotManifest | undefined> {
+    await mkdir(this.options.dataDir, { recursive: true });
+    if (!this.options.storage) {
+      logger.info("durable storage is not configured; using local RDB persistence", {
+        dataDir: this.options.dataDir,
+      });
+      return undefined;
+    }
+
+    const raw = await this.options.storage.readJson<unknown>(LATEST_MANIFEST_PATH);
+    if (raw === null) {
+      logger.info("no durable FalkorDB snapshot found; using local database", {
+        dataDir: this.options.dataDir,
+      });
+      return undefined;
+    }
+
+    const started = Date.now();
+    const manifest = parseSnapshotManifest(raw);
+    const temporary = `${this.dumpPath}.restore`;
+    await rm(temporary, { force: true });
+    try {
+      await this.options.storage.download(manifest.snapshot, temporary);
+      await verifySnapshot(temporary, manifest.sha256);
+      await rename(temporary, this.dumpPath);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+    this.manifest = manifest;
+    this.lastUploadedSaveTime = manifest.redisSaveTime ?? 0;
+    this.statusValue.restoreDurationMs = Date.now() - started;
+    this.statusValue.restoreSnapshotSequence = manifest.sequence;
+    logger.info("restored FalkorDB snapshot", {
+      sequence: manifest.sequence,
+      size: manifest.size,
+      durationMs: this.statusValue.restoreDurationMs,
+    });
+    return manifest;
+  }
+
+  /** Begin polling Redis persistence metadata for completed new snapshots. */
+  async start(redis: RedisPersistenceClient): Promise<void> {
+    if (this.timer) return;
+    this.redis = redis;
+    const initial = await this.observe(redis);
+    if (this.manifest) {
+      this.lastUploadedSaveTime = initial.rdbLastSaveTime;
+    }
+    await this.checkNow();
+    this.timer = setInterval(() => {
+      void this.checkNow().catch((error) => {
+        logger.error("FalkorDB persistence check failed; retrying later", { error });
+      });
+    }, this.options.pollIntervalMs ?? 10_000);
+    this.timer.unref?.();
+  }
+
+  /** Stop background polling without forcing a save or upload. */
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+
+  /** Inspect persistence now, coalescing concurrent checks into the newest RDB. */
+  async checkNow(): Promise<void> {
+    if (!this.redis) return;
+    if (this.backupPromise) {
+      this.checkAgain = true;
+      return this.backupPromise;
+    }
+    this.backupPromise = this.runChecks();
+    try {
+      await this.backupPromise;
+    } finally {
+      this.backupPromise = undefined;
+    }
+  }
+
+  /** Optionally force one dirty save/upload, bounded so shutdown cannot hang. */
+  async prepareShutdown(): Promise<void> {
+    this.stop();
+    if (!this.options.forceBackupOnShutdown || !this.redis) return;
+    const timeoutMs = this.options.shutdownTimeoutMs ?? 30_000;
+    const work = this.finishShutdownBackup(this.redis);
+    const timeout = new AbortController();
+    try {
+      await Promise.race([
+        work,
+        asyncUtils.sleep(timeoutMs, timeout.signal).then(() => {
+          throw new Error(`FalkorDB shutdown backup exceeded ${timeoutMs}ms`);
+        }),
+      ]);
+    } catch (error) {
+      logger.error("shutdown backup failed; continuing shutdown", { error });
+    } finally {
+      timeout.abort();
+    }
+  }
+
+  private async finishShutdownBackup(redis: RedisPersistenceClient): Promise<void> {
+    if (this.backupPromise) {
+      try {
+        await this.backupPromise;
+      } catch (error) {
+        logger.warn("in-flight FalkorDB backup failed; retrying during shutdown", { error });
+      }
+    }
+    await this.forceDirtySnapshot(redis);
+  }
+
+  private async runChecks(): Promise<void> {
+    do {
+      this.checkAgain = false;
+      await this.inspectAndBackup();
+    } while (this.checkAgain);
+  }
+
+  private async inspectAndBackup(): Promise<void> {
+    const redis = this.redis;
+    if (!redis) return;
+    const info = await this.observe(redis);
+    if (info.rdbBgSaveInProgress) return;
+    if (info.rdbLastBgSaveStatus !== "ok") {
+      logger.error("Redis reported an unsuccessful background save", {
+        status: info.rdbLastBgSaveStatus,
+      });
+      return;
+    }
+    this.warnIfStale(info);
+    if (!this.options.storage) {
+      if (info.rdbLastSaveTime > this.lastLoggedLocalSaveTime) {
+        this.lastLoggedLocalSaveTime = info.rdbLastSaveTime;
+        logger.info("local FalkorDB RDB snapshot completed", {
+          lastSaveTime: info.rdbLastSaveTime,
+          changesSinceSave: info.rdbChangesSinceLastSave,
+          path: this.dumpPath,
+        });
+      }
+      return;
+    }
+    if (info.rdbLastSaveTime <= this.lastUploadedSaveTime || !existsSync(this.dumpPath)) return;
+    if (Date.now() < this.retryAfter) return;
+
+    try {
+      await this.upload(info);
+      this.retryAttempt = 0;
+      this.retryAfter = 0;
+      const newest = await this.observe(redis);
+      if (newest.rdbLastSaveTime > this.lastUploadedSaveTime) this.checkAgain = true;
+    } catch (error) {
+      this.statusValue.backupFailures += 1;
+      const delays = this.options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+      const delay = asyncUtils.boundedRetryDelay(this.retryAttempt++, delays);
+      this.retryAfter = Date.now() + delay;
+      logger.error("durable FalkorDB backup failed; local database remains available", {
+        error,
+        retryInMs: delay,
+      });
+    }
+  }
+
+  private async upload(info: RedisPersistenceInfo): Promise<void> {
+    const storage = this.options.storage;
+    if (!storage) return;
+    const started = Date.now();
+    const sequence = await nextSnapshotSequence(storage, this.manifest);
+    const remote = snapshotPath(sequence);
+    const stagedPath = join(this.stagingDirectory, `snapshot-${sequence}.rdb`);
+    const staged = await stageSnapshot(this.dumpPath, stagedPath);
+    try {
+      await storage.upload(staged.path, remote, { overwrite: false });
+      const manifest: SnapshotManifest = {
+        snapshot: remote,
+        createdAt: new Date().toISOString(),
+        size: staged.size,
+        sha256: staged.sha256,
+        sequence,
+        redisSaveTime: info.rdbLastSaveTime,
+      };
+      await storage.writeJson(LATEST_MANIFEST_PATH, manifest);
+      this.manifest = manifest;
+      this.lastUploadedSaveTime = info.rdbLastSaveTime;
+      this.statusValue.backupLastSuccessTime = manifest.createdAt;
+      this.statusValue.backupLastSequence = sequence;
+      this.statusValue.backupSizeBytes = staged.size;
+      this.statusValue.backupDurationMs = Date.now() - started;
+      logger.info("uploaded durable FalkorDB snapshot", {
+        sequence,
+        size: staged.size,
+        durationMs: this.statusValue.backupDurationMs,
+      });
+      await enforceRetention(storage, manifest, this.options.retention ?? 5).catch((error) => {
+        logger.warn("FalkorDB snapshot retention cleanup failed", { error });
+      });
+    } finally {
+      await rm(stagedPath, { force: true });
+    }
+  }
+
+  private async forceDirtySnapshot(redis: RedisPersistenceClient): Promise<void> {
+    let info = await this.observe(redis);
+    if (info.rdbChangesSinceLastSave > 0) {
+      const previous = info.rdbLastSaveTime;
+      await redis.bgSave();
+      info = await waitForBackgroundSave(redis, previous, {
+        timeoutMs: this.options.shutdownTimeoutMs ?? 30_000,
+      });
+    }
+    if (this.options.storage && info.rdbLastSaveTime > this.lastUploadedSaveTime) {
+      this.retryAfter = 0;
+      await this.upload(info);
+    }
+  }
+
+  private async observe(redis: RedisPersistenceClient): Promise<RedisPersistenceInfo> {
+    const info = await getPersistenceInfo(redis);
+    this.statusValue.rdbLastSaveTime = info.rdbLastSaveTime;
+    this.statusValue.rdbChangesSinceLastSave = info.rdbChangesSinceLastSave;
+    return info;
+  }
+
+  private warnIfStale(info: RedisPersistenceInfo): void {
+    if (!this.options.storage) return;
+    const threshold = this.options.staleBackupWarningMs;
+    if (!threshold || info.rdbChangesSinceLastSave === 0) return;
+    const last = this.statusValue.backupLastSuccessTime
+      ? Date.parse(this.statusValue.backupLastSuccessTime)
+      : 0;
+    if (Date.now() - last > threshold) {
+      logger.warn("FalkorDB has changes without a recent durable backup", {
+        changesSinceSave: info.rdbChangesSinceLastSave,
+        lastSuccessTime: this.statusValue.backupLastSuccessTime,
+      });
+    }
+  }
+}

package/src/persistence/manifest.ts

@@ -0,0 +1,113 @@
+/**
+ * Durable snapshot manifest naming, validation, sequencing, and retention.
+ *
+ * `latest.json` is updated only after its immutable snapshot exists. Reuse this
+ * module for manifest policy so restore and cleanup cannot disagree about the
+ * current good snapshot.
+ *
+ * @module
+ */
+
+import { posix } from "node:path";
+import type { VolumeStorage } from "./volume.ts";
+
+/** Durable pointer updated only after a complete immutable snapshot upload. */
+export const LATEST_MANIFEST_PATH = "latest.json";
+
+/** Directory containing immutable, monotonically sequenced RDB files. */
+export const SNAPSHOT_DIRECTORY = "snapshots";
+
+/** Durable pointer to one verified immutable RDB snapshot. */
+export interface SnapshotManifest {
+  snapshot: string;
+  createdAt: string;
+  size: number;
+  sha256: string;
+  sequence: number;
+  /** Redis `rdb_last_save_time` represented by this snapshot. */
+  redisSaveTime?: number;
+}
+
+/** Parse an untrusted manifest read from durable storage. */
+export function parseSnapshotManifest(value: unknown): SnapshotManifest {
+  if (!isRecord(value)) throw new TypeError("FalkorDB latest.json must be an object");
+  const manifest: SnapshotManifest = {
+    snapshot: requiredString(value.snapshot, "snapshot"),
+    createdAt: requiredString(value.createdAt, "createdAt"),
+    size: nonNegativeInteger(value.size, "size"),
+    sha256: requiredString(value.sha256, "sha256").toLowerCase(),
+    sequence: positiveInteger(value.sequence, "sequence"),
+    ...(value.redisSaveTime === undefined
+      ? {}
+      : { redisSaveTime: nonNegativeInteger(value.redisSaveTime, "redisSaveTime") }),
+  };
+  if (!manifest.snapshot.startsWith(`${SNAPSHOT_DIRECTORY}/`)) {
+    throw new TypeError("FalkorDB manifest snapshot must be under snapshots/");
+  }
+  if (!/^[a-f0-9]{64}$/.test(manifest.sha256)) {
+    throw new TypeError("FalkorDB manifest sha256 must be a 64-character hex digest");
+  }
+  if (!Number.isFinite(Date.parse(manifest.createdAt))) {
+    throw new TypeError("FalkorDB manifest createdAt must be an ISO date");
+  }
+  return manifest;
+}
+
+/** Remote path for an immutable, monotonically sequenced RDB snapshot. */
+export function snapshotPath(sequence: number): string {
+  return posix.join(SNAPSHOT_DIRECTORY, `${String(sequence).padStart(8, "0")}.rdb`);
+}
+
+/** Choose a sequence above both the manifest and any orphaned uploads. */
+export async function nextSnapshotSequence(
+  storage: VolumeStorage,
+  manifest?: SnapshotManifest,
+): Promise<number> {
+  const entries = await storage.list(SNAPSHOT_DIRECTORY);
+  let maximum = manifest?.sequence ?? 0;
+  for (const entry of entries) {
+    const match = /^(\d+)\.rdb$/.exec(entry.name);
+    if (match) maximum = Math.max(maximum, Number.parseInt(match[1]!, 10));
+  }
+  return maximum + 1;
+}
+
+/** Delete old immutable snapshots while preserving the manifest target. */
+export async function enforceRetention(
+  storage: VolumeStorage,
+  manifest: SnapshotManifest,
+  retain: number,
+): Promise<void> {
+  const snapshots = (await storage.list(SNAPSHOT_DIRECTORY))
+    .map((entry) => ({ entry, match: /^(\d+)\.rdb$/.exec(entry.name) }))
+    .filter((item): item is typeof item & { match: RegExpExecArray } => item.match !== null)
+    .map(({ entry, match }) => ({ entry, sequence: Number.parseInt(match[1]!, 10) }))
+    .sort((left, right) => right.sequence - left.sequence);
+  const keep = new Set(snapshots.slice(0, Math.max(1, retain)).map(({ entry }) => entry.path));
+  keep.add(manifest.snapshot);
+  for (const { entry } of snapshots) {
+    if (!keep.has(entry.path)) await storage.delete(entry.path);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a string`);
+  return value;
+}
+
+function nonNegativeInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new TypeError(`${name} must be a non-negative integer`);
+  }
+  return Number(value);
+}
+
+function positiveInteger(value: unknown, name: string): number {
+  const parsed = nonNegativeInteger(value, name);
+  if (parsed < 1) throw new TypeError(`${name} must be positive`);
+  return parsed;
+}

package/src/persistence/redis-info.ts

@@ -0,0 +1,80 @@
+/**
+ * Redis persistence metadata parsing and completed-RDB detection.
+ *
+ * Reuse this module whenever FalkorDB persistence decisions depend on `INFO
+ * persistence`; do not infer snapshot completion from filesystem timestamps
+ * alone or trigger `BGSAVE` merely to discover whether the graph changed.
+ *
+ * @module
+ */
+
+import { asyncUtils } from "@dbx-tools/shared-core";
+
+/** Redis persistence fields required by durable snapshot orchestration. */
+export interface RedisPersistenceInfo {
+  rdbBgSaveInProgress: boolean;
+  rdbLastSaveTime: number;
+  rdbLastBgSaveStatus: string;
+  rdbChangesSinceLastSave: number;
+}
+
+/** Minimal Redis client surface used by the persistence manager. */
+export interface RedisPersistenceClient {
+  info(section: "persistence"): Promise<string>;
+  bgSave(): Promise<unknown>;
+}
+
+/** Parse the fields used by the backup manager from `INFO persistence`. */
+export function parsePersistenceInfo(raw: string): RedisPersistenceInfo {
+  const values = new Map<string, string>();
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line || line.startsWith("#")) continue;
+    const separator = line.indexOf(":");
+    if (separator < 0) continue;
+    values.set(line.slice(0, separator), line.slice(separator + 1));
+  }
+  return {
+    rdbBgSaveInProgress: integer(values, "rdb_bgsave_in_progress") !== 0,
+    rdbLastSaveTime: integer(values, "rdb_last_save_time"),
+    rdbLastBgSaveStatus: values.get("rdb_last_bgsave_status") ?? "unknown",
+    rdbChangesSinceLastSave: integer(values, "rdb_changes_since_last_save"),
+  };
+}
+
+/** Read and parse the current Redis persistence state. */
+export async function getPersistenceInfo(
+  redis: RedisPersistenceClient,
+): Promise<RedisPersistenceInfo> {
+  return parsePersistenceInfo(await redis.info("persistence"));
+}
+
+/** Wait until a requested background save finishes successfully. */
+export async function waitForBackgroundSave(
+  redis: RedisPersistenceClient,
+  previousSaveTime: number,
+  options: { intervalMs?: number; timeoutMs?: number } = {},
+): Promise<RedisPersistenceInfo> {
+  let completed: RedisPersistenceInfo | undefined;
+  for await (const info of asyncUtils.poll(() => getPersistenceInfo(redis), {
+    intervalMs: options.intervalMs ?? 250,
+    timeoutMs: options.timeoutMs ?? 30_000,
+    predicate: (value) => {
+      if (!value.rdbBgSaveInProgress && value.rdbLastBgSaveStatus !== "ok") {
+        throw new Error(`Redis background save failed: ${value.rdbLastBgSaveStatus}`);
+      }
+      completed = value;
+      return value.rdbBgSaveInProgress || value.rdbLastSaveTime <= previousSaveTime;
+    },
+  })) {
+    completed = info;
+  }
+  if (!completed || completed.rdbLastSaveTime <= previousSaveTime) {
+    throw new Error("Redis background save completed without a newer RDB timestamp");
+  }
+  return completed;
+}
+
+function integer(values: ReadonlyMap<string, string>, key: string): number {
+  const value = Number.parseInt(values.get(key) ?? "0", 10);
+  return Number.isFinite(value) ? value : 0;
+}

package/src/persistence/snapshot.ts

@@ -0,0 +1,46 @@
+/**
+ * Immutable local RDB staging, hashing, and restore verification.
+ *
+ * The live `dump.rdb` is always copied before upload so a later Redis rename
+ * cannot change the bytes being transferred. Reuse these helpers instead of
+ * hashing or uploading the live database file directly.
+ *
+ * @module
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { copyFile, mkdir, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** Local immutable snapshot metadata. */
+export interface LocalSnapshot {
+  path: string;
+  size: number;
+  sha256: string;
+}
+
+/** Copy a live RDB into an immutable staging path and hash the copied bytes. */
+export async function stageSnapshot(source: string, destination: string): Promise<LocalSnapshot> {
+  await mkdir(dirname(destination), { recursive: true });
+  await copyFile(source, destination);
+  const [details, sha256] = await Promise.all([stat(destination), sha256File(destination)]);
+  return { path: destination, size: details.size, sha256 };
+}
+
+/** Compute a file's lowercase SHA-256 digest without buffering it in memory. */
+export async function sha256File(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest("hex");
+}
+
+/** Fail when a restored snapshot does not match the durable manifest. */
+export async function verifySnapshot(path: string, expectedSha256: string): Promise<void> {
+  const actual = await sha256File(path);
+  if (actual !== expectedSha256.toLowerCase()) {
+    throw new Error(
+      `FalkorDB snapshot checksum mismatch: expected ${expectedSha256}, got ${actual}`,
+    );
+  }
+}

package/src/persistence/volume.ts

@@ -0,0 +1,84 @@
+/**
+ * Durable snapshot storage abstraction and Databricks Volume adapter.
+ *
+ * Backup policy depends only on {@link VolumeStorage}. The Databricks adapter
+ * receives an initialized {@link DatabricksFileSystem}, keeping profile and
+ * application authentication in `@dbx-tools/databricks` rather than this
+ * package. Other durable stores can implement the same narrow contract.
+ *
+ * @module
+ */
+
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { DatabricksFileSystem } from "@dbx-tools/databricks/databricks-fs";
+
+/** One entry in durable snapshot storage. */
+export interface VolumeEntry {
+  name: string;
+  path: string;
+  size?: number;
+}
+
+/** Storage contract used by restore, upload, manifest, and retention policy. */
+export interface VolumeStorage {
+  exists(path: string): Promise<boolean>;
+  download(remote: string, local: string): Promise<void>;
+  upload(local: string, remote: string, options?: { overwrite?: boolean }): Promise<void>;
+  readJson<T>(path: string): Promise<T | null>;
+  writeJson(path: string, value: unknown): Promise<void>;
+  list(path: string): Promise<VolumeEntry[]>;
+  delete(path: string): Promise<void>;
+}
+
+/** Stream local snapshots to and from a rooted Unity Catalog Volume filesystem. */
+export class DatabricksVolumeStorage implements VolumeStorage {
+  constructor(private readonly fileSystem: DatabricksFileSystem) {}
+
+  async exists(path: string): Promise<boolean> {
+    return this.fileSystem.exists(path);
+  }
+
+  async download(remote: string, local: string): Promise<void> {
+    await mkdir(dirname(local), { recursive: true });
+    const source = await this.fileSystem.readStream(remote);
+    await pipeline(Readable.fromWeb(source), createWriteStream(local));
+  }
+
+  async upload(
+    local: string,
+    remote: string,
+    options: { overwrite?: boolean } = {},
+  ): Promise<void> {
+    const source = Readable.toWeb(createReadStream(local)) as globalThis.ReadableStream<Uint8Array>;
+    await this.fileSystem.writeStream(remote, source, options);
+  }
+
+  async readJson<T>(path: string): Promise<T | null> {
+    if (!(await this.fileSystem.exists(path))) return null;
+    const text = await this.fileSystem.readFile(path, { encoding: "utf-8" });
+    return JSON.parse(text) as T;
+  }
+
+  async writeJson(path: string, value: unknown): Promise<void> {
+    await this.fileSystem.writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+      overwrite: true,
+    });
+  }
+
+  async list(path: string): Promise<VolumeEntry[]> {
+    if (!(await this.fileSystem.exists(path))) return [];
+    return (await this.fileSystem.readdir(path)).map((entry) => ({
+      name: entry.name,
+      path: `${path.replace(/\/$/, "")}/${entry.name}`,
+      size: entry.size,
+    }));
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.fileSystem.deleteFile(path, { force: true });
+  }
+}