@harness-fe/runtime 3.0.1

package/src/fetchPatch.ts

@@ -0,0 +1,371 @@
+/**
+ * fetch monkey-patch — captures URL/method/headers/body for request and
+ * response, including streaming SSE responses, without changing
+ * business-observable fetch behavior.
+ *
+ * Safety contract (do not weaken without updating the spec):
+ *  1. Identity-preserving: replacement is a named `fetch`, with
+ *     defineProperty'd name/length/toString so library fingerprint checks
+ *     still pass. Response / Request instances are NOT wrapped.
+ *  2. Error-isolated: capture failures are swallowed via `safeEmit`; they
+ *     NEVER propagate to business code.
+ *  3. No timing or value change: the original Promise is returned to the
+ *     caller unchanged. body capture reads `response.clone()` on a side
+ *     branch — the business path retains an untouched stream.
+ *  4. Self-traffic guard: requests carrying `init.__hfeInternal === true`
+ *     short-circuit to the original fetch. A URL denylist also skips HMR /
+ *     dev-server traffic to prevent capture feedback loops.
+ *  5. Bounded memory: bodies are capped at BODY_CAP per request. SSE
+ *     streams stop accumulating and `cancel()` the cloned reader once
+ *     the cap is hit.
+ *
+ * The patch is idempotent (re-install is a no-op) and returns a dispose
+ * function that restores the original `window.fetch`.
+ */
+
+import type { NetworkEntry } from '@harness-fe/protocol';
+
+const DEFAULT_BODY_CAP = 256 * 1024;
+const INTERNAL_FLAG = '__hfeInternal';
+const PATCHED_FLAG = '__hfePatched';
+const DEFAULT_DENYLIST: RegExp[] = [/\/__hfe\//, /sockjs-node/, /\.hot-update\./];
+const SENSITIVE_HEADER = /^(authorization|cookie|x-api-key|x-auth-.+)$/i;
+
+export interface FetchPatchOptions {
+    /** Called once for each emitted record (request and response are separate calls). */
+    onEntry: (entry: NetworkEntry) => void;
+    /** Per-body byte cap. Default 256 KB. */
+    bodyCap?: number;
+    /** URL patterns to skip capture entirely. */
+    denylist?: RegExp[];
+}
+
+/**
+ * Install the fetch patch. Returns a dispose function that restores the
+ * original window.fetch. Safe to call multiple times (subsequent calls
+ * are no-ops while a patch is active).
+ */
+export function installFetchPatch(opts: FetchPatchOptions): () => void {
+    if (typeof window === 'undefined' || typeof window.fetch !== 'function') {
+        return () => {};
+    }
+    const original = window.fetch;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((original as any)[PATCHED_FLAG]) return () => {};
+
+    const bodyCap = opts.bodyCap ?? DEFAULT_BODY_CAP;
+    const denylist = opts.denylist ?? DEFAULT_DENYLIST;
+    const emit = (entry: NetworkEntry): void => safeEmit(opts.onEntry, entry);
+
+    // Named function so .name === 'fetch'.
+    const patched = function fetch(
+        this: typeof globalThis,
+        input: RequestInfo | URL,
+        init?: RequestInit,
+    ): Promise<Response> {
+        // Self-traffic short-circuit — internal requests bypass capture.
+        if (init && (init as Record<string, unknown>)[INTERNAL_FLAG]) {
+            return original.call(this, input as RequestInfo, init);
+        }
+
+        const meta = extractRequestMeta(input, init);
+        if (denylist.some((re) => re.test(meta.url))) {
+            return original.call(this, input as RequestInfo, init);
+        }
+
+        const id = generateId();
+        const startedAt = performance.now();
+        const startedTs = Date.now();
+
+        // Emit request record eagerly (req body is read async — second emit
+        // updates the record once body is serialized; consumers join by id).
+        const reqRecord: NetworkEntry = {
+            ts: startedTs,
+            id,
+            phase: 'req',
+            method: meta.method,
+            url: meta.url,
+            requestHeaders: meta.headers,
+        };
+        emit(reqRecord);
+        cloneRequestBody(input, init, bodyCap).then(
+            ({ body, truncated }) => {
+                if (body === undefined && !truncated) return;
+                emit({
+                    ...reqRecord,
+                    requestBody: body,
+                    requestBodyTruncated: truncated || undefined,
+                });
+            },
+            () => {
+                /* serialization error — ignore, req already emitted */
+            },
+        );
+
+        const promise = original.call(this, input as RequestInfo, init);
+
+        promise.then(
+            (response) => {
+                let cloned: Response | undefined;
+                try {
+                    cloned = response.clone();
+                } catch {
+                    emit({
+                        ts: Date.now(),
+                        id,
+                        phase: 'res',
+                        method: meta.method,
+                        url: meta.url,
+                        status: response.status,
+                        responseHeaders: headersToObject(response.headers),
+                        durationMs: performance.now() - startedAt,
+                    });
+                    return;
+                }
+                const finalize = (body: unknown, truncated: boolean): void => {
+                    emit({
+                        ts: Date.now(),
+                        id,
+                        phase: 'res',
+                        method: meta.method,
+                        url: meta.url,
+                        status: response.status,
+                        responseHeaders: headersToObject(response.headers),
+                        responseBody: body,
+                        responseBodyTruncated: truncated || undefined,
+                        durationMs: performance.now() - startedAt,
+                    });
+                };
+
+                const ct = response.headers.get('content-type') ?? '';
+                if (isSSE(ct)) {
+                    pumpSSE(cloned, bodyCap, finalize);
+                } else if (isTextLike(ct)) {
+                    readTextWithCap(cloned, bodyCap).then(
+                        ({ body, truncated }) =>
+                            finalize(maybeParseJson(body, ct), truncated),
+                        () => finalize(undefined, false),
+                    );
+                } else {
+                    // Binary or unknown: only record size, do not pull bytes.
+                    cloned.arrayBuffer().then(
+                        (buf) => finalize(`[binary ${buf.byteLength}B]`, false),
+                        () => finalize(undefined, false),
+                    );
+                }
+            },
+            (err: unknown) => {
+                emit({
+                    ts: Date.now(),
+                    id,
+                    phase: 'res',
+                    method: meta.method,
+                    url: meta.url,
+                    durationMs: performance.now() - startedAt,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            },
+        );
+
+        return promise;
+    };
+
+    // Preserve fingerprint — library detection commonly inspects these.
+    try {
+        Object.defineProperty(patched, 'name', { value: 'fetch' });
+        Object.defineProperty(patched, 'length', { value: original.length });
+        Object.defineProperty(patched, 'toString', {
+            value: () => original.toString(),
+        });
+    } catch {
+        /* sealed property — safe to skip */
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (patched as any)[PATCHED_FLAG] = true;
+
+    window.fetch = patched as typeof fetch;
+    return () => {
+        if (window.fetch === (patched as typeof fetch)) {
+            window.fetch = original;
+        }
+    };
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function generateId(): string {
+    try {
+        return crypto.randomUUID();
+    } catch {
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    }
+}
+
+interface RequestMeta {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+}
+
+function extractRequestMeta(input: RequestInfo | URL, init?: RequestInit): RequestMeta {
+    let url: string;
+    let method = 'GET';
+    let headers: Record<string, string> | undefined;
+
+    if (typeof input === 'string') {
+        url = input;
+    } else if (input instanceof URL) {
+        url = input.toString();
+    } else {
+        url = input.url;
+        method = input.method;
+        headers = headersToObject(input.headers);
+    }
+    if (init?.method) method = init.method;
+    if (init?.headers) {
+        headers = { ...(headers ?? {}), ...(headersToObject(init.headers) ?? {}) };
+    }
+    return { url, method, headers };
+}
+
+function headersToObject(
+    h: HeadersInit | Headers | undefined,
+): Record<string, string> | undefined {
+    if (!h) return undefined;
+    const out: Record<string, string> = {};
+    if (h instanceof Headers) {
+        h.forEach((v, k) => {
+            out[k] = v;
+        });
+    } else if (Array.isArray(h)) {
+        for (const [k, v] of h) out[k] = v;
+    } else {
+        Object.assign(out, h);
+    }
+    return redactHeaders(out);
+}
+
+function redactHeaders(h: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(h)) {
+        out[k] = SENSITIVE_HEADER.test(k) ? `[redacted ${String(v).length}]` : v;
+    }
+    return out;
+}
+
+async function cloneRequestBody(
+    input: RequestInfo | URL,
+    init: RequestInit | undefined,
+    cap: number,
+): Promise<{ body?: unknown; truncated: boolean }> {
+    if (init?.body !== undefined && init.body !== null) {
+        return serializeBodyInit(init.body, cap);
+    }
+    if (input instanceof Request && input.body) {
+        try {
+            const text = await input.clone().text();
+            return capText(text, cap);
+        } catch {
+            return { truncated: false };
+        }
+    }
+    return { truncated: false };
+}
+
+function serializeBodyInit(
+    body: BodyInit,
+    cap: number,
+): { body?: unknown; truncated: boolean } {
+    if (typeof body === 'string') return capText(body, cap);
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const obj: Record<string, unknown> = {};
+        body.forEach((v, k) => {
+            obj[k] = typeof v === 'string'
+                ? v
+                : `[File ${(v as File).name} ${(v as File).size}B]`;
+        });
+        return { body: obj, truncated: false };
+    }
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+        return { body: body.toString(), truncated: false };
+    }
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+        return { body: `[Blob ${body.size}B]`, truncated: false };
+    }
+    if (body instanceof ArrayBuffer) {
+        return { body: `[ArrayBuffer ${body.byteLength}B]`, truncated: false };
+    }
+    if (ArrayBuffer.isView(body)) {
+        return { body: `[${(body.constructor as { name: string }).name} ${body.byteLength}B]`, truncated: false };
+    }
+    return { body: '[unknown body]', truncated: false };
+}
+
+function capText(text: string, cap: number): { body: string; truncated: boolean } {
+    if (text.length > cap) return { body: text.slice(0, cap), truncated: true };
+    return { body: text, truncated: false };
+}
+
+async function readTextWithCap(
+    res: Response,
+    cap: number,
+): Promise<{ body: string; truncated: boolean }> {
+    const text = await res.text();
+    return capText(text, cap);
+}
+
+function maybeParseJson(text: string, contentType: string): unknown {
+    if (!/json/i.test(contentType)) return text;
+    try {
+        return JSON.parse(text);
+    } catch {
+        return text;
+    }
+}
+
+function isSSE(ct: string): boolean {
+    return /text\/event-stream/i.test(ct);
+}
+
+function isTextLike(ct: string): boolean {
+    return /json|text|xml|javascript|x-www-form-urlencoded/i.test(ct);
+}
+
+function pumpSSE(
+    res: Response,
+    cap: number,
+    done: (body: string, truncated: boolean) => void,
+): void {
+    if (!res.body || typeof res.body.getReader !== 'function') {
+        return done('', false);
+    }
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let total = '';
+    let truncated = false;
+    const step = (): void => {
+        reader.read().then(
+            ({ done: end, value }) => {
+                if (end) return done(total, truncated);
+                total += dec.decode(value, { stream: true });
+                if (total.length > cap) {
+                    total = total.slice(0, cap);
+                    truncated = true;
+                    reader.cancel().catch(() => {});
+                    return done(total, truncated);
+                }
+                step();
+            },
+            () => done(total, truncated),
+        );
+    };
+    step();
+}
+
+function safeEmit(fn: (entry: NetworkEntry) => void, entry: NetworkEntry): void {
+    try {
+        fn(entry);
+    } catch {
+        /* swallow — capture must not break business */
+    }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Auto-start entry. Importing this module (as the Vite plugin does)
+ * boots a RuntimeClient using the config planted on `window.__HARNESS_FE__`.
+ *
+ * Idempotent: importing twice is a no-op.
+ */
+
+import { installOverlay } from './overlay.js';
+import { RuntimeClient, readInjectedConfig } from './client.js';
+
+const w = window as unknown as {
+    __harness_fe_started__?: boolean;
+    __harness_fe_client__?: RuntimeClient;
+    __hfe_session_id__?: string;
+};
+
+if (typeof window !== 'undefined' && !w.__harness_fe_started__) {
+    w.__harness_fe_started__ = true;
+    const cfg = readInjectedConfig();
+    const client = new RuntimeClient(cfg);
+    client.start();
+    installOverlay(client);
+    // Expose for debugging + same-origin iframe inheritance.
+    // Same-origin children read `window.parent.__hfe_session_id__` and
+    // `window.parent.__harness_fe_client__.tabId` in tryInheritFromParent()
+    // so all iframes within one pageload share identity.
+    w.__harness_fe_client__ = client;
+    w.__hfe_session_id__ = client.sessionId;
+}
+
+export { RuntimeClient, tryInheritFromParent } from './client.js';
+export type { ClientOptions, ParentInheritance } from './client.js';

package/src/outbox.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { Outbox } from './outbox.js';
+
+describe('Outbox', () => {
+    describe('FIFO eviction', () => {
+        it('evicts oldest non-sticky frame when frame cap is exceeded', () => {
+            const outbox = new Outbox(3, 1024);
+            outbox.enqueue('a', false);
+            outbox.enqueue('b', false);
+            outbox.enqueue('c', false);
+            outbox.enqueue('d', false); // triggers eviction
+            const payloads = outbox.snapshot().map((e) => e.payload);
+            expect(payloads).toEqual(['b', 'c', 'd']);
+        });
+
+        it('evicts oldest non-sticky frame when byte cap is exceeded', () => {
+            const outbox = new Outbox(100, 6); // 6 bytes total
+            outbox.enqueue('aa', false); // 2
+            outbox.enqueue('bb', false); // 4
+            outbox.enqueue('cc', false); // 6
+            outbox.enqueue('dd', false); // 8 → evict 'aa'
+            const payloads = outbox.snapshot().map((e) => e.payload);
+            expect(payloads).toEqual(['bb', 'cc', 'dd']);
+            expect(outbox.byteSize).toBe(6);
+        });
+    });
+
+    describe('sticky protection (the core fix)', () => {
+        it('keeps a sticky frame even when older non-sticky frames must yield', () => {
+            const outbox = new Outbox(3, 1024);
+            outbox.enqueue('fullsnap', true);   // sticky — must survive
+            outbox.enqueue('inc-1', false);
+            outbox.enqueue('inc-2', false);
+            outbox.enqueue('inc-3', false);     // triggers eviction
+            const payloads = outbox.snapshot().map((e) => e.payload);
+            expect(payloads).toContain('fullsnap');
+            // The sticky frame stays; the oldest non-sticky goes.
+            expect(payloads).toEqual(['fullsnap', 'inc-2', 'inc-3']);
+        });
+
+        it('evicts non-sticky from the middle to preserve a sticky older frame', () => {
+            const outbox = new Outbox(2, 1024);
+            outbox.enqueue('fullsnap', true);
+            outbox.enqueue('inc-1', false);
+            outbox.enqueue('inc-2', false); // cap=2 → evict inc-1, keep [fullsnap, inc-2]
+            const payloads = outbox.snapshot().map((e) => e.payload);
+            expect(payloads).toEqual(['fullsnap', 'inc-2']);
+        });
+
+        it('falls back to dropping oldest sticky when ALL frames are sticky and cap busted', () => {
+            // Pathological: many ws reconnects, each adding a sticky frame,
+            // daemon never staying up to drain.
+            const outbox = new Outbox(2, 1024);
+            outbox.enqueue('fs-1', true);
+            outbox.enqueue('fs-2', true);
+            outbox.enqueue('fs-3', true); // cap=2 → must drop oldest sticky
+            const payloads = outbox.snapshot().map((e) => e.payload);
+            expect(payloads).toEqual(['fs-2', 'fs-3']);
+        });
+
+        it('regression: the original FIFO bug — without sticky protection, FullSnapshot would be dropped', () => {
+            // Reproduce the original bug shape, but with sticky=true to prove the fix.
+            const outbox = new Outbox(500, 8 * 1024 * 1024);
+            const BIG_PAYLOAD = 'x'.repeat(20 * 1024); // 20 KB "FullSnapshot"
+            outbox.enqueue(BIG_PAYLOAD, true);
+            // Flood with 600 incrementals, 20 KB each — bytes cap ~8 MB, frame
+            // cap = 500. Without sticky protection the FullSnapshot would be
+            // the first evicted (oldest by FIFO).
+            for (let i = 0; i < 600; i++) {
+                outbox.enqueue('x'.repeat(20 * 1024), false);
+            }
+            const snap = outbox.snapshot();
+            expect(snap[0]!.payload).toBe(BIG_PAYLOAD); // FullSnapshot retained
+            expect(snap[0]!.sticky).toBe(true);
+            // Outbox stays within frame cap.
+            expect(snap.length).toBeLessThanOrEqual(500);
+        });
+    });
+
+    describe('flush', () => {
+        it('sends FIFO in order and clears the queue', () => {
+            const outbox = new Outbox(10, 1024);
+            outbox.enqueue('a', false);
+            outbox.enqueue('b', true);
+            outbox.enqueue('c', false);
+            const sent: string[] = [];
+            outbox.flush((p) => { sent.push(p); });
+            expect(sent).toEqual(['a', 'b', 'c']);
+            expect(outbox.size).toBe(0);
+            expect(outbox.byteSize).toBe(0);
+        });
+
+        it('halts on send throw and retains remaining frames for next flush', () => {
+            const outbox = new Outbox(10, 1024);
+            outbox.enqueue('a', false);
+            outbox.enqueue('b', false);
+            outbox.enqueue('c', false);
+            let calls = 0;
+            outbox.flush(() => {
+                calls++;
+                if (calls === 2) throw new Error('socket died');
+            });
+            // 'a' sent, 'b' failed → keep 'b' and 'c'
+            expect(outbox.snapshot().map((e) => e.payload)).toEqual(['b', 'c']);
+        });
+
+        it('treats explicit `false` return as send-failed', () => {
+            const outbox = new Outbox(10, 1024);
+            outbox.enqueue('a', false);
+            outbox.enqueue('b', false);
+            outbox.flush((p) => (p === 'b' ? false : true));
+            expect(outbox.snapshot().map((e) => e.payload)).toEqual(['b']);
+        });
+    });
+});

package/src/outbox.ts

@@ -0,0 +1,84 @@
+/**
+ * Pre-handshake / reconnect outbox.
+ *
+ * Buffers frames produced while the WebSocket isn't OPEN and replays them
+ * in FIFO order on `flush(send)`. Capped to defend against OOM if the
+ * bridge is unreachable for an extended period.
+ *
+ * `sticky` marks frames that must survive eviction even when the outbox
+ * is full — currently used for rrweb chunks containing a FullSnapshot
+ * (type:2) baseline. Without this protection, the FullSnapshot — being
+ * the oldest frame in the outbox — was always the first to be FIFO-
+ * evicted under load, leaving the session permanently unreplayable.
+ * Eviction only touches sticky frames as a last resort (all remaining
+ * frames are sticky and we still exceed cap).
+ */
+export class Outbox {
+    private entries: Array<{ payload: string; sticky: boolean }> = [];
+    private bytes = 0;
+
+    constructor(
+        private readonly maxFrames: number,
+        private readonly maxBytes: number,
+    ) {}
+
+    /** Current buffered frame count. */
+    get size(): number {
+        return this.entries.length;
+    }
+
+    /** Current buffered byte size. */
+    get byteSize(): number {
+        return this.bytes;
+    }
+
+    /** Inspect entries without exposing the underlying mutable array. */
+    snapshot(): ReadonlyArray<{ payload: string; sticky: boolean }> {
+        return this.entries.slice();
+    }
+
+    enqueue(payload: string, sticky: boolean): void {
+        this.entries.push({ payload, sticky });
+        this.bytes += payload.length;
+
+        // Pass 1: evict only non-sticky frames, oldest first.
+        let i = 0;
+        while ((this.entries.length > this.maxFrames || this.bytes > this.maxBytes) && i < this.entries.length) {
+            const entry = this.entries[i]!;
+            if (entry.sticky) {
+                i++;
+                continue;
+            }
+            this.entries.splice(i, 1);
+            this.bytes -= entry.payload.length;
+        }
+
+        // Pass 2 (last resort): drop oldest sticky frames if we still bust
+        // the cap. Replay only needs the *most recent* baseline, so dropping
+        // older sticky frames is acceptable.
+        while ((this.entries.length > this.maxFrames || this.bytes > this.maxBytes) && this.entries.length > 0) {
+            const dropped = this.entries.shift()!;
+            this.bytes -= dropped.payload.length;
+        }
+    }
+
+    /**
+     * Drain FIFO into `send`. If `send` throws (or returns false), keep the
+     * frame in the queue and bail — caller will retry on next flush.
+     */
+    flush(send: (payload: string) => boolean | void): void {
+        while (this.entries.length > 0) {
+            const entry = this.entries[0]!;
+            let ok = false;
+            try {
+                const result = send(entry.payload);
+                ok = result !== false;
+            } catch {
+                ok = false;
+            }
+            if (!ok) return;
+            this.entries.shift();
+            this.bytes -= entry.payload.length;
+        }
+    }
+}