okgeometry-api 0.5.0 → 0.5.2

package/src/mesh-boolean.pool.ts

@@ -0,0 +1,481 @@
+import {
+  MeshBooleanExecutionError,
+  type MeshBooleanAsyncOptions,
+  type MeshBooleanErrorPayload,
+  type MeshBooleanOperation,
+  type MeshBooleanOptions,
+  type MeshBooleanProgressEvent,
+  type MeshBooleanWorkerRequest,
+  type MeshBooleanWorkerResponse,
+} from "./mesh-boolean.protocol.js";
+
+interface PoolAcquireOptions {
+  size?: number;
+  workerFactory?: () => Worker;
+}
+
+interface BooleanJob {
+  id: number;
+  operation: MeshBooleanOperation;
+  options: MeshBooleanOptions;
+  onProgress?: (event: MeshBooleanProgressEvent) => void;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  bufferA: ArrayBuffer;
+  bufferB: ArrayBuffer;
+  cancelView?: Int32Array;
+  timeoutToken?: number;
+  abortHandler?: () => void;
+  resolve: (value: Float64Array) => void;
+  reject: (reason: Error) => void;
+}
+
+interface WorkerSlot {
+  id: number;
+  worker: Worker;
+  currentJobId: number | null;
+  onMessage: (event: MessageEvent<MeshBooleanWorkerResponse>) => void;
+  onError: (event: ErrorEvent) => void;
+}
+
+function defaultPoolSize(): number {
+  if (typeof navigator === "undefined" || !Number.isFinite(navigator.hardwareConcurrency)) {
+    return 2;
+  }
+  const cores = Math.max(1, Math.floor(navigator.hardwareConcurrency));
+  return Math.min(4, Math.max(1, Math.floor(cores / 2)));
+}
+
+function normalizePoolSize(size: number | undefined): number {
+  if (!Number.isFinite(size) || size === undefined) return defaultPoolSize();
+  return Math.max(1, Math.floor(size));
+}
+
+function createWorker(workerFactory?: () => Worker): Worker {
+  if (workerFactory) return workerFactory();
+  if (typeof Worker === "undefined") {
+    throw new MeshBooleanExecutionError({
+      code: "worker_unavailable",
+      message: "Web Worker is not available in this environment.",
+    });
+  }
+  return new Worker(new URL("./mesh-boolean.worker.js", import.meta.url), { type: "module" });
+}
+
+function rejectPayload(code: MeshBooleanErrorPayload["code"], message: string, details?: string): MeshBooleanErrorPayload {
+  return { code, message, details };
+}
+
+function createCancellationView(): Int32Array | undefined {
+  if (typeof SharedArrayBuffer === "undefined") return undefined;
+  try {
+    return new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+  } catch {
+    return undefined;
+  }
+}
+
+function requestCancellation(job: BooleanJob): void {
+  if (!job.cancelView) return;
+  try {
+    Atomics.store(job.cancelView, 0, 1);
+  } catch {
+    job.cancelView[0] = 1;
+  }
+}
+
+export class MeshBooleanWorkerPool {
+  readonly size: number;
+  private readonly workerFactory?: () => Worker;
+  private disposed = false;
+  private nextJobId = 1;
+  private slots: WorkerSlot[] = [];
+  private readonly queue: BooleanJob[] = [];
+  private readonly running = new Map<number, BooleanJob>();
+
+  constructor(options?: PoolAcquireOptions) {
+    this.workerFactory = options?.workerFactory;
+    this.size = normalizePoolSize(options?.size);
+  }
+
+  get isDisposed(): boolean {
+    return this.disposed;
+  }
+
+  run(
+    operation: MeshBooleanOperation,
+    bufferA: Float64Array,
+    bufferB: Float64Array,
+    options?: MeshBooleanAsyncOptions,
+  ): Promise<Float64Array> {
+    if (this.disposed) {
+      return Promise.reject(
+        new MeshBooleanExecutionError(
+          rejectPayload("worker_unavailable", "Boolean worker pool has been disposed."),
+        ),
+      );
+    }
+
+    this.ensureWorkers();
+    const jobId = this.nextJobId++;
+
+    return new Promise<Float64Array>((resolve, reject) => {
+      const job: BooleanJob = {
+        id: jobId,
+        operation,
+        options: {
+          allowUnsafe: options?.allowUnsafe ?? true,
+          limits: options?.limits,
+          backend: options?.backend,
+        },
+        onProgress: options?.onProgress,
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs,
+        bufferA: new Float64Array(bufferA).buffer,
+        bufferB: new Float64Array(bufferB).buffer,
+        cancelView: createCancellationView(),
+        resolve,
+        reject,
+      };
+
+      if (job.signal?.aborted) {
+        this.rejectJob(job, rejectPayload("worker_aborted", `Boolean ${operation} aborted.`));
+        return;
+      }
+
+      if (job.signal) {
+        job.abortHandler = () => {
+          this.cancelJob(job.id, "worker_aborted", `Boolean ${job.operation} aborted.`);
+        };
+        job.signal.addEventListener("abort", job.abortHandler, { once: true });
+      }
+
+      this.queue.push(job);
+      this.emitProgress(job, "queued");
+      this.dispatch();
+    });
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+
+    while (this.queue.length > 0) {
+      const job = this.queue.shift()!;
+      this.rejectJob(job, rejectPayload("worker_aborted", "Boolean worker pool was disposed."));
+    }
+
+    for (const [jobId, job] of this.running) {
+      this.running.delete(jobId);
+      this.cleanupJob(job);
+      job.reject(new MeshBooleanExecutionError(rejectPayload("worker_aborted", "Boolean worker pool was disposed.")));
+    }
+
+    for (const slot of this.slots) {
+      slot.worker.removeEventListener("message", slot.onMessage as EventListener);
+      slot.worker.removeEventListener("error", slot.onError as EventListener);
+      slot.worker.terminate();
+    }
+    this.slots = [];
+  }
+
+  private ensureWorkers(): void {
+    while (this.slots.length < this.size) {
+      this.slots.push(this.spawnWorker(this.slots.length));
+    }
+  }
+
+  private spawnWorker(workerId: number): WorkerSlot {
+    const worker = createWorker(this.workerFactory);
+    const slot: WorkerSlot = {
+      id: workerId,
+      worker,
+      currentJobId: null,
+      onMessage: () => {},
+      onError: () => {},
+    };
+
+    slot.onMessage = (event: MessageEvent<MeshBooleanWorkerResponse>) => {
+      this.onWorkerMessage(slot, event.data);
+    };
+    slot.onError = (event: ErrorEvent) => {
+      const reason = event.message ? `: ${event.message}` : "";
+      this.failWorker(slot, rejectPayload("worker_crashed", `Boolean worker crashed${reason}`));
+    };
+
+    worker.addEventListener("message", slot.onMessage as EventListener);
+    worker.addEventListener("error", slot.onError as EventListener);
+    return slot;
+  }
+
+  private replaceWorker(slot: WorkerSlot): void {
+    slot.worker.removeEventListener("message", slot.onMessage as EventListener);
+    slot.worker.removeEventListener("error", slot.onError as EventListener);
+    slot.worker.terminate();
+    const replacement = this.spawnWorker(slot.id);
+    const index = this.slots.findIndex(s => s.id === slot.id);
+    if (index >= 0) {
+      this.slots[index] = replacement;
+    }
+  }
+
+  private dispatch(): void {
+    if (this.disposed) return;
+
+    for (;;) {
+      const slot = this.slots.find(s => s.currentJobId === null);
+      if (!slot) return;
+      const job = this.queue.shift();
+      if (!job) return;
+
+      if (job.signal?.aborted) {
+        this.rejectJob(job, rejectPayload("worker_aborted", `Boolean ${job.operation} aborted.`));
+        continue;
+      }
+
+      slot.currentJobId = job.id;
+      this.running.set(job.id, job);
+      this.emitProgress(job, "running", slot.id);
+
+      if (job.timeoutMs !== undefined && Number.isFinite(job.timeoutMs) && job.timeoutMs > 0) {
+        job.timeoutToken = setTimeout(() => {
+          this.cancelJob(job.id, "worker_timeout", `Boolean ${job.operation} timed out after ${job.timeoutMs}ms.`);
+        }, job.timeoutMs) as unknown as number;
+      }
+
+      const request: MeshBooleanWorkerRequest = {
+        kind: "mesh-boolean-request",
+        jobId: job.id,
+        operation: job.operation,
+        bufferA: job.bufferA,
+        bufferB: job.bufferB,
+        cancelBuffer: job.cancelView?.buffer as SharedArrayBuffer | undefined,
+        options: job.options,
+      };
+
+      try {
+        slot.worker.postMessage(request, [request.bufferA, request.bufferB]);
+      } catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        this.finishRunningJob(
+          slot,
+          job,
+          new MeshBooleanExecutionError(
+            rejectPayload("worker_protocol", "Failed to post boolean job to worker.", details),
+          ),
+          undefined,
+        );
+      }
+    }
+  }
+
+  private onWorkerMessage(slot: WorkerSlot, data: MeshBooleanWorkerResponse): void {
+    if (!data || data.kind !== "mesh-boolean-result") return;
+
+    const runningId = slot.currentJobId;
+    if (runningId === null) return;
+    if (runningId !== data.jobId) {
+      this.failWorker(
+        slot,
+        rejectPayload(
+          "worker_protocol",
+          `Worker responded with unexpected job id ${data.jobId}; expected ${runningId}.`,
+        ),
+      );
+      return;
+    }
+
+    const job = this.running.get(data.jobId);
+    if (!job) {
+      slot.currentJobId = null;
+      this.dispatch();
+      return;
+    }
+
+    if (data.ok) {
+      this.finishRunningJob(slot, job, undefined, new Float64Array(data.buffer));
+      return;
+    }
+
+    this.finishRunningJob(
+      slot,
+      job,
+      new MeshBooleanExecutionError(data.error),
+      undefined,
+    );
+  }
+
+  private failWorker(slot: WorkerSlot, payload: MeshBooleanErrorPayload): void {
+    const jobId = slot.currentJobId;
+    if (jobId !== null) {
+      const job = this.running.get(jobId);
+      if (job) {
+        this.running.delete(jobId);
+        this.cleanupJob(job);
+        job.reject(new MeshBooleanExecutionError(payload));
+      }
+      slot.currentJobId = null;
+    }
+    if (!this.disposed) {
+      this.replaceWorker(slot);
+      this.dispatch();
+    }
+  }
+
+  private cancelJob(jobId: number, code: MeshBooleanErrorPayload["code"], message: string): void {
+    const queuedIndex = this.queue.findIndex(job => job.id === jobId);
+    if (queuedIndex >= 0) {
+      const [job] = this.queue.splice(queuedIndex, 1);
+      this.rejectJob(job, rejectPayload(code, message));
+      return;
+    }
+
+    const job = this.running.get(jobId);
+    if (!job) return;
+
+    const slot = this.slots.find(s => s.currentJobId === jobId);
+    requestCancellation(job);
+    this.running.delete(jobId);
+    this.cleanupJob(job);
+    job.reject(new MeshBooleanExecutionError(rejectPayload(code, message)));
+    this.emitProgress(job, "completed", slot?.id);
+
+    if (slot) {
+      try {
+        slot.worker.postMessage({ kind: "mesh-boolean-cancel", jobId });
+      } catch {
+        // Best effort only; fallback behavior below still applies.
+      }
+
+      if (job.cancelView) {
+        // Cooperative cancellation: keep the slot occupied until the worker
+        // acknowledges completion/abort for this job id.
+        this.dispatch();
+        return;
+      }
+
+      slot.currentJobId = null;
+      if (!this.disposed) {
+        this.replaceWorker(slot);
+      }
+    }
+
+    this.dispatch();
+  }
+
+  private finishRunningJob(
+    slot: WorkerSlot,
+    job: BooleanJob,
+    error: Error | undefined,
+    result: Float64Array | undefined,
+  ): void {
+    this.running.delete(job.id);
+    slot.currentJobId = null;
+    this.cleanupJob(job);
+
+    if (error) {
+      job.reject(error);
+    } else if (result) {
+      job.resolve(result);
+    } else {
+      job.reject(
+        new MeshBooleanExecutionError(
+          rejectPayload("worker_protocol", "Boolean worker finished without a valid result."),
+        ),
+      );
+    }
+    this.emitProgress(job, "completed", slot.id);
+    this.dispatch();
+  }
+
+  private rejectJob(job: BooleanJob, payload: MeshBooleanErrorPayload): void {
+    this.cleanupJob(job);
+    job.reject(new MeshBooleanExecutionError(payload));
+    this.emitProgress(job, "completed");
+  }
+
+  private cleanupJob(job: BooleanJob): void {
+    if (job.timeoutToken !== undefined) clearTimeout(job.timeoutToken);
+    if (job.signal && job.abortHandler) {
+      job.signal.removeEventListener("abort", job.abortHandler);
+    }
+  }
+
+  private emitProgress(job: BooleanJob, stage: MeshBooleanProgressEvent["stage"], workerId?: number): void {
+    if (!job.onProgress) return;
+    job.onProgress({
+      stage,
+      jobId: job.id,
+      workerId,
+      queueSize: this.queue.length,
+    });
+  }
+}
+
+let defaultPoolSizeOverride: number | undefined;
+const defaultPools = new Map<number, MeshBooleanWorkerPool>();
+const factoryPools = new WeakMap<() => Worker, Map<number, MeshBooleanWorkerPool>>();
+const customPoolStores = new Set<Map<number, MeshBooleanWorkerPool>>();
+
+function getPoolStore(workerFactory?: () => Worker): Map<number, MeshBooleanWorkerPool> {
+  if (!workerFactory) return defaultPools;
+  let store = factoryPools.get(workerFactory);
+  if (!store) {
+    store = new Map<number, MeshBooleanWorkerPool>();
+    factoryPools.set(workerFactory, store);
+    customPoolStores.add(store);
+  }
+  return store;
+}
+
+export function getMeshBooleanWorkerPool(options?: PoolAcquireOptions): MeshBooleanWorkerPool {
+  const size = normalizePoolSize(options?.size ?? defaultPoolSizeOverride);
+  const store = getPoolStore(options?.workerFactory);
+  const existing = store.get(size);
+  if (existing && !existing.isDisposed) return existing;
+
+  const created = new MeshBooleanWorkerPool({
+    size,
+    workerFactory: options?.workerFactory,
+  });
+  store.set(size, created);
+  return created;
+}
+
+export function configureDefaultMeshBooleanWorkerPool(options: { size: number }): void {
+  const nextSize = normalizePoolSize(options.size);
+  if (defaultPoolSizeOverride === nextSize) return;
+  defaultPoolSizeOverride = nextSize;
+  for (const pool of defaultPools.values()) {
+    pool.dispose();
+  }
+  defaultPools.clear();
+}
+
+export function disposeMeshBooleanWorkerPools(): void {
+  for (const pool of defaultPools.values()) {
+    pool.dispose();
+  }
+  defaultPools.clear();
+
+  for (const store of customPoolStores) {
+    for (const pool of store.values()) {
+      pool.dispose();
+    }
+    store.clear();
+  }
+  customPoolStores.clear();
+}
+
+export function runMeshBooleanInWorkerPool(
+  operation: MeshBooleanOperation,
+  bufferA: Float64Array,
+  bufferB: Float64Array,
+  options?: MeshBooleanAsyncOptions,
+): Promise<Float64Array> {
+  const pool = getMeshBooleanWorkerPool({
+    workerFactory: options?.workerFactory,
+    size: options?.poolSize,
+  });
+  return pool.run(operation, bufferA, bufferB, options);
+}

