@riebeckite/runtime 0.0.0-stage → 0.0.36

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./src/core/errors.js";
+export * from "./src/core/instance.js";
+export * from "./src/core/outcome.js";
+export * from "./src/core/payload.js";
+export * from "./src/core/protocol.js";
+export * from "./src/core/registry.js";
+export * from "./src/core/types.js";

package/dist/index.js

@@ -0,0 +1,617 @@
+// src/core/errors.ts
+var RuntimeError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RuntimeError";
+  }
+};
+var RuntimeStateError = class extends RuntimeError {
+  constructor(message) {
+    super(message);
+    this.name = "RuntimeStateError";
+  }
+};
+var RuntimeFailureError = class extends RuntimeStateError {
+  constructor(message, options) {
+    super(message);
+    this.name = "RuntimeFailureError";
+    if (options?.cause !== void 0) this.cause = options.cause;
+  }
+};
+var RuntimeAbortError = class extends RuntimeError {
+  constructor(message = "Interactive runtime operation was aborted.") {
+    super(message);
+    this.name = "RuntimeAbortError";
+  }
+};
+var RuntimeTimeoutError = class extends RuntimeError {
+  constructor(message = "Interactive runtime operation timed out.") {
+    super(message);
+    this.name = "RuntimeTimeoutError";
+  }
+};
+var RuntimePayloadError = class extends RuntimeError {
+  constructor(message) {
+    super(message);
+    this.name = "RuntimePayloadError";
+  }
+};
+var RuntimeConcurrencyError = class extends RuntimeError {
+  constructor(message) {
+    super(message);
+    this.name = "RuntimeConcurrencyError";
+  }
+};
+var RuntimeWorkerError = class extends RuntimeError {
+  remoteName;
+  remoteKind;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RuntimeWorkerError";
+    this.remoteName = options?.remoteName;
+    this.remoteKind = options?.remoteKind;
+  }
+};
+var RuntimeWasmError = class extends RuntimeError {
+  trap;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RuntimeWasmError";
+    this.trap = options?.trap ?? false;
+  }
+};
+var RuntimeIframeError = class extends RuntimeError {
+  remoteKind;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RuntimeIframeError";
+    this.remoteKind = options?.remoteKind;
+  }
+};
+var RuntimeUnsupportedError = class extends RuntimeError {
+  constructor(message) {
+    super(message);
+    this.name = "RuntimeUnsupportedError";
+  }
+};
+
+// src/core/abort.ts
+var knownReasonTypes = [
+  RuntimeAbortError,
+  RuntimeTimeoutError,
+  RuntimeWasmError,
+  RuntimeWorkerError,
+  RuntimeIframeError,
+  RuntimeFailureError
+];
+function abortReasonToError(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) {
+    for (const type of knownReasonTypes) {
+      if (reason instanceof type) return reason;
+    }
+    if (reason.message) return new RuntimeAbortError(reason.message);
+  }
+  return new RuntimeAbortError();
+}
+
+// src/core/outcome.ts
+var RuntimeTransfer = class {
+  constructor(value, transfer = []) {
+    this.value = value;
+    this.transfer = transfer;
+  }
+  value;
+  transfer;
+};
+function transferOutput(value, transfer = []) {
+  return new RuntimeTransfer(value, transfer);
+}
+function isRuntimeTransfer(value) {
+  return value instanceof RuntimeTransfer;
+}
+
+// src/core/payload.ts
+var MAX_DEPTH = 16;
+var MAX_ENTRIES = 1e5;
+var encoder = new TextEncoder();
+function estimatePayloadSize(value) {
+  return estimate(value, 0, { entries: 0 }, /* @__PURE__ */ new WeakSet());
+}
+function assertPayloadSize(value, limit, label) {
+  if (limit <= 0) return;
+  const size = estimatePayloadSize(value);
+  if (size > limit) {
+    throw new RuntimePayloadError(
+      `${label} is ${size} bytes, exceeding the ${limit} byte runtime limit.`
+    );
+  }
+}
+function estimate(value, depth, counter, ancestors) {
+  counter.entries += 1;
+  if (counter.entries > MAX_ENTRIES) {
+    throw new RuntimePayloadError(
+      "Runtime payload contains too many entries to measure."
+    );
+  }
+  if (value === void 0 || value === null) return 0;
+  if (typeof value === "string") return encoder.encode(value).byteLength;
+  if (typeof value === "number") return 8;
+  if (typeof value === "boolean") return 1;
+  if (typeof value === "bigint") return 16;
+  if (typeof value === "function" || typeof value === "symbol") {
+    throw new RuntimePayloadError(
+      "Runtime payload is not structured-cloneable."
+    );
+  }
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  if (value instanceof Date) return 8;
+  if (depth >= MAX_DEPTH) {
+    throw new RuntimePayloadError("Runtime payload is nested too deeply.");
+  }
+  const objectValue = value;
+  if (ancestors.has(objectValue)) {
+    throw new RuntimePayloadError("Runtime payload must not contain cycles.");
+  }
+  ancestors.add(objectValue);
+  let total = 0;
+  if (value instanceof Map) {
+    for (const [key, item] of value) {
+      total += estimate(key, depth + 1, counter, ancestors);
+      total += estimate(item, depth + 1, counter, ancestors);
+    }
+  } else if (value instanceof Set) {
+    for (const item of value) {
+      total += estimate(item, depth + 1, counter, ancestors);
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      total += estimate(item, depth + 1, counter, ancestors);
+    }
+  } else {
+    for (const key of Object.keys(value)) {
+      total += encoder.encode(key).byteLength;
+      total += estimate(
+        value[key],
+        depth + 1,
+        counter,
+        ancestors
+      );
+    }
+  }
+  ancestors.delete(objectValue);
+  return total;
+}
+
+// src/core/instance.ts
+var instanceCounter = 0;
+var RuntimeInstance = class {
+  id;
+  instanceId;
+  kind;
+  capabilities;
+  driver;
+  controller = new AbortController();
+  listeners = /* @__PURE__ */ new Set();
+  active = /* @__PURE__ */ new Set();
+  limits;
+  onError;
+  currentState = "created";
+  requestCount = 0;
+  mountPromise;
+  disposePromise;
+  stopPromise;
+  failure;
+  constructor(definition, options) {
+    this.id = definition.id;
+    this.instanceId = createInstanceId(definition.id);
+    this.kind = definition.kind;
+    this.capabilities = definition.capabilities;
+    this.limits = resolveLimits(definition.limits);
+    this.onError = options.onError ?? defaultErrorReporter;
+    this.driver = definition.create({
+      instanceId: this.instanceId,
+      signal: this.controller.signal,
+      limits: this.limits,
+      root: options.root
+    });
+    if (options.signal?.aborted) {
+      void this.dispose();
+    } else {
+      options.signal?.addEventListener("abort", () => void this.dispose(), {
+        once: true
+      });
+    }
+  }
+  get state() {
+    return this.currentState;
+  }
+  get signal() {
+    return this.controller.signal;
+  }
+  onStateChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  mount() {
+    if (this.disposePromise) {
+      return Promise.reject(this.disposedError());
+    }
+    if (this.mountPromise) return this.mountPromise;
+    if (this.currentState !== "created") {
+      return Promise.reject(
+        new RuntimeStateError(
+          `Cannot mount runtime "${this.id}" from state "${this.currentState}".`
+        )
+      );
+    }
+    this.mountPromise = this.runStart();
+    return this.mountPromise;
+  }
+  async invoke(input, options = {}) {
+    if (this.currentState === "failed") {
+      throw new RuntimeFailureError(
+        `Runtime "${this.id}" failed and cannot be reused; create a new instance.`,
+        { cause: this.failure }
+      );
+    }
+    if (this.currentState !== "ready" && this.currentState !== "running") {
+      throw new RuntimeStateError(
+        `Cannot invoke runtime "${this.id}" from state "${this.currentState}".`
+      );
+    }
+    if (this.active.size >= this.limits.maxConcurrent) {
+      throw new RuntimeConcurrencyError(
+        `Runtime "${this.id}" rejected an invocation: ${this.active.size} requests are already in flight.`
+      );
+    }
+    if (options.signal?.aborted) throw abortReasonToError(options.signal);
+    if (options.capability && !this.capabilities.includes(options.capability)) {
+      throw new RuntimeStateError(
+        `Runtime "${this.id}" does not declare the "${options.capability}" capability.`
+      );
+    }
+    assertPayloadSize(input, this.limits.maxInputBytes, "Runtime input");
+    const requestId = ++this.requestCount;
+    const call = new AbortController();
+    const unlinkInstance = linkSignal(this.controller.signal, call);
+    const unlinkExternal = options.signal ? linkSignal(options.signal, call) : () => {
+    };
+    const timeoutMs = options.timeoutMs ?? this.limits.invokeTimeoutMs;
+    const timer = timeoutMs > 0 ? setTimeout(
+      () => call.abort(
+        new RuntimeTimeoutError(
+          `Runtime "${this.id}" invocation timed out after ${timeoutMs}ms.`
+        )
+      ),
+      timeoutMs
+    ) : void 0;
+    this.active.add(requestId);
+    this.transition("running");
+    try {
+      const pending = Promise.resolve(
+        this.driver.invoke(input, {
+          signal: call.signal,
+          requestId,
+          capability: options.capability,
+          transfer: options.transfer
+        })
+      );
+      const raw = await awaitWithSignal(pending, call.signal);
+      const output = isRuntimeTransfer(raw) ? raw.value : raw;
+      assertPayloadSize(output, this.limits.maxOutputBytes, "Runtime output");
+      return output;
+    } catch (error) {
+      if (error instanceof RuntimeFailureError) {
+        this.failure = error;
+        if (this.currentState === "running") this.transition("failed");
+        this.report(error, "invoke");
+      }
+      throw error;
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+      unlinkExternal();
+      unlinkInstance();
+      this.active.delete(requestId);
+      if (this.active.size === 0 && this.currentState === "running") {
+        this.transition("ready");
+      }
+    }
+  }
+  dispose() {
+    if (this.disposePromise) return this.disposePromise;
+    if (this.currentState === "disposed") return Promise.resolve();
+    this.disposePromise = this.runStop();
+    return this.disposePromise;
+  }
+  async runStart() {
+    this.transition("starting");
+    try {
+      const start = Promise.resolve(this.driver.start());
+      await awaitWithSignal(
+        withTimeout(
+          start,
+          this.limits.startTimeoutMs,
+          `Runtime "${this.id}" start timed out.`
+        ),
+        this.controller.signal
+      );
+      if (this.currentState !== "starting") {
+        throw this.disposedError();
+      }
+      this.transition("ready");
+    } catch (error) {
+      this.failure = error;
+      if (this.currentState === "starting") this.transition("failed");
+      this.report(error, "start");
+      await this.stopDriver();
+      throw error;
+    }
+  }
+  async runStop() {
+    if (this.currentState !== "disposed") this.transition("stopping");
+    this.controller.abort(new RuntimeAbortError("Runtime was disposed."));
+    await this.mountPromise?.catch(() => {
+    });
+    await this.stopDriver();
+    if (this.currentState !== "disposed") this.transition("disposed");
+    this.listeners.clear();
+  }
+  stopDriver() {
+    this.stopPromise ??= (async () => {
+      try {
+        await this.driver.stop();
+      } catch (error) {
+        this.report(error, "stop");
+      }
+    })();
+    return this.stopPromise;
+  }
+  disposedError() {
+    return new RuntimeAbortError(`Runtime "${this.id}" was disposed.`);
+  }
+  transition(state) {
+    const previous = this.currentState;
+    if (previous === state) return;
+    this.currentState = state;
+    const change = { previous, state };
+    for (const listener of this.listeners) {
+      try {
+        listener(change);
+      } catch (error) {
+        this.report(error, "state-change");
+      }
+    }
+  }
+  report(error, phase) {
+    try {
+      this.onError(error, phase);
+    } catch {
+      return;
+    }
+  }
+};
+function resolveLimits(limits) {
+  return {
+    maxInputBytes: limits.maxInputBytes ?? 4 * 1024 * 1024,
+    maxOutputBytes: limits.maxOutputBytes ?? 16 * 1024 * 1024,
+    maxConcurrent: limits.maxConcurrent ?? 16,
+    invokeTimeoutMs: limits.invokeTimeoutMs ?? 0,
+    startTimeoutMs: limits.startTimeoutMs ?? 15e3
+  };
+}
+function createInstanceId(id) {
+  const random = globalThis.crypto?.randomUUID?.();
+  if (random) return `${id}#${random}`;
+  instanceCounter += 1;
+  return `${id}#${Date.now().toString(36)}-${instanceCounter}`;
+}
+function linkSignal(parent, child) {
+  if (parent.aborted) {
+    child.abort(parent.reason);
+    return () => {
+    };
+  }
+  const listener = () => child.abort(parent.reason);
+  parent.addEventListener("abort", listener, { once: true });
+  return () => parent.removeEventListener("abort", listener);
+}
+function abortFrom(signal) {
+  return abortReasonToError(signal);
+}
+function awaitWithSignal(promise, signal) {
+  if (signal.aborted) {
+    void promise.catch(() => {
+    });
+    return Promise.reject(abortFrom(signal));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(abortFrom(signal));
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function withTimeout(promise, timeoutMs, message) {
+  if (timeoutMs <= 0) return promise;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new RuntimeTimeoutError(message)),
+      timeoutMs
+    );
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+function defaultErrorReporter(error, phase) {
+  if (error instanceof RuntimeAbortError) return;
+  console.error(`[riebeckite] Interactive runtime ${phase} failed.`, error);
+}
+
+// src/core/protocol.ts
+var RUNTIME_PROTOCOL = "riebeckite:runtime";
+var RUNTIME_PROTOCOL_VERSION = 1;
+var RUNTIME_MESSAGE_KINDS = [
+  "init",
+  "invoke",
+  "cancel",
+  "ready",
+  "result",
+  "error",
+  "fatal",
+  "dispose"
+];
+function isRuntimeMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const message = value;
+  if (message.protocol !== RUNTIME_PROTOCOL) return false;
+  if (message.version !== RUNTIME_PROTOCOL_VERSION) return false;
+  if (typeof message.instanceId !== "string") return false;
+  return RUNTIME_MESSAGE_KINDS.includes(message.kind);
+}
+function serializeRuntimeError(error) {
+  if (error instanceof Error) {
+    const details = error;
+    return {
+      name: error.name,
+      message: error.message,
+      kind: typeof details.kind === "string" ? details.kind : void 0,
+      trap: details.trap === true,
+      stack: error.stack
+    };
+  }
+  return {
+    name: "Error",
+    message: typeof error === "string" ? error : "Unknown runtime error."
+  };
+}
+
+// src/core/registry.ts
+var InteractiveRuntimeRegistry = class {
+  definitions = /* @__PURE__ */ new Map();
+  register(definition) {
+    if (this.definitions.has(definition.id)) {
+      throw new RuntimeStateError(
+        `Interactive runtime "${definition.id}" is already registered.`
+      );
+    }
+    this.definitions.set(
+      definition.id,
+      definition
+    );
+  }
+  has(id) {
+    return this.definitions.has(id);
+  }
+  get(id) {
+    const definition = this.definitions.get(id);
+    if (!definition) {
+      throw new RuntimeStateError(
+        `Interactive runtime "${id}" is not registered.`
+      );
+    }
+    return definition;
+  }
+  get ids() {
+    return [...this.definitions.keys()];
+  }
+  create(id, options = {}) {
+    return new RuntimeInstance(this.get(id), options);
+  }
+};
+function defineInteractiveRuntime(definition) {
+  if (!definition.id.trim()) {
+    throw new RuntimeStateError("Interactive runtime id must not be empty.");
+  }
+  const capabilities = [...definition.capabilities ?? []];
+  if (new Set(capabilities).size !== capabilities.length) {
+    throw new RuntimeStateError(
+      `Interactive runtime "${definition.id}" declares duplicate capabilities.`
+    );
+  }
+  return Object.freeze({
+    id: definition.id,
+    kind: definition.kind,
+    capabilities: Object.freeze(capabilities),
+    limits: Object.freeze({ ...definition.limits ?? {} }),
+    create: definition.create
+  });
+}
+function createInteractiveRuntime(definition, options = {}) {
+  return new RuntimeInstance(definition, options);
+}
+
+// src/core/types.ts
+var RUNTIME_KINDS = [
+  "main",
+  "worker",
+  "wasm-worker",
+  "iframe"
+];
+var RUNTIME_STATES = [
+  "created",
+  "starting",
+  "ready",
+  "running",
+  "stopping",
+  "disposed",
+  "failed"
+];
+var RUNTIME_CAPABILITIES = [
+  "dom",
+  "worker",
+  "wasm",
+  "network",
+  "message"
+];
+export {
+  InteractiveRuntimeRegistry,
+  RUNTIME_CAPABILITIES,
+  RUNTIME_KINDS,
+  RUNTIME_MESSAGE_KINDS,
+  RUNTIME_PROTOCOL,
+  RUNTIME_PROTOCOL_VERSION,
+  RUNTIME_STATES,
+  RuntimeAbortError,
+  RuntimeConcurrencyError,
+  RuntimeError,
+  RuntimeFailureError,
+  RuntimeIframeError,
+  RuntimeInstance,
+  RuntimePayloadError,
+  RuntimeStateError,
+  RuntimeTimeoutError,
+  RuntimeTransfer,
+  RuntimeUnsupportedError,
+  RuntimeWasmError,
+  RuntimeWorkerError,
+  assertPayloadSize,
+  createInteractiveRuntime,
+  defineInteractiveRuntime,
+  estimatePayloadSize,
+  isRuntimeMessage,
+  isRuntimeTransfer,
+  serializeRuntimeError,
+  transferOutput
+};

