@adobe/uix-core 0.6.5 → 0.7.1-nightly.20230114

package/src/tunnel/tunnel-messenger.test.ts

@@ -0,0 +1,183 @@
+import { NS_ROOT, VERSION } from "../constants";
+import { TunnelMessenger } from "./tunnel-messenger";
+
+const fakeConsole = {
+  error: jest.fn(),
+  warn: jest.fn(),
+} as unknown as jest.Mocked<Console>;
+
+describe("tunnel negotiation message factory", () => {
+  let messenger: TunnelMessenger;
+  beforeEach(() => {
+    messenger = new TunnelMessenger({
+      myOrigin: "https://me",
+      targetOrigin: "https://you",
+      logger: fakeConsole,
+    });
+    jest.clearAllMocks();
+  });
+  afterAll(() => {
+    jest.restoreAllMocks();
+  });
+  it("makeAccepted", () => {
+    expect(messenger.makeAccepted("test1")).toMatchObject({
+      [NS_ROOT]: {
+        accepts: "test1",
+        version: VERSION,
+      },
+    });
+  });
+  it("makeOffered", () => {
+    expect(messenger.makeOffered("test1")).toMatchObject({
+      [NS_ROOT]: {
+        offers: "test1",
+        version: VERSION,
+      },
+    });
+  });
+  it("isHandshakeOffer", () => {
+    expect(
+      messenger.isHandshakeOffer({
+        [NS_ROOT]: {
+          offers: "test2",
+          version: VERSION,
+        },
+      })
+    ).toBeTruthy();
+    expect(
+      messenger.isHandshakeOffer({
+        [NS_ROOT]: {
+          accepts: "test2",
+          version: VERSION,
+        },
+      })
+    ).toBeFalsy();
+    expect(messenger.isHandshakeOffer({})).toBeFalsy();
+  });
+  it("isHandshakeAccepting(message, id) matches on id", () => {
+    expect(
+      messenger.isHandshakeAccepting(
+        {
+          [NS_ROOT]: {
+            accepts: "test3",
+            version: VERSION,
+          },
+        },
+        "test3"
+      )
+    ).toBeTruthy();
+    expect(
+      messenger.isHandshakeAccepting(
+        {
+          accepts: "test3",
+          version: VERSION,
+        },
+        "mismatch"
+      )
+    ).toBeFalsy();
+    expect(messenger.isHandshakeAccepting({}, "test3")).toBeFalsy();
+  });
+  describe("isHandshake rejects malformed messages", () => {
+    it("non-plain-objects", () => {
+      expect(messenger.isHandshake([])).toBeFalsy();
+      expect(messenger.isHandshake("")).toBeFalsy();
+      expect(messenger.isHandshake(true)).toBeFalsy();
+      expect(fakeConsole.error).toHaveBeenCalledTimes(3);
+      expect(fakeConsole.error.mock.calls.map(([msg]) => msg))
+        .toMatchInlineSnapshot(`
+        [
+          "Malformed tunnel message sent from SDK at https://you to https://me:
+        []
+        Message must be an object with "_$pg" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.",
+          "Malformed tunnel message sent from SDK at https://you to https://me:
+        ""
+        Message must be an object with "_$pg" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.",
+          "Malformed tunnel message sent from SDK at https://you to https://me:
+        true
+        Message must be an object with "_$pg" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.",
+        ]
+      `);
+    });
+    it("without a sub-object at the expected root property", () => {
+      expect(
+        messenger.isHandshakeOffer({
+          someOtherRoot: false,
+        })
+      ).toBeFalsy();
+      expect(
+        messenger.isHandshake({
+          [NS_ROOT]: 5,
+        })
+      ).toBeFalsy();
+      expect(fakeConsole.error.mock.calls.map(([msg]) => msg))
+        .toMatchInlineSnapshot(`
+        [
+          "Malformed tunnel message sent from SDK at https://you to https://me:
+        {
+          "someOtherRoot": false
+        }
+        Message must be an object with "_$pg" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.",
+          "Malformed tunnel message sent from SDK at https://you to https://me:
+        {
+          "_$pg": 5
+        }
+        Message must be an object with "_$pg" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.",
+        ]
+      `);
+    });
+    it("without accept or offers properties", () => {
+      expect(
+        messenger.isHandshake({
+          [NS_ROOT]: {
+            version: VERSION,
+          },
+        })
+      ).toBeFalsy();
+    });
+    it("with no version string", () => {
+      expect(
+        messenger.isHandshake({
+          [NS_ROOT]: {
+            offers: "test4",
+          },
+        })
+      ).toBeFalsy();
+    });
+  });
+  describe("version mismatch handling", () => {
+    const withVersion = (version: string) => ({
+      [NS_ROOT]: {
+        offers: "test5",
+        version,
+      },
+    });
+    it("warns in console, once for each version", () => {
+      expect(messenger.isHandshake(withVersion("bad-version"))).toBeTruthy();
+      expect(messenger.isHandshake(withVersion("worse-version"))).toBeTruthy();
+      expect(messenger.isHandshake(withVersion("bad-version"))).toBeTruthy();
+      expect(fakeConsole.warn).toHaveBeenCalledTimes(2);
+      expect(fakeConsole.warn.mock.calls.map(([msg]) => msg))
+        .toMatchInlineSnapshot(`
+        [
+          "SDK version mismatch. https://me is using v0.0.1-test, but received message from https://you using SDK vbad-version. Extensions may be broken or unresponsive.",
+          "SDK version mismatch. https://me is using v0.0.1-test, but received message from https://you using SDK vworse-version. Extensions may be broken or unresponsive.",
+        ]
+      `);
+    });
+    it("resetWarnings() resets seen version warnings so they'll log again", () => {
+      messenger.resetWarnings();
+      expect(
+        messenger.isHandshake(withVersion("same-bad-version"))
+      ).toBeTruthy();
+      expect(
+        messenger.isHandshake(withVersion("same-bad-version"))
+      ).toBeTruthy();
+      expect(fakeConsole.warn).toHaveBeenCalledTimes(1);
+      messenger.resetWarnings();
+      expect(
+        messenger.isHandshake(withVersion("same-bad-version"))
+      ).toBeTruthy();
+      expect(fakeConsole.warn).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/tunnel/tunnel-messenger.ts

@@ -0,0 +1,99 @@
+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;
+
+export class TunnelMessenger {
+  private myOrigin: string;
+  private remoteOrigin: string;
+  private logger: Console;
+  private versionWarnings = new Set<string>();
+  constructor(opts: {
+    myOrigin: string;
+    targetOrigin: string;
+    logger: Console;
+  }) {
+    this.myOrigin = opts.myOrigin;
+    this.remoteOrigin =
+      opts.targetOrigin === "*" ? "remote document" : opts.targetOrigin;
+    this.logger = opts.logger;
+  }
+  resetWarnings() {
+    this.versionWarnings.clear();
+  }
+
+  makeAccepted(id: string): HandshakeAccepted {
+    return wrap({
+      accepts: id,
+      version: VERSION,
+    });
+  }
+  makeOffered(id: string): HandshakeOffered {
+    return wrap({
+      offers: id,
+      version: VERSION,
+    });
+  }
+  isHandshakeAccepting(
+    message: unknown,
+    id: string
+  ): message is HandshakeAccepted {
+    return (
+      this.isHandshake(message) &&
+      unwrap(message as HandshakeAccepted).accepts === id
+    );
+  }
+  isHandshakeOffer(message: unknown): message is HandshakeOffered {
+    return (
+      this.isHandshake(message) &&
+      typeof unwrap(message as HandshakeOffered).offers === "string"
+    );
+  }
+  isHandshake(message: unknown): message is HandshakeMessage {
+    if (!isWrapped(message)) {
+      this.logMalformed(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"))
+    ) {
+      this.logMalformed(message);
+      return false;
+    }
+    const { version } = tunnelData;
+    if (version !== VERSION && !this.versionWarnings.has(version)) {
+      this.versionWarnings.add(version);
+      this.logger.warn(
+        `SDK version mismatch. ${this.myOrigin} is using v${VERSION}, but received message from ${this.remoteOrigin} using SDK v${version}. Extensions may be broken or unresponsive.`
+      );
+    }
+    return true;
+  }
+  private logMalformed(message: unknown) {
+    let inspectedMessage: string;
+    try {
+      inspectedMessage = JSON.stringify(message, null, 2);
+    } catch (_) {
+      try {
+        inspectedMessage = message.toString();
+      } catch (e) {
+        inspectedMessage = Object.prototype.toString.call(message);
+      }
+    }
+    this.logger.error(
+      `Malformed tunnel message sent from SDK at ${this.remoteOrigin} to ${this.myOrigin}:
+${inspectedMessage}
+Message must be an object with "${NS_ROOT}" property, which must be an object with a "version" string and an either an "accepts" or "offers" property containing an ID string.`
+    );
+  }
+}

package/src/tunnel/tunnel.test.ts

@@ -0,0 +1,211 @@
+import { fireEvent } from "@testing-library/dom";
+import { wait } from "../promises/wait";
+import { Tunnel } from "./tunnel";
+import { TunnelMessenger } from "./tunnel-messenger";
+
+const fakeConsole = {
+  error: jest.fn(),
+  warn: jest.fn(),
+} as unknown as jest.Mocked<Console>;
+
+const defaultTunnelConfig = {
+  targetOrigin: "*",
+  timeout: 4000,
+  logger: fakeConsole,
+};
+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 targetOrigin = "https://example.com:4001";
+      const loadedFrame = document.createElement("iframe");
+      loadedFrame.src = targetOrigin;
+      document.body.appendChild(loadedFrame);
+      loadedFrame.contentWindow.addEventListener("message", acceptListener);
+      const localTunnel = Tunnel.toIframe(loadedFrame, {
+        targetOrigin,
+        timeout: 9999,
+      });
+      const messenger = new TunnelMessenger({
+        myOrigin: "https://example.com",
+        targetOrigin,
+        logger: fakeConsole,
+      });
+      localTunnel.on("connected", connectMessageHandler);
+      await wait(100);
+      fireEvent(
+        window,
+        new MessageEvent("message", {
+          data: messenger.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",
+        messenger.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);
+    });
+  });
+});