vector-framework 1.2.1 → 1.2.3

package/src/checkpoint/ipc.ts

@@ -0,0 +1,107 @@
+export type CheckpointIpcMessage =
+  | { type: 'ready' }
+  | { type: 'error'; message: string }
+  | { type: 'health'; status: 'ok' | 'degraded' };
+
+const MAX_PENDING_STDOUT_CHARS = 1_048_576; // 1 MiB guard against unbounded startup log lines.
+
+export function parseIpcLine(line: string): CheckpointIpcMessage | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  if (trimmed === 'READY') return { type: 'ready' };
+
+  try {
+    return JSON.parse(trimmed) as CheckpointIpcMessage;
+  } catch {
+    return null;
+  }
+}
+
+export async function waitForReady(stdout: ReadableStream<Uint8Array>, timeoutMs: number = 10_000): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const reader = stdout.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    function settle(fn: () => void) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        reader.releaseLock();
+      } catch {
+        // Ignore release failures when the reader is already detached.
+      }
+      fn();
+    }
+
+    const timer = setTimeout(() => {
+      settle(() => reject(new Error(`Checkpoint process did not become ready within ${timeoutMs}ms`)));
+    }, timeoutMs);
+
+    const processLine = (line: string): 'ready' | 'error' | 'continue' => {
+      const msg = parseIpcLine(line);
+      if (msg?.type === 'ready') {
+        settle(() => resolve());
+        return 'ready';
+      }
+      if (msg?.type === 'error') {
+        settle(() => reject(new Error(`Checkpoint process error: ${msg.message}`)));
+        return 'error';
+      }
+      return 'continue';
+    };
+
+    const processBufferLines = (): 'ready' | 'error' | 'continue' => {
+      let lineEnd = buffer.indexOf('\n');
+      while (lineEnd !== -1) {
+        const line = buffer.slice(0, lineEnd);
+        buffer = buffer.slice(lineEnd + 1);
+        const result = processLine(line);
+        if (result !== 'continue') {
+          return result;
+        }
+        lineEnd = buffer.indexOf('\n');
+      }
+      return 'continue';
+    };
+
+    // Iterative read loop (not recursive) to avoid stack overflow on large stdout
+    (async () => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+
+          if (done) {
+            buffer += decoder.decode();
+            const lastLine = buffer.trim();
+            if (lastLine.length > 0) {
+              const result = processLine(lastLine);
+              if (result !== 'continue') {
+                return;
+              }
+            }
+            settle(() => reject(new Error('Checkpoint process stdout closed before READY signal')));
+            return;
+          }
+
+          buffer += decoder.decode(value, { stream: true });
+          if (buffer.length > MAX_PENDING_STDOUT_CHARS) {
+            settle(() =>
+              reject(new Error(`Checkpoint process stdout exceeded ${MAX_PENDING_STDOUT_CHARS} chars before READY`))
+            );
+            return;
+          }
+
+          const result = processBufferLines();
+          if (result !== 'continue') {
+            return;
+          }
+        }
+      } catch (err) {
+        settle(() => reject(err));
+      }
+    })();
+  });
+}

package/src/checkpoint/manager.ts

