Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
12.8 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Readable } from "node:stream";
import { BlobNotFoundError, BlobStore, BlobWriteCleanupError, ReadOnlyStoreError } from "./blobStore";
import { PathError, normalizeResourceId, resolveBlobKeyPath, resolveBlobPath } from "./paths";

const RID = "0123456789abcdef0123456789abcdef";
const UUID = "01234567-89ab-cdef-0123-456789abcdef";
const GENERATION = "11111111-1111-4111-8111-111111111111";
const SECOND_GENERATION = "22222222-2222-4222-8222-222222222222";

async function collect(stream: Readable): Promise<Buffer> {
  const chunks: Buffer[] = [];
  for await (const chunk of stream) chunks.push(chunk as Buffer);
  return Buffer.concat(chunks);
}

describe("path safety", () => {
  it("normalizes a UUID to its 32-hex key and accepts the bare rid", () => {
    expect(normalizeResourceId(UUID)).toBe(RID);
    expect(normalizeResourceId(RID)).toBe(RID);
    expect(normalizeResourceId(UUID.toUpperCase())).toBe(RID);
  });

  it("REJECTS traversal, NUL, backslash, absolute, separators, empty, non-string", () => {
    const bad: unknown[] = [
      "..",
      "../../etc/passwd",
      "a/../b",
      "0123456789abcdef0123456789abcde/", // trailing separator
      "0123456789abcdef0123456789abcde\\evil",
      "/etc/passwd",
      "0123456789abcdef0123456789abcdef\0",
      "g123456789abcdef0123456789abcdef", // non-hex char
      "",
      123,
      null,
      undefined,
    ];
    for (const value of bad) {
      expect(() => normalizeResourceId(value)).toThrow(PathError);
    }
  });

  it("resolveBlobPath keeps the blob directly under the prefix", () => {
    const full = resolveBlobPath("/data/gfs", UUID);
    expect(full).toBe(`/data/gfs/${RID}`);
  });

  it("resolves immutable generations without permitting extra path components", () => {
    expect(resolveBlobKeyPath("/data/gfs", `${RID}/${GENERATION}`)).toBe(
      `/data/gfs/.generations/${RID}/${GENERATION}`
    );
  });
});

