penpal 6.2.0

package/es5/methodSerialization.js

@@ -0,0 +1,94 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.deserializeMethods = exports.serializeMethods = exports.setAtKeyPath = void 0;
+const KEY_PATH_DELIMITER = '.';
+
+const keyPathToSegments = keyPath => keyPath ? keyPath.split(KEY_PATH_DELIMITER) : [];
+
+const segmentsToKeyPath = segments => segments.join(KEY_PATH_DELIMITER);
+
+const createKeyPath = (key, prefix) => {
+  const segments = keyPathToSegments(prefix || '');
+  segments.push(key);
+  return segmentsToKeyPath(segments);
+};
+/**
+ * Given a `keyPath`, set it to be `value` on `subject`, creating any intermediate
+ * objects along the way.
+ *
+ * @param {Object} subject The object on which to set value.
+ * @param {string} keyPath The key path at which to set value.
+ * @param {Object} value The value to store at the given key path.
+ * @returns {Object} Updated subject.
+ */
+
+
+const setAtKeyPath = (subject, keyPath, value) => {
+  const segments = keyPathToSegments(keyPath);
+  segments.reduce((prevSubject, key, idx) => {
+    if (typeof prevSubject[key] === 'undefined') {
+      prevSubject[key] = {};
+    }
+
+    if (idx === segments.length - 1) {
+      prevSubject[key] = value;
+    }
+
+    return prevSubject[key];
+  }, subject);
+  return subject;
+};
+/**
+ * Given a dictionary of (nested) keys to function, flatten them to a map
+ * from key path to function.
+ *
+ * @param {Object} methods The (potentially nested) object to serialize.
+ * @param {string} prefix A string with which to prefix entries. Typically not intended to be used by consumers.
+ * @returns {Object} An map from key path in `methods` to functions.
+ */
+
+
+exports.setAtKeyPath = setAtKeyPath;
+
+const serializeMethods = (methods, prefix) => {
+  const flattenedMethods = {};
+  Object.keys(methods).forEach(key => {
+    const value = methods[key];
+    const keyPath = createKeyPath(key, prefix);
+
+    if (typeof value === 'object') {
+      // Recurse into any nested children.
+      Object.assign(flattenedMethods, serializeMethods(value, keyPath));
+    }
+
+    if (typeof value === 'function') {
+      // If we've found a method, expose it.
+      flattenedMethods[keyPath] = value;
+    }
+  });
+  return flattenedMethods;
+};
+/**
+ * Given a map of key paths to functions, unpack the key paths to an object.
+ *
+ * @param {Object} flattenedMethods A map of key paths to functions to unpack.
+ * @returns {Object} A (potentially nested) map of functions.
+ */
+
+
+exports.serializeMethods = serializeMethods;
+
+const deserializeMethods = flattenedMethods => {
+  const methods = {};
+
+  for (const keyPath in flattenedMethods) {
+    setAtKeyPath(methods, keyPath, flattenedMethods[keyPath]);
+  }
+
+  return methods;
+};
+
+exports.deserializeMethods = deserializeMethods;

package/es5/parent/connectToChild.js

