@react-native-harness/bridge 1.6.0 → 1.7.0

package/src/app-liveness.ts

@@ -0,0 +1,103 @@
+import {
+  createConnectionCheck,
+  type ConnectionCheckOptions,
+  type PingableSocket,
+} from './connection-check.js';
+import { AppBridgeDisconnectedError } from './errors.js';
+import {
+  createJsBlockBudgetPolicy,
+  getIdleBudget,
+  type JsBlockBudgetPolicyOptions,
+} from './js-block-budget-policy.js';
+import { createJsWatchdog } from './js-watchdog.js';
+import type { BridgeEvents } from './shared.js';
+
+export type AppLivenessOptions = {
+  connectionCheck: ConnectionCheckOptions;
+  jsBlockBudget: JsBlockBudgetPolicyOptions;
+  jsProbeIntervalMs?: number;
+};
+
+export type AppLivenessOverrides = {
+  connectionCheck?: Partial<ConnectionCheckOptions>;
+  jsBlockBudget?: Partial<JsBlockBudgetPolicyOptions>;
+  jsProbeIntervalMs?: number;
+};
+
+export const DEFAULT_APP_LIVENESS_OPTIONS: AppLivenessOptions = {
+  connectionCheck: { intervalMs: 5_000, timeoutMs: 20_000 },
+  jsBlockBudget: { idleMs: 20_000, fileLoadMs: 60_000, graceMs: 5_000 },
+};
+
+// An override left `undefined` keeps the default instead of replacing it,
+// which would turn a budget into `undefined` and disable it.
+const definedOnly = <T extends object>(values: Partial<T> = {}): Partial<T> =>
+  Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== undefined),
+  ) as Partial<T>;
+
+export const resolveAppLivenessOptions = (
+  overrides: AppLivenessOverrides = {},
+): AppLivenessOptions => ({
+  connectionCheck: {
+    ...DEFAULT_APP_LIVENESS_OPTIONS.connectionCheck,
+    ...definedOnly(overrides.connectionCheck),
+  },
+  jsBlockBudget: {
+    ...DEFAULT_APP_LIVENESS_OPTIONS.jsBlockBudget,
+    ...definedOnly(overrides.jsBlockBudget),
+  },
+  jsProbeIntervalMs: overrides.jsProbeIntervalMs,
+});
+
+export type AppLiveness = {
+  handleEvent: (event: BridgeEvents) => void;
+  handleProbeAck: (id: number) => void;
+  dispose: () => void;
+};
+
+/**
+ * Watches one app connection with two independent checks: the connection
+ * check (is the process reachable?) and the JS watchdog (is the JS thread
+ * getting a turn?). See docs/adr/0001-app-liveness-detection.md.
+ */
+export const createAppLiveness = (options: {
+  socket: PingableSocket;
+  sendProbe: (id: number) => void;
+  onLost: (error: AppBridgeDisconnectedError) => void;
+  config: AppLivenessOptions;
+}): AppLiveness => {
+  const connectionCheck = createConnectionCheck(options.socket, {
+    ...options.config.connectionCheck,
+    onLost: () => {
+      options.onLost(new AppBridgeDisconnectedError('connection-lost'));
+    },
+  });
+
+  const policy = createJsBlockBudgetPolicy(options.config.jsBlockBudget);
+  const watchdog = createJsWatchdog({
+    sendProbe: options.sendProbe,
+    initialBudget: getIdleBudget(options.config.jsBlockBudget),
+    probeIntervalMs: options.config.jsProbeIntervalMs,
+    onUnresponsive: (budget) => {
+      options.onLost(
+        new AppBridgeDisconnectedError('js-thread-unresponsive', budget.label),
+      );
+    },
+  });
+
+  return {
+    handleEvent: (event) => {
+      const budget = policy.getBudgetForEvent(event);
+
+      if (budget) {
+        watchdog.setBlockBudget(budget);
+      }
+    },
+    handleProbeAck: watchdog.notifyProbeAck,
+    dispose: () => {
+      connectionCheck.dispose();
+      watchdog.dispose();
+    },
+  };
+};

