PostMessage can also be used like this

In daily work, message communication is a very common scenario. For example, everyone is familiar with the B/S structure, in which the browser and the server communicate with each other based on the HTTP protocol:

However, in addition to the HTTP protocol, in some scenarios where data real-time requirements are high, we will use the WebSocket protocol to complete message communication:

I believe that everyone is familiar with these two scenarios. Next, Brother Abao will introduce another scenario of message communication, that is, how to communicate messages between the parent page and the child page loaded by the iframe.

Why did I suddenly write about this topic? Actually, it is because in a recent project, Abao needs to implement message communication between the parent page and the child page loaded by the iframe. In addition, Abao happened to be writing a special topic on source code analysis recently, so I searched on Github and found a good project - Postmate.

After reading the Postmate source code, I think some of the design ideas of the project are worth learning from, so I wrote this article to share with you. After reading this article, you will learn the following knowledge:

• The role of handshake in message systems and how to implement handshake;
• The design of message models and how to implement message verification to ensure communication security;
• The use of postMessage and how to use it to implement message communication between parent and child pages;
• Design and implementation of message communication API.

Okay, without further ado, let’s first give you a brief introduction to Postmate.

1. Introduction to Postmate

[[352432]]

Postmate is a powerful, simple, Promise-based postMessage library. It allows the parent page to communicate with the cross-domain child iframe with minimal cost. The library has the following features:

• Promise-based API for elegant and simple communication;
• Use message authentication to secure bidirectional parent <-> child message communications;
• The child object exposes a retrievable model object that the parent object can access;
• Child objects can dispatch events that their parent objects have listened to;
• The parent object can call functions in the child object;
• Zero dependencies. You can provide custom polyfills or abstractions for the Promise API if needed;
• Lightweight, about 1.6 KB (minified & gzipped).

Next, I will analyze the Postmate library from three aspects: how to perform a handshake, how to implement two-way message communication, and how to disconnect. In addition, I will also introduce some good design ideas in the Postmate project.

2. How to Handshake

When TCP establishes a connection, a three-way handshake is required. Similarly, when a parent page communicates with a child page, Postmate also uses a "handshake" to ensure that both parties can communicate normally. Because the basis of Postmate communication is based on postMessage, before introducing how to handshake, let's first take a brief look at the postMessage API.

2.1 Introduction to postMessage

For two scripts in different pages, the two scripts can only communicate with each other if the page that executes them is located on the same protocol, port number, and host. The window.postMessage() method provides a controlled mechanism to circumvent this limitation, and this method is safe as long as it is used correctly.

2.1.1 postMessage() Syntax

 otherWindow.postMessage(message, targetOrigin, [transfer]);

• otherWindow: A reference to another window, such as the contentWindow property of an iframe, the window object returned by executing window.open, etc.
• message: data to be sent to other windows, which will be serialized by the structured cloning algorithm.
• targetOrigin: Use the origin property of the window to specify which windows can receive message events. Its value can be a string "*" (indicating no restrictions) or a URI.
• transfer (optional): is a list of Transferable objects that are passed with the message. The ownership of these objects will be transferred to the recipient of the message, and the sender will no longer retain ownership.

The sender sends a message through the postMessage API, and the receiver can add a message processing callback function by listening to the message event. The specific usage is as follows:

 window.addEventListener( "message" , receiveMessage, false ); 
 
 function receiveMessage(event) {
  let origin = event.origin || event.originalEvent.origin;
  if (origin !== "http://semlinker.com" ) return ;
 }

2.2 Implementation of Postmate Handshake

In telecommunications and microprocessor systems, the term handshake has the following meanings:

• In data communications, a sequence of events managed by hardware or software that requires mutual agreement on the state of the operating mode before information can be exchanged.
• The process of establishing communication parameters between a receiving station and a sending station.

For communication systems, handshaking is the process after the communication circuit is established but before information transmission begins. Handshaking is used to agree on parameters such as information transmission rate, alphabet, parity, interrupt procedures, and other protocol features.

For the Postmate library, the handshake is to ensure that the parent page and the iframe child page can communicate normally. The corresponding handshake process is as follows:

