Skip to content

engine: split the browser session from its CDP client - #182

Merged
ruifigueira merged 3 commits into
mainfrom
rfigueira/browser-session-split
Nov 20, 2026
Merged

ruifigueira merged 3 commits into
mainfrom
rfigueira/browser-session-split

Conversation

@ruifigueira

@ruifigueira ruifigueira commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

handleWebSocket keeps all browser state in one closure that belongs to one WebSocket. As a result, you cannot read, test or reuse the browser state apart from the socket code.

This pull request splits the two. BrowserSession owns the browser. ClientConnection owns the socket. A session still has exactly one client, so the behavior does not change.

This is preparation for sessions with more than one CDP client. That work is in the stacked draft #186. It needs per-client ownership of events, Fetch interception and screencasts, and the first version of this pull request did not enforce that. See "Risks and follow-ups".

No issue tracks this work yet.

Behavior and API impact

The CDP behavior does not change. handleWebSocket builds a BrowserSession and attaches the socket as its one client. The teardown order, session_end, the log lines, the idle deadline and the wall-clock cap are the same as on main.

Changes to the embedder API (embed.ts):

  • DispatchCtx.ctx is now SessionContext, a Pick of the four ExecutionContext fields that a session uses: waitUntil, exports, props and passThroughOnException. Code that passes dispatchCtx.ctx where an ExecutionContext is expected no longer typechecks.
  • DispatchCtx has a new required field, client (CdpClientState). BrowserState no longer has connectionMode, autoAttach and flatten, which moved to client.
  • embed.ts now exports the SessionContext and CdpClientState types.
  • handleWebSocket keeps its signature. BrowserSession and ClientConnection are not exported from embed.ts.

Implementation

The pull request has three commits:

  1. SessionContext: the session and the spawn helpers for the renderer, PageScript, OOPIF and dedicated workers take SessionContext, not ExecutionContext. A host can build one without a cast.
  2. CdpClientState: connectionMode, autoAttach and flatten move from BrowserState to DispatchCtx.client. Every unit fixture for DispatchCtx gets its client from test/client-state.ts, so a missing field fails the typecheck.
  3. BrowserSession and ClientConnection:
    • BrowserSession owns the targets, cookie jars, network log, renderer, background drain, wall-clock cap and teardown.
    • ClientConnection owns sending, the message loop, the idle deadline and Browser.close.
    • BrowserSession.route sends every event to the client. A second attachClient throws.
    • handleWebSocket builds the session before it accepts the socket, so a throwing host connectionOptions hook fails the upgrade, as on main.
    • The client runs onCtx and onDispatch before it creates the initial blank page and announces it, as on main.
    • After the idle deadline closes the socket, the wall-clock cap does not close it again while the close handshake runs.
    • AGENTS.md names the two classes. Before, it said that the state lives in the closure of handleWebSocket.

Validation

  • bazel test //:check: 34 of 34 pass.
  • test/connection-lifecycle.test.ts (new): covers the hook order, teardown on a close and then an error with one session_end, the idle deadline and then the wall-clock cap, and a throwing connectionOptions hook. The three regression tests fail against the earlier code.
  • bazel test //packages/engine:types //packages/engine:vitest: passes on each of the three commits.
  • bazel run //scripts:workspace_checks: passes.
  • 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.
  • pnpm run test:e2e target-dom-reclaim: 2 passed.
  • pnpm run test:e2e session-outbound: 7 passed.

Some of these runs log the uncaught error "Worker's code had hung". main (a58b15d) logs the same error in the same worktree.

I did not run the full e2e, WPT, Playwright or Puppeteer suites.

Risks and follow-ups

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. No behavior changes. The new lifecycle tests make sure of the behavior of main.
  • Updated documentation and generated files, or confirmed they do not apply.

beep-boop-🤖

@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-split branch 2 times, most recently from 1f6224c to 3a2aab1 Compare November 19, 2026 22:19
@ruifigueira
ruifigueira marked this pull request as ready for review November 19, 2026 22:19
@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-🤖

Reviewed 3a2aab1e12778124ac70590a83893f7c5dfc3e27 against a58b15d with the full panel: two correctness lenses, security, design/tests/standards, performance, and two breakers with cross-examination.

