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
This commit is contained in:
Alex Hunt authored and meta-codesync[bot] committed 2026-02-26 12:12:16 -08:00
1 parent 58d94863f8
commit 4206c12180
9 files changed
+67 -72

No files matched your search

@@ -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 {
@@ -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
});
});
@@ -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,
/**
* An implementation for logging messages to the terminal (recommended).
*
* In `@react-native/community-cli-plugin`, this reuses Metro's
* 'unstable_server_log' event in `TerminalReporter`.
*/
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.
* 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,
+3 -3
View File
@@ -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';
@@ -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,7 +44,7 @@ type Options = Readonly<{
export default function openDebuggerMiddleware({
serverBaseUrl,
logger,
browserLauncher,
toolLauncher,
eventReporter,
experiments,
inspectorProxy,
@@ -52,7 +52,7 @@ export default function openDebuggerMiddleware({
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();
@@ -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>;
}
@@ -8,7 +8,7 @@
* @format
*/
import type {DebuggerShellPreparationResult} from './BrowserLauncher';
import type {DebuggerShellPreparationResult} from './DevToolLauncher';
type SuccessResult<Props: {...} | void = {}> = {
status: 'success',
@@ -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
@@ -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;