describe("BlobStore", () => {
  let dir: string;

  beforeEach(() => {
    dir = mkdtempSync(join(tmpdir(), "gfs-blob-"));
  });

  afterEach(() => {
    rmSync(dir, { recursive: true, force: true });
  });

  it("writes, independently verifies, and reads an immutable generation", async () => {
    const store = new BlobStore(dir, "writer");
    const written = await store.writeImmutable(RID, GENERATION, Buffer.from("hello gfs"));
    expect(written.bytes).toBe(9);
    expect(written.contentSha256).toMatch(/^[0-9a-f]{64}$/);
    await store.verify(written.blobKey, written.bytes, written.contentSha256);
    const bytes = await collect(await store.read(RID, written.blobKey));
    expect(bytes.toString()).toBe("hello gfs");
  });

  it("accepts a streamed write and reports the committed size", async () => {
    const store = new BlobStore(dir, "writer");
    const written = await store.writeImmutable(
      RID,
      GENERATION,
      Readable.from([Buffer.from("ab"), Buffer.from("cde")])
    );
    expect(written.bytes).toBe(5);
    expect((await collect(await store.read(RID, written.blobKey))).toString()).toBe("abcde");
  });

  it("delete removes the blob; reading after delete is not_found", async () => {
    const store = new BlobStore(dir, "writer");
    writeFileSync(join(dir, RID), "x");
    await store.delete(RID);
    await expect(store.read(RID)).rejects.toBeInstanceOf(BlobNotFoundError);
  });

  it("reading an absent blob throws not_found (fail-loud, no empty default)", async () => {
    const store = new BlobStore(dir, "writer");
    await expect(store.read(RID)).rejects.toBeInstanceOf(BlobNotFoundError);
  });

  it("rejects a directory target as non-regular", async () => {
    mkdirSync(join(dir, RID));
    const store = new BlobStore(dir, "reader");
    await expect(store.read(RID)).rejects.toBeInstanceOf(PathError);
    rmSync(join(dir, RID), { recursive: true });
  });

  it("a reader replica may NOT write or delete (RO enforcement)", async () => {
    const reader = new BlobStore(dir, "reader");
    await expect(reader.writeImmutable(RID, GENERATION, Buffer.from("x"))).rejects.toBeInstanceOf(
      ReadOnlyStoreError
    );
    await expect(reader.delete(RID)).rejects.toBeInstanceOf(ReadOnlyStoreError);
  });

  it("rejects an invalid resourceId before touching the filesystem", async () => {
    const store = new BlobStore(dir, "writer");
    await expect(store.writeImmutable("../escape", GENERATION, Buffer.from("x"))).rejects.toBeInstanceOf(
      PathError
    );
    await expect(store.read("/etc/passwd")).rejects.toBeInstanceOf(PathError);
  });

  it("refuses to read through a symlink planted at the blob path", async () => {
    const secret = join(dir, "secret.txt");
    writeFileSync(secret, "top secret");
    symlinkSync(secret, join(dir, RID));
    const store = new BlobStore(dir, "reader");
    await expect(store.read(RID)).rejects.toBeInstanceOf(PathError);
  });

  it("refuses a symlinked resource parent without reading or deleting external bytes", async () => {
    const outside = mkdtempSync(join(tmpdir(), "gfs-outside-"));
    try {
      const outsideBlob = join(outside, GENERATION);
      writeFileSync(outsideBlob, "must survive");
      mkdirSync(join(dir, ".generations"));
      symlinkSync(outside, join(dir, ".generations", RID));
      const key = `${RID}/${GENERATION}`;
      await expect(
        new BlobStore(dir, "writer").writeImmutable(RID, GENERATION, Buffer.from("blocked"))
      ).rejects.toBeInstanceOf(PathError);
      await expect(new BlobStore(dir, "reader").read(RID, key)).rejects.toBeInstanceOf(PathError);
      await expect(new BlobStore(dir, "writer").deleteByKey(key)).rejects.toBeInstanceOf(PathError);
      expect(existsSync(outsideBlob)).toBe(true);
    } finally {
      rmSync(outside, { recursive: true, force: true });
    }
  });

  it("never overwrites an existing generation", async () => {
    const store = new BlobStore(dir, "writer");
    const first = await store.writeImmutable(RID, GENERATION, Buffer.from("first"));
    await expect(store.writeImmutable(RID, GENERATION, Buffer.from("second"))).rejects.toMatchObject({
      code: "EEXIST",
    });
    expect((await collect(await store.read(RID, first.blobKey))).toString()).toBe("first");
  });

  it("never removes a preexisting generation when exclusive open fails before ownership", async () => {
    const parent = join(dir, ".generations", RID);
    const path = join(parent, GENERATION);
    mkdirSync(parent, { recursive: true });
    writeFileSync(path, "committed bytes");
    const injectedFault = Object.assign(new Error("exclusive open failed"), { code: "EIO" });
    const store = new BlobStore(
      dir,
      "writer",
      undefined,
      undefined,
      async () => {
        throw injectedFault;
      }
    );

    await expect(store.writeImmutable(RID, GENERATION, Buffer.from("replacement"))).rejects.toBe(
      injectedFault
    );
    expect(readFileSync(path, "utf8")).toBe("committed bytes");
  });

  it("removes a generation created by this request when a later write step fails", async () => {
    const path = join(dir, ".generations", RID, GENERATION);
    const synced: string[] = [];
    const store = new BlobStore(dir, "writer", async syncPath => {
      synced.push(syncPath);
      if (syncPath === path) throw new Error("blob fsync failed");
    });

    await expect(store.writeImmutable(RID, GENERATION, Buffer.from("uncommitted"))).rejects.toThrow(
      "blob fsync failed"
    );
    expect(existsSync(path)).toBe(false);
    expect(existsSync(join(dir, ".generations"))).toBe(false);
    expect(synced.slice(-3)).toEqual([
      join(dir, ".generations", RID), join(dir, ".generations"), dir,
    ]);
  });

  it("reports incomplete exact cleanup without touching a sibling generation", async () => {
    const sibling = await new BlobStore(dir, "writer").writeImmutable(
      RID, SECOND_GENERATION, Buffer.from("sibling")
    );
    const path = join(dir, ".generations", RID, GENERATION);
    const cleanupFault = new Error("unlink failed");
    const store = new BlobStore(
      dir, "writer", syncPath => syncPath === path ? Promise.reject(new Error("fsync failed")) : Promise.resolve(),
      undefined, undefined, async candidate => {
        expect(candidate).toBe(path);
        throw cleanupFault;
      }
    );

    const failure = await store.writeImmutable(RID, GENERATION, Buffer.from("candidate")).catch(err => err);
    expect(failure).toBeInstanceOf(BlobWriteCleanupError);
    expect(failure.cleanupErrors).toContain(cleanupFault);
    expect(existsSync(path)).toBe(true);
    expect((await collect(await store.read(RID, sibling.blobKey))).toString()).toBe("sibling");
  });

  it("durably syncs file, generation directory, then storage prefix before returning", async () => {
    const synced: string[] = [];
    const store = new BlobStore(dir, "writer", async path => void synced.push(path));
    await store.writeImmutable(RID, GENERATION, Buffer.from("durable"));
    expect(synced).toEqual([
      join(dir, ".generations", RID, GENERATION),
      join(dir, ".generations", RID),
      join(dir, ".generations"),
      dir,
    ]);
  });

  it("durably syncs the resource directory and prefix before cleanup may drop its manifest", async () => {
    const synced: string[] = [];
    const store = new BlobStore(dir, "writer", async path => void synced.push(path));
    const written = await store.writeImmutable(RID, GENERATION, Buffer.from("candidate"));
    synced.length = 0;
    await store.deleteByKey(written.blobKey);
    expect(synced).toEqual([
      join(dir, ".generations", RID),
      join(dir, ".generations"),
      dir,
    ]);
    expect(existsSync(join(dir, ".generations", RID))).toBe(false);
  });

  it("durably confirms cleanup and removes an empty generation directory when bytes are absent", async () => {
    const synced: string[] = [];
    const store = new BlobStore(dir, "writer", async path => void synced.push(path));
    const written = await store.writeImmutable(RID, GENERATION, Buffer.from("candidate"));
    const physicalPath = join(dir, ".generations", RID, GENERATION);
    rmSync(physicalPath);
    synced.length = 0;

    await store.deleteByKey(written.blobKey);

    expect(synced).toEqual([
      join(dir, ".generations", RID),
      join(dir, ".generations"),
      dir,
    ]);
    expect(existsSync(join(dir, ".generations", RID))).toBe(false);
  });

  it("durably confirms an already-absent generation namespace", async () => {
    const synced: string[] = [];
    const store = new BlobStore(dir, "writer", async path => void synced.push(path));

    await store.deleteByKey(`${RID}/${GENERATION}`);

    expect(synced).toEqual([dir]);
  });

  it("never removes a sibling generation while cleaning a candidate", async () => {
    const store = new BlobStore(dir, "writer");
    const candidate = await store.writeImmutable(RID, GENERATION, Buffer.from("candidate"));
    const sibling = await store.writeImmutable(RID, SECOND_GENERATION, Buffer.from("sibling"));

    await store.deleteByKey(candidate.blobKey);

    expect(existsSync(join(dir, ".generations", RID))).toBe(true);
    expect((await collect(await store.read(RID, sibling.blobKey))).toString()).toBe("sibling");
  });

  it("reads a legacy flat blob only when metadata has no generation key", async () => {
    writeFileSync(join(dir, RID), "legacy");
    const store = new BlobStore(dir, "reader");
    expect((await collect(await store.read(RID, null))).toString()).toBe("legacy");
  });

  it("keeps a legacy flat blob intact while staging and reading a new generation", async () => {
    const legacyPath = join(dir, RID);
    writeFileSync(legacyPath, "legacy bytes");
    const store = new BlobStore(dir, "writer");

    expect((await collect(await store.read(RID, null))).toString()).toBe("legacy bytes");
    const written = await store.writeImmutable(RID, GENERATION, Buffer.from("new bytes"));
    expect(written.blobKey).toBe(`${RID}/${GENERATION}`);
    await store.verify(written.blobKey, written.bytes, written.contentSha256);

    expect((await collect(await store.read(RID, written.blobKey))).toString()).toBe("new bytes");
    expect((await collect(await store.read(RID, null))).toString()).toBe("legacy bytes");
    expect(readFileSync(legacyPath, "utf8")).toBe("legacy bytes");

    await store.deleteByKey(written.blobKey);
    await expect(store.read(RID, written.blobKey)).rejects.toBeInstanceOf(BlobNotFoundError);
    expect(readFileSync(legacyPath, "utf8")).toBe("legacy bytes");
  });

  it("rejects a committed key that belongs to a different resource", async () => {
    const store = new BlobStore(dir, "reader");
    const other = "ffffffffffffffffffffffffffffffff";
    await expect(store.read(RID, `${other}/${GENERATION}`)).rejects.toBeInstanceOf(PathError);
  });
});