@react-native/dev-middleware
Version:
Dev server middleware for React Native
325 lines (244 loc) • 13.8 kB
Markdown
# Inspector Proxy Protocol
[🏠 Home](../../../../../__docs__/README.md)
The inspector-proxy protocol facilitates Chrome DevTools Protocol (CDP) target
discovery and communication between **debuggers** (e.g., Chrome DevTools, VS
Code) and **devices** (processes containing React Native hosts). The proxy
multiplexes connections over a single WebSocket per device, allowing multiple
debuggers to connect to multiple pages on the same device.
## 🚀 Usage
### Target Discovery (HTTP)
We implement a subset of the
[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)'s
[HTTP endpoints](https://chromedevtools.github.io/devtools-protocol/#:~:text=a%20reconnect%20button.-,HTTP%20Endpoints,-If%20started%20with)
to allow debuggers to discover targets.
| Endpoint | Description |
| --------------------------- | ------------------------ |
| `GET /json` or `/json/list` | List of debuggable pages |
| `GET /json/version` | Protocol version info |
### Device Registration (WebSocket)
Devices register themselves with the proxy by connecting to `/inspector/device`:
```text
ws://{host}/inspector/device?device={id}&name={name}&app={bundle_id}&profiling={true|false}
```
| Parameter | Required | Description |
| ----------- | -------- | ------------------------------------------------------------ |
| `device` | No\* | Logical device identifier. Auto-generated if omitted. |
| `name` | No | Human-readable device name. Defaults to "Unknown". |
| `app` | No | App bundle identifier. Defaults to "Unknown". |
| `profiling` | No | "true" if this is a profiling build. (Used for logging only) |
\*Recommended for connection persistence across app restarts.
#### Requirements for the `device` parameter
The intent of the logical device ID is to help with target discovery and
especially *re*discovery - to reduce the number of times users need to
explicitly close and restart the debugger frontend (e.g. after an app crash).
If provided, the logical device ID:
1. SHOULD be stable for the current combination of physical device (or emulator
instance) and app.
2. SHOULD be stable across installs/launches of the same app on the same device
(or emulator instance), though it MAY be user-resettable (so as to not
require any special privacy permissions).
3. MUST be unique across different apps on the same physical device (or
emulator).
4. MUST be unique across physical devices (or emulators).
5. MUST be unique for each concurrent _instance_ of the same app on the same
physical device (or emulator).
NOTE: The uniqueness requirements are stronger (MUST) than the stability
requirements (SHOULD). In particular, on platforms that allow multiple instances
of the same app to run concurrently, requirements 1 and/or 2 MAY be violated in
order to meet requirement 5. This is relevant, for example, on desktop
platforms.
### Debugger Connection (WebSocket)
Debuggers connect to `/inspector/debug` to form a CDP session with a page:
```text
ws://{host}/inspector/debug?device={device_id}&page={page_id}
```
Both `device` and `page` query parameters are required.
## 📐 Design
### Architecture
```text
┌─────────────────┐ ┌─────────────────────────┐ ┌────────────────┐
│ Debugger │────▶│ Inspector Proxy │◀────│ Device │
│ (Chrome/VSCode) │ │ (Node.js) │ │ (iOS/Android) │
└─────────────────┘ └─────────────────────────┘ └────────────────┘
WebSocket HTTP + WebSocket WebSocket
/inspector/debug /json, /json/list /inspector/device
/json/version
```
### Device ↔ Proxy Protocol
All messages are JSON-encoded WebSocket text frames:
```typescript
interface Message {
event: string;
payload?: /* depends on event */;
}
```
#### Proxy → Device Messages
| Event | Payload | Description |
| -------------- | ------------------------------------------------------------- | --------------------------------------------- |
| `getPages` | _(none)_ | Request current page list. Sent periodically. |
| `connect` | `{ pageId: string, sessionId: string }` | Prepare for debugger connection to page. |
| `disconnect` | `{ pageId: string, sessionId: string }` | Terminate debugger session for page. |
| `wrappedEvent` | `{ pageId: string, sessionId: string, wrappedEvent: string }` | Forward CDP message (JSON string) to page. |
#### Device → Proxy Messages
| Event | Payload | Description |
| -------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
| `getPages` | `Page[]` | Current list of inspectable pages. |
| `disconnect` | `{ pageId: string, sessionId?: string }` | Notify that page disconnected or rejected connection. |
| `wrappedEvent` | `{ pageId: string, sessionId?: string, wrappedEvent: string }` | Forward CDP message (JSON string) from page. |
#### Page Object
```typescript
interface Page {
id: string; // Unique page identifier (typically numeric string)
title: string; // Display title
app: string; // App bundle identifier
description?: string; // Additional description
capabilities?: {
nativePageReloads?: boolean; // Target keeps the socket open across reloads
nativeSourceCodeFetching?: boolean; // Target supports Network.loadNetworkResource
supportsMultipleDebuggers?: boolean; // Supports concurrent debugger sessions
};
}
```
**Note**: The value of `supportsMultipleDebuggers` SHOULD be consistent across
all pages for a given device.
### Connection Lifecycle
**Device Registration:**
```text
Device Proxy
│ │
│──── WS Connect ─────────────────▶│
│ /inspector/device?... │
│ │
│◀──── getPages ───────────────────│ (periodically)
│ │
│───── getPages response ─────────▶│
│ (page list) │
```
**Debugger Session:**
```text
Debugger Proxy Device
│ │ │
│── WS Connect ───▶│ │
│ ?device&page │── connect ────────────────▶│
│ │ {pageId, sessionId} │
│ │ │
│── CDP Request ──▶│── wrappedEvent ───────────▶│
│ │ {pageId, sessionId, │
│ │ wrappedEvent} │
│ │ │
│ │◀── wrappedEvent ───────────│
│◀── CDP Response ─│ {pageId, sessionId, │
│ │ wrappedEvent} │
│ │ │
│── WS Close ─────▶│── disconnect ─────────────▶│
│ │ {pageId, sessionId} │
```
**Connection Rejection:**
If a device cannot accept a `connect` (e.g., page doesn't exist), it should send
a `disconnect` back to the proxy for that `pageId`.
### Connection Semantics
#### Multi-Debugger Support
Multiple debuggers can connect simultaneously to the same page when **both** the
proxy and device support session multiplexing:
1. **Session IDs**: The proxy assigns a unique, non-empty `sessionId` to each
debugger connection. All messages include this `sessionId` for routing. This
SHOULD be a UUID or other suitably unique and ephemeral identifier.
2. **Capability Detection**: Devices report `supportsMultipleDebuggers: true` in
their page capabilities to indicate session support.
3. **Backwards Compatibility**: Legacy devices ignore `sessionId` fields in
incoming messages and don't include them in responses.
#### Connection Rules
1. **Session-Capable Device**: Multiple debuggers can connect to the same page
simultaneously. Each connection has an independent session.
2. **Legacy Device (no `supportsMultipleDebuggers`)**: New debugger connections
to an already-connected page disconnect the existing debugger. The proxy MUST
NOT allow multiple debuggers to connect to the same page.
3. **Device Reconnection**: If a device reconnects with the same `device` ID
while debugger connections to the same logical device are open in the proxy,
the proxy may attempt to preserve active debugger sessions by forwarding them
to the new device.
### WebSocket Close Reasons
The proxy uses specific close reasons that DevTools frontends may recognize:
| Reason | Context |
| ----------------------- | --------------------------------------- |
| `[PAGE_NOT_FOUND]` | Debugger connected to non-existent page |
| `[CONNECTION_LOST]` | Device disconnected |
| `[RECREATING_DEVICE]` | Device is reconnecting |
| `[NEW_DEBUGGER_OPENED]` | Another debugger took over this page |
| `[UNREGISTERED_DEVICE]` | Device ID not found |
| `[INCORRECT_URL]` | Missing device/page query parameters |
### PageDescription (HTTP Response)
The `/json` endpoint returns enriched page descriptions based on those reported
by the device.
```typescript
interface PageDescription {
// Used for target selection
id: string; // "{deviceId}-{pageId}"
// Used for display
title: string;
description: string;
deviceName: string;
// Used for target matching
appId: string;
// Used for debugger connection
webSocketDebuggerUrl: string;
// React Native-specific metadata
reactNative: {
logicalDeviceId: string; // Used for target matching
capabilities: {
nativePageReloads?: boolean; // Used for target filtering
};
};
}
```
## 🔗 Relationship with other systems
### Part of this
- **Device.js** - Per-device connection handler in the proxy
- **InspectorProxy.js** - Main proxy HTTP/WebSocket server
### Used by this
- **Chrome DevTools Protocol (CDP)** - The wrapped messages are CDP messages
exchanged between DevTools frontends and JavaScript runtimes.
- **WebSocket** - Transport layer for device and debugger connections.
### Uses this
- **InspectorPackagerConnection (C++)** - Shared device-side protocol
implementation in `ReactCommon/jsinspector-modern/`.
- **Platform layers** - iOS (`RCTInspectorDevServerHelper.mm`), Android
(`DevServerHelper.kt`), and ReactCxxPlatform (`Inspector.cpp`) provide
WebSocket I/O and threading.
- **openDebuggerMiddleware** - Uses `/json` to discover targets for the
`/open-debugger` endpoint.
- **OpenDebuggerKeyboardHandler** - Uses `/json` to display target selection in
the CLI.
---
## Legacy Features
The following features exist for backward compatibility with older React Native
targets that lack modern capabilities. New implementations should set
appropriate capability flags and may ignore this section.
### Synthetic Reloadable Page (Page ID `-1`)
For targets without the `nativePageReloads` capability, the proxy exposes a
synthetic page with ID `-1` titled "React Native Experimental (Improved Chrome
Reloads)". Debuggers connecting to this page are automatically redirected to the
most recent React Native page, surviving page reloads.
When a new React Native page appears while a debugger is connected to `-1`:
1. Proxy sends `disconnect` for the old page, `connect` for the new page
2. Proxy sends `Runtime.enable` and `Debugger.enable` CDP commands to the new
page
3. When `Runtime.executionContextCreated` is received, proxy sends
`Runtime.executionContextsCleared` to debugger, then `Debugger.resume` to
device
### URL Rewriting
For targets without the `nativeSourceCodeFetching` capability, the proxy
rewrites URLs in CDP messages:
- **Debugger.scriptParsed** (device → debugger): Device-relative URLs are
rewritten to debugger-relative URLs
- **Debugger.setBreakpointByUrl** (debugger → device): URLs are rewritten back
to device-relative form
- **Debugger.getScriptSource**: Intercepted and handled by proxy via HTTP fetch
- **Network.loadNetworkResource**: Returns CDP error (code -32601) to force
frontend fallback
Additionally, if a script URL matches `^[0-9a-z]+$` (alphanumeric ID), the proxy
prepends `file://` to ensure Chrome downloads source maps.
### Legacy Reload Notification
For targets without `nativePageReloads`, when a `disconnect` event is received
for a page, the proxy sends `{method: 'reload'}` to the connected debugger to
signal a page reload.