Skip to content

engine: host page/renderer isolates in PageIsolateHost and tighten teardown - #192

Open
BernardoPe wants to merge 2 commits into
bpereira/pr2-boa-perf-wasm-splitfrom
bpereira/pr3-isolate-lifecycle-memory
Open

BernardoPe wants to merge 2 commits into
bpereira/pr2-boa-perf-wasm-splitfrom
bpereira/pr3-isolate-lifecycle-memory

Conversation

@BernardoPe

Copy link
Copy Markdown
Collaborator

Part 3 of a 4-PR stack (stacked on #191).

Summary

  • Hosted isolate lifecycle (PageIsolateHost, page-script.ts, page-renderer.ts, embed.ts):
    • Introduce PageIsolateHost WorkerEntrypoint (exported on @kitesurf/engine/embed) with zero-copy static module handoff so each PageScript and PageRenderer isolate is loaded in its own loopback request IoContext and releases its heap, Wasm memory, and compiled code as soon as the handle is disposed.
    • Recycle idle PageRenderer isolates once above Wasm high-water thresholds (36 MiB idle / 48 MiB with live pages) and drop target images on Target.closeTarget.
  • Teardown & interception cleanup (target.ts, connection.ts, oopif-render.ts, fetch-interception.ts):
    • Immediately kill resolved OOPIF prespawns and detached retiring stubs on Target.closeTarget / WebSocket close.
    • End session fetch interception across all detached target and frame sessions.
  • Streaming text capture & session outbound body lifecycle (outbound.ts, read-capped.ts, session-outbound.ts, fetch-shim.ts, native-http.ts):
    • Stream status < 400 text responses via streamCapturedTextBody (awaiting capture completion before closing the page stream and buffering >= 400 error bodies) instead of buffering full responses before returning headers.
    • Track active session response bodies on both engine and page sides and cancel/abort them cleanly on session close or same-tick AbortSignal.

Verification

  • Engine unit tests passing (10 suites, 154 tests): cors, outbound-event-stream, dedicated-worker-teardown, fetch-shim-redirect-body, frame-page-script, outbound-session-bodies, page-renderer-timeout, page-script-rpc-session, session-outbound, target-close.
  • E2E tests passing: text-stream-headers.
  • pnpm run -s lint:js, pnpm run -s format:check, and Bazel typechecks passing.

: null;
// Buffer error-status text bodies before returning so Network.responseReceived is emitted
// immediately even when the caller never reads the error body.
if (textBody && !needsBufferedBody && resp.status < 400) {

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-rui-agent-🤖

Blocking: a redirect hop that has a text body now reports Network.loadingFailed net::ERR_ABORTED and no Network.responseReceived.

A 3xx status is below 400, so its text body takes the new streaming path. The redirect walker then cancels the body of the hop (redirect-walk.ts:132; the fetch shim now does the same), and the cancel handler of the stream calls fail("net::ERR_ABORTED"). Most servers send a body with a redirect, for example nginx and Express.

Before this PR the outbound read the body and called completeRequest before it returned the response. The later cancel changed nothing.

I ran this with walkRedirects, SandboxOutbound.handle and a tracker, on 9e6bab0a4 (before) and on this head. The request is a same-origin Script request, and /hop answers 302 with content-type: text/html:

302 response Before This PR
with the body <a href=/next>moved</a> responseReceived 302, loadingFinished loadingFailed net::ERR_ABORTED, no responseReceived
with no body responseReceived 302, loadingFinished the same

Both versions report the final 200 correctly. For the walkers on the engine side (script prefetch, module walk, OOPIF documents) the result is the same on every run. For a page fetch() that follows a same-origin redirect, the result depends on whether the capture or the cancel finishes first.

Fix: keep redirect statuses on the buffered path, as this code already does for >= 400. resp.status < 300 is one way. Please add a 302 with a body to outbound-event-stream.test.ts; the fixtures today all use c.body(null, 302, …).

if (modulesId !== undefined) {
const entry = stashedPageModules.get(modulesId);
stashedPageModules.delete(modulesId);
if (!entry) throw new Error("PageIsolateHost.open: missing stashed page modules");

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-rui-agent-🤖

Blocking: open() reads a module-level map that the loopback call may not share with its caller, and nothing falls back when the entry is missing.

getOrCreatePageScript puts the page modules in stashedPageModules and sends only the id through cx.exports.PageIsolateHost.open(...). open looks the id up in the map of the isolate that serves the call. If that isolate is not the caller's, open throws here. The direct env.LOADER.load path runs only when the export is missing, not when open fails, so the navigation fails.

The engine already handles this case for other loopback calls:

  • eval/isolate-id.ts: "Tags requests with the engine isolate ID so loopback hops can detect a different isolate."
  • eval/outbound.ts: "A loopback call may reach a replacement isolate with a separate resource store."
  • noteForeignIsolate logs [ks-outbound] foreign isolate: … engine-held state skipped.

A CDP connection stays on the isolate that accepted it. If its loopback calls start to reach a replacement isolate, every later Page.navigate on that connection fails with missing stashed page modules.

I traced this path and did not run it. Local workerd has one isolate, so a local test cannot show it.

Fix: do not make shared module state a required input. Two options:

  1. When open rejects with this error, load directly with env.LOADER.load(code).
  2. Send engineIsolateId() with the call. open then reports a foreign isolate, and the caller loads directly.

openRenderer sends the full spec, so it is not affected.

@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from b7814a9 to 7b3a2f2 Compare November 20, 2026 22:36
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 7b3a2f2 to a6289c9 Compare November 20, 2026 22:54
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from a6289c9 to 9310c73 Compare November 20, 2026 23:13
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 9310c73 to a45c384 Compare November 20, 2026 23:30
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from a45c384 to 386541d Compare November 20, 2026 23:53
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 386541d to 4700846 Compare November 21, 2026 00:09
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 4700846 to 739295c Compare November 21, 2026 00:42
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 739295c to 582773a Compare November 21, 2026 03:46
…n teardown

Page and renderer isolates were started, messaged and killed from three
different places, and a closed target or a retiring page could leave a worker
running with its readers and outbound bodies still attached. `PageIsolateHost`
owns their lifecycle: one place starts a worker, one place kills it, and
teardown ends every body the isolate handed out before the worker goes away.

The renderer's timeout and target-close paths now go through it, the OOPIF
render path stops holding a retired isolate alive, and `read-capped` gives each
connection half of the shared budget instead of a per-read charge.

Signed-off-by: bpereira <bpereira@cloudflare.com>
A routed body was a default stream, so `response.body.getReader({mode:"byob"})`
threw and a page could not read a fetched body the way it reads a native one.
Wrap it in a byte stream built from captured intrinsics: fill a pending BYOB
request in place, copy the tail so the chunk's buffer is not detached, and keep
a null-prototype source so `Object.prototype` poisoning cannot reach creation.

A decompression or RPC failure crossed the boundary as a plain `Error`; surface
it as `TypeError`, which is what a page's `response.text()` is allowed to
reject with, while an abort keeps its `AbortError`.

Signed-off-by: bpereira <bpereira@cloudflare.com>
@BernardoPe
BernardoPe force-pushed the bpereira/pr3-isolate-lifecycle-memory branch from 582773a to a77c314 Compare November 21, 2026 05:00
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