Skip to content

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

TypeScript
10.1 KB
Raw Blame
import { createHash } from "node:crypto";
import { constants } from "node:fs";
import {
  open as fsOpen,
  rmdir as fsRmdir,
  rm as fsRm,
  stat as fsStat,
  statfs as fsStatfs,
} from "node:fs/promises";
import { dirname } from "node:path";
import { Readable, Transform } from "node:stream";
import { pipeline } from "node:stream/promises";
import {
  generationBlobKey,
  normalizeBlobKey,
  normalizeResourceId,
  PathError,
  resolveBlobKeyPath,
  resolveBlobPath,
} from "./paths";
import {
  ImmutableBlobFilesystem,
  isErrno,
  syncFilesystemPath,
  type DurabilitySync,
  type GenerationDirectoryOwnership,
  type RemoveBlobPath,
  type RemoveEmptyDirectory,
} from "./immutableBlobFilesystem";

export interface ImmutableBlob {
  blobKey: string;
  bytes: number;
  contentSha256: string;
}
export interface ImmutableWriteOptions {
  signal?: AbortSignal;
  checkDeadline?: () => void;
}
export type FilesystemStats = (path: string) => Promise<{ bavail: bigint; bsize: bigint }>;
type ExclusiveBlobOpen = (path: string, flags: number, mode: number) => ReturnType<typeof fsOpen>;
const readFilesystemStats: FilesystemStats = async path => {
  const stats = await fsStatfs(path, { bigint: true });
  return { bavail: stats.bavail, bsize: stats.bsize };
};

export class ReadOnlyStoreError extends Error {
  readonly code = "forbidden";
  constructor(message = "this gfsc replica mounts the drive read-only") {
    super(message);
    this.name = "ReadOnlyStoreError";
  }
}

export class BlobNotFoundError extends Error {
  readonly code = "not_found";
  constructor() {
    super("blob not found");
    this.name = "BlobNotFoundError";
  }
}
export class BlobVerificationError extends Error {
  constructor(message = "immutable blob verification failed") {
    super(message);
    this.name = "BlobVerificationError";
  }
}
export class BlobWriteCleanupError extends AggregateError {
  constructor(
    readonly writeError: unknown,
    readonly cleanupErrors: readonly unknown[]
  ) {
    super([writeError, ...cleanupErrors], "immutable blob write failed and cleanup was incomplete", {
      cause: writeError,
    });
    this.name = "BlobWriteCleanupError";
  }
}

function immutableBlobKey(resourceId: unknown, generation: unknown): string {
  try {
    return generationBlobKey(resourceId, generation);
  } catch (err) {
    if (err instanceof PathError) throw new PathError("invalid immutable blob identity");
    throw err;
  }
}

function committedBlobKey(resourceId: string, blobKey: string): string {
  let normalized: string;
  try {
    normalized = normalizeBlobKey(blobKey);
  } catch (err) {
    if (err instanceof PathError) throw new PathError("invalid committed blob reference");
    throw err;
  }
  if (!normalized.startsWith(`${normalizeResourceId(resourceId)}/`)) {
    throw new PathError("blob key does not belong to resource");
  }
  return normalized;
}

/** Immutable generations plus read-only legacy flat blobs. */
export class BlobStore {
  private readonly immutableFilesystem: ImmutableBlobFilesystem;

  constructor(
    private readonly prefix: string,
    private readonly role: "writer" | "reader",
    private readonly durabilitySync: DurabilitySync = syncFilesystemPath,
    private readonly filesystemStats: FilesystemStats = readFilesystemStats,
    private readonly openExclusive: ExclusiveBlobOpen = fsOpen,
    removeBlobPath?: RemoveBlobPath,
    removeEmptyDirectory?: RemoveEmptyDirectory
  ) {
    this.immutableFilesystem = new ImmutableBlobFilesystem(
      prefix,
      durabilitySync,
      removeBlobPath,
      removeEmptyDirectory
    );
  }

  private requireWriter(): void {
    if (this.role !== "writer") throw new ReadOnlyStoreError();
  }

  private checkWrite(options: ImmutableWriteOptions): void {
    options.signal?.throwIfAborted();
    options.checkDeadline?.();
  }

  async availableBytes(): Promise<bigint> {
    const stats = await this.filesystemStats(this.prefix);
    if (stats.bavail < 0n || stats.bsize < 0n) {
      throw new Error("filesystem reported invalid available space");
    }
    return stats.bavail * stats.bsize;
  }

