@adobe/uix-core 0.6.5-1 → 0.7.0

package/src/tickets.ts

@@ -0,0 +1,71 @@
+import { INIT_CALLBACK } from "./constants";
+
+export interface HandshakeAcceptedTicket {
+  // #region Properties
+
+  accepts: string;
+  version: string;
+
+  // #endregion Properties
+}
+export interface HandshakeOfferedTicket {
+  // #region Properties
+
+  offers: string;
+  version: string;
+
+  // #endregion Properties
+}
+
+/** @internal */
+export interface DefTicket {
+  // #region Properties
+
+  fnId: string;
+
+  // #endregion Properties
+}
+export interface InitTicket extends DefTicket {
+  // #region Properties
+
+  fnId: typeof INIT_CALLBACK;
+
+  // #endregion Properties
+}
+export interface CallTicket extends DefTicket {
+  // #region Properties
+
+  callId: number;
+
+  // #endregion Properties
+}
+export interface CallArgsTicket extends CallTicket {
+  // #region Properties
+
+  args: any[];
+
+  // #endregion Properties
+}
+export interface ResolveTicket extends CallTicket {
+  // #region Properties
+
+  status: "resolve";
+  value: any;
+
+  // #endregion Properties
+}
+export interface RejectTicket extends CallTicket {
+  // #region Properties
+
+  error: Error;
+  status: "reject";
+
+  // #endregion Properties
+}
+export type RespondTicket = ResolveTicket | RejectTicket;
+
+export type CleanupTicket = {};
+
+export const INIT_TICKET: InitTicket = {
+  fnId: INIT_CALLBACK,
+};

package/src/tunnel/index.ts

@@ -0,0 +1 @@
+export * from "./tunnel";

package/src/tunnel/tunnel-message.ts

@@ -0,0 +1,75 @@
+import { NS_ROOT, VERSION } from "../constants";
+import { isPlainObject } from "../value-assertions";
+import { WrappedMessage, isWrapped, wrap, unwrap } from "../message-wrapper";
+import { HandshakeAcceptedTicket, HandshakeOfferedTicket } from "../tickets";
+
+type Handshake = HandshakeAcceptedTicket | HandshakeOfferedTicket;
+type HandshakeAccepted = WrappedMessage<HandshakeAcceptedTicket>;
+type HandshakeOffered = WrappedMessage<HandshakeOfferedTicket>;
+type HandshakeMessage = HandshakeAccepted | HandshakeOffered;
+
+const VERSION_WARNINGS = new Set();
+
+export function resetWarnings() {
+  VERSION_WARNINGS.clear();
+}
+
+export function makeAccepted(id: string): HandshakeAccepted {
+  return wrap({
+    accepts: id,
+    version: VERSION,
+  });
+}
+export function makeOffered(id: string): HandshakeOffered {
+  return wrap({
+    offers: id,
+    version: VERSION,
+  });
+}
+export function isHandshakeAccepting(
+  message: unknown,
+  id: string
+): message is HandshakeAccepted {
+  return (
+    isHandshake(message) && unwrap(message as HandshakeAccepted).accepts === id
+  );
+}
+export function isHandshakeOffer(
+  message: unknown
+): message is HandshakeOffered {
+  return (
+    isHandshake(message) &&
+    typeof unwrap(message as HandshakeOffered).offers === "string"
+  );
+}
+export function isHandshake(message: unknown): message is HandshakeMessage {
+  if (!isWrapped(message)) {
+    return false;
+  }
+  const tunnelData: Handshake = unwrap<Handshake>(message as HandshakeMessage);
+  if (
+    !isPlainObject(tunnelData) ||
+    typeof tunnelData.version !== "string" ||
+    !(Reflect.has(tunnelData, "accepts") || Reflect.has(tunnelData, "offers"))
+  ) {
+    console.error(
+      `malformed tunnel message, message.${NS_ROOT} must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.`
+    );
+    return false;
+  }
+  const { version } = tunnelData;
+  if (version !== VERSION && !VERSION_WARNINGS.has(version)) {
+    VERSION_WARNINGS.add(version);
+    console.warn(
+      `Version mismatch: current Tunnel is ${VERSION} and remote Tunnel is ${version}. May cause problems.`
+    );
+  }
+  return true;
+}
+
+export default {
+  makeOffered,
+  makeAccepted,
+  isHandshake,
+  resetWarnings,
+};

package/src/tunnel/tunnel.test.ts