In Postmate, the handshake message is initiated by the parent page. To initiate a handshake message in the parent page, you first need to create a Postmate object:

 const postmate = new Postmate({
 container: document.getElementById( 'some-div' ), // iframe container
 url: 'http://child.com/page.html' , // The iframe child page address containing postmate.js
 name : 'my-iframe-name' // used to set the name attribute of the iframe element
 });

In the above code, we create a postmate object by calling the Postmate constructor. There are two main steps in the Postmate constructor: setting the internal properties of the Postmate object and sending a handshake message:

The code corresponding to the above flowchart is relatively simple, so I won't post the detailed code here. Interested friends can read the relevant content in the src/postmate.js file. In order to respond to the handshake information of the parent page, we need to create a Model object in the child page:

 const model = new Postmate.Model({
  // Expose your model to the Parent. Property values ​​may be functions, promises, or regular values  
  height: () => document.height || document.body.offsetHeight
 });

The Postmate.Model constructor is defined as follows:

 // src/postmate.js
 Postmate.Model = class Model {
 constructor(model) {
 this.child = window;
 this.model = model;
    this.parent = this.child.parent;
 return this.sendHandshakeReply();
 }
 }

In the Model constructor, we can clearly see the call to the sendHandshakeReply method. Here we only look at the core code:

Now let's summarize the handshake process between the parent page and the child page: When the child page is loaded, the parent page will send a handshake message to the child page through the postMessage API. After the child page receives the handshake message, it will also use the postMessage API to reply a handshake-reply message to the parent page.

In addition, it should be noted that in order to ensure that the child page can receive the handshake handshake message, a timer will be started inside the sendHandshake method to perform the sending operation:

 // src/postmate.js
 class Postmate {
 sendHandshake(url) {
 return new Postmate.Promise((resolve, reject) => {
 const loaded = () => {
 doSend();
        responseInterval = setInterval(doSend, 500);
 }; 
 
      if (this.frame.attachEvent) {
        this.frame.attachEvent( "onload" , loaded);
 } else {
        this.frame.addEventListener( "load" , loaded);
 } 
       
 this.frame.src = url;
 });
 }
 }

Of course, in order to avoid sending too many invalid handshake messages, the maximum number of handshakes is limited inside the doSend method:

 const doSend = () => {
 attempt++;
 this.child.postMessage(
 {
 postmate: "handshake" ,
 type: messageType,
 model: this.model,
 },
 childOrigin
 );
  // const maxHandshakeRequests = 5;
  if (attempt === maxHandshakeRequests) {
     clearInterval(responseInterval);
 }
 };

After the main application and the sub-application complete the handshake, two-way message communication can be carried out. Let's learn how to implement two-way message communication.

3. How to implement two-way message communication

After calling the Postmate and Postmate.Model constructors, a Promise object is returned. When the Promise object's state changes from pending to resolved, ParentAPI and ChildAPI objects are returned respectively:

Postmate

 // src/postmate.js
 class Postmate {
 constructor({
    container = typeof container !== "undefined" ? container : document.body,
    model, url, name , classListArray = [],
 }) {
 // Omit setting the internal properties of the Postmate object
 return this.sendHandshake(url);
 } 
   
 sendHandshake(url) {
 // Omit some code
 return new Postmate.Promise((resolve, reject) => {
 const reply = (e) => {
        if (!sanitize(e, childOrigin)) return   false ;
        if (e.data.postmate === "handshake-reply" ) {
 return resolve(new ParentAPI(this));
 }
 return reject( "Failed handshake" );
 };
 });
 }
 }

ParentAPI

 class ParentAPI{
 +get(property: any ) // Get the value of the property attribute on the Model object in the subpage
 +call(property: any , data: any ) // Call the method on the Model object in the subpage
 + on (eventName: any , callback: any ) // Listen for events dispatched by subpages
 +destroy() // Remove event listener and delete iframe
 }

