@swf2es/player-hosts 0.0.0-stage → 0.1.1

package/src/precompiled.ts

@@ -0,0 +1,166 @@
+// A ModuleCache of the modules the swf2es command compiled ahead of time,
+// read-only: each found by the key the command wrote beside it, which is
+// the one the player asks for when the SWF loads in the position the
+// command compiled it for, with its log, which the player replays as it
+// does a cached module's. A key the manifest lacks, as one taken by
+// another compiler, whose identity keys name, is a miss, and the player
+// compiles (see docs/architecture/modules.md, Caching modules).
+import type { CachedModule, ModuleCache } from "@swf2es/player";
+
+export interface PrecompiledModulesOptions {
+  /** A file the manifest names, or the manifest, read by its URL: fetched by default. */
+  read?: (url: URL) => Promise<string>;
+  /**
+   * Have the player import each module from its URL, as an ES module, not
+   * evaluate its text: for a page whose Content-Security-Policy refuses
+   * 'unsafe-eval'. The document then keeps the modules for as long as it
+   * lives.
+   */
+  importModules?: boolean;
+}
+
+/** The manifest's format this reads, the command's MANIFEST_VERSION: any other names no module. */
+const MANIFEST_VERSION = 2;
+
+interface Entry {
+  module: URL;
+  log: URL;
+  lengths: [number, number];
+}
+
+/**
+ * The modules of the manifest.json at `manifest` (a URL, resolved against
+ * the page's), and the logs beside them. The manifest is read at the first
+ * get, and again at the next if that failed. Asks for every module however
+ * small, so that with each precompiled none compiles.
+ */
+export function precompiledModules(
+  manifest: string | URL,
+  options: PrecompiledModulesOptions = {},
+): ModuleCache {
+  const base = new URL(manifest, globalThis.location?.href);
+  const read = options.read ?? fetchText;
+  let entries: Promise<Map<string, Entry>> | null = null;
+  const rejected = new Set<string>();
+  const load = async () => {
+    const parsed = JSON.parse(await read(base));
+    const map = new Map<string, Entry>();
+    if (parsed?.manifestVersion !== MANIFEST_VERSION) {
+      return map;
+    }
+
+    for (const e of [parsed.libraries, parsed.abcs].flat()) {
+      const { key, module, log, lengths } = e ?? {};
+      if (
+        typeof key === "string" &&
+        typeof module === "string" &&
+        typeof log === "string" &&
+        Array.isArray(lengths) &&
+        lengths.length === 2
+      ) {
+        map.set(key, {
+          module: new URL(module, base),
+          log: new URL(log, base),
+          lengths: [...lengths] as [number, number],
+        });
+      }
+    }
+
+    return map;
+  };
+
+  return {
+    minBytes: 0,
+    async get(key: string): Promise<CachedModule | undefined> {
+      if (rejected.has(key)) {
+        return undefined;
+      }
+
+      entries ??= load();
+      let found: Entry | undefined;
+      try {
+        found = (await entries).get(key);
+      } catch (e) {
+        entries = null;
+        throw e;
+      }
+
+      if (!found) {
+        return undefined;
+      }
+
+      // Each file by a URL of its key: a module or log of another build,
+      // which an HTTP cache may hold under the same name, is never this
+      // key's, and an imported module's length is not checked.
+      const { lengths } = found;
+      const [module, log] = [found.module, found.log].map((url) => {
+        const keyed = new URL(url);
+        keyed.search = key;
+        return keyed;
+      });
+      if (options.importModules) {
+        return { module: "", log: await read(log), lengths, url: module.href };
+      }
+
+      const [text, logText] = await Promise.all([read(module), read(log)]);
+      return { module: text, log: logText, lengths };
+    },
+    async put() {},
+    // Its files cannot be deleted; the key is not answered again on this page.
+    async delete(key) {
+      rejected.add(key);
+    },
+  };
+}
+
+async function fetchText(url: URL): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`${url}: HTTP ${response.status}`);
+  }
+
+  return response.text();
+}
+
+/**
+ * Caches asked in order, the first that holds a module answering, as the
+ * modules compiled ahead of time and then an IndexedDB cache: a module
+ * compiled goes to each. A deletion naming the entry the player could not
+ * use goes only to the member that gave that entry, which then answers
+ * the key no more, so that the player, which asks again once, reads the
+ * next one's; one naming none goes to each. One that fails is passed
+ * over. Asks for the ABCs the member that asks for the smallest does,
+ * every member then asked for them.
+ */
+export function chainCaches(...caches: ModuleCache[]): ModuleCache {
+  const sizes = caches.flatMap((c) => (c.minBytes === undefined ? [] : [c.minBytes]));
+  // By the entry, not the key: two reads of one key may have been answered by two members.
+  const answered = new WeakMap<CachedModule, ModuleCache>();
+  // A member that throws at the call skips none of the others.
+  const each = async (members: ModuleCache[], f: (cache: ModuleCache) => Promise<void>) => {
+    await Promise.allSettled(members.map((c) => Promise.resolve().then(() => f(c))));
+  };
+  return {
+    ...(sizes.length ? { minBytes: Math.min(...sizes) } : {}),
+    async get(key) {
+      for (const cache of caches) {
+        try {
+          const entry = await cache.get(key);
+          if (entry !== undefined) {
+            answered.set(entry, cache);
+            return entry;
+          }
+        } catch {
+          // The next may hold it.
+        }
+      }
+
+      return undefined;
+    },
+    put: (key, entry) => each(caches, (c) => c.put(key, entry)),
+    delete: (key, entry) => {
+      const from = entry && answered.get(entry);
+      return each(from ? [from] : caches, (c) => c.delete(key, entry));
+    },
+  };
+}

