Implement subscribing to data updates for Flipper Server Companion

Summary: Allow subscribing to state updates from the plugin in headless mode

Reviewed By: passy

Differential Revision: D36516754

fbshipit-source-id: 14db51243e1d91332a7327c1792412149339f907

desktop/flipper-common/src/companion-types.tsx

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+type SerializableFnArg =
+  | null
+  | boolean
+  | number
+  | string
+  | {[prop: string]: SerializableFnArg | SerializableFnArg[]};
+
+export interface FlipperCompanionAvailablePlugin {
+  pluginId: string;
+  /**
+   * `active` if a plugin is connected and running (accepting messages)
+   * `ready` if a plugin can be started: bundled or found on a file system.
+   * `unavailable` if plugin is supported by a device, but it cannot be loaded by Flipper (not bundled, not found on a file system, does not support a headless mode)
+   */
+  state: 'unavailable' | 'ready' | 'active';
+}
+
+export type FlipperCompanionCommands = {
+  'companion-plugin-list': (
+    clientId: string,
+  ) => Promise<FlipperCompanionAvailablePlugin[]>;
+  /**
+   * Start a plugin for a client. It triggers 'onConnect' and 'onActivate' listeners for the plugin.
+   */
+  'companion-plugin-start': (
+    clientId: string,
+    pluginId: string,
+  ) => Promise<void>;
+  /**
+   * Stops and destroys a plugin for a client. It triggers 'onDeactivate', 'onDisconnect', and 'onDestroy' listeners for the plugin.
+   */
+  'companion-plugin-stop': (
+    clientId: string,
+    pluginId: string,
+  ) => Promise<void>;
+  /**
+   * Execute a command exposed via `export const API = () => ...` in a plugin.
+   */
+  'companion-plugin-exec': (
+    clientId: string,
+    pluginId: string,
+    api: string,
+    params?: SerializableFnArg[],
+  ) => Promise<any>;
+  /**
+   * Subscribe to state updates via `export const API = () => ...` in a plugin. Returns the current state.
+   */
+  'companion-plugin-subscribe': (
+    clientId: string,
+    pluginId: string,
+    api: string,
+  ) => Promise<any>;
+  'companion-device-plugin-list': (
+    deviceSerial: string,
+  ) => Promise<FlipperCompanionAvailablePlugin[]>;
+  /**
+   * Start a device plugin for a device. It triggers 'onActivate' listener for the plugin.
+   */
+  'companion-device-plugin-start': (
+    deviceSerial: string,
+    pluginId: string,
+  ) => Promise<void>;
+  /**
+   * Stops and destroys a device plugin for a device. It triggers 'onDeactivate' and 'onDestroy' listeners for the plugin.
+   */
+  'companion-device-plugin-stop': (
+    deviceSerial: string,
+    pluginId: string,
+  ) => Promise<void>;
+  /**
+   * Execute a command exposed via `export const api = () => ...` in a plugin.
+   */
+  'companion-device-plugin-exec': (
+    deviceSerial: string,
+    pluginId: string,
+    api: string,
+    params?: SerializableFnArg[],
+  ) => Promise<any>;
+  /**
+   * Subscribe to state updates via `export const API = () => ...` in a plugin. Returns the current state.
+   */
+  'companion-device-plugin-subscribe': (
+    clientId: string,
+    pluginId: string,
+    api: string,
+  ) => Promise<any>;
+};
+
+export type FlipperCompanionEvents = {
+  'companion-plugin-state-update': {
+    clientId: string;
+    pluginId: string;
+    api: string;
+    data: unknown;
+  };
+  'companion-device-plugin-state-update': {
+    deviceSerial: string;
+    pluginId: string;
+    api: string;
+    data: unknown;
+  };
+};

desktop/flipper-common/src/index.tsx

@@ -17,6 +17,7 @@ export {
   NoopLogger,
 } from './utils/Logger';
 export * from './server-types';
+export * from './companion-types';
 export * from './ServerAddOn';
 export {sleep} from './utils/sleep';
 export {timeout} from './utils/timeout';

desktop/flipper-common/src/transport.tsx

@@ -7,9 +7,10 @@
  * @format
  */
 
+import {FlipperCompanionEvents} from './companion-types';
 import {FlipperServerCommands, FlipperServerEvents} from './server-types';
 
-type GenericWebSocketMessage<E = string, T = unknown> = {
+export type GenericWebSocketMessage<E = string, T = unknown> = {
   event: E;
   payload: T;
 };
@@ -47,6 +48,16 @@ export type ServerEventWebSocketMessage = GenericWebSocketMessage<
   }[keyof FlipperServerEvents]
 >;
 
+export type CompanionEventWebSocketMessage = GenericWebSocketMessage<
+  'companion-event',
+  {
+    [K in keyof FlipperCompanionEvents]: {
+      event: K;
+      data: FlipperCompanionEvents[K];
+    };
+  }[keyof FlipperCompanionEvents]
+>;
+
 export type ClientWebSocketMessage = ExecWebSocketMessage;
 export type ServerWebSocketMessage =
   | ExecResponseWebSocketMessage