Postmate.Model

 // src/postmate.js
 Postmate.Model = class Model {
 constructor(model) {
 this.child = window;
 this.model = model;
    this.parent = this.child.parent;
 return this.sendHandshakeReply();
 } 
 
 sendHandshakeReply() {
 // Omit some code
 return new Postmate.Promise((resolve, reject) => {
 const shake = (e) => {
        if (e.data.postmate === "handshake" ) {
          this.child.removeEventListener( "message" , shake, false );
 return resolve(new ChildAPI(this));
 }
 return reject( "Handshake Reply Failed" );
 };
      this.child.addEventListener( "message" , shake, false );
 });
 }
 };

ChildAPI

 class ChildAPI{
  +emit( ​​name : any , data: any )
 }

3.1 Child page -> parent page

3.1.1 Subpage sends message

 const model = new Postmate.Model({
  // Expose your model to the Parent. Property values ​​may be functions, promises, or regular values  
  height: () => document.height || document.body.offsetHeight
 }); 
 
 model.then (childAPI => {
  childAPI.emit( ​​'some-event' , 'Hello, World!' );
 });

In the above code, the child page can send messages through the emit method provided by the ChildAPI object. The definition of this method is as follows:

 export class ChildAPI {
 emit( ​​name , data) {
 this.parent.postMessage(
 {
 postmate: "emit" ,
 type: messageType,
 value: {
 name ,
 data,
 },
 },
 this.parentOrigin
 );
 }
 }

3.1.2 Parent page listens to messages

 const postmate = new Postmate({
 container: document.getElementById( 'some-div' ), // iframe container
 url: 'http://child.com/page.html' , // The iframe child page address containing postmate.js
 name : 'my-iframe-name' // used to set the name attribute of the iframe element
 }); 
 
 postmate.then (parentAPI => {
  parentAPI.on ( 'some-event' , data => console.log(data)); // Logs "Hello, World!"  
 });

In the above code, the parent page can register the event handler through the on method provided by the ParentAPI object. The definition of this method is as follows:

 export class ParentAPI {
 constructor(info) {
    this.parent = info.parent;
 this.frame = info.frame;
 this.child = info.child; 
 
 this.events = {}; 
 
 this.listener = (e) => {
      if (!sanitize(e, this.childOrigin)) return   false ;
 // Omit some code
      if (e.data.postmate === "emit" ) {
 if ( name   in this.events) {
          this.events[ name ].forEach((callback) => {
            callback.call(this, data);
 });
 }
 }
 }; 
 
    this.parent.addEventListener( "message" , this.listener, false );
 } 
 
 on (eventName, callback) {
    if (!this.events[eventName]) {
      this.events[eventName] = [];
 }
    this.events[eventName].push(callback);
 }
 }

3.2 Message Verification

To ensure the security of communication, Postmate will verify the message when processing it. The corresponding verification logic is encapsulated in the sanitize method:

 const sanitize = (message, allowedOrigin) => {
  if (typeof allowedOrigin === "string" && message.origin !== allowedOrigin)
 return   false ;
 if (!message.data) return   false ;
  if (typeof message.data === "object" && !( "postmate"   in message.data))
 return   false ;
  if (message.data.type !== messageType) return   false ;
  if (!messageTypes[message.data.postmate]) return   false ;
 return   true ;
 };

The corresponding validation rules are as follows:

• Verify that the source of the message is legitimate;
• Verify whether there is a message body;
• Verify whether the message body contains the postmate attribute;
• Verify that the message type is "application/x-postmate-v1+json";
• Verify whether the message type corresponding to the postmate in the message body is legal;

The following message types are supported by Postmate:

 const messageTypes = {
 handshake: 1,
 "handshake-reply" : 1,
 call: 1,
 emit: 1,
 reply: 1,
 request: 1,
 };

In fact, to implement message verification in advance, we also need to define a standard message body model:

 {
 postmate: "emit" , // required: "request" | "call" etc.
 type: messageType, // Required: "application/x-postmate-v1+json"  
 // Custom properties
 }

After understanding how child pages communicate with parent pages and how to perform message verification, let's take a look at how parent pages communicate messages with child pages.

3.3 Parent page -> child page