@@ -0,0 +1,107 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _enums = require("../enums");
+
+var _createDestructor = _interopRequireDefault(require("../createDestructor"));
+
+var _createLogger = _interopRequireDefault(require("../createLogger"));
+
+var _getOriginFromSrc = _interopRequireDefault(require("./getOriginFromSrc"));
+
+var _handleAckMessageFactory = _interopRequireDefault(require("./handleAckMessageFactory"));
+
+var _handleSynMessageFactory = _interopRequireDefault(require("./handleSynMessageFactory"));
+
+var _methodSerialization = require("../methodSerialization");
+
+var _monitorIframeRemoval = _interopRequireDefault(require("./monitorIframeRemoval"));
+
+var _startConnectionTimeout = _interopRequireDefault(require("../startConnectionTimeout"));
+
+var _validateIframeHasSrcOrSrcDoc = _interopRequireDefault(require("./validateIframeHasSrcOrSrcDoc"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * Attempts to establish communication with an iframe.
+ */
+var _default = options => {
+  let {
+    iframe,
+    methods = {},
+    childOrigin,
+    timeout,
+    debug = false
+  } = options;
+  const log = (0, _createLogger.default)(debug);
+  const destructor = (0, _createDestructor.default)('Parent', log);
+  const {
+    onDestroy,
+    destroy
+  } = destructor;
+
+  if (!childOrigin) {
+    (0, _validateIframeHasSrcOrSrcDoc.default)(iframe);
+    childOrigin = (0, _getOriginFromSrc.default)(iframe.src);
+  } // If event.origin is "null", the remote protocol is file: or data: and we
+  // must post messages with "*" as targetOrigin when sending messages.
+  // https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#Using_window.postMessage_in_extensions
+
+
+  const originForSending = childOrigin === 'null' ? '*' : childOrigin;
+  const serializedMethods = (0, _methodSerialization.serializeMethods)(methods);
+  const handleSynMessage = (0, _handleSynMessageFactory.default)(log, serializedMethods, childOrigin, originForSending);
+  const handleAckMessage = (0, _handleAckMessageFactory.default)(serializedMethods, childOrigin, originForSending, destructor, log);
+  const promise = new Promise((resolve, reject) => {
+    const stopConnectionTimeout = (0, _startConnectionTimeout.default)(timeout, destroy);
+
+    const handleMessage = event => {
+      if (event.source !== iframe.contentWindow || !event.data) {
+        return;
+      }
+
+      if (event.data.penpal === _enums.MessageType.Syn) {
+        handleSynMessage(event);
+        return;
+      }
+
+      if (event.data.penpal === _enums.MessageType.Ack) {
+        const callSender = handleAckMessage(event);
+
+        if (callSender) {
+          stopConnectionTimeout();
+          resolve(callSender);
+        }
+
+        return;
+      }
+    };
+
+    window.addEventListener(_enums.NativeEventType.Message, handleMessage);
+    log('Parent: Awaiting handshake');
+    (0, _monitorIframeRemoval.default)(iframe, destructor);
+    onDestroy(error => {
+      window.removeEventListener(_enums.NativeEventType.Message, handleMessage);
+
+      if (error) {
+        reject(error);
+      }
+    });
+  });
+  return {
+    promise,
+
+    destroy() {
+      // Don't allow consumer to pass an error into destroy.
+      destroy();
+    }
+
+  };
+};
+
+exports.default = _default;

package/es5/parent/getOriginFromSrc.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+const DEFAULT_PORT_BY_PROTOCOL = {
+  'http:': '80',
+  'https:': '443'
+};
+const URL_REGEX = /^(https?:)?\/\/([^/:]+)?(:(\d+))?/;
+const opaqueOriginSchemes = ['file:', 'data:'];
+/**
+ * Converts a src value into an origin.
+ */
+
+var _default = src => {
+  if (src && opaqueOriginSchemes.find(scheme => src.startsWith(scheme))) {
+    // The origin of the child document is an opaque origin and its
+    // serialization is "null"
+    // https://html.spec.whatwg.org/multipage/origin.html#origin
+    return 'null';
+  } // Note that if src is undefined, then srcdoc is being used instead of src
+  // and we can follow this same logic below to get the origin of the parent,
+  // which is the origin that we will need to use.
+
+
+  const location = document.location;
+  const regexResult = URL_REGEX.exec(src);
+  let protocol;
+  let hostname;
+  let port;
+
+  if (regexResult) {
+    // It's an absolute URL. Use the parsed info.
+    // regexResult[1] will be undefined if the URL starts with //
+    protocol = regexResult[1] ? regexResult[1] : location.protocol;
+    hostname = regexResult[2];
+    port = regexResult[4];
+  } else {
+    // It's a relative path. Use the current location's info.
+    protocol = location.protocol;
+    hostname = location.hostname;
+    port = location.port;
+  } // If the port is the default for the protocol, we don't want to add it to the origin string
+  // or it won't match the message's event.origin.
+
+
+  const portSuffix = port && port !== DEFAULT_PORT_BY_PROTOCOL[protocol] ? ":".concat(port) : '';
+  return "".concat(protocol, "//").concat(hostname).concat(portSuffix);
+};
+
+exports.default = _default;

package/es5/parent/handleAckMessageFactory.js

@@ -0,0 +1,66 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _connectCallReceiver = _interopRequireDefault(require("../connectCallReceiver"));
+
+var _connectCallSender = _interopRequireDefault(require("../connectCallSender"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * Handles an ACK handshake message.
+ */
+var _default = (serializedMethods, childOrigin, originForSending, destructor, log) => {
+  const {
+    destroy,
+    onDestroy
+  } = destructor;
+  let destroyCallReceiver;
+  let receiverMethodNames; // We resolve the promise with the call sender. If the child reconnects
+  // (for example, after refreshing or navigating to another page that
+  // uses Penpal, we'll update the call sender with methods that match the
+  // latest provided by the child.
+
+  const callSender = {};
+  return event => {
+    if (childOrigin !== '*' && event.origin !== childOrigin) {
+      log("Parent: Handshake - Received ACK message from origin ".concat(event.origin, " which did not match expected origin ").concat(childOrigin));
+      return;
+    }
+
+    log('Parent: Handshake - Received ACK');
+    const info = {
+      localName: 'Parent',
+      local: window,
+      remote: event.source,
+      originForSending: originForSending,
+      originForReceiving: childOrigin
+    }; // If the child reconnected, we need to destroy the prior call receiver
+    // before setting up a new one.
+
+    if (destroyCallReceiver) {
+      destroyCallReceiver();
+    }
+
+    destroyCallReceiver = (0, _connectCallReceiver.default)(info, serializedMethods, log);
+    onDestroy(destroyCallReceiver); // If the child reconnected, we need to remove the methods from the
+    // previous call receiver off the sender.
+
+    if (receiverMethodNames) {
+      receiverMethodNames.forEach(receiverMethodName => {
+        delete callSender[receiverMethodName];
+      });
+    }
+
+    receiverMethodNames = event.data.methodNames;
+    const destroyCallSender = (0, _connectCallSender.default)(callSender, info, receiverMethodNames, destroy, log);
+    onDestroy(destroyCallSender);
+    return callSender;
+  };
+};
+
+exports.default = _default;

package/es5/parent/handleSynMessageFactory.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _enums = require("../enums");
+
+/**
+ * Handles a SYN handshake message.
+ */
+var _default = (log, serializedMethods, childOrigin, originForSending) => {
+  return event => {
+    if (childOrigin !== '*' && event.origin !== childOrigin) {
+      log("Parent: Handshake - Received SYN message from origin ".concat(event.origin, " which did not match expected origin ").concat(childOrigin));
+      return;
+    }
+
+    log('Parent: Handshake - Received SYN, responding with SYN-ACK');
+    const synAckMessage = {
+      penpal: _enums.MessageType.SynAck,
+      methodNames: Object.keys(serializedMethods)
+    };
+    event.source.postMessage(synAckMessage, originForSending);
+  };
+};
+
+exports.default = _default;

package/es5/parent/monitorIframeRemoval.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+const CHECK_IFRAME_IN_DOC_INTERVAL = 60000;
+/**
+ * Monitors for iframe removal and destroys connection if iframe
+ * is found to have been removed from DOM. This is to prevent memory
+ * leaks when the iframe is removed from the document and the consumer
+ * hasn't called destroy(). Without this, event listeners attached to
+ * the window would stick around and since the event handlers have a
+ * reference to the iframe in their closures, the iframe would stick
+ * around too.
+ */
+
+var _default = (iframe, destructor) => {
+  const {
+    destroy,
+    onDestroy
+  } = destructor;
+  const checkIframeInDocIntervalId = setInterval(() => {
+    if (!iframe.isConnected) {
+      clearInterval(checkIframeInDocIntervalId);
+      destroy();
+    }
+  }, CHECK_IFRAME_IN_DOC_INTERVAL);
+  onDestroy(() => {
+    clearInterval(checkIframeInDocIntervalId);
+  });
+};
+
+exports.default = _default;

package/es5/parent/validateIframeHasSrcOrSrcDoc.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _enums = require("../enums");
+
+var _default = iframe => {
+  if (!iframe.src && !iframe.srcdoc) {
+    const error = new Error('Iframe must have src or srcdoc property defined.');
+    error.code = _enums.ErrorCode.NoIframeSrc;
+    throw error;
+  }
+};
+
+exports.default = _default;

package/es5/startConnectionTimeout.js

@@ -0,0 +1,30 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _enums = require("./enums");
+
+/**
+ * Starts a timeout and calls the callback with an error
+ * if the timeout completes before the stop function is called.
+ */
+var _default = (timeout, callback) => {
+  let timeoutId;
+
+  if (timeout !== undefined) {
+    timeoutId = window.setTimeout(() => {
+      const error = new Error("Connection timed out after ".concat(timeout, "ms"));
+      error.code = _enums.ErrorCode.ConnectionTimeout;
+      callback(error);
+    }, timeout);
+  }
+
+  return () => {
+    clearTimeout(timeoutId);
+  };
+};
+
+exports.default = _default;

package/es5/types.js

@@ -0,0 +1 @@
+"use strict";

package/lib/child/connectToParent.d.ts

@@ -0,0 +1,36 @@
+import { Methods, CallSender, AsyncMethodReturns } from '../types';
+declare type Options = {
+    /**
+     * Valid parent origin used to restrict communication.
+     */
+    parentOrigin?: string | RegExp;
+    /**
+     * Methods that may be called by the parent window.
+     */
+    methods?: Methods;
+    /**
+     * The amount of time, in milliseconds, Penpal should wait
+     * for the parent to respond before rejecting the connection promise.
+     */
+    timeout?: number;
+    /**
+     * Whether log messages should be emitted to the console.
+     */
+    debug?: boolean;
+};
+declare type Connection<TCallSender extends object = CallSender> = {
+    /**
+     * A promise which will be resolved once a connection has been established.
+     */
+    promise: Promise<AsyncMethodReturns<TCallSender>>;
+    /**
+     * A method that, when called, will disconnect any messaging channels.
+     * You may call this even before a connection has been established.
+     */
+    destroy: Function;
+};
+declare const _default: <TCallSender extends object = CallSender>(options?: Options) => Connection<TCallSender>;
+/**
+ * Attempts to establish communication with the parent window.
+ */
+export default _default;

package/lib/child/connectToParent.js

@@ -0,0 +1,73 @@
+import createDestructor from '../createDestructor';
+import createLogger from '../createLogger';
+import { MessageType, NativeEventType } from '../enums';
+import handleSynAckMessageFactory from './handleSynAckMessageFactory';
+import { serializeMethods } from '../methodSerialization';
+import startConnectionTimeout from '../startConnectionTimeout';
+const areGlobalsAccessible = () => {
+    try {
+        clearTimeout();
+    }
+    catch (e) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Attempts to establish communication with the parent window.
+ */
+export default (options = {}) => {
+    const { parentOrigin = '*', methods = {}, timeout, debug = false } = options;
+    const log = createLogger(debug);
+    const destructor = createDestructor('Child', log);
+    const { destroy, onDestroy } = destructor;
+    const serializedMethods = serializeMethods(methods);
+    const handleSynAckMessage = handleSynAckMessageFactory(parentOrigin, serializedMethods, destructor, log);
+    const sendSynMessage = () => {
+        log('Child: Handshake - Sending SYN');
+        const synMessage = { penpal: MessageType.Syn };
+        const parentOriginForSyn = parentOrigin instanceof RegExp ? '*' : parentOrigin;
+        window.parent.postMessage(synMessage, parentOriginForSyn);
+    };
+    const promise = new Promise((resolve, reject) => {
+        const stopConnectionTimeout = startConnectionTimeout(timeout, destroy);
+        const handleMessage = (event) => {
+            // Under niche scenarios, we get into this function after
+            // the iframe has been removed from the DOM. In Edge, this
+            // results in "Object expected" errors being thrown when we
+            // try to access properties on window (global properties).
+            // For this reason, we try to access a global up front (clearTimeout)
+            // and if it fails we can assume the iframe has been removed
+            // and we ignore the message event.
+            if (!areGlobalsAccessible()) {
+                return;
+            }
+            if (event.source !== parent || !event.data) {
+                return;
+            }
+            if (event.data.penpal === MessageType.SynAck) {
+                const callSender = handleSynAckMessage(event);
+                if (callSender) {
+                    window.removeEventListener(NativeEventType.Message, handleMessage);
+                    stopConnectionTimeout();
+                    resolve(callSender);
+                }
+            }
+        };
+        window.addEventListener(NativeEventType.Message, handleMessage);
+        sendSynMessage();
+        onDestroy((error) => {
+            window.removeEventListener(NativeEventType.Message, handleMessage);
+            if (error) {
+                reject(error);
+            }
+        });
+    });
+    return {
+        promise,
+        destroy() {
+            // Don't allow consumer to pass an error into destroy.
+            destroy();
+        },
+    };
+};

package/lib/child/handleSynAckMessageFactory.d.ts

@@ -0,0 +1,7 @@
+import { CallSender, SerializedMethods } from '../types';
+import { Destructor } from '../createDestructor';
+declare const _default: (parentOrigin: string | RegExp, serializedMethods: SerializedMethods, destructor: Destructor, log: Function) => (event: MessageEvent) => CallSender | undefined;
+/**
+ * Handles a SYN-ACK handshake message.
+ */
+export default _default;

package/lib/child/handleSynAckMessageFactory.js

@@ -0,0 +1,41 @@
+import { MessageType } from '../enums';
+import connectCallReceiver from '../connectCallReceiver';
+import connectCallSender from '../connectCallSender';
+/**
+ * Handles a SYN-ACK handshake message.
+ */
+export default (parentOrigin, serializedMethods, destructor, log) => {
+    const { destroy, onDestroy } = destructor;
+    return (event) => {
+        let originQualifies = parentOrigin instanceof RegExp
+            ? parentOrigin.test(event.origin)
+            : parentOrigin === '*' || parentOrigin === event.origin;
+        if (!originQualifies) {
+            log(`Child: Handshake - Received SYN-ACK from origin ${event.origin} which did not match expected origin ${parentOrigin}`);
+            return;
+        }
+        log('Child: Handshake - Received SYN-ACK, responding with ACK');
+        // If event.origin is "null", the remote protocol is file: or data: and we
+        // must post messages with "*" as targetOrigin when sending messages.
+        // https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#Using_window.postMessage_in_extensions
+        const originForSending = event.origin === 'null' ? '*' : event.origin;
+        const ackMessage = {
+            penpal: MessageType.Ack,
+            methodNames: Object.keys(serializedMethods),
+        };
+        window.parent.postMessage(ackMessage, originForSending);
+        const info = {
+            localName: 'Child',
+            local: window,
+            remote: window.parent,
+            originForSending,
+            originForReceiving: event.origin,
+        };
+        const destroyCallReceiver = connectCallReceiver(info, serializedMethods, log);
+        onDestroy(destroyCallReceiver);
+        const callSender = {};
+        const destroyCallSender = connectCallSender(callSender, info, event.data.methodNames, destroy, log);
+        onDestroy(destroyCallSender);
+        return callSender;
+    };
+};

package/lib/connectCallReceiver.d.ts

@@ -0,0 +1,7 @@
+import { SerializedMethods, WindowsInfo } from './types';
+declare const _default: (info: WindowsInfo, serializedMethods: SerializedMethods, log: Function) => () => void;
+/**
+ * Listens for "call" messages coming from the remote, executes the corresponding method, and
+ * responds with the return value.
+ */
+export default _default;

package/lib/connectCallReceiver.js

@@ -0,0 +1,71 @@
+import { serializeError } from './errorSerialization';
+import { MessageType, NativeEventType, NativeErrorName, Resolution, } from './enums';
+/**
+ * Listens for "call" messages coming from the remote, executes the corresponding method, and
+ * responds with the return value.
+ */
+export default (info, serializedMethods, log) => {
+    const { localName, local, remote, originForSending, originForReceiving, } = info;
+    let destroyed = false;
+    const handleMessageEvent = (event) => {
+        if (event.source !== remote || event.data.penpal !== MessageType.Call) {
+            return;
+        }
+        if (originForReceiving !== '*' && event.origin !== originForReceiving) {
+            log(`${localName} received message from origin ${event.origin} which did not match expected origin ${originForReceiving}`);
+            return;
+        }
+        const callMessage = event.data;
+        const { methodName, args, id } = callMessage;
+        log(`${localName}: Received ${methodName}() call`);
+        const createPromiseHandler = (resolution) => {
+            return (returnValue) => {
+                log(`${localName}: Sending ${methodName}() reply`);
+                if (destroyed) {
+                    // It's possible to throw an error here, but it would need to be thrown asynchronously
+                    // and would only be catchable using window.onerror. This is because the consumer
+                    // is merely returning a value from their method and not calling any function
+                    // that they could wrap in a try-catch. Even if the consumer were to catch the error,
+                    // the value of doing so is questionable. Instead, we'll just log a message.
+                    log(`${localName}: Unable to send ${methodName}() reply due to destroyed connection`);
+                    return;
+                }
+                const message = {
+                    penpal: MessageType.Reply,
+                    id,
+                    resolution,
+                    returnValue,
+                };
+                if (resolution === Resolution.Rejected &&
+                    returnValue instanceof Error) {
+                    message.returnValue = serializeError(returnValue);
+                    message.returnValueIsError = true;
+                }
+                try {
+                    remote.postMessage(message, originForSending);
+                }
+                catch (err) {
+                    // If a consumer attempts to send an object that's not cloneable (e.g., window),
+                    // we want to ensure the receiver's promise gets rejected.
+                    if (err.name === NativeErrorName.DataCloneError) {
+                        const errorReplyMessage = {
+                            penpal: MessageType.Reply,
+                            id,
+                            resolution: Resolution.Rejected,
+                            returnValue: serializeError(err),
+                            returnValueIsError: true,
+                        };
+                        remote.postMessage(errorReplyMessage, originForSending);
+                    }
+                    throw err;
+                }
+            };
+        };
+        new Promise((resolve) => resolve(serializedMethods[methodName].apply(serializedMethods, args))).then(createPromiseHandler(Resolution.Fulfilled), createPromiseHandler(Resolution.Rejected));
+    };
+    local.addEventListener(NativeEventType.Message, handleMessageEvent);
+    return () => {
+        destroyed = true;
+        local.removeEventListener(NativeEventType.Message, handleMessageEvent);
+    };
+};