@@ -0,0 +1,196 @@
+import { fireEvent } from "@testing-library/dom";
+import { wait } from "../promises/wait";
+import { Tunnel } from "./tunnel";
+import { makeAccepted, makeOffered } from "./tunnel-message";
+
+const defaultTunnelConfig = {
+  targetOrigin: "*",
+  timeout: 4000,
+};
+type TunnelHarness = { tunnel: Tunnel; port: MessagePort };
+const openPorts: MessagePort[] = [];
+function tunnelHarness(
+  port: MessagePort,
+  config = defaultTunnelConfig
+): TunnelHarness {
+  const tunnel = new Tunnel(config);
+  tunnel.connect(port);
+  openPorts.push(port);
+  return {
+    tunnel,
+    port,
+  };
+}
+
+async function testEventExchange(local: Tunnel, remote: Tunnel) {
+  const replyHandler = jest.fn();
+  remote.on("outgoing", replyHandler);
+  local.on("incoming", (data) => {
+    local.emit("outgoing", {
+      reply: `${data.greeting} It is I!`,
+    });
+  });
+  remote.emit("incoming", { greeting: "Who goes there?" });
+  await wait(10);
+  expect(replyHandler).toHaveBeenCalledTimes(1);
+  expect(replyHandler.mock.lastCall[0]).toMatchObject({
+    reply: "Who goes there? It is I!",
+  });
+}
+
+describe("an EventEmitter dispatching and receiving from a MessagePort", () => {
+  let local: TunnelHarness;
+  let remote: TunnelHarness;
+  beforeEach(() => {
+    const channel = new MessageChannel();
+    local = tunnelHarness(channel.port1);
+    remote = tunnelHarness(channel.port2);
+  });
+  afterEach(() => {
+    while (openPorts.length > 0) {
+      openPorts.pop().close();
+    }
+  });
+  it("receives MessageEvents and emits local events to listeners", async () => {
+    const test1Handler = jest.fn();
+    local.tunnel.on("test1", test1Handler);
+    remote.port.postMessage({
+      type: "test1",
+      payload: {
+        test1Payload: true,
+      },
+    });
+    await wait(100);
+    expect(test1Handler).toHaveBeenCalled();
+    expect(test1Handler.mock.lastCall[0]).toMatchObject({ test1Payload: true });
+  });
+  it("exchanges connect events", async () => {
+    const localConnectHandler = jest.fn();
+    const remoteConnectHandler = jest.fn();
+    local.tunnel.on("connected", localConnectHandler);
+    remote.tunnel.on("connected", remoteConnectHandler);
+    await wait(100);
+    expect(localConnectHandler).toHaveBeenCalledTimes(1);
+    expect(remoteConnectHandler).toHaveBeenCalledTimes(1);
+  });
+  it("#emitRemote() sends remote events after connect", async () => {
+    const messageListener = jest.fn();
+    remote.port.addEventListener("message", messageListener);
+    local.tunnel.emit("test2", { test2Payload: true });
+    local.tunnel.emit("test3", { test3Payload: true });
+    await wait(10);
+    expect(messageListener).toHaveBeenCalledTimes(3);
+    const connectMessageEvent = messageListener.mock.calls[0][0];
+    expect(connectMessageEvent).toHaveProperty("data", {
+      type: "connected",
+    });
+    const test2MessageEvent = messageListener.mock.calls[1][0];
+    expect(test2MessageEvent).toHaveProperty("data", {
+      type: "test2",
+      payload: {
+        test2Payload: true,
+      },
+    });
+    const test3MessageEvent = messageListener.mock.calls[2][0];
+    expect(test3MessageEvent).toHaveProperty("data", {
+      type: "test3",
+      payload: {
+        test3Payload: true,
+      },
+    });
+  });
+  it("exchanges events between two emitters sharing ports", async () => {
+    await testEventExchange(local.tunnel, remote.tunnel);
+  });
+  it("#connect(port) accepts a new messageport", async () => {
+    const connectHandler = jest.fn();
+    local.tunnel.on("connected", connectHandler);
+    remote.tunnel.on("reconnect", connectHandler);
+    const confirmHandler = jest.fn();
+    local.tunnel.on("confirm", confirmHandler);
+    const dispelHandler = jest.fn();
+    remote.tunnel.on("dispel", dispelHandler);
+    local.tunnel.emit("dispel", { dispelled: 1 });
+    remote.tunnel.emit("confirm", { confirmed: 1 });
+    await wait(10);
+    expect(confirmHandler).toHaveBeenCalledTimes(1);
+    expect(dispelHandler).toHaveBeenCalledTimes(1);
+
+    const replacementChannel = new MessageChannel();
+    local.tunnel.connect(replacementChannel.port2);
+
+    // this event should wait until remote connects port1;
+    local.tunnel.emit("dispel", { dispelled: 2 });
+
+    // this event fires on the dead port, since remote.tunnel still has it
+    remote.tunnel.emit("confirm", { confirmed: 2 });
+    await wait(10);
+    // so neither is called
+    expect(confirmHandler).toHaveBeenCalledTimes(1);
+    expect(dispelHandler).toHaveBeenCalledTimes(1);
+
+    remote.tunnel.connect(replacementChannel.port1);
+    await wait(10);
+    // dispel handler fired when port1 was opened by #reconnect
+    expect(dispelHandler).toHaveBeenCalledTimes(2);
+
+    // this dispel event should work now
+    remote.tunnel.emit("confirm", { confirmed: 3 });
+    await wait(10);
+
+    expect(confirmHandler).toHaveBeenCalledTimes(2);
+    expect(confirmHandler.mock.calls[1][0]).toMatchObject({ confirmed: 3 });
+
+    expect(connectHandler).toHaveBeenCalledTimes(2);
+    replacementChannel.port1.close();
+    replacementChannel.port2.close();
+  });
+});
+describe("static Tunnel.toIframe(iframe, options)", () => {
+  let localTunnel: Tunnel;
+  let remoteTunnel: Tunnel;
+  afterEach(() => {
+    localTunnel && localTunnel.destroy();
+    remoteTunnel && remoteTunnel.destroy();
+  });
+  /**
+   * skipped in unit tests because JSDOM's iframe and postMessage don't
+   * implement proper MessageEvents as of 2022/11/30. See
+   * https://github.com/jsdom/jsdom/blob/22f7c3c51829a6f14387f7a99e5cdf087f72e685/lib/jsdom/living/post-message.js#L31-L37
+   */
+  describe.skip("creates a Tunnel connected to an iframe", () => {
+    it.only("listens for handshakes from the frame window", async () => {
+      let remoteTunnel: Tunnel;
+      const connectMessageHandler = jest.fn();
+      const acceptListener = jest.fn();
+      const loadedFrame = document.createElement("iframe");
+      loadedFrame.src = "https://example.com:4001";
+      document.body.appendChild(loadedFrame);
+      loadedFrame.contentWindow.addEventListener("message", acceptListener);
+      const localTunnel = Tunnel.toIframe(loadedFrame, {
+        targetOrigin: "https://example.com:4001",
+        timeout: 9999,
+      });
+      localTunnel.on("connected", connectMessageHandler);
+      await wait(100);
+      fireEvent(
+        window,
+        new MessageEvent("message", {
+          data: makeOffered("iframe-test-1"),
+          origin: loadedFrame.src,
+          source: loadedFrame.contentWindow,
+        })
+      );
+      await wait(100);
+      expect(acceptListener).toHaveBeenCalled();
+      const acceptEvent = acceptListener.mock.lastCall[0];
+      expect(acceptEvent).toHaveProperty("data", makeAccepted("iframe-test-1"));
+      expect(acceptEvent.ports).toHaveLength(1);
+      remoteTunnel = new Tunnel(defaultTunnelConfig);
+      remoteTunnel.connect(acceptEvent.ports[0]);
+      await wait(100);
+      expect(connectMessageHandler).toHaveBeenCalledTimes(1);
+      await testEventExchange(localTunnel, remoteTunnel);
+    });
+  });
+});