3.3.1 Calling methods on subpage model objects

In the page, we can call the method on the child page model object through the call method provided by the ParentAPI object:

 export class ParentAPI {
 call(property, data) {
 this.child.postMessage(
 {
 postmate: "call" ,
 type: messageType,
 property,
 data,
 },
 this.childOrigin
 );
 }
 }

In the ChildAPI object, the call message type will be processed accordingly. The corresponding processing logic is as follows:

 export class ChildAPI {
 constructor(info) {
 // Omit some code
    this.child.addEventListener( "message" , (e) => {
      if (!sanitize(e, this.parentOrigin)) return ;
      const { property, uid, data } = e.data; 
       
 // Respond to the call message type sent by the parent page, used to call the corresponding method on the Model object
      if (e.data.postmate === "call" ) {
 if (
          property in this.model &&
          typeof this.model[property] === "function"  
 ) {
          this.model[property](data);
 }
 return ;
 }
 });
 }
 }

From the above code, we know that the call message can only be used to call the method on the sub-page Model object and cannot obtain the return value of the method call. However, in some scenarios, we need to obtain the return value of the method call. Next, let's see how ParentAPI implements this function.

3.3.2 Calling methods on subpage model objects and getting return values

If we need to get the return value after the call, we need to call the get method provided on the ParentAPI object:

 export class ParentAPI {
 get(property) {
 return new Postmate.Promise((resolve) => {
 // Get data from the response and remove the listener
      const uid = generateNewMessageId();
      const transact = (e) => {
        if (e.data.uid === uid && e.data.postmate === "reply" ) {
          this.parent.removeEventListener( "message" , transact, false );
          resolve(e.data.value);
 }
 }; 
       
 // Listen for response messages from subpages
      this.parent.addEventListener( "message" , transact, false ); 
 
 // Send a request to the subpage
 this.child.postMessage(
 {
          postmate: "request" ,
 type: messageType,
 property,
 uid,
 },
 this.childOrigin
 );
 });
 }
 }

For the request message sent by the parent page, the child page will use the resolveValue method to obtain the return result, and then return the result through postMessage:

 // src/postmate.js
 export class ChildAPI {
 constructor(info) {
    this.child.addEventListener( "message" , (e) => {
      if (!sanitize(e, this.parentOrigin)) return ;
      const { property, uid, data } = e.data; 
       
 // Respond to the request message sent by the parent page
      resolveValue(this.model, property). then ((value) =>
 e.source.postMessage(
 {
 property,
            postmate: "reply" ,
            type: messageType,
 uid,
 value,
 },
 e.origin
 )
 );
 });
 }
 }

The resolveValue method in the above code is also very simple to implement:

 const resolveValue = (model, property) => {
 const unwrappedContext =
    typeof model[property] === "function" ? model[property]() : model[property];
 return Postmate.Promise.resolve(unwrappedContext);
 };

At this point, we have introduced how Postmate performs handshakes and how to implement two-way message communication. Finally, let's introduce how to disconnect.

4. How to disconnect

When the parent page and the child page have completed the message communication, we need to disconnect. At this time, we can call the destroy method on the ParentAPI object to disconnect.

 // src/postmate.js
 export class ParentAPI {
 destroy() {
    window.removeEventListener( "message" , this.listener, false );
    this.frame.parentNode.removeChild(this.frame);
 }
 }

In this article, Abaoge uses the Postmate library as an example to introduce how to implement elegant message communication between the parent page and the iframe child page based on postMessage. If you are still not satisfied, you can read Abaoge's previous articles related to communication: How to implement message communication elegantly? and WebSocket that you don't know.

5. Reference Resources

• MDN - postMessage
• Github - postmate【Editor's recommendation】

1. Microsoft technical experts believe that SMS verification is not safe
2. Ten years of cloud computing: Great power competition and life-and-death struggle among Internet giants
3. Should programmers continue to choose computer science as their major for postgraduate entrance examination?
4. What is the difference between adding semicolons and not adding semicolons to JavaScript code?
5. Tomorrow at 1pm! A complete guide to booking for the Google Developer Conference