@modelprofile.com/browser-runtime 1.0.0

package/ts/classes.artifactstore.ts

@@ -0,0 +1,432 @@
+import * as plugins from './plugins.js';
+import type {
+  IBrowserArtifactMetadata,
+  IBrowserArtifactStoreOptions,
+} from './interfaces.js';
+import { BrowserRuntimeError } from './errors.js';
+import {
+  TransitionMutex,
+  randomId,
+  validateBoundedString,
+  validateOptionalInteger,
+} from './utils.js';
+
+interface IStoredArtifact {
+  metadata: IBrowserArtifactMetadata;
+  digest: string;
+}
+
+interface IProjectArtifacts {
+  directoryName: string;
+  totalBytes: number;
+  artifacts: Map<string, IStoredArtifact>;
+}
+
+export class BrowserArtifactStore {
+  private readonly rootDirectory: string;
+  private readonly maxFileBytes: number;
+  private readonly maxArtifactsPerProject: number;
+  private readonly maxProjectBytes: number;
+  private readonly maxProjects: number;
+  private readonly maxTotalArtifacts: number;
+  private readonly maxTotalBytes: number;
+  private readonly artifactTtlMs: number;
+  private readonly now: () => number;
+  private readonly directoryKey = plugins.crypto.randomBytes(32);
+  private readonly projects = new Map<string, IProjectArtifacts>();
+  private readonly mutex = new TransitionMutex();
+  private totalArtifacts = 0;
+  private totalBytes = 0;
+  private started = false;
+  private startPromise?: Promise<void>;
+  private stopPromise?: Promise<void>;
+  private sweepTimer?: ReturnType<typeof setInterval>;
+  private sweepRunning = false;
+
+  constructor(options: IBrowserArtifactStoreOptions) {
+    if (!options || typeof options !== 'object' || !plugins.path.isAbsolute(options.rootDirectory)) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'rootDirectory must be absolute');
+    }
+    this.rootDirectory = options.rootDirectory;
+    this.maxFileBytes = validateOptionalInteger(
+      options.maxFileBytes,
+      'maxFileBytes',
+      1024,
+      64 * 1024 * 1024,
+      8 * 1024 * 1024,
+    );
+    this.maxArtifactsPerProject = validateOptionalInteger(
+      options.maxArtifactsPerProject,
+      'maxArtifactsPerProject',
+      1,
+      4096,
+      256,
+    );
+    this.maxProjectBytes = validateOptionalInteger(
+      options.maxProjectBytes,
+      'maxProjectBytes',
+      this.maxFileBytes,
+      1024 * 1024 * 1024,
+      64 * 1024 * 1024,
+    );
+    this.maxProjects = validateOptionalInteger(
+      options.maxProjects,
+      'maxProjects',
+      1,
+      256,
+      32,
+    );
+    this.maxTotalArtifacts = validateOptionalInteger(
+      options.maxTotalArtifacts,
+      'maxTotalArtifacts',
+      this.maxArtifactsPerProject,
+      65_536,
+      Math.max(4096, this.maxArtifactsPerProject),
+    );
+    this.maxTotalBytes = validateOptionalInteger(
+      options.maxTotalBytes,
+      'maxTotalBytes',
+      this.maxProjectBytes,
+      8 * 1024 * 1024 * 1024,
+      Math.max(512 * 1024 * 1024, this.maxProjectBytes),
+    );
+    this.artifactTtlMs = validateOptionalInteger(
+      options.artifactTtlMs,
+      'artifactTtlMs',
+      1000,
+      24 * 60 * 60 * 1000,
+      60 * 60 * 1000,
+    );
+    this.now = options.now ?? Date.now;
+    if (typeof this.now !== 'function') throw new BrowserRuntimeError('INVALID_INPUT');
+  }
+
+  public start(): Promise<void> {
+    if (this.started) return Promise.resolve();
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = this.startInternal().finally(() => {
+      this.startPromise = undefined;
+    });
+    return this.startPromise;
+  }
+
+  public stop(): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    if (!this.started && !this.startPromise) return Promise.resolve();
+    this.stopPromise = (async () => {
+      await this.startPromise?.catch(() => undefined);
+      if (this.sweepTimer) clearInterval(this.sweepTimer);
+      this.sweepTimer = undefined;
+      const release = await this.mutex.acquire();
+      try {
+        await plugins.fsPromises.rm(this.rootDirectory, { recursive: true, force: true });
+        this.projects.clear();
+        this.totalArtifacts = 0;
+        this.totalBytes = 0;
+        this.started = false;
+      } finally {
+        release();
+      }
+    })().finally(() => {
+      this.stopPromise = undefined;
+    });
+    return this.stopPromise;
+  }
+
+  public async store(
+    projectIdArg: string,
+    mimeTypeArg: string,
+    data: Uint8Array,
+  ): Promise<IBrowserArtifactMetadata> {
+    this.requireStarted();
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const mimeType = validateBoundedString(mimeTypeArg, 'mimeType', 1, 128);
+    if (!(data instanceof Uint8Array)) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'data must be Uint8Array');
+    }
+    if (data.byteLength > this.maxFileBytes) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    const bytes = plugins.Buffer.from(data);
+    const release = await this.mutex.acquire();
+    try {
+      this.requireStarted();
+      await this.purgeExpiredInternal(projectId);
+      const existingProject = this.projects.get(projectId);
+      if (!existingProject && this.projects.size >= this.maxProjects) {
+        throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      }
+      if (
+        this.totalArtifacts >= this.maxTotalArtifacts
+        || this.totalBytes + bytes.byteLength > this.maxTotalBytes
+      ) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      const project = existingProject ?? await this.createProject(projectId);
+      if (
+        project.artifacts.size >= this.maxArtifactsPerProject
+        || project.totalBytes + bytes.byteLength > this.maxProjectBytes
+      ) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+
+      const artifactId = randomId();
+      const createdAt = this.now();
+      const metadata: IBrowserArtifactMetadata = {
+        artifactId,
+        projectId,
+        mimeType,
+        size: bytes.byteLength,
+        createdAt,
+        expiresAt: createdAt + this.artifactTtlMs,
+      };
+      const stored: IStoredArtifact = {
+        metadata,
+        digest: plugins.crypto.createHash('sha256').update(bytes).digest('hex'),
+      };
+      const projectDirectory = plugins.path.join(this.rootDirectory, project.directoryName);
+      const finalPath = plugins.path.join(projectDirectory, artifactId);
+      const temporaryPath = plugins.path.join(projectDirectory, `.${randomId(12)}.tmp`);
+      let handle: plugins.fsPromises.FileHandle | undefined;
+      let renamed = false;
+      try {
+        handle = await plugins.fsPromises.open(temporaryPath, 'wx', 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await plugins.fsPromises.rename(temporaryPath, finalPath);
+        renamed = true;
+        await plugins.fsPromises.chmod(finalPath, 0o600);
+        project.artifacts.set(artifactId, stored);
+        project.totalBytes += bytes.byteLength;
+        this.totalArtifacts += 1;
+        this.totalBytes += bytes.byteLength;
+        return { ...metadata };
+      } catch (error) {
+        await handle?.close().catch(() => undefined);
+        await plugins.fsPromises.rm(temporaryPath, { force: true }).catch(() => undefined);
+        if (renamed) await plugins.fsPromises.rm(finalPath, { force: true }).catch(() => undefined);
+        if (project.artifacts.size === 0) await this.removeEmptyProject(projectId, project);
+        throw error;
+      }
+    } finally {
+      release();
+    }
+  }
+
+  public async read(projectIdArg: string, artifactIdArg: string): Promise<Uint8Array> {
+    this.requireStarted();
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const artifactId = validateBoundedString(artifactIdArg, 'artifactId', 1, 128);
+    const release = await this.mutex.acquire();
+    let handle: plugins.fsPromises.FileHandle | undefined;
+    try {
+      const { project, stored, filePath } = this.resolveArtifact(projectId, artifactId);
+      if (stored.metadata.expiresAt <= this.now()) {
+        await this.deleteArtifact(projectId, project, stored, filePath);
+        throw new BrowserRuntimeError('INVALID_INPUT', 'artifact is unavailable');
+      }
+      handle = await plugins.fsPromises.open(
+        filePath,
+        plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
+      );
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.size !== stored.metadata.size || stat.size > this.maxFileBytes) {
+        await handle.close();
+        handle = undefined;
+        await this.deleteArtifact(projectId, project, stored, filePath);
+        throw new BrowserRuntimeError('FENCED', 'artifact integrity check failed');
+      }
+      const data = plugins.Buffer.allocUnsafe(stat.size);
+      const { bytesRead } = await handle.read(data, 0, stat.size, 0);
+      await handle.close();
+      handle = undefined;
+      const digest = plugins.crypto.createHash('sha256').update(data).digest('hex');
+      if (bytesRead !== stat.size || digest !== stored.digest) {
+        await this.deleteArtifact(projectId, project, stored, filePath);
+        throw new BrowserRuntimeError('FENCED', 'artifact integrity check failed');
+      }
+      return new Uint8Array(data);
+    } finally {
+      await handle?.close().catch(() => undefined);
+      release();
+    }
+  }
+
+  public async delete(projectIdArg: string, artifactIdArg: string): Promise<void> {
+    this.requireStarted();
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const artifactId = validateBoundedString(artifactIdArg, 'artifactId', 1, 128);
+    const release = await this.mutex.acquire();
+    try {
+      const { project, stored, filePath } = this.resolveArtifact(projectId, artifactId);
+      await this.deleteArtifact(projectId, project, stored, filePath);
+    } finally {
+      release();
+    }
+  }
+
+  public async purgeExpired(projectIdArg?: string): Promise<number> {
+    this.requireStarted();
+    const projectId = projectIdArg === undefined
+      ? undefined
+      : validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const release = await this.mutex.acquire();
+    try {
+      return await this.purgeExpiredInternal(projectId);
+    } finally {
+      release();
+    }
+  }
+
+  public async purgeProject(projectIdArg: string): Promise<void> {
+    this.requireStarted();
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const release = await this.mutex.acquire();
+    try {
+      const project = this.projects.get(projectId);
+      if (!project) return;
+      await plugins.fsPromises.rm(
+        plugins.path.join(this.rootDirectory, project.directoryName),
+        { recursive: true, force: true },
+      );
+      this.totalArtifacts -= project.artifacts.size;
+      this.totalBytes -= project.totalBytes;
+      this.projects.delete(projectId);
+    } finally {
+      release();
+    }
+  }
+
+  public getMetadata(projectIdArg: string, artifactIdArg: string): IBrowserArtifactMetadata {
+    this.requireStarted();
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, 128);
+    const artifactId = validateBoundedString(artifactIdArg, 'artifactId', 1, 128);
+    const project = this.projects.get(projectId);
+    const stored = project?.artifacts.get(artifactId);
+    if (!stored || stored.metadata.expiresAt <= this.now()) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'artifact is unavailable');
+    }
+    try {
+      const stat = plugins.fs.lstatSync(
+        plugins.path.join(this.rootDirectory, project!.directoryName, artifactId),
+      );
+      if (stat.isSymbolicLink() || !stat.isFile() || stat.size !== stored.metadata.size) {
+        throw new BrowserRuntimeError('FENCED', 'artifact integrity check failed');
+      }
+    } catch (error) {
+      if (error instanceof BrowserRuntimeError) throw error;
+      throw new BrowserRuntimeError('FENCED', 'artifact integrity check failed');
+    }
+    return { ...stored.metadata };
+  }
+
+  private async startInternal(): Promise<void> {
+    try {
+      await plugins.fsPromises.mkdir(this.rootDirectory, { recursive: false, mode: 0o700 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+        const entries = await plugins.fsPromises.readdir(this.rootDirectory).catch(() => []);
+        throw new BrowserRuntimeError(
+          'FENCED',
+          entries.length > 0 ? 'artifact root is not empty' : 'artifact root must not exist',
+        );
+      }
+      throw error;
+    }
+    const stat = await plugins.fsPromises.lstat(this.rootDirectory);
+    const uid = process.getuid?.();
+    if (
+      !stat.isDirectory()
+      || stat.isSymbolicLink()
+      || (uid !== undefined && stat.uid !== uid)
+      || (stat.mode & 0o777) !== 0o700
+    ) throw new BrowserRuntimeError('FENCED', 'artifact root is not private');
+    const entries = await plugins.fsPromises.readdir(this.rootDirectory);
+    if (entries.length > 0) throw new BrowserRuntimeError('FENCED', 'artifact root is not empty');
+    await plugins.fsPromises.chmod(this.rootDirectory, 0o700);
+    this.started = true;
+    const sweepIntervalMs = Math.min(60_000, Math.max(1000, Math.floor(this.artifactTtlMs / 2)));
+    this.sweepTimer = setInterval(() => {
+      if (this.sweepRunning) return;
+      this.sweepRunning = true;
+      void this.purgeExpired().catch(() => undefined).finally(() => {
+        this.sweepRunning = false;
+      });
+    }, sweepIntervalMs);
+    this.sweepTimer.unref();
+  }
+
+  private requireStarted(): void {
+    if (!this.started) throw new BrowserRuntimeError('NOT_RUNNING');
+  }
+
+  private async createProject(projectId: string): Promise<IProjectArtifacts> {
+    const directoryName = plugins.crypto
+      .createHmac('sha256', this.directoryKey)
+      .update(projectId, 'utf8')
+      .digest('hex');
+    const projectDirectory = plugins.path.join(this.rootDirectory, directoryName);
+    await plugins.fsPromises.mkdir(projectDirectory, { recursive: false, mode: 0o700 });
+    const project = { directoryName, totalBytes: 0, artifacts: new Map() };
+    this.projects.set(projectId, project);
+    return project;
+  }
+
+  private async purgeExpiredInternal(projectId?: string): Promise<number> {
+    const projectIds = projectId === undefined ? [...this.projects.keys()] : [projectId];
+    let purged = 0;
+    for (const currentProjectId of projectIds) {
+      const project = this.projects.get(currentProjectId);
+      if (!project) continue;
+      for (const stored of [...project.artifacts.values()]) {
+        if (stored.metadata.expiresAt <= this.now()) {
+          const filePath = plugins.path.join(
+            this.rootDirectory,
+            project.directoryName,
+            stored.metadata.artifactId,
+          );
+          await this.deleteArtifact(currentProjectId, project, stored, filePath);
+          purged += 1;
+        }
+      }
+    }
+    return purged;
+  }
+
+  private async deleteArtifact(
+    projectId: string,
+    project: IProjectArtifacts,
+    stored: IStoredArtifact,
+    filePath: string,
+  ): Promise<void> {
+    await plugins.fsPromises.rm(filePath, { force: true });
+    if (project.artifacts.delete(stored.metadata.artifactId)) {
+      project.totalBytes = Math.max(0, project.totalBytes - stored.metadata.size);
+      this.totalArtifacts = Math.max(0, this.totalArtifacts - 1);
+      this.totalBytes = Math.max(0, this.totalBytes - stored.metadata.size);
+    }
+    await this.removeEmptyProject(projectId, project);
+  }
+
+  private async removeEmptyProject(projectId: string, project: IProjectArtifacts): Promise<void> {
+    if (project.artifacts.size > 0 || this.projects.get(projectId) !== project) return;
+    await plugins.fsPromises.rm(
+      plugins.path.join(this.rootDirectory, project.directoryName),
+      { recursive: true, force: true },
+    );
+    this.projects.delete(projectId);
+  }
+
+  private resolveArtifact(projectId: string, artifactId: string): {
+    project: IProjectArtifacts;
+    stored: IStoredArtifact;
+    filePath: string;
+  } {
+    const project = this.projects.get(projectId);
+    const stored = project?.artifacts.get(artifactId);
+    if (!project || !stored) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'artifact is unavailable');
+    }
+    return {
+      project,
+      stored,
+      filePath: plugins.path.join(this.rootDirectory, project.directoryName, artifactId),
+    };
+  }
+}