Skip to content

engine: let a browser session outlive its client and serve several - #186

Open
ruifigueira wants to merge 3 commits into
mainfrom
rfigueira/browser-session-multi-client
Open

ruifigueira wants to merge 3 commits into
mainfrom
rfigueira/browser-session-multi-client

Conversation

@ruifigueira

@ruifigueira ruifigueira commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Stacked on #182. Review only the last three commits. The base branch is rfigueira/browser-session-split, so the diff shows only this work.

#182 splits the browser session from its CDP client, with one client per session. This pull request lets a session outlive its client and serve more than one CDP client. These changes were in the first version of #182. They moved here after the review of #182 found that the code does not enforce per-client ownership.

This pull request is a draft. It has the same code as that first version. It does not yet address the review findings that the next section lists. Only the unit tests turn on persistent, so this pull request changes no traffic.

No issue tracks this work yet.

Findings to address before review

From the review of #182 (summary):

  1. Root-session domain enables and scene streams:
    • A root enable uses the shared key "", so a departed client's enables stay, and their events go to every client.
    • Give each client its own key for root enables.
    • Give each scene stream an owner client, and stop the streams of a client that leaves.
  2. Fetch ownership:
    • Deliver Fetch.requestPaused to the owner only.
    • Check the owner in Fetch.enable, Fetch.disable, Fetch.continueRequest, Fetch.fulfillRequest and Fetch.failRequest.
    • On takeover, release the parked requests of the previous owner.
  3. Screencast ownership:
    • Deliver Page.screencastFrame and the visibility events to the owner only.
    • Check the owner in Page.stopScreencast and Page.screencastFrameAck.
  4. Page.addScriptToEvaluateOnNewDocument: the engine records each script on its client, but runs it from one browser-wide map. Run each script only in the pages of its client.
  5. detachClientSession clears memoryTargets.renderer but not memoryTargets.engine.
  6. BrowserSession and attachClient are not exported from embed.ts, so no host can turn the feature on, and the hermetic e2e lane cannot test it. Export them, and add an e2e test with two clients.

From a second review:

  1. BrowserSession.close() and the wall-clock cap close each client before dispose() marks the session as ended. As a result, #releaseClient and onClientLeft run for each client while the session ends. Set the ended flag first.
  2. Target.createTarget auto-attaches page-mode clients. Target.setAutoAttach excludes them. Apply the same check in createTarget.
  3. ClientConnection.start() announces existing pages with browserContextId: "default", also for pages in another browser context. Use the context of the target.
  4. A DOM.getDocument that completes after its client left builds frontend nodes again, and the late cleanup does not find them. The client's session list is already empty at that time.

Dependency:

  1. Retired page isolates stay alive until the CDP connection closes #165: retired page isolates stay pinned to the request context that created the session. A persistent session keeps that context for its whole life, so Retired page isolates stay alive until the CDP connection closes #165 must be fixed before a host turns on persistent.

Behavior and API impact

None for current traffic: handleWebSocket builds a non-persistent session with one client. With persistent: true:

  • Each client has its own Target.setAutoAttach state, its own CDP sessions and its own new-document scripts.
  • Events on a CDP session go only to the client that owns that session. Other events go to every client. Findings 1 to 3 are the exceptions that must be fixed.
  • Every client with auto-attach on gets its own session on a new page, iframe or OOPIF.
  • The idle deadline closes only the idle client. The wall-clock cap and Browser.close end the session for all clients.
  • When a client leaves, the session releases what that client held: its CDP sessions, screencasts, new-document scripts and Fetch interception.
  • A client cannot detach a session that another client attached.

DispatchCtx gets two new required fields: peers() and emitToClient.

Implementation

  1. Persistent sessions: BrowserSession keeps a map of clients and routes events by CDP session. CdpClientState gets back id and sessions for this. The first client opens the browser and its initial page, and a later client receives announcements of the pages that exist. The deadlines and Browser.close apply as the previous section describes.
  2. Target announcements: iframe, OOPIF and new-page targets go to every client that can see them. The renderer and engine Memory-panel targets move to the client (CdpClientState.memoryTargets).
  3. Cleanup when a client leaves: a persistent session releases what the client held. CdpClientState gets back preNavScriptIds for this. If a command is still in progress when the client leaves, the cleanup runs again when the command completes.

