This package contains message definitions for the different entitites in the ARC project.
It serves as both a contract, definition and implementation for the communication between arc-control and the Desktop Application, as well as between arc-screen and the DisplayManager.
To start, make sure that your project is setup to use Airtame's private NPM repository:
echo @airtame:registry=https://gitlab.com/api/v4/packages/npm/ >> .npmrcAnd the you can simply install the library:
npm install --save @airtame/doveNote:
You will need to set up your NPM config to log onto our Gitlab instance:
npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your token>"But you should replace your token with a token that you generate here:
https://gitlab.com/profile/personal_access_tokens.
Your token should have read_api and read_repository rights to work.
Four core Messenger classes are available, which serves, in pairs, to
provide means of message passing between the different entitites in ARC.
The messages between messengers are passed by using [postMessage()] on a
Window-like object.
Predefined typed messages can be passed between the classes as shown below. The available message types are specified in Messages.ts.
DisplayManagerMessenger ↔︎ ScreenMessenger
DesktopAppMessenger ↔︎ ControlMessenger
ZoomScreenMessenger ↔︎ ZoomIframeMessenger
All Messenger classes provides the same core api.
addRequestListener(listener: (msg: ReceiveRequestType, next: NextFunction) => Promise<SendRequestType>): void
Adds a handler for the request.
The handler must return a Promise which is resolved when the request is successfully handled, rejected if an error occurs or call next() if the message received is not handled by this current handler.
removeRequestListener(listener: (msg: ReceiveRequestType, next: NextFunction) => Promise<SendRequestType>): void
Removes the listener from the list.
Adds a listener for notifications. This will be called for each notifications.
Removes the listener.
Sends a request to a receiving messenger, and returns a promise which either resolves or rejects, depending on whether the receiver handled the message or not.
If the call times out, it means that the request was either not handled, or took too long to be processed.
Dispatches a message without waiting for a confirmation of receival.
This example will be demonstrated with the (display-manager-utils)[https://gitlab.com/airtame/device/display-manager-utils] library but it could be replaced by anything else.
/***********************/
/* DESKTOP APPLICATION */
/***********************/
import {
DesktopAppMessage,
DesktopAppMessenger,
ControlMessage,
ControlMessageName,
DesktopAppMessageName,
} from '@airtame/dove';
import {
AutoReadyMessagingProxy,
PageEndpoint,
ProxyEnvelope,
Sender,
} from '@airtame/display-manager-utils';
const dmEndpoint = new PageEndpoint<
ProxyEnvelope<DesktopAppMessage, ControlMessage>
>({
sendWindow: window,
receiveWindow: window,
name: Sender.ContentScript,
peerName: Sender.Page,
});
const proxy = new AutoReadyMessagingProxy<DesktopAppMessage, ControlMessage>({
endpoint: dmEndpoint,
});
const desktopMessenger = new DesktopAppMessenger(proxy);
try {
const message = await desktopMessenger.sendRequest({
name: DesktopAppMessageName.CALL_INFO_REQUEST,
});
if (message.name === ControlMessageName.CALL_INFO_RESPONSE) {
if (message.isInCall) {
await this.leaveCall();
} else {
await this.endCall();
}
}
} catch (err) {
logger.error('Failed to get call info', { err });
} finally {
this.stop();
}
/***********/
/* CONTROL */
/***********/
import {
ControlMessenger,
ControlMessage,
DesktopAppMessage,
NextFunction,
} from '@airtame/dove';
import {
AutoReadyMessagingProxy,
PageEndpoint,
ProxyEnvelope,
Sender,
} from '@airtame/display-manager-utils';
const endpoint = new PageEndpoint<
ProxyEnvelope<ControlMessage, DesktopAppMessage>
>({
sendWindow: window.parent,
receiveWindow: window,
name: Sender.Page,
peerName: Sender.ContentScript,
});
const proxy = new AutoReadyMessagingProxy<ControlMessage, DesktopAppMessage>({
endpoint,
});
controlMessenger = new ControlMessenger(proxy);
const handleRequest = (
message: DesktopAppMessage,
next: NextFunction
): Promise<ControlMessage> => {
if (message.name === DesktopAppMessageName.CALL_INFO_REQUEST_v1) {
return Promise.resolve({
name: ControlMessageName.CALL_INFO_RESPONSE,
isInCall: meetingJoined !== -1 && meetingLeft === -1,
});
}
next();
};
controlMessenger.addRequestListener(handleRequest);A few tests are included which showcases usage of the various Messenger classes:
The versioning of messages is relatively simple: we will have the versioning made via new messages (see adr).
That means that for if a message need to be upgraded, we simply create a new message.
Here is an example:
// You are using the message to send the SDP offer:
type ControlMessages = {
name: ControlMessageName.SDP_OFFER_v1;
description: RTCSessionDescriptionJSON;
};
// All is well but now there is a new field that is useful in the new version that
// would allow you to tell the peer if this is a renewal or not. For that you need
// to create a new version of the message:
type ControlMessages =
| {
name: ControlMessageName.SDP_OFFER_v1;
description: RTCSessionDescriptionJSON;
}
| {
name: ControlMessageName.SDP_OFFER_v2;
description: RTCSessionDescriptionJSON;
renewal: boolean;
};
// In the handler, in an effort to keep backward compatibility you could have:
desktopAppMessenger.addRequestListener(
(message: ControlMessage, next: NextFunction): Promise<DesktopAppMessage> => {
switch (message.name) {
case ControlMessageName.SDP_OFFER_v2: {
if (!this.isActive) {
return Promise.reject();
}
const { description, renewal } = message;
return this.handleSDPOffer(description, renewal).then(
(descriptionResp) => {
const replyMessage: DesktopAppMessage = {
name: DesktopAppMessageName.SDP_ANSWER_v2,
description: descriptionResp,
renewal,
};
return Promise.resolve(replyMessage);
}
);
}
case ControlMessageName.SDP_OFFER_v1: {
if (!this.isActive) {
return Promise.reject();
}
const { description } = message;
return this.handleSDPOffer(
description,
true /* Imagine this would be our default in case*/
).then((descriptionResp) => {
const replyMessage: DesktopAppMessage = {
name: DesktopAppMessageName.SDP_ANSWER_v1,
description: descriptionResp,
};
return Promise.resolve(replyMessage);
});
}
default:
next();
}
}
);This would be the same for notifications and replies.
To build the library:
# Install the dependencies
npm install
# Run the build script
npm run buildAfter that you have the artifacts in the dist/ folder.
Use yalc package to publish and install
local version of @airtame/dove to another local project.
To install yalc globally, run:
npm i -g yalcTo publish, first build the changes, then run:
npx yalc publishThen inside another project run:
npx yalc install @airtame/doveTo create a release, you need to update related files, merge changes into
master branch and create a tag from master named as version number prefixed
with v as follows: v1.2.3.
To update related files run the following command:
npm run release:prepare [major | minor | patch]Then push to remote, review and merge the changes.
After that switch back to master, pull the latest changes, and create a tag:
git checkout master
git pull --rebase
git tag v1.2.3
git push origin v1.2.3