Rename BrowserLauncher interface and implementations

Summary:
Renames the **"BrowserLauncher"** concept (`unstable_browserLauncher`) to **"DevToolLauncher"** (`unstable_toolLauncher`), since the scope is now widened to open the desktop debugger shell by default.

Also rename and remove `unstable_` prefixes for `launchDebuggerShell` and `prepareDebuggerShell` methods (APIs remain unstable on the root option key).

**Why not `DebuggerLauncher`?**

This naming remains wide enough to cover other host process delegation in future (e.g. opening other secondary tools, or opening a generic URL in the browser). Debugger launching methods remain specifically named to match their intent.

Changelog: [Internal]

Reviewed By: vzaidman

Differential Revision: D94218654

fbshipit-source-id: e59d5465f200666cd0f1a189414f2223f5e46f69

Author: huntie

packages/dev-middleware/src/__tests__/InspectorProxyHttpApi-test.js

@@ -13,7 +13,7 @@ import type {
   JsonVersionResponse,
 } from '../inspector-proxy/types';
 
-import DefaultBrowserLauncher from '../utils/DefaultBrowserLauncher';
+import DefaultToolLauncher from '../utils/DefaultToolLauncher';
 import {fetchJson, requestLocal} from './FetchUtils';
 import {createDeviceMock} from './InspectorDeviceUtils';
 import {withAbortSignalForEachTest} from './ResourceUtils';
@@ -397,9 +397,9 @@ describe('inspector proxy HTTP API', () => {
       ]);
       jest.advanceTimersByTime(PAGES_POLLING_DELAY);
 
-      // Hook into `DefaultBrowserLauncher.launchDebuggerAppWindow` to ensure debugger was launched
+      // Hook into `DefaultToolLauncher.launchDebuggerAppWindow` to ensure debugger was launched
       const launchDebuggerSpy = jest