package/src/binary.ts

@@ -0,0 +1,74 @@
+import type { LinkChannel, LinkConnection } from './link/index.js';
+
+export type OutgoingBinary = {
+  channelId: string;
+  /** Settles once every byte is handed to the link, or rejects if the channel fails. */
+  written: Promise<void>;
+  abort: (reason?: string) => void;
+};
+
+/**
+ * Opens a link channel and starts writing `data` into it. The channel id travels in an
+ * RPC message; the peer reads the bytes with `receiveBinary`. The link sends the channel's
+ * OPEN before any later message, so the peer always knows the id by the time it asks.
+ */
+export const sendBinary = async (
+  link: LinkConnection,
+  data: Uint8Array,
+): Promise<OutgoingBinary> => {
+  const channel = await link.openChannel({
+    signal: new AbortController().signal,
+  });
+
+  const written = (async () => {
+    const writer = channel.writable.getWriter();
+    await writer.write(data);
+    await writer.close();
+  })();
+
+  return {
+    channelId: channel.id,
+    written,
+    abort: (reason) => channel.abort(reason),
+  };
+};
+
+const readAll = async (channel: LinkChannel): Promise<Uint8Array> => {
+  const reader = channel.readable.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+
+  for (;;) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    chunks.push(value);
+    size += value.length;
+  }
+
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  return bytes;
+};
+
+/** Accepts the channel the peer opened with `sendBinary` and reads it to the end. */
+export const receiveBinary = async (
+  link: LinkConnection,
+  channelId: string,
+): Promise<Uint8Array> => {
+  const channel = link.acceptChannel(channelId);
+
+  // Nothing flows back to the sender; ending this direction lets the channel free its slot.
+  void channel.writable.close().catch(() => undefined);
+
+  return readAll(channel);
+};

package/src/client.ts

@@ -1,11 +1,15 @@
-import { createBinaryFrame, generateTransferId } from './binary-transfer.js';
+import { sendBinary } from './binary.js';
+import {
+  connectStandardWebSocket,
+  createLink,
+  globalClock,
+  type LinkConnection,
+  type Logger,
+  type StandardWebSocket,
+  type UplinkTransportConnection,
+} from './link/index.js';
 import { serializeBridgeMessage } from './protocol.js';
 import { createRpcPeer } from './rpc-peer.js';