Three blocking findings below, all on the new persistent path. Each needs persistent: true, which only the new unit tests set today — handleWebSocket still builds a one-client session — so none affects current traffic. They matter because the code, its comments and its tests claim per-client ownership that delivery and cleanup do not enforce.

Worth fixing alongside them, not raised inline:

  • AGENTS.md:72-73 still says "Per-connection state lives in handleWebSocket's closure". That is no longer true, and CONTRIBUTING.md asks for an altered invariant's comment to be updated in the same commit. The PR body lists it as a follow-up instead.
  • The one stated behaviour change does not exist. emitSessionEnd is already guarded by analytics.once("session_end") (src/observability.ts:174), so main never sent a second session_end after a socket error. The stateless path's telemetry is unchanged, not "unchanged except".
  • persistent has no caller and no stable surface: BrowserSession and attachClient are not exported from src/embed.ts, so the feature ships inert and the hermetic e2e lane cannot cover it.
  • Page.addScriptToEvaluateOnNewDocument is tracked per client but still executed from one browser-wide map (src/cdp/page.ts:1928), so a client's script runs in another client's page.
  • A closed page's iframe session ids stay in CdpClientState.sessions: src/cdp/target.ts:403-406 clears frame.sessions without the detach notice that prunes the owner entry.
  • Target.detachFromTarget on the engine memory target clears only memoryTargets.renderer (src/cdp/target.ts:111), not .engine. This is identical at base, so it is pre-existing rather than a regression here.

Comment thread packages/engine/src/cdp/connection.ts Resolved
Comment thread packages/engine/src/cdp/fetch.ts Resolved
Comment thread packages/engine/src/cdp/page.ts Resolved
@BernardoPe BernardoPe assigned BernardoPe and unassigned BernardoPe Nov 20, 2026
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-split branch from 3a2aab1 to 2aabdea Compare November 20, 2026 07:59
@ruifigueira ruifigueira changed the title engine: split the browser session from its CDP clients engine: split the browser session from its CDP client Nov 20, 2026
@ruifigueira

ruifigueira commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator Author

beep-boop-rui-agent-🤖

Thank you for the review. I narrowed this pull request to the refactor alone. It has three commits:

  1. SessionContext.
  2. Per-client CDP state.
  3. The split into BrowserSession and ClientConnection, with exactly one client per session.

The persistent option, multi-client target announcements and leave-cleanup are gone. They moved to the stacked draft #186, which must enforce ownership from end to end before review. That pull request will also export the API and add an e2e test.

Answers to the items in the review summary:

  • AGENTS.md:72-73: fixed in the split commit. The line names the two classes.
  • session_end: you are correct. emitSessionEnd sends at most once, so main never sent a second session_end. I removed the claim from the description. The telemetry does not change.
  • persistent has no caller: removed from this pull request.
  • Page.addScriptToEvaluateOnNewDocument runs browser-wide: with one client, the client that added a script owns every page, so nothing changes. The follow-up pull request will run each script only in the pages of its client.
  • Iframe sessions of a closed page stay in CdpClientState.sessions: fixed in the per-client state commit. closeTargetInternal removes them from the client.
  • memoryTargets.engine: memoryTargets is not in this pull request anymore. On main, BrowserState.engineSessionId has the same behavior. The follow-up pull request will clear it on detach.

Two other changes came from a second review:

  • After the idle deadline closes the socket, the wall-clock cap does not close it again.
  • embed.ts exports SessionContext and CdpClientState, because the public DispatchCtx type uses them.

@BernardoPe BernardoPe self-assigned this Nov 20, 2026
@BernardoPe BernardoPe removed their assignment Nov 20, 2026
@ruifigueira
ruifigueira added this pull request to stack #187 November 20, 2026 08:10

@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-🤖

Reviewed 2aabdead28e80751b223c2af8bcfd91eb46b8cf9 against a58b15d with the full panel: two correctness lenses, security, design/tests/standards, performance, and two breakers.