package/src/stage3d.ts

@@ -0,0 +1,76 @@
+import type { Context3D, Context3DLifecycle, Stage3DHost } from "@swf2es/player/context3d";
+
+export interface Stage3DSurface {
+  canvas: HTMLCanvasElement;
+  context: Context3D;
+  /** Called once after resource disposal and listener removal, including failed attachment. */
+  destroy?: () => void;
+}
+
+/** The caller supplies a positioned, clipped parent, with the display-list canvas
+ * above slots 0..3. The adapter disposes resources before removing a surface. */
+export function stage3DCanvasHost(
+  parent: HTMLElement,
+  create: (slot: number) => Stage3DSurface,
+): Stage3DHost {
+  const surfaces = new Map<number, Stage3DSurface & { detach: () => void }>();
+
+  return {
+    create(slot, lifecycle) {
+      if (surfaces.has(slot)) {
+        throw new Error("Stage3D surface must be removed before recreation");
+      }
+
+      const surface = create(slot);
+      const detach = observeLoss(surface.canvas, lifecycle);
+      try {
+        surface.canvas.style.position = "absolute";
+        surface.canvas.style.zIndex = String(slot);
+        parent.append(surface.canvas);
+        surfaces.set(slot, { ...surface, detach });
+      } catch (error) {
+        detach();
+        surface.context.dispose();
+        surface.canvas.remove();
+        surface.destroy?.();
+        throw error;
+      }
+
+      return surface.context;
+    },
+    place(slot, x, y, visible) {
+      const surface = surfaces.get(slot);
+      if (surface) {
+        const style = surface.canvas.style;
+        style.left = `${x}px`;
+        style.top = `${y}px`;
+        style.visibility = visible ? "visible" : "hidden";
+      }
+    },
+    remove(slot) {
+      const surface = surfaces.get(slot);
+      if (surface) {
+        surface.detach();
+        surface.canvas.remove();
+        surfaces.delete(slot);
+        surface.destroy?.();
+      }
+    },
+  };
+}
+
+/** The surface outlives its lost resources so the browser can signal recovery. */
+export function observeLoss(canvas: HTMLCanvasElement, lifecycle: Context3DLifecycle): () => void {
+  const lost = (event: Event): void => {
+    event.preventDefault();
+    lifecycle.lost();
+  };
+  const restored = (): void => lifecycle.restored();
+  canvas.addEventListener("webglcontextlost", lost);
+  canvas.addEventListener("webglcontextrestored", restored);
+
+  return () => {
+    canvas.removeEventListener("webglcontextlost", lost);
+    canvas.removeEventListener("webglcontextrestored", restored);
+  };
+}

