@scelar/nodepod 1.0.0

package/src/threading/vfs-bridge.ts

@@ -0,0 +1,231 @@
+// VFSBridge — syncs the canonical MemoryVolume with worker VFS clones.
+// Creates snapshots for initialization, applies worker writes, broadcasts changes.
+
+import type { MemoryVolume } from "../memory-volume";
+import type { VFSBinarySnapshot, VFSSnapshotEntry } from "./worker-protocol";
+import type { SharedVFSController } from "./shared-vfs";
+
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+
+const VFS_CHUNK_SIZE = 4 * 1024 * 1024; // 4MB
+
+/* ------------------------------------------------------------------ */
+/*  VFSBridge                                                          */
+/* ------------------------------------------------------------------ */
+
+export class VFSBridge {
+  private _volume: MemoryVolume;
+  private _broadcaster: ((path: string, content: ArrayBuffer | null, excludePid: number) => void) | null = null;
+  private _sharedVFS: SharedVFSController | null = null;
+  // Suppressed during handleWorkerWrite/Mkdir/Delete to prevent double-broadcasting
+  private _suppressWatch = false;
+
+  constructor(volume: MemoryVolume) {
+    this._volume = volume;
+  }
+
+  setBroadcaster(fn: (path: string, content: ArrayBuffer | null, excludePid: number) => void): void {
+    this._broadcaster = fn;
+  }
+
+  setSharedVFS(controller: SharedVFSController): void {
+    this._sharedVFS = controller;
+  }
+
+  // Packs all files into a single ArrayBuffer with a manifest
+  createSnapshot(): VFSBinarySnapshot {
+    const manifest: VFSSnapshotEntry[] = [];
+    const chunks: Uint8Array[] = [];
+    let totalSize = 0;
+
+    this._walkVolume("/", (path, isDirectory, content) => {
+      if (isDirectory) {
+        manifest.push({
+          path,
+          offset: 0,
+          length: 0,
+          isDirectory: true,
+        });
+      } else if (content) {
+        manifest.push({
+          path,
+          offset: totalSize,
+          length: content.byteLength,
+          isDirectory: false,
+        });
+        chunks.push(content);
+        totalSize += content.byteLength;
+      }
+    });
+
+    const data = new ArrayBuffer(totalSize);
+    const view = new Uint8Array(data);
+    let offset = 0;
+    for (const chunk of chunks) {
+      view.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+
+    return { manifest, data };
+  }
+
+  // Split into chunks for large transfers
+  createChunkedSnapshots(): { chunkIndex: number; totalChunks: number; data: ArrayBuffer; manifest: VFSSnapshotEntry[] }[] {
+    const fullSnapshot = this.createSnapshot();
+    const totalSize = fullSnapshot.data.byteLength;
+
+    if (totalSize <= VFS_CHUNK_SIZE) {
+      return [{
+        chunkIndex: 0,
+        totalChunks: 1,
+        data: fullSnapshot.data,
+        manifest: fullSnapshot.manifest,
+      }];
+    }
+
+    const chunks: { chunkIndex: number; totalChunks: number; data: ArrayBuffer; manifest: VFSSnapshotEntry[] }[] = [];
+    const fullData = new Uint8Array(fullSnapshot.data);
+    const totalChunks = Math.ceil(totalSize / VFS_CHUNK_SIZE);
+
+    let currentOffset = 0;
+    for (let i = 0; i < totalChunks; i++) {
+      const chunkEnd = Math.min(currentOffset + VFS_CHUNK_SIZE, totalSize);
+      const chunkData = fullData.slice(currentOffset, chunkEnd);
+
+      const chunkManifest = fullSnapshot.manifest.filter(entry => {
+        if (entry.isDirectory) return i === 0;
+        return entry.offset >= currentOffset && entry.offset < chunkEnd;
+      }).map(entry => ({
+        ...entry,
+        offset: entry.isDirectory ? 0 : entry.offset - currentOffset,
+      }));
+
+      chunks.push({
+        chunkIndex: i,
+        totalChunks,
+        data: chunkData.buffer.slice(chunkData.byteOffset, chunkData.byteOffset + chunkData.byteLength),
+        manifest: chunkManifest,
+      });
+
+      currentOffset = chunkEnd;
+    }
+
+    return chunks;
+  }
+
+  handleWorkerWrite(path: string, content: Uint8Array): void {
+    this._suppressWatch = true;
+    try {
+      const parentDir = path.substring(0, path.lastIndexOf("/")) || "/";
+      if (parentDir !== "/" && !this._volume.existsSync(parentDir)) {
+        this._volume.mkdirSync(parentDir, { recursive: true });
+      }
+      this._volume.writeFileSync(path, content);
+      if (this._sharedVFS) {
+        this._sharedVFS.writeFile(path, content);
+      }
+    } finally {
+      this._suppressWatch = false;
+    }
+  }
+
+  handleWorkerMkdir(path: string): void {
+    this._suppressWatch = true;
+    try {
+      if (!this._volume.existsSync(path)) {
+        this._volume.mkdirSync(path, { recursive: true });
+      }
+      if (this._sharedVFS) {
+        this._sharedVFS.writeDirectory(path);
+      }
+    } finally {
+      this._suppressWatch = false;
+    }
+  }
+
+  handleWorkerDelete(path: string): void {
+    this._suppressWatch = true;
+    try {
+      try {
+        if (this._volume.existsSync(path)) {
+          const stat = this._volume.statSync(path);
+          if (stat.isDirectory()) {
+            this._volume.rmdirSync(path);
+          } else {
+            this._volume.unlinkSync(path);
+          }
+        }
+      } catch (e) {
+        console.warn(`[VFSBridge] Failed to delete "${path}":`, e);
+      }
+      if (this._sharedVFS) {
+        this._sharedVFS.deleteFile(path);
+      }
+    } finally {
+      this._suppressWatch = false;
+    }
+  }
+
+  broadcastChange(path: string, content: ArrayBuffer | null, excludePid: number): void {
+    if (this._broadcaster) {
+      this._broadcaster(path, content, excludePid);
+    }
+  }
+
+  // Watches canonical volume for changes and pushes to workers. Returns unsubscribe fn.
+  watch(): () => void {
+    const handle = this._volume.watch("/", { recursive: true }, (event, filename) => {
+      if (!filename || this._suppressWatch) return;
+
+      try {
+        if (this._volume.existsSync(filename)) {
+          const stat = this._volume.statSync(filename);
+          if (stat.isDirectory()) {
+            this.broadcastChange(filename, new ArrayBuffer(0), -1);
+            if (this._sharedVFS) this._sharedVFS.writeDirectory(filename);
+          } else {
+            const data = this._volume.readFileSync(filename);
+            const buffer = (data.buffer as ArrayBuffer).slice(data.byteOffset, data.byteOffset + data.byteLength);
+            this.broadcastChange(filename, buffer, -1);
+            if (this._sharedVFS) this._sharedVFS.writeFile(filename, data);
+          }
+        } else {
+          this.broadcastChange(filename, null, -1);
+          if (this._sharedVFS) this._sharedVFS.deleteFile(filename);
+        }
+      } catch (e) {
+        console.warn(`[VFSBridge] Watch error for "${filename}":`, e);
+      }
+    });
+
+    return () => handle.close();
+  }
+
+  private _walkVolume(
+    dir: string,
+    visitor: (path: string, isDirectory: boolean, content: Uint8Array | null) => void,
+  ): void {
+    try {
+      const entries = this._volume.readdirSync(dir);
+      for (const name of entries) {
+        const fullPath = dir === "/" ? `/${name}` : `${dir}/${name}`;
+        try {
+          const stat = this._volume.statSync(fullPath);
+          if (stat.isDirectory()) {
+            visitor(fullPath, true, null);
+            this._walkVolume(fullPath, visitor);
+          } else {
+            const content = this._volume.readFileSync(fullPath);
+            visitor(fullPath, false, content);
+          }
+        } catch (e) {
+          console.warn(`[VFSBridge] Failed to stat/read "${fullPath}":`, e);
+        }
+      }
+    } catch (e) {
+      console.warn(`[VFSBridge] Failed to read directory "${dir}":`, e);
+    }
+  }
+}

package/src/threading/worker-pool.ts

@@ -0,0 +1,233 @@
+// WorkerPool — on-demand Web Worker pool for offload tasks.
+// Workers are pre-warmed, reused, and reaped after idle timeout.
+// If Worker creation fails (CSP, etc.), acquire() throws so the caller can fall back.
+
+import { wrap, type Remote } from "comlink";
+import type { OffloadWorkerEndpoint, PoolConfig } from "./offload-types";
+import { createInlineWorker, revokeInlineWorkerUrl } from "./inline-worker";
+import { TIMEOUTS, LIMITS } from "../constants/config";
+
+// --- Internal types ---
+
+interface PooledWorker {
+  thread: Worker;
+  endpoint: Remote<OffloadWorkerEndpoint>;
+  busy: boolean;
+  initialized: boolean;
+  initPromise: Promise<void> | null;
+  lastUsed: number;
+  id: number;
+}
+
+interface WaitEntry {
+  resolve: (result: { worker: PooledWorker; release: () => void }) => void;
+  reject: (err: Error) => void;
+}
+
+// --- WorkerPool ---
+
+export class WorkerPool {
+  private workers: PooledWorker[] = [];
+  private waitQueue: WaitEntry[] = [];
+  private nextId = 0;
+  private config: Required<PoolConfig>;
+  private idleTimer: ReturnType<typeof setInterval> | null = null;
+  private disposed = false;
+
+  broken = false;
+
+  constructor(config: PoolConfig = {}) {
+    const cores =
+      typeof navigator !== "undefined"
+        ? navigator.hardwareConcurrency || 4
+        : 4;
+
+    this.config = {
+      minWorkers: config.minWorkers ?? 1,
+      maxWorkers: config.maxWorkers ?? Math.min(cores, LIMITS.MAX_WORKERS_CAP),
+      idleTimeoutMs: config.idleTimeoutMs ?? TIMEOUTS.WORKER_IDLE_TIMEOUT,
+      warmUpOnCreate: config.warmUpOnCreate ?? true,
+    };
+
+    this.idleTimer = setInterval(() => this.reapIdle(), TIMEOUTS.WORKER_REAP_INTERVAL);
+  }
+
+  // --- Public API ---
+
+  // Returns a worker + release callback. Caller MUST call release() when done.
+  async acquire(): Promise<{ worker: PooledWorker; release: () => void }> {
+    if (this.disposed) throw new Error("WorkerPool is disposed");
+    if (this.broken) throw new Error("WorkerPool is broken — Workers unavailable");
+
+    // Try idle initialized worker first
+    const idle = this.workers.find((w) => !w.busy && w.initialized);
+    if (idle) {
+      idle.busy = true;
+      idle.lastUsed = Date.now();
+      return { worker: idle, release: () => this.release(idle) };
+    }
+
+    // Create new worker if under capacity
+    if (this.workers.length < this.config.maxWorkers) {
+      const pooled = this.tryCreateWorker();
+      if (!pooled) {
+        // Construction failed — mark pool as broken
+        this.broken = true;
+        this.rejectAllWaiters();
+        throw new Error("WorkerPool is broken — Worker construction failed");
+      }
+
+      pooled.busy = true;
+
+      // Wait for init to finish
+      if (!pooled.initialized && pooled.initPromise) {
+        try {
+          await pooled.initPromise;
+        } catch (err) {
+          // Init failed — mark pool as broken
+          this.terminateWorker(pooled);
+          this.broken = true;
+          this.rejectAllWaiters();
+          throw new Error(
+            `WorkerPool is broken — Worker init failed: ${err instanceof Error ? err.message : err}`,
+          );
+        }
+      }
+
+      pooled.lastUsed = Date.now();
+      return { worker: pooled, release: () => this.release(pooled) };
+    }
+
+    // At capacity — wait for a worker to become free
+    return new Promise<{ worker: PooledWorker; release: () => void }>(
+      (resolve, reject) => {
+        this.waitQueue.push({ resolve, reject });
+      },
+    );
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    if (this.idleTimer) {
+      clearInterval(this.idleTimer);
+      this.idleTimer = null;
+    }
+    for (const w of [...this.workers]) {
+      this.terminateWorker(w);
+    }
+    this.rejectAllWaiters();
+    revokeInlineWorkerUrl();
+  }
+
+  stats(): {
+    total: number;
+    busy: number;
+    idle: number;
+    initialized: number;
+  } {
+    return {
+      total: this.workers.length,
+      busy: this.workers.filter((w) => w.busy).length,
+      idle: this.workers.filter((w) => !w.busy).length,
+      initialized: this.workers.filter((w) => w.initialized).length,
+    };
+  }
+
+  // --- Internal ---
+
+  private rejectAllWaiters(): void {
+    for (const entry of this.waitQueue) {
+      entry.reject(new Error("WorkerPool is no longer available"));
+    }
+    this.waitQueue.length = 0;
+  }
+
+  private release(pooled: PooledWorker): void {
+    pooled.busy = false;
+    pooled.lastUsed = Date.now();
+
+    // Wake up anyone waiting for a worker
+    if (this.waitQueue.length > 0) {
+      const entry = this.waitQueue.shift()!;
+      pooled.busy = true;
+      pooled.lastUsed = Date.now();
+      entry.resolve({ worker: pooled, release: () => this.release(pooled) });
+    }
+  }
+
+  // Returns null if Worker construction fails (CSP, etc.)
+  private tryCreateWorker(): PooledWorker | null {
+    const thread = createInlineWorker();
+    if (!thread) return null;
+
+    try {
+      const endpoint = wrap<OffloadWorkerEndpoint>(thread);
+      const id = this.nextId++;
+
+      const pooled: PooledWorker = {
+        thread,
+        endpoint,
+        busy: false,
+        initialized: false,
+        initPromise: null,
+        lastUsed: Date.now(),
+        id,
+      };
+
+      // Pre-warm esbuild-wasm + pako. Timeout prevents stalled CDN from hanging.
+      if (this.config.warmUpOnCreate) {
+        const INIT_TIMEOUT = TIMEOUTS.WORKER_INIT_TIMEOUT;
+        const initCall = endpoint.init();
+        const timeout = new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error("Worker init timed out")), INIT_TIMEOUT),
+        );
+        pooled.initPromise = Promise.race([initCall, timeout])
+          .then(() => {
+            pooled.initialized = true;
+            pooled.initPromise = null;
+          })
+          .catch((err) => {
+            this.terminateWorker(pooled);
+            throw err; // propagate so acquire() can catch it
+          });
+      }
+
+      this.workers.push(pooled);
+      return pooled;
+    } catch {
+      try { thread.terminate(); } catch { /* ignore */ }
+      return null;
+    }
+  }
+
+  private reapIdle(): void {
+    const now = Date.now();
+    const candidates = this.workers.filter(
+      (w) =>
+        !w.busy &&
+        w.initialized &&
+        now - w.lastUsed > this.config.idleTimeoutMs,
+    );
+
+    // Keep at least minWorkers
+    const canRemove = Math.max(
+      0,
+      this.workers.length - this.config.minWorkers,
+    );
+    const toRemove = candidates.slice(0, canRemove);
+
+    for (const w of toRemove) {
+      this.terminateWorker(w);
+    }
+  }
+
+  private terminateWorker(pooled: PooledWorker): void {
+    const idx = this.workers.indexOf(pooled);
+    if (idx >= 0) this.workers.splice(idx, 1);
+    try {
+      pooled.thread.terminate();
+    } catch {
+      /* ignore */
+    }
+  }
+}