-        .spyOn(DefaultBrowserLauncher, 'launchDebuggerAppWindow')
+        .spyOn(DefaultToolLauncher, 'launchDebuggerAppWindow')
         .mockResolvedValueOnce();
 
       try {

packages/dev-middleware/src/__tests__/StandaloneFuseboxShell-test.js

@@ -9,9 +9,9 @@
  */
 
 import type {JsonPagesListResponse} from '../inspector-proxy/types';
-import type {BrowserLauncher} from '../types/BrowserLauncher';
+import type {DevToolLauncher} from '../types/DevToolLauncher';
 
-import DefaultBrowserLauncher from '../utils/DefaultBrowserLauncher';
+import DefaultToolLauncher from '../utils/DefaultToolLauncher';
 import {fetchJson, requestLocal} from './FetchUtils';
 import {createDeviceMock} from './InspectorDeviceUtils';
 import {withAbortSignalForEachTest} from './ResourceUtils';
@@ -23,18 +23,18 @@ const PAGES_POLLING_DELAY = 2100;
 jest.useFakeTimers();
 
 describe('enableStandaloneFuseboxShell experiment', () => {
-  const BrowserLauncherWithFuseboxShell: BrowserLauncher = {
-    ...DefaultBrowserLauncher,
-    unstable_showFuseboxShell: () => {
+  const ToolLauncherWithFuseboxShell: DevToolLauncher = {
+    ...DefaultToolLauncher,
+    launchDebuggerShell: () => {
       throw new Error('Not implemented');
     },
-    unstable_prepareFuseboxShell: async () => {
+    prepareDebuggerShell: async () => {
       return {code: 'not_implemented'};
     },
   };
   const serverRef = withServerForEachTest({
     logger: undefined,
-    unstable_browserLauncher: BrowserLauncherWithFuseboxShell,
+    unstable_toolLauncher: ToolLauncherWithFuseboxShell,
     unstable_experiments: {
       enableStandaloneFuseboxShell: true,
     },
@@ -66,10 +66,10 @@ describe('enableStandaloneFuseboxShell experiment', () => {
       jest.advanceTimersByTime(PAGES_POLLING_DELAY);
 
       const launchDebuggerAppWindowSpy = jest
-        .spyOn(BrowserLauncherWithFuseboxShell, 'launchDebuggerAppWindow')
+        .spyOn(ToolLauncherWithFuseboxShell, 'launchDebuggerAppWindow')
         .mockResolvedValue();
       const showFuseboxShellSpy = jest
-        .spyOn(BrowserLauncherWithFuseboxShell, 'unstable_showFuseboxShell')
+        .spyOn(ToolLauncherWithFuseboxShell, 'launchDebuggerShell')
         .mockResolvedValue();
 
       try {
@@ -128,6 +128,6 @@ describe('enableStandaloneFuseboxShell experiment', () => {
       }
     });
 
-    // TODO(moti): Add tests around unstable_prepareFuseboxShell
+    // TODO(moti): Add tests around prepareDebuggerShell
   });
 });

packages/dev-middleware/src/createDevMiddleware.js

@@ -9,7 +9,7 @@
  */
 
 import type {CreateCustomMessageHandlerFn} from './inspector-proxy/CustomMessageHandler';
-import type {BrowserLauncher} from './types/BrowserLauncher';
+import type {DevToolLauncher} from './types/DevToolLauncher';
 import type {EventReporter, ReportableEvent} from './types/EventReporter';
 import type {Experiments, ExperimentsConfig} from './types/Experiments';
 import type {Logger} from './types/Logger';
@@ -18,7 +18,7 @@ import type {NextHandleFunction} from 'connect';
 
 import InspectorProxy from './inspector-proxy/InspectorProxy';
 import openDebuggerMiddleware from './middleware/openDebuggerMiddleware';
-import DefaultBrowserLauncher from './utils/DefaultBrowserLauncher';
+import DefaultToolLauncher from './utils/DefaultToolLauncher';
 import reactNativeDebuggerFrontendPath from '@react-native/debugger-frontend';
 import connect from 'connect';
 import path from 'path';
@@ -31,18 +31,17 @@ type Options = Readonly<{
    */
   serverBaseUrl: string | ReadonlyURL,
 
-  logger?: Logger,
-
   /**
-   * An interface for integrators to provide a custom implementation for
-   * opening URLs in a web browser.
+   * An implementation for logging messages to the terminal (recommended).
    *
-   * This is an unstable API with no semver guarantees.
+   * In `@react-native/community-cli-plugin`, this reuses Metro's
+   * 'unstable_server_log' event in `TerminalReporter`.
    */
-  unstable_browserLauncher?: BrowserLauncher,
+  logger?: Logger,
 
   /**
-   * An interface for logging events.
+   * An `EventReporter` implementation for logging structured events
+   * (recommended).
    *
    * This is an unstable API with no semver guarantees.
    */
@@ -55,6 +54,14 @@ type Options = Readonly<{
    */
   unstable_experiments?: ExperimentsConfig,
 
+  /**
+   * Override the default handlers for launching external applications (the
+   * debugger frontend) on the host machine (or target dev machine).
+   *
+   * This is an unstable API with no semver guarantees.
+   */
+  unstable_toolLauncher?: DevToolLauncher,
+
   /**
    * Create custom handler to add support for unsupported CDP events, or debuggers.
    * This handler is instantiated per logical device and debugger pair.
@@ -64,7 +71,8 @@ type Options = Readonly<{
   unstable_customInspectorMessageHandler?: CreateCustomMessageHandlerFn,
 
   /**
-   * Whether to measure the event loop performance of inspector proxy and log report it via the event reporter.
+   * Whether to measure the event loop performance of inspector proxy and
+   * report it via the event reporter.
    *
    * This is an unstable API with no semver guarantees.
    */
@@ -79,10 +87,9 @@ type DevMiddlewareAPI = Readonly<{
 export default function createDevMiddleware({
   serverBaseUrl,
   logger,
-  // $FlowFixMe[incompatible-type]
-  unstable_browserLauncher = DefaultBrowserLauncher,
   unstable_eventReporter,
   unstable_experiments: experimentConfig = {},
+  unstable_toolLauncher = DefaultToolLauncher,
   unstable_customInspectorMessageHandler,
   unstable_trackInspectorProxyEventLoopPerf = false,
 }: Options): DevMiddlewareAPI {
@@ -110,7 +117,7 @@ export default function createDevMiddleware({
       openDebuggerMiddleware({
         serverBaseUrl: normalizedServerBaseUrl,
         inspectorProxy,
-        browserLauncher: unstable_browserLauncher,
+        toolLauncher: unstable_toolLauncher,
         eventReporter,
         experiments,
         logger,

packages/dev-middleware/src/index.flow.js

@@ -9,9 +9,9 @@
  */
 
 export type {
-  BrowserLauncher,
+  DevToolLauncher,
   DebuggerShellPreparationResult,
-} from './types/BrowserLauncher';
+} from './types/DevToolLauncher';
 export type {EventReporter, ReportableEvent} from './types/EventReporter';
 export type {
   CustomMessageHandler,
@@ -21,5 +21,5 @@ export type {
 export type {Logger} from './types/Logger';
 export type {ReadonlyURL} from './types/ReadonlyURL';
 
-export {default as unstable_DefaultBrowserLauncher} from './utils/DefaultBrowserLauncher';
+export {default as unstable_DefaultToolLauncher} from './utils/DefaultToolLauncher';
 export {default as createDevMiddleware} from './createDevMiddleware';

packages/dev-middleware/src/middleware/openDebuggerMiddleware.js

@@ -11,9 +11,9 @@
 import type {InspectorProxyQueries} from '../inspector-proxy/InspectorProxy';
 import type {PageDescription} from '../inspector-proxy/types';
 import type {
-  BrowserLauncher,
   DebuggerShellPreparationResult,
-} from '../types/BrowserLauncher';
+  DevToolLauncher,
+} from '../types/DevToolLauncher';
 import type {EventReporter} from '../types/EventReporter';
 import type {Experiments} from '../types/Experiments';
 import type {Logger} from '../types/Logger';
@@ -30,7 +30,7 @@ const LEGACY_SYNTHETIC_PAGE_TITLE =
 type Options = Readonly<{
   serverBaseUrl: ReadonlyURL,
   logger?: Logger,
-  browserLauncher: BrowserLauncher,
+  toolLauncher: DevToolLauncher,
   eventReporter?: EventReporter,
   experiments: Experiments,
   inspectorProxy: InspectorProxyQueries,
@@ -44,15 +44,15 @@ type Options = Readonly<{
 export default function openDebuggerMiddleware({
   serverBaseUrl,
   logger,
-  browserLauncher,
+  toolLauncher,
   eventReporter,
   experiments,
   inspectorProxy,
 }: Options): NextHandleFunction {
   let shellPreparationPromise: Promise<DebuggerShellPreparationResult>;
   if (experiments.enableStandaloneFuseboxShell) {
     shellPreparationPromise =
-      browserLauncher?.unstable_prepareFuseboxShell?.() ??
+      toolLauncher?.prepareDebuggerShell?.() ??
       Promise.resolve({code: 'not_implemented'});
     shellPreparationPromise = shellPreparationPromise.then(result => {
       eventReporter?.logEvent({
@@ -196,17 +196,14 @@ export default function openDebuggerMiddleware({
                   ].join('-'),
                 )
                 .digest('hex');
-              if (!browserLauncher.unstable_showFuseboxShell) {
+              if (!toolLauncher.launchDebuggerShell) {
                 throw new Error(
-                  'Fusebox shell is not supported by the current browser launcher',
+                  'Fusebox shell is not supported by the current app launcher',
                 );
               }
-              await browserLauncher.unstable_showFuseboxShell(
-                frontendUrl,
-                windowKey,
-              );
+              await toolLauncher.launchDebuggerShell(frontendUrl, windowKey);
             } else {
-              await browserLauncher.launchDebuggerAppWindow(frontendUrl);
+              await toolLauncher.launchDebuggerAppWindow(frontendUrl);
             }
             res.writeHead(200);
             res.end();

…-middleware/src/types/BrowserLauncher.js …-middleware/src/types/DevToolLauncher.jspackages/dev-middleware/src/types/BrowserLauncher.js renamed to packages/dev-middleware/src/types/DevToolLauncher.js packages/dev-middleware/src/types/BrowserLauncher.js renamed to packages/dev-middleware/src/types/DevToolLauncher.js

@@ -14,19 +14,20 @@ export type {DebuggerShellPreparationResult};
 
 /**
  * An interface for integrators to provide a custom implementation for
- * opening URLs in a web browser.
+ * launching external applications on the host machine (or target dev machine).
+ *
+ * This is an unstable API with no semver guarantees.
  */
-export interface BrowserLauncher {
+export interface DevToolLauncher {
   /**
-   * Attempt to open a debugger frontend URL in a browser app window,
-   * optionally returning an object to control the launched browser instance.
-   * The browser used should be capable of running Chrome DevTools.
+   * Attempt to open a debugger frontend URL in a browser app window. The
+   * browser used should be capable of running Chrome DevTools.
    *
    * The provided URL is based on serverBaseUrl, and therefore reachable from
    * the host of dev-middleware. Implementations are responsible for rewriting
    * this as necessary where the server is remote.
    */
-  launchDebuggerAppWindow: (url: string) => Promise<void>;
+  +launchDebuggerAppWindow: (url: string) => Promise<void>;
 
   /**
    * Attempt to open a debugger frontend URL in a standalone shell window
@@ -46,10 +47,7 @@ export interface BrowserLauncher {
    * the host of dev-middleware. Implementations are responsible for rewriting
    * this as necessary where the server is remote.
    */
-  +unstable_showFuseboxShell?: (
-    url: string,
-    windowKey: string,
-  ) => Promise<void>;
+  +launchDebuggerShell?: (url: string, windowKey: string) => Promise<void>;
 
   /**
    * Attempt to prepare the debugger shell for use and returns a coded result
@@ -62,5 +60,5 @@ export interface BrowserLauncher {
    * SHOULD NOT return a rejecting promise in any case, and instead SHOULD report
    * errors via the returned result object.
    */
-  +unstable_prepareFuseboxShell?: () => Promise<DebuggerShellPreparationResult>;
+  +prepareDebuggerShell?: () => Promise<DebuggerShellPreparationResult>;
 }

packages/dev-middleware/src/types/EventReporter.js

@@ -8,7 +8,7 @@
  * @format
  */
 
-import type {DebuggerShellPreparationResult} from './BrowserLauncher';
+import type {DebuggerShellPreparationResult} from './DevToolLauncher';
 
 type SuccessResult<Props: {...} | void = {}> = {
   status: 'success',

packages/dev-middleware/src/types/Experiments.js

@@ -12,7 +12,7 @@ export type Experiments = Readonly<{
   /**
    * Enables the handling of GET requests in the /open-debugger endpoint,
    * in addition to POST requests. GET requests respond by redirecting to
-   * the debugger frontend, instead of opening it using the BrowserLauncher
+   * the debugger frontend, instead of opening it using the DevToolLauncher
    * interface.
    */
   enableOpenDebuggerRedirect: boolean,
@@ -25,8 +25,8 @@ export type Experiments = Readonly<{
 
   /**
    * Launch the debugger frontend in a standalone shell instead of a browser.
-   * When this is enabled, we will use the optional unstable_showFuseboxShell
-   * method on the BrowserLauncher, or throw an error if the method is missing.
+   * When this is enabled, we will use the optional launchDebuggerShell
+   * method on the DevToolLauncher, or throw an error if the method is missing.
    *
    * NOTE: Disabling this also disables support for concurrent sessions in the
    * inspector proxy. Without the standalone shell, the proxy remains responsible

…ware/src/utils/DefaultBrowserLauncher.js …dleware/src/utils/DefaultToolLauncher.jspackages/dev-middleware/src/utils/DefaultBrowserLauncher.js renamed to packages/dev-middleware/src/utils/DefaultToolLauncher.js packages/dev-middleware/src/utils/DefaultBrowserLauncher.js renamed to packages/dev-middleware/src/utils/DefaultToolLauncher.js

@@ -8,7 +8,7 @@
  * @format
  */
 
-import type {DebuggerShellPreparationResult} from '../';
+import type {DebuggerShellPreparationResult} from '../types/DevToolLauncher';
 
 const {
   unstable_prepareDebuggerShell,
@@ -20,14 +20,10 @@ const {Launcher: EdgeLauncher} = require('chromium-edge-launcher');
 const open = require('open');
 
 /**
- * Default `BrowserLauncher` implementation which opens URLs on the host
- * machine.
+ * Default `DevToolLauncher` implementation which handles opening apps on the
+ * local machine.
  */
-const DefaultBrowserLauncher = {
-  /**
-   * Attempt to open the debugger frontend in a Google Chrome or Microsoft Edge
-   * app window.
-   */
+const DefaultToolLauncher = {
   launchDebuggerAppWindow: async (url: string): Promise<void> => {
     let chromePath;
 
@@ -69,21 +65,18 @@ const DefaultBrowserLauncher = {
     });
   },
 
-  async unstable_showFuseboxShell(
-    url: string,
-    windowKey: string,
-  ): Promise<void> {
+  async launchDebuggerShell(url: string, windowKey: string): Promise<void> {
     return await unstable_spawnDebuggerShellWithArgs([
       '--frontendUrl=' + url,
       '--windowKey=' + windowKey,
     ]);
   },
 
-  async unstable_prepareFuseboxShell(
+  async prepareDebuggerShell(
     prebuiltBinaryPath?: ?string,
   ): Promise<DebuggerShellPreparationResult> {
     return await unstable_prepareDebuggerShell();
   },
 };
 
-export default DefaultBrowserLauncher;
+export default DefaultToolLauncher;