@ttsc/playground 0.21.0 → 0.23.0

package/src/react/internal/PlaygroundCompilerLifecycle.ts

@@ -0,0 +1,95 @@
+export interface IPlaygroundCompilerGeneration {
+  /** Whether this token still owns the active compiler Worker generation. */
+  isCurrent(): boolean;
+}
+
+/**
+ * Serializes dependency mutations and fences every asynchronous consumer of a
+ * compiler Worker generation.
+ *
+ * Invalidating a generation immediately makes its active task advisory-only and
+ * prevents its queued tasks from starting. New-generation tasks remain
+ * serialized behind an active old task so two dependency installers can never
+ * mutate the shared compiler filesystem concurrently.
+ */
+export class PlaygroundCompilerLifecycle {
+  private epoch: number = 0;
+  private queue: Promise<void> = Promise.resolve();
+
+  public capture(): IPlaygroundCompilerGeneration {
+    const epoch = this.epoch;
+    return {
+      isCurrent: () => this.epoch === epoch,
+    };
+  }
+
+  public invalidate(): IPlaygroundCompilerGeneration {
+    this.epoch++;
+    return this.capture();
+  }
+
+  public invalidateIfCurrent(
+    generation: IPlaygroundCompilerGeneration,
+  ): IPlaygroundCompilerGeneration | undefined {
+    if (!generation.isCurrent()) return undefined;
+    return this.invalidate();
+  }
+
+  /**
+   * Reset a Worker owned by `generation`, then clear its dependency metadata.
+   *
+   * The clear deliberately happens before a caller checks any independent
+   * source version. A source edit during reset still leaves an empty Worker, so
+   * its metadata must become empty too. A Worker-generation replacement
+   * performs its own synchronous clear and prevents this stale reset from
+   * clearing the replacement.
+   */
+  public async resetWorkerIfCurrent(
+    generation: IPlaygroundCompilerGeneration,
+    reset: () => Promise<void>,
+    clear: () => void,
+  ): Promise<boolean> {
+    if (!generation.isCurrent()) return false;
+    await reset();
+    if (!generation.isCurrent()) return false;
+    clear();
+    return true;
+  }
+
+  /**
+   * Run a Worker mutation and reconcile a source edit that lands during it.
+   *
+   * An RPC cannot be cancelled after it has started mutating the Worker's
+   * MemFS. If its source becomes stale before completion, reset that Worker and
+   * clear the matching dependency metadata before another source can reuse it.
+   */
+  public async mutateWorkerIfCurrent(
+    generation: IPlaygroundCompilerGeneration,
+    isSourceCurrent: () => boolean,
+    mutate: () => Promise<unknown>,
+    reset: () => Promise<void>,
+    clear: () => void,
+  ): Promise<boolean> {
+    if (!generation.isCurrent() || !isSourceCurrent()) return false;
+    await mutate();
+    if (!generation.isCurrent()) return false;
+    if (isSourceCurrent()) return true;
+    await this.resetWorkerIfCurrent(generation, reset, clear);
+    return false;
+  }
+
+  public enqueue<T>(
+    task: (generation: IPlaygroundCompilerGeneration) => Promise<T>,
+  ): Promise<T | undefined> {
+    const generation = this.capture();
+    const result = this.queue.then(async () => {
+      if (!generation.isCurrent()) return undefined;
+      return task(generation);
+    });
+    this.queue = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+}

package/src/react/internal/PlaygroundExecutionLifecycle.ts

@@ -0,0 +1,55 @@
+export interface IPlaygroundExecutionAttempt {
+  /** Signal passed through every cancellable step owned by this attempt. */
+  readonly signal: AbortSignal;
+  /** Whether this attempt may still commit messages or state. */
+  isCurrent(): boolean;
+  /** Release the active slot if this is still the current attempt. */
+  finish(): boolean;
+}
+
+/**
+ * Owns the cancellation and stale-write boundary for Execute attempts.
+ *
+ * React state stays in `PlaygroundShell`; this small state machine keeps the
+ * supersession rules independently testable and makes every invalidation path
+ * use the same abort behavior.
+ */
+export class PlaygroundExecutionLifecycle {
+  private active: AbortController | null = null;
+  private epoch = 0;
+
+  public begin(): IPlaygroundExecutionAttempt {
+    this.invalidate("a newer Execute started");
+    const controller = new AbortController();
+    const epoch = this.epoch;
+    this.active = controller;
+    return {
+      signal: controller.signal,
+      isCurrent: () => this.epoch === epoch && this.active === controller,
+      finish: () => {
+        if (this.epoch !== epoch || this.active !== controller) return false;
+        this.active = null;
+        return true;
+      },
+    };
+  }
+
+  /**
+   * Abort the active attempt and make its callbacks stale.
+   *
+   * Returns whether an active attempt was canceled.
+   */
+  public invalidate(reason: string): boolean {
+    const active = this.active;
+    this.active = null;
+    ++this.epoch;
+    active?.abort(createExecutionAbortError(reason));
+    return active !== null;
+  }
+}
+
+function createExecutionAbortError(reason: string): Error {
+  const error = new Error(`Playground execution aborted: ${reason}.`);
+  error.name = "AbortError";
+  return error;
+}

package/src/react/internal/recoverTerminalCompilerWorker.ts

@@ -0,0 +1,41 @@
+import { BootTtscWorkerTerminationError } from "@ttsc/wasm";
+
+export interface ITerminalCompilerWorkerRecovery {
+  /** Atomically claim and fence the failed Worker generation. */
+  claim(): boolean;
+  /** Close and clear that Worker generation. */
+  reset(): Promise<void>;
+  /** Publish the terminal error after the old Worker is no longer reachable. */
+  fail(error: unknown): void;
+}
+
+/**
+ * Replace a compiler Worker after its Go runtime started but boot never became
+ * usable. Returns false for ordinary compile, transport, and plugin failures.
+ */
+export async function recoverTerminalCompilerWorker(
+  error: unknown,
+  recovery: ITerminalCompilerWorkerRecovery,
+): Promise<boolean> {
+  if (!requiresCompilerWorkerReplacement(error)) return false;
+  if (!recovery.claim()) return true;
+  try {
+    await recovery.reset();
+  } finally {
+    recovery.fail(error);
+  }
+  return true;
+}
+
+/** Recognize both local errors and their plain tgrid/JSON transport shape. */
+export function requiresCompilerWorkerReplacement(error: unknown): boolean {
+  const code = BootTtscWorkerTerminationError.CODE;
+  const prefix = `[${code}] `;
+  if (typeof error === "string") return error.startsWith(prefix);
+  if (!error || typeof error !== "object") return false;
+  const record = error as { code?: unknown; message?: unknown };
+  return (
+    record.code === code ||
+    (typeof record.message === "string" && record.message.startsWith(prefix))
+  );
+}

package/src/sandbox/loadTypiaRuntimePack.ts

@@ -2,35 +2,171 @@
 //
 // The pack JSON itself is built by the site (e.g. `pack-typia-runtime.cjs`
 // in the ttsc website) and served at a site-chosen URL. It mirrors the
-// layout the typia transform's emit references — `typia/lib/internal/*`,
-// `@typia/utils/lib/*`, etc. — so a bundle's `require("typia/lib/internal/X")`
-// resolves to the matching pack entry.
+// layout the typia transform's emit references -- `typia/lib/internal/*`,
+// `@typia/utils/lib/*`, etc. -- so a bundle's
+// `require("typia/lib/internal/X")` resolves to the matching pack entry.
+import type { ILoadTypiaRuntimePackOptions } from "../structures/ILoadTypiaRuntimePackOptions";
 
-const packCache = new Map<string, Promise<Record<string, string>>>();
+interface RuntimePackEntry {
+  controller: AbortController;
+  promise: Promise<Record<string, string>>;
+}
+
+interface RuntimePackCancellationReason {
+  kind: "abort" | "timeout";
+  reason?: unknown;
+  timeoutMs?: number;
+}
+
+interface RuntimePackCancellation {
+  promise: Promise<never>;
+  dispose: () => void;
+}
+
+export const DEFAULT_RUNTIME_PACK_TIMEOUT_MS = 30_000;
+
+const packCache = new Map<string, RuntimePackEntry>();
 
 /**
- * Fetches the prebuilt runtime pack once per URL. Re-entrant on the same
- * in-flight promise. On rejection the cache entry is cleared so the next call
- * retries — otherwise a transient fetch failure (CDN blip, offline at first
- * Execute) would permanently break every later Execute attempt.
+ * Fetches the prebuilt runtime pack once per URL.
+ *
+ * Concurrent callers share one load. A caller abort or deadline cancels that
+ * shared attempt; rejection removes it from the cache so the next call retries
+ * from scratch. Successful packs remain cached.
  */
-export async function loadTypiaRuntimePack(
+export function loadTypiaRuntimePack(
   url: string,
+  options: ILoadTypiaRuntimePackOptions = {},
 ): Promise<Record<string, string>> {
+  const timeoutMs = resolveRuntimePackTimeout(options.timeoutMs);
   const cached = packCache.get(url);
-  if (cached) return cached;
+  if (cached) {
+    attachRuntimePackCancellation(cached, options.signal, timeoutMs);
+    return cached.promise;
+  }
+
+  const controller = new AbortController();
+  let phase = `fetching ${url}`;
+  const cancellation = createRuntimePackCancellation(
+    controller.signal,
+    () => phase,
+  );
+  let entry!: RuntimePackEntry;
   const promise = (async () => {
-    const response = await fetch(url);
-    if (!response.ok) {
+    const response = await raceRuntimePackCancellation(
+      fetch(url, { signal: controller.signal }),
+      cancellation.promise,
+      controller.signal,
+      () => phase,
+    );
+    if (!response.ok)
       throw new Error(
         `loadTypiaRuntimePack: failed to fetch ${url}: ${response.status}`,
       );
-    }
-    return (await response.json()) as Record<string, string>;
-  })().catch((err) => {
-    packCache.delete(url);
-    throw err;
-  });
-  packCache.set(url, promise);
+
+    phase = `reading JSON from ${url}`;
+    return (await raceRuntimePackCancellation(
+      response.json(),
+      cancellation.promise,
+      controller.signal,
+      () => phase,
+    )) as Record<string, string>;
+  })()
+    .catch((error) => {
+      if (packCache.get(url) === entry) packCache.delete(url);
+      throw error;
+    })
+    .finally(cancellation.dispose);
+
+  entry = { controller, promise };
+  packCache.set(url, entry);
+  attachRuntimePackCancellation(entry, options.signal, timeoutMs);
   return promise;
 }