This is much narrower than the earlier version, and the three blocking findings from that review are resolved: the multi-client code is gone, so #releaseClient, the Fetch owner and the screencast owner no longer exist. The seam itself is sound. The single-client teardown, deadline and session_end state machine came out identical to main under 18,750 fuzzed event interleavings, plus 7,203 more with the response path and Browser.close, with zero divergences in close calls, session_end payloads, delivered events and teardown counts. The security and performance lenses found nothing at P0-P2.

Three findings below. None affects current traffic: the first needs an embedder that dispatches synchronously from onDispatch, the second is dead state, the third needs a host hook that throws.

Smaller things, not raised inline:

  • No test covers the close-listener teardown path, the new idle-then-wall-cap guard, or the single-session_end claim. test/limit-registry.test.ts:80-92 already drives handleWebSocket with a fake server socket, so it is the cheapest place for one.
  • 17 of 19 DispatchCtx fixtures still omit the new required client field behind as casts, so tsc cannot catch it. test/client-state.ts now exists; using it everywhere would close that gap.
  • SessionContext is declared in cdp/dispatch.ts and imported by four eval/* modules, which inverts the package split AGENTS.md describes. Type-only today, so no runtime cycle.
  • The description says code passing dispatchCtx.ctx where an ExecutionContext is expected no longer typechecks. connection.ts:798 passes a SessionContext to EngineHost.egress, which takes an ExecutionContext, and tsc is reported green. If that compiles, the two types are mutually assignable with the pinned workers-types and the claimed break does not exist.
  • Commit 28b0a94 is independently landable and carries the only embedder-visible break, so it could move to its own PR.

Comment thread packages/engine/src/cdp/connection.ts Resolved
Comment thread packages/engine/src/cdp/types.ts Resolved
Comment thread packages/engine/src/cdp/connection.ts Resolved
@BernardoPe BernardoPe assigned BernardoPe and unassigned BernardoPe Nov 20, 2026
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-split branch from 2aabdea to b61a785 Compare November 20, 2026 11:33
@ruifigueira

Copy link
Copy Markdown
Collaborator Author

beep-boop-rui-agent-🤖

Thank you for the second review. I fixed the three inline findings, and I replied in each thread. The two smaller items:

  • Lifecycle tests: the new test/connection-lifecycle.test.ts drives handleWebSocket over a fake socket, as limit-registry.test.ts does. The tests cover these cases:

    • The order of the hooks and the initial page.
    • A close, then an error: one teardown and one session_end, with the close fields.
    • The idle deadline, then the wall-clock cap during the close handshake: one close() call.
    • A throwing connectionOptions hook.

    I ran the three regression tests against the earlier code, and each one fails there.

  • DispatchCtx fixtures: every unit fixture that stands for a DispatchCtx now gets client from test/client-state.ts.

I rebased #186 onto this version. It adds id, sessions and preNavScriptIds in the commits that read them. The first client of a session opens the browser and its initial page, and a later client receives announcements of the pages that exist.

@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-🤖

Reviewed b61a7857cb4c049d726f76e4f6d3aa92eeb16d5c against the merge-base a58b15d with the full panel, split into two groups because the diff exceeds 25 files: two correctness lenses, security, design/tests/standards and performance per group, plus two breakers per group.

The seam is faithful. The deadline machine, teardown and event route came out equivalent to main under 20,000 randomised interleavings and 17 scripted timelines, with zero differences in close calls, session_end, delivered events and teardown counts. Group B's migration is a pure rename: reverse-substituting the three fields on head reproduces base byte-for-byte for target.ts and page.ts. The three findings from the earlier review are resolved.

Two blocking items and one test finding below. The first is why CI is red.

Not raised inline:

  • A throw from sessionAgeMs() — an unguarded host HOST_CLOCK.now() — escapes emitSessionEnd, which runs before #disposed = true in dispose(). Because #leave sets #left first, the second terminal event cannot retry, so teardown never runs. main could still recover on a second event. Narrow trigger, but the guard order is worth flipping: mark disposed and clear the timer before emitting telemetry.
  • sendFailCount no longer counts events dropped after teardown, because route returns before deliver. Nothing emits during teardown today, so no log line differs yet, but "the log lines are the same as main" stops being true the first time something does.
  • dispose()'s client?.close(...) can never run: #clientLeft nulls #client immediately before calling it. get disposed() has no reader either.
  • The #leave comment still says close() reports a departure; it does not.
  • CdpClientState.flatten is write-only, as BrowserState.flatten was. Target.setAutoAttach accepts and ignores it.
  • No test constructs BrowserSession or ClientConnection directly, so attachClient rejecting a second client, route dropping events after dispose, and dispose idempotence are unverified. Page mode has no unit coverage at all: testClient("page") has no caller.
  • The upstream-events fixture now reaches a browser-mode branch it did not before, but asserts with .some(...), so the newly reached announcement is not pinned.
  • SessionContext lives in cdp/dispatch.ts and is imported by four eval/* modules; type-only, but it inverts the package split AGENTS.md describes.
  • The four new lifecycle tests pass on main too. That is the right property for a no-behaviour-change refactor, and they do guard the intermediate regressions from the previous head, but the body should not present them as evidence of equivalence.

Comment thread packages/engine/src/cdp/connection.ts Resolved
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-split branch from b61a785 to 33f8dd8 Compare November 20, 2026 11:53
@BernardoPe BernardoPe assigned BernardoPe and unassigned BernardoPe Nov 20, 2026
A browser session and the spawn helpers it calls read four fields of
their ExecutionContext: waitUntil, exports, props and
passThroughOnException. They took the full type, so a host that wants
to run a session outside a fetch handler has to cast a partial object
to ExecutionContext.

DispatchCtx.ctx and the renderer, PageScript, OOPIF and dedicated
worker spawn paths now take SessionContext, a Pick of those four
fields. A host can build one without a cast, and a session that starts
to need another field fails to compile instead of failing at run time.
handleWebSocket still takes the full ExecutionContext.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
Chrome keeps some CDP state per DevTools client, not per browser: the
connection mode a socket opened with, and Target.setAutoAttach's
autoAttach and flatten. The engine kept them on BrowserState. That
works while one socket owns one browser, but a browser shared by two
clients would let one client's setAutoAttach change what the other sees.

Add CdpClientState on DispatchCtx.client and move the three fields
there. Target and page code now read the client's copy, and embed.ts
exports the type because DispatchCtx uses it. The unit fixtures for
DispatchCtx get a client from test/client-state.ts, so a missing field
fails the typecheck instead of hiding behind a cast.

There is still one client per browser, so nothing changes on the wire.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
handleWebSocket built all browser state in one closure bound to one
socket. The browser state and the socket code could not be read, tested
or reused apart.

BrowserSession now owns the browser: the targets, cookie jars, network
log, renderer, the background drain, the wall-clock cap and teardown.
ClientConnection owns the socket: sending and its counters, the message
loop, the idle deadline and Browser.close. Events go through
BrowserSession.route to the client.

A session still has one client: a second attachClient throws, and the
session ends when its client leaves. handleWebSocket keeps the order it
had. It resolves the host's connection options before it accepts the
socket, so a hook that throws fails the upgrade. The client runs the
onCtx and onDispatch hooks before it creates the initial blank page and
announces it, so a page that a hook creates is announced once. The
teardown, session_end, the log lines and the deadlines are the same as
before, and the host egress hook still gets the full ExecutionContext.
Once the idle deadline closes the socket, the wall-clock cap does not
close it again while the close handshake runs.

test/connection-lifecycle.test.ts drives handleWebSocket over a fake
socket and covers the hook order, teardown on close then error with
one session_end, the two deadlines and a throwing hook.

AGENTS.md now names the two classes where it said the state lives in
handleWebSocket's closure.

beep-boop-🤖

Signed-off-by: Rui Figueira <rfigueira@cloudflare.com>
@ruifigueira
ruifigueira force-pushed the rfigueira/browser-session-split branch from 33f8dd8 to a807feb Compare November 20, 2026 12:04
@BernardoPe BernardoPe assigned BernardoPe and unassigned BernardoPe Nov 20, 2026
@ruifigueira
ruifigueira merged commit 6b0176b into main Nov 20, 2026
10 checks passed
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