package/src/web-worker.ts

@@ -0,0 +1,24 @@
+// A Web Worker running one background flash.system.Worker (workers.ts).
+import { runWorkerThread } from "@swf2es/player/worker";
+
+// The DOM's types, not a worker's, are this package's: its global scope as a worker sees it.
+const scope = globalThis as unknown as {
+  postMessage(message: unknown): void;
+  onmessage: ((event: MessageEvent) => void) | null;
+};
+runWorkerThread({
+  post: (message) => scope.postMessage(message),
+  listen: (receive) => {
+    scope.onmessage = (event) => {
+      // The host's first message: answered, it tells the host that what it
+      // posts reaches this worker, which it then counts on while the page's
+      // thread is blocked (workers.ts).
+      if (event.data?.type === "ping") {
+        scope.postMessage({ type: "ready" });
+        return;
+      }
+
+      receive(event.data);
+    };
+  },
+});

package/src/websocket.ts

@@ -0,0 +1,32 @@
+// A binary WebSocket bridge for flash.net.Socket. The caller chooses its URL protocol.
+import type { SocketHost } from "@swf2es/player";
+
+/** Map the AS3 host and port to a WebSocket endpoint that relays a byte stream. */
+export function webSocketSocketHost(
+  urlFor: (host: string, port: number) => string,
+  open: (url: string) => WebSocket = (url) => new WebSocket(url),
+): SocketHost {
+  return {
+    connect(host, port, events) {
+      const socket = open(urlFor(host, port));
+      socket.binaryType = "arraybuffer";
+      socket.addEventListener("open", () => events.open());
+      socket.addEventListener("message", ({ data }) => {
+        if (data instanceof ArrayBuffer) {
+          events.data(new Uint8Array(data));
+        } else {
+          events.error("Socket bridge sent a non-binary WebSocket message.");
+          socket.close();
+        }
+      });
+      socket.addEventListener("close", () => events.close());
+      socket.addEventListener("error", () => events.error("Error #2031: Socket Error."));
+
+      return {
+        // Browser WebSocket accepts typed arrays; the Socket native supplies ArrayBuffer-backed bytes.
+        send: (bytes) => socket.send(bytes as Uint8Array<ArrayBuffer>),
+        close: () => socket.close(),
+      };
+    },
+  };
+}

package/src/workers.ts