+
+function resolveRuntimePackTimeout(timeoutMs: number | undefined): number {
+  const value = timeoutMs ?? DEFAULT_RUNTIME_PACK_TIMEOUT_MS;
+  if (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647)
+    throw new RangeError(
+      "loadTypiaRuntimePack: timeoutMs must be a positive integer no greater than 2147483647.",
+    );
+  return value;
+}
+
+function attachRuntimePackCancellation(
+  entry: RuntimePackEntry,
+  callerSignal: AbortSignal | undefined,
+  timeoutMs: number,
+): void {
+  const abortFromCaller = (): void => {
+    if (!entry.controller.signal.aborted)
+      entry.controller.abort({
+        kind: "abort",
+        reason: callerSignal?.reason,
+      } satisfies RuntimePackCancellationReason);
+  };
+  if (callerSignal?.aborted) abortFromCaller();
+  else callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
+
+  const timer = setTimeout(() => {
+    if (!entry.controller.signal.aborted)
+      entry.controller.abort({
+        kind: "timeout",
+        timeoutMs,
+      } satisfies RuntimePackCancellationReason);
+  }, timeoutMs);
+  const cleanup = (): void => {
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", abortFromCaller);
+  };
+  void entry.promise.then(cleanup, cleanup);
+}
+
+function createRuntimePackCancellation(
+  signal: AbortSignal,
+  getPhase: () => string,
+): RuntimePackCancellation {
+  let rejectCancellation!: (error: Error) => void;
+  const promise = new Promise<never>((_resolve, reject) => {
+    rejectCancellation = reject;
+  });
+  const onAbort = (): void => {
+    rejectCancellation(runtimePackCancellationError(signal, getPhase()));
+  };
+  signal.addEventListener("abort", onAbort, { once: true });
+  if (signal.aborted) onAbort();
+  return {
+    promise,
+    dispose: () => signal.removeEventListener("abort", onAbort),
+  };
+}
+
+async function raceRuntimePackCancellation<T>(
+  work: Promise<T>,
+  cancellation: Promise<never>,
+  signal: AbortSignal,
+  getPhase: () => string,
+): Promise<T> {
+  try {
+    return await Promise.race([work, cancellation]);
+  } catch (error) {
+    if (signal.aborted) throw runtimePackCancellationError(signal, getPhase());
+    throw error;
+  }
+}
+
+function runtimePackCancellationError(
+  signal: AbortSignal,
+  phase: string,
+): Error {
+  const reason = signal.reason as RuntimePackCancellationReason | undefined;
+  if (reason?.kind === "timeout")
+    return new Error(
+      `loadTypiaRuntimePack: timed out after ${reason.timeoutMs}ms while ${phase}.`,
+    );
+
+  const error = new Error(`loadTypiaRuntimePack: aborted while ${phase}.`);
+  const cause = reason?.kind === "abort" ? reason.reason : signal.reason;
+  if (cause !== undefined) (error as Error & { cause?: unknown }).cause = cause;
+  return error;
+}

