Skip to content

Add multi-session support to InspectorPackagerConnection #55238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
motiz88 wants to merge 1 commit into from
+1,021 −81
Closed

Add multi-session support to InspectorPackagerConnection #55238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 47 additions & 19 deletions packages/dev-middleware/src/inspector-proxy/__docs__/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,20 +101,20 @@ interface Message {

#### Proxy → Device Messages

| Event | Payload | Description |
| -------------- | ------------------------------------------ | --------------------------------------------- |
| `getPages` | _(none)_ | Request current page list. Sent periodically. |
| `connect` | `{ pageId: string }` | Prepare for debugger connection to page. |
| `disconnect` | `{ pageId: string }` | Terminate debugger session for page. |
| `wrappedEvent` | `{ pageId: string, wrappedEvent: string }` | Forward CDP message (JSON string) to page. |
| 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 }` | Notify that page disconnected or rejected connection. |
| `wrappedEvent` | `{ pageId: string, wrappedEvent: string }` | Forward CDP message (JSON string) from page. |
| 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

Expand All @@ -128,10 +128,14 @@ interface Page {
nativePageReloads?: boolean; // Target keeps the socket open across reloads
nativeSourceCodeFetching?: boolean; // Target supports Network.loadNetworkResource
prefersFuseboxFrontend?: boolean; // Target is designed for React Native DevTools
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:**
Expand All @@ -155,16 +159,18 @@ Debugger Proxy Device
│ │ │
│── WS Connect ───▶│ │
│ ?device&page │── connect ────────────────▶│
│ │ {pageId} │
│ │ {pageId, sessionId} │
│ │ │
│── CDP Request ──▶│── wrappedEvent ───────────▶│
│ │ {pageId, wrappedEvent} │
│ │ {pageId, sessionId, │
│ │ wrappedEvent} │
│ │ │
│ │◀── wrappedEvent ───────────│
│◀── CDP Response ─│ {pageId, wrappedEvent} │
│◀── CDP Response ─│ {pageId, sessionId, │
│ │ wrappedEvent} │
│ │ │
│── WS Close ─────▶│── disconnect ─────────────▶│
│ │ {pageId} │
│ │ {pageId, sessionId} │
```

**Connection Rejection:**
Expand All @@ -174,12 +180,34 @@ a `disconnect` back to the proxy for that `pageId`.

### Connection Semantics

1. **One Debugger Per Page**: New debugger connections to an already-connected
page disconnect the existing debugger.
#### 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.

2. **Device Reconnection**: If a device reconnects with the same `device` ID,
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 connection.
to the new device.

### WebSocket Close Reasons

Expand Down
Loading
Loading