@react-native-harness/bridge 1.3.0 → 1.4.0-rc.1

package/src/protocol.ts

@@ -0,0 +1,233 @@
+import type { BridgeEvents, DeviceDescriptor } from './shared.js';
+
+export type SerializedBridgeError = {
+  name: string;
+  message: string;
+  stack?: string;
+  cause?: unknown;
+};
+
+export type BridgeInvokeMessage = {
+  type: 'invoke';
+  id: number;
+  method: string;
+  args: unknown[];
+};
+
+export type BridgeReturnMessage =
+  | {
+      type: 'return';
+      id: number;
+      ok: true;
+      value?: unknown;
+    }
+  | {
+      type: 'return';
+      id: number;
+      ok: false;
+      error: SerializedBridgeError;
+    };
+
+export type BridgeEventMessage<Event extends { type: string } = BridgeEvents> = {
+  type: 'event';
+  event: Event;
+};
+
+export type BridgeReadyMessage = {
+  type: 'ready';
+  device: DeviceDescriptor;
+};
+
+export type BridgePingMessage = {
+  type: 'ping';
+  id: number;
+};
+
+export type BridgePongMessage = {
+  type: 'pong';
+  id: number;
+};
+
+export type BridgeControlMessage =
+  | BridgeReadyMessage
+  | BridgePingMessage
+  | BridgePongMessage;
+
+export type BridgeMessage<Event extends { type: string } = BridgeEvents> =
+  | BridgeInvokeMessage
+  | BridgeReturnMessage
+  | BridgeEventMessage<Event>
+  | BridgeControlMessage;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null;
+};
+
+const readNumber = (value: unknown, fieldName: string): number => {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`Invalid bridge message: ${fieldName} must be a number`);
+  }
+
+  return value;
+};
+
+const readString = (value: unknown, fieldName: string): string => {
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid bridge message: ${fieldName} must be a string`);
+  }
+
+  return value;
+};
+
+const readSerializedBridgeError = (value: unknown): SerializedBridgeError => {
+  if (!isRecord(value)) {
+    throw new Error('Invalid bridge message: error must be an object');
+  }
+
+  const name = readString(value.name, 'error.name');
+  const message = readString(value.message, 'error.message');
+
+  if (value.stack !== undefined) {
+    readString(value.stack, 'error.stack');
+  }
+
+  const stack = value.stack as string | undefined;
+
+  return {
+    name,
+    message,
+    stack,
+    cause: value.cause,
+  };
+};
+
+const readDeviceDescriptor = (value: unknown): DeviceDescriptor => {
+  if (!isRecord(value)) {
+    throw new Error('Invalid bridge message: device must be an object');
+  }
+
+  return {
+    platform: readString(value.platform, 'device.platform') as DeviceDescriptor['platform'],
+    manufacturer: readString(value.manufacturer, 'device.manufacturer'),
+    model: readString(value.model, 'device.model'),
+    osVersion: readString(value.osVersion, 'device.osVersion'),
+  };
+};
+
+const readBridgeEvent = (value: unknown): BridgeEvents => {
+  if (!isRecord(value)) {
+    throw new Error('Invalid bridge message: event must be an object');
+  }
+
+  readString(value.type, 'event.type');
+
+  return value as BridgeEvents;
+};
+
+export const serializeBridgeMessage = (
+  message: BridgeMessage,
+): string => {
+  return JSON.stringify(message);
+};
+
+export const parseBridgeMessage = (raw: string): BridgeMessage => {
+  const parsed: unknown = JSON.parse(raw);
+
+  if (!isRecord(parsed)) {
+    throw new Error('Invalid bridge message: expected an object');
+  }
+
+  const messageType = readString(parsed.type, 'type');
+
+  switch (messageType) {
+    case 'invoke': {
+      readNumber(parsed.id, 'id');
+      readString(parsed.method, 'method');
+
+      if (!Array.isArray(parsed.args)) {
+        throw new Error('Invalid bridge message: args must be an array');
+      }
+
+      return parsed as BridgeInvokeMessage;
+    }
+    case 'return': {
+      readNumber(parsed.id, 'id');
+
+      if (typeof parsed.ok !== 'boolean') {
+        throw new Error('Invalid bridge message: ok must be a boolean');
+      }
+
+      if (!parsed.ok) {
+        readSerializedBridgeError(parsed.error);
+      }
+
+      return parsed as BridgeReturnMessage;
+    }
+    case 'event': {
+      readBridgeEvent(parsed.event);
+      return parsed as BridgeEventMessage;
+    }
+    case 'ready': {
+      readDeviceDescriptor(parsed.device);
+      return parsed as BridgeReadyMessage;
+    }
+    case 'ping':
+    case 'pong': {
+      readNumber(parsed.id, 'id');
+      return parsed as BridgePingMessage | BridgePongMessage;
+    }
+    default:
+      throw new Error(`Invalid bridge message: unknown type ${messageType}`);
+  }
+};
+
+export const serializeBridgeError = (
+  error: unknown,
+): SerializedBridgeError => {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+      cause: error.cause,
+    };
+  }
+
+  if (isRecord(error)) {
+    const message =
+      typeof error.message === 'string'
+        ? error.message
+        : `Non-Error thrown value: ${String(error)}`;
+
+    return {
+      name: typeof error.name === 'string' ? error.name : 'NonErrorThrown',
+      message,
+      stack: typeof error.stack === 'string' ? error.stack : undefined,
+      cause: 'cause' in error ? error.cause : undefined,
+    };
+  }
+
+  return {
+    name: 'NonErrorThrown',
+    message:
+      typeof error === 'string'
+        ? error
+        : `Non-Error thrown value: ${String(error)}`,
+  };
+};
+
+export const deserializeBridgeError = (
+  serialized: SerializedBridgeError,
+): Error => {
+  const error = new Error(serialized.message, {
+    cause: serialized.cause,
+  });
+
+  error.name = serialized.name;
+
+  if (serialized.stack) {
+    error.stack = serialized.stack;
+  }
+
+  return error;
+};

package/src/rpc-peer.ts

@@ -0,0 +1,222 @@
+import {
+  deserializeBridgeError,
+  parseBridgeMessage,
+  serializeBridgeError,
+  serializeBridgeMessage,
+  type BridgeControlMessage,
+} from './protocol.js';
+import type { RpcTransport } from './transport.js';
+
+type RpcMethod = {
+  bivarianceHack(...args: unknown[]): unknown;
+}['bivarianceHack'];
+type RpcMethods = Record<string, RpcMethod>;
+
+type PendingInvocation = {
+  args: unknown[];
+  method: string;
+  reject: (reason: unknown) => void;
+  resolve: (value: unknown) => void;
+  timeout: ReturnType<typeof setTimeout> | null;
+};
+
+export type RpcPeer<
+  Remote extends RpcMethods,
+  Event extends { type: string },
+> = {
+  invoke: <K extends keyof Remote>(
+    method: K,
+    ...args: Parameters<Remote[K]>
+  ) => Promise<Awaited<ReturnType<Remote[K]>>>;
+  sendEvent: (event: Event) => void;
+  handleMessage: (raw: string) => Promise<BridgeControlMessage | null>;
+  close: (reason?: Error) => void;
+};
+
+export type CreateRpcPeerOptions<
+  Local extends RpcMethods,
+  Event extends { type: string },
+> = {
+  localMethods: Local;
+  transport: RpcTransport;
+  onEvent?: (event: Event) => void;
+  callTimeoutMs?: number;
+  createTimeoutError?: (method: string, args: unknown[]) => Error;
+};
+
+const createClosedPeerError = (): Error => {
+  return new Error('Bridge RPC peer closed');
+};
+
+export const createRpcPeer = <
+  Local extends RpcMethods,
+  Remote extends RpcMethods,
+  Event extends { type: string },
+>(
+  options: CreateRpcPeerOptions<Local, Event>,
+): RpcPeer<Remote, Event> => {
+  const pendingInvocations = new Map<number, PendingInvocation>();
+  let nextMessageId = 1;
+  let closedReason: Error | null = null;
+
+  const rejectPendingInvocations = (reason: Error) => {
+    for (const [id, invocation] of pendingInvocations) {
+      if (invocation.timeout) {
+        clearTimeout(invocation.timeout);
+      }
+
+      pendingInvocations.delete(id);
+      invocation.reject(reason);
+    }
+  };
+
+  const close = (reason = createClosedPeerError()) => {
+    if (closedReason) {
+      return;
+    }
+
+    closedReason = reason;
+    rejectPendingInvocations(reason);
+  };
+
+  const sendMessage = (message: object) => {
+    if (closedReason) {
+      throw closedReason;
+    }
+
+    options.transport.send(serializeBridgeMessage(message as never));
+  };
+
+  return {
+    invoke: (method, ...args) => {
+      if (closedReason) {
+        return Promise.reject(closedReason);
+      }
+
+      const id = nextMessageId++;
+
+      return new Promise((resolve, reject) => {
+        const methodName = String(method);
+        const invocation: PendingInvocation = {
+          args,
+          method: methodName,
+          reject,
+          resolve: (value) => {
+            resolve(value as Awaited<ReturnType<Remote[typeof method]>>);
+          },
+          timeout: null,
+        };
+
+        if (options.callTimeoutMs !== undefined) {
+          invocation.timeout = setTimeout(() => {
+            pendingInvocations.delete(id);
+            reject(
+              options.createTimeoutError?.(methodName, args) ??
+                new Error(`RPC call timed out: ${methodName}`),
+            );
+          }, options.callTimeoutMs);
+        }
+
+        pendingInvocations.set(id, invocation);
+
+        try {
+          sendMessage({
+            type: 'invoke',
+            id,
+            method: methodName,
+            args,
+          });
+        } catch (error) {
+          pendingInvocations.delete(id);
+
+          if (invocation.timeout) {
+            clearTimeout(invocation.timeout);
+          }
+
+          reject(error);
+        }
+      });
+    },
+    sendEvent: (event) => {
+      if (closedReason) {
+        return;
+      }
+
+      try {
+        sendMessage({ type: 'event', event });
+      } catch (error) {
+        close(error instanceof Error ? error : createClosedPeerError());
+      }
+    },
+    handleMessage: async (raw) => {
+      const message = parseBridgeMessage(raw);
+
+      switch (message.type) {
+        case 'invoke': {
+          const localMethod = options.localMethods[message.method];
+
+          if (!localMethod) {
+            sendMessage({
+              type: 'return',
+              id: message.id,
+              ok: false,
+              error: serializeBridgeError(
+                new Error(`Unknown bridge RPC method: ${message.method}`),
+              ),
+            });
+            return null;
+          }
+
+          try {
+            const value = await localMethod(...message.args);
+            sendMessage({
+              type: 'return',
+              id: message.id,
+              ok: true,
+              value,
+            });
+          } catch (error) {
+            sendMessage({
+              type: 'return',
+              id: message.id,
+              ok: false,
+              error: serializeBridgeError(error),
+            });
+          }
+
+          return null;
+        }
+        case 'return': {
+          const invocation = pendingInvocations.get(message.id);
+
+          if (!invocation) {
+            return null;
+          }
+
+          pendingInvocations.delete(message.id);
+
+          if (invocation.timeout) {
+            clearTimeout(invocation.timeout);
+          }
+
+          if (message.ok) {
+            invocation.resolve(message.value);
+          } else {
+            invocation.reject(deserializeBridgeError(message.error));
+          }
+
+          return null;
+        }
+        case 'event': {
+          options.onEvent?.(message.event as unknown as Event);
+          return null;
+        }
+        case 'ready':
+        case 'ping':
+        case 'pong':
+          return message;
+      }
+    },
+    close,
+  };
+};