Implement JS flipper client

Summary:
Standardize WS implementation for JS environments.

Why do we need a separate server implementation for browsers?
Browser targets cannot authenticate via the default certificate exchange flow. We need a dedicated client for them that works over an insecure channel (without the cert exchange).

Major changes:
1. Renamed `flipper-js-client-sdk` to `js-flipper` for consistency with `react-native-flipper`
2. Updated `js-flipper` implementation to match our other existing clients

Documentation will be updated in a separate subsequent PR.

https://fb.quip.com/2mboA0xbgoxl

Reviewed By: mweststrate

Differential Revision: D31688105

fbshipit-source-id: 418aa80e0fd86361c089cf54b0d44a8b4f748efa

js/js-flipper/src/__tests__/client.spec.ts

@@ -0,0 +1,170 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {AddressInfo} from 'net';
+import {WebSocketServer, WebSocket} from 'ws';
+
+import {FlipperClient, FlipperWebSocket} from '../client';
+import {RECONNECT_TIMEOUT} from '../consts';
+import {WSMessageAccumulator} from './utils';
+
+describe('client', () => {
+  let port: number;
+  let wsServer: WebSocketServer;
+  let client: FlipperClient;
+
+  let allowConnection = true;
+  const verifyClient = jest.fn().mockImplementation(() => allowConnection);
+  beforeEach(() => {
+    allowConnection = true;
+  });
+
+  beforeAll(() => {
+    jest.useFakeTimers();
+  });
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  beforeEach(async () => {
+    wsServer = new WebSocketServer({
+      port: 0,
+      verifyClient,
+    });
+    await new Promise((resolve) => wsServer.on('listening', resolve));
+    port = (wsServer.address() as AddressInfo).port;
+    client = new FlipperClient();
+    // TODO: Figure out why we need to convert ot unknown first
+    client.websocketFactory = (url) =>
+      new WebSocket(url) as unknown as FlipperWebSocket;
+    client.urlBase = `localhost:${port}`;
+  });
+  afterEach(async () => {
+    client.stop();
+    await new Promise((resolve) => wsServer.close(resolve));
+  });
+
+  describe('message handling', () => {
+    describe('getPlugins', () => {
+      it('returns a list of registered plugins', async () => {
+        const serverReceivedMessages = new WSMessageAccumulator();
+        wsServer.on('connection', (ws) => {
+          ws.send(JSON.stringify({method: 'getPlugins', id: 0}));
+          ws.on('message', (message) =>
+            serverReceivedMessages.add(message.toString()),
+          );
+        });
+
+        client.addPlugin({
+          getId: () => '42',
+          onConnect: () => undefined,
+          onDisconnect: () => undefined,
+        });
+
+        await client.start();
+
+        const expectedGetPluginsResponse = {
+          id: 0,
+          success: {
+            plugins: ['42'],
+          },
+        };
+        const actualGetPluginsReponse = await serverReceivedMessages.newMessage;
+        expect(actualGetPluginsReponse).toBe(
+          JSON.stringify(expectedGetPluginsResponse),
+        );
+      });
+    });
+
+    it('onError is called if message handling has failed, connection is closed, client reconnects', async () => {
+      const onError = jest.fn();
+      client.onError = onError;
+
+      let resolveFirstConnectionPromise: () => void;
+      const firstConnectionPromise = new Promise<void>((resolve) => {
+        resolveFirstConnectionPromise = resolve;
+      });
+      wsServer.on('connection', (ws) => {
+        resolveFirstConnectionPromise();
+        // Send a malformed message to cause a failure
+        ws.send('{{{');
+      });
+
+      // Capturing a moment when the client received an error
+      const receivedErrorPromise = new Promise<void>((resolve) =>
+        onError.mockImplementationOnce((e) => {
+          resolve();
+        }),
+      );
+
+      await client.start();
+
+      // Capturing a moment when the client was closed because of the error
+      const closedPromise = new Promise<void>((resolve) => {
+        const originalOnclose = (client as any).ws.onclose;
+        (client as any).ws.onclose = (data: unknown) => {
+          originalOnclose(data);
+          resolve();
+        };
+      });
+
+      await receivedErrorPromise;
+      expect(onError).toBeCalledTimes(1);
+
+      // Make sure that the connection went through
+      await firstConnectionPromise;
+
+      wsServer.removeAllListeners('connection');
+
+      let resolveSecondConnectionPromise: () => void;
+      const secondConnectionPromise = new Promise<void>((resolve) => {
+        resolveSecondConnectionPromise = resolve;
+      });
+      wsServer.on('connection', () => {
+        resolveSecondConnectionPromise();
+      });
+
+      // Make sure the current client is closed
+      // When it closes, it schedules a reconnection
+      await closedPromise;
+
+      // Now, once the reconnection is scheduled, we can advance timers to do the actual reconnection
+      jest.advanceTimersByTime(RECONNECT_TIMEOUT);
+
+      // Make sure that the client reconnects
+      await secondConnectionPromise;
+    });
+  });
+
+  describe('connection', () => {
+    it('onError is called if connection has failed, it is called every time Flipper fails to reconnect', async () => {
+      allowConnection = false;
+
+      const onError = jest.fn();
+      client.onError = onError;
+
+      expect(onError).toBeCalledTimes(0);
+      client.start();
+
+      // Expect connection request to fail
+      await new Promise((resolve) => onError.mockImplementationOnce(resolve));
+      expect(onError).toBeCalledTimes(1);
+      // Checking that the request went through to the server
+      expect(verifyClient).toBeCalledTimes(1);
+
+      // Exepect reconnection attempts to fail
+      for (let i = 2; i < 10; i++) {
+        jest.advanceTimersByTime(RECONNECT_TIMEOUT);
+        await new Promise((resolve) => onError.mockImplementationOnce(resolve));
+        expect(onError).toBeCalledTimes(i);
+        expect(verifyClient).toBeCalledTimes(i);
+      }
+    });
+  });
+});