  async writeImmutable(
    resourceId: string,
    generation: string,
    data: Readable | Buffer,
    options: ImmutableWriteOptions = {}
  ): Promise<ImmutableBlob> {
    this.requireWriter();
    this.checkWrite(options);
    const blobKey = immutableBlobKey(resourceId, generation);
    const path = resolveBlobKeyPath(this.prefix, blobKey);
    const parent = dirname(path);
    const generationRoot = dirname(parent);
    const source = Buffer.isBuffer(data) ? Readable.from(data) : data;
    const digest = createHash("sha256");
    let bytes = 0;
    const hashing = new Transform({
      transform(chunk: Buffer, _encoding, callback) {
        try {
          options.signal?.throwIfAborted();
          options.checkDeadline?.();
          const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
          bytes += value.length;
          digest.update(value);
          callback(null, value);
        } catch (err) {
          callback(err as Error);
        }
      },
    });
    let created = false;
    const directoryOwnership: GenerationDirectoryOwnership = {
      generationRoot: false,
      resourceDirectory: false,
    };
    try {
      this.checkWrite(options);
      await this.immutableFilesystem.ensureGenerationParent(path, directoryOwnership);
      this.checkWrite(options);
      await this.immutableFilesystem.assertSafeParents(path);
      await this.immutableFilesystem.assertNotSymlink(path);
      this.checkWrite(options);
      const handle = await this.openExclusive(
        path,
        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
        0o600
      );
      created = true;
      await pipeline(source, hashing, handle.createWriteStream(), { signal: options.signal });
      this.checkWrite(options);
      for (const syncPath of [path, parent, generationRoot, this.prefix]) {
        this.checkWrite(options);
        await this.durabilitySync(syncPath);
        this.checkWrite(options);
      }
      const info = await fsStat(path);
      if (!info.isFile() || info.size !== bytes) {
        throw new BlobVerificationError("immutable blob size verification failed");
      }
      const contentSha256 = digest.digest("hex");
      await this.verify(blobKey, bytes, contentSha256, options);
      return { blobKey, bytes, contentSha256 };
    } catch (err) {
      const cleanupErrors = await this.immutableFilesystem.cleanupFailedWrite(
        path,
        created,
        directoryOwnership
      );
      if (cleanupErrors.length > 0) {
        throw new BlobWriteCleanupError(err, cleanupErrors);
      }
      throw err;
    }
  }

  async verify(
    blobKey: string,
    expectedBytes: number,
    expectedSha256: string,
    options: ImmutableWriteOptions = {}
  ): Promise<void> {
    this.checkWrite(options);
    const path = resolveBlobKeyPath(this.prefix, blobKey);
    await this.immutableFilesystem.assertSafeParents(path);
    await this.immutableFilesystem.assertNotSymlink(path);
    const digest = createHash("sha256");
    let bytes = 0;
    const handle = await fsOpen(path, constants.O_RDONLY | constants.O_NOFOLLOW);
    const stream = handle.createReadStream();
    for await (const chunk of stream) {
      this.checkWrite(options);
      const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
      bytes += value.length;
      digest.update(value);
    }
    this.checkWrite(options);
    const actual = digest.digest("hex");
    if (bytes !== expectedBytes || actual !== expectedSha256) {
      throw new BlobVerificationError("immutable blob digest verification failed");
    }
  }

  async read(resourceId: string, blobKey?: string | null): Promise<Readable> {
    const normalizedBlobKey = blobKey ? committedBlobKey(resourceId, blobKey) : null;
    const path = normalizedBlobKey
      ? resolveBlobKeyPath(this.prefix, normalizedBlobKey)
      : resolveBlobPath(this.prefix, resourceId);
    try {
      await this.immutableFilesystem.assertSafeParents(path);
      await this.immutableFilesystem.assertNotSymlink(path);
      const handle = await fsOpen(path, constants.O_RDONLY | constants.O_NOFOLLOW);
      try {
        const info = await handle.stat();
        if (!info.isFile()) throw new PathError("blob path is not a file");
        return handle.createReadStream();
      } catch (err) {
        await handle.close().catch(() => undefined);
        throw err;
      }
    } catch (err) {
      if (isErrno(err, "ENOENT")) throw new BlobNotFoundError();
      throw err;
    }
  }

  async delete(resourceId: string): Promise<void> {
    this.requireWriter();
    const path = resolveBlobPath(this.prefix, resourceId);
    await this.immutableFilesystem.assertSafeParents(path);
    await this.immutableFilesystem.assertNotSymlink(path);
    try {
      await fsRm(path, { force: false });
      await this.durabilitySync(this.prefix);
    } catch (err) {
      if (isErrno(err, "ENOENT")) throw new BlobNotFoundError();
      throw err;
    }
  }

  async deleteByKey(blobKey: string): Promise<void> {
    this.requireWriter();
    const path = resolveBlobKeyPath(this.prefix, blobKey);
    const parent = dirname(path);
    const generationRoot = dirname(parent);
    try {
      await this.immutableFilesystem.assertSafeDirectory(generationRoot);
    } catch (err) {
      if (!isErrno(err, "ENOENT")) throw err;
      await this.durabilitySync(this.prefix);
      return;
    }

    let parentExists = true;
    try {
      await this.immutableFilesystem.assertSafeParents(path);
    } catch (err) {
      if (!isErrno(err, "ENOENT")) throw err;
      parentExists = false;
    }

    if (parentExists) {
      await this.immutableFilesystem.assertNotSymlink(path);
      try {
        await fsRm(path, { force: false });
      } catch (err) {
        if (!isErrno(err, "ENOENT")) throw err;
      }
      await this.durabilitySync(parent);
    }

    try {
      await fsRmdir(parent);
    } catch (err) {
      if (!isErrno(err, "ENOENT") && !isErrno(err, "ENOTEMPTY")) throw err;
    }
    await this.durabilitySync(generationRoot);
    await this.durabilitySync(this.prefix);
  }
  async deleteLegacyFlat(resourceId: string): Promise<void> {
    return this.delete(resourceId);
  }
}