Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
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);
});
});