package/src/tunnel/tunnel.ts

@@ -0,0 +1,311 @@
+import EventEmitter from "eventemitter3";
+import { isIframe, isTunnelSource } from "../value-assertions";
+import {
+  isHandshakeAccepting,
+  isHandshakeOffer,
+  makeAccepted,
+  makeOffered,
+} from "./tunnel-message";
+import { unwrap } from "../message-wrapper";
+
+/**
+ * Child iframe will send offer messages to parent at this frequency until one
+ * is accepted or the attempt times out.
+ * TODO: make configurable if ever necessary
+ */
+const RETRY_MS = 100;
+
+/**
+ * Child iframe may unexpectedly close or detach from DOM. It emits no event
+ * when this happens, so we must poll it and destroy the tunnel when necessary.
+ * TODO: make configurable if ever necessary
+ */
+const STATUSCHECK_MS = 5000;
+
+/**
+ * Semi-unique IDs allow multiple parallel connections to handshake on both parent
+ * and child iframe. This generates a semi-random 8-char base 36 string.
+ */
+const KEY_BASE = 36;
+const KEY_LENGTH = 8;
+const KEY_EXP = KEY_BASE ** KEY_LENGTH;
+const makeKey = () => Math.round(Math.random() * KEY_EXP).toString(KEY_BASE);
+
+/** @alpha */
+export interface TunnelConfig {
+  // #region Properties
+
+  /**
+   * To ensure secure communication, target origin must be specified, so the
+   * tunnel can't connect to an unauthorized domain. Can be '*' to disable
+   * origin checks, but this is discouraged!
+   */
+  targetOrigin: string;
+  /**
+   * A Promise for a tunnel will reject if not connected within timeout (ms).
+   * @defaultValue 4000
+   */
+  timeout: number;
+
+  // #endregion Properties
+}
+
+const badTimeout = "\n - timeout value must be a number of milliseconds";
+const badTargetOrigin =
+  "\n - targetOrigin must be a valid URL origin or '*' for any origin";
+
+function isFromOrigin(
+  event: MessageEvent,
+  source: WindowProxy,
+  targetOrigin: string
+) {
+  try {
+    return (
+      source === event.source &&
+      (targetOrigin === "*" || targetOrigin === new URL(event.origin).origin)
+    );
+  } catch (_) {
+    return false;
+  }
+}
+
+const { emit: emitOn } = EventEmitter.prototype;
+
+/**
+ * An EventEmitter across two documents. It emits events on the remote document
+ * and takes subscribers from the local document.
+ * @alpha
+ */
+export class Tunnel extends EventEmitter {
+  // #region Properties
+
+  private _messagePort: MessagePort;
+
+  config: TunnelConfig;
+
+  // #endregion Properties
+
+  // #region Constructors
+
+  constructor(config: TunnelConfig) {
+    super();
+    this.config = config;
+  }
+
+  // #endregion Constructors
+
+  // #region Public Static Methods
+
+  /**
+   * Create a Tunnel that connects to the page running in the provided iframe.
+   *
+   * @remarks
+   * Returns a Tunnel that listens for connection requests from the page in the
+   * provided iframe, which it will send periodically until timeout if that page
+   * has called {@link Tunnel.toParent}. If it receives one, the Tunnel will accept the
+   * connection and send an exclusive MessagePort to the xrobject on the other
+   * end. The tunnel may reconnect if the iframe reloads, in which case it will
+   * emit another "connected" event.
+   *
+   * @alpha
+   */
+  static toIframe(
+    target: HTMLIFrameElement,
+    options: Partial<TunnelConfig>
+  ): Tunnel {
+    if (!isIframe(target)) {
+      throw new Error(
+        `Provided tunnel target is not an iframe! ${Object.prototype.toString.call(
+          target
+        )}`
+      );
+    }
+    const source = target.contentWindow;
+    const config = Tunnel._normalizeConfig(options);
+    const tunnel = new Tunnel(config);
+    let frameStatusCheck: number;
+    let timeout: number;
+    const offerListener = (event: MessageEvent) => {
+      if (
+        isFromOrigin(event, source, config.targetOrigin) &&
+        isHandshakeOffer(event.data)
+      ) {
+        const accepted = makeAccepted(unwrap(event.data).offers);
+        const channel = new MessageChannel();
+        source.postMessage(accepted, config.targetOrigin, [channel.port1]);
+        tunnel.connect(channel.port2);
+      }
+    };
+    const cleanup = () => {
+      clearTimeout(timeout);
+      clearInterval(frameStatusCheck);
+      window.removeEventListener("message", offerListener);
+    };
+    timeout = window.setTimeout(() => {
+      tunnel.emitLocal(
+        "error",
+        new Error(
+          `Timed out awaiting initial message from iframe after ${config.timeout}ms`
+        )
+      );
+      tunnel.destroy();
+    }, config.timeout);
+
+    tunnel.on("destroyed", cleanup);
+    tunnel.on("connected", () => clearTimeout(timeout));
+
+    /**
+     * Check if the iframe has been unexpectedly removed from the DOM (for
+     * example, by React). Unsubscribe event listeners and destroy tunnel.
+     */
+    frameStatusCheck = window.setInterval(() => {
+      if (!target.isConnected) {
+        tunnel.destroy();
+      }
+    }, STATUSCHECK_MS);
+
+    window.addEventListener("message", offerListener);
+
+    return tunnel;
+  }
+
+  /**
+   * Create a Tunnel that connects to the page running in the parent window.
+   *
+   * @remarks
+   * Returns a Tunnel that starts sending connection requests to the parent
+   * window, sending them periodically until the window responds with an accept
+   * message or the timeout passes. The parent window will accept the request if
+   * it calls {@link Tunnel.toIframe}.
+   *
+   * @alpha
+   */
+  static toParent(source: WindowProxy, opts: Partial<TunnelConfig>): Tunnel {
+    let retrying: number;
+    let timeout: number;
+    let timedOut = false;
+    const key = makeKey();
+    const config = Tunnel._normalizeConfig(opts);
+    const tunnel = new Tunnel(config);
+    const acceptListener = (event: MessageEvent) => {
+      if (
+        !timedOut &&
+        isFromOrigin(event, source, config.targetOrigin) &&
+        isHandshakeAccepting(event.data, key)
+      ) {
+        cleanup();
+        if (!event.ports || !event.ports.length) {
+          const portError = new Error(
+            "Received handshake accept message, but it did not include a MessagePort to establish tunnel"
+          );
+          tunnel.emitLocal("error", portError);
+          return;
+        }
+        tunnel.connect(event.ports[0]);
+      }
+    };
+    const cleanup = () => {
+      clearInterval(retrying);
+      clearTimeout(timeout);
+      window.removeEventListener("message", acceptListener);
+    };
+
+    timeout = window.setTimeout(() => {
+      tunnel.emitLocal(
+        "error",
+        new Error(
+          `Timed out waiting for initial response from parent after ${config.timeout}ms`
+        )
+      );
+      tunnel.destroy();
+    }, config.timeout);
+
+    window.addEventListener("message", acceptListener);
+    tunnel.on("destroyed", cleanup);
+    tunnel.on("connected", cleanup);
+
+    const sendOffer = () =>
+      source.postMessage(makeOffered(key), config.targetOrigin);
+    retrying = window.setInterval(sendOffer, RETRY_MS);
+    sendOffer();
+
+    return tunnel;
+  }
+
+  // #endregion Public Static Methods
+
+  // #region Public Methods
+
+  connect(remote: MessagePort) {
+    if (this._messagePort) {
+      this._messagePort.removeEventListener("message", this._emitFromMessage);
+      this._messagePort.close();
+    }
+    this._messagePort = remote;
+    remote.addEventListener("message", this._emitFromMessage);
+    this.emit("connected");
+    this._messagePort.start();
+  }
+
+  destroy(): void {
+    if (this._messagePort) {
+      this._messagePort.close();
+      this._messagePort = null;
+    }
+    this.emitLocal("destroyed");
+    this.emit("destroyed");
+    // this.removeAllListeners(); // TODO: maybe necessary for memory leaks
+  }
+
+  emit(type: string | symbol, payload?: unknown): boolean {
+    if (!this._messagePort) {
+      return false;
+    }
+    this._messagePort.postMessage({ type, payload });
+    return true;
+  }
+
+  emitLocal = (type: string | symbol, payload?: unknown) => {
+    return emitOn.call(this, type, payload);
+  };
+
+  // #endregion Public Methods
+
+  // #region Private Static Methods
+
+  private static _normalizeConfig(
+    options: Partial<TunnelConfig> = {}
+  ): TunnelConfig {
+    let errorMessage = "";
+    const config: Partial<TunnelConfig> = {
+      timeout: 4000,
+      ...options,
+    };
+
+    const timeoutMs = Number(config.timeout);
+    if (!Number.isSafeInteger(timeoutMs)) {
+      errorMessage += badTimeout;
+    }
+    if (config.targetOrigin !== "*") {
+      try {
+        new URL(config.targetOrigin);
+      } catch (e) {
+        errorMessage += badTargetOrigin;
+      }
+    }
+    if (errorMessage) {
+      throw new Error(`Invalid tunnel configuration: ${errorMessage}`);
+    }
+    return config as TunnelConfig;
+  }
+
+  // #endregion Private Static Methods
+
+  // #region Private Methods
+
+  private _emitFromMessage = ({ data: { type, payload } }: MessageEvent) => {
+    this.emitLocal(type, payload);
+  };
+
+  // #endregion Private Methods
+}

package/src/types.ts

@@ -10,6 +10,8 @@ OF ANY KIND, either express or implied. See the License for the specific languag
 governing permissions and limitations under the License.
 */
 
+import { CrossRealmObject } from "./cross-realm-object";
+
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
 /**
@@ -172,11 +174,7 @@ export interface GuestConnection {
   attachUI(
     frame: HTMLIFrameElement,
     privateMethods?: RemoteHostApis
-  ): {
-    promise: Promise<unknown>;
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    destroy: Function;
-  };
+  ): Promise<unknown>;
   load(): Promise<unknown>;
   error?: Error;
   hasCapabilities(capabilities: unknown): boolean;