Validation

  • bazel test //packages/engine:types //packages/engine:vitest: passes on each of the three commits.
  • bazel test //:check: 33 of 33 pass.
  • pnpm run test:e2e browser-close: 1 passed.
  • pnpm run test:e2e session-deadlines: 3 passed.
  • pnpm run test:e2e browser-context.e2e: 5 passed.
  • packages/engine/test/browser-session.test.ts tests a persistent session with two clients: target announcements, routing, per-client auto-attach, cleanup when a client leaves and the idle deadline.

No e2e test connects two clients, because finding 6 is open.

Checklist

  • This pull request solves one problem; see CONTRIBUTING.md.
  • Every commit has a Signed-off-by line (git commit -s); see CONTRIBUTING.md.
  • Added or updated focused tests for behavior changes. Unit tests only. The e2e test waits on finding 6.
  • Updated documentation and generated files, or confirmed they do not apply.

beep-boop-🤖

@ruifigueira
ruifigueira added this pull request to stack #187 November 20, 2026 08:10
@ruifigueira
ruifigueira marked this pull request as ready for review November 20, 2026 11:08
@BernardoPe BernardoPe self-assigned this Nov 20, 2026
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-multi-client branch 2 times, most recently from e578178 to 6959fa2 Compare November 20, 2026 11:52
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-multi-client branch from 6959fa2 to a0c3b6c Compare November 20, 2026 12:04
Base automatically changed from rfigueira/browser-session-split to main November 20, 2026 12:34
A BrowserSession has one client and ends when that client leaves. A
host that keeps a browser across connections, or lets two CDP clients
share one, needs more than that.

A persistent option lets a session outlive its clients and accept more
than one. Then the idle deadline closes only the idle client, the
wall-clock cap closes every client and ends the session, and
Browser.close ends the session. The first client opens the browser and
its initial page; a later client hears of the pages that exist.

BrowserSession.route sends an event on a CDP session to the client that
owns it, and drops it when no client does; other events go to every
client. For that, CdpClientState gains an id and the set of sessions
the client attached, which the target code records. Nothing outside
tests turns the option on.

A non-persistent session is unchanged: it has one client, route() sends
it everything, and the session ends when its socket closes.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
Target announcements followed the dispatching context. With more than
one client on a browser, only the client whose command or navigation
found a frame or page would hear about it:

- Iframe targets reached only the navigating client. emitFrameTarget
  now announces the frame to every browser-mode client and attaches
  each one that has auto-attach on. When the frame goes away, its
  targetDestroyed goes to the clients that could have seen it.
- An OOPIF's page-mode target went only to the client that spawned it,
  and a client that turned on auto-attach later got another client's
  session back. Each page-mode client now gets its own session.
- Target.createTarget attached only the creator. Every client with
  auto-attach on now gets its own session on the new page, as in
  Chrome, and the setAutoAttach backfill no longer skips a page because
  another client is attached to it.
- The synthetic renderer and engine Memory-panel targets had one
  session each on BrowserState, owned by the first client to ask. They
  now live on the client (CdpClientState.memoryTargets), so each client
  is announced and answered on its own.

DispatchCtx gains peers(), the contexts of every connected client, and
emitToClient for an event that only one client must see. With one
client, peers() is that client and every announcement is unchanged.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
When a persistent session outlives a client, the browser kept what that
client had set up. Its CDP sessions stayed attached, its screencasts
kept rendering, its new-document scripts ran on every later navigation,
and requests paused for its Fetch interception waited for an answer
that would never come.

When a client of a persistent session leaves, the session now undoes
what that client held, as Chrome does for a DevTools client that
disconnects:

- its CDP sessions detach, with their Runtime, Debugger, DOM and CSS
  enables;
- the screencasts it started or took over stop;
- its new-document scripts are removed;
- if it enabled Fetch interception, interception stops and its paused
  requests continue.

CdpClientState gains preNavScriptIds, the new-document scripts the
client added, so the session knows which ones to remove. Other clients
keep theirs. A command that was still running when the
client left runs the cleanup again when it settles. A client can no
longer detach a session another client attached. A non-persistent
session still tears everything down when its one client leaves, so the
stateless path does not change.

The new browser-session unit test covers a persistent session with two
clients: the target announcements, routing, per-client auto-attach,
cleanup on leave and the idle deadline.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-multi-client branch from a0c3b6c to 9f3b757 Compare November 20, 2026 12:34
@BernardoPe BernardoPe assigned BernardoPe and unassigned BernardoPe Nov 20, 2026

@BernardoPe BernardoPe left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

beep-boop-bernardo-agent-🤖

