Skip to content

inspector: send each command response only to the client that sent the command - #46908

Closed
robobun wants to merge 2 commits into
mainfrom
robobun/ec80e5f4/inspector-response-to-requester
Closed

robobun wants to merge 2 commits into
mainfrom
robobun/ec80e5f4/inspector-response-to-requester

Conversation

@robobun

@robobun robobun commented Oct 25, 2026

Copy link
Copy Markdown
Collaborator

Do not merge with this pin. It is the preview build of oven-sh/WebKit#899.

Problem

  • With two inspector clients on one process, each command response goes to both. A client with the same id pending takes the other client's result.
  • With inspector.open(), one client and an in-process inspector.Session are enough. It also happens on bun --inspect and the BUN_INSPECT socket.
  • Cause: JavaScriptCore's FrontendRouter::sendResponse() sends to every frontend channel. BunInspectorConnection dispatches without naming itself (src/jsc/bindings/BunDebugger.cpp:370, :384).

Fix

  • [JSC] Inspector: a command's response goes to the frontend channel that sent it WebKit#899 makes BackendDispatcher::dispatch() take the sending channel, and sends each response to that channel only. This PR pins its preview build and passes *this at the two dispatch calls.
  • A maintainer must decide if the fork takes that change (Notes).
  • Self-reviewed: 10 concerns raised, 10 addressed.
  • Verified: 14 new tests in test/cli/inspect/inspect.test.ts and test/js/node/inspector/inspector.test.ts fail on main and pass here. Both directories: 139 pass, 0 fail.

Background

Downsides

  • The WebKit fork carries 30 more USE(BUN_JSC_ADDITIONS) guard lines in 11 files.
  • A response for a client that disconnected is dropped. Before, the other clients received it.
  • Release .text grows by 768 bytes. Per command with one client: 1,354 to 1,353 instructions, 68 to 68 allocator calls.
Notes

