Communication Channel

[kpanot]

Communication Channel

The purpose of the documentation is to regroup the different requirements to be fulfilled by the Communication Solution.
This is covering the dialogs between micro-frontend modules, focused in the Iframe implementation but keeping in mind the generalization of the solution for other Micro-frontend forms (and potentially cross-app such as Browser Extensions/plugins).

Communication tool capabilities

To facilitate the implementation of a communication protocol by the different micro-frontend modules (and host), a tool should be provided.
It main goal will be to facilitate its integration in the different Web Application developed in Amadeus and to do so, it should come with the following technical requirements:

• Be published as NPM Package(s)
• Exposed a Readme.md file explaining the integration process
• Expose Angular integrator (Injectable/Module/Components)
• Expose ngAdd schematics

To avoid the applications dealing with network complexities, the communication tool should handle internally the following features:

• Communication message transport mechanism (post-message, channelApi, window events or any other)
• Serialization/deserialization of the messages
• Connection and disconnection requests (via handshake mechanism)
• Reconnection/retry in case of disconnection
• Both ways messages transportation
• Messages buffering
• Validation of the support of the message version by the receiver
• Validation of the support of the message type by the receiver
• ( ❔ ) Support multi-casting and then dedicated message

Note

Of course, any part of the process can emit events and be driven or configured by the application using the communication tooling.

Message protocol

The main purpose of the communication channel is to allow message exchange between, at least, two web applications.
To simplify the exchanges, the message should be based on a serialized JavaScript object.

A message should contain at least 3 mandatory properties (with label to be defined) listed as following:

• Version (string): SemVer following version to corresponding to the version of the message.
• Type Identification (string?): Unique identification of the type message. This identification will drive the interface of the content of the message.
• Data (any | undefined): Content of the message following interface to be shared between the 2+ actors.

Version support

Each message content its version to identify the version of the API it is following the interface.
This version is following the SemVer format but should not rely exclusively SemVer to determine backward compatibility of the message.

The version and version handling mechanism should comport the following characteristics:

• Version should be defined at API level (aligned on the NPM package version, not different per message).
  The purpose is to simplify the sub-versioning (and publishing) of the interface set (see Organization of API Definition).
• The support should be validated by the receiver
  Per default the "major breaking" strategy should be used to determine the support of the message but this mechanism should not be absolute, (see Version validation).
• Version rejection should be notified to both emitter and receiver.
  More details on Version validation.

Version validation

To facilitate the integration of Communication Channel tool, a Version validation mechanism should be integrated in the tool.
The receiver is responsible of the message version validation based on the message Type Identifier and the corresponding API version it is supported.

The validation mechanism should provide the listed features:

• Provide the possibility to configure a SemVer Range, for a set of messages, defining the range of supported version
• ( ❔ ) Reject per default a message from different different Major version (if no SemVer range provided)
• Multiple version ranges should be supported (and potentially lead to different code execution on the receiver)
• Message rejection should be notified to the sender via an Error Message (sent by the receiver(s)) and an event should be emit to the receiver (containing the original message).

Extension capability

The purpose of a message to to send information from a sender to a (or several) receiver(s).
It is then mandatory to provide the capability, for an API, to defined interfaces of messages containing:

• A unique Type Identifier for a message
• The interface of the data content of the message

Note

Additional metadata information (not part of data) may need requested by API message definition.

Unknown message

An unknown message is a message received but not recognized by the recipient.

• The message should be considered as unknown if not handled by the receiver (meaning that the Type Identifier is no considered).
• Unknown Message rejection should be notified to the sender via an Error Message (sent by the receiver(s)) and an n event should be emit to the receiver (containing the original message).

Minimum API message list to support

We can distinguish 2 different levels of messages which may need to be handled by different actors:

• Protocol Messages: messages to be handle by the Communication Channel mechanism to manage the connections.
• Feature Messages: messages dedicated to applications, components or specific services.

Note

The messages exchanged to handle IFrame micro-service constraints are considered as Feature Messages.

Protocol Messages

Messages to drive communication mechanism:

• Hand shake: initialize communication message
• disconnection: client disconnection indicating a voluntary disconnection by the client
• error: Error message sent by following a message reception covering, at least, unknown message and unsupported version.

Services/API Messages

Messages defined by Applications/Components/Services APIs.
It will depend of the implementation of the Applications/Components/Services proposing a message exchange API.

The following messages are examples of message that can handle by Otter in there dedicate packages:

Micro-frontend Messages

Messages dedicated to micro-frontend mechanism:

• Routing: Determine navigation route
• Resize: Request application container resizing

Styling Messages

Messages dedicated to theming in the modules:

• theming: Containing theming information and the CSS to apply (including mainly CSS Variable)

Package organization

To flexibilize, reduce the quantity of non-used imported code and the number of dependencies, a proposal is to split code per packages containing both features and message interfaces.

Following the previously listed messages, we could distinguish 3 packages:

• Communication Channel Package
  Exposing both protocol message interfaces and Client/Server communication tool.
• Micro-frontend Iframe handler package
  Exposing tools to handle and react to Micro-frontend requests (routing update, resize, etc...) and send command.
  Exposing tools to handle and react to Micro-frontend host requests (routing update, etc...) and send command (routing update, resize, etc...).
  Exposing Micro-frontend message interfaces handling by both Host and Client.
• Theming package
  Exposing tools to handle theming override (as message reception and initial state of the application).
  Exposing Styling message interfaces.