-import {
-  createRpcTransport,
-  type BridgeTransport,
-} from './transport.js';
-import { createWebSocketClientTransport } from './websocket-client-transport.js';
 import type {
   BridgeClientFunctions,
   BridgeServerFunctions,
@@ -39,184 +43,182 @@ export type HarnessHandle = {
 };
 
 export type ConnectToHarnessOptions = {
-  transport?: BridgeTransport;
+  /** An already open link transport, used instead of dialing `url`. */
+  transport?: UplinkTransportConnection;
+  /** Creates the WebSocket to dial `url` with. Defaults to the global `WebSocket`. */
+  createSocket?: (url: string) => StandardWebSocket;
 };
 
-export { createWebSocketClientTransport };
+export type { UplinkTransportConnection };
 
 const noop = (): void => undefined;
 
-export const connectToHarness = (
+const createConsoleLogger = (): Logger => {
+  const logger: Logger = {
+    debug: noop,
+    info: noop,
+    warn: (message) => console.warn(`[harness] ${message}`),
+    error: (message) => console.error(`[harness] ${message}`),
+    child: () => logger,
+  };
+
+  return logger;
+};
+
+// React Native has no `crypto.randomUUID`, so channel ids come from a counter. Ids only
+// need to be unique among this connection's channels.
+const createChannelIdGenerator = (): (() => string) => {
+  let nextId = 1;
+  return () => `app-${nextId++}`;
+};
+
+const dial = async (
+  url: string,
+  options: ConnectToHarnessOptions,
+): Promise<UplinkTransportConnection> => {
+  if (options.transport) {
+    return options.transport;
+  }
+
+  try {
+    return await connectStandardWebSocket({
+      url,
+      createSocket: options.createSocket,
+    });
+  } catch (error) {
+    const detail =
+      error instanceof Error && error.message ? `: ${error.message}` : '';
+    throw new Error(`Failed to connect to Harness at ${url}${detail}`);
+  }
+};
+
+export const connectToHarness = async (
   url: string,
   callbacks: HarnessCallbacks,
   options: ConnectToHarnessOptions = {},
-): Promise<HarnessHandle> =>
-  new Promise((resolve, reject) => {
-    const transport = options.transport ?? createWebSocketClientTransport(url);
-    let settled = false;
-    let peerClosed = false;
-    let offOpen: () => void = noop;
-    let offError: () => void = noop;
-    let offClose: () => void = noop;
-
-    const cleanup = () => {
-      offOpen();
-      offError();
-      offClose();
-    };
-
-    const fail = (message: string) => {
-      if (settled) {
-        return;
-      }
+): Promise<HarnessHandle> => {
+  const transport = await dial(url, options);
+  const link: LinkConnection = createLink(transport, {
+    end: 'worker',
+    clock: globalClock,
+    logger: createConsoleLogger(),
+    generateId: createChannelIdGenerator(),
+  });
+
+  const rpc = createRpcPeer<
+    BridgeClientFunctions,
+    BridgeServerFunctions,
+    BridgeEvents
+  >({
+    localMethods: callbacks,
+    transport: {
+      send: (message) => {
+        void link.write(message);
+      },
+    },
+  });
+
+  let peerClosed = false;
+  let offMessage: () => void = noop;
+  let offClose: () => void = noop;
+  let offError: () => void = noop;
 
-      settled = true;
-      cleanup();
-      reject(new Error(message));
-    };
+  const getLinkClosedError = () => {
+    return new Error('Harness bridge link is closed');
+  };
 
-    const handleOpen = () => {
-      if (settled) {
+  const closePeer = (reason: Error) => {
+    if (peerClosed) {
+      return;
+    }
+
+    peerClosed = true;
+    offMessage();
+    offClose();
+    offError();
+    rpc.close(reason);
+  };
+
+  const handleMessage = async (data: string) => {
+    const controlMessage = await rpc.handleMessage(data);
+
+    if (!controlMessage) {
+      return;
+    }
+
+    if (controlMessage.type === 'js-probe') {
+      void link.write(
+        serializeBridgeMessage({ type: 'js-probe-ack', id: controlMessage.id }),
+      );
+    }
+  };
+
+  offMessage = link.onData((message) => {
+    void handleMessage(message).catch((error) => {
+      closePeer(
+        error instanceof Error
+          ? error
+          : new Error('Received invalid Harness bridge message'),
+      );
+      void link.close();
+    });
+  });
+
+  offError = link.onError((error) => {
+    closePeer(error);
+  });
+
+  offClose = link.onClose(() => {
+    closePeer(new Error('Harness connection closed'));
+  });
+
+  return {
+    reportReady: (device) => {
+      if (link.closed) {
+        closePeer(getLinkClosedError());
         return;
       }
 
-      settled = true;
-      cleanup();
-
-      const getTransportNotOpenError = () => {
-        return new Error('Harness bridge transport is not open');
-      };
-
-      const rpc = createRpcPeer<
-        BridgeClientFunctions,
-        BridgeServerFunctions,
-        BridgeEvents
-      >({
-        localMethods: callbacks,
-        transport: createRpcTransport(transport),
-      });
-
-      let offMessage: () => void = noop;
-      let offRuntimeClose: () => void = noop;
-      let offRuntimeError: () => void = noop;
-
-      const closePeer = (reason: Error) => {
-        if (peerClosed) {
-          return;
-        }
-
-        peerClosed = true;
-        offMessage();
-        offRuntimeClose();
-        offRuntimeError();
-        rpc.close(reason);
-      };
-
-      const handleMessage = async (data: string) => {
-        const controlMessage = await rpc.handleMessage(data);
-
-        if (!controlMessage) {
-          return;
-        }
-
-        if (controlMessage.type === 'ping') {
-          transport.send(
-            serializeBridgeMessage({ type: 'pong', id: controlMessage.id }),
-          );
-        }
-      };
-
-      offMessage = transport.onMessage((message) => {
-        if (typeof message !== 'string') {
-          return;
-        }
-
-        void handleMessage(message).catch((error) => {
-          closePeer(
-            error instanceof Error
-              ? error
-              : new Error('Received invalid Harness bridge message'),
-          );
-
-          if (transport.state === 'open') {
-            transport.close(1002, 'Invalid message');
-          }
-        });
-      });
-
-      offRuntimeClose = transport.onClose((event) => {
-        closePeer(
-          new Error(
-            `Harness connection closed (code ${event.code}${
-              event.reason ? `, reason: ${event.reason}` : ''
-            })`,
-          ),
-        );
-      });
-
-      offRuntimeError = transport.onError((error) => {
-        closePeer(error);
-      });
-
-      resolve({
-        reportReady: (device) => {
-          try {
-            if (transport.state !== 'open') {
-              throw getTransportNotOpenError();
-            }
-
-            transport.send(serializeBridgeMessage({ type: 'ready', device }));
-          } catch (error) {
-            closePeer(
-              error instanceof Error ? error : getTransportNotOpenError(),
-            );
-          }
-        },
-        emitEvent: (event) => {
-          rpc.sendEvent(event);
-        },
-        transferScreenshot: async (data, metadata) => {
-          const transferId = generateTransferId();
-          transport.send(createBinaryFrame(transferId, data));
-          return rpc.invoke(
+      void link.write(serializeBridgeMessage({ type: 'ready', device }));
+    },
+    emitEvent: (event) => {
+      rpc.sendEvent(event);
+    },
+    transferScreenshot: async (data, metadata) => {
+      const binary = await sendBinary(link, data);
+
+      try {
+        const [file] = await Promise.all([
+          rpc.invoke(
             'device.screenshot.receive',
-            { type: 'binary', transferId, size: data.length, mimeType: 'image/png' },
+            {
+              type: 'binary',
+              channelId: binary.channelId,
+              size: data.length,
+              mimeType: 'image/png',
+            },
             metadata,
-          );
-        },
-        matchImageSnapshot: (screenshot, testPath, options, runner) =>
-          rpc.invoke(
-            'test.matchImageSnapshot',
-            screenshot,
-            testPath,
-            options,
-            runner,
           ),
-        disconnect: () => {
-          closePeer(new Error('Harness connection closed by client'));
-          transport.close();
-        },
-      });
-    };
-
-    const handleError = (error: Error) => {
-      const detail = error.message ? `: ${error.message}` : '';
-      fail(`Failed to connect to Harness at ${url}${detail}`);
-    };
-
-    const handleClose = (event: { code: number; reason: string }) => {
-      fail(
-        `Harness connection at ${url} closed before becoming ready (code ${event.code}${
-          event.reason ? `, reason: ${event.reason}` : ''
-        })`,
-      );
-    };
+          binary.written,
+        ]);
 
-    offOpen = transport.onOpen(handleOpen);
-    offError = transport.onError(handleError);
-    offClose = transport.onClose(handleClose);
-
-    if (transport.state === 'open') {
-      handleOpen();
-    }
-  });
+        return file;
+      } catch (error) {
+        binary.abort();
+        throw error;
+      }
+    },
+    matchImageSnapshot: (screenshot, testPath, options, runner) =>
+      rpc.invoke(
+        'test.matchImageSnapshot',
+        screenshot,
+        testPath,
+        options,
+        runner,
+      ),
+    disconnect: () => {
+      closePeer(new Error('Harness connection closed by client'));
+      void link.close();
+    },
+  };
+};

package/src/connection-check.ts

@@ -0,0 +1,60 @@
+/**
+ * Checks that the app process is still reachable, using WebSocket protocol
+ * ping frames (RFC 6455). The app's native WebSocket answers them without
+ * involving JS (OkHttp on Android, SocketRocket on iOS, the network stack in
+ * browsers), so a blocked JS thread does not fail this check.
+ */
+export type PingableSocket = {
+  ping: () => void;
+  on: (event: 'pong', listener: () => void) => unknown;
+  off: (event: 'pong', listener: () => void) => unknown;
+};
+
+export type ConnectionCheckOptions = {
+  intervalMs: number;
+  timeoutMs: number;
+};
+
+export type ConnectionCheck = {
+  dispose: () => void;
+};
+
+export const createConnectionCheck = (
+  socket: PingableSocket,
+  options: ConnectionCheckOptions & { onLost: () => void },
+): ConnectionCheck => {
+  let lastPongAt = Date.now();
+  let disposed = false;
+
+  const handlePong = () => {
+    lastPongAt = Date.now();
+  };
+
+  socket.on('pong', handlePong);
+
+  const dispose = () => {
+    if (disposed) {
+      return;
+    }
+
+    disposed = true;
+    clearInterval(interval);
+    socket.off('pong', handlePong);
+  };
+
+  const interval = setInterval(() => {
+    if (Date.now() - lastPongAt > options.timeoutMs) {
+      dispose();
+      options.onLost();
+      return;
+    }
+
+    try {
+      socket.ping();
+    } catch {
+      // The socket is closing; its close event ends the session.
+    }
+  }, options.intervalMs);
+
+  return { dispose };
+};

package/src/errors.ts

@@ -13,7 +13,8 @@ export class DeviceNotRespondingError extends HarnessError {
 export type AppBridgeDisconnectedReason =
   | 'app-disconnected'
   | 'app-replaced'
-  | 'heartbeat-timeout'
+  | 'connection-lost'
+  | 'js-thread-unresponsive'
   | 'socket-error'
   | 'bridge-disposed';
 
@@ -23,8 +24,10 @@ const appBridgeDisconnectedMessage = (
   switch (reason) {
     case 'app-replaced':
       return 'The app bridge was replaced by a newer app connection. This can happen when the app reloads, restarts, or reconnects while a test file is still running.';
-    case 'heartbeat-timeout':
-      return 'The app bridge stopped responding during test execution. This can happen if the app was killed, crashed, became unresponsive, or lost its WebSocket connection.';
+    case 'connection-lost':
+      return 'The app stopped answering WebSocket pings during test execution. The app process was likely killed, frozen, or lost its network connection. Check .harness/crash-reports for a crash report.';
+    case 'js-thread-unresponsive':
+      return "The app's JS thread was blocked for longer than allowed during test execution.";
     case 'socket-error':
       return 'The app bridge connection failed during test execution. This can happen if the app was killed, crashed, or the underlying WebSocket connection closed unexpectedly.';
     case 'bridge-disposed':
@@ -35,8 +38,16 @@ const appBridgeDisconnectedMessage = (
 };
 
 export class AppBridgeDisconnectedError extends HarnessError {
-  constructor(public readonly reason: AppBridgeDisconnectedReason) {
-    super(appBridgeDisconnectedMessage(reason));
+  constructor(
+    public readonly reason: AppBridgeDisconnectedReason,
+    /** What the app was busy with, when known. Appended to the message. */
+    public readonly detail?: string
+  ) {
+    super(
+      detail
+        ? `${appBridgeDisconnectedMessage(reason)} It was busy with: ${detail}.`
+        : appBridgeDisconnectedMessage(reason)
+    );
     this.name = 'AppBridgeDisconnectedError';
     this.stack = `${this.name}: ${this.message}`;
   }