perf: Node IPC binary framing to avoid JSON-encoding large HTML payloads

[zeroedin]

Context

Follow-up from #1180. The Node bridge has the same 4-pass JSON serialization overhead as QuickJS for onPageRendered payloads — EncodeMessage embeds the full ~800KB HTML inside a JSON envelope, requiring JSON escaping on encode and unescaping on decode on both Go and Node sides.

The QuickJS path is addressed in #1180 via native object construction. The Node path requires IPC protocol changes and is tracked separately here.

Current Node IPC path

CallHook → bridge.Send(&Message{Payload: HookRenderedPayload{...}}) → EncodeMessage:

1. Go: jsonCodec.Marshal(msg) — JSON-encodes ~800KB HTML (escaping ", <, >, \n, etc.)
2. Node: JSON.parse(body) — parses the full JSON including escaped HTML
3. Node: Hook runs, returns object
4. Node: JSON.stringify(result) — re-encodes ~800KB HTML
5. Go: jsonCodec.Unmarshal(body, &resp) — parses it back

Why it's lower priority than #1180

• BatchCallHook distributes pages across the worker pool — per-page overhead is amortized across CPU cores
• QuickJS is single-threaded, so the QuickJS fix has higher wall-clock impact
• Protocol changes touch EncodeMessage/DecodeMessage (Go), the Node-side bridge JS message handler, and the Message struct — higher blast radius

Possible approaches

1. Split-message framing: Send a small JSON metadata message ({ frontMatter, url, path, htmlLength: N }) followed by N bytes of raw HTML. Avoids JSON-encoding the HTML body entirely.
2. Length-prefixed binary fields: Extend the LSP-style framing to support binary fields — the JSON envelope references a field by name, and the raw bytes follow the JSON body.
3. Base64 encoding: Simpler than protocol changes but only reduces overhead ~33% (base64 inflation vs JSON escaping). Not recommended.

Refs

• perf: onPageRendered object API causes 2x regression on large sites (JSON serialization overhead) #1180 — QuickJS fast path (parent issue)

[zeroedin]

Experiment results: split-body framing implemented and tested

Built an experiment binary with split-body framing for the Node IPC path and tested against the RHDS benchmark.

What was implemented

Go side (EncodeMessage): For hook messages with HookRenderedPayload, HookFormatRenderedPayload, HookTransformPayload, or map[string]interface{} containing html/content, the large string field is stripped from the JSON and sent as raw bytes after the JSON body:

Content-Length: 200\r\nX-Body-Length: 800000\r\nX-Body-Field: html\r\n\r\n{"id":1,...}<raw 800KB HTML>

Go side (Send response reading): Multi-header parsing loop reads Content-Length, X-Body-Length, X-Body-Field. After parsing the JSON body, reads raw bytes and injects them into resp.Result.

Node side (bridge.js parser): Header parsing updated to detect X-Body-Length/X-Body-Field. Raw body bytes are read separately and injected into msg.payload[bodyField].

Node side (sendMessage): For hook results with html or content string fields, strips the field from the JSON and sends it as raw bytes with the split-body headers.

Result

No measurable improvement on the RHDS benchmark. BatchCallHook already parallelizes Node hook calls across the worker pool, amortizing the per-page IPC overhead across CPU cores. The JSON escaping cost per page is real (~5ms for 800KB HTML), but distributed across 12 workers, the wall-clock impact is ~340ms total — noise relative to the 8s of actual SSR work.

Recommendation

The split-body framing is correct and tested (all 442 pipeline tests pass, backward compatible with old single-header format). Worth shipping as a maintenance improvement — it reduces peak memory (no JSON-escaped copy of 800KB HTML) and CPU waste — but it's not a performance-visible change on sites that use worker pools.

The framing would matter more for:

• Sites with plugins.workers: 1 (no parallelization)
• Very large pages (>2MB) where JSON escaping overhead exceeds worker amortization
• Future streaming SSR where pages are processed sequentially

Implementation details for the architect

Spec tests needed:

• EncodeMessage with HookRenderedPayload: verify X-Body-Length and X-Body-Field headers present, JSON body does not contain html, raw bytes follow JSON
• EncodeMessage with map[string]interface{}{"html": "..."}: verify split-body for chained hook results
• EncodeMessage with non-hook message (e.g., type "filter"): verify old single-header format preserved
• DecodeMessage / Send response: verify raw body bytes injected into result map under correct field name
• bridge.js parser: verify inbound split-body message delivers msg.payload.html correctly
• bridge.js sendMessage: verify outbound hook result strips html/content and sends raw bytes
• Backward compatibility: old single-header messages still parse correctly with new multi-header parser
• Malformed frame diagnostic: non-protocol data on first line still produces stdout pollution error