superset-frontend/packages/superset-ui-switchboard/src/switchboard.ts
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
export type Params = {
port: MessagePort;
name?: string;
debug?: boolean;
};
// Each message we send on the channel specifies an action we want the other side to cooperate with.
enum Actions {
GET = 'get',
REPLY = 'reply',
EMIT = 'emit',
ERROR = 'error',
}
type Method<A extends {}, R> = (args: A) => R | Promise<R>;
// helper types/functions for making sure wires don't get crossed
interface Message {
switchboardAction: Actions;
}
interface GetMessage<T = any> extends Message {
switchboardAction: Actions.GET;
method: string;
messageId: string;
args: T;
}
function isGet(message: Message): message is GetMessage {
return message.switchboardAction === Actions.GET;
}
interface ReplyMessage<T = any> extends Message {
switchboardAction: Actions.REPLY;
messageId: string;
result: T;
}
function isReply(message: Message): message is ReplyMessage {
return message.switchboardAction === Actions.REPLY;
}
interface EmitMessage<T = any> extends Message {
switchboardAction: Actions.EMIT;
method: string;
args: T;
}
function isEmit(message: Message): message is EmitMessage {
return message.switchboardAction === Actions.EMIT;
}
interface ErrorMessage extends Message {
switchboardAction: Actions.ERROR;
messageId: string;
error: string;
}
function isError(message: Message): message is ErrorMessage {
return message.switchboardAction === Actions.ERROR;
}
/**
* A utility for communications between an iframe and its parent, used by the Superset embedded SDK.
* This builds useful patterns on top of the basic functionality offered by MessageChannel.
*
* Both windows instantiate a Switchboard, passing in their MessagePorts.
* Calling methods on the switchboard causes messages to be sent through the channel.
*/
export class Switchboard {
port: MessagePort;
name = '';
methods: Record<string, Method<any, unknown>> = {};
// used to make unique ids
incrementor = 1;
debugMode: boolean;
private isInitialised: boolean;
constructor(params?: Params) {
if (!params) {
return;
}
this.init(params);
}
init(params: Params) {
if (this.isInitialised) {
this.logError('already initialized');
return;
}
const { port, name = 'switchboard', debug = false } = params;
this.port = port;
this.name = name;
this.debugMode = debug;
port.addEventListener('message', async event => {
this.log('message received', event);
const message = event.data;
if (isGet(message)) {
// find the method, call it, and reply with the result
this.port.postMessage(await this.getMethodResult(message));
} else if (isEmit(message)) {
const { method, args } = message;
// Find the method and call it, but no result necessary.
// Should this multicast to a set of listeners?
// Maybe, but that requires writing a bunch more code
// and I haven't found a need for it yet.
const executor = this.methods[method];
if (executor) {
executor(args);
}
}
});
this.isInitialised = true;
}
private async getMethodResult({
messageId,
method,
args,
}: GetMessage): Promise<ReplyMessage | ErrorMessage> {
const executor = this.methods[method];
if (executor == null) {
return <ErrorMessage>{
switchboardAction: Actions.ERROR,
messageId,
error: `[${this.name}] Method "${method}" is not defined`,
};
}
try {
const result = await executor(args);
return <ReplyMessage>{
switchboardAction: Actions.REPLY,
messageId,
result,
};
} catch (err) {
this.logError(err);
return <ErrorMessage>{
switchboardAction: Actions.ERROR,
messageId,
error: `[${this.name}] Method "${method}" threw an error`,
};
}
}
/**
* Defines a method that can be "called" from the other side by sending an event.
*/
defineMethod<A extends {}, R = any>(
methodName: string,
executor: Method<A, R>,
) {
this.methods[methodName] = executor;
}
/**
* Calls a method registered on the other side, and returns the result.
*
* How this is accomplished:
* This switchboard sends a "get" message over the channel describing which method to call with which arguments.
* The other side's switchboard finds a method with that name, and calls it with the arguments.
* It then packages up the returned value into a "reply" message, sending it back to us across the channel.
* This switchboard has attached a listener on the channel, which will resolve with the result when a reply is detected.
*
* Instead of an arguments list, arguments are supplied as a map.
*
* @param method the name of the method to call
* @param args arguments that will be supplied. Must be serializable, no functions or other nonsense.
* @returns whatever is returned from the method
*/
get<T = unknown>(method: string, args: unknown = undefined): Promise<T> {
return new Promise((resolve, reject) => {
if (!this.isInitialised) {
reject(new Error('Switchboard not initialised'));
return;
}
// In order to "call a method" on the other side of the port,
// we will send a message with a unique id
const messageId = this.getNewMessageId();
// attach a new listener to our port, and remove it when we get a response
const listener = (event: MessageEvent) => {
const message = event.data;
if (message.messageId !== messageId) return;
this.port.removeEventListener('message', listener);
if (isReply(message)) {
resolve(message.result);
} else {
const errStr = isError(message)
? message.error
: 'Unexpected response message';
reject(new Error(errStr));
}
};
this.port.addEventListener('message', listener);
this.port.start();
const message: GetMessage = {
switchboardAction: Actions.GET,
method,
messageId,
args,
};
this.port.postMessage(message);
});
}
/**
* Emit calls a method on the other side just like get does.
* But emit doesn't wait for a response, it just sends and forgets.
*
* @param method
* @param args
*/
emit(method: string, args: unknown = undefined) {
if (!this.isInitialised) {
this.logError('Switchboard not initialised');
return;
}
const message: EmitMessage = {
switchboardAction: Actions.EMIT,
method,
args,
};
this.port.postMessage(message);
}
start() {
if (!this.isInitialised) {
this.logError('Switchboard not initialised');
return;
}
this.port.start();
}
private log(...args: unknown[]) {
if (this.debugMode) {
console.debug(`[${this.name}]`, ...args);
}
}
private logError(...args: unknown[]) {
console.error(`[${this.name}]`, ...args);
}
private getNewMessageId() {
// eslint-disable-next-line no-plusplus
return `m_${this.name}_${this.incrementor++}`;
}
}
export default new Switchboard();