package/dist/src/client/errors.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeErrorWire } from "../core/protocol.js";
+export declare function runtimeErrorFromWire(error: RuntimeErrorWire | undefined, fallbackMessage: string): Error;

package/dist/src/client/fallback.d.ts

@@ -0,0 +1,7 @@
+export type RuntimeFallback = {
+    showLoading(): void;
+    showReady(): void;
+    showError(error: unknown): void;
+    reset(): void;
+};
+export declare function createRuntimeFallback(root: Element): RuntimeFallback;

package/dist/src/client/host.d.ts

@@ -0,0 +1,10 @@
+import type { ClientRuntimeHost } from "@riebeckite/core/client";
+import type { InteractiveRuntimeRegistry } from "../core/registry.js";
+import type { RuntimeInstanceOptions } from "../core/types.js";
+export type ClientRuntimeHostOptions = {
+    readonly registry: InteractiveRuntimeRegistry;
+    readonly root?: unknown;
+    readonly signal?: AbortSignal;
+    readonly onError?: RuntimeInstanceOptions["onError"];
+};
+export declare function createClientRuntimeHost(options: ClientRuntimeHostOptions): ClientRuntimeHost;

package/dist/src/client/iframe.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeCapability, RuntimeDefinition, RuntimeLimits } from "../core/types.js";
+export declare const IFRAME_PROTOCOL = "riebeckite:iframe";
+export declare const IFRAME_PROTOCOL_VERSION = 1;
+export declare const MAX_ACTIVE_IFRAMES = 4;
+export type IframeRuntimeOptions = {
+    readonly id: string;
+    readonly capabilities?: readonly RuntimeCapability[];
+    readonly limits?: RuntimeLimits;
+    readonly html: string;
+    readonly title?: string;
+    readonly sandbox?: readonly string[];
+    readonly expectedOrigin?: string;
+    readonly csp?: string;
+    readonly container?: Element | string | (() => Element | null);
+};
+export declare function createIframeRuntime<TInput, TOutput>(options: IframeRuntimeOptions): RuntimeDefinition<TInput, TOutput>;

