@ccheever/exact-ibex-runtime 0.1.0

package/src/messaging/MessagePort.ts

@@ -0,0 +1,180 @@
+// @ts-nocheck
+/**
+ * MessagePort implementation for Ibex runtime
+ * 
+ * Implements the HTML MessagePort API for two-way communication.
+ * @see https://html.spec.whatwg.org/multipage/web-messaging.html#message-ports
+ */
+
+import { EventTarget } from '../events/EventTarget';
+import { MessageEvent } from '../events/MessageEvent';
+import { structuredClone } from '../clone/structuredClone';
+import { structuredCloneTransferSymbol } from '../clone/transferableSymbols';
+
+// Store for port pairs - weak references to avoid memory leaks
+const portPairs = new WeakMap<MessagePort, MessagePort>();
+
+/**
+ * MessagePort represents one end of a two-way communication channel.
+ * Messages sent through one port are received by the other port.
+ */
+export class MessagePort extends EventTarget {
+  #started = false;
+  #closed = false;
+  #queue: Array<{ data: any; transfer: Transferable[] }> = [];
+  #onmessage: ((this: MessagePort, ev: MessageEvent) => any) | null = null;
+  #onmessageerror: ((this: MessagePort, ev: MessageEvent) => any) | null = null;
+
+  constructor() {
+    super();
+  }
+
+  get onmessage(): ((this: MessagePort, ev: MessageEvent) => any) | null {
+    return this.#onmessage;
+  }
+
+  set onmessage(value: ((this: MessagePort, ev: MessageEvent) => any) | null) {
+    this.#onmessage = value;
+    if (value !== null) {
+      this.start();
+    }
+  }
+
+  get onmessageerror(): ((this: MessagePort, ev: MessageEvent) => any) | null {
+    return this.#onmessageerror;
+  }
+
+  set onmessageerror(value: ((this: MessagePort, ev: MessageEvent) => any) | null) {
+    this.#onmessageerror = value;
+  }
+
+  /**
+   * Posts a message through the channel.
+   * The message is cloned using the structured clone algorithm.
+   */
+  postMessage(message: any, transfer?: Transferable[]): void;
+  postMessage(message: any, options?: StructuredSerializeOptions): void;
+  postMessage(message: any, transferOrOptions?: Transferable[] | StructuredSerializeOptions): void {
+    if (this.#closed) {
+      return; // Silently ignore messages on closed ports
+    }
+
+    const transfer: Transferable[] = Array.isArray(transferOrOptions)
+      ? transferOrOptions
+      : (transferOrOptions?.transfer ?? []);
+
+    const otherPort = portPairs.get(this);
+    if (!otherPort) {
+      return; // No paired port, message is lost
+    }
+
+    // Clone the message
+    const clonedMessage = structuredClone(message, { transfer });
+
+    // Queue or deliver the message
+    if (otherPort.#started) {
+      otherPort._deliverMessage(clonedMessage, []);
+    } else {
+      otherPort.#queue.push({ data: clonedMessage, transfer: [] });
+    }
+  }
+
+  /**
+   * Begins dispatching messages received on the port.
+   * Messages are held in a queue until start() is called.
+   */
+  start(): void {
+    if (this.#started || this.#closed) {
+      return;
+    }
+
+    this.#started = true;
+
+    // Deliver queued messages
+    const queue = this.#queue;
+    this.#queue = [];
+
+    for (const { data, transfer } of queue) {
+      this._deliverMessage(data, transfer);
+    }
+  }
+
+  /**
+   * Disconnects the port, preventing any further messages.
+   */
+  close(): void {
+    this.#closed = true;
+    this.#started = false;
+    this.#queue = [];
+    
+    // Disconnect from paired port
+    const otherPort = portPairs.get(this);
+    if (otherPort) {
+      portPairs.delete(this);
+      portPairs.delete(otherPort);
+    }
+  }
+
+  /**
+   * Internal method to deliver a message to this port.
+   */
+  _deliverMessage(data: any, ports: MessagePort[]): void {
+    // Dispatch asynchronously per spec
+    queueMicrotask(() => {
+      if (this.#closed) {
+        return;
+      }
+
+      const event = new MessageEvent('message', {
+        data,
+        origin: '',
+        lastEventId: '',
+        source: null,
+        ports,
+      });
+
+      // Call onmessage handler
+      if (this.#onmessage) {
+        this.#onmessage.call(this, event);
+      }
+
+      // Dispatch event
+      this.dispatchEvent(event);
+    });
+  }
+
+  /**
+   * Internal method to set up port pairing.
+   */
+  static _pair(port1: MessagePort, port2: MessagePort): void {
+    portPairs.set(port1, port2);
+    portPairs.set(port2, port1);
+  }
+
+  [structuredCloneTransferSymbol](): MessagePort {
+    const transferredPort = new MessagePort();
+    const otherPort = portPairs.get(this);
+    transferredPort.#queue = this.#queue;
+    if (otherPort) {
+      portPairs.set(transferredPort, otherPort);
+      portPairs.set(otherPort, transferredPort);
+      portPairs.delete(this);
+    }
+    this.#queue = [];
+    this.#closed = true;
+    this.#started = false;
+    this.#onmessage = null;
+    this.#onmessageerror = null;
+    return transferredPort;
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'MessagePort';
+  }
+}
+
+interface StructuredSerializeOptions {
+  transfer?: Transferable[];
+}
+
+export default MessagePort;

