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

package/src/tunnel/tunnel.ts

@@ -0,0 +1,322 @@
+import EventEmitter from "eventemitter3";
+import { isIframe } from "../value-assertions";
+import { TunnelMessenger } from "./tunnel-messenger";
+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;
+  /**
+   * Logger instance to use for debugging tunnel connection.
+   */
+  logger: Console;
+
+  // #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);
+    const messenger = new TunnelMessenger({
+      myOrigin: window.location.origin,
+      targetOrigin: options.targetOrigin,
+      logger: options.logger || console,
+    });
+    let frameStatusCheck: number;
+    let timeout: number;
+    const offerListener = (event: MessageEvent) => {
+      if (
+        isFromOrigin(event, source, config.targetOrigin) &&
+        messenger.isHandshakeOffer(event.data)
+      ) {
+        const accepted = messenger.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 messenger = new TunnelMessenger({
+      myOrigin: window.location.origin,
+      targetOrigin: config.targetOrigin,
+      logger: config.logger,
+    });
+    const acceptListener = (event: MessageEvent) => {
+      if (
+        !timedOut &&
+        isFromOrigin(event, source, config.targetOrigin) &&
+        messenger.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(messenger.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,
+      logger: console,
+      ...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;

package/src/value-assertions.ts

@@ -0,0 +1,58 @@
+/** @internal */
+export type Primitive = string | number | boolean;
+
+export function isPlainObject<T>(value: unknown): value is T & object {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const proto = Reflect.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+export function isPrimitive(value: unknown): value is Primitive {
+  if (!value) {
+    return true;
+  }
+  const theType = typeof value;
+  return theType === "string" || theType === "number" || theType === "boolean";
+}
+
+export function isIterable<T>(value: unknown): value is T[] {
+  return Array.isArray(value);
+}
+
+export function isFunction(value: unknown): value is CallableFunction {
+  return typeof value === "function";
+}
+
+export function hasProp(value: unknown, prop: string) {
+  return !isPrimitive(value) && Reflect.has(value as object, prop);
+}
+
+export function isTunnelSource(
+  value: unknown
+): value is Window | ServiceWorker {
+  return (
+    value instanceof Window ||
+    value instanceof ServiceWorker ||
+    hasProp(value, "onmessage")
+  );
+}
+
+export function isIframe(value: unknown): value is HTMLIFrameElement {
+  if (!value || isPrimitive(value)) {
+    return false;
+  }
+  const { nodeName } = value as HTMLIFrameElement;
+  return typeof nodeName === "string" && nodeName.toLowerCase() === "iframe";
+}
+
+export function isObjectWithPrototype<T>(
+  value: unknown
+): value is T & { [key: string | symbol]: unknown } {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const proto = Reflect.getPrototypeOf(value);
+  return proto !== Object.prototype;
+}

package/tsconfig.json

@@ -5,10 +5,6 @@
     "outDir": "dist",
     "rootDir": "src"
   },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "src/**/*.test.tsx?"
-  ]
+  "include": ["src/**/*"],
+  "exclude": ["src/**/*.test.tsx?"]
 }

package/dist/timeout-promise.d.ts

@@ -1,12 +0,0 @@
-/**
- * Add a timeout to a Promise. The returned Promise will resolve to the value of
- * the original Promise, but if it doesn't resolve within the timeout interval,
- * it will reject with a timeout error.
- * @internal
- *
- * @param timeoutMs - Time to wait (ms) before rejecting
- * @param promise - Original promise to set a timeout for
- * @returns - Promise that rejects after X milliseconds have passed
- */
-export declare function timeoutPromise<T>(timeoutMs: number, promise: Promise<T>): Promise<unknown>;
-//# sourceMappingURL=timeout-promise.d.ts.map

package/dist/timeout-promise.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"timeout-promise.d.ts","sourceRoot":"","sources":["../src/timeout-promise.ts"],"names":[],"mappings":"AAYA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,oBAavE"}

package/src/timeout-promise.ts

@@ -1,36 +0,0 @@
-/*
-Copyright 2022 Adobe. All rights reserved.
-This file is licensed to you under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License. You may obtain a copy
-of the License at http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed under
-the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
-OF ANY KIND, either express or implied. See the License for the specific language
-governing permissions and limitations under the License.
-*/
-
-/**
- * Add a timeout to a Promise. The returned Promise will resolve to the value of
- * the original Promise, but if it doesn't resolve within the timeout interval,
- * it will reject with a timeout error.
- * @internal
- *
- * @param timeoutMs - Time to wait (ms) before rejecting
- * @param promise - Original promise to set a timeout for
- * @returns - Promise that rejects after X milliseconds have passed
- */
-export function timeoutPromise<T>(timeoutMs: number, promise: Promise<T>) {
-  return new Promise((resolve, reject) => {
-    const timeout = setTimeout(
-      () => reject(new Error(`Timed out after ${timeoutMs}ms`)),
-      timeoutMs
-    );
-    promise
-      .then((result) => {
-        clearTimeout(timeout);
-        resolve(result);
-      })
-      .catch(reject);
-  });
-}