js/js-flipper/src/__tests__/utils.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+// TODO: Share with desktop/flipper-server-core/src/comms/__tests__/utils.ts
+export class WSMessageAccumulator {
+  private messages: unknown[] = [];
+  private newMessageSubscribers: ((newMessageContent: unknown) => void)[] = [];
+
+  constructor(private readonly timeout = 1000) {}
+
+  get newMessage(): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error('Timeout exceeded'));
+      }, this.timeout);
+
+      this.newMessageSubscribers.push((newMessageContent: unknown) => {
+        clearTimeout(timer);
+        resolve(newMessageContent);
+      });
+
+      this.consume();
+    });
+  }
+
+  add(newMessageContent: unknown) {
+    this.messages.push(newMessageContent);
+    this.consume();
+  }
+
+  private consume() {
+    if (this.messages.length && this.newMessageSubscribers.length) {
+      const message = this.messages.shift();
+      const subscriber = this.newMessageSubscribers.shift();
+      subscriber!(message);
+    }
+  }
+}

js/js-flipper/src/client.ts

@@ -0,0 +1,366 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {FlipperConnection} from './connection';
+import {FlipperRequest, FlipperResponse} from './message';
+import {FlipperPlugin} from './plugin';
+import {FlipperResponder} from './responder';
+import {assert, detectDevice, detectOS} from './util';
+import {RECONNECT_TIMEOUT} from './consts';
+
+// TODO: Share with flipper-server-core
+/**
+ * IANA WebSocket close code definitions.
+ *
+ * @remarks
+ * https://www.iana.org/assignments/websocket/websocket.xml#close-code-number
+ */
+export enum WSCloseCode {
+  /**
+   * Normal closure; the connection successfully completed whatever
+   * purpose for which it was created.
+   */
+  NormalClosure = 1000,
+  /**
+   * The endpoint is going away, either because of a server failure
+   * or because the browser is navigating away from the page that
+   * opened the connection.
+   */
+  GoingAway = 1001,
+  /**
+   * The endpoint is terminating the connection due to a protocol
+   * error.
+   */
+  ProtocolError = 1002,
+  /**
+   * The connection is being terminated because the endpoint
+   * received data of a type it cannot accept (for example, a
+   * text-only endpoint received binary data).
+   */
+  UnsupportedData = 1003,
+  /**
+   * (Reserved.)  Indicates that no status code was provided even
+   * though one was expected.
+   */
+  NoStatusRecvd = 1005,
+  /**
+   * (Reserved.) Used to indicate that a connection was closed
+   * abnormally (that is, with no close frame being sent) when a
+   * status code is expected.
+   */
+  AbnormalClosure = 1006,
+  /**
+   * The endpoint is terminating the connection because a message
+   * was received that contained inconsistent data (e.g., non-UTF-8
+   * data within a text message).
+   */
+  InvalidFramePayloadData = 1007,
+  /**
+   * The endpoint is terminating the connection because it received
+   * a message that violates its policy. This is a generic status
+   * code, used when codes 1003 and 1009 are not suitable.
+   */
+  PolicyViolation = 1008,
+  /**
+   * The endpoint is terminating the connection because a data frame
+   * was received that is too large.
+   */
+  MessageTooBig = 1009,
+  /**
+   * The client is terminating the connection because it expected
+   * the server to negotiate one or more extension, but the server
+   * didn't.
+   */
+  MissingExtension = 1010,
+  /**
+   * The server is terminating the connection because it encountered
+   * an unexpected condition that prevented it from fulfilling the
+   * request.
+   */
+  InternalError = 1011,
+  /**
+   * The server is terminating the connection because it is
+   * restarting. [Ref]
+   */
+  ServiceRestart = 1012,
+  /**
+   * The server is terminating the connection due to a temporary
+   * condition, e.g. it is overloaded and is casting off some of its
+   * clients.
+   */
+  TryAgainLater = 1013,
+  /**
+   * The server was acting as a gateway or proxy and received an
+   * invalid response from the upstream server. This is similar to
+   * 502 HTTP Status Code.
+   */
+  BadGateway = 1014,
+  /**
+   * (Reserved.) Indicates that the connection was closed due to a
+   * failure to perform a TLS handshake (e.g., the server
+   * certificate can't be verified).
+   */
+  TLSHandshake = 1015,
+}
+
+// global.WebSocket interface is not 100% compatible with ws.WebSocket interface
+// We need to support both, so defining our own with only required props
+export interface FlipperWebSocket {
+  onclose: ((ev: {code: WSCloseCode}) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+  onmessage:
+    | ((ev: {data: Buffer | ArrayBuffer | Buffer[] | string}) => void)
+    | null;
+  onopen: (() => void) | null;
+  close(code?: number): void;
+  send(data: string): void;
+  readyState: number;
+}
+
+export class FlipperClient {
+  protected plugins: Map<string, FlipperPlugin> = new Map();
+  protected connections: Map<string, FlipperConnection> = new Map();
+  private ws?: FlipperWebSocket;
+  private devicePseudoId = `${Date.now()}.${Math.random()}`;
+  private os = detectOS();
+  private device = detectDevice();
+  private _appName = 'JS App';
+  private reconnectionTimer?: NodeJS.Timeout;
+  private resolveStartPromise?: () => void;
+
+  public urlBase = `localhost:8333`;
+
+  public websocketFactory: (url: string) => FlipperWebSocket = (url) =>
+    new WebSocket(url) as FlipperWebSocket;
+  public onError: (e: unknown) => void = (e: unknown) =>
+    console.error('WebSocket error', e);
+
+  constructor(public readonly reconnectTimeout = RECONNECT_TIMEOUT) {}
+
+  addPlugin(plugin: FlipperPlugin) {
+    this.plugins.set(plugin.getId(), plugin);
+
+    if (this.isConnected) {
+      this.refreshPlugins();
+    }
+  }
+
+  getPlugin(id: string): FlipperPlugin | undefined {
+    return this.plugins.get(id);
+  }
+
+  async start(): Promise<void> {
+    if (this.ws) {
+      return;
+    }
+
+    return new Promise<void>((resolve) => {
+      this.resolveStartPromise = resolve;
+      this.connectToFlipper();
+    });
+  }
+
+  stop() {
+    if (!this.ws) {
+      return;
+    }
+
+    // TODO: Why is it not 1000 by default?
+    this.ws.close(WSCloseCode.NormalClosure);
+    this.ws = undefined;
+    for (const plugin of this.plugins.values()) {
+      this.disconnectPlugin(plugin);
+    }
+  }
+
+  sendData(payload: FlipperRequest | FlipperResponse) {
+    assert(this.ws);
+    this.ws.send(JSON.stringify(payload));
+  }
+
+  get isConnected() {
+    // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState#value
+    return !!this.ws && this.ws.readyState === 1;
+  }
+
+  get appName() {
+    return this._appName;
+  }
+
+  set appName(newAppName: string) {
+    this._appName = newAppName;
+
+    this.ws?.close(WSCloseCode.NormalClosure);
+    this.reconnect(true);
+  }
+
+  private connectToFlipper() {
+    const url = `ws://${this.urlBase}?device_id=${this.device}${this.devicePseudoId}&device=${this.device}&app=${this.appName}&os=${this.os}`;
+
+    this.ws = this.websocketFactory(url);
+
+    this.ws.onerror = (error) => {
+      this.onError(error);
+    };
+    this.ws.onclose = ({code}) => {
+      // Some WS implementations do not properly set `wasClean`
+      if (code !== WSCloseCode.NormalClosure) {
+        this.reconnect(false);
+      }
+    };
+
+    this.ws.onopen = () => {
+      assert(this.ws);
+
+      this.resolveStartPromise?.();
+      this.resolveStartPromise = undefined;
+
+      this.ws.onmessage = ({data}) => {
+        try {
+          const message = JSON.parse(data.toString());
+          this.onMessageReceived(message);
+        } catch (error) {
+          this.onError(error);
+          assert(this.ws);
+          this.ws.close(WSCloseCode.InternalError);
+        }
+      };
+    };
+  }
+
+  // TODO: Reconnect in a loop with an exponential backoff
+  private reconnect(now?: boolean) {
+    this.ws = undefined;
+
+    if (this.reconnectionTimer) {
+      clearTimeout(this.reconnectionTimer);
+      this.reconnectionTimer = undefined;
+    }
+
+    this.reconnectionTimer = setTimeout(
+      () => {
+        this.connectToFlipper();
+      },
+      now ? 0 : this.reconnectTimeout,
+    );
+  }
+
+  private onMessageReceived(message: {
+    method: string;
+    id: number;
+    params: any;
+  }) {
+    let responder: FlipperResponder | undefined;
+    try {
+      const {method, params, id} = message;
+      responder = new FlipperResponder(id, this);
+
+      if (method === 'getPlugins') {
+        responder.success({plugins: [...this.plugins.keys()]});
+        return;
+      }
+
+      if (method === 'getBackgroundPlugins') {
+        responder.success({
+          plugins: [...this.plugins.keys()].filter((key) =>
+            this.plugins.get(key)?.runInBackground?.(),
+          ),
+        });
+        return;
+      }
+
+      if (method === 'init') {
+        const identifier = params['plugin'] as string;
+        const plugin = this.plugins.get(identifier);
+        if (plugin == null) {
+          const errorMessage = `Plugin ${identifier} not found for method ${method}`;
+          responder.error({message: errorMessage, name: 'PluginNotFound'});
+          return;
+        }
+
+        this.connectPlugin(plugin);
+        return;
+      }
+
+      if (method === 'deinit') {
+        const identifier = params['plugin'] as string;
+        const plugin = this.plugins.get(identifier);
+        if (plugin == null) {
+          const errorMessage = `Plugin ${identifier} not found for method ${method}`;
+          responder.error({message: errorMessage, name: 'PluginNotFound'});
+          return;
+        }
+
+        this.disconnectPlugin(plugin);
+        return;
+      }
+
+      if (method === 'execute') {
+        const identifier = params['api'] as string;
+        const connection = this.connections.get(identifier);
+        if (connection == null) {
+          const errorMessage = `Connection ${identifier} not found for plugin identifier`;
+
+          responder.error({message: errorMessage, name: 'ConnectionNotFound'});
+          return;
+        }
+
+        connection.call(
+          params['method'] as string,
+          params['params'],
+          responder,
+        );
+        return;
+      }
+
+      if (method == 'isMethodSupported') {
+        const identifier = params['api'] as string;
+        const method = params['method'] as string;
+        const connection = this.connections.get(identifier);
+        if (connection == null) {
+          const errorMessage = `Connection ${identifier} not found for plugin identifier`;
+          responder.error({message: errorMessage, name: 'ConnectionNotFound'});
+          return;
+        }
+        responder.success({isSupported: connection.hasReceiver(method)});
+        return;
+      }
+
+      const response = {message: 'Received unknown method: ' + method};
+      responder.error(response);
+    } catch (e) {
+      if (responder) {
+        responder.error({
+          message: 'Unknown error during ' + JSON.stringify(message),
+          name: 'Unknown',
+        });
+      }
+      throw e;
+    }
+  }
+
+  private refreshPlugins() {
+    this.sendData({method: 'refreshPlugins'});
+  }
+
+  private connectPlugin(plugin: FlipperPlugin): void {
+    const id = plugin.getId();
+    const connection = new FlipperConnection(id, this);
+    plugin.onConnect(connection);
+    this.connections.set(id, connection);
+  }
+
+  private disconnectPlugin(plugin: FlipperPlugin): void {
+    const id = plugin.getId();
+    if (this.connections.has(id)) {
+      plugin.onDisconnect();
+      this.connections.delete(id);
+    }
+  }
+}

js/js-flipper/src/connection.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {FlipperErrorMessage, FlipperMessageBus} from './message';
+import {FlipperPluginConnection, FlipperPluginReceiver} from './plugin';
+import {FlipperResponder} from './responder';
+import {isPromise, safeJSONStringify} from './util';
+
+type FlipperReceiver = (data: unknown, responder: FlipperResponder) => void;
+
+export class FlipperConnection implements FlipperPluginConnection {
+  pluginId: string;
+  private client: FlipperMessageBus;
+  private subscriptions: Map<string, FlipperReceiver> = new Map();
+
+  constructor(pluginId: string, client: FlipperMessageBus) {
+    this.pluginId = pluginId;
+    this.client = client;
+  }
+
+  send(method: string, params?: unknown) {
+    this.client.sendData({
+      method: 'execute',
+      params: {
+        api: this.pluginId,
+        method,
+        params,
+      },
+    });
+  }
+
+  receive(method: string, receiver: FlipperPluginReceiver) {
+    const wrappedReceiver: FlipperReceiver = (data, responder) => {
+      const handleError = (e: unknown) => {
+        const errorMessage: FlipperErrorMessage =
+          e instanceof Error
+            ? {name: e.name, message: e.message, stacktrace: e.stack}
+            : {name: 'Unknown', message: safeJSONStringify(e)};
+        responder.error(errorMessage);
+      };
+      try {
+        const response = receiver(data);
+        if (isPromise(response)) {
+          response.then((data) => responder.success(data)).catch(handleError);
+          return;
+        }
+        responder.success(response);
+      } catch (e) {
+        handleError(e);
+      }
+    };
+    this.subscriptions.set(method, wrappedReceiver);
+  }
+
+  call(method: string, params: unknown, responder: FlipperResponder) {
+    const receiver = this.subscriptions.get(method);
+    if (receiver == null) {
+      const errorMessage = `Receiver ${method} not found.`;
+      responder.error({message: errorMessage});
+      return;
+    }
+    receiver.call(receiver, params, responder);
+  }
+
+  hasReceiver(method: string): boolean {
+    return this.subscriptions.has(method);
+  }
+}

js/js-flipper/src/consts.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+export const RECONNECT_TIMEOUT = 1000;

js/js-flipper/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {FlipperClient, FlipperWebSocket, WSCloseCode} from './client';
+import {FlipperPlugin} from './plugin';
+
+export * from './plugin';
+export {FlipperWebSocket};
+
+export const flipperClient = new FlipperClient();

js/js-flipper/src/message.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+export interface FlipperRequest {
+  method: string;
+  params?: {
+    method: string;
+    api: string;
+    params?: unknown;
+  };
+}
+export type FlipperResponse =
+  | {
+      id: number;
+      success: object | string | number | boolean | null;
+      error?: never;
+    }
+  | {
+      id: number;
+      success?: never;
+      error: FlipperErrorMessage;
+    };
+export interface FlipperErrorMessage {
+  message: string;
+  stacktrace?: string;
+  name?: string;
+}
+export interface FlipperMessageBus {
+  sendData(data: FlipperRequest | FlipperResponse): void;
+}

js/js-flipper/src/plugin.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+export type FlipperPluginReceiverRes =
+  | object
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | void;
+export type FlipperPluginReceiver = (
+  data: any,
+) => FlipperPluginReceiverRes | Promise<FlipperPluginReceiverRes>;
+export interface FlipperPluginConnection {
+  /**
+   * Send an `execute` message to Flipper.
+   * Here is what client sends over the wire:
+   * { method: 'execute', params: { api: pluginID, method, params } }
+   *
+   * @param method Method name that needs to be executed by Flipper
+   * @param params Any extra params required for the method execution
+   */
+  send(method: string, params?: unknown): void;
+  /**
+   * Listen to messages for the method provided and execute a callback when one arrives.
+   * Send response back to Flipper.
+   * Read more about responses at https://fbflipper.com/docs/extending/new-clients#responding-to-messages
+   *
+   * @param method Method name that Flipper sent to the client
+   * @param receiver A callback executed by the client when a message with the specified method arrives.
+   * If this callback throws or returns a rejected Promise, client send an error message to Flipper.
+   * If this callback returns any value (even undefined) synchronously, client sends it as a success message to Flipper.
+   * If this callback returns a Promise, clients sends the value it is resolved with as a success message to Flipper.
+   */
+  receive(method: string, receiver: FlipperPluginReceiver): void;
+}
+export interface FlipperPlugin {
+  /**
+   * @return The id of this plugin. This is the namespace which Flipper desktop plugins will call
+   *     methods on to route them to your plugin. This should match the id specified in your React
+   *     plugin.
+   */
+  getId(): string;
+
+  /**
+   * Called when a connection has been established. The connection passed to this method is valid
+   * until {@link FlipperPlugin#onDisconnect()} is called.
+   */
+  onConnect(connection: FlipperPluginConnection): void;
+
+  /**
+   * Called when the connection passed to `FlipperPlugin#onConnect(FlipperConnection)` is no
+   * longer valid. Do not try to use the connection in or after this method has been called.
+   */
+  onDisconnect(): void;
+
+  /**
+   * Returns true if the plugin is meant to be run in background too, otherwise it returns false.
+   */
+  runInBackground?(): boolean;
+}

js/js-flipper/src/responder.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+import {FlipperErrorMessage, FlipperMessageBus} from './message';
+import {FlipperPluginReceiverRes} from './plugin';
+
+export class FlipperResponder {
+  constructor(
+    public readonly responderId: number,
+    private client: FlipperMessageBus,
+  ) {}
+
+  success(response?: FlipperPluginReceiverRes) {
+    this.client.sendData({
+      id: this.responderId,
+      success: response == null ? null : response,
+    });
+  }
+
+  error(response: FlipperErrorMessage) {
+    this.client.sendData({id: this.responderId, error: response});
+  }
+}

js/js-flipper/src/util.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+// https://github.com/microsoft/TypeScript/issues/36931#issuecomment-846131999
+type Assert = (condition: unknown) => asserts condition;
+export const assert: Assert = (condition) => {
+  if (!condition) {
+    throw new Error();
+  }
+};
+
+export const safeJSONStringify = (data: unknown): string => {
+  try {
+    return JSON.stringify(data);
+  } catch {
+    return 'Unable to serialize';
+  }
+};
+
+export const isPromise = (val: unknown): val is Promise<unknown> =>
+  typeof val === 'object' &&
+  val !== null &&
+  typeof (val as Promise<unknown>).then === 'function' &&
+  typeof (val as Promise<unknown>).catch === 'function';
+
+// TODO: Share types wiht desktop
+type OS =
+  | 'iOS'
+  | 'Android'
+  | 'Metro'
+  | 'Windows'
+  | 'MacOS'
+  | 'Browser'
+  | 'Linux';
+
+// https://stackoverflow.com/a/31456668
+const detectDeviceType = () =>
+  typeof process === 'object' &&
+  typeof process.versions === 'object' &&
+  typeof process.versions.node !== 'undefined'
+    ? 'Node.js'
+    : 'Browser';
+export const detectOS = (): OS => {
+  if (detectDeviceType() === 'Browser') {
+    return 'Browser';
+  }
+  switch (require('os').type()) {
+    case 'Linux':
+      return 'Linux';
+    case 'Darwin':
+      return 'MacOS';
+    default:
+      return 'Windows';
+  }
+};
+
+export const detectDevice = (): string => {
+  if (detectDeviceType() === 'Browser') {
+    return window.navigator.userAgent;
+  }
+  return require('os').release();
+};
+
+export const awaitTimeout = (timeout: number) => new Promise(resolve => setTimeout)