package/dist/src/client/main.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeCapability, RuntimeDefinition, RuntimeLimits } from "../core/types.js";
+export type MainRuntimeContext = {
+    readonly instanceId: string;
+    readonly signal: AbortSignal;
+    readonly limits: RuntimeLimits;
+    readonly root: unknown;
+};
+export type MainRuntimeOptions<TInput, TOutput> = {
+    readonly id: string;
+    readonly capabilities?: readonly RuntimeCapability[];
+    readonly limits?: RuntimeLimits;
+    readonly start?: (context: MainRuntimeContext) => void | Promise<void>;
+    readonly invoke: (input: TInput, context: MainRuntimeContext & {
+        readonly requestId: number;
+        readonly capability?: RuntimeCapability;
+    }) => TOutput | Promise<TOutput>;
+    readonly stop?: (context: MainRuntimeContext) => void | Promise<void>;
+};
+export declare function createMainRuntime<TInput, TOutput>(options: MainRuntimeOptions<TInput, TOutput>): RuntimeDefinition<TInput, TOutput>;

package/dist/src/client/wasm_worker.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeCapability, RuntimeDefinition, RuntimeLimits } from "../core/types.js";
+import { type WorkerLike } from "./worker.js";
+export type WasmWorkerRuntimeOptions<TOutput> = {
+    readonly id: string;
+    readonly capabilities?: readonly RuntimeCapability[];
+    readonly limits?: RuntimeLimits;
+    readonly createWorker: () => WorkerLike;
+    readonly wasmUrl: string;
+    readonly exportName: string;
+    readonly mapOutput?: (payload: unknown) => TOutput;
+};
+export declare function createWasmWorkerRuntime<TInput extends readonly unknown[], TOutput = unknown>(options: WasmWorkerRuntimeOptions<TOutput>): RuntimeDefinition<TInput, TOutput>;