@@ -0,0 +1,254 @@
+import { existsSync, promises as fs } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { ActivePointer, CheckpointConfig, CheckpointManifest, CheckpointPublishOptions } from './types';
+import { CHECKPOINT_FORMAT_VERSION } from './types';
+import { AssetStore } from './asset-store';
+import { CheckpointBundler } from './bundler';
+import { CheckpointEntrypointGenerator } from './entrypoint-generator';
+import { CheckpointPackager } from './artifacts/packager';
+import { resolveCheckpointSocketPath } from './socket-path';
+
+const DEFAULT_STORAGE_DIR = '.vector/checkpoints';
+const ACTIVE_POINTER_FILE = 'active.json';
+
+function inferLegacyAssetCodec(asset: {
+  codec?: 'none' | 'gzip';
+  blobPath?: string;
+  storedPath?: string;
+}): 'none' | 'gzip' {
+  if (asset.codec) {
+    return asset.codec;
+  }
+
+  const rawPath = (asset.blobPath ?? asset.storedPath ?? '').trim().toLowerCase();
+  return rawPath.endsWith('.gz') ? 'gzip' : 'none';
+}
+
+export class CheckpointManager {
+  private storageDir: string;
+  private maxCheckpoints: number;
+
+  constructor(config: CheckpointConfig = {}) {
+    this.storageDir = resolve(process.cwd(), config.storageDir ?? DEFAULT_STORAGE_DIR);
+    this.maxCheckpoints = config.maxCheckpoints ?? 10;
+  }
+
+  getStorageDir(): string {
+    return this.storageDir;
+  }
+
+  versionDir(version: string): string {
+    return join(this.storageDir, version);
+  }
+
+  socketPath(version: string): string {
+    return resolveCheckpointSocketPath(this.storageDir, version);
+  }
+
+  async ensureStorageDir(): Promise<void> {
+    await fs.mkdir(this.storageDir, { recursive: true });
+  }
+
+  async publish(options: CheckpointPublishOptions): Promise<CheckpointManifest> {
+    await this.ensureStorageDir();
+
+    const versionDir = this.versionDir(options.version);
+    await fs.mkdir(versionDir, { recursive: true });
+
+    // Generate entrypoint
+    const generator = new CheckpointEntrypointGenerator();
+    const entrypointPath = await generator.generate({
+      version: options.version,
+      outputDir: versionDir,
+      routesDir: resolve(process.cwd(), options.routesDir),
+      socketPath: this.socketPath(options.version),
+    });
+
+    // Bundle
+    const bundler = new CheckpointBundler();
+    const bundleResult = await bundler.bundle({
+      entrypointPath,
+      outputDir: versionDir,
+    });
+
+    // Collect assets
+    const assetStore = new AssetStore(this.storageDir);
+    const assets = await assetStore.collect(options.embeddedAssetPaths ?? [], options.sidecarAssetPaths ?? []);
+    assetStore.validateBudgets(assets);
+
+    // Build manifest
+    const manifest: CheckpointManifest = {
+      formatVersion: CHECKPOINT_FORMAT_VERSION,
+      version: options.version,
+      createdAt: new Date().toISOString(),
+      entrypoint: 'checkpoint.js',
+      routes: generator.getDiscoveredRoutes(),
+      assets,
+      bundleHash: bundleResult.hash,
+      bundleSize: bundleResult.size,
+      checkpointArchivePath: undefined,
+      checkpointArchiveHash: undefined,
+      checkpointArchiveSize: undefined,
+      checkpointArchiveCodec: undefined,
+    };
+
+    await this.writeManifest(options.version, manifest);
+
+    // Clean up entrypoint source (keep only the bundle)
+    try {
+      await fs.unlink(entrypointPath);
+    } catch {
+      // Ignore cleanup failures
+    }
+
+    // Package checkpoint folder with compression for local transport workflows.
+    const packager = new CheckpointPackager(this.storageDir);
+    const archive = await packager.packageVersion(options.version);
+    manifest.checkpointArchivePath = archive.archivePath;
+    manifest.checkpointArchiveHash = archive.archiveHash;
+    manifest.checkpointArchiveSize = archive.archiveSize;
+    manifest.checkpointArchiveCodec = archive.codec;
+    await this.writeManifest(options.version, manifest);
+
+    await this.pruneOld();
+
+    return manifest;
+  }
+
+  async readManifest(version: string): Promise<CheckpointManifest> {
+    const manifestPath = join(this.versionDir(version), 'manifest.json');
+    const content = await fs.readFile(manifestPath, 'utf-8');
+    return this.normalizeManifest(JSON.parse(content) as Partial<CheckpointManifest>);
+  }
+
+  async writeManifest(version: string, manifest: CheckpointManifest): Promise<void> {
+    const manifestPath = join(this.versionDir(version), 'manifest.json');
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+  }
+
+  async listVersions(): Promise<CheckpointManifest[]> {
+    if (!existsSync(this.storageDir)) {
+      return [];
+    }
+
+    const entries = await fs.readdir(this.storageDir);
+    const manifests: CheckpointManifest[] = [];
+
+    for (const entry of entries) {
+      const manifestPath = join(this.storageDir, entry, 'manifest.json');
+      if (existsSync(manifestPath)) {
+        try {
+          const content = await fs.readFile(manifestPath, 'utf-8');
+          manifests.push(this.normalizeManifest(JSON.parse(content) as Partial<CheckpointManifest>));
+        } catch {
+          // Skip corrupted manifests
+        }
+      }
+    }
+
+    // Sort by createdAt descending (newest first)
+    manifests.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    return manifests;
+  }
+
+  async getActive(): Promise<ActivePointer | null> {
+    const pointerPath = join(this.storageDir, ACTIVE_POINTER_FILE);
+    if (!existsSync(pointerPath)) {
+      return null;
+    }
+
+    try {
+      const content = await fs.readFile(pointerPath, 'utf-8');
+      return JSON.parse(content) as ActivePointer;
+    } catch {
+      return null;
+    }
+  }
+
+  async setActive(version: string): Promise<void> {
+    // Verify version exists
+    const versionDir = this.versionDir(version);
+    if (!existsSync(versionDir)) {
+      throw new Error(`Checkpoint version ${version} does not exist`);
+    }
+
+    const manifestPath = join(versionDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      throw new Error(`Checkpoint version ${version} has no manifest`);
+    }
+
+    await this.ensureStorageDir();
+
+    const pointer: ActivePointer = {
+      version,
+      activatedAt: new Date().toISOString(),
+    };
+
+    const pointerPath = join(this.storageDir, ACTIVE_POINTER_FILE);
+    await fs.writeFile(pointerPath, JSON.stringify(pointer, null, 2), 'utf-8');
+  }
+
+  async remove(version: string): Promise<void> {
+    // Check if this is the active version
+    const active = await this.getActive();
+    if (active?.version === version) {
+      throw new Error(`Cannot remove active checkpoint version ${version}. Rollback to a different version first.`);
+    }
+
+    const versionDir = this.versionDir(version);
+    if (!existsSync(versionDir)) {
+      throw new Error(`Checkpoint version ${version} does not exist`);
+    }
+
+    await fs.rm(versionDir, { recursive: true, force: true });
+  }
+
+  async pruneOld(): Promise<void> {
+    if (this.maxCheckpoints <= 0) return;
+
+    const manifests = await this.listVersions();
+    if (manifests.length <= this.maxCheckpoints) return;
+
+    const active = await this.getActive();
+    const toRemove = manifests.slice(this.maxCheckpoints);
+
+    for (const manifest of toRemove) {
+      // Never remove the active version
+      if (active?.version === manifest.version) continue;
+
+      try {
+        const versionDir = this.versionDir(manifest.version);
+        await fs.rm(versionDir, { recursive: true, force: true });
+      } catch {
+        // Ignore removal failures during pruning
+      }
+    }
+  }
+
+  private normalizeManifest(manifest: Partial<CheckpointManifest>): CheckpointManifest {
+    const normalizedAssets = (manifest.assets ?? []).map((asset) => ({
+      ...asset,
+      contentHash: asset.contentHash ?? asset.hash,
+      contentSize: asset.contentSize ?? asset.size,
+      blobPath: asset.blobPath ?? asset.storedPath,
+      blobHash: asset.blobHash,
+      blobSize: asset.blobSize,
+      codec: inferLegacyAssetCodec(asset),
+    }));
+
+    return {
+      formatVersion: manifest.formatVersion ?? CHECKPOINT_FORMAT_VERSION,
+      version: manifest.version ?? 'unknown',
+      createdAt: manifest.createdAt ?? new Date(0).toISOString(),
+      entrypoint: manifest.entrypoint ?? 'checkpoint.js',
+      routes: manifest.routes ?? [],
+      assets: normalizedAssets,
+      bundleHash: manifest.bundleHash ?? '',
+      bundleSize: manifest.bundleSize ?? 0,
+      checkpointArchivePath: manifest.checkpointArchivePath,
+      checkpointArchiveHash: manifest.checkpointArchiveHash,
+      checkpointArchiveSize: manifest.checkpointArchiveSize,
+      checkpointArchiveCodec: manifest.checkpointArchiveCodec,
+    };
+  }
+}