The default path is preserved: a non-persistent session still has one client, route broadcasts to it, and attachClient still refuses a second one. The persistent path is a sound shape, but its leave-time cleanup does not release everything a client wrote, and two target paths disagree about what a late-joining client has been told. Three findings inline; none of them is on the open list in the description, and all are on the persistent path, which no host enables yet.

Agent review: COMMENT sha=9f3b757aaaf5e835891a4b6ba0bcc063e747b325

state.sessions.clear();
state.memoryTargets.renderer = null;
state.memoryTargets.engine = null;
disableInterceptionForClient(this.id, state.id);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

beep-boop-bernardo-agent-🤖

Blocking (P2 - Correctness): a departed client's request overrides keep applying to the remaining clients

#releaseClient releases sessions, new-document scripts, screencasts and Fetch interception, but not the target-level overrides a client wrote: target.extraHttpHeaders (Network.setExtraHTTPHeaders, network.ts:46), target.userAgentOverride (Emulation.setUserAgentOverride and Network.setUserAgentOverride), target.emulatedMedia, and the viewport and scale from Emulation.setDeviceMetricsOverride.

After that client leaves, every later navigation of the shared page still merges its headers (page.ts:880), sends its user agent (page.ts:2258) and re-applies its media type (page.ts:2496). A departed client's Authorization header therefore rides on the remaining client's requests to origins it chose.

Record the writer on the client and clear or restore the fields here, next to the interception release:

// #releaseClient, after disableInterceptionForClient
for (const t of browser.targets.values()) {
  if (t.overrideClientId !== state.id) continue;
  t.extraHttpHeaders = {};
  t.userAgentOverride = "";
  t.emulatedMedia = "screen";
  t.viewportWidth = null;
  t.viewportHeight = null;
  t.deviceScaleFactor = 1;
}

// Browser-mode clients saw the frame's targetCreated; page-mode ones only their own attach.
const recipients = ctx
.peers()
.filter((p) => p.client.connectionMode === "browser" || hasClientSession(p, frame.sessions));

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

beep-boop-bernardo-agent-🤖

Blocking (P3 - Correctness): a late-joining browser-mode client is told a frame was destroyed that it never saw created

The Target.setAutoAttach backfill attaches a browser-mode client to page targets only (target.ts:162-168), and announceExistingOopifTargets covers page-mode clients alone. A client that joins a session where child frames already exist therefore gets no Target.targetCreated or Target.attachedToTarget for them. This filter then sends Target.targetDestroyed to every browser-mode peer, including one that never learned the frame existed.

Until the page navigates again, that client cannot send session-scoped commands to the existing iframes, and it receives a destroy for an unknown target. Target.getTargets does list the frames, so it can recover by attaching explicitly, but the announcement should not be missing.

Attach the joining client to existing child frames in the same backfill:

// in the Target.setAutoAttach backfill, after the page loop
for (const t of ctx.browser.targets.values()) {
  if (t.type !== "page") continue;
  for (const frame of t.frames.values()) {
    if (frame.parentFrameId === null || frame.detached) continue;
    if (hasClientSession(ctx, frame.sessions)) continue;
    const sessionId = newClientSession(ctx);
    frame.sessions.add(sessionId);
    ctx.emit({
      method: "Target.attachedToTarget",
      params: { sessionId, targetInfo: frameTargetInfo(frame), waitingForDebugger: false },
    });
  }
}

}
for (const sessionId of frame.sessions) {
ctx.browser.networkEvents.forgetSession(sessionId);
ctx.client.sessions.delete(sessionId);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

beep-boop-bernardo-agent-🤖

Blocking (P3 - Correctness): closing a page leaves other clients holding dead session ids

The target's own sessions go through detachSessions on line 415, which emits Target.detachedFromTarget and lets route remove the id from every client. Child-frame sessions take this loop instead, which removes the id from the closing client only, and then frame.sessions.clear() drops the last reference.

Every other client keeps one dead id per child frame of every page another client closes, for the rest of the session, and re-walks them in #releaseClient. Session ids are random UUIDs, so nothing is misdelivered; the cost is retained entries and wasted work.

Send the same detach notice for frame sessions:

for (const frame of target.frames.values()) {
  if (frame.frameId !== target.frameId) {
    ctx.browser.networkEvents.deleteTargetAttribution(frame.frameId);
  }
  detachSessions(ctx, frame.sessions, frame.frameId);
  frame.detached = true;
  // ...
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants