@react-native/dev-middleware 0.73.0 → 0.73.3

package/README.md

@@ -1,11 +1,85 @@
 # @react-native/dev-middleware
 
-![https://img.shields.io/npm/v/@react-native/dev-middleware?color=brightgreen&label=npm%20package](https://www.npmjs.com/package/@react-native/dev-middleware)
+![npm package](https://img.shields.io/npm/v/@react-native/dev-middleware?color=brightgreen&label=npm%20package)
 
 Dev server middleware supporting core React Native development features. This package is preconfigured in all React Native projects.
 
-## Endpoints
+## Usage
 
-### `/open-debugger`
+Middleware can be attached to a dev server (e.g. [Metro](https://facebook.github.io/metro/docs/getting-started)) using the `createDevMiddleware` API.
+
+```js
+import { createDevMiddleware } from '@react-native/dev-middleware';
+
+function myDevServerImpl(args) {
+  ...
+
+  const {middleware, websocketEndpoints} = createDevMiddleware({
+    projectRoot: metroConfig.projectRoot,
+    serverBaseUrl: `http://${args.host}:${args.port}`,
+    logger,
+  });
+
+  await Metro.runServer(metroConfig, {
+    host: args.host,
+    ...,
+    unstable_extraMiddleware: [
+      middleware,
+      // Optionally extend with additional HTTP middleware
+    ],
+    websocketEndpoints: {
+      ...websocketEndpoints,
+      // Optionally extend with additional WebSocket endpoints
+    },
+  });
+}
+```
+
+## Included middleware
+
+`@react-native/dev-middleware` is designed for integrators such as [`@expo/dev-server`](https://www.npmjs.com/package/@expo/dev-server) and [`@react-native/community-cli-plugin`](https://github.com/facebook/react-native/tree/main/packages/community-cli-plugin). It provides a common default implementation for core React Native dev server responsibilities.
+
+We intend to keep this to a narrow set of functionality, based around:
+
+- **Debugging** — The [Chrome DevTools protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/) endpoints supported by React Native, including the Inspector Proxy, which facilitates connections with multiple devices.
+- **Dev actions** — Endpoints implementing core [Dev Menu](https://reactnative.dev/docs/debugging#accessing-the-dev-menu) actions, e.g. reloading the app, opening the debugger frontend.
+
+### HTTP endpoints
+
+<small>`DevMiddlewareAPI.middleware`</small>
+
+These are exposed as a [`connect`](https://www.npmjs.com/package/connect) middleware handler, assignable to `Metro.runServer` or other compatible HTTP servers.
+
+#### GET `/json/list`, `/json` ([CDP](https://chromedevtools.github.io/devtools-protocol/#endpoints))
+
+Returns the list of available WebSocket targets for all connected React Native app sessions.
+
+#### GET `/json/version` ([CDP](https://chromedevtools.github.io/devtools-protocol/#endpoints))
+
+Returns version metadata used by Chrome DevTools.
+
+#### POST `/open-debugger`
 
 Open the JavaScript debugger for a given CDP target (direct Hermes debugging).
+
+<details>
+<summary>Example</summary>
+
+    curl -X POST 'http://localhost:8081/open-debugger?appId=com.meta.RNTester'
+</details>
+
+### WebSocket endpoints
+
+<small>`DevMiddlewareAPI.websocketEndpoints`</small>
+
+#### `/inspector/device`
+
+WebSocket handler for registering device connections.
+
+#### `/inspector/debug`
+
+WebSocket handler that proxies CDP messages to/from the corresponding device.
+
+## Contributing
+
+Changes to this package can be made locally and tested against the `rn-tester` app, per the [Contributing guide](https://reactnative.dev/contributing/overview#contributing-code). During development, this package is automatically run from source with no build step.

package/dist/createDevMiddleware.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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
+ * @oncall react_native
+ */
+
+import type { NextHandleFunction } from "connect";
+import type { BrowserLauncher } from "./types/BrowserLauncher";
+import type { EventReporter } from "./types/EventReporter";
+import type { ExperimentsConfig } from "./types/Experiments";
+import type { Logger } from "./types/Logger";
+type Options = Readonly<{
+  projectRoot: string;
+  /**
+   * The base URL to the dev server, as addressible from the local developer
+   * machine. This is used in responses which return URLs to other endpoints,
+   * e.g. the debugger frontend and inspector proxy targets.
+   *
+   * Example: `'http://localhost:8081'`.
+   */
+  serverBaseUrl: string;
+  logger?: Logger;
+  /**
+   * An interface for integrators to provide a custom implementation for
+   * opening URLs in a web browser.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_browserLauncher?: BrowserLauncher;
+  /**
+   * An interface for logging events.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_eventReporter?: EventReporter;
+  /**
+   * The set of experimental features to enable.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_experiments?: ExperimentsConfig;
+}>;
+type DevMiddlewareAPI = Readonly<{
+  middleware: NextHandleFunction;
+  websocketEndpoints: { [path: string]: ws$WebSocketServer };
+}>;
+declare function createDevMiddleware($$PARAM_0$$: Options): DevMiddlewareAPI;
+export default createDevMiddleware;

package/dist/createDevMiddleware.js

@@ -4,10 +4,21 @@ Object.defineProperty(exports, "__esModule", {
   value: true,
 });
 exports.default = createDevMiddleware;
+var _debuggerFrontend = _interopRequireDefault(
+  require("@react-native/debugger-frontend")
+);
 var _connect = _interopRequireDefault(require("connect"));
+var _path = _interopRequireDefault(require("path"));
+var _serveStatic = _interopRequireDefault(require("serve-static"));
 var _openDebuggerMiddleware = _interopRequireDefault(
   require("./middleware/openDebuggerMiddleware")
 );
+var _InspectorProxy = _interopRequireDefault(
+  require("./inspector-proxy/InspectorProxy")
+);
+var _DefaultBrowserLauncher = _interopRequireDefault(
+  require("./utils/DefaultBrowserLauncher")
+);
 function _interopRequireDefault(obj) {
   return obj && obj.__esModule ? obj : { default: obj };
 }
@@ -22,14 +33,50 @@ function _interopRequireDefault(obj) {
  * @oncall react_native
  */
 
-function createDevMiddleware({ logger } = {}) {
-  const middleware = (0, _connect.default)().use(
-    "/open-debugger",
-    (0, _openDebuggerMiddleware.default)({
-      logger,
-    })
+// $FlowFixMe[untyped-import] TODO: type serve-static
+
+function createDevMiddleware({
+  projectRoot,
+  serverBaseUrl,
+  logger,
+  unstable_browserLauncher = _DefaultBrowserLauncher.default,
+  unstable_eventReporter,
+  unstable_experiments: experimentConfig = {},
+}) {
+  const experiments = getExperiments(experimentConfig);
+  const inspectorProxy = new _InspectorProxy.default(
+    projectRoot,
+    serverBaseUrl,
+    unstable_eventReporter,
+    experiments
   );
+  const middleware = (0, _connect.default)()
+    .use(
+      "/open-debugger",
+      (0, _openDebuggerMiddleware.default)({
+        serverBaseUrl,
+        inspectorProxy,
+        browserLauncher: unstable_browserLauncher,
+        eventReporter: unstable_eventReporter,
+        experiments,
+        logger,
+      })
+    )
+    .use(
+      "/debugger-frontend",
+      (0, _serveStatic.default)(_path.default.join(_debuggerFrontend.default), {
+        fallthrough: false,
+      })
+    )
+    .use((...args) => inspectorProxy.processRequest(...args));
   return {
     middleware,
+    websocketEndpoints: inspectorProxy.createWebSocketListeners(),
+  };
+}
+function getExperiments(config) {
+  return {
+    enableCustomDebuggerFrontend: config.enableCustomDebuggerFrontend ?? false,
+    enableOpenDebuggerRedirect: config.enableOpenDebuggerRedirect ?? false,
   };
 }

package/dist/createDevMiddleware.js.flow

@@ -4,28 +4,57 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow strict
+ * @flow strict-local
  * @format
  * @oncall react_native
  */
 
-import type {NextHandleFunction} from 'connect';
-import type {Logger} from './types/Logger';
-
-import connect from 'connect';
-import openDebuggerMiddleware from './middleware/openDebuggerMiddleware';
+import type { NextHandleFunction } from "connect";
+import type { BrowserLauncher } from "./types/BrowserLauncher";
+import type { EventReporter } from "./types/EventReporter";
+import type { ExperimentsConfig } from "./types/Experiments";
+import type { Logger } from "./types/Logger";
 
 type Options = $ReadOnly<{
+  projectRoot: string,
+
+  /**
+   * The base URL to the dev server, as addressible from the local developer
+   * machine. This is used in responses which return URLs to other endpoints,
+   * e.g. the debugger frontend and inspector proxy targets.
+   *
+   * Example: `'http://localhost:8081'`.
+   */
+  serverBaseUrl: string,
+
   logger?: Logger,
+
+  /**
+   * An interface for integrators to provide a custom implementation for
+   * opening URLs in a web browser.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_browserLauncher?: BrowserLauncher,
+
+  /**
+   * An interface for logging events.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_eventReporter?: EventReporter,
+
+  /**
+   * The set of experimental features to enable.
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_experiments?: ExperimentsConfig,
 }>;
 
-export default function createDevMiddleware({logger}: Options = {}): {
+type DevMiddlewareAPI = $ReadOnly<{
   middleware: NextHandleFunction,
-} {
-  const middleware = connect().use(
-    '/open-debugger',
-    openDebuggerMiddleware({logger}),
-  );
-
-  return {middleware};
-}
+  websocketEndpoints: { [path: string]: ws$WebSocketServer },
+}>;
+
+declare export default function createDevMiddleware(Options): DevMiddlewareAPI;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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
+ * @oncall react_native
+ */
+
+export * from "./index.flow";

package/dist/index.flow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ * @oncall react_native
+ */
+
+export { default as createDevMiddleware } from "./createDevMiddleware";
+export type { BrowserLauncher, LaunchedBrowser } from "./types/BrowserLauncher";
+export type { EventReporter, ReportableEvent } from "./types/EventReporter";

package/dist/index.flow.js.flow

@@ -4,9 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow strict
+ * @flow strict-local
  * @format
  * @oncall react_native
  */
 
-export {default as createDevMiddleware} from './createDevMiddleware';
+export { default as createDevMiddleware } from "./createDevMiddleware";
+
+export type { BrowserLauncher, LaunchedBrowser } from "./types/BrowserLauncher";
+export type { EventReporter, ReportableEvent } from "./types/EventReporter";

package/dist/index.js

@@ -1,3 +1,16 @@
 "use strict";
 
-module.exports = require("./index.flow");
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+var _index = require("./index.flow");
+Object.keys(_index).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _index[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _index[key];
+    },
+  });
+});

package/dist/index.js.flow

@@ -9,12 +9,4 @@
  * @oncall react_native
  */
 
-/*::
-export type * from './index.flow';
-*/
-
-if (!process.env.BUILD_EXCLUDE_BABEL_REGISTER) {
-  require('../../../scripts/build/babel-register').registerForMonorepo();
-}
-
-module.exports = require('./index.flow');
+export * from "./index.flow";

package/dist/inspector-proxy/Device.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ * @oncall react_native
+ */
+
+import type {
+  DebuggerRequest,
+  GetScriptSourceRequest,
+  MessageFromDevice,
+  MessageToDevice,
+  Page,
+  SetBreakpointByUrlRequest,
+} from "./types";
+import DeviceEventReporter from "./DeviceEventReporter";
+import WS from "ws";
+import type { EventReporter } from "../types/EventReporter";
+type DebuggerInfo = {
+  socket: WS;
+  originalSourceURLAddress?: string;
+  prependedFilePrefix: boolean;
+  pageId: string;
+  userAgent: string | null;
+};
+/**
+ * Device class represents single device connection to Inspector Proxy. Each device
+ * can have multiple inspectable pages.
+ */
+declare class Device {
+  _id: string;
+  _name: string;
+  _app: string;
+  _deviceSocket: WS;
+  _pages: Array<Page>;
+  _debuggerConnection: null | undefined | DebuggerInfo;
+  _lastConnectedReactNativePage: null | undefined | Page;
+  _isReloading: boolean;
+  _lastGetPagesMessage: string;
+  _scriptIdToSourcePathMapping: Map<string, string>;
+  _projectRoot: string;
+  _deviceEventReporter: null | undefined | DeviceEventReporter;
+  constructor(
+    id: string,
+    name: string,
+    app: string,
+    socket: WS,
+    projectRoot: string,
+    eventReporter: null | undefined | EventReporter
+  );
+  getName(): string;
+  getApp(): string;
+  getPagesList(): Array<Page>;
+  handleDebuggerConnection(
+    socket: WS,
+    pageId: string,
+    metadata: Readonly<{ userAgent: string | null }>
+  ): void;
+  handleDuplicateDeviceConnection(newDevice: Device): void;
+  _handleMessageFromDevice(message: MessageFromDevice): void;
+  _sendMessageToDevice(message: MessageToDevice): void;
+  _setPagesPolling(): void;
+  _newReactNativePage(page: Page): void;
+  _processMessageFromDevice(
+    payload: { method: string; params: { sourceMapURL: string; url: string } },
+    debuggerInfo: DebuggerInfo
+  ): void;
+  _interceptMessageFromDebugger(
+    req: DebuggerRequest,
+    debuggerInfo: DebuggerInfo,
+    socket: WS
+  ): boolean;
+  _processDebuggerSetBreakpointByUrl(
+    req: SetBreakpointByUrlRequest,
+    debuggerInfo: DebuggerInfo
+  ): void;
+  _processDebuggerGetScriptSource(
+    req: GetScriptSourceRequest,
+    socket: WS
+  ): void;
+  _mapToDevicePageId(pageId: string): string;
+  _tryParseHTTPURL(url: string): null | undefined | URL;
+  _fetchText(url: URL): Promise<string>;
+  _sendErrorToDebugger(message: string): void;
+}
+export default Device;