feat(messaging): support nested iframes by tagging messages with dire…

…ction Cross-frame messages are now tagged as `HostToClient` or `ClientToHost` so that a frame running both host and client code will not try to incorrectly process messages intended for the host code with the client code and vice-versa.
purecloudlabs · Aug 3, 2020 · 00d2cbf · 00d2cbf
1 parent 87f87a3
commit 00d2cbf
Show file tree

Hide file tree

Showing 8 changed files with 227 additions and 56 deletions.
diff --git a/src/FrameManager.ts b/src/FrameManager.ts
@@ -2,8 +2,15 @@ import {
   ClientToHost,
   validate as validateIncoming
 } from './messages/ClientToHost';
-import { validate as validateOutgoing } from './messages/HostToClient';
-import { API_PROTOCOL, PartialMsg } from './messages/LabeledMsg';
+import {
+  HostToClient,
+  validate as validateOutgoing
+} from './messages/HostToClient';
+import {
+  API_PROTOCOL,
+  applyHostProtocol,
+  PartialMsg
+} from './messages/LabeledMsg';
 
 /** @external */
 const IFRAME_STYLE = `
@@ -140,10 +147,11 @@ class FrameManager {
    *
    * @param message The message to send.
    */
-  public sendToClient<T, V>(message: PartialMsg<T, V>) {
+  public sendToClient<T, V>(partialMsg: PartialMsg<T, V>) {
     const clientOrigin = this._expectedClientOrigin();
     if (this._iframe.contentWindow && clientOrigin) {
-      let validated = null;
+      const message = applyHostProtocol(partialMsg);
+      let validated: HostToClient;
 
       try {
         validated = validateOutgoing(message);
@@ -188,6 +196,10 @@ to bad data passed to a frame-router method.
   private _handlePostMessage(handler: MessageHandler, event: MessageEvent) {
     let validated = null;
 
+    if (event.data && event.data.direction === 'HostToClient') {
+      return;
+    }
+
     try {
       validated = validateIncoming(event.data);
     } catch (e) {

diff --git a/src/client.ts b/src/client.ts
@@ -9,7 +9,11 @@ import {
   HostToClient,
   validate as validateIncoming
 } from './messages/HostToClient';
-import { API_PROTOCOL, applyProtocol, PartialMsg } from './messages/LabeledMsg';
+import {
+  API_PROTOCOL,
+  applyClientProtocol,
+  PartialMsg
+} from './messages/LabeledMsg';
 import {
   EnvData,
   EnvDataHandler,
@@ -102,6 +106,10 @@ export class Client {
   private _onWindowMessage = (event: MessageEvent) => {
     let validated = null;
 
+    if (event.data && event.data.direction === 'ClientToHost') {
+      return;
+    }
+
     try {
       validated = validateIncoming(event.data);
     } catch (e) {
@@ -230,8 +238,9 @@ export class Client {
   }
 
   private _sendToHost<T, V>(partialMsg: PartialMsg<T, V>): void {
-    const message = applyProtocol(partialMsg);
-    let validated = null;
+    const message = applyClientProtocol(partialMsg);
+
+    let validated: ClientToHost;
 
     try {
       validated = validateOutgoing(message);

diff --git a/src/messages/LabeledMsg.ts b/src/messages/LabeledMsg.ts
@@ -5,6 +5,7 @@ import {
   hardcoded,
   map,
   object,
+  optional,
   string
 } from 'decoders';
 
@@ -20,6 +21,12 @@ const version = require('../../package.json').version;
  */
 export const API_PROTOCOL = 'iframe-coordinator';
 
+/**
+ * Based on MessageDirection, hosts and clients can ignore messages that are not targeted at them.
+ * @external
+ */
+export type MessageDirection = 'ClientToHost' | 'HostToClient';
+
 /**
  * Labeled message is a general structure
  * used by all coordinated messages between
@@ -35,6 +42,8 @@ export interface LabeledMsg<T, V> extends PartialMsg<T, V> {
   protocol: 'iframe-coordinator';
   /** library version */
   version: string;
+  /** So that nested iframe-coordinators can ignore messages that don't apply */
+  direction?: MessageDirection;
 }
 
 /**
@@ -50,25 +59,36 @@ export interface PartialMsg<T, V> {
 
 /**
  * Takes an object with a `msgType` and `msg` and applies the appropriate
- * `protocol` and `version` fields for the current version of the library.
+ * `direction`, `protocol` and `version` fields for the current version of the library.
  * @param partialMsg
  * @external
  */
-export function applyProtocol<T, V>(
+export function applyClientProtocol<T, V>(
   partialMsg: PartialMsg<T, V>
 ): LabeledMsg<T, V> {
-  return { ...partialMsg, protocol: API_PROTOCOL, version };
+  return {
+    direction: 'ClientToHost',
+    ...partialMsg,
+    protocol: API_PROTOCOL,
+    version
+  };
 }
 
 /**
- * Converts a PartialMsg decoder into a LabeledMsg decoder
- * @param msgDecoder
+ * Takes an object with a `msgType` and `msg` and applies the appropriate
+ * `direction`, `protocol` and `version` fields for the current version of the library.
+ * @param partialMsg
  * @external
  */
-export function labeledDecoder2<T, V>(
-  msgDecoder: Decoder<PartialMsg<T, V>>
-): Decoder<LabeledMsg<T, V>> {
-  return map(msgDecoder, applyProtocol);
+export function applyHostProtocol<T, V>(
+  partialMsg: PartialMsg<T, V>
+): LabeledMsg<T, V> {
+  return {
+    direction: 'HostToClient',
+    ...partialMsg,
+    protocol: API_PROTOCOL,
+    version
+  };
 }
 
 /**
@@ -81,13 +101,19 @@ export function labeledDecoder<T, V>(
   msgDecoder: Decoder<V>
 ): Decoder<LabeledMsg<T, V>> {
   return object({
-    // TODO: in 4.0.0 make protocol and verison fields mandatory
+    // TODO: in 4.0.0 make protocol and version fields mandatory
     protocol: either(
       constant<'iframe-coordinator'>(API_PROTOCOL),
       hardcoded<'iframe-coordinator'>(API_PROTOCOL)
     ),
     version: either(string, hardcoded('unknown')),
     msgType: typeDecoder,
-    msg: msgDecoder
+    msg: msgDecoder,
+    direction: optional(directionDecoder)
   });
 }
+
+const directionDecoder: Decoder<MessageDirection, unknown> = either(
+  constant('ClientToHost'),
+  constant('HostToClient')
+);
diff --git a/src/messages/Lifecycle.ts b/src/messages/Lifecycle.ts
@@ -8,7 +8,7 @@ import {
   optional,
   string
 } from 'decoders';
-import { applyProtocol, labeledDecoder, LabeledMsg } from './LabeledMsg';
+import { applyClientProtocol, labeledDecoder, LabeledMsg } from './LabeledMsg';
 
 /**
  * Client started indication.  The client will
@@ -118,7 +118,7 @@ export class Lifecycle {
    * A {@link LabeledStarted} message to send to the host application.
    */
   public static get startedMessage(): LabeledStarted {
-    return applyProtocol({
+    return applyClientProtocol({
       msgType: 'client_started',
       msg: undefined
     });

diff --git a/src/messages/specs/ClientToHost.spec.ts b/src/messages/specs/ClientToHost.spec.ts
@@ -35,7 +35,8 @@ describe('ClientToHost', () => {
       const expectedMessage = withClientId({
         ...testMessage,
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       }) as LabeledPublication;
 
       let testResult: ClientToHost;
@@ -60,7 +61,8 @@ describe('ClientToHost', () => {
       const expectedMessage = withClientId({
         ...testMessage,
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       });
 
       let testResult: ClientToHost;
@@ -103,7 +105,8 @@ describe('ClientToHost', () => {
           clientId: undefined
         },
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       } as ClientToHost;
 
       let testResult: ClientToHost;
@@ -134,7 +137,8 @@ describe('ClientToHost', () => {
           custom: undefined
         },
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       };
 
       let testResult: ClientToHost;
@@ -164,7 +168,8 @@ describe('ClientToHost', () => {
           custom: undefined
         },
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       };
 
       let testResult: ClientToHost;
@@ -190,7 +195,8 @@ describe('ClientToHost', () => {
       const expectedMessage: ClientToHost = {
         ...testMessage,
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       } as LabeledNotification;
 
       let testResult: ClientToHost;
@@ -233,7 +239,8 @@ describe('ClientToHost', () => {
         ...toastMessage,
         msgType: 'notifyRequest',
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       } as LabeledNotification;
 
       expect(validate(toastMessage)).toEqual(expectedMessage);
@@ -252,7 +259,8 @@ describe('ClientToHost', () => {
       const expectedMessage = {
         ...testMessage,
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       } as LabeledNavRequest;
 
       let testResult: ClientToHost;

diff --git a/src/messages/specs/HostToClient.spec.ts b/src/messages/specs/HostToClient.spec.ts
@@ -1,5 +1,5 @@
 import { HostToClient, validate } from '../HostToClient';
-import { applyProtocol } from '../LabeledMsg';
+import { applyClientProtocol } from '../LabeledMsg';
 
 describe('HostToClient', () => {
   describe('validating an invalid message type', () => {
@@ -17,7 +17,7 @@ describe('HostToClient', () => {
 
   describe('validating publish type', () => {
     describe('when payload is a string', () => {
-      const testMessage: HostToClient = applyProtocol({
+      const testMessage: HostToClient = applyClientProtocol({
         msgType: 'publish',
         msg: {
           topic: 'test.topic',
@@ -30,7 +30,7 @@ describe('HostToClient', () => {
       });
       it('should return the validated message', () => {
         expect(testResult).toEqual(
-          applyProtocol({
+          applyClientProtocol({
             msgType: 'publish',
             msg: { ...testMessage.msg, clientId: undefined }
           })
@@ -39,7 +39,7 @@ describe('HostToClient', () => {
     });
 
     describe('when payload is an object', () => {
-      const testMessage: HostToClient = applyProtocol({
+      const testMessage: HostToClient = applyClientProtocol({
         msgType: 'publish',
         msg: {
           topic: 'test.topic',
@@ -52,7 +52,7 @@ describe('HostToClient', () => {
       });
       it('should return the validated message', () => {
         expect(testResult).toEqual(
-          applyProtocol({
+          applyClientProtocol({
             msgType: 'publish',
             msg: { ...testMessage.msg, clientId: undefined }
           })
@@ -90,7 +90,8 @@ describe('HostToClient', () => {
           clientId: undefined
         },
         protocol: 'iframe-coordinator',
-        version: 'unknown'
+        version: 'unknown',
+        direction: undefined
       };
 
       let testResult: HostToClient;
@@ -105,7 +106,7 @@ describe('HostToClient', () => {
 
   describe('validating env_init type', () => {
     describe('when given a proper environmental data payload', () => {
-      const testMessage: HostToClient = applyProtocol({
+      const testMessage: HostToClient = applyClientProtocol({
         msgType: 'env_init',
         msg: {
           locale: 'nl-NL',
@@ -118,7 +119,7 @@ describe('HostToClient', () => {
       it('should return the validated message', () => {
         const testResult = validate(testMessage);
         expect(testResult).toEqual(
-          applyProtocol({
+          applyClientProtocol({
             msgType: 'env_init',
             msg: {
               ...testMessage.msg,
@@ -130,7 +131,7 @@ describe('HostToClient', () => {
     });
 
     describe('when given a proper environmental data payload including custom data', () => {
-      const testMessage: HostToClient = applyProtocol({
+      const testMessage: HostToClient = applyClientProtocol({
         msgType: 'env_init',
         msg: {
           locale: 'nl-NL',
@@ -147,7 +148,7 @@ describe('HostToClient', () => {
         testResult = validate(testMessage);
       });
       it('should return the validated message', () => {
-        expect(testResult).toEqual(applyProtocol(testMessage));
+        expect(testResult).toEqual(applyClientProtocol(testMessage));
       });
     });