package/src/structures/IInstallTypiaSourcePackOptions.ts

@@ -10,9 +10,13 @@ export interface IInstallTypiaSourcePackOptions {
    * matching `DEFAULT_WORK_DIR + "/node_modules"`.
    */
   mountRoot?: string;
+  /** Cancel the shared in-flight load. */
+  signal?: AbortSignal;
+  /** Maximum fetch and JSON-read time. Defaults to 30 seconds. */
+  timeoutMs?: number;
   /**
    * Optional fetcher. Defaults to `globalThis.fetch`. Override for tests or for
    * sites that want their own caching strategy.
    */
-  fetch?: (input: string) => Promise<Response>;
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>;
 }

package/src/structures/ILoadTypiaRuntimePackOptions.ts

@@ -0,0 +1,7 @@
+/** Cancellation and deadline policy for `loadTypiaRuntimePack`. */
+export interface ILoadTypiaRuntimePackOptions {
+  /** Cancel the shared in-flight load. */
+  signal?: AbortSignal;
+  /** Maximum fetch and JSON-read time. Defaults to 30 seconds. */
+  timeoutMs?: number;
+}

package/src/structures/IPlaygroundShellProps.ts

@@ -58,6 +58,12 @@ export interface IPlaygroundShellProps {
    * union to `createSandboxRequire` — without this channel the in-page Execute
    * sandbox cannot resolve any npm dependency the user installed.
    *
+   * `sandbox.signal` aborts when source or compiler options change, a newer
+   * Execute starts, or the shell unmounts. Implementations must pass it through
+   * to cancellable setup such as runtime-pack fetches. Synchronous evaluated
+   * user code cannot be preempted and still requires an isolated executor when
+   * untrusted code is accepted.
+   *
    * When omitted, the Execute UI is hidden.
    */
   executeBundle?: (
@@ -65,6 +71,7 @@ export interface IPlaygroundShellProps {
     sandbox: {
       console: Record<string, (...args: unknown[]) => void>;
       runtimeFiles: Record<string, string>;
+      signal: AbortSignal;
     },
   ) => Promise<void>;
 

package/src/structures/index.ts

@@ -4,6 +4,7 @@ export * from "./IConsoleMessage";
 export * from "./ICreateCompilerClientOptions";
 export * from "./ICreateWorkerCompilerOptions";
 export * from "./IInstallTypiaSourcePackOptions";
+export * from "./ILoadTypiaRuntimePackOptions";
 export * from "./ILintPluginConfig";
 export * from "./IOptionToggle";
 export * from "./IPlaygroundDependencyInstallOptions";