package/src/messaging/index.ts

@@ -0,0 +1,2 @@
+export { MessagePort } from './MessagePort';
+export { MessageChannel } from './MessageChannel';

package/src/messaging.ts

@@ -0,0 +1,247 @@
+/**
+ * MessagePort and MessageChannel - Web Standard Messaging API
+ *
+ * Provides in-process message passing between ports via the structured clone
+ * algorithm.  Messages are always delivered asynchronously (via queueMicrotask)
+ * to match the HTML specification behaviour.
+ *
+ * @see https://html.spec.whatwg.org/multipage/web-messaging.html#message-channels
+ * @see https://html.spec.whatwg.org/multipage/web-messaging.html#message-ports
+ */
+
+import { EventTarget } from './events/EventTarget';
+import { MessageEvent } from './events/MessageEvent';
+import { structuredClone } from './clone/structuredClone';
+import { structuredCloneTransferSymbol } from './clone/transferableSymbols';
+
+// ---------------------------------------------------------------------------
+// MessagePort
+// ---------------------------------------------------------------------------
+
+/**
+ * A MessagePort represents one end of a two-port message channel.
+ *
+ * The port must be *started* before it will dispatch queued messages.
+ * Setting the `onmessage` property implicitly calls `start()` (per spec).
+ * Using `addEventListener('message', ...)` does NOT auto-start; the caller
+ * must invoke `start()` explicitly.
+ */
+export class MessagePort extends EventTarget {
+  /** The entangled remote port, or null if not yet wired / closed. */
+  #remotePort: MessagePort | null = null;
+
+  /** Whether `start()` has been called. */
+  #started = false;
+
+  /** Whether `close()` has been called. */
+  #closed = false;
+
+  /** Messages received before `start()` was called. */
+  #queue: unknown[] = [];
+
+  /** Backing field for the `onmessage` property. */
+  #onmessage: ((this: MessagePort, ev: MessageEvent) => any) | null = null;
+
+  /** Backing field for the `onmessageerror` property. */
+  #onmessageerror: ((this: MessagePort, ev: MessageEvent) => any) | null = null;
+
+  // -- Event handler properties (IDL attributes) ---------------------------
+
+  /**
+   * Setting `onmessage` implicitly calls `start()` per the HTML spec.
+   */
+  get onmessage(): ((this: MessagePort, ev: MessageEvent) => any) | null {
+    return this.#onmessage;
+  }
+
+  set onmessage(handler: ((this: MessagePort, ev: MessageEvent) => any) | null) {
+    this.#onmessage = handler;
+    // Per spec: setting onmessage implicitly starts the port
+    this.start();
+  }
+
+  get onmessageerror(): ((this: MessagePort, ev: MessageEvent) => any) | null {
+    return this.#onmessageerror;
+  }
+
+  set onmessageerror(handler: ((this: MessagePort, ev: MessageEvent) => any) | null) {
+    this.#onmessageerror = handler;
+  }
+
+  // -- Public API -----------------------------------------------------------
+
+  /**
+   * Post a message through this port to the entangled remote port.
+   *
+   * The `value` is cloned via `structuredClone` before delivery so that the
+   * sender and receiver hold independent copies.
+   *
+   * @param value  The message payload (must be structured-cloneable).
+   * @param transferList  Optional transfer list for ArrayBuffer ownership move.
+   */
+  postMessage(value: unknown, transferList?: Transferable[]): void {
+    if (this.#closed) {
+      return; // Silently ignore per spec (sender side closed)
+    }
+
+    const remote = this.#remotePort;
+    if (!remote || remote.#closed) {
+      return; // No entangled port or remote is closed
+    }
+
+    // Clone the message data
+    let clonedData: unknown;
+    try {
+      clonedData = structuredClone(value, { transfer: transferList as ArrayBuffer[] | undefined });
+    } catch (err) {
+      // Cloning failed — dispatch messageerror on the remote port
+      queueMicrotask(() => {
+        if (!remote.#closed) {
+          remote.#dispatchMessageError(err);
+        }
+      });
+      return;
+    }
+
+    // Deliver asynchronously
+    if (remote.#started) {
+      queueMicrotask(() => {
+        if (!remote.#closed) {
+          remote.#dispatchMessage(clonedData);
+        }
+      });
+    } else {
+      // Queue the message until the remote port is started
+      remote.#queue.push(clonedData);
+    }
+  }
+
+  /**
+   * Begin dispatching messages.  Messages posted before `start()` is called
+   * are buffered and flushed when start is invoked.
+   */
+  start(): void {
+    if (this.#started) {
+      return; // Idempotent
+    }
+
+    this.#started = true;
+
+    // Flush any queued messages
+    if (this.#queue.length > 0) {
+      const pending = this.#queue.splice(0);
+      for (const data of pending) {
+        queueMicrotask(() => {
+          if (!this.#closed) {
+            this.#dispatchMessage(data);
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Disentangle this port.  After calling `close()`, no more messages will
+   * be sent or received through this port.
+   */
+  close(): void {
+    this.#closed = true;
+    this.#queue.length = 0;
+    this.#remotePort = null;
+    this.#onmessage = null;
+    this.#onmessageerror = null;
+  }
+
+  // -- Internal wiring (used by MessageChannel) ----------------------------
+
+  /** @internal Wire this port to its remote partner. */
+  _setRemotePort(remote: MessagePort): void {
+    this.#remotePort = remote;
+  }
+
+  [structuredCloneTransferSymbol](): MessagePort {
+    const transferredPort = new MessagePort();
+    const remote = this.#remotePort;
+
+    transferredPort.#queue = this.#queue;
+    transferredPort.#started = this.#started;
+
+    if (remote && !remote.#closed) {
+      transferredPort._setRemotePort(remote);
+      remote._setRemotePort(transferredPort);
+    }
+
+    this.#queue = [];
+    this.#started = false;
+    this.#closed = true;
+    this.#remotePort = null;
+    this.#onmessage = null;
+    this.#onmessageerror = null;
+
+    return transferredPort;
+  }
+
+  // -- Private helpers ------------------------------------------------------
+
+  #dispatchMessage(data: unknown): void {
+    const event = new MessageEvent('message', { data });
+
+    // Call the IDL onmessage handler first
+    if (this.#onmessage) {
+      try {
+        this.#onmessage.call(this, event);
+      } catch (error) {
+        console.error('[MessagePort] onmessage handler threw:', error);
+      }
+    }
+
+    // Then dispatch to addEventListener listeners
+    this.dispatchEvent(event);
+  }
+
+  #dispatchMessageError(error: unknown): void {
+    const event = new MessageEvent('messageerror', { data: error });
+
+    if (this.#onmessageerror) {
+      try {
+        this.#onmessageerror.call(this, event);
+      } catch (e) {
+        console.error('[MessagePort] onmessageerror handler threw:', e);
+      }
+    }
+
+    this.dispatchEvent(event);
+  }
+
+  // -- Symbol.toStringTag ---------------------------------------------------
+
+  get [Symbol.toStringTag](): string {
+    return 'MessagePort';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MessageChannel
+// ---------------------------------------------------------------------------
+
+/**
+ * A MessageChannel creates a pair of entangled MessagePort objects.  Messages
+ * posted on one port are delivered to the other and vice versa.
+ */
+export class MessageChannel {
+  readonly port1: MessagePort;
+  readonly port2: MessagePort;
+
+  constructor() {
+    this.port1 = new MessagePort();
+    this.port2 = new MessagePort();
+
+    // Wire the two ports together
+    this.port1._setRemotePort(this.port2);
+    this.port2._setRemotePort(this.port1);
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'MessageChannel';
+  }
+}