package/src/mesh-boolean.protocol.ts

@@ -0,0 +1,122 @@
+export type MeshBooleanOperation = "union" | "subtraction" | "intersection";
+export type MeshBooleanBackend = "nextgen";
+
+export interface MeshBooleanLimits {
+  maxInputFacesPerMesh: number;
+  maxCombinedInputFaces: number;
+  maxFaceProduct: number;
+}
+
+export interface MeshBooleanOptions {
+  /**
+   * Override one or more safety limits for this operation.
+   */
+  limits?: Partial<MeshBooleanLimits>;
+  /**
+   * Skip safety limits and force boolean execution.
+   */
+  allowUnsafe?: boolean;
+  /**
+   * Boolean backend selector.
+   * Defaults to "nextgen" (strict closed-solid topology contract).
+   */
+  backend?: MeshBooleanBackend;
+}
+
+export type MeshBooleanErrorCode =
+  | "worker_unavailable"
+  | "worker_crashed"
+  | "worker_protocol"
+  | "worker_aborted"
+  | "worker_timeout"
+  | "kernel_error";
+
+export interface MeshBooleanErrorPayload {
+  code: MeshBooleanErrorCode;
+  message: string;
+  details?: string;
+}
+
+export type MeshBooleanJobStage = "queued" | "running" | "completed";
+
+export interface MeshBooleanProgressEvent {
+  stage: MeshBooleanJobStage;
+  jobId: number;
+  workerId?: number;
+  queueSize: number;
+}
+
+export interface MeshBooleanAsyncOptions extends MeshBooleanOptions {
+  /**
+   * Abort the worker job when this signal is aborted.
+   */
+  signal?: AbortSignal;
+  /**
+   * Optional timeout in milliseconds.
+   */
+  timeoutMs?: number;
+  /**
+   * Optional custom worker factory (for app-level worker pooling/reuse).
+   */
+  workerFactory?: () => Worker;
+  /**
+   * Override worker pool size for this call.
+   */
+  poolSize?: number;
+  /**
+   * Observe coarse-grained job stage changes.
+   */
+  onProgress?: (event: MeshBooleanProgressEvent) => void;
+}
+
+export interface MeshBooleanWorkerRequest {
+  kind: "mesh-boolean-request";
+  jobId: number;
+  operation: MeshBooleanOperation;
+  bufferA: ArrayBuffer;
+  bufferB: ArrayBuffer;
+  /**
+   * Optional shared cancellation flag (index 0: 0=running, 1=cancel requested).
+   * When present, kernel loops can cooperatively abort without waiting for
+   * worker message handling.
+   */
+  cancelBuffer?: SharedArrayBuffer;
+  options: MeshBooleanOptions;
+}
+
+export interface MeshBooleanWorkerCancel {
+  kind: "mesh-boolean-cancel";
+  jobId: number;
+}
+
+export type MeshBooleanWorkerInbound = MeshBooleanWorkerRequest | MeshBooleanWorkerCancel;
+
+export interface MeshBooleanWorkerSuccessResponse {
+  kind: "mesh-boolean-result";
+  jobId: number;
+  ok: true;
+  buffer: ArrayBuffer;
+  elapsedMs: number;
+}
+
+export interface MeshBooleanWorkerErrorResponse {
+  kind: "mesh-boolean-result";
+  jobId: number;
+  ok: false;
+  error: MeshBooleanErrorPayload;
+  elapsedMs: number;
+}
+
+export type MeshBooleanWorkerResponse = MeshBooleanWorkerSuccessResponse | MeshBooleanWorkerErrorResponse;
+
+export class MeshBooleanExecutionError extends Error {
+  readonly code: MeshBooleanErrorCode;
+  readonly details?: string;
+
+  constructor(payload: MeshBooleanErrorPayload) {
+    super(payload.message);
+    this.name = "MeshBooleanExecutionError";
+    this.code = payload.code;
+    this.details = payload.details;
+  }
+}