package/src/checkpoint/process-manager.ts

@@ -0,0 +1,250 @@
+import { existsSync, promises as fs, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { CheckpointManifest } from './types';
+import { waitForReady } from './ipc';
+import { CheckpointArtifactMaterializer } from './artifacts/materializer';
+import { resolveCheckpointSocketPath } from './socket-path';
+
+export interface SpawnedCheckpoint {
+  version: string;
+  socketPath: string;
+  process: ReturnType<typeof Bun.spawn>;
+  pid: number;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 10_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+const STOP_TIMEOUT_MS = 5_000;
+
+export interface CheckpointProcessManagerOptions {
+  readyTimeoutMs?: number;
+  idleTimeoutMs?: number;
+}
+
+export class CheckpointProcessManager {
+  private running: Map<string, SpawnedCheckpoint> = new Map();
+  private pending: Map<string, Promise<SpawnedCheckpoint>> = new Map();
+  private readyTimeoutMs: number;
+  private idleTimeoutMs: number;
+  private idleTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  private lastUsedAt: Map<string, number> = new Map();
+  private materializer: CheckpointArtifactMaterializer;
+
+  constructor(options: number | CheckpointProcessManagerOptions = DEFAULT_READY_TIMEOUT_MS) {
+    if (typeof options === 'number') {
+      this.readyTimeoutMs = options;
+      this.idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS;
+    } else {
+      this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+      this.idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    }
+
+    this.materializer = new CheckpointArtifactMaterializer();
+  }
+
+  async spawn(manifest: CheckpointManifest, storageDir: string): Promise<SpawnedCheckpoint> {
+    // Return already-running checkpoint
+    if (this.running.has(manifest.version)) {
+      return this.running.get(manifest.version)!;
+    }
+
+    // Return in-flight spawn to prevent duplicate processes for same version
+    if (this.pending.has(manifest.version)) {
+      return this.pending.get(manifest.version)!;
+    }
+
+    const promise = this.doSpawn(manifest, storageDir);
+    this.pending.set(manifest.version, promise);
+
+    try {
+      const result = await promise;
+      return result;
+    } finally {
+      this.pending.delete(manifest.version);
+    }
+  }
+
+  private async doSpawn(manifest: CheckpointManifest, storageDir: string): Promise<SpawnedCheckpoint> {
+    const versionDir = join(storageDir, manifest.version);
+    const bundlePath = join(versionDir, manifest.entrypoint);
+    const socketPath = resolveCheckpointSocketPath(storageDir, manifest.version);
+
+    if (!existsSync(bundlePath)) {
+      throw new Error(`Checkpoint bundle not found: ${bundlePath}`);
+    }
+
+    // Materialize declared assets into the checkpoint version directory before boot.
+    await this.materializer.materialize(manifest, storageDir);
+
+    // Ensure socket parent exists when fallback roots are used.
+    await fs.mkdir(dirname(socketPath), { recursive: true });
+
+    // Clean up stale socket file if it exists
+    this.tryUnlinkSocket(socketPath);
+
+    const proc = Bun.spawn(['bun', 'run', bundlePath], {
+      env: {
+        ...process.env,
+        VECTOR_CHECKPOINT_SOCKET: socketPath,
+        VECTOR_CHECKPOINT_VERSION: manifest.version,
+      },
+      stdout: 'pipe',
+      stderr: 'inherit',
+    });
+
+    // Guard against null stdout (shouldn't happen with stdout: 'pipe' but be safe)
+    if (!proc.stdout) {
+      proc.kill('SIGTERM');
+      throw new Error(`Checkpoint process for ${manifest.version} did not provide stdout`);
+    }
+
+    try {
+      await waitForReady(proc.stdout as ReadableStream<Uint8Array>, this.readyTimeoutMs);
+    } catch (err) {
+      proc.kill('SIGTERM');
+      throw err;
+    }
+
+    const spawned: SpawnedCheckpoint = {
+      version: manifest.version,
+      socketPath,
+      process: proc,
+      pid: proc.pid,
+    };
+
+    this.running.set(manifest.version, spawned);
+    this.lastUsedAt.set(manifest.version, Date.now());
+    this.scheduleIdleCheck(manifest.version);
+    return spawned;
+  }
+
+  markUsed(version: string): void {
+    if (!this.running.has(version)) {
+      return;
+    }
+    this.lastUsedAt.set(version, Date.now());
+  }
+
+  async stop(version: string): Promise<void> {
+    const snap = this.running.get(version);
+    if (!snap) return;
+
+    this.running.delete(version);
+    this.clearIdleTimer(version);
+    this.lastUsedAt.delete(version);
+
+    snap.process.kill('SIGTERM');
+
+    // Wait for exit with a timeout
+    const exited = await Promise.race([
+      snap.process.exited.then(() => true),
+      new Promise<false>((resolve) => setTimeout(() => resolve(false), STOP_TIMEOUT_MS)),
+    ]);
+
+    // Force kill if SIGTERM didn't work
+    if (!exited) {
+      try {
+        snap.process.kill('SIGKILL');
+        await snap.process.exited;
+      } catch {
+        // Process may have already exited between the check and SIGKILL
+      }
+    }
+
+    this.tryUnlinkSocket(snap.socketPath);
+  }
+
+  async stopAll(): Promise<void> {
+    const versions = [...this.running.keys()];
+    for (const version of versions) {
+      await this.stop(version);
+    }
+  }
+
+  isRunning(version: string): boolean {
+    return this.running.has(version);
+  }
+
+  getRunning(version: string): SpawnedCheckpoint | undefined {
+    return this.running.get(version);
+  }
+
+  async health(version: string): Promise<boolean> {
+    const snap = this.running.get(version);
+    if (!snap) return false;
+
+    try {
+      const response = await fetch('http://localhost/_vector/health', {
+        unix: snap.socketPath,
+        signal: AbortSignal.timeout(2000),
+      } as any);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  getRunningVersions(): string[] {
+    return [...this.running.keys()];
+  }
+
+  private scheduleIdleCheck(version: string, delayMs = this.idleTimeoutMs): void {
+    this.clearIdleTimer(version);
+    if (this.idleTimeoutMs <= 0) {
+      return;
+    }
+
+    const timer = setTimeout(
+      () => {
+        void this.handleIdleCheck(version);
+      },
+      Math.max(1, delayMs)
+    );
+
+    if (typeof (timer as any).unref === 'function') {
+      (timer as any).unref();
+    }
+
+    this.idleTimers.set(version, timer);
+  }
+
+  private async handleIdleCheck(version: string): Promise<void> {
+    if (!this.running.has(version)) {
+      return;
+    }
+
+    const lastUsedAt = this.lastUsedAt.get(version) ?? 0;
+    const idleForMs = Date.now() - lastUsedAt;
+    const remainingMs = this.idleTimeoutMs - idleForMs;
+
+    if (remainingMs > 0) {
+      this.scheduleIdleCheck(version, remainingMs);
+      return;
+    }
+
+    try {
+      await this.stop(version);
+    } catch (error) {
+      console.error(`[CheckpointProcessManager] Failed to stop idle checkpoint ${version}:`, error);
+    }
+  }
+
+  private clearIdleTimer(version: string): void {
+    const timer = this.idleTimers.get(version);
+    if (!timer) {
+      return;
+    }
+    clearTimeout(timer);
+    this.idleTimers.delete(version);
+  }
+
+  private tryUnlinkSocket(socketPath: string): void {
+    try {
+      if (existsSync(socketPath)) {
+        unlinkSync(socketPath);
+      }
+    } catch {
+      // Ignore cleanup failures
+    }
+  }
+}