@@ -0,0 +1,255 @@
+// The browser's threads for flash.system.Worker (docs/workers.md): each
+// background worker a module Web Worker running web-worker.ts, given
+// codegen's compiled module so that it need not compile it again.
+//
+// A browser loads a Web Worker's modules only while the page's thread is
+// in its event loop, which a primordial blocked in Mutex.lock or
+// Condition.wait is not: Crossbridge starts a thread and waits for it in
+// the same script. So a few workers are started ahead, as Emscripten's
+// thread pool is, and a worker that starts takes one that has loaded,
+// which runs what it is posted whatever the page's thread does; another
+// is started in its place for the next.
+//
+// Nor does a worker that has run its script take the page's messages at
+// once: Chrome holds what the page posts to a Web Worker until the page's
+// thread has run its own task for the script's end, which may come after
+// the worker's first message. A page that blocked first would hold the
+// worker's start until it stopped blocking, past the script timeout. So a
+// worker counts as loaded only once it answers a message the page posted
+// it when it was made.
+import type { WorkerHost } from "@swf2es/player";
+import type { ThreadStart } from "@swf2es/player/worker";
+
+export interface WebWorkerHostOptions {
+  /** codegen.wasm compiled, as the player's own codegen was made from. */
+  codegen: WebAssembly.Module;
+  /**
+   * The worker script: by default this package's dist/thread/, which
+   * holds web-worker.js and the modules it imports with their bare
+   * specifiers made relative (build-thread.ts), so that it loads wherever
+   * the package is served, as a worker sees no import map. One from
+   * another origin, as a CDN's, starts through a module of the page's own
+   * that imports it, which a Content-Security-Policy must allow as a
+   * worker's `blob:` source.
+   */
+  url?: string | URL;
+  /**
+   * How many Web Workers to keep started ahead, for workers a script starts
+   * and then waits for without returning to the event loop: by default as
+   * many as the machine has cores, from 2 up to 4. The page's hosts for one
+   * script URL share them, and they are let go a while after the last
+   * player that used them is.
+   */
+  spares?: number;
+}
+
+/** A host of Web Workers, and when the workers it started ahead have loaded. */
+export interface WebWorkerHost extends WorkerHost {
+  /**
+   * Resolves once the workers started ahead have loaded, or failed to:
+   * a page that awaits it before it plays a SWF has them for a script
+   * that blocks at once.
+   */
+  readonly ready: Promise<void>;
+}
+
+/** A Web Worker started ahead: whether it has loaded, and the error it failed with meanwhile. */
+interface Spare {
+  worker: Worker;
+  ready: boolean;
+  failed: string | null;
+  /** Resolves once it has loaded or failed, whoever took it meanwhile. */
+  settled: Promise<void>;
+  settle(): void;
+}
+
+/**
+ * How long after a Web Worker's terminate it is taken to have stopped. A
+ * browser does not say, and Chrome lets a busy worker's script run on for
+ * some seconds (2.5 to 4 s measured, in Chrome 156) before it stops it by
+ * force; Firefox's and Safari's were not measured. The player stops a
+ * terminated worker's thread so only when the worker has not stopped
+ * itself first (scripting/workers.ts).
+ */
+const STOPPED_GRACE = 8000;
+
+/** The workers started ahead, by script URL. */
+const pools = new Map<string, Spare[]>();
+
+/** How many hosts not yet released use each pool, and the timer that lets an unused one go. */
+const users = new Map<string, { count: number; idle: ReturnType<typeof setTimeout> | null }>();
+
+/** How long a pool no player uses keeps its workers, for the next player a page makes. */
+const IDLE = 10_000;
+
+function use(url: string | URL): void {
+  const key = String(url);
+  const u = users.get(key) ?? { count: 0, idle: null };
+  if (u.idle !== null) {
+    clearTimeout(u.idle);
+    u.idle = null;
+  }
+
+  u.count++;
+  users.set(key, u);
+}
+
+function release(url: string | URL): void {
+  const key = String(url);
+  const u = users.get(key);
+  if (!u || --u.count > 0) {
+    return;
+  }
+
+  u.idle = setTimeout(() => {
+    for (const spare of pools.get(key) ?? []) {
+      spare.settle();
+      spare.worker.terminate();
+    }
+
+    pools.delete(key);
+    users.delete(key);
+  }, IDLE);
+}
+
+/** The page's own modules that import a worker script from another origin, by its URL. */
+const importers = new Map<string, string>();
+
+function spawn(url: string | URL): Worker {
+  const worker = construct(url);
+  // Answered with "ready" once the page's messages reach the worker.
+  worker.postMessage({ type: "ping" });
+  return worker;
+}
+
+function construct(url: string | URL): Worker {
+  try {
+    return new Worker(url, { type: "module" });
+  } catch (error) {
+    // A browser starts a worker only on a script of the page's origin.
+    if (!(error instanceof DOMException && error.name === "SecurityError")) {
+      throw error;
+    }
+
+    const href = new URL(url, globalThis.location?.href).href;
+    let importer = importers.get(href);
+    if (importer === undefined) {
+      const source = `import ${JSON.stringify(href)};`;
+      importer = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+      importers.set(href, importer);
+    }
+
+    return new Worker(importer, { type: "module" });
+  }
+}
+
+/** Keep `count` workers started ahead for `url`; where the page cannot start one, fewer. */
+function fill(url: string | URL, count: number): Spare[] {
+  const key = String(url);
+  let pool = pools.get(key);
+  if (!pool) {
+    pool = [];
+    pools.set(key, pool);
+  }
+
+  while (pool.length < count) {
+    let worker: Worker;
+    try {
+      worker = spawn(url);
+    } catch {
+      // A policy that forbids the script: start() reports it.
+      break;
+    }
+
+    let settle = () => {};
+    const spare: Spare = {
+      worker,
+      ready: false,
+      failed: null,
+      settled: new Promise((resolve) => {
+        settle = resolve;
+      }),
+      settle: () => settle(),
+    };
+    worker.onmessage = (event) => {
+      if (event.data?.type === "ready") {
+        spare.ready = true;
+        spare.settle();
+      }
+    };
+    worker.onerror = (event) => {
+      event.preventDefault();
+      spare.failed = event.message;
+      spare.settle();
+    };
+    pool.push(spare);
+  }
+
+  return pool;
+}
+
+/** The pool's first worker that has loaded, else its first that has not failed. */
+function take(pool: Spare[]): Spare | undefined {
+  for (const spare of pool.filter((s) => s.failed !== null)) {
+    spare.worker.terminate();
+    pool.splice(pool.indexOf(spare), 1);
+  }
+
+  const at = Math.max(
+    pool.findIndex((s) => s.ready),
+    0,
+  );
+  return pool.splice(at, 1)[0];
+}
+
+/** Background workers on module Web Workers. */
+export function webWorkerHost(options: WebWorkerHostOptions): WebWorkerHost {
+  const url = options.url ?? new URL("./thread/player-hosts/web-worker.js", import.meta.url);
+  const cores = (globalThis as { navigator?: { hardwareConcurrency?: number } }).navigator
+    ?.hardwareConcurrency;
+  const spares = options.spares ?? Math.min(4, Math.max(2, cores ?? 2));
+  use(url);
+  const pool = fill(url, spares);
+  let released = false;
+  return {
+    ready: Promise.all(pool.map((s) => s.settled)).then(() => {}),
+    release() {
+      if (!released) {
+        released = true;
+        release(url);
+      }
+    },
+    start(init, receive, failed) {
+      const spare = take(fill(url, spares));
+      const worker = spare?.worker ?? spawn(url);
+      // One in its place, loaded once the page's thread is free.
+      fill(url, spares);
+      // Taken before it loaded, it still settles the ready of the host that started it ahead.
+      worker.onmessage = (event) => {
+        // A worker taken before it loaded says so first.
+        if (event.data?.type === "ready") {
+          spare?.settle();
+        } else {
+          receive(event.data);
+        }
+      };
+      worker.onerror = (event) => {
+        event.preventDefault();
+        spare?.settle();
+        worker.terminate();
+        failed(new Error(`a background worker's thread failed: ${event.message}`));
+      };
+      const start: ThreadStart = { codegen: options.codegen, init };
+      worker.postMessage(start);
+      return {
+        post: (message) => worker.postMessage(message),
+        // A browser tells nobody when a Web Worker has stopped.
+        terminate: () => {
+          spare?.settle();
+          worker.terminate();
+          return new Promise((resolve) => setTimeout(resolve, STOPPED_GRACE));
+        },
+      };
+    },
+  };
+}