Decision needed. The behaviour change is in the WebKit fork. There are three answers, and a maintainer chooses one:

  1. No fork change. Then inspector.open() gets one backend id counter for all adapters (node:inspector: route CDP responses to the right client when multiple are attached #35701, closed by the stale bot, or the id ranges in inspector: CDP on --inspect, node announce lines, Session, Profiler adapter, Network, exit handshake, async stacks (+9 tests, inspector 11%→22%) #34719). bun --inspect and the BUN_INSPECT socket keep the defect.
  2. This change: [JSC] Inspector: a command's response goes to the frontend channel that sent it WebKit#899, +169/-1 lines. It fixes the responses on every transport.
  3. One inspector session for each frontend, the larger design in the comment on #35752. It would replace most of [JSC] Inspector: a command's response goes to the frontend channel that sent it WebKit#899. The dispatch entry that names the sender, and the two lines in BunDebugger.cpp, stay.

Designs considered.

  • One backend id counter for all adapters in cdp.ts (node:inspector: route CDP responses to the right client when multiple are attached #35701). It is 2 lines and exact for inspector.open(). The other transports have no adapter, and JavaScriptCore still sends each response to each channel.
  • A router in BunDebugger.cpp in front of one JavaScriptCore channel. It needs no fork change. It must parse each command a second time to rewrite its id, and it copies connection state that JavaScriptCore already has.
  • One backend dispatcher for each frontend in JavaScriptCore. It also answers each client alone, but it allocates a dispatcher and 11 domain dispatchers for each attach and changes 13 agent classes.
  • A sender identifier through BackendDispatcher (this change). It adds nothing for one client and fixes every transport.

Origin. A maintainer reported the inspector.open() form in chat. No user issue reports crossed responses. #35701 fixed that form in cdp.ts and was closed by the stale bot with no review.

Repro on main (179664e). Two WebSocket clients on bun --inspect, and each sends {"id":1,"method":"Runtime.evaluate",...}. Client A received ["1:answer-for-A","1:answer-for-B"] and B received the same two, in 3 of 3 rounds. With ids 1 and 2, each client still received both responses. On inspector.open(): A got "answer-for-A", B got "answer-for-A", 3 of 3 rounds. On this branch: 0 of 3 in each form.

Reach. A client that receives a response with an id it does not have pending usually drops it. It takes a foreign result only when the same id is pending. That is certain when two commands overlap, and each new test makes them overlap. Debugger.enable from two clients shows the effect: on main each client receives {} and error -32000 Debugger domain already enabled, so the second client can read a success. On this branch the first gets {} and the second gets the error.

What is still wrong with two clients. This PR changes responses only.

  • The process has one set of agents. A second client's Debugger.enable gets Debugger domain already enabled.
  • When one client closes, the agents of the other are disabled (inspector: keep agents enabled when one of several --inspect clients disconnects #36884): after the close the other client received 0 of 5 console events, on main and on this branch.
  • Events go to every client, also to one that did not enable the domain. The VS Code adapter depends on that for a shared debugger.
  • A client that attaches while another client is paused is answered after the resume.
  • With bun test --isolate, a client that attached in the first file gets no reply after the runner moves to the next file, on main and on this branch. On main a client that attaches later receives those replies. On this branch no client receives them.
  • On inspector.open(), a message that is not JSON gets no reply at all (cdp.ts returns). Node answers the sender.

Other open pull requests. #34719 adds a third dispatchMessageFromRemote call (BunDebugger.cpp:1143 at its head 30097ed) for its InProcessInspectorChannel. After this change that call must pass its channel, or it does not compile. Its id ranges for remote adapters are then not necessary. #36884 changes BunInspectorConnection::disconnect and does not conflict.

The gate cannot run its fail-before step. oven-sh/WebKit#899 replaces the dispatch entries that carry no channel, so a caller that does not name its channel does not compile. src/ of main with this pin fails at BunDebugger.cpp:370 and :384 (too few arguments). The fail-before evidence is main's own release build: 14 of 14 new tests fail, in 20 of 20 runs. With bun bd test on this branch, 14 of 14 pass.

The new tests, and the result on main.

Test On main
--inspect: each client gets the response to its own command, and an idle client gets none B's id 1 is answered answer-for-A. The idle client receives both responses.
--inspect: the response to Runtime.awaitPromise goes to the client that awaited A's pending id 2 is answered with B's second-for-B.
--inspect: the response for a client that closed is not sent to the client that remains B receives 2:awaited-by-A.
--inspect: a second client's command is answered to it while the first client's command is paused A receives B's responses during the pause.
--inspect: the error of a command that fails goes to the client that sent it The idle client receives 1:error -32000.
--inspect: the error of an awaited promise that fails later goes to the client that awaited B receives A's responses, and A receives B's.
--inspect: the error for a message that is not JSON goes to its sender B receives {"error":{"code":-32700,...},"id":null}.
--inspect: a command from a client that closes before the inspected thread sees it is answered to no client A receives 1:answer-for-late.
BUN_INSPECT unix socket and --inspect WebSocket on one process The WebSocket client's id 1 is answered answer-for-unix.
inspector.open(): two clients each get the result of their own Runtime.evaluate B gets released, which is A's result.
inspector.open(): the error of a failed command goes to the client that sent it B's successful command is answered error -32000.
inspector.open(): the result of an awaited promise goes to the client that awaited A's awaited command is answered second-for-B.
inspector.open(): an in-process inspector.Session does not answer a client The client's awaited command is answered by the Session's Debugger.setBreakpointsActive.
inspector.open(): a client of a reopened inspector does not get the result the previous client awaited The new client's second command is answered awaited-by-previous.

An assertion that a message did not arrive follows a round trip on the same client (settle() in test/cli/inspect/inspector-client.ts), not a sleep. The inspectee sends the responses and the events for one client through one ordered queue. The pause test also checks that the second client receives Debugger.paused and Debugger.resumed.

Measurements. Linux x64, release builds with LTO: main 179664e (WebKit 680ef47c) against this branch (WebKit preview-pr-899-ba39e0db).

What Before After
Instructions per command, one client, in the functions the change touches 1,354 1,353
Conditional branches, same path 175 175
Allocator calls per command (inspected thread) 68 68
Allocator calls, first attach / second attach 82 / 30 82 / 30
Instructions per event identical disassembly
.text of bun-profile 82,164,617 82,165,385
Stripped bun file 107,730,656 107,730,656
sizeof FrontendChannel / FrontendRouter / BackendDispatcher / CallbackBase 8 / 40 / 72 / 40 16 / 40 / 80 / 48
Channel deliveries for 1,000 responses, second client idle 2,000 1,000
Bytes sent to an idle second --inspect client for 20 responses of 8.4 MB 167.8 MB 0
  • Instructions: gdb single-step on the inspected thread, from the entry of BunInspectorConnection::receiveMessagesOnInspectorThread to its return, for Runtime.evaluate "1". It counts that function, JSGlobalObjectDebuggable::dispatchMessageFromRemote, BackendDispatcher::* and RuntimeBackendDispatcher::* (with the inlined FrontendRouter::sendResponse). Callees outside that set are the same code in both builds and are not counted. 12 of 12 samples were equal in each build.
  • Events: the normalized disassembly of BunInspectorConnection::sendMessageToFrontend, ConsoleFrontendDispatcher::messageAdded (with the inlined FrontendRouter::sendEvent loop) and DebuggerFrontendDispatcher::scriptParsed is identical in both builds.
  • Allocator calls: gdb breakpoints on the mi_* entry points. The value for a command is the steady state.
  • Each global object has one BackendDispatcher, with or without an inspector. mimalloc puts 72 and 80 bytes in the same 80-byte size class, so a process with no inspector uses the same heap bytes. CallbackBase is one object for each pending asynchronous command.
  • Channel deliveries: calls of BunInspectorConnection::sendMessageToFrontend for each channel, on bun --inspect and on inspector.open(). The idle client's channel went from 1,000 to 0.
  • Debugger thread CPU for those 20 large responses, in 3 interleaved runs: 90 to 120 ms before and 50 to 70 ms after on bun --inspect, 140 to 160 ms before and 90 to 110 ms after on inspector.open().

Parity with Node. For 8 inspector.open() call orders whose transcript is stable under node v26.3.0, main gives node's transcript in 3 and this branch in 7. The one left differs by events: a client receives Debugger.scriptParsed after an in-process Session enabled the Debugger domain.

Fork carry. The fork patch adds 30 guard lines, 19 of them with an #else that keeps the upstream line. Upstream plans to remove legacy_async_callbacks from the inspector code generator (WebKit bug 288203). After that, the generated asynchronous commands do not compile in the fork until they capture the requester. That compile error is intended.

Test runs. bun bd test test/cli/inspect/ test/js/node/inspector/: 139 pass, 5 todo, 0 fail in 10 files. One test that this PR does not change, inspector.open() can be retried after a failed start, timed out in 3 of 30 runs of the debug build. In the hung process the debugger thread waits in JSC::Heap::collectSync during inspector.close(). No inspector client is attached in that test, so the change is not on that path. The release builds of main and of this branch passed it 60 of 60 times.

Fork CI for oven-sh/WebKit#899 built every lane. One JSC stress test failed on one of the three tested lanes (stress/tagged-templates-in-direct-eval-should-not-produce-same-site-object.js.dfg-eager, hardened lane). It does not use the inspector.

…e command

With two or more inspector clients attached to one process, each client
received the responses to the commands of every other client. Two clients
that use the same command id (each counts from 1) took each other's
results. This happened on `bun --inspect`, on the unix socket transport of
`BUN_INSPECT`, and on `inspector.open()` from node:inspector.

JavaScriptCore sent each response to every frontend channel. The WebKit
build that this commit pins (the preview build of oven-sh/WebKit#899)
makes BackendDispatcher::dispatch() take the channel that sent the
command, and sends the response to that channel only.
BunInspectorConnection passes itself at its two dispatch calls.
…lient

The error of a command that fails, at once or when an awaited promise
settles, goes to the client that sent the command. A second client still
receives Debugger.paused and Debugger.resumed. On inspector.open(), a
client's successful command is not answered with another client's error.
@robobun

robobun commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 12:33 PM PT - Oct 25th, 2026

✅ @robobun, your commit 396c4ff2a114072d328895877ab12196a664f1bb passed in Build #132702! 🎉


🧪   To try this PR locally:

bunx bun-pr 46908

That installs a local version of the PR into your bun-46908 executable, so you can run:

bun-46908 --bun

@robobun

robobun commented Oct 25, 2026

Copy link
Copy Markdown
Collaborator Author

Status: reproduced on main (179664e).

  • bun --inspect: two WebSocket clients each send Runtime.evaluate as id 1. Each client receives both responses, in 3 of 3 rounds.
  • inspector.open(): client B receives client A's result under its own id, in 3 of 3 rounds.
  • This branch: 0 of 3 rounds in both forms.

The behaviour change is in oven-sh/WebKit#899. This pull request stays a draft until that one lands, and then the pin moves to its merge commit.

@robobun

robobun commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator Author

A fourth answer for the "Decision needed" list in the description. It comes from the bun test --isolate item under "What is still wrong with two clients".

4. Bun owns the inspector controller, one for each VM. No fork change.

Today each global object has its own JSGlobalObjectInspectorController. bun test --isolate and each bun test --parallel worker replace the global object between test files. A client that attached in one file then has no session in the next file: its commands get no reply, and it gets no Console or Debugger event from later files.

The branch robobun/b028d669/inspector-follows-isolation-swap is a working implementation. It is not a pull request.

What a yes changes for the other open work

What it costs

  • Bun carries about 470 lines that mirror JavaScriptCore's controller and three of its agents. Each WebKit upgrade must check them against the new sources.
  • The branch is 22 files, +1255/-251. A self-review found open items. The main ones: a Worker reads the inspector URL of the main thread (the node:inspector part must become a separate change), the global of a finished file stays inspectable, and the hand-over of the context identifier has no test.

The question

Should Bun own the inspector controller (this answer)? The alternative is that the fork's controller learns to move between the global objects of one VM.

The defects that this answers

The effects, all with --isolate:

  1. A client from an earlier file gets no reply to a command (the reproduction below), and no Console or Debugger event from later files.
  2. A second client that attaches in a later file gets 'TestReporter' domain was not found for TestReporter.enable. Bun registers the agents of its own domains once for the process, on the first controller that a client attaches to.
  3. The global of the file in which a client attached stays alive while that client is attached. If that file logs to the console after the attach, its global stays alive to the end of the run, also after the client left: the inspector keeps the message, and the message keeps the global.
  4. From the code, not reproduced: a message that the debugger thread posts while the global is replaced can be lost, and the connection is then silent. Zig__GlobalObject__createForTestIsolation removes the context identifier from the map before the new global registers it. ScriptExecutionContext::postTaskTo returns false in that interval, sendMessageToInspectorFromDebuggerThread does not read the result, and jsThreadMessageScheduledCount stays above zero.

No issue tracks these four effects yet. Until one exists, this comment is the reference for them. #47113 repairs only the crashes in this area.

Reproduction of effect 1

a.test.ts, and b.test.ts with "b" in place of "a":

import { test } from "bun:test";

test("a", async () => {
  globalThis.file = "a";
  console.error("READY a");
  await new Promise(resolve => (globalThis.release = resolve));
});

driver.mjs:

// bun driver.mjs [--isolate]
import { spawn } from "node:child_process";

const child = spawn(process.execPath, ["test", ...process.argv.slice(2), "--inspect=127.0.0.1:0", "./a.test.ts", "./b.test.ts"], {
  stdio: ["ignore", "ignore", "pipe"],
});
let stderr = "";
child.stderr.on("data", chunk => (stderr += chunk));
const seen = async pattern => {
  for (;;) {
    const match = stderr.match(pattern);
    if (match) return match;
    await new Promise(resolve => setTimeout(resolve, 10));
  }
};

const socket = new WebSocket((await seen(/^\s*(ws:\/\/\S+)$/m))[1]);
await new Promise(resolve => (socket.onopen = resolve));
const replies = new Map();
socket.onmessage = ({ data }) => {
  const message = JSON.parse(data);
  replies.get(message.id)?.(message.result?.result?.value);
};
let id = 0;
const evaluate = expression =>
  Promise.race([
    new Promise(resolve => {
      replies.set(++id, resolve);
      socket.send(JSON.stringify({ id, method: "Runtime.evaluate", params: { expression } }));
    }),
    new Promise(resolve => setTimeout(resolve, 2000, "no reply in 2 s")),
  ]);

await seen(/^READY a$/m);
console.log("in a.test.ts:", await evaluate("globalThis.file"));
await evaluate("globalThis.release()");
await seen(/^READY b$/m);
console.log("in b.test.ts:", await evaluate("globalThis.file"));
child.kill();
process.exit(0);
$ bun driver.mjs
in a.test.ts: a
in b.test.ts: b
$ bun driver.mjs --isolate
in a.test.ts: a
in b.test.ts: no reply in 2 s

Bun 1.4.4 and main give this output on Linux x64.

Bun 1.4.4 and main give this output on Linux x64.

@robobun

robobun commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Closing as stale: this PR conflicts with main, and its last commit is from 2026-10-25.

The branch stays, so the work is not lost. To pick it up again, rebase the branch on main and reopen this PR.

@robobun robobun closed this Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants