From d742788abeed290a259c96e2d4f486bc7774793f Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Fri, 23 Oct 2026 12:03:14 +0500 Subject: [PATCH 01/10] feat(web): record profiles --- README.md | 28 + packages/chrome-extension/README.md | 22 + packages/chrome-extension/background.js | 410 ++++++++++++ packages/chrome-extension/bridge.js | 21 + packages/chrome-extension/manifest.json | 26 + src/app/api/captures/[id]/download/route.ts | 25 + .../captures/[id]/ingest/finalize/route.ts | 28 + src/app/api/captures/[id]/ingest/raw/route.ts | 20 + .../api/captures/[id]/ingest/status/route.ts | 35 ++ src/app/api/captures/[id]/route.ts | 26 + src/app/api/captures/[id]/stop/route.ts | 13 + src/app/api/captures/route.ts | 26 + src/app/capture/page.tsx | 266 ++++++++ src/app/globals.css | 61 ++ src/app/page.tsx | 4 + src/lib/capture-store.ts | 581 ++++++++++++++++++ src/lib/capture-types.ts | 86 +++ tests/capture-store.test.mjs | 98 +++ tests/chrome-extension.test.mjs | 41 ++ 19 files changed, 1817 insertions(+) create mode 100644 packages/chrome-extension/README.md create mode 100644 packages/chrome-extension/background.js create mode 100644 packages/chrome-extension/bridge.js create mode 100644 packages/chrome-extension/manifest.json create mode 100644 src/app/api/captures/[id]/download/route.ts create mode 100644 src/app/api/captures/[id]/ingest/finalize/route.ts create mode 100644 src/app/api/captures/[id]/ingest/raw/route.ts create mode 100644 src/app/api/captures/[id]/ingest/status/route.ts create mode 100644 src/app/api/captures/[id]/route.ts create mode 100644 src/app/api/captures/[id]/stop/route.ts create mode 100644 src/app/api/captures/route.ts create mode 100644 src/app/capture/page.tsx create mode 100644 src/lib/capture-store.ts create mode 100644 src/lib/capture-types.ts create mode 100644 tests/capture-store.test.mjs create mode 100644 tests/chrome-extension.test.mjs diff --git a/README.md b/README.md index 50139d0..849e53d 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,34 @@ See the [CLI documentation](packages/cli/CLI.md) for storage, troubleshooting, a ## Using the web interface +### Capture a Chrome performance trace + +TraceSift can record an already-open Chrome tab without opening the DevTools +Performance panel. Open **Capture** in the header, then click the TraceSift +Capture extension in Chrome's toolbar while that exact page is active. This +explicit gesture approves the page; a loopback website cannot pair itself. +Choose the website tab and start recording. The page remains the control +surface while the extension uses Chrome DevTools Protocol as a narrow, local +bridge. Reloading or navigating the approved capture page requires another +toolbar click. + +Chrome buffers events internally while recording. When recording stops, the +extension pulls the resulting CDP stream in fixed-size chunks and waits for +each append to `~/.tracesift/captures` before reading the next. The finished +trace is exported as a Chrome-compatible `.json.gz`; captures remain until +they are deleted in TraceSift. TraceSift monitors Chrome's trace buffer and +automatically stops at 90% to avoid losing a full recording. A Chrome crash +before it exposes the completed stream can still make that recording +unrecoverable. + +The extension currently ships as a developer package. In Chrome 125 or newer, +open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked**, +and select [`packages/chrome-extension`](packages/chrome-extension). Chrome +shows its standard debugging banner during a capture. Opening DevTools for the +same tab, closing the tab, or dismissing that banner can detach the recorder; +TraceSift reports the capture as interrupted rather than presenting it as a +complete export. + ### 1. Configure Analysis settings Without a provider configured, TraceSift still reads a profile end to end and produces its cards. Configure one for the optional extras: diff --git a/packages/chrome-extension/README.md b/packages/chrome-extension/README.md new file mode 100644 index 0000000..ff4152f --- /dev/null +++ b/packages/chrome-extension/README.md @@ -0,0 +1,22 @@ +# TraceSift Capture extension + +This Manifest V3 extension is the privileged CDP bridge used by the local +TraceSift capture page. Chrome 125 or newer is required. + +For local development: + +1. Open `chrome://extensions`. +2. Enable **Developer mode**. +3. Choose **Load unpacked** and select this directory. +4. Open TraceSift's exact `/capture` page and click **TraceSift Capture** in + Chrome's toolbar while that tab is active. Then choose **Check connection**. + +The toolbar click is the pairing approval. A loopback website cannot approve +itself, and reloading or navigating the approved tab clears the approval. The +extension attaches only after an explicit recording request from that tab. + +Chrome buffers the recording internally. On stop, the extension pulls Chrome's +`ReturnAsStream` result in fixed-size chunks, waiting for each local disk append +before requesting the next one. It never uploads captures to an external +service. A browser or renderer crash before Chrome exposes the completed stream +can still make that recording unrecoverable. diff --git a/packages/chrome-extension/background.js b/packages/chrome-extension/background.js new file mode 100644 index 0000000..3b06dc7 --- /dev/null +++ b/packages/chrome-extension/background.js @@ -0,0 +1,410 @@ +const SAFE_BUFFER_LIMIT = 0.9; +// IO.read's size is not a promise about the UTF-8 byte length of its returned +// JavaScript string. 192K code units remains below the server's 1 MB cap even +// in the worst case of four-byte UTF-8 characters. +const MAX_UPLOAD_BYTES = 192 * 1024; +const MAX_SOURCE_MAP_BYTES = 8 * 1024 * 1024; +const MAX_ALL_SOURCE_MAP_BYTES = 16 * 1024 * 1024; +const TRACE_CATEGORIES = [ + "-*", + "blink.console", + "blink.user_timing", + "devtools.timeline", + "disabled-by-default-devtools.timeline", + "disabled-by-default-devtools.timeline.frame", + "disabled-by-default-devtools.timeline.stack", + "disabled-by-default-v8.cpu_profiler", + "disabled-by-default-v8.cpu_profiler.hires", + "disabled-by-default-v8.source_rundown", + "disabled-by-default-v8.source_rundown_sources", + "latencyInfo", + "loading", + "toplevel", + "v8.execute", +].join(","); + +let pairing = null; +let active = null; + +void chrome.storage.session.get("pairing").then((stored) => { pairing = stored.pairing || null; }); + +function errorText(error) { + return error instanceof Error ? error.message : String(error || "Unknown capture error."); +} + +function normalizedBaseUrl(value) { + const url = new URL(value); + if (url.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(url.hostname)) throw new Error("TraceSift must be running on local loopback."); + return url.origin; +} + +function capturePageForTab(tab) { + if (!Number.isInteger(tab?.id) || typeof tab.url !== "string") return null; + try { + const url = new URL(tab.url); + if (url.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(url.hostname) || url.pathname !== "/capture") return null; + return { baseUrl: url.origin, bridgeTabId: tab.id }; + } catch { return null; } +} + +function senderIsPaired(sender) { + if (!pairing || sender.tab?.id !== pairing.bridgeTabId) return false; + try { + const url = new URL(sender.tab.url); + return url.origin === pairing.baseUrl && url.pathname === "/capture"; + } + catch { return false; } +} + +async function jsonFetch(url, init = {}) { + const response = await fetch(url, init); + const body = await response.json().catch(() => ({})); + if (!response.ok) throw new Error(body.error || `TraceSift returned HTTP ${response.status}.`); + return body; +} + +async function targets() { + const candidates = await chrome.debugger.getTargets(); + return candidates + .filter((target) => target.type === "page" && Number.isInteger(target.tabId) && !target.attached) + .filter((target) => !/^(chrome|chrome-extension|devtools):/.test(target.url || "")) + .filter((target) => target.url && !target.url.startsWith(`${pairing.baseUrl}/capture`)) + .map((target) => ({ tabId: target.tabId, title: target.title || "Untitled tab", url: target.url })); +} + +function authHeaders(token) { + return { "Content-Type": "application/json", Authorization: `Bearer ${token}` }; +} + +async function postStatus(update) { + if (!active) return; + await jsonFetch(`${active.baseUrl}/api/captures/${active.captureId}/ingest/status`, { + method: "POST", + headers: authHeaders(active.token), + body: JSON.stringify(update), + }); +} + +function scriptKey(source, params) { + return `${source.sessionId || "root"}:${params.scriptId}`; +} + +async function configureChild(source) { + // Keep renderer page metadata active on Chrome versions that still emit the + // legacy TracingStartedInPage marker. Newer versions need the target-scoped + // marker recorded below because chrome.debugger cannot trace browser events. + await chrome.debugger.sendCommand(source, "Page.enable").catch(() => undefined); + await chrome.debugger.sendCommand(source, "Debugger.enable").catch(() => undefined); + await chrome.debugger.sendCommand(source, "Target.setAutoAttach", { + autoAttach: true, + waitForDebuggerOnStart: false, + flatten: true, + filter: [ + { type: "iframe", exclude: false }, + { type: "worker", exclude: false }, + { type: "shared_worker", exclude: false }, + { type: "service_worker", exclude: false }, + ], + }).catch(() => undefined); +} + +async function inspectedMainFrame(source) { + const result = await chrome.debugger.sendCommand(source, "Page.getFrameTree"); + const frame = result.frameTree?.frame; + if (!frame || typeof frame.id !== "string") throw new Error("Chrome did not identify the inspected main frame."); + return { id: frame.id, url: frame.url || "", name: frame.name || "" }; +} + +async function startCapture(message) { + if (active) throw new Error("A TraceSift capture is already active."); + const baseUrl = normalizedBaseUrl(message.baseUrl); + if (baseUrl !== pairing.baseUrl) throw new Error("Pair TraceSift again before starting a capture."); + const debuggee = { tabId: message.target.tabId }; + active = { + debuggee, + captureId: message.captureId, + token: message.token, + baseUrl, + sequence: 0, + scripts: new Map(), + stopping: false, + stopReason: "manual", + pollTimer: null, + lastEventCount: 0, + mainFrame: null, + traceMarker: `__tracesift_main_${message.captureId}`, + }; + try { + await postStatus({ state: "attaching" }); + await chrome.debugger.attach(debuggee, "1.3"); + await configureChild(debuggee); + active.mainFrame = await inspectedMainFrame(debuggee); + await chrome.debugger.sendCommand(debuggee, "Tracing.start", { + categories: TRACE_CATEGORIES, + options: "record-until-full", + bufferUsageReportingInterval: 1000, + transferMode: "ReturnAsStream", + streamFormat: "json", + streamCompression: "none", + }); + // Chrome 156+ intentionally removes browser-process metadata from traces + // started by chrome.debugger. Leave a renderer-main marker so the exporter + // can restore the equivalent, target-scoped frame metadata offline. + const markerResult = await chrome.debugger.sendCommand(debuggee, "Runtime.evaluate", { + expression: `performance.mark(${JSON.stringify(active.traceMarker)})`, + returnByValue: true, + }); + if (markerResult.exceptionDetails) throw new Error("Chrome could not mark the inspected renderer main thread."); + await postStatus({ state: "recording" }); + active.pollTimer = setInterval(() => void pollStopRequest(), 1000); + return { ok: true }; + } catch (error) { + const messageText = errorText(error); + await postStatus({ state: "failed", stopReason: "error", error: messageText }).catch(() => undefined); + await chrome.debugger.detach(debuggee).catch(() => undefined); + active = null; + throw new Error(messageText); + } +} + +async function pollStopRequest() { + const capture = active; + if (!capture || capture.stopping) return; + try { + const result = await jsonFetch(`${capture.baseUrl}/api/captures/${capture.captureId}`, { cache: "no-store" }); + if (result.capture?.state === "stop_requested") await stopCapture("manual"); + } catch (error) { + await postStatus({ warning: `Could not read the stop signal: ${errorText(error)}` }).catch(() => undefined); + } +} + +async function stopCapture(reason) { + if (!active || active.stopping) return; + active.stopping = true; + active.stopReason = reason; + if (active.pollTimer) clearInterval(active.pollTimer); + await postStatus({ state: "flushing", stopReason: reason, bufferUsage: reason === "buffer_limit" ? SAFE_BUFFER_LIMIT : undefined }); + await chrome.debugger.sendCommand(active.debuggee, "Tracing.end"); +} + +function decodeBase64Bytes(value) { + const decoded = atob(value); + const bytes = new Uint8Array(decoded.length); + for (let index = 0; index < decoded.length; index += 1) bytes[index] = decoded.charCodeAt(index); + return bytes; +} + +async function uploadRawTraceStream(capture, handle) { + try { + while (true) { + // Pull only after the previous disk append is acknowledged. At most one + // fixed-size CDP read and one fetch body are retained by the extension. + const result = await chrome.debugger.sendCommand(capture.debuggee, "IO.read", { handle, size: MAX_UPLOAD_BYTES }); + const body = result.base64Encoded ? decodeBase64Bytes(result.data) : new TextEncoder().encode(result.data); + if (body.byteLength > 0) { + const response = await fetch(`${capture.baseUrl}/api/captures/${capture.captureId}/ingest/raw?sequence=${capture.sequence}`, { + method: "POST", + headers: { "Content-Type": "application/octet-stream", Authorization: `Bearer ${capture.token}` }, + body, + }); + const responseBody = await response.json().catch(() => ({})); + if (!response.ok) throw new Error(responseBody.error || `TraceSift returned HTTP ${response.status}.`); + capture.sequence += 1; + } + if (result.eof) break; + } + } finally { + await chrome.debugger.sendCommand(capture.debuggee, "IO.close", { handle }).catch(() => undefined); + } +} + +function decodeDataUrl(url) { + const comma = url.indexOf(","); + if (comma < 0) throw new Error("Malformed source-map data URL."); + const header = url.slice(0, comma); + const payload = url.slice(comma + 1); + return header.includes(";base64") ? atob(payload) : decodeURIComponent(payload); +} + +function resolveSourceMapUrl(script) { + return new URL(script.sourceMapURL, script.url || undefined).href; +} + +async function readProtocolStream(source, handle) { + let content = ""; + try { + while (true) { + const result = await chrome.debugger.sendCommand(source, "IO.read", { handle, size: 512 * 1024 }); + const part = result.base64Encoded ? atob(result.data) : result.data; + content += part; + if (content.length > MAX_SOURCE_MAP_BYTES) throw new Error("Source map exceeds the 8 MB retention limit."); + if (result.eof) return content; + } + } finally { + await chrome.debugger.sendCommand(source, "IO.close", { handle }).catch(() => undefined); + } +} + +async function loadSourceMap(capture, script) { + if (!script.url || !script.sourceMapURL || script.url.startsWith("chrome-extension:")) return null; + const sourceMapUrl = resolveSourceMapUrl(script); + let raw; + if (sourceMapUrl.startsWith("data:")) { + raw = decodeDataUrl(sourceMapUrl); + } else { + const source = { ...capture.debuggee, ...(script.sessionId ? { sessionId: script.sessionId } : {}) }; + const result = await chrome.debugger.sendCommand(source, "Network.loadNetworkResource", { + ...(script.frameId ? { frameId: script.frameId } : {}), + url: sourceMapUrl, + options: { disableCache: false, includeCredentials: true }, + }); + if (!result.resource?.success || !result.resource.stream) throw new Error(result.resource?.netErrorName || `Could not load ${sourceMapUrl}`); + raw = await readProtocolStream(source, result.resource.stream); + } + if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error("Source map exceeds the 8 MB retention limit."); + const sourceMap = JSON.parse(raw); + if (!sourceMap || typeof sourceMap !== "object" || Array.isArray(sourceMap)) throw new Error("Source map is not a JSON object."); + return { url: script.url, sourceMapUrl, sourceMap, bytes: raw.length }; +} + +async function collectSourceMaps(capture) { + const retained = []; + const warnings = []; + const seen = new Set(); + let bytes = 0; + for (const script of capture.scripts.values()) { + if (!script.sourceMapURL) continue; + let resolved; + try { resolved = resolveSourceMapUrl(script); } + catch { warnings.push(`Ignored an invalid source-map URL for ${script.url || "an anonymous script"}.`); continue; } + // DevTools does not duplicate data-URL maps in metadata: source-rundown + // events already carry their contents in the trace. + if (resolved.startsWith("data:")) continue; + const key = `${script.url}\n${resolved}`; + if (seen.has(key)) continue; + seen.add(key); + try { + const loaded = await loadSourceMap(capture, script); + if (!loaded) continue; + if (bytes + loaded.bytes > MAX_ALL_SOURCE_MAP_BYTES) { + warnings.push("Stopped retaining source maps after the 16 MB safety limit."); + break; + } + bytes += loaded.bytes; + retained.push({ url: loaded.url, sourceMapUrl: loaded.sourceMapUrl, sourceMap: loaded.sourceMap }); + } catch (error) { + warnings.push(`Could not retain the source map for ${script.url || "an anonymous script"}: ${errorText(error)}`); + } + } + return { retained, warnings }; +} + +async function finalize(params) { + const capture = active; + if (!capture) return; + if (capture.pollTimer) clearInterval(capture.pollTimer); + try { + if (!params.stream) throw new Error("Chrome completed tracing without returning a stream."); + await uploadRawTraceStream(capture, params.stream); + await postStatus({ state: "enriching" }); + const sourceMaps = await collectSourceMaps(capture); + await jsonFetch(`${capture.baseUrl}/api/captures/${capture.captureId}/ingest/finalize`, { + method: "POST", + headers: authHeaders(capture.token), + body: JSON.stringify({ + dataLoss: params.dataLossOccurred === true, + stopReason: capture.stopReason, + scripts: [...capture.scripts.values()], + sourceMaps: sourceMaps.retained, + warnings: sourceMaps.warnings, + mainFrame: capture.mainFrame, + traceMarker: capture.traceMarker, + }), + }); + } catch (error) { + await postStatus({ state: "failed", stopReason: "error", error: `Trace export failed: ${errorText(error)}` }).catch(() => undefined); + } finally { + await chrome.debugger.detach(capture.debuggee).catch(() => undefined); + if (active === capture) active = null; + } +} + +chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { + (async () => { + if (!senderIsPaired(sender)) throw new Error("Pair this TraceSift tab with the extension first."); + if (message.type === "STATUS") return { ok: true }; + if (message.type === "LIST_TARGETS") return { ok: true, targets: await targets() }; + if (message.type === "START") return startCapture(message); + throw new Error("Unknown TraceSift extension request."); + })().then(sendResponse, (error) => sendResponse({ ok: false, error: errorText(error) })); + return true; +}); + +chrome.debugger.onEvent.addListener((source, method, params = {}) => { + const capture = active; + if (!capture || source.tabId !== capture.debuggee.tabId) return; + + if (method === "Target.attachedToTarget") { + void configureChild({ ...capture.debuggee, sessionId: params.sessionId }); + return; + } + if (method === "Debugger.scriptParsed" && typeof params.scriptId === "string") { + if (capture.scripts.size >= 50_000) return; + capture.scripts.set(scriptKey(source, params), { + scriptId: params.scriptId, + url: params.url || "", + ...(params.sourceMapURL ? { sourceMapURL: params.sourceMapURL } : {}), + ...(typeof params.executionContextAuxData?.frameId === "string" ? { frameId: params.executionContextAuxData.frameId } : {}), + ...(source.sessionId ? { sessionId: source.sessionId } : {}), + }); + return; + } + if (method === "Tracing.bufferUsage") { + const usage = Number(params.percentFull ?? params.value ?? 0); + capture.lastEventCount = Math.max(capture.lastEventCount, Number(params.eventCount || 0)); + void postStatus({ bufferUsage: usage, eventCount: capture.lastEventCount }).catch(() => undefined); + if (usage >= SAFE_BUFFER_LIMIT) void stopCapture("buffer_limit").catch(async (error) => { + await postStatus({ state: "failed", stopReason: "error", error: errorText(error) }).catch(() => undefined); + }); + return; + } + // ReturnAsStream deliberately avoids dataCollected arrays: they can arrive + // faster than HTTP uploads and a promise queue would retain every batch. + if (method === "Tracing.tracingComplete") void finalize(params); +}); + +chrome.debugger.onDetach.addListener((source, reason) => { + const capture = active; + if (!capture || source.tabId !== capture.debuggee.tabId) return; + if (capture.stopping) return; + if (capture.pollTimer) clearInterval(capture.pollTimer); + void postStatus({ + state: "interrupted", + stopReason: reason === "target_closed" ? "target_closed" : "detached", + error: reason === "target_closed" ? "The captured tab was closed before Chrome flushed the trace." : "Chrome detached the profiler. Opening DevTools or dismissing Chrome’s debugging banner can cause this.", + }).finally(() => { if (active === capture) active = null; }); +}); + +chrome.action.onClicked.addListener((tab) => { + const approved = capturePageForTab(tab); + if (approved) { + pairing = approved; + void chrome.storage.session.set({ pairing }).then(() => chrome.tabs.sendMessage(approved.bridgeTabId, { type: "PAIRED_BY_USER" }).catch(() => undefined)); + return; + } + if (pairing?.baseUrl) void chrome.tabs.create({ url: `${pairing.baseUrl}/capture` }); +}); + +function forgetPairingForTab(tabId) { + if (pairing?.bridgeTabId !== tabId) return; + pairing = null; + void chrome.storage.session.remove("pairing"); +} + +// Approval belongs to the exact document on which the user clicked the +// extension action, not merely to a loopback port that another process could +// later claim. Reload/navigation requires another explicit click. +chrome.tabs.onUpdated.addListener((tabId, changeInfo) => { + if (changeInfo.status === "loading") forgetPairingForTab(tabId); +}); +chrome.tabs.onRemoved.addListener((tabId) => forgetPairingForTab(tabId)); diff --git a/packages/chrome-extension/bridge.js b/packages/chrome-extension/bridge.js new file mode 100644 index 0000000..3a69b31 --- /dev/null +++ b/packages/chrome-extension/bridge.js @@ -0,0 +1,21 @@ +const REQUEST_SOURCE = "tracesift-web-v1"; +const RESPONSE_SOURCE = "tracesift-extension-v1"; + +window.addEventListener("message", (event) => { + if (event.source !== window || event.origin !== window.location.origin) return; + const message = event.data; + if (!message || message.source !== REQUEST_SOURCE || typeof message.requestId !== "string") return; + + chrome.runtime.sendMessage(message).then( + (response) => window.postMessage({ source: RESPONSE_SOURCE, requestId: message.requestId, ...response }, event.origin), + (error) => window.postMessage({ source: RESPONSE_SOURCE, requestId: message.requestId, ok: false, error: error?.message || "TraceSift extension did not respond." }, event.origin), + ); +}); + +chrome.runtime.onMessage.addListener((message) => { + if (message?.type === "PAIRED_BY_USER") { + window.postMessage({ source: RESPONSE_SOURCE, type: "PAIRED_BY_USER" }, window.location.origin); + } +}); + +window.postMessage({ source: RESPONSE_SOURCE, type: "READY" }, window.location.origin); diff --git a/packages/chrome-extension/manifest.json b/packages/chrome-extension/manifest.json new file mode 100644 index 0000000..ff8be52 --- /dev/null +++ b/packages/chrome-extension/manifest.json @@ -0,0 +1,26 @@ +{ + "manifest_version": 3, + "name": "TraceSift Capture", + "version": "0.1.0", + "description": "Captures Chrome Performance traces directly into the local TraceSift app.", + "minimum_chrome_version": "125", + "permissions": ["debugger", "storage"], + "host_permissions": [ + "http://127.0.0.1/*", + "http://localhost/*" + ], + "background": { + "service_worker": "background.js", + "type": "module" + }, + "content_scripts": [ + { + "matches": ["http://127.0.0.1/*", "http://localhost/*"], + "js": ["bridge.js"], + "run_at": "document_start" + } + ], + "action": { + "default_title": "Open TraceSift Capture" + } +} diff --git a/src/app/api/captures/[id]/download/route.ts b/src/app/api/captures/[id]/download/route.ts new file mode 100644 index 0000000..b0a93c3 --- /dev/null +++ b/src/app/api/captures/[id]/download/route.ts @@ -0,0 +1,25 @@ +import { createReadStream } from "node:fs"; +import { Readable } from "node:stream"; + +import { captureExport } from "@/lib/capture-store"; + +export const runtime = "nodejs"; + +export async function GET(_request: Request, context: RouteContext<"/api/captures/[id]/download">): Promise { + const { id } = await context.params; + try { + const exported = await captureExport(id); + if (!exported) return Response.json({ error: "This capture has no export yet." }, { status: 404 }); + const body = Readable.toWeb(createReadStream(exported.path)) as ReadableStream; + return new Response(body, { + headers: { + "Content-Type": "application/gzip", + "Content-Length": String(exported.sizeBytes), + "Content-Disposition": `attachment; filename="${exported.fileName}"`, + "Cache-Control": "private, no-store", + }, + }); + } catch { + return Response.json({ error: "Invalid capture id." }, { status: 400 }); + } +} diff --git a/src/app/api/captures/[id]/ingest/finalize/route.ts b/src/app/api/captures/[id]/ingest/finalize/route.ts new file mode 100644 index 0000000..aece914 --- /dev/null +++ b/src/app/api/captures/[id]/ingest/finalize/route.ts @@ -0,0 +1,28 @@ +import { bearerToken, finalizeCapture } from "@/lib/capture-store"; +import type { CaptureMainFrame, CaptureScriptMetadata, CaptureSourceMap, CaptureStopReason } from "@/lib/capture-types"; + +export const runtime = "nodejs"; + +const reasons = new Set(["manual", "buffer_limit", "target_closed", "detached", "shutdown", "error"]); + +export async function POST(request: Request, context: RouteContext<"/api/captures/[id]/ingest/finalize">): Promise { + const { id } = await context.params; + let body: { dataLoss?: unknown; stopReason?: unknown; scripts?: unknown; sourceMaps?: unknown; warnings?: unknown; mainFrame?: unknown; traceMarker?: unknown }; + try { body = await request.json(); } + catch { return Response.json({ error: "Expected capture finalization details." }, { status: 400 }); } + try { + const capture = await finalizeCapture(id, bearerToken(request), { + dataLoss: body.dataLoss === true, + stopReason: reasons.has(body.stopReason as CaptureStopReason) ? body.stopReason as CaptureStopReason : undefined, + scripts: Array.isArray(body.scripts) ? body.scripts as CaptureScriptMetadata[] : [], + sourceMaps: Array.isArray(body.sourceMaps) ? body.sourceMaps as CaptureSourceMap[] : [], + warnings: Array.isArray(body.warnings) ? body.warnings.map(String) : [], + mainFrame: body.mainFrame && typeof body.mainFrame === "object" ? body.mainFrame as CaptureMainFrame : undefined, + traceMarker: typeof body.traceMarker === "string" ? body.traceMarker : undefined, + }); + return Response.json({ capture }); + } catch (error) { + const message = error instanceof Error ? error.message : "Could not finalize the capture."; + return Response.json({ error: message }, { status: message.includes("authorization") ? 401 : 400 }); + } +} diff --git a/src/app/api/captures/[id]/ingest/raw/route.ts b/src/app/api/captures/[id]/ingest/raw/route.ts new file mode 100644 index 0000000..2ee103b --- /dev/null +++ b/src/app/api/captures/[id]/ingest/raw/route.ts @@ -0,0 +1,20 @@ +import { appendCaptureRawChunk, bearerToken, MAX_RAW_CHUNK_BYTES } from "@/lib/capture-store"; + +export const runtime = "nodejs"; + +export async function POST(request: Request, context: RouteContext<"/api/captures/[id]/ingest/raw">): Promise { + const { id } = await context.params; + try { + const sequence = Number(new URL(request.url).searchParams.get("sequence")); + const declaredLength = Number(request.headers.get("content-length") ?? 0); + if (!Number.isSafeInteger(sequence) || sequence < 0) throw new Error("Expected a non-negative trace chunk sequence."); + if (declaredLength > MAX_RAW_CHUNK_BYTES) throw new Error("Raw trace chunk exceeds the 1 MB limit."); + const bytes = new Uint8Array(await request.arrayBuffer()); + if (bytes.byteLength > MAX_RAW_CHUNK_BYTES) throw new Error("Raw trace chunk exceeds the 1 MB limit."); + const capture = await appendCaptureRawChunk(id, bearerToken(request), sequence, bytes); + return Response.json({ nextSequence: capture.chunkCount }); + } catch (error) { + const message = error instanceof Error ? error.message : "Could not append the raw trace chunk."; + return Response.json({ error: message }, { status: message.includes("authorization") ? 401 : 409 }); + } +} diff --git a/src/app/api/captures/[id]/ingest/status/route.ts b/src/app/api/captures/[id]/ingest/status/route.ts new file mode 100644 index 0000000..16ee2a9 --- /dev/null +++ b/src/app/api/captures/[id]/ingest/status/route.ts @@ -0,0 +1,35 @@ +import { bearerToken, failCapture, updateCaptureFromExtension } from "@/lib/capture-store"; +import type { CaptureStopReason } from "@/lib/capture-types"; + +export const runtime = "nodejs"; + +const states = new Set(["attaching", "recording", "flushing", "enriching", "failed", "interrupted"]); +const reasons = new Set(["manual", "buffer_limit", "target_closed", "detached", "shutdown", "error"]); + +export async function POST(request: Request, context: RouteContext<"/api/captures/[id]/ingest/status">): Promise { + const { id } = await context.params; + let body: { state?: unknown; stopReason?: unknown; bufferUsage?: unknown; eventCount?: unknown; warning?: unknown; error?: unknown }; + try { body = await request.json(); } + catch { return Response.json({ error: "Expected a status update." }, { status: 400 }); } + try { + if ((body.state === "failed" || body.state === "interrupted") && typeof body.error === "string") { + return Response.json({ capture: await failCapture(id, bearerToken(request), { + error: body.error, + interrupted: body.state === "interrupted", + reason: reasons.has(body.stopReason as CaptureStopReason) ? body.stopReason as CaptureStopReason : undefined, + }) }); + } + const capture = await updateCaptureFromExtension(id, bearerToken(request), { + state: states.has(String(body.state)) ? body.state as "attaching" | "recording" | "flushing" | "enriching" : undefined, + stopReason: reasons.has(body.stopReason as CaptureStopReason) ? body.stopReason as CaptureStopReason : undefined, + bufferUsage: typeof body.bufferUsage === "number" ? body.bufferUsage : undefined, + eventCount: typeof body.eventCount === "number" ? body.eventCount : undefined, + warning: typeof body.warning === "string" ? body.warning : undefined, + error: typeof body.error === "string" ? body.error : undefined, + }); + return Response.json({ capture }); + } catch (error) { + const message = error instanceof Error ? error.message : "Could not update capture status."; + return Response.json({ error: message }, { status: message.includes("authorization") ? 401 : 400 }); + } +} diff --git a/src/app/api/captures/[id]/route.ts b/src/app/api/captures/[id]/route.ts new file mode 100644 index 0000000..d688a26 --- /dev/null +++ b/src/app/api/captures/[id]/route.ts @@ -0,0 +1,26 @@ +import { deleteCapture, getCapture } from "@/lib/capture-store"; + +export const runtime = "nodejs"; + +export async function GET(_request: Request, context: RouteContext<"/api/captures/[id]">): Promise { + const { id } = await context.params; + try { + const capture = await getCapture(id); + return capture + ? Response.json({ capture }, { headers: { "Cache-Control": "no-store" } }) + : Response.json({ error: "Capture not found." }, { status: 404 }); + } catch { + return Response.json({ error: "Invalid capture id." }, { status: 400 }); + } +} + +export async function DELETE(_request: Request, context: RouteContext<"/api/captures/[id]">): Promise { + const { id } = await context.params; + try { + return await deleteCapture(id) + ? new Response(null, { status: 204 }) + : Response.json({ error: "Capture not found." }, { status: 404 }); + } catch (error) { + return Response.json({ error: error instanceof Error ? error.message : "Could not delete the capture." }, { status: 409 }); + } +} diff --git a/src/app/api/captures/[id]/stop/route.ts b/src/app/api/captures/[id]/stop/route.ts new file mode 100644 index 0000000..5bdbbea --- /dev/null +++ b/src/app/api/captures/[id]/stop/route.ts @@ -0,0 +1,13 @@ +import { requestCaptureStop } from "@/lib/capture-store"; + +export const runtime = "nodejs"; + +export async function POST(_request: Request, context: RouteContext<"/api/captures/[id]/stop">): Promise { + const { id } = await context.params; + try { + return Response.json({ capture: await requestCaptureStop(id) }); + } catch (error) { + const message = error instanceof Error ? error.message : "Could not stop the capture."; + return Response.json({ error: message }, { status: message === "Capture not found." ? 404 : 400 }); + } +} diff --git a/src/app/api/captures/route.ts b/src/app/api/captures/route.ts new file mode 100644 index 0000000..cc2a2a6 --- /dev/null +++ b/src/app/api/captures/route.ts @@ -0,0 +1,26 @@ +import { createCapture, listCaptures } from "@/lib/capture-store"; + +export const runtime = "nodejs"; + +export async function GET(): Promise { + return Response.json({ captures: await listCaptures() }, { headers: { "Cache-Control": "no-store" } }); +} + +export async function POST(request: Request): Promise { + let body: { title?: unknown; target?: { tabId?: unknown; title?: unknown; url?: unknown } }; + try { body = await request.json(); } + catch { return Response.json({ error: "Expected capture details." }, { status: 400 }); } + const target = body.target; + if (!target || typeof target.tabId !== "number" || typeof target.title !== "string" || typeof target.url !== "string") { + return Response.json({ error: "Choose a Chrome tab to capture." }, { status: 400 }); + } + try { + const result = await createCapture({ + title: typeof body.title === "string" ? body.title : undefined, + target: { tabId: target.tabId, title: target.title, url: target.url }, + }); + return Response.json(result, { status: 201 }); + } catch (error) { + return Response.json({ error: error instanceof Error ? error.message : "Could not create the capture." }, { status: 409 }); + } +} diff --git a/src/app/capture/page.tsx b/src/app/capture/page.tsx new file mode 100644 index 0000000..ddb6ad6 --- /dev/null +++ b/src/app/capture/page.tsx @@ -0,0 +1,266 @@ +"use client"; + +import Image from "next/image"; +import Link from "next/link"; +import { useCallback, useEffect, useMemo, useRef, useState } from "react"; +import { Button, PluginHeader, PluginShell } from "@rozenite/ui"; + +import { ThemeGate } from "@/app/theme-gate"; +import type { CaptureRecord, CaptureTarget } from "@/lib/capture-types"; + +type ExtensionReply = { ok: boolean; error?: string; targets?: CaptureTarget[] }; + +const REQUEST_SOURCE = "tracesift-web-v1"; +const RESPONSE_SOURCE = "tracesift-extension-v1"; + +function message(error: unknown): string { + return error instanceof Error ? error.message : "Something went wrong."; +} + +function formatBytes(bytes: number): string { + if (bytes < 1024) return `${bytes} B`; + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`; + return `${(bytes / 1024 / 1024).toFixed(1)} MB`; +} + +function stateLabel(state: CaptureRecord["state"]): string { + return state.replaceAll("_", " "); +} + +function CapturePage() { + const [extensionState, setExtensionState] = useState<"disconnected" | "connecting" | "connected">("disconnected"); + const [targets, setTargets] = useState([]); + const [selectedTab, setSelectedTab] = useState(null); + const [captures, setCaptures] = useState([]); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(null); + const requests = useRef(new Map void; timeout: number }>()); + + const bridgeRequest = useCallback((type: string, payload: Record = {}): Promise => { + const requestId = crypto.randomUUID(); + return new Promise((resolve) => { + const timeout = window.setTimeout(() => { + requests.current.delete(requestId); + resolve({ ok: false, error: "The TraceSift extension did not respond. Install or reload it, then try again." }); + }, 5000); + requests.current.set(requestId, { resolve, timeout }); + window.postMessage({ source: REQUEST_SOURCE, requestId, type, ...payload }, window.location.origin); + }); + }, []); + + const loadCaptures = useCallback(async () => { + const response = await fetch("/api/captures", { cache: "no-store" }); + const body = await response.json() as { captures?: CaptureRecord[] }; + if (response.ok) setCaptures(body.captures ?? []); + }, []); + + const refreshTargets = useCallback(async () => { + const reply = await bridgeRequest("LIST_TARGETS"); + if (!reply.ok) throw new Error(reply.error || "Could not read Chrome tabs."); + const nextTargets = reply.targets ?? []; + setTargets(nextTargets); + setSelectedTab((current) => nextTargets.some((target) => target.tabId === current) ? current : nextTargets[0]?.tabId ?? null); + }, [bridgeRequest]); + + useEffect(() => { + const pendingRequests = requests.current; + const receive = (event: MessageEvent) => { + if (event.source !== window || event.origin !== window.location.origin || event.data?.source !== RESPONSE_SOURCE) return; + if (event.data.type === "PAIRED_BY_USER") { + setExtensionState("connected"); + setError(null); + void refreshTargets().catch((caught) => setError(message(caught))); + return; + } + const pending = requests.current.get(event.data.requestId); + if (!pending) return; + window.clearTimeout(pending.timeout); + requests.current.delete(event.data.requestId); + pending.resolve(event.data as ExtensionReply); + }; + window.addEventListener("message", receive); + const initialLoad = window.setTimeout(() => void loadCaptures(), 0); + const connectionCheck = window.setTimeout(() => void bridgeRequest("STATUS").then((reply) => { + if (reply.ok) { + setExtensionState("connected"); + void refreshTargets().catch(() => undefined); + } + }), 0); + const timer = window.setInterval(() => void loadCaptures(), 1000); + return () => { + window.removeEventListener("message", receive); + window.clearTimeout(initialLoad); + window.clearTimeout(connectionCheck); + window.clearInterval(timer); + for (const pending of pendingRequests.values()) window.clearTimeout(pending.timeout); + pendingRequests.clear(); + }; + }, [bridgeRequest, loadCaptures, refreshTargets]); + + const connect = async () => { + setBusy(true); setError(null); setExtensionState("connecting"); + try { + const reply = await bridgeRequest("STATUS"); + if (!reply.ok) throw new Error("Click the TraceSift Capture extension in Chrome’s toolbar while this exact page is active, then check again."); + setExtensionState("connected"); + await refreshTargets(); + } catch (caught) { + setExtensionState("disconnected"); + setError(message(caught)); + } finally { setBusy(false); } + }; + + const start = async () => { + const target = targets.find((candidate) => candidate.tabId === selectedTab); + if (!target) return; + setBusy(true); setError(null); + let created: { capture: CaptureRecord; uploadToken: string } | undefined; + try { + const response = await fetch("/api/captures", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ target }), + }); + const body = await response.json() as { capture?: CaptureRecord; uploadToken?: string; error?: string }; + if (!response.ok || !body.capture || !body.uploadToken) throw new Error(body.error || "Could not create the capture."); + created = { capture: body.capture, uploadToken: body.uploadToken }; + const reply = await bridgeRequest("START", { + baseUrl: window.location.origin, + captureId: body.capture.id, + token: body.uploadToken, + target, + }); + if (!reply.ok) throw new Error(reply.error || "Chrome refused the profiling connection."); + await loadCaptures(); + } catch (caught) { + const text = message(caught); + if (created) { + await fetch(`/api/captures/${created.capture.id}/ingest/status`, { + method: "POST", + headers: { "Content-Type": "application/json", Authorization: `Bearer ${created.uploadToken}` }, + body: JSON.stringify({ state: "failed", stopReason: "error", error: text }), + }).catch(() => undefined); + } + setError(text); + } finally { setBusy(false); } + }; + + const stop = async (id: string) => { + setError(null); + const response = await fetch(`/api/captures/${id}/stop`, { method: "POST" }); + const body = await response.json().catch(() => ({})) as { error?: string }; + if (!response.ok) setError(body.error || "Could not stop the capture."); + await loadCaptures(); + }; + + const remove = async (id: string) => { + setError(null); + const response = await fetch(`/api/captures/${id}`, { method: "DELETE" }); + const body = await response.json().catch(() => ({})) as { error?: string }; + if (!response.ok) setError(body.error || "Could not delete the capture."); + await loadCaptures(); + }; + + const active = useMemo(() => captures.find((capture) => ["pending", "attaching", "recording", "stop_requested", "flushing", "enriching"].includes(capture.state)), [captures]); + + return ( + + + }> + + TraceSiftby Callstack + + + + + + + + +
+
+ Chrome performance capture +

Record demanding flows without loading the trace into DevTools.

+

Chrome collects the same timeline and V8 CPU samples. TraceSift streams the result to local disk and keeps it until you delete it.

+
+ + {error &&
Capture could not continue{error}
} + +
+
+
1

Connect Chrome

The extension is a local CDP bridge and attaches only when you start recording.

+ {extensionState} +
+ {extensionState !== "connected" ? ( +
+

Approve this page in ChromeClick the TraceSift Capture extension in Chrome’s toolbar while this page is active. A website cannot approve itself.

+ +

For development, load packages/chrome-extension from chrome://extensions. Chrome 125+ is required.

+
+ ) : ( +
+ + + +
+ )} +
+ +
+
+
2

Record the flow

TraceSift automatically stops before Chrome’s trace buffer fills.

+
+ {active ? ( +
+ + ) : ( +
+
Ready to recordStart here, perform the flow in the selected tab, then return to stop.
+ +
+ )} +
+ +
+
Local library

Saved captures

{captures.length} capture{captures.length === 1 ? "" : "s"}
+ {captures.length === 0 ?
Completed captures will remain here until you delete them.
: ( +
+ {captures.map((capture) => ( +
+
+
{capture.title}{stateLabel(capture.state)}
+ {new Date(capture.createdAt).toLocaleString()} · {capture.eventCount.toLocaleString()} events · {capture.export ? formatBytes(capture.export.sizeBytes) : formatBytes(capture.byteCount)} + {capture.target.url} + {capture.error &&

{capture.error}

} + {capture.warnings.length > 0 &&

{capture.warnings.join(" ")}

} +
+
+ {capture.export && } + {!["pending", "attaching", "recording", "stop_requested", "flushing", "enriching"].includes(capture.state) && } +
+
+ ))} +
+ )} +
+
+
+
+ ); +} + +export default function Capture() { + return ; +} diff --git a/src/app/globals.css b/src/app/globals.css index d675751..ef12388 100644 --- a/src/app/globals.css +++ b/src/app/globals.css @@ -32,6 +32,67 @@ body { color-scheme: dark; } +.capture-workspace { + width: min(980px, calc(100% - 40px)); + margin: 0 auto; + padding: 48px 0 64px; +} +.capture-intro { max-width: 760px; } +.capture-intro h1 { margin: 12px 0; font-size: clamp(30px, 4vw, 43px); line-height: 1.08; letter-spacing: -0.045em; } +.capture-intro p { margin: 0 0 34px; color: var(--muted-foreground); font-size: 16px; line-height: 1.6; } +.capture-error { display: flex; flex-direction: column; gap: 4px; margin: 0 0 18px; padding: 14px 16px; color: var(--danger); background: color-mix(in srgb, var(--danger) 8%, var(--card)); border: 1px solid color-mix(in srgb, var(--danger) 35%, var(--border)); } +.capture-error span { color: var(--foreground); font-size: 13px; } +.capture-panel { margin-top: 16px; padding: 22px; background: var(--card); border: 1px solid var(--border); } +.capture-panel-head, .capture-panel-head > div, .capture-target-row, .capture-active, .capture-ready, .capture-library-head, .capture-item, .capture-item-title, .capture-item-actions { display: flex; align-items: center; } +.capture-panel-head { justify-content: space-between; gap: 20px; } +.capture-panel-head > div { gap: 12px; } +.capture-panel-head h2, .capture-library h2 { margin: 0; font-size: 18px; letter-spacing: -0.02em; } +.capture-panel-head p { margin: 4px 0 0; color: var(--muted-foreground); font-size: 13px; } +.capture-step { width: 27px; height: 27px; display: grid; flex: 0 0 auto; place-items: center; color: var(--primary-foreground); background: var(--foreground); border-radius: 50%; font-size: 13px; font-weight: 700; } +.capture-connection { padding: 5px 9px; color: var(--muted-foreground); background: var(--muted); font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase; } +.capture-connection.connected { color: #059669; background: color-mix(in srgb, #10b981 12%, var(--muted)); } +.capture-connection.connecting { color: #d97706; } +.capture-connect { margin: 20px 0 0 39px; } +.capture-approval { display: flex; flex-direction: column; gap: 3px; margin-bottom: 12px !important; color: var(--foreground) !important; } +.capture-approval span { color: var(--muted-foreground); font-weight: 400; } +.capture-connect p { margin: 10px 0 0; color: var(--muted-foreground); font-size: 12px; } +.capture-connect code { padding: 2px 5px; background: var(--muted); font-family: var(--font-mono, monospace); } +.capture-target-row { gap: 12px; margin: 20px 0 0 39px; } +.capture-target-row label { flex: 0 0 auto; font-size: 13px; font-weight: 700; } +.capture-target-row select { min-width: 0; flex: 1; height: 36px; padding: 0 10px; color: var(--foreground); background: var(--background); border: 1px solid var(--border); } +.capture-ready, .capture-active { justify-content: space-between; gap: 18px; margin: 20px 0 0 39px; padding: 18px; background: var(--muted); } +.capture-ready > div, .capture-active-copy { display: flex; min-width: 0; flex: 1; flex-direction: column; gap: 5px; } +.capture-ready span, .capture-active-copy span { color: var(--muted-foreground); font-size: 13px; } +.capture-pulse { width: 12px; height: 12px; flex: 0 0 auto; background: #ef4444; border-radius: 50%; box-shadow: 0 0 0 5px color-mix(in srgb, #ef4444 17%, transparent); } +.capture-buffer { height: 4px; margin-top: 5px; overflow: hidden; background: var(--border); } +.capture-buffer span { display: block; height: 100%; background: var(--primary); transition: width 240ms ease; } +.capture-library { margin-top: 40px; } +.capture-library-head { justify-content: space-between; margin-bottom: 12px; } +.capture-library-head h2 { margin-top: 5px; font-size: 24px; } +.capture-library-head > span { color: var(--muted-foreground); font-size: 13px; } +.capture-empty { padding: 34px; color: var(--muted-foreground); background: var(--card); border: 1px dashed var(--border); text-align: center; } +.capture-list { display: grid; gap: 10px; } +.capture-item { justify-content: space-between; gap: 20px; padding: 18px; background: var(--card); border: 1px solid var(--border); } +.capture-item-main { min-width: 0; display: flex; flex: 1; flex-direction: column; gap: 5px; } +.capture-item-title { gap: 10px; } +.capture-item-main > span, .capture-item-main > small { overflow: hidden; color: var(--muted-foreground); font-size: 12px; text-overflow: ellipsis; white-space: nowrap; } +.capture-state { padding: 3px 7px; color: var(--muted-foreground); background: var(--muted); font-size: 10px; font-weight: 700; letter-spacing: .05em; text-transform: uppercase; } +.capture-state.recording { color: #dc2626; background: color-mix(in srgb, #ef4444 10%, var(--muted)); } +.capture-state.captured, .capture-state.captured_with_warnings { color: #059669; background: color-mix(in srgb, #10b981 10%, var(--muted)); } +.capture-state.failed, .capture-state.interrupted { color: var(--danger); } +.capture-item-actions { flex: 0 0 auto; gap: 8px; } +.capture-item-error, .capture-item-warning { margin: 3px 0 0; font-size: 12px; line-height: 1.4; } +.capture-item-error { color: var(--danger); } +.capture-item-warning { color: #d97706; } + +@media (max-width: 700px) { + .capture-target-row, .capture-ready, .capture-active { margin-left: 0; align-items: stretch; flex-direction: column; } + .capture-target-row label { margin-top: 4px; } + .capture-panel-head, .capture-item { align-items: flex-start; } + .capture-item { flex-direction: column; } + .capture-item-actions { width: 100%; } +} + * { box-sizing: border-box; } body { diff --git a/src/app/page.tsx b/src/app/page.tsx index 6eb77ce..69c4d1b 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -1,6 +1,7 @@ "use client"; import Image from "next/image"; +import Link from "next/link"; import { ChangeEvent, DragEvent, ReactNode, useEffect, useId, useRef, useState } from "react"; import { Alert, @@ -1803,6 +1804,9 @@ function InspectorApp() { TraceSiftby Callstack + diff --git a/src/lib/capture-store.ts b/src/lib/capture-store.ts new file mode 100644 index 0000000..6fafd49 --- /dev/null +++ b/src/lib/capture-store.ts @@ -0,0 +1,581 @@ +import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto"; +import { createReadStream, createWriteStream } from "node:fs"; +import { + appendFile, + chmod, + mkdir, + readFile, + readdir, + rename, + rm, + stat, + writeFile, +} from "node:fs/promises"; +import { homedir } from "node:os"; +import { basename, join, resolve } from "node:path"; +import { finished } from "node:stream/promises"; +import { createGzip } from "node:zlib"; + +import { + ACTIVE_CAPTURE_STATES, + type CaptureRecord, + type CaptureMainFrame, + type CaptureScriptMetadata, + type CaptureSourceMap, + type CaptureState, + type CaptureStopReason, + type CaptureTarget, +} from "./capture-types.ts"; + +interface StoredCapture extends CaptureRecord { + uploadTokenHash: string; + ownerInstance: string; +} + +interface CaptureStoreShared { + mutation: Promise; + instance: string; +} + +const shared = (globalThis as typeof globalThis & { [key: symbol]: CaptureStoreShared })[ + Symbol.for("tracesift.capture-store.v1") +] ??= { mutation: Promise.resolve(), instance: process.env.TRACE_SIFT_INSTANCE || randomUUID() }; + +const CAPTURE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; +// IO.read is deliberately smaller than this limit. Keeping the server limit +// close to the read size prevents either side from retaining a large request. +export const MAX_RAW_CHUNK_BYTES = 1024 * 1024; +const MAX_TRACE_PREFIX_BYTES = 1024 * 1024; +const MAX_INSPECTED_EVENT_BYTES = 512 * 1024; +const MAX_WARNING_LENGTH = 500; +const TERMINAL_STATES = new Set(["captured", "captured_with_warnings", "failed", "interrupted"]); + +function storeRoot(): string { + const home = resolve(/* turbopackIgnore: true */ process.env.TRACE_SIFT_HOME || join(homedir(), ".tracesift")); + return join(home, "captures"); +} + +function captureDir(id: string): string { + if (!CAPTURE_ID.test(id)) throw new Error("Invalid capture id."); + return join(storeRoot(), id); +} + +function metadataPath(id: string): string { return join(captureDir(id), "capture.json"); } +function spoolPath(id: string): string { return join(captureDir(id), "trace.spool"); } +function scriptsPath(id: string): string { return join(captureDir(id), "scripts.json"); } + +function hashToken(token: string): string { + return createHash("sha256").update(token).digest("hex"); +} + +function publicRecord(record: StoredCapture): CaptureRecord { + const { uploadTokenHash: _secret, ownerInstance: _owner, ...visible } = record; + void _secret; void _owner; + return visible; +} + +function cleanText(value: string, maximum: number): string { + return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, maximum); +} + +function safeTarget(target: CaptureTarget): CaptureTarget { + if (!Number.isSafeInteger(target.tabId) || target.tabId < 0) throw new Error("Choose a valid Chrome tab."); + return { + tabId: target.tabId, + title: cleanText(target.title || "Untitled tab", 300), + url: cleanText(target.url || "", 4000), + }; +} + +async function ensureRoot(): Promise { + await mkdir(storeRoot(), { recursive: true, mode: 0o700 }); + await chmod(storeRoot(), 0o700); +} + +async function readStored(id: string): Promise { + let raw: string; + try { raw = await readFile(metadataPath(id), "utf8"); } + catch (error) { + if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; + throw error; + } + return JSON.parse(raw) as StoredCapture; +} + +async function writeStored(record: StoredCapture): Promise { + const temporary = join(captureDir(record.id), `.capture-${randomUUID()}.tmp`); + try { + await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { flag: "wx", mode: 0o600 }); + await rename(temporary, metadataPath(record.id)); + } finally { + await rm(temporary, { force: true }); + } +} + +function mutate(operation: () => Promise): Promise { + const result = shared.mutation.then(operation, operation); + shared.mutation = result.catch(() => undefined); + return result; +} + +function tokenMatches(record: StoredCapture, token: string): boolean { + if (!token) return false; + const expected = Buffer.from(record.uploadTokenHash, "hex"); + const supplied = Buffer.from(hashToken(token), "hex"); + return expected.length === supplied.length && timingSafeEqual(expected, supplied); +} + +async function authorized(id: string, token: string): Promise { + const record = await readStored(id); + if (!record || !tokenMatches(record, token)) throw new Error("Capture authorization failed."); + return record; +} + +export async function createCapture(input: { title?: string; target: CaptureTarget }): Promise<{ capture: CaptureRecord; uploadToken: string }> { + return mutate(async () => { + const active = (await listCaptures()).find((record) => ACTIVE_CAPTURE_STATES.has(record.state)); + if (active) throw new Error(`A capture is already active for “${active.target.title}”.`); + + await ensureRoot(); + const id = randomUUID(); + const uploadToken = randomBytes(32).toString("base64url"); + const dir = captureDir(id); + await mkdir(dir, { mode: 0o700 }); + const now = Date.now(); + const target = safeTarget(input.target); + const record: StoredCapture = { + id, + createdAt: now, + updatedAt: now, + title: cleanText(input.title || target.title || "Chrome performance capture", 300), + target, + state: "pending", + bufferUsage: 0, + eventCount: 0, + chunkCount: 0, + byteCount: 0, + dataLoss: false, + scriptsSeen: 0, + sourceMapsSeen: 0, + warnings: [], + uploadTokenHash: hashToken(uploadToken), + ownerInstance: shared.instance, + }; + await writeFile(spoolPath(id), "", { flag: "wx", mode: 0o600 }); + await writeStored(record); + return { capture: publicRecord(record), uploadToken }; + }); +} + +export async function getCapture(id: string): Promise { + const record = await readStored(id); + return record ? publicRecord(record) : undefined; +} + +export async function listCaptures(): Promise { + await ensureRoot(); + const entries = await readdir(storeRoot(), { withFileTypes: true }); + const records = (await Promise.all(entries.filter((entry) => entry.isDirectory() && CAPTURE_ID.test(entry.name)).map((entry) => readStored(entry.name)))) + .filter((record): record is StoredCapture => Boolean(record)); + for (const record of records) { + if (ACTIVE_CAPTURE_STATES.has(record.state) && record.ownerInstance !== shared.instance) { + record.state = "interrupted"; + record.stopReason = "shutdown"; + record.error = "TraceSift stopped before Chrome completed this capture."; + record.stoppedAt = Date.now(); + record.updatedAt = record.stoppedAt; + await writeStored(record); + } + } + return records.map(publicRecord).sort((a, b) => b.createdAt - a.createdAt); +} + +export async function requestCaptureStop(id: string): Promise { + return mutate(async () => { + const record = await readStored(id); + if (!record) throw new Error("Capture not found."); + if (record.state !== "recording" && record.state !== "attaching") return publicRecord(record); + record.state = "stop_requested"; + record.stopReason = "manual"; + record.updatedAt = Date.now(); + await writeStored(record); + return publicRecord(record); + }); +} + +export async function updateCaptureFromExtension(id: string, token: string, update: { + state?: "attaching" | "recording" | "flushing" | "enriching" | "failed" | "interrupted"; + stopReason?: CaptureStopReason; + bufferUsage?: number; + eventCount?: number; + warning?: string; + error?: string; +}): Promise { + return mutate(async () => { + const record = await authorized(id, token); + if (TERMINAL_STATES.has(record.state)) return publicRecord(record); + // A Stop click can race with Chrome's attach handshake. Do not let the + // extension's late "recording" acknowledgement erase that stop request; + // its poller will observe it and end tracing immediately. + if (update.state && !(record.state === "stop_requested" && (update.state === "attaching" || update.state === "recording"))) { + record.state = update.state; + } + if (update.state === "recording" && !record.startedAt) record.startedAt = Date.now(); + if (update.stopReason) record.stopReason = update.stopReason; + if (typeof update.bufferUsage === "number" && Number.isFinite(update.bufferUsage)) { + record.bufferUsage = Math.max(record.bufferUsage, Math.min(1, Math.max(0, update.bufferUsage))); + } + if (typeof update.eventCount === "number" && Number.isSafeInteger(update.eventCount) && update.eventCount >= 0) { + record.eventCount = Math.max(record.eventCount, update.eventCount); + } + if (update.warning) record.warnings.push(cleanText(update.warning, MAX_WARNING_LENGTH)); + if (update.error) record.error = cleanText(update.error, 2000); + record.updatedAt = Date.now(); + await writeStored(record); + return publicRecord(record); + }); +} + +export async function appendCaptureRawChunk(id: string, token: string, sequence: number, bytes: Uint8Array): Promise { + return mutate(async () => { + const record = await authorized(id, token); + if (!Number.isSafeInteger(sequence) || sequence !== record.chunkCount) { + throw new Error(`Expected trace chunk ${record.chunkCount}, received ${sequence}.`); + } + if (!(bytes instanceof Uint8Array) || bytes.byteLength > MAX_RAW_CHUNK_BYTES) { + throw new Error("Raw trace chunk exceeds the 1 MB limit."); + } + if (bytes.byteLength > 0) await appendFile(spoolPath(id), bytes); + record.chunkCount += 1; + record.byteCount += bytes.byteLength; + if (record.state !== "stop_requested") record.state = "flushing"; + record.updatedAt = Date.now(); + await writeStored(record); + return publicRecord(record); + }); +} + +async function writeWithBackpressure(stream: NodeJS.WritableStream, chunk: Uint8Array | string): Promise { + if (!stream.write(chunk)) await new Promise((resolveDrain) => stream.once("drain", resolveDrain)); +} + +/** + * Copy only the traceEvents array body from Chrome's JSON trace stream. + * + * ReturnAsStream still produces one valid JSON document. We never parse or + * retain its events: this small byte-level state machine locates the array and + * streams its contents into the enhanced-trace wrapper. JSON punctuation is + * ASCII, so scanning bytes remains correct across UTF-8 and input boundaries. + */ +async function copyTraceEvents(spool: string, output: NodeJS.WritableStream): Promise { + let prefix = Buffer.alloc(0); + let started = false; + let ended = false; + let depth = 0; + let inString = false; + let escaped = false; + let objectDepth = 0; + let eventCount = 0; + + const copyArrayBytes = async (bytes: Buffer): Promise => { + const sliceStart = 0; + for (let index = 0; index < bytes.length; index += 1) { + const byte = bytes[index]; + if (inString) { + if (escaped) escaped = false; + else if (byte === 0x5c) escaped = true; + else if (byte === 0x22) inString = false; + continue; + } + if (byte === 0x22) inString = true; + else if (byte === 0x5b) depth += 1; + else if (byte === 0x7b) { + if (depth === 1 && objectDepth === 0) eventCount += 1; + objectDepth += 1; + } + else if (byte === 0x7d) objectDepth -= 1; + else if (byte === 0x5d) { + depth -= 1; + if (depth === 0) { + if (index > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart, index)); + ended = true; + return; + } + } + } + if (bytes.length > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart)); + }; + + for await (const value of createReadStream(spool)) { + if (ended) break; + let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); + if (!started) { + prefix = Buffer.concat([prefix, chunk]); + if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) throw new Error("Chrome trace is missing a traceEvents array near its start."); + const text = prefix.toString("utf8"); + const first = text.search(/\S/); + let opening = first >= 0 && text[first] === "[" ? first : -1; + if (opening < 0) { + const marker = text.indexOf('"traceEvents"'); + if (marker >= 0) opening = text.indexOf("[", marker + 13); + } + if (opening < 0) continue; + // The stream can be either a bare trace-event array or Chrome's usual + // {"traceEvents":[...]} object. Start immediately after its outer array. + chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), "utf8")); + prefix = Buffer.alloc(0); + started = true; + depth = 1; + } + await copyArrayBytes(chunk); + } + if (!started || !ended || inString || depth !== 0 || objectDepth !== 0) throw new Error("Chrome returned an incomplete trace stream."); + return eventCount; +} + +async function inspectTraceMetadata(spool: string, traceMarker: string): Promise<{ + hasInspectorMetadata: boolean; + marker?: { pid: number; tid: number; ts: number }; +}> { + let prefix = Buffer.alloc(0); + let started = false; + let depth = 0; + let objectDepth = 0; + let inString = false; + let escaped = false; + let eventParts: Buffer[] = []; + let eventBytes = 0; + let eventOverflow = false; + let capturingEvent = false; + let hasInspectorMetadata = false; + + const inspectEvent = (): { pid: number; tid: number; ts: number } | undefined => { + if (eventOverflow) return undefined; + try { + const event = JSON.parse(Buffer.concat(eventParts, eventBytes).toString("utf8")) as Record; + if (["TracingStartedInBrowser", "TracingStartedInPage", "CpuProfile"].includes(String(event.name))) { + hasInspectorMetadata = true; + } + if (event.name === traceMarker && typeof event.pid === "number" && typeof event.tid === "number" && typeof event.ts === "number" && Number.isFinite(event.pid) && Number.isFinite(event.tid) && Number.isFinite(event.ts)) { + return { pid: Number(event.pid), tid: Number(event.tid), ts: Number(event.ts) }; + } + } catch { /* A malformed event is rejected later by the full stream copier. */ } + return undefined; + }; + + for await (const value of createReadStream(spool)) { + let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); + if (!started) { + prefix = Buffer.concat([prefix, chunk]); + if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) break; + const text = prefix.toString("utf8"); + const first = text.search(/\S/); + let opening = first >= 0 && text[first] === "[" ? first : -1; + if (opening < 0) { + const marker = text.indexOf('"traceEvents"'); + if (marker >= 0) opening = text.indexOf("[", marker + 13); + } + if (opening < 0) continue; + chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), "utf8")); + prefix = Buffer.alloc(0); + started = true; + depth = 1; + } + + let eventStart = capturingEvent ? 0 : -1; + for (let index = 0; index < chunk.length; index += 1) { + const byte = chunk[index]; + if (inString) { + if (escaped) escaped = false; + else if (byte === 0x5c) escaped = true; + else if (byte === 0x22) inString = false; + } else if (byte === 0x22) inString = true; + else if (byte === 0x5b) depth += 1; + else if (byte === 0x5d) depth -= 1; + else if (byte === 0x7b) { + if (depth === 1 && objectDepth === 0) { + eventStart = index; + eventParts = []; + eventBytes = 0; + eventOverflow = false; + capturingEvent = true; + } + objectDepth += 1; + } else if (byte === 0x7d) { + objectDepth -= 1; + if (depth === 1 && objectDepth === 0 && eventStart >= 0) { + const part = chunk.subarray(eventStart, index + 1); + eventBytes += part.byteLength; + if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); + else eventOverflow = true; + const marker = inspectEvent(); + if (marker) return { hasInspectorMetadata, marker }; + eventStart = -1; + capturingEvent = false; + } + } + } + if (eventStart >= 0) { + const part = chunk.subarray(eventStart); + eventBytes += part.byteLength; + if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); + else eventOverflow = true; + } + } + return { hasInspectorMetadata }; +} + +function validScripts(value: CaptureScriptMetadata[]): CaptureScriptMetadata[] { + return value.slice(0, 50_000).filter((script) => script && typeof script.scriptId === "string" && typeof script.url === "string").map((script) => ({ + scriptId: cleanText(script.scriptId, 200), + url: cleanText(script.url, 4000), + ...(script.sourceMapURL ? { sourceMapURL: cleanText(script.sourceMapURL, 4000) } : {}), + ...(script.frameId ? { frameId: cleanText(script.frameId, 300) } : {}), + ...(script.sessionId ? { sessionId: cleanText(script.sessionId, 300) } : {}), + })); +} + +function validSourceMaps(value: CaptureSourceMap[]): CaptureSourceMap[] { + return value.slice(0, 5_000).filter((entry) => entry && typeof entry.url === "string" && typeof entry.sourceMapUrl === "string" && entry.sourceMap && typeof entry.sourceMap === "object" && !Array.isArray(entry.sourceMap)).map((entry) => ({ + url: cleanText(entry.url, 4000), + sourceMapUrl: cleanText(entry.sourceMapUrl, 4000), + sourceMap: entry.sourceMap, + })); +} + +async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMetadata[], sourceMaps: CaptureSourceMap[], mainFrame?: CaptureMainFrame, traceMarker?: string): Promise<{ export: { fileName: string; sizeBytes: number }; eventCount: number }> { + const stamp = new Date(record.createdAt).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z"); + const fileName = `Trace-${stamp}.json.gz`; + const destination = join(captureDir(record.id), fileName); + const temporary = `${destination}.${randomUUID()}.tmp`; + const output = createWriteStream(temporary, { flags: "wx", mode: 0o600 }); + const gzip = createGzip({ level: 6 }); + gzip.pipe(output); + const metadata = { + // DevTools' enhanced-trace schema is currently version 1. The source + // rundown events in traceEvents carry script content; these retained maps + // let an offline import resolve authored names without refetching assets. + enhancedTraceVersion: 1, + sourceMaps, + traceSift: { + captureId: record.id, + target: record.target, + createdAt: new Date(record.createdAt).toISOString(), + scripts, + }, + }; + const traceMetadata = traceMarker ? await inspectTraceMetadata(spoolPath(record.id), traceMarker) : { hasInspectorMetadata: false }; + const syntheticMetadata = !traceMetadata.hasInspectorMetadata && traceMetadata.marker && mainFrame ? { + name: "TracingStartedInBrowser", + cat: "disabled-by-default-devtools.timeline", + ph: "I", + s: "t", + pid: traceMetadata.marker.pid, + tid: traceMetadata.marker.tid, + ts: traceMetadata.marker.ts, + args: { data: { persistentIds: true, frames: [{ + frame: mainFrame.id, + url: mainFrame.url || record.target.url, + name: mainFrame.name, + processId: traceMetadata.marker.pid, + isOutermostMainFrame: true, + isInPrimaryMainFrame: true, + }] } }, + } : undefined; + try { + gzip.write(`{"metadata":${JSON.stringify(metadata)},"traceEvents":[`); + if (syntheticMetadata) gzip.write(`${JSON.stringify(syntheticMetadata)},`); + const eventCount = await copyTraceEvents(spoolPath(record.id), gzip); + gzip.end("]}"); + await finished(output); + await rename(temporary, destination); + const info = await stat(destination); + return { export: { fileName, sizeBytes: info.size }, eventCount: eventCount + (syntheticMetadata ? 1 : 0) }; + } finally { + await rm(temporary, { force: true }); + } +} + +export async function finalizeCapture(id: string, token: string, input: { + dataLoss?: boolean; + stopReason?: CaptureStopReason; + scripts?: CaptureScriptMetadata[]; + sourceMaps?: CaptureSourceMap[]; + warnings?: string[]; + mainFrame?: CaptureMainFrame; + traceMarker?: string; +}): Promise { + return mutate(async () => { + const record = await authorized(id, token); + if (record.export && TERMINAL_STATES.has(record.state)) return publicRecord(record); + record.state = "enriching"; + record.updatedAt = Date.now(); + await writeStored(record); + + const scripts = validScripts(Array.isArray(input.scripts) ? input.scripts : []); + const sourceMaps = validSourceMaps(Array.isArray(input.sourceMaps) ? input.sourceMaps : []); + await writeFile(scriptsPath(id), `${JSON.stringify(scripts)}\n`, { mode: 0o600 }); + record.scriptsSeen = scripts.length; + record.sourceMapsSeen = sourceMaps.length; + record.dataLoss = Boolean(input.dataLoss); + if (input.stopReason) record.stopReason = input.stopReason; + if (record.dataLoss) record.warnings.push("Chrome reported that trace data was lost before export completed."); + for (const warning of input.warnings ?? []) record.warnings.push(cleanText(String(warning), MAX_WARNING_LENGTH)); + const externalSourceMapsReported = scripts.some((script) => script.sourceMapURL && !script.sourceMapURL.startsWith("data:")); + if (externalSourceMapsReported && record.sourceMapsSeen === 0) record.warnings.push("Chrome reported external source maps, but none could be retained; generated function names may remain minified."); + if (!scripts.some((script) => script.sourceMapURL)) record.warnings.push("No source-map URLs were reported by Chrome; generated function names may remain minified."); + record.warnings = [...new Set(record.warnings)].slice(0, 100); + const mainFrame = input.mainFrame && typeof input.mainFrame.id === "string" ? { + id: cleanText(input.mainFrame.id, 300), + url: cleanText(input.mainFrame.url || record.target.url, 4000), + name: cleanText(input.mainFrame.name || "", 300), + } : undefined; + const traceMarker = input.traceMarker ? cleanText(input.traceMarker, 300) : undefined; + const completedExport = await writeGzipExport(record, scripts, sourceMaps, mainFrame, traceMarker); + record.export = completedExport.export; + record.eventCount = completedExport.eventCount; + record.state = record.warnings.length > 0 ? "captured_with_warnings" : "captured"; + record.stoppedAt = Date.now(); + record.updatedAt = record.stoppedAt; + await writeStored(record); + return publicRecord(record); + }); +} + +export async function failCapture(id: string, token: string, input: { error: string; reason?: CaptureStopReason; interrupted?: boolean }): Promise { + return mutate(async () => { + const record = await authorized(id, token); + if (TERMINAL_STATES.has(record.state)) return publicRecord(record); + record.state = input.interrupted ? "interrupted" : "failed"; + record.stopReason = input.reason ?? "error"; + record.error = cleanText(input.error || "Capture failed.", 2000); + record.stoppedAt = Date.now(); + record.updatedAt = record.stoppedAt; + await writeStored(record); + return publicRecord(record); + }); +} + +export async function deleteCapture(id: string): Promise { + return mutate(async () => { + const record = await readStored(id); + if (!record) return false; + if (ACTIVE_CAPTURE_STATES.has(record.state)) throw new Error("Stop the active capture before deleting it."); + await rm(captureDir(id), { recursive: true, force: true }); + return true; + }); +} + +export async function captureExport(id: string): Promise<{ path: string; fileName: string; sizeBytes: number } | undefined> { + const record = await readStored(id); + if (!record?.export) return undefined; + const fileName = basename(record.export.fileName); + const path = join(captureDir(id), fileName); + const info = await stat(path); + return { path, fileName, sizeBytes: info.size }; +} + +export function bearerToken(request: Request): string { + const authorization = request.headers.get("authorization") ?? ""; + return authorization.startsWith("Bearer ") ? authorization.slice(7) : ""; +} diff --git a/src/lib/capture-types.ts b/src/lib/capture-types.ts new file mode 100644 index 0000000..5928f39 --- /dev/null +++ b/src/lib/capture-types.ts @@ -0,0 +1,86 @@ +export const CAPTURE_STATES = [ + "pending", + "attaching", + "recording", + "stop_requested", + "flushing", + "enriching", + "captured", + "captured_with_warnings", + "failed", + "interrupted", +] as const; + +export type CaptureState = (typeof CAPTURE_STATES)[number]; + +export type CaptureStopReason = + | "manual" + | "buffer_limit" + | "target_closed" + | "detached" + | "shutdown" + | "error"; + +export interface CaptureTarget { + tabId: number; + title: string; + url: string; +} + +export interface CaptureRecord { + id: string; + createdAt: number; + updatedAt: number; + startedAt?: number; + stoppedAt?: number; + title: string; + target: CaptureTarget; + state: CaptureState; + stopReason?: CaptureStopReason; + bufferUsage: number; + eventCount: number; + chunkCount: number; + byteCount: number; + dataLoss: boolean; + scriptsSeen: number; + sourceMapsSeen: number; + warnings: string[]; + error?: string; + export?: { + fileName: string; + sizeBytes: number; + }; +} + +export interface CaptureScriptMetadata { + scriptId: string; + url: string; + sourceMapURL?: string; + frameId?: string; + sessionId?: string; +} + +export interface CaptureSourceMap { + url: string; + sourceMapUrl: string; + sourceMap: Record; +} + +export interface CaptureMainFrame { + id: string; + url: string; + name: string; +} + +export const ACTIVE_CAPTURE_STATES = new Set([ + "pending", + "attaching", + "recording", + "stop_requested", + "flushing", + "enriching", +]); + +export function isCaptureState(value: unknown): value is CaptureState { + return typeof value === "string" && (CAPTURE_STATES as readonly string[]).includes(value); +} diff --git a/tests/capture-store.test.mjs b/tests/capture-store.test.mjs new file mode 100644 index 0000000..a720597 --- /dev/null +++ b/tests/capture-store.test.mjs @@ -0,0 +1,98 @@ +import assert from "node:assert/strict"; +import { gunzip } from "node:zlib"; +import { promisify } from "node:util"; +import { mkdtemp, readFile, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import test from "node:test"; + +const unzip = promisify(gunzip); +const home = await mkdtemp(path.join(tmpdir(), "tracesift-captures-")); +process.env.TRACE_SIFT_HOME = home; +const store = await import("../src/lib/capture-store.ts"); +const { coerceCdpProfile } = await import("../src/lib/js-profile.ts"); + +const target = { tabId: 42, title: "Profile target", url: "https://example.test/workflow" }; + +test("raw Chrome stream chunks are authorized, ordered, durable, and exported as an enhanced trace", async () => { + const { capture, uploadToken } = await store.createCapture({ target }); + assert.equal(capture.state, "pending"); + assert.equal(capture.target.url, target.url); + assert.equal("uploadTokenHash" in capture, false); + + await assert.rejects( + store.appendCaptureRawChunk(capture.id, "wrong-token", 0, new Uint8Array()), + /authorization failed/, + ); + + await store.updateCaptureFromExtension(capture.id, uploadToken, { state: "recording", bufferUsage: 0.25 }); + const events = [ + { + name: "__tracesift_main_capture", cat: "blink.user_timing", ph: "R", + ts: 900, pid: 1, tid: 2, args: {}, + }, + { + name: "Profile", cat: "disabled-by-default-v8.cpu_profiler", id: "0x1", ph: "P", + ts: 1000, pid: 1, tid: 2, args: { data: { startTime: 1000 } }, + }, + { + name: "ProfileChunk", cat: "disabled-by-default-v8.cpu_profiler", id: "0x1", ph: "P", + ts: 1000, pid: 1, tid: 3, args: { data: { + timeDeltas: [100, 100], + cpuProfile: { + nodes: [ + { id: 1, callFrame: { functionName: "(root)", scriptId: "0", url: "", lineNumber: -1, columnNumber: -1 } }, + { id: 2, parent: 1, callFrame: { functionName: "runFlow", scriptId: "7", url: "https://example.test/app.js", lineNumber: 4, columnNumber: 2 } }, + ], + samples: [2, 2], + }, + } }, + }, + ]; + const rawTrace = Buffer.from(JSON.stringify({ traceEvents: events, metadata: { chrome: "preserved as events, not copied" } }), "utf8"); + const split = rawTrace.indexOf(Buffer.from('"ProfileChunk"')) + 5; + await store.appendCaptureRawChunk(capture.id, uploadToken, 0, rawTrace.subarray(0, split)); + await assert.rejects(store.appendCaptureRawChunk(capture.id, uploadToken, 0, new Uint8Array()), /Expected trace chunk 1/); + await store.appendCaptureRawChunk(capture.id, uploadToken, 1, rawTrace.subarray(split)); + + const completed = await store.finalizeCapture(capture.id, uploadToken, { + stopReason: "manual", + scripts: [{ scriptId: "7", url: "https://example.test/app.js", sourceMapURL: "https://example.test/app.js.map", frameId: "frame-1" }], + sourceMaps: [{ url: "https://example.test/app.js", sourceMapUrl: "https://example.test/app.js.map", sourceMap: { version: 3, sources: ["src/app.ts"], names: ["runFlow"], mappings: "AAAA" } }], + mainFrame: { id: "frame-1", url: target.url, name: "" }, + traceMarker: "__tracesift_main_capture", + }); + assert.equal(completed.state, "captured"); + assert.equal(completed.eventCount, 4); + assert.equal(completed.chunkCount, 2); + assert.equal(completed.sourceMapsSeen, 1); + assert.ok(completed.export?.fileName.endsWith(".json.gz")); + + const exported = await store.captureExport(capture.id); + const decoded = JSON.parse((await unzip(await readFile(exported.path))).toString("utf8")); + assert.equal(decoded.metadata.traceSift.captureId, capture.id); + assert.equal(Object.keys(decoded.metadata)[0], "enhancedTraceVersion"); + assert.equal(decoded.metadata.enhancedTraceVersion, 1); + assert.deepEqual(Object.keys(decoded.metadata.sourceMaps[0]), ["url", "sourceMapUrl", "sourceMap"]); + assert.equal(decoded.metadata.sourceMaps[0].sourceMap.names[0], "runFlow"); + assert.equal(decoded.metadata.traceSift.scripts[0].frameId, "frame-1"); + assert.equal(decoded.traceEvents.length, 4); + assert.equal(decoded.traceEvents[0].name, "TracingStartedInBrowser"); + assert.equal(decoded.traceEvents[0].args.data.frames[0].processId, 1); + assert.equal(decoded.traceEvents[0].args.data.frames[0].url, target.url); + assert.equal(coerceCdpProfile(decoded).nodes.find((node) => node.id === 2)?.callFrame.functionName, "runFlow"); + + assert.equal((await store.listCaptures())[0].id, capture.id); + assert.equal(await store.deleteCapture(capture.id), true); + assert.equal(await store.getCapture(capture.id), undefined); +}); + +test("only one active capture can exist", async () => { + const first = await store.createCapture({ target }); + await assert.rejects(store.createCapture({ target: { ...target, tabId: 43 } }), /already active/); + await store.failCapture(first.capture.id, first.uploadToken, { error: "test cleanup", interrupted: true }); + const second = await store.createCapture({ target: { ...target, tabId: 43 } }); + await store.failCapture(second.capture.id, second.uploadToken, { error: "test cleanup", interrupted: true }); +}); + +test.after(async () => { await rm(home, { recursive: true, force: true }); }); diff --git a/tests/chrome-extension.test.mjs b/tests/chrome-extension.test.mjs new file mode 100644 index 0000000..d643996 --- /dev/null +++ b/tests/chrome-extension.test.mjs @@ -0,0 +1,41 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import test from "node:test"; + +const background = await readFile(new URL("../packages/chrome-extension/background.js", import.meta.url), "utf8"); +const manifest = JSON.parse(await readFile(new URL("../packages/chrome-extension/manifest.json", import.meta.url), "utf8")); + +test("capture extension requires a toolbar gesture on the exact capture page", () => { + assert.equal(manifest.manifest_version, 3); + assert.equal(manifest.minimum_chrome_version, "125"); + assert.ok(manifest.permissions.includes("debugger")); + assert.match(background, /chrome\.action\.onClicked\.addListener/); + assert.match(background, /url\.pathname !== "\/capture"/); + assert.match(background, /sender\.tab\?\.id !== pairing\.bridgeTabId/); + assert.doesNotMatch(background, /message\.type === "PAIR"/); + assert.doesNotMatch(background, /api\/captures\/pairing/); +}); + +test("capture extension pulls a bounded CDP stream instead of queueing event batches", () => { + assert.match(background, /transferMode: "ReturnAsStream"/); + assert.match(background, /"IO\.read"/); + assert.match(background, /MAX_UPLOAD_BYTES = 192 \* 1024/); + assert.doesNotMatch(background, /method === "Tracing\.dataCollected"/); +}); + +test("capture extension enables renderer metadata before tracing", () => { + const pageEnable = background.indexOf('sendCommand(source, "Page.enable")'); + const tracingStart = background.indexOf('sendCommand(debuggee, "Tracing.start"'); + assert.ok(pageEnable >= 0); + assert.ok(tracingStart > pageEnable); + assert.match(background, /TracingStartedInPage/); + assert.match(background, /"Page\.getFrameTree"/); + assert.match(background, /performance\.mark/); + assert.match(background, /traceMarker: capture\.traceMarker/); +}); + +test("source-map loading retains frame identity for frame targets", () => { + assert.match(background, /params\.executionContextAuxData\?\.frameId/); + assert.match(background, /\.\.\.\(script\.frameId \? \{ frameId: script\.frameId \} : \{\}\)/); + assert.match(background, /script\.url \|\| undefined/); +}); From 90b644e029777d80c4d465ca9bdd9aeddb7a8ace Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Fri, 23 Oct 2026 16:55:05 +0500 Subject: [PATCH 02/10] fix: sourcemaps --- packages/chrome-extension/background.js | 103 ++++++++++++++++-------- tests/chrome-extension.test.mjs | 23 ++++++ 2 files changed, 94 insertions(+), 32 deletions(-) diff --git a/packages/chrome-extension/background.js b/packages/chrome-extension/background.js index 3b06dc7..5f86f7c 100644 --- a/packages/chrome-extension/background.js +++ b/packages/chrome-extension/background.js @@ -127,6 +127,11 @@ async function startCapture(message) { baseUrl, sequence: 0, scripts: new Map(), + sourceMapEntries: new Map(), + sourceMapQueue: Promise.resolve(), + sourceMapBytes: 0, + sourceMapWarnings: [], + sourceMapLimitReached: false, stopping: false, stopReason: "manual", pollTimer: null, @@ -245,9 +250,15 @@ async function readProtocolStream(source, handle) { } } -async function loadSourceMap(capture, script) { +function sourceMapLoadFailure(resource, sourceMapUrl) { + const details = []; + if (Number.isInteger(resource?.httpStatusCode)) details.push(`HTTP ${resource.httpStatusCode}`); + if (resource?.netErrorName) details.push(resource.netErrorName); + return new Error(details.length > 0 ? `${sourceMapUrl} returned ${details.join("; ")}` : `Could not load ${sourceMapUrl}`); +} + +async function loadSourceMap(capture, script, sourceMapUrl = resolveSourceMapUrl(script)) { if (!script.url || !script.sourceMapURL || script.url.startsWith("chrome-extension:")) return null; - const sourceMapUrl = resolveSourceMapUrl(script); let raw; if (sourceMapUrl.startsWith("data:")) { raw = decodeDataUrl(sourceMapUrl); @@ -258,7 +269,7 @@ async function loadSourceMap(capture, script) { url: sourceMapUrl, options: { disableCache: false, includeCredentials: true }, }); - if (!result.resource?.success || !result.resource.stream) throw new Error(result.resource?.netErrorName || `Could not load ${sourceMapUrl}`); + if (!result.resource?.success || !result.resource.stream) throw sourceMapLoadFailure(result.resource, sourceMapUrl); raw = await readProtocolStream(source, result.resource.stream); } if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error("Source map exceeds the 8 MB retention limit."); @@ -267,36 +278,62 @@ async function loadSourceMap(capture, script) { return { url: script.url, sourceMapUrl, sourceMap, bytes: raw.length }; } +async function tryRetainSourceMap(capture, entry) { + if (entry.retained || capture.sourceMapLimitReached) return; + entry.attempts += 1; + try { + const loaded = await loadSourceMap(capture, entry.script, entry.sourceMapUrl); + if (!loaded) return; + if (capture.sourceMapBytes + loaded.bytes > MAX_ALL_SOURCE_MAP_BYTES) { + capture.sourceMapLimitReached = true; + capture.sourceMapWarnings.push("Stopped retaining source maps after the 16 MB safety limit."); + return; + } + capture.sourceMapBytes += loaded.bytes; + entry.retained = { url: loaded.url, sourceMapUrl: loaded.sourceMapUrl, sourceMap: loaded.sourceMap }; + entry.error = null; + } catch (error) { + entry.error = errorText(error); + } +} + +function queueSourceMap(capture, script) { + if (!script.url || !script.sourceMapURL || script.url.startsWith("chrome-extension:")) return; + let sourceMapUrl; + try { sourceMapUrl = resolveSourceMapUrl(script); } + catch { + capture.sourceMapWarnings.push(`Ignored an invalid source-map URL for ${script.url || "an anonymous script"}.`); + return; + } + // DevTools does not duplicate data-URL maps in metadata: source-rundown + // events already carry their contents in the trace. + if (sourceMapUrl.startsWith("data:")) return; + const key = `${script.url}\n${sourceMapUrl}`; + if (capture.sourceMapEntries.has(key)) return; + const entry = { script, sourceMapUrl, attempts: 0, retained: null, error: null }; + capture.sourceMapEntries.set(key, entry); + // Serialize reads so eager retention cannot temporarily hold an unbounded + // number of large maps while still enforcing the aggregate byte limit. + capture.sourceMapQueue = capture.sourceMapQueue.then(() => tryRetainSourceMap(capture, entry)); +} + async function collectSourceMaps(capture) { - const retained = []; - const warnings = []; - const seen = new Set(); - let bytes = 0; - for (const script of capture.scripts.values()) { - if (!script.sourceMapURL) continue; - let resolved; - try { resolved = resolveSourceMapUrl(script); } - catch { warnings.push(`Ignored an invalid source-map URL for ${script.url || "an anonymous script"}.`); continue; } - // DevTools does not duplicate data-URL maps in metadata: source-rundown - // events already carry their contents in the trace. - if (resolved.startsWith("data:")) continue; - const key = `${script.url}\n${resolved}`; - if (seen.has(key)) continue; - seen.add(key); - try { - const loaded = await loadSourceMap(capture, script); - if (!loaded) continue; - if (bytes + loaded.bytes > MAX_ALL_SOURCE_MAP_BYTES) { - warnings.push("Stopped retaining source maps after the 16 MB safety limit."); - break; - } - bytes += loaded.bytes; - retained.push({ url: loaded.url, sourceMapUrl: loaded.sourceMapUrl, sourceMap: loaded.sourceMap }); - } catch (error) { - warnings.push(`Could not retain the source map for ${script.url || "an anonymous script"}: ${errorText(error)}`); + await capture.sourceMapQueue; + // A development server can still be compiling when scriptParsed arrives. + // Retry eager failures once at finalization, matching DevTools' fallback. + for (const entry of capture.sourceMapEntries.values()) { + if (!entry.retained && entry.error && !capture.sourceMapLimitReached) await tryRetainSourceMap(capture, entry); + } + const warnings = [...capture.sourceMapWarnings]; + for (const entry of capture.sourceMapEntries.values()) { + if (!entry.retained && entry.error) { + warnings.push(`Could not retain source map ${entry.sourceMapUrl} for ${entry.script.url || "an anonymous script"}: ${entry.error}`); } } - return { retained, warnings }; + return { + retained: [...capture.sourceMapEntries.values()].flatMap((entry) => entry.retained ? [entry.retained] : []), + warnings: [...new Set(warnings)], + }; } async function finalize(params) { @@ -350,13 +387,15 @@ chrome.debugger.onEvent.addListener((source, method, params = {}) => { } if (method === "Debugger.scriptParsed" && typeof params.scriptId === "string") { if (capture.scripts.size >= 50_000) return; - capture.scripts.set(scriptKey(source, params), { + const script = { scriptId: params.scriptId, url: params.url || "", ...(params.sourceMapURL ? { sourceMapURL: params.sourceMapURL } : {}), ...(typeof params.executionContextAuxData?.frameId === "string" ? { frameId: params.executionContextAuxData.frameId } : {}), ...(source.sessionId ? { sessionId: source.sessionId } : {}), - }); + }; + capture.scripts.set(scriptKey(source, params), script); + queueSourceMap(capture, script); return; } if (method === "Tracing.bufferUsage") { diff --git a/tests/chrome-extension.test.mjs b/tests/chrome-extension.test.mjs index d643996..ed2c319 100644 --- a/tests/chrome-extension.test.mjs +++ b/tests/chrome-extension.test.mjs @@ -39,3 +39,26 @@ test("source-map loading retains frame identity for frame targets", () => { assert.match(background, /\.\.\.\(script\.frameId \? \{ frameId: script\.frameId \} : \{\}\)/); assert.match(background, /script\.url \|\| undefined/); }); + +test("source maps are queued eagerly as scripts are parsed and awaited before export", () => { + const scriptParsed = background.indexOf('method === "Debugger.scriptParsed"'); + const eagerQueue = background.indexOf("queueSourceMap(capture, script)", scriptParsed); + const tracingComplete = background.indexOf('method === "Tracing.tracingComplete"'); + assert.ok(scriptParsed >= 0); + assert.ok(eagerQueue > scriptParsed && eagerQueue < tracingComplete); + assert.match(background, /capture\.sourceMapQueue = capture\.sourceMapQueue\.then\(\(\) => tryRetainSourceMap\(capture, entry\)\)/); + assert.match(background, /async function collectSourceMaps\(capture\) \{\s+await capture\.sourceMapQueue;/); +}); + +test("source-map retention deduplicates, bounds memory, and retries eager failures", () => { + assert.match(background, /capture\.sourceMapEntries\.has\(key\)/); + assert.match(background, /capture\.sourceMapBytes \+ loaded\.bytes > MAX_ALL_SOURCE_MAP_BYTES/); + assert.match(background, /!entry\.retained && entry\.error && !capture\.sourceMapLimitReached/); + assert.match(background, /await tryRetainSourceMap\(capture, entry\)/); +}); + +test("source-map failures identify the map URL, HTTP status, and network error", () => { + assert.match(background, /resource\?\.httpStatusCode/); + assert.match(background, /resource\?\.netErrorName/); + assert.match(background, /Could not retain source map \$\{entry\.sourceMapUrl\} for/); +}); From 0d8b4b5c268cb7d39ceaf811ae8660c37de65243 Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Mon, 2 Nov 2026 14:55:09 +0500 Subject: [PATCH 03/10] fix: empty cards --- packages/explore/src/lib/frame-classes.ts | 38 ++++++++++++++++-- packages/explore/src/lib/tasks.ts | 48 +++++++++++++++++++---- src/lib/frame-classes.ts | 38 ++++++++++++++++-- src/lib/tasks.ts | 48 +++++++++++++++++++---- tests/frame-classes.test.mjs | 20 ++++++++++ tests/tasks.test.mjs | 23 +++++++++++ 6 files changed, 193 insertions(+), 22 deletions(-) diff --git a/packages/explore/src/lib/frame-classes.ts b/packages/explore/src/lib/frame-classes.ts index 786d0c2..5cdc821 100644 --- a/packages/explore/src/lib/frame-classes.ts +++ b/packages/explore/src/lib/frame-classes.ts @@ -65,7 +65,37 @@ function isVendorChunkUrl(url: string): boolean { const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#]|$)/i; /** Schemes that name no file on disk: engine internals, extensions, eval'd code. */ -const VIRTUAL_SCHEME = /^(?:node|extensions|chrome-extension|chrome|webpack-internal|v8|evalmachine|blob|data):/i; +const VIRTUAL_SCHEME = /^(?:node|extensions|chrome|chrome-extension|v8|evalmachine|blob|data):/i; + +/** + * webpack's own schemes are wrapping, not a statement that the module has no + * file: `webpack-internal:///./node_modules/react-dom/cjs/react-dom-client.development.js` + * carries the path webpack compiled, and a dev server hands every single frame + * one. Filing those with the engine collapsed a whole recording to `native` — + * no frame reached the `node_modules` or readable-path rules, so nothing was + * ever the developer's own code, no card found a boundary, and the collapse + * that hides React's internals had nothing left to recognise. + * + * Both spellings appear: `webpack-internal:///(layer)/./src/app.ts` from a + * build with layers, `webpack://namespace/./src/app.ts` from a source map. + */ +const WEBPACK_SCHEME = /^webpack(?:-internal)?:\/\/\/?/i; + +/** The path behind a webpack scheme, or the URL untouched when there is none. */ +function unwrapBundlerUrl(url: string): string { + if (!WEBPACK_SCHEME.test(url)) return url; + // After the scheme comes an optional build layer in parentheses, then either + // a module path or the namespace the source map was written under. + let rest = url.replace(WEBPACK_SCHEME, "").replace(/^\([^)]*\)\//, ""); + if (!rest.startsWith("./") && !rest.startsWith("../") && !rest.startsWith("/")) { + const slash = rest.indexOf("/"); + // A namespace is a bare word; a first segment holding a dot is already a + // file or a directory webpack recorded, so it stays. + if (slash > 0 && !rest.slice(0, slash).includes(".")) rest = rest.slice(slash + 1); + } + // `./` is webpack's marker for the project root, not part of the path. + return rest.replace(/^\.\//, ""); +} /** * V8 and Hermes label built-ins `native array.js`. The leading word is the @@ -85,12 +115,14 @@ export function frameClassKey(frame: CdpCallFrame): string { * case no rule can settle. */ export function classifyByRule(frame: CdpCallFrame, codeSplit = false): FrameClass | undefined { - const { functionName: name, url } = frame; + const { functionName: name } = frame; + const url = unwrapBundlerUrl(frame.url); + const resolved = url === frame.url ? frame : { ...frame, url }; if (TRANSPARENT_NAMES.has(name)) return "native"; if (NATIVE_URL.test(url)) return "native"; if (ANONYMOUS_NAMES.has(name) && !url) return "anonymous"; if (VIRTUAL_SCHEME.test(url)) return "native"; - if (isFrameworkInternalFrame(frame)) return "framework"; + if (isFrameworkInternalFrame(resolved)) return "framework"; if (DEPENDENCY_URL.test(url) || isVendorChunkUrl(url)) return "library"; if (ANONYMOUS_NAMES.has(name)) return "anonymous"; // No URL means the engine, with one exception: the call wrappers V8 parks at diff --git a/packages/explore/src/lib/tasks.ts b/packages/explore/src/lib/tasks.ts index a6b18f6..d52d83c 100644 --- a/packages/explore/src/lib/tasks.ts +++ b/packages/explore/src/lib/tasks.ts @@ -163,20 +163,52 @@ export function measuredTasks(profile: CdpProfile): RawTaskInterval[] | undefine */ const PROFILER_OVERHEAD_EVENTS = new Set(["CpuProfiler::StartProfiling", "CpuProfiler::StopProfiling"]); +/** + * The mark the extension writes into the page the moment `Tracing.start` + * returns. Chrome emits no `CpuProfiler::StartProfiling` for a trace a + * `chrome.debugger` client started, so on a browser capture the span above is + * invisible and the attach lands in the recording as a first block holding + * nothing but `(program)` — 518 ms of it on the local capture, carded as "no + * code of your own ran in this block" because that is literally true. + * + * Everything between the profiler's own start and that mark is the cost of + * attaching the debugger and starting the recording. Reading it off the mark + * keeps this the same kind of claim as the event above — something the tracer + * stated — rather than a `(program)`-heavy call tree we decided to distrust. + */ +const CAPTURE_MARKER_PREFIX = "__tracesift_main_"; + /** Profiler-overhead intervals, grouped by the thread that paid for them. */ export function profilerOverheadIntervals( events: readonly Record[], ): Map { const byThread = new Map(); - for (const event of events) { - if (typeof event.name !== "string" || !PROFILER_OVERHEAD_EVENTS.has(event.name)) continue; - if (typeof event.ts !== "number") continue; - const dur = typeof event.dur === "number" ? event.dur : 0; - if (dur <= 0) continue; - const key = threadKey(event); + const add = (key: string, interval: RawTaskInterval) => { const list = byThread.get(key); - if (list) list.push({ ts: event.ts, dur }); - else byThread.set(key, [{ ts: event.ts, dur }]); + if (list) list.push(interval); + else byThread.set(key, [interval]); + }; + // `Profile` is emitted on the thread being profiled, and so is the mark, so + // the two meet under one key. First of each wins: a capture starts once. + const profileStart = new Map(); + const captureMark = new Map(); + for (const event of events) { + if (typeof event.name !== "string" || typeof event.ts !== "number") continue; + if (PROFILER_OVERHEAD_EVENTS.has(event.name)) { + const dur = typeof event.dur === "number" ? event.dur : 0; + if (dur > 0) add(threadKey(event), { ts: event.ts, dur }); + } else if (event.name === "Profile") { + const key = threadKey(event); + if (!profileStart.has(key)) profileStart.set(key, event.ts); + } else if (event.name.startsWith(CAPTURE_MARKER_PREFIX)) { + const key = threadKey(event); + if (!captureMark.has(key)) captureMark.set(key, event.ts); + } + } + for (const [key, mark] of captureMark) { + const start = profileStart.get(key); + if (start === undefined || mark <= start) continue; + add(key, { ts: start, dur: mark - start }); } return byThread; } diff --git a/src/lib/frame-classes.ts b/src/lib/frame-classes.ts index 0ecc5ad..0e5f95c 100644 --- a/src/lib/frame-classes.ts +++ b/src/lib/frame-classes.ts @@ -65,7 +65,37 @@ function isVendorChunkUrl(url: string): boolean { const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#]|$)/i; /** Schemes that name no file on disk: engine internals, extensions, eval'd code. */ -const VIRTUAL_SCHEME = /^(?:node|extensions|chrome-extension|chrome|webpack-internal|v8|evalmachine|blob|data):/i; +const VIRTUAL_SCHEME = /^(?:node|extensions|chrome|chrome-extension|v8|evalmachine|blob|data):/i; + +/** + * webpack's own schemes are wrapping, not a statement that the module has no + * file: `webpack-internal:///./node_modules/react-dom/cjs/react-dom-client.development.js` + * carries the path webpack compiled, and a dev server hands every single frame + * one. Filing those with the engine collapsed a whole recording to `native` — + * no frame reached the `node_modules` or readable-path rules, so nothing was + * ever the developer's own code, no card found a boundary, and the collapse + * that hides React's internals had nothing left to recognise. + * + * Both spellings appear: `webpack-internal:///(layer)/./src/app.ts` from a + * build with layers, `webpack://namespace/./src/app.ts` from a source map. + */ +const WEBPACK_SCHEME = /^webpack(?:-internal)?:\/\/\/?/i; + +/** The path behind a webpack scheme, or the URL untouched when there is none. */ +function unwrapBundlerUrl(url: string): string { + if (!WEBPACK_SCHEME.test(url)) return url; + // After the scheme comes an optional build layer in parentheses, then either + // a module path or the namespace the source map was written under. + let rest = url.replace(WEBPACK_SCHEME, "").replace(/^\([^)]*\)\//, ""); + if (!rest.startsWith("./") && !rest.startsWith("../") && !rest.startsWith("/")) { + const slash = rest.indexOf("/"); + // A namespace is a bare word; a first segment holding a dot is already a + // file or a directory webpack recorded, so it stays. + if (slash > 0 && !rest.slice(0, slash).includes(".")) rest = rest.slice(slash + 1); + } + // `./` is webpack's marker for the project root, not part of the path. + return rest.replace(/^\.\//, ""); +} /** * V8 and Hermes label built-ins `native array.js`. The leading word is the @@ -85,12 +115,14 @@ export function frameClassKey(frame: CdpCallFrame): string { * case no rule can settle. */ export function classifyByRule(frame: CdpCallFrame, codeSplit = false): FrameClass | undefined { - const { functionName: name, url } = frame; + const { functionName: name } = frame; + const url = unwrapBundlerUrl(frame.url); + const resolved = url === frame.url ? frame : { ...frame, url }; if (TRANSPARENT_NAMES.has(name)) return "native"; if (NATIVE_URL.test(url)) return "native"; if (ANONYMOUS_NAMES.has(name) && !url) return "anonymous"; if (VIRTUAL_SCHEME.test(url)) return "native"; - if (isFrameworkInternalFrame(frame)) return "framework"; + if (isFrameworkInternalFrame(resolved)) return "framework"; if (DEPENDENCY_URL.test(url) || isVendorChunkUrl(url)) return "library"; if (ANONYMOUS_NAMES.has(name)) return "anonymous"; // No URL means the engine, with one exception: the call wrappers V8 parks at diff --git a/src/lib/tasks.ts b/src/lib/tasks.ts index 515d620..43b6785 100644 --- a/src/lib/tasks.ts +++ b/src/lib/tasks.ts @@ -163,20 +163,52 @@ export function measuredTasks(profile: CdpProfile): RawTaskInterval[] | undefine */ const PROFILER_OVERHEAD_EVENTS = new Set(["CpuProfiler::StartProfiling", "CpuProfiler::StopProfiling"]); +/** + * The mark the extension writes into the page the moment `Tracing.start` + * returns. Chrome emits no `CpuProfiler::StartProfiling` for a trace a + * `chrome.debugger` client started, so on a browser capture the span above is + * invisible and the attach lands in the recording as a first block holding + * nothing but `(program)` — 518 ms of it on the local capture, carded as "no + * code of your own ran in this block" because that is literally true. + * + * Everything between the profiler's own start and that mark is the cost of + * attaching the debugger and starting the recording. Reading it off the mark + * keeps this the same kind of claim as the event above — something the tracer + * stated — rather than a `(program)`-heavy call tree we decided to distrust. + */ +const CAPTURE_MARKER_PREFIX = "__tracesift_main_"; + /** Profiler-overhead intervals, grouped by the thread that paid for them. */ export function profilerOverheadIntervals( events: readonly Record[], ): Map { const byThread = new Map(); - for (const event of events) { - if (typeof event.name !== "string" || !PROFILER_OVERHEAD_EVENTS.has(event.name)) continue; - if (typeof event.ts !== "number") continue; - const dur = typeof event.dur === "number" ? event.dur : 0; - if (dur <= 0) continue; - const key = threadKey(event); + const add = (key: string, interval: RawTaskInterval) => { const list = byThread.get(key); - if (list) list.push({ ts: event.ts, dur }); - else byThread.set(key, [{ ts: event.ts, dur }]); + if (list) list.push(interval); + else byThread.set(key, [interval]); + }; + // `Profile` is emitted on the thread being profiled, and so is the mark, so + // the two meet under one key. First of each wins: a capture starts once. + const profileStart = new Map(); + const captureMark = new Map(); + for (const event of events) { + if (typeof event.name !== "string" || typeof event.ts !== "number") continue; + if (PROFILER_OVERHEAD_EVENTS.has(event.name)) { + const dur = typeof event.dur === "number" ? event.dur : 0; + if (dur > 0) add(threadKey(event), { ts: event.ts, dur }); + } else if (event.name === "Profile") { + const key = threadKey(event); + if (!profileStart.has(key)) profileStart.set(key, event.ts); + } else if (event.name.startsWith(CAPTURE_MARKER_PREFIX)) { + const key = threadKey(event); + if (!captureMark.has(key)) captureMark.set(key, event.ts); + } + } + for (const [key, mark] of captureMark) { + const start = profileStart.get(key); + if (start === undefined || mark <= start) continue; + add(key, { ts: start, dur: mark - start }); } return byThread; } diff --git a/tests/frame-classes.test.mjs b/tests/frame-classes.test.mjs index fab26b0..74363c7 100644 --- a/tests/frame-classes.test.mjs +++ b/tests/frame-classes.test.mjs @@ -88,3 +88,23 @@ test('no model runs for a classification, whatever is configured', async () => { const source = await import('node:fs/promises').then((fs) => fs.readFile('src/lib/frame-classes.ts', 'utf8')); assert.ok(!source.includes('pi-agent'), 'frame classification must not import the agent runner'); }); + +test('a webpack scheme is unwrapped, not filed with the engine', () => { + // A webpack dev server hands every frame a `webpack-internal:` URL. Reading + // the scheme as "no file on disk" collapsed a whole recording to `native`: + // no frame was ever the developer's own, so no card found a boundary and the + // collapse that hides React had nothing left to recognise. + assert.equal(classifyByRule(frame('blockMainThread', 'webpack-internal:///./src/app/index.web.ts')), 'app'); + assert.equal( + classifyByRule(frame('logComponentRender', 'webpack-internal:///./node_modules/react-dom/cjs/react-dom-client.development.js')), + 'framework', + ); + assert.equal(classifyByRule(frame('map', 'webpack-internal:///./node_modules/lodash/map.js')), 'library'); + // A build layer sits between the scheme and the path, and a source map writes + // the same path under a namespace instead. + assert.equal(classifyByRule(frame('Page', 'webpack-internal:///(app-pages-browser)/./src/app/page.tsx')), 'app'); + assert.equal(classifyByRule(frame('getUsers', 'webpack://_N_E/./src/api/users.ts')), 'app'); + // The other virtual schemes still name no file. + assert.equal(classifyByRule(frame('handler', 'chrome-extension://abc/background.js')), 'native'); + assert.equal(classifyByRule(frame('run', 'blob:http://localhost:3000/abc')), 'native'); +}); diff --git a/tests/tasks.test.mjs b/tests/tasks.test.mjs index 3ca8438..77da56c 100644 --- a/tests/tasks.test.mjs +++ b/tests/tasks.test.mjs @@ -276,3 +276,26 @@ test('a trace that never names the profiler leaves every task alone', () => { const raw = attachMeasuredTasks(profile(nodes, [1, 2, 3], 1000), [{ ts: 2000, dur: 3000 }]); assert.deepEqual(extractTasks(raw).tasks.map((task) => task.overhead), [undefined]); }); + +test("a browser capture's attach window is read off TraceSift's own mark", () => { + // Chrome emits no `CpuProfiler::StartProfiling` for a trace started through + // `chrome.debugger`, so the attach arrives as a first block of `(program)` + // with no JS frame in it. The mark the extension writes once `Tracing.start` + // returns is the only statement of when the recording really began. + const byThread = profilerOverheadIntervals([ + { name: 'Profile', ph: 'P', ts: 1000, pid: 1, tid: 1 }, + { name: '__tracesift_main_734ab274-fb87-481f-ba3b-d5f813fee252', ph: 'I', ts: 6000, pid: 1, tid: 1 }, + // A second thread profiled without a mark keeps its whole recording. + { name: 'Profile', ph: 'P', ts: 1000, pid: 1, tid: 2 }, + ]); + assert.deepEqual(byThread.get('1:1'), [{ ts: 1000, dur: 5000 }]); + assert.equal(byThread.get('1:2'), undefined); +}); + +test('a mark that precedes the profiler bills nothing', () => { + const byThread = profilerOverheadIntervals([ + { name: '__tracesift_main_abc', ph: 'I', ts: 500, pid: 1, tid: 1 }, + { name: 'Profile', ph: 'P', ts: 1000, pid: 1, tid: 1 }, + ]); + assert.equal(byThread.get('1:1'), undefined); +}); From 32c0b703dc39c97e7cff48068d21be7c9795a07f Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Mon, 2 Nov 2026 15:05:47 +0500 Subject: [PATCH 04/10] fix: soften warning for sourcemap --- packages/chrome-extension/background.js | 21 +++++++++++++++++- src/lib/capture-store.ts | 20 ++++++++++++++++- tests/capture-store.test.mjs | 29 +++++++++++++++++++++++++ tests/chrome-extension.test.mjs | 2 ++ 4 files changed, 70 insertions(+), 2 deletions(-) diff --git a/packages/chrome-extension/background.js b/packages/chrome-extension/background.js index 5f86f7c..5490ac0 100644 --- a/packages/chrome-extension/background.js +++ b/packages/chrome-extension/background.js @@ -231,6 +231,22 @@ function decodeDataUrl(url) { return header.includes(";base64") ? atob(payload) : decodeURIComponent(payload); } +function sourceMapBasename(value) { + const clean = (value || "").split(/[?#]/)[0]; + return clean.slice(clean.lastIndexOf("/") + 1); +} + +// A bundled module's own `//# sourceMappingURL` comment can survive +// concatenation, and Chrome reports the last comment it finds in a script. Such +// a name points at a file the bundler never emitted, so failing to load it says +// nothing about whether the bundle itself has a retrievable map. +function sourceMapBelongsToScript(scriptUrl, sourceMapUrl) { + const script = sourceMapBasename(scriptUrl); + const map = sourceMapBasename(sourceMapUrl).replace(/\.map$/, ""); + if (!script || !map) return true; + return script.startsWith(map) || map.startsWith(script); +} + function resolveSourceMapUrl(script) { return new URL(script.sourceMapURL, script.url || undefined).href; } @@ -327,7 +343,10 @@ async function collectSourceMaps(capture) { const warnings = [...capture.sourceMapWarnings]; for (const entry of capture.sourceMapEntries.values()) { if (!entry.retained && entry.error) { - warnings.push(`Could not retain source map ${entry.sourceMapUrl} for ${entry.script.url || "an anonymous script"}: ${entry.error}`); + const script = entry.script.url || "an anonymous script"; + warnings.push(sourceMapBelongsToScript(entry.script.url, entry.sourceMapUrl) + ? `Could not retain source map ${entry.sourceMapUrl} for ${script}: ${entry.error}` + : `Ignored ${entry.sourceMapUrl}, a stale source-map comment a bundled module left inside ${script}: ${entry.error}`); } } return { diff --git a/src/lib/capture-store.ts b/src/lib/capture-store.ts index 6fafd49..6c50862 100644 --- a/src/lib/capture-store.ts +++ b/src/lib/capture-store.ts @@ -425,6 +425,24 @@ async function inspectTraceMetadata(spool: string, traceMarker: string): Promise return { hasInspectorMetadata }; } +function sourceMapBasename(value: string): string { + const clean = value.split(/[?#]/)[0]; + return clean.slice(clean.lastIndexOf("/") + 1); +} + +/** + * A bundled module's own `//# sourceMappingURL` comment can survive + * concatenation, and Chrome reports the last comment it finds in a script. A + * name that cannot belong to the script points at a file the bundler never + * emitted, so it is no evidence that this script has a retrievable map. + */ +function sourceMapBelongsToScript(scriptUrl: string, sourceMapURL: string): boolean { + const script = sourceMapBasename(scriptUrl); + const map = sourceMapBasename(sourceMapURL).replace(/\.map$/, ""); + if (!script || !map) return true; + return script.startsWith(map) || map.startsWith(script); +} + function validScripts(value: CaptureScriptMetadata[]): CaptureScriptMetadata[] { return value.slice(0, 50_000).filter((script) => script && typeof script.scriptId === "string" && typeof script.url === "string").map((script) => ({ scriptId: cleanText(script.scriptId, 200), @@ -521,7 +539,7 @@ export async function finalizeCapture(id: string, token: string, input: { if (input.stopReason) record.stopReason = input.stopReason; if (record.dataLoss) record.warnings.push("Chrome reported that trace data was lost before export completed."); for (const warning of input.warnings ?? []) record.warnings.push(cleanText(String(warning), MAX_WARNING_LENGTH)); - const externalSourceMapsReported = scripts.some((script) => script.sourceMapURL && !script.sourceMapURL.startsWith("data:")); + const externalSourceMapsReported = scripts.some((script) => script.sourceMapURL && !script.sourceMapURL.startsWith("data:") && sourceMapBelongsToScript(script.url, script.sourceMapURL)); if (externalSourceMapsReported && record.sourceMapsSeen === 0) record.warnings.push("Chrome reported external source maps, but none could be retained; generated function names may remain minified."); if (!scripts.some((script) => script.sourceMapURL)) record.warnings.push("No source-map URLs were reported by Chrome; generated function names may remain minified."); record.warnings = [...new Set(record.warnings)].slice(0, 100); diff --git a/tests/capture-store.test.mjs b/tests/capture-store.test.mjs index a720597..c0ef529 100644 --- a/tests/capture-store.test.mjs +++ b/tests/capture-store.test.mjs @@ -87,6 +87,35 @@ test("raw Chrome stream chunks are authorized, ordered, durable, and exported as assert.equal(await store.getCapture(capture.id), undefined); }); +test("a stale source-map comment from a bundled module does not warn about minified names", async () => { + const { capture, uploadToken } = await store.createCapture({ target }); + await store.appendCaptureRawChunk(capture.id, uploadToken, 0, Buffer.from(JSON.stringify({ traceEvents: [] }), "utf8")); + const completed = await store.finalizeCapture(capture.id, uploadToken, { + stopReason: "manual", + // Metro concatenates a dependency that still carries its own comment, and + // Chrome reports that name for the whole bundle. + scripts: [{ scriptId: "9", url: "https://dev.test:8082/vendors.bundle.js", sourceMapURL: "Size.js.map" }], + sourceMaps: [], + }); + assert.equal(completed.sourceMapsSeen, 0); + assert.deepEqual(completed.warnings, []); + assert.equal(completed.state, "captured"); + await store.deleteCapture(capture.id); +}); + +test("a missing map that does belong to the script still warns", async () => { + const { capture, uploadToken } = await store.createCapture({ target }); + await store.appendCaptureRawChunk(capture.id, uploadToken, 0, Buffer.from(JSON.stringify({ traceEvents: [] }), "utf8")); + const completed = await store.finalizeCapture(capture.id, uploadToken, { + stopReason: "manual", + scripts: [{ scriptId: "9", url: "https://dev.test:8082/vendors.bundle.js", sourceMapURL: "vendors.bundle.js.map" }], + sourceMaps: [], + }); + assert.match(completed.warnings.join("\n"), /none could be retained/); + assert.equal(completed.state, "captured_with_warnings"); + await store.deleteCapture(capture.id); +}); + test("only one active capture can exist", async () => { const first = await store.createCapture({ target }); await assert.rejects(store.createCapture({ target: { ...target, tabId: 43 } }), /already active/); diff --git a/tests/chrome-extension.test.mjs b/tests/chrome-extension.test.mjs index ed2c319..fedc171 100644 --- a/tests/chrome-extension.test.mjs +++ b/tests/chrome-extension.test.mjs @@ -61,4 +61,6 @@ test("source-map failures identify the map URL, HTTP status, and network error", assert.match(background, /resource\?\.httpStatusCode/); assert.match(background, /resource\?\.netErrorName/); assert.match(background, /Could not retain source map \$\{entry\.sourceMapUrl\} for/); + assert.match(background, /a stale source-map comment a bundled module left inside/); + assert.match(background, /sourceMapBelongsToScript\(entry\.script\.url, entry\.sourceMapUrl\)/); }); From c9d86a487a4a9d8af411a5d7e1797306fac6a5bc Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Mon, 2 Nov 2026 16:34:10 +0500 Subject: [PATCH 05/10] feat: JS capture via chrome instance --- .changeset/chilled-donkeys-shake.md | 9 + packages/cli/CLI.md | 18 +- packages/cli/package.json | 6 +- packages/cli/src/cdp.js | 133 ++++++++ packages/cli/src/chrome.js | 123 +++++++ packages/cli/src/cli.js | 29 +- packages/cli/src/record-runner.js | 4 + packages/cli/src/record-session.js | 455 +++++++++++++++++++++++++ packages/cli/src/record-sink.js | 152 +++++++++ packages/cli/src/record-state.js | 121 +++++++ packages/cli/src/record.js | 235 +++++++++++++ packages/cli/src/trace-export.d.ts | 37 ++ packages/cli/src/trace-export.js | 266 +++++++++++++++ packages/cli/test/cdp.test.js | 130 +++++++ packages/cli/test/pack.test.js | 6 +- packages/cli/test/record.test.js | 250 ++++++++++++++ packages/cli/test/trace-export.test.js | 146 ++++++++ src/lib/capture-store.ts | 221 +----------- 18 files changed, 2123 insertions(+), 218 deletions(-) create mode 100644 .changeset/chilled-donkeys-shake.md create mode 100644 packages/cli/src/cdp.js create mode 100644 packages/cli/src/chrome.js create mode 100644 packages/cli/src/record-runner.js create mode 100644 packages/cli/src/record-session.js create mode 100644 packages/cli/src/record-sink.js create mode 100644 packages/cli/src/record-state.js create mode 100644 packages/cli/src/record.js create mode 100644 packages/cli/src/trace-export.d.ts create mode 100644 packages/cli/src/trace-export.js create mode 100644 packages/cli/test/cdp.test.js create mode 100644 packages/cli/test/record.test.js create mode 100644 packages/cli/test/trace-export.test.js diff --git a/.changeset/chilled-donkeys-shake.md b/.changeset/chilled-donkeys-shake.md new file mode 100644 index 0000000..b7cb77b --- /dev/null +++ b/.changeset/chilled-donkeys-shake.md @@ -0,0 +1,9 @@ +--- +"@callstack/tracesift": minor +--- + +Record Chrome performance traces from the CLI, without the browser extension. + +`tracesift record start` launches its own Chrome over the DevTools Protocol and begins tracing before the page is navigated, so page load is inside the recording; `record stop` flushes it and `record status` reports the result. The trace streams into a running TraceSift when one is reachable and is written as a `.json.gz` otherwise. `tracesift record launch` instead opens a Chrome that stays running after the command returns, so you can sign in or navigate by hand; `record start` then attaches to it without navigating, `record stop` leaves it open for further recordings, and `record close` quits it. This gives harnesses such as Codex a route to a capture that needs no extension and no one to click. + +The gzip exporter the web app already used is now shared from `@callstack/tracesift/trace-export`, so both routes produce the same enhanced-trace document. A `TracingStartedInBrowser` event that names no frames no longer suppresses the rebuilt frame metadata. diff --git a/packages/cli/CLI.md b/packages/cli/CLI.md index 46b303f..54f7bbb 100644 --- a/packages/cli/CLI.md +++ b/packages/cli/CLI.md @@ -8,6 +8,10 @@ tracesift init tracesift start tracesift explore /path/to/analysis.json --task 0 tracesift explore /path/to/react-analysis.json --commit 1.2 +tracesift record start --url https://example.com --duration 30s +tracesift record stop +tracesift record launch --url https://example.com +tracesift record close ``` `init` downloads the immutable, platform-specific web app archive selected by your CLI release, verifies its size and SHA-256 checksum, and installs it locally. It needs internet access to fetch the release artifact. Supported targets are macOS and Linux on arm64 or x64. @@ -16,6 +20,18 @@ tracesift explore /path/to/react-analysis.json --commit 1.2 `explore` opens a CPU task or React commit from a compact TraceSift analysis file in the running local web app. Use `--task ` for a CPU task, optionally with `--focus `, or `--commit .` for a React commit. The analysis file carries the measured card and selection metadata; full Explore data remains in the local TraceSift service and does not pass through the invoking integration. +## Recording a trace + +`record` captures a Chrome performance trace over the DevTools Protocol without the browser extension, which makes it the route to use from a harness such as Codex where no one is there to click. It launches its own Chrome against a throwaway profile, starts tracing before the page is navigated so page load is inside the recording, and detaches so the shell comes back immediately. + +`record start` accepts `--url` to navigate once tracing is live, `--duration 30s` to stop on its own, `--headless` for an unattended run, `--chrome ` (or `CHROME_PATH`) to choose the binary, and `--user-data-dir ` to record against an existing profile — that profile must not already be open in Chrome. `record stop` ends the recording and waits for Chrome to flush; `record status` reports the last one. Only one recording runs at a time, and its state lives in `record.json` with diagnostics in `record.log`. + +To profile something you had to sign in or click around to reach, open the browser first: `record launch [--url ...]` starts Chrome, leaves it running after the command returns and records its debugging endpoint in `browser.json`. Use the browser by hand, then run `record start`. With a launched browser open it attaches to that Chrome and does not navigate, so the trace covers what is already on screen; pass `--url` to navigate after tracing starts anyway. `--chrome`, `--user-data-dir` and `--headless` belong to `record launch` in that case. `record stop` leaves the launched browser open, so several profiles can come from one sign-in; `record close` quits it and deletes its profile when TraceSift created it, and refuses while a recording is running. With no launched browser, `record start` behaves as above: it starts its own Chrome, traces the page load and shuts that Chrome down afterwards. `record status` also reports a launched browser that is still open. + +The trace goes to a running TraceSift when `service.json` points at one, arriving in its capture list exactly as an extension capture does, so the web app's own Stop button ends a CLI recording too. With no TraceSift running it writes the same `.json.gz` under `recordings/` in the TraceSift home, or wherever `--out` says. Force either with `--sink ingest` or `--sink local`. + +Both routes produce the same enhanced-trace document: trace events, the scripts Chrome parsed, and any source maps that could be retained, so authored names survive an offline import. A trace recorded without a TraceSift running can be analyzed later through the Integration API's `analyze` endpoint or by uploading it in the web app. + ## Local integrations After the server is ready, `start` writes `service.json` in the TraceSift home. The mode-`0600` descriptor advertises the loopback base URL, TraceSift and integration API versions, owning process IDs, process instance, start time, and a random bearer token. It is removed when that server stops. Local integrations should validate the version and live process, authenticate every request with the bearer token, and treat an unreachable endpoint as a stale descriptor. @@ -24,7 +40,7 @@ Integration API v1 provides authenticated health, profile analysis, per-card han ## Local files -The default home is `~/.tracesift`; set `TRACE_SIFT_HOME` to an absolute alternate directory to isolate an installation. `app/` contains the installed standalone web app, `config.json` stores the selected provider/model, authentication method, and API keys, `auth.json` stores TraceSift OAuth credentials, `process.json` is the active operation lock, and `service.json` is the active local-integration descriptor. Credentials are plaintext at rest with mode `0600` inside a `0700` home. Keys and tokens are submitted only to the local server, are never returned to the browser, and are not logged. TraceSift never reads `~/.pi/agent/auth.json`. Clearing all credentials removes TraceSift's selected model, API keys, and OAuth connections. +The default home is `~/.tracesift`; set `TRACE_SIFT_HOME` to an absolute alternate directory to isolate an installation. `app/` contains the installed standalone web app, `config.json` stores the selected provider/model, authentication method, and API keys, `auth.json` stores TraceSift OAuth credentials, `process.json` is the active operation lock, `service.json` is the active local-integration descriptor, `record.json` and `record.log` belong to `record`, `browser.json` names a Chrome left open by `record launch`, and `recordings/` holds traces captured with no TraceSift running. Credentials are plaintext at rest with mode `0600` inside a `0700` home. Keys and tokens are submitted only to the local server, are never returned to the browser, and are not logged. TraceSift never reads `~/.pi/agent/auth.json`. Clearing all credentials removes TraceSift's selected model, API keys, and OAuth connections. Replacing an installation requires its server to be stopped. Download and verification run in a staging directory; failures preserve the existing app and configuration. Repeating `init` for a complete matching release does nothing. Updating the globally installed CLI does not update the app until you run `init` again. diff --git a/packages/cli/package.json b/packages/cli/package.json index 4f1c1de..d5e3a20 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -12,7 +12,11 @@ "./models": "./src/models.js", "./runtime": "./src/runtime.js", "./oauth": "./src/oauth.js", - "./bootstrap": "./src/bootstrap.js" + "./bootstrap": "./src/bootstrap.js", + "./trace-export": { + "types": "./src/trace-export.d.ts", + "default": "./src/trace-export.js" + } }, "files": [ "src", diff --git a/packages/cli/src/cdp.js b/packages/cli/src/cdp.js new file mode 100644 index 0000000..923f208 --- /dev/null +++ b/packages/cli/src/cdp.js @@ -0,0 +1,133 @@ +const CONNECT_TIMEOUT_MS = 15_000; +const COMMAND_TIMEOUT_MS = 30_000; + +/** @typedef {{ sessionId?: string }} CdpSession */ + +function closeReason(event) { + return event?.reason ? `${event.reason} (code ${event.code})` : `code ${event?.code ?? 'unknown'}`; +} + +/** + * A minimal Chrome DevTools Protocol client over Node's global WebSocket. + * + * Flattened sessions are the only mode used here: every command carries the + * session it belongs to, so one socket drives the browser target and each + * attached page, worker and frame without nesting. + */ +export async function connectCdp(url, { createSocket = (target) => new WebSocket(target) } = {}) { + const socket = createSocket(url); + const pending = new Map(); + const listeners = new Set(); + let nextId = 1; + let shutdown = null; + + const rejectAll = (error) => { + for (const { reject } of pending.values()) reject(error); + pending.clear(); + }; + + socket.addEventListener('message', (event) => { + let message; + try { message = JSON.parse(typeof event.data === 'string' ? event.data : String(event.data)); } + catch { return; } + if (message.id !== undefined) { + const waiter = pending.get(message.id); + if (!waiter) return; + pending.delete(message.id); + if (message.error) waiter.reject(new Error(`${waiter.method} failed: ${message.error.message || 'Chrome rejected the command.'}`)); + else waiter.resolve(message.result ?? {}); + return; + } + if (typeof message.method !== 'string') return; + // A listener throwing must not take down the socket; the recorder reports + // its own failures through the capture state instead. + for (const listener of listeners) { + try { listener(message.method, message.params ?? {}, message.sessionId); } + catch { /* ignore */ } + } + }); + + socket.addEventListener('close', (event) => { + shutdown ??= new Error(`Chrome closed the debugging connection: ${closeReason(event)}`); + rejectAll(shutdown); + }); + socket.addEventListener('error', () => { + shutdown ??= new Error('The Chrome debugging connection failed.'); + }); + + await new Promise((resolve, reject) => { + const timer = setTimeout(() => reject(new Error('Chrome did not accept a debugging connection in time.')), CONNECT_TIMEOUT_MS); + socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true }); + socket.addEventListener('close', (event) => { clearTimeout(timer); reject(new Error(`Chrome refused the debugging connection: ${closeReason(event)}`)); }, { once: true }); + }); + + return { + /** + * @param {string} method + * @param {Record} [params] + * @param {string} [sessionId] omit to address the browser target itself + */ + send(method, params = {}, sessionId) { + if (shutdown) return Promise.reject(shutdown); + const id = nextId++; + const payload = { id, method, params, ...(sessionId ? { sessionId } : {}) }; + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + pending.delete(id); + reject(new Error(`${method} did not complete in time.`)); + }, COMMAND_TIMEOUT_MS); + pending.set(id, { + method, + resolve: (value) => { clearTimeout(timer); resolve(value); }, + reject: (error) => { clearTimeout(timer); reject(error); }, + }); + try { socket.send(JSON.stringify(payload)); } + catch (error) { pending.delete(id); clearTimeout(timer); reject(error); } + }); + }, + /** @param {(method: string, params: Record, sessionId?: string) => void} listener */ + on(listener) { + listeners.add(listener); + return () => listeners.delete(listener); + }, + get closed() { return Boolean(shutdown) || socket.readyState > 1; }, + close() { + shutdown ??= new Error('The Chrome debugging connection was closed.'); + rejectAll(shutdown); + try { socket.close(); } catch { /* already gone */ } + }, + }; +} + +/** + * Read a stream handle returned by a CDP command to completion. + * + * @param {{ send: Function }} cdp + * @param {string} handle + * @param {{ sessionId?: string, size?: number, onChunk?: (bytes: Uint8Array) => Promise }} options + * @returns {Promise} concatenated text when no onChunk is given + */ +export async function readProtocolStream(cdp, handle, options = {}) { + const { sessionId, size = 512 * 1024, onChunk, limitBytes } = options; + const parts = []; + let total = 0; + try { + for (;;) { + const result = await cdp.send('IO.read', { handle, size }, sessionId); + const text = typeof result.data === 'string' ? result.data : ''; + const bytes = result.base64Encoded ? Buffer.from(text, 'base64') : Buffer.from(text, 'utf8'); + total += bytes.byteLength; + if (limitBytes && total > limitBytes) throw new Error('Stream exceeded its retention limit.'); + if (bytes.byteLength > 0) { + // Push only after the consumer acknowledges the previous chunk so a + // fast stream cannot queue an unbounded amount of trace data. + if (onChunk) await onChunk(bytes); + else parts.push(bytes); + } + if (result.eof) break; + } + } finally { + await cdp.send('IO.close', { handle }, sessionId).catch(() => undefined); + } + return onChunk ? undefined : Buffer.concat(parts).toString('utf8'); +} diff --git a/packages/cli/src/chrome.js b/packages/cli/src/chrome.js new file mode 100644 index 0000000..bae5300 --- /dev/null +++ b/packages/cli/src/chrome.js @@ -0,0 +1,123 @@ +import { spawn } from 'node:child_process'; +import { constants } from 'node:fs'; +import { access, mkdir, readFile } from 'node:fs/promises'; +import { delimiter, join } from 'node:path'; + +const PORT_FILE = 'DevToolsActivePort'; +const PORT_FILE_TIMEOUT_MS = 30_000; +const PORT_FILE_POLL_MS = 100; + +const MACOS_CANDIDATES = [ + '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', + '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary', + '/Applications/Chromium.app/Contents/MacOS/Chromium', + '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', +]; + +const LINUX_COMMANDS = ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge']; + +/** + * Flags are deliberately few. Anything that disables GPU, networking or + * background work changes the very timings this capture exists to measure, so + * only first-run interstitials that would steal the recording are suppressed. + */ +const LAUNCH_FLAGS = [ + '--no-first-run', + '--no-default-browser-check', + '--disable-search-engine-choice-screen', + '--homepage=about:blank', +]; + +async function executable(path) { + try { await access(path, constants.X_OK); return true; } + catch { return false; } +} + +async function fromPath(command) { + for (const directory of (process.env.PATH || '').split(delimiter)) { + if (!directory) continue; + const candidate = join(directory, command); + if (await executable(candidate)) return candidate; + } + return null; +} + +/** + * Resolve the Chrome binary to launch. + * + * @param {string} [preferred] an explicit path from `--chrome` or CHROME_PATH + */ +export async function findChrome(preferred) { + if (preferred) { + if (!(await executable(preferred))) throw new Error(`${preferred} is not an executable Chrome binary.`); + return preferred; + } + if (process.platform === 'darwin') { + for (const candidate of MACOS_CANDIDATES) if (await executable(candidate)) return candidate; + } + for (const command of LINUX_COMMANDS) { + const found = await fromPath(command); + if (found) return found; + } + throw new Error('Could not find Chrome. Pass --chrome or set CHROME_PATH.'); +} + +async function readDebuggerUrl(userDataDir, child, startedAt) { + for (;;) { + let raw; + try { raw = await readFile(join(userDataDir, PORT_FILE), 'utf8'); } + catch { raw = ''; } + const [port, path] = raw.split('\n'); + if (port && path && path.startsWith('/devtools/browser/')) { + return { port: Number(port), webSocketDebuggerUrl: `ws://127.0.0.1:${port}${path.trim()}` }; + } + if (child.exitCode !== null) { + // A second Chrome started against a profile that is already open simply + // hands the URL to the running instance and exits, leaving the existing + // process in charge of a debugging port we never asked it to open. + throw new Error('Chrome exited before opening a debugging port. If --user-data-dir names a profile Chrome already has open, quit that window or let TraceSift use its own profile.'); + } + if (Date.now() - startedAt > PORT_FILE_TIMEOUT_MS) throw new Error('Chrome did not open a debugging port in time.'); + await new Promise((resolve) => setTimeout(resolve, PORT_FILE_POLL_MS)); + } +} + +/** + * Launch Chrome with a debugging port it chooses itself. + * + * Port 0 lets Chrome pick a free port and publish it in DevToolsActivePort, so + * concurrent captures never collide on a fixed 9222. + * + * With `detached`, Chrome gets its own process group and the CLI lets go of + * it. CDP is only a websocket, so nothing has to stay alive to keep the + * browser open between one `tracesift` invocation and the next. + * + * @param {{ executablePath: string, userDataDir: string, url?: string, args?: string[], headless?: boolean, detached?: boolean }} options + * @returns {Promise<{ child: import('node:child_process').ChildProcess, port: number, webSocketDebuggerUrl: string }>} + */ +export async function launchChrome(options) { + const { executablePath, userDataDir, url, args = [], headless = false, detached = false } = options; + await mkdir(userDataDir, { recursive: true, mode: 0o700 }); + const argv = [ + `--user-data-dir=${userDataDir}`, + '--remote-debugging-port=0', + ...LAUNCH_FLAGS, + ...(headless ? ['--headless=new'] : []), + ...args, + // Always give Chrome a page to open. Headless Chrome started with no URL + // exposes no page target at all, and the recorder needs one to attach to + // before tracing begins. + url || 'about:blank', + ]; + const child = spawn(executablePath, argv, { stdio: 'ignore', detached }); + const startedAt = Date.now(); + child.on('error', () => undefined); + try { + const endpoint = await readDebuggerUrl(userDataDir, child, startedAt); + if (detached) child.unref(); + return { child, ...endpoint }; + } catch (error) { + child.kill('SIGKILL'); + throw error; + } +} diff --git a/packages/cli/src/cli.js b/packages/cli/src/cli.js index 7fea59e..000c37b 100755 --- a/packages/cli/src/cli.js +++ b/packages/cli/src/cli.js @@ -3,25 +3,46 @@ import { parseArgs } from 'node:util'; import { prerequisites, install } from './install.js'; import { start, parsePort } from './start.js'; import { explore } from './explore.js'; +import { + RECORD_SUBCOMMANDS, assertRecordOptions, parseDuration, recordClose, recordLaunch, recordStart, recordStatus, recordStop, +} from './record.js'; try { const { values, positionals } = parseArgs({ allowPositionals: true, options: { help: { type: 'boolean', short: 'h' }, port: { type: 'string' }, 'no-open': { type: 'boolean' }, task: { type: 'string' }, commit: { type: 'string' }, focus: { type: 'string' }, + url: { type: 'string' }, chrome: { type: 'string' }, 'user-data-dir': { type: 'string' }, + out: { type: 'string' }, duration: { type: 'string' }, headless: { type: 'boolean' }, + sink: { type: 'string' }, } }); const [command, ...extra] = positionals; if (values.help || !command) { - console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); + console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n tracesift record start [--url https://example.com] [--duration 30s] [--headless] [--out trace.json.gz]\n tracesift record stop\n tracesift record status\n tracesift record launch [--url https://example.com] [--headless] [--chrome path] [--user-data-dir path]\n tracesift record close\n\nRecording drives Chrome over the DevTools Protocol, so it needs no browser\nextension. It streams into a running TraceSift when there is one and writes a\n.json.gz otherwise; --sink ingest|local forces either.\n\nWith no browser open, record start launches its own Chrome and traces the page\nload. To profile a state you reached by hand, record launch a browser, sign in\nor navigate, then record start: it attaches without navigating, and the\nbrowser stays open after record stop until record close.\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); } else { - if (!['init', 'start', 'explore'].includes(command)) throw new Error('Unknown command. Run tracesift --help.'); - if (command !== 'explore' && extra.length) throw new Error('Unknown command. Run tracesift --help.'); + if (!['init', 'start', 'explore', 'record'].includes(command)) throw new Error('Unknown command. Run tracesift --help.'); + if (!['explore', 'record'].includes(command) && extra.length) throw new Error('Unknown command. Run tracesift --help.'); if (command === 'explore' && extra.length !== 1) throw new Error('Explore requires one analysis path. Run tracesift --help.'); + if (command === 'record' && (extra.length !== 1 || !RECORD_SUBCOMMANDS.includes(extra[0]))) { + throw new Error('Record requires one of start, stop, status, launch or close. Run tracesift --help.'); + } if ((values.port || values['no-open']) && command !== 'start') throw new Error('This option is not supported for this command. Run tracesift --help.'); if ((values.task || values.commit || values.focus) && command !== 'explore') throw new Error('This option is not supported for this command. Run tracesift --help.'); + assertRecordOptions(command, extra[0], values); + if (values.sink && !['auto', 'ingest', 'local'].includes(values.sink)) throw new Error('Sink must be auto, ingest or local.'); prerequisites(); if (command === 'init') await install(); else if (command === 'start') await start({ port: parsePort(values.port), open: !values['no-open'] }); - else await explore(extra[0], { task: values.task, commit: values.commit, focus: values.focus }); + else if (command === 'explore') await explore(extra[0], { task: values.task, commit: values.commit, focus: values.focus }); + else if (extra[0] === 'start') await recordStart({ + url: values.url, chrome: values.chrome, userDataDir: values['user-data-dir'], + out: values.out, duration: parseDuration(values.duration), headless: values.headless, sink: values.sink, + }); + else if (extra[0] === 'launch') await recordLaunch({ + url: values.url, chrome: values.chrome, userDataDir: values['user-data-dir'], headless: values.headless, + }); + else if (extra[0] === 'close') await recordClose(); + else if (extra[0] === 'stop') await recordStop(); + else await recordStatus(); } } catch (error) { console.error(`tracesift: ${error.message}`); process.exitCode = 1; diff --git a/packages/cli/src/record-runner.js b/packages/cli/src/record-runner.js new file mode 100644 index 0000000..36c36cc --- /dev/null +++ b/packages/cli/src/record-runner.js @@ -0,0 +1,4 @@ +#!/usr/bin/env node +import { recorderMain } from './record-session.js'; + +await recorderMain(process.argv.slice(2)); diff --git a/packages/cli/src/record-session.js b/packages/cli/src/record-session.js new file mode 100644 index 0000000..45713a6 --- /dev/null +++ b/packages/cli/src/record-session.js @@ -0,0 +1,455 @@ +import { rm } from 'node:fs/promises'; +import { join } from 'node:path'; + +import { connectCdp, readProtocolStream } from './cdp.js'; +import { findChrome, launchChrome } from './chrome.js'; +import { createIngestSink, createLocalSink } from './record-sink.js'; +import { liveBrowserState, writeRecordState } from './record-state.js'; +import { readActiveService } from './service.js'; + +const SAFE_BUFFER_LIMIT = 0.9; +// Keep each upload well under the ingest route's 1 MB cap even when every +// code unit Chrome returns expands to four UTF-8 bytes. +const MAX_UPLOAD_BYTES = 192 * 1024; +const MAX_SOURCE_MAP_BYTES = 8 * 1024 * 1024; +const MAX_ALL_SOURCE_MAP_BYTES = 16 * 1024 * 1024; +const STOP_POLL_MS = 1000; + +const TRACE_CATEGORIES = [ + '-*', + 'blink.console', + 'blink.user_timing', + 'devtools.timeline', + 'disabled-by-default-devtools.timeline', + 'disabled-by-default-devtools.timeline.frame', + 'disabled-by-default-devtools.timeline.stack', + 'disabled-by-default-v8.cpu_profiler', + 'disabled-by-default-v8.cpu_profiler.hires', + 'disabled-by-default-v8.source_rundown', + 'disabled-by-default-v8.source_rundown_sources', + 'latencyInfo', + 'loading', + 'toplevel', + 'v8.execute', +].join(','); + +function errorText(error) { + return error instanceof Error ? error.message : String(error || 'Unknown recording error.'); +} + +function sourceMapBasename(value) { + const clean = (value || '').split(/[?#]/)[0]; + return clean.slice(clean.lastIndexOf('/') + 1); +} + +// A bundled module's own `//# sourceMappingURL` comment can survive +// concatenation, and Chrome reports the last comment it finds in a script. Such +// a name points at a file the bundler never emitted, so failing to load it says +// nothing about whether the bundle itself has a retrievable map. +function sourceMapBelongsToScript(scriptUrl, sourceMapUrl) { + const script = sourceMapBasename(scriptUrl); + const map = sourceMapBasename(sourceMapUrl).replace(/\.map$/, ''); + if (!script || !map) return true; + return script.startsWith(map) || map.startsWith(script); +} + +function decodeDataUrl(url) { + const comma = url.indexOf(','); + if (comma < 0) throw new Error('Malformed source-map data URL.'); + const header = url.slice(0, comma); + const payload = url.slice(comma + 1); + return header.includes(';base64') ? Buffer.from(payload, 'base64').toString('utf8') : decodeURIComponent(payload); +} + +function resolveSourceMapUrl(script) { + return new URL(script.sourceMapURL, script.url || undefined).href; +} + +function sourceMapLoadFailure(resource, sourceMapUrl) { + const details = []; + if (Number.isInteger(resource?.httpStatusCode)) details.push(`HTTP ${resource.httpStatusCode}`); + if (resource?.netErrorName) details.push(resource.netErrorName); + return new Error(details.length > 0 ? `${sourceMapUrl} returned ${details.join('; ')}` : `Could not load ${sourceMapUrl}`); +} + +/** + * Keep renderer page metadata active and follow every child execution context. + * Failures are tolerated: a target can detach between attach and configuration. + */ +async function configureSession(cdp, sessionId) { + await cdp.send('Page.enable', {}, sessionId).catch(() => undefined); + await cdp.send('Debugger.enable', {}, sessionId).catch(() => undefined); + await cdp.send('Target.setAutoAttach', { + autoAttach: true, + waitForDebuggerOnStart: false, + flatten: true, + filter: [ + { type: 'iframe', exclude: false }, + { type: 'worker', exclude: false }, + { type: 'shared_worker', exclude: false }, + { type: 'service_worker', exclude: false }, + ], + }, sessionId).catch(() => undefined); +} + +async function mainFrameOf(cdp, sessionId) { + try { + const result = await cdp.send('Page.getFrameTree', {}, sessionId); + const frame = result.frameTree?.frame; + if (!frame || typeof frame.id !== 'string') return undefined; + return { id: frame.id, url: frame.url || '', name: frame.name || '' }; + } catch { return undefined; } +} + +/** Wait for Chrome to report a page target it is willing to let us attach to. */ +async function pageTarget(cdp) { + const deadline = Date.now() + 15_000; + for (;;) { + const { targetInfos = [] } = await cdp.send('Target.getTargets'); + const page = targetInfos.find((target) => target.type === 'page' && !/^(chrome|chrome-extension|devtools):/.test(target.url || '')); + if (page) return page; + if (Date.now() > deadline) throw new Error('Chrome did not open a page to record.'); + await new Promise((resolve) => setTimeout(resolve, 100)); + } +} + +/** + * Retain source maps for the scripts Chrome reported, mirroring what DevTools + * embeds in an enhanced trace so authored names survive an offline import. + */ +function sourceMapCollector(cdp) { + const entries = new Map(); + const warnings = []; + let queue = Promise.resolve(); + let bytes = 0; + let limitReached = false; + + async function load(script, sourceMapUrl) { + if (!script.url || !script.sourceMapURL || script.url.startsWith('chrome-extension:')) return null; + let raw; + if (sourceMapUrl.startsWith('data:')) { + raw = decodeDataUrl(sourceMapUrl); + } else { + const result = await cdp.send('Network.loadNetworkResource', { + ...(script.frameId ? { frameId: script.frameId } : {}), + url: sourceMapUrl, + options: { disableCache: false, includeCredentials: true }, + }, script.sessionId); + if (!result.resource?.success || !result.resource.stream) throw sourceMapLoadFailure(result.resource, sourceMapUrl); + raw = await readProtocolStream(cdp, result.resource.stream, { sessionId: script.sessionId, limitBytes: MAX_SOURCE_MAP_BYTES }); + } + if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error('Source map exceeds the 8 MB retention limit.'); + const sourceMap = JSON.parse(raw); + if (!sourceMap || typeof sourceMap !== 'object' || Array.isArray(sourceMap)) throw new Error('Source map is not a JSON object.'); + return { url: script.url, sourceMapUrl, sourceMap, bytes: raw.length }; + } + + async function retain(entry) { + if (entry.retained || limitReached) return; + try { + const loaded = await load(entry.script, entry.sourceMapUrl); + if (!loaded) return; + if (bytes + loaded.bytes > MAX_ALL_SOURCE_MAP_BYTES) { + limitReached = true; + warnings.push('Stopped retaining source maps after the 16 MB safety limit.'); + return; + } + bytes += loaded.bytes; + entry.retained = { url: loaded.url, sourceMapUrl: loaded.sourceMapUrl, sourceMap: loaded.sourceMap }; + entry.error = null; + } catch (error) { + entry.error = errorText(error); + } + } + + return { + queue(script) { + if (!script.url || !script.sourceMapURL || script.url.startsWith('chrome-extension:')) return; + let sourceMapUrl; + try { sourceMapUrl = resolveSourceMapUrl(script); } + catch { + warnings.push(`Ignored an invalid source-map URL for ${script.url || 'an anonymous script'}.`); + return; + } + // DevTools does not duplicate data-URL maps in metadata: source-rundown + // events already carry their contents in the trace. + if (sourceMapUrl.startsWith('data:')) return; + const key = `${script.url}\n${sourceMapUrl}`; + if (entries.has(key)) return; + const entry = { script, sourceMapUrl, retained: null, error: null }; + entries.set(key, entry); + // Serialize reads so eager retention never holds an unbounded number of + // large maps while still enforcing the aggregate byte limit. + queue = queue.then(() => retain(entry)); + }, + async collect() { + await queue; + // A development server can still be compiling when scriptParsed arrives. + // Retry eager failures once at finalization, matching DevTools' fallback. + for (const entry of entries.values()) { + if (!entry.retained && entry.error && !limitReached) await retain(entry); + } + const all = [...warnings]; + for (const entry of entries.values()) { + if (!entry.retained && entry.error) { + const script = entry.script.url || 'an anonymous script'; + all.push(sourceMapBelongsToScript(entry.script.url, entry.sourceMapUrl) + ? `Could not retain source map ${entry.sourceMapUrl} for ${script}: ${entry.error}` + : `Ignored ${entry.sourceMapUrl}, a stale source-map comment a bundled module left inside ${script}: ${entry.error}`); + } + } + return { + retained: [...entries.values()].flatMap((entry) => entry.retained ? [entry.retained] : []), + warnings: [...new Set(all)], + }; + }, + }; +} + +/** Choose where the trace goes: a running TraceSift if there is one, else disk. */ +async function resolveSink(home, target, title, options) { + if (options.sink !== 'local') { + try { + const service = await readActiveService(home); + return await createIngestSink(service, target, title); + } catch (error) { + if (options.sink === 'ingest') throw error; + } + } + return createLocalSink(home, target, options); +} + +/** + * Record a Chrome performance trace over the DevTools Protocol. + * + * Unlike the extension, the trace is started on the page before it is + * navigated, so page load is inside the recording and Chrome still emits its + * own browser-process frame metadata. + * + * When `record launch` left a browser running the recording attaches to it + * instead and leaves the page where it is: the point of that browser is to + * profile a state that took signing in or clicking around to reach, and a + * navigation would throw it away. Passing `url` still navigates. That browser + * outlives the recording; only a Chrome started here is shut down here. + * + * @param {{ + * home: string, + * url?: string, + * chrome?: string, + * userDataDir?: string, + * out?: string, + * duration?: number, + * headless?: boolean, + * sink?: 'auto' | 'ingest' | 'local', + * onReady?: (info: { captureId: string, mode: string }) => void, + * }} options + */ +export async function runRecording(options) { + const { home } = options; + const existing = await liveBrowserState(home); + const ownsProfile = !existing && !options.userDataDir; + const userDataDir = options.userDataDir || join(home, 'chrome-profiles', `record-${process.pid}`); + + const launched = existing ? null : await launchChrome({ + executablePath: await findChrome(options.chrome || process.env.CHROME_PATH), + userDataDir, + headless: options.headless, + }); + const webSocketDebuggerUrl = existing?.webSocketDebuggerUrl ?? launched.webSocketDebuggerUrl; + let cdp; + let sink; + let stopReason = 'manual'; + const warnings = []; + const scripts = new Map(); + const sourceMaps = sourceMapCollector({ send: (...args) => cdp.send(...args) }); + + const cleanup = async () => { + cdp?.close(); + if (!launched) return; + launched.child.kill('SIGTERM'); + if (ownsProfile) await rm(userDataDir, { recursive: true, force: true }).catch(() => undefined); + }; + + try { + cdp = await connectCdp(webSocketDebuggerUrl); + const page = await pageTarget(cdp); + const { sessionId } = await cdp.send('Target.attachToTarget', { targetId: page.targetId, flatten: true }); + await configureSession(cdp, sessionId); + + const target = { tabId: 0, title: page.title || options.url || 'Chrome performance capture', url: options.url || page.url || '' }; + sink = await resolveSink(home, target, target.title, options); + const traceMarker = `__tracesift_main_${sink.captureId}`; + let mainFrame = await mainFrameOf(cdp, sessionId); + + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink.mode, + state: 'starting', + startedAt: Date.now(), + url: target.url, + captureId: sink.captureId, + ...(sink.baseUrl ? { baseUrl: sink.baseUrl } : {}), + ...(sink.directory ? { directory: sink.directory } : {}), + }); + await sink.status({ state: 'attaching' }).catch(() => undefined); + + let stop; + const stopped = new Promise((resolve) => { stop = (reason) => { stopReason = reason; resolve(reason); }; }); + + cdp.on((method, params, source) => { + if (method === 'Target.attachedToTarget') { + void configureSession(cdp, params.sessionId); + return; + } + if (method === 'Debugger.scriptParsed' && typeof params.scriptId === 'string') { + if (scripts.size >= 50_000) return; + const script = { + scriptId: params.scriptId, + url: params.url || '', + ...(params.sourceMapURL ? { sourceMapURL: params.sourceMapURL } : {}), + ...(typeof params.executionContextAuxData?.frameId === 'string' ? { frameId: params.executionContextAuxData.frameId } : {}), + ...(source ? { sessionId: source } : {}), + }; + scripts.set(`${source || 'root'}:${params.scriptId}`, script); + sourceMaps.queue(script); + return; + } + if (method === 'Tracing.bufferUsage') { + const usage = Number(params.percentFull ?? params.value ?? 0); + void sink.status({ bufferUsage: usage, eventCount: Number(params.eventCount || 0) }).catch(() => undefined); + if (usage >= SAFE_BUFFER_LIMIT) stop('buffer_limit'); + } + }); + + // Tracing is scoped to the page session rather than the browser target. + // A browser-target trace started before any navigation emits a + // TracingStartedInBrowser with empty args, which claims to describe the + // trace's frames and does not; the renderer scope keeps the one metadata + // path the exporter already knows how to complete. + await cdp.send('Tracing.start', { + categories: TRACE_CATEGORIES, + options: 'record-until-full', + bufferUsageReportingInterval: 1000, + transferMode: 'ReturnAsStream', + streamFormat: 'json', + streamCompression: 'none', + }, sessionId); + // Leave a renderer-main marker anyway: a Chrome that withholds browser + // metadata still lets the exporter rebuild the equivalent frame record. + await cdp.send('Runtime.evaluate', { + expression: `performance.mark(${JSON.stringify(traceMarker)})`, + returnByValue: true, + }, sessionId).catch(() => undefined); + + if (options.url) { + await cdp.send('Page.navigate', { url: options.url }, sessionId); + } + + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink.mode, + state: 'recording', + startedAt: Date.now(), + url: target.url, + captureId: sink.captureId, + ...(sink.baseUrl ? { baseUrl: sink.baseUrl } : {}), + ...(sink.directory ? { directory: sink.directory } : {}), + }); + await sink.status({ state: 'recording' }).catch(() => undefined); + options.onReady?.({ captureId: sink.captureId, mode: sink.mode }); + + const onSignal = () => stop('manual'); + process.on('SIGINT', onSignal); + process.on('SIGTERM', onSignal); + const durationTimer = options.duration ? setTimeout(() => stop('manual'), options.duration) : null; + // The web app's Stop button only sets a state; an ingesting recorder has to + // notice it the same way the extension does. + const poller = setInterval(() => { + void sink.stopRequested().then((requested) => { if (requested) stop('manual'); }).catch(() => undefined); + }, STOP_POLL_MS); + + await stopped; + + process.off('SIGINT', onSignal); + process.off('SIGTERM', onSignal); + if (durationTimer) clearTimeout(durationTimer); + clearInterval(poller); + + await sink.status({ state: 'flushing', stopReason }).catch(() => undefined); + mainFrame = (await mainFrameOf(cdp, sessionId)) ?? mainFrame; + + const complete = new Promise((resolve, reject) => { + const timer = setTimeout(() => reject(new Error('Chrome did not finish flushing the trace in time.')), 120_000); + const off = cdp.on((method, params) => { + if (method !== 'Tracing.tracingComplete') return; + clearTimeout(timer); + off(); + resolve(params); + }); + }); + await cdp.send('Tracing.end', {}, sessionId); + const finished = await complete; + if (!finished.stream) throw new Error('Chrome completed tracing without returning a stream.'); + + await readProtocolStream(cdp, finished.stream, { sessionId, size: MAX_UPLOAD_BYTES, onChunk: (bytes) => sink.chunk(bytes) }); + + await sink.status({ state: 'enriching' }).catch(() => undefined); + const collected = await sourceMaps.collect(); + warnings.push(...collected.warnings); + + const result = await sink.finalize({ + dataLoss: finished.dataLossOccurred === true, + stopReason, + scripts: [...scripts.values()], + sourceMaps: collected.retained, + warnings, + mainFrame, + traceMarker, + }); + + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink.mode, + state: 'captured', + startedAt: Date.now(), + url: target.url, + captureId: sink.captureId, + ...(sink.baseUrl ? { baseUrl: sink.baseUrl } : {}), + ...(sink.directory ? { directory: sink.directory } : {}), + export: { path: result.path ?? '', sizeBytes: result.sizeBytes, eventCount: result.eventCount }, + warnings: result.warnings ?? warnings, + }); + return { ...result, mode: sink.mode, captureId: sink.captureId, baseUrl: sink.baseUrl }; + } catch (error) { + const message = errorText(error); + await sink?.fail(message).catch(() => undefined); + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink?.mode ?? 'local', + state: 'failed', + startedAt: Date.now(), + url: options.url ?? '', + ...(sink?.captureId ? { captureId: sink.captureId } : {}), + error: message, + }).catch(() => undefined); + throw error; + } finally { + await cleanup(); + } +} + +/** Entry point for the detached recorder `tracesift record start` spawns. */ +export async function recorderMain(argv) { + try { + await runRecording(JSON.parse(argv[0])); + } catch (error) { + // The failure is already recorded in record.json for `record stop` and + // `record status` to report; the log keeps the full text. + console.error(`tracesift: ${errorText(error)}`); + process.exitCode = 1; + } +} diff --git a/packages/cli/src/record-sink.js b/packages/cli/src/record-sink.js new file mode 100644 index 0000000..bde386d --- /dev/null +++ b/packages/cli/src/record-sink.js @@ -0,0 +1,152 @@ +import { randomUUID } from 'node:crypto'; +import { appendFile, mkdir, rm, writeFile } from 'node:fs/promises'; +import { dirname, isAbsolute, join, resolve } from 'node:path'; + +import { writeTraceExport } from './trace-export.js'; + +/** + * A sink receives the raw trace Chrome streams back and turns it into a + * finished export. Two exist: one hands the bytes to a running TraceSift so the + * capture appears in its UI, the other writes the same `.json.gz` on its own. + * + * @typedef {{ + * mode: 'ingest' | 'local', + * captureId: string, + * directory?: string, + * baseUrl?: string, + * status(update: Record): Promise, + * stopRequested(): Promise, + * chunk(bytes: Uint8Array): Promise, + * finalize(input: Record): Promise<{ path?: string, fileName: string, sizeBytes: number, eventCount: number, warnings: string[] }>, + * fail(message: string, reason?: string): Promise, + * }} RecordSink + */ + +async function jsonFetch(url, init = {}) { + const response = await fetch(url, init); + const body = await response.json().catch(() => ({})); + if (!response.ok) throw new Error(body.error || `TraceSift returned HTTP ${response.status}.`); + return body; +} + +function authHeaders(token) { + return { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` }; +} + +function exportStamp(createdAt) { + return new Date(createdAt).toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z'); +} + +/** + * Build the enhanced-trace `metadata` object, matching what the web app writes + * for an extension capture so both exports import identically. + */ +function exportMetadata(captureId, target, createdAt, scripts, sourceMaps) { + return { + enhancedTraceVersion: 1, + sourceMaps, + traceSift: { + captureId, + target, + createdAt: new Date(createdAt).toISOString(), + scripts, + }, + }; +} + +/** Hand the trace to a running TraceSift, exactly as the extension does. */ +export async function createIngestSink(service, target, title) { + const { capture, uploadToken } = await jsonFetch(`${service.baseUrl}/api/captures`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ title, target }), + }); + let sequence = 0; + return { + mode: 'ingest', + captureId: capture.id, + baseUrl: service.baseUrl, + async status(update) { + await jsonFetch(`${service.baseUrl}/api/captures/${capture.id}/ingest/status`, { + method: 'POST', headers: authHeaders(uploadToken), body: JSON.stringify(update), + }); + }, + async stopRequested() { + const result = await jsonFetch(`${service.baseUrl}/api/captures/${capture.id}`, { cache: 'no-store' }); + return result.capture?.state === 'stop_requested'; + }, + async chunk(bytes) { + const response = await fetch(`${service.baseUrl}/api/captures/${capture.id}/ingest/raw?sequence=${sequence}`, { + method: 'POST', + headers: { 'Content-Type': 'application/octet-stream', Authorization: `Bearer ${uploadToken}` }, + body: bytes, + }); + const body = await response.json().catch(() => ({})); + if (!response.ok) throw new Error(body.error || `TraceSift returned HTTP ${response.status}.`); + sequence += 1; + }, + async finalize(input) { + const result = await jsonFetch(`${service.baseUrl}/api/captures/${capture.id}/ingest/finalize`, { + method: 'POST', headers: authHeaders(uploadToken), body: JSON.stringify(input), + }); + const record = result.capture ?? result; + return { + fileName: record.export?.fileName ?? '', + sizeBytes: record.export?.sizeBytes ?? 0, + eventCount: record.eventCount ?? 0, + warnings: record.warnings ?? [], + }; + }, + async fail(message, reason = 'error') { + await this.status({ state: 'failed', stopReason: reason, error: message }).catch(() => undefined); + }, + }; +} + +/** + * Write the trace without a running TraceSift. Recordings live beside the + * capture store rather than inside it: they carry none of the store's + * bookkeeping, so they must not look like records it owns. + */ +export async function createLocalSink(home, target, options = {}) { + const captureId = randomUUID(); + const createdAt = Date.now(); + const directory = join(home, 'recordings', captureId); + await mkdir(directory, { recursive: true, mode: 0o700 }); + const spool = join(directory, 'trace.spool'); + await writeFile(spool, '', { flag: 'wx', mode: 0o600 }); + const fileName = `Trace-${exportStamp(createdAt)}.json.gz`; + const destination = options.out + ? resolve(isAbsolute(options.out) ? options.out : join(process.cwd(), options.out)) + : join(directory, fileName); + return { + mode: 'local', + captureId, + directory, + async status() { /* No server holds this recording's state; record.json does. */ }, + async stopRequested() { return false; }, + async chunk(bytes) { await appendFile(spool, bytes); }, + async finalize(input) { + await mkdir(dirname(destination), { recursive: true }); + const written = await writeTraceExport({ + spool, + destination, + metadata: exportMetadata(captureId, target, createdAt, input.scripts ?? [], input.sourceMaps ?? []), + mainFrame: input.mainFrame, + fallbackUrl: target.url, + traceMarker: input.traceMarker, + }); + // The spool is several times the size of the export it produced and + // nothing reads it again once the gzip is on disk. + await rm(spool, { force: true }); + return { + path: destination, + fileName: destination.slice(destination.lastIndexOf('/') + 1), + sizeBytes: written.sizeBytes, + eventCount: written.eventCount, + warnings: input.warnings ?? [], + }; + }, + async fail() { /* The caller records the failure in record.json. */ }, + }; +} diff --git a/packages/cli/src/record-state.js b/packages/cli/src/record-state.js new file mode 100644 index 0000000..15d6a9e --- /dev/null +++ b/packages/cli/src/record-state.js @@ -0,0 +1,121 @@ +import { randomUUID } from 'node:crypto'; +import { readFile, rename, rm, writeFile } from 'node:fs/promises'; +import { join } from 'node:path'; + +export const RECORD_STATE = 'record.json'; +export const RECORD_API_VERSION = 1; +export const BROWSER_STATE = 'browser.json'; + +/** + * @typedef {{ + * apiVersion: 1, + * pid: number, + * mode: 'ingest' | 'local', + * state: 'starting' | 'recording' | 'flushing' | 'captured' | 'failed', + * startedAt: number, + * url: string, + * captureId?: string, + * baseUrl?: string, + * directory?: string, + * export?: { path: string, sizeBytes: number, eventCount: number }, + * warnings?: string[], + * error?: string, + * }} RecordState + */ + +/** + * A Chrome that `record launch` left running for later recordings. + * + * @typedef {{ + * apiVersion: 1, + * pid: number, + * webSocketDebuggerUrl: string, + * port: number, + * userDataDir: string, + * ownsProfile: boolean, + * url: string, + * startedAt: number, + * }} BrowserState + */ + +function statePath(home) { return join(home, RECORD_STATE); } +function browserPath(home) { return join(home, BROWSER_STATE); } + +export function processAlive(pid) { + if (!Number.isSafeInteger(pid) || pid <= 0) return false; + try { process.kill(pid, 0); return true; } + catch (error) { return error?.code === 'EPERM'; } +} + +/** @returns {Promise} */ +export async function readRecordState(home) { + let raw; + try { raw = await readFile(statePath(home), 'utf8'); } + catch (error) { if (error.code === 'ENOENT') return null; throw error; } + let state; + try { state = JSON.parse(raw); } + catch { return null; } + return state?.apiVersion === RECORD_API_VERSION ? state : null; +} + +async function writeJsonAtomic(home, destination, value) { + const temporary = join(home, `.record-${randomUUID()}`); + try { + await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 }); + await rename(temporary, destination); + } finally { + await rm(temporary, { force: true }); + } +} + +/** @param {RecordState} state */ +export async function writeRecordState(home, state) { + await writeJsonAtomic(home, statePath(home), state); +} + +/** Remove only the state this recorder published, never a later recording. */ +export async function clearRecordState(home, pid) { + const current = await readRecordState(home); + if (pid && current && current.pid !== pid) return; + await rm(statePath(home), { force: true }); +} + +/** A state file left behind by a recorder that died is not an active recording. */ +export async function activeRecordState(home) { + const state = await readRecordState(home); + if (!state) return null; + if (['captured', 'failed'].includes(state.state)) return null; + return processAlive(state.pid) ? state : null; +} + +/** @returns {Promise} */ +export async function readBrowserState(home) { + let raw; + try { raw = await readFile(browserPath(home), 'utf8'); } + catch (error) { if (error.code === 'ENOENT') return null; throw error; } + let state; + try { state = JSON.parse(raw); } + catch { return null; } + return state?.apiVersion === RECORD_API_VERSION ? state : null; +} + +/** @param {BrowserState} state */ +export async function writeBrowserState(home, state) { + await writeJsonAtomic(home, browserPath(home), state); +} + +export async function clearBrowserState(home) { + await rm(browserPath(home), { force: true }); +} + +/** + * The launched browser, if it is still running. The file outlives a Chrome the + * user quit by hand, and its endpoint would then refuse every connection, so a + * dead pid means there is no browser to attach to. + * + * @returns {Promise} + */ +export async function liveBrowserState(home) { + const state = await readBrowserState(home); + return state && processAlive(state.pid) ? state : null; +} diff --git a/packages/cli/src/record.js b/packages/cli/src/record.js new file mode 100644 index 0000000..a390b3c --- /dev/null +++ b/packages/cli/src/record.js @@ -0,0 +1,235 @@ +import { spawn } from 'node:child_process'; +import { open, rm } from 'node:fs/promises'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import { connectCdp } from './cdp.js'; +import { findChrome, launchChrome } from './chrome.js'; +import { ensureHome, getHome } from './config.js'; +import { + activeRecordState, clearBrowserState, liveBrowserState, processAlive, readBrowserState, readRecordState, writeBrowserState, +} from './record-state.js'; + +const RUNNER = fileURLToPath(new URL('./record-runner.js', import.meta.url)); +const READY_TIMEOUT_MS = 45_000; +const FLUSH_TIMEOUT_MS = 180_000; +const POLL_MS = 150; +const CLOSE_TIMEOUT_MS = 10_000; + +// Which options each `record` subcommand understands. `launch` only shapes the +// browser; everything about the trace itself belongs to `start`. +const RECORD_OPTIONS = { + start: ['url', 'chrome', 'user-data-dir', 'out', 'duration', 'headless', 'sink'], + launch: ['url', 'chrome', 'user-data-dir', 'headless'], + stop: [], + status: [], + close: [], +}; +export const RECORD_SUBCOMMANDS = Object.keys(RECORD_OPTIONS); + +/** + * Reject an option the chosen command would silently ignore, so a typo such as + * `record stop --out x` fails instead of looking like it worked. + * + * @param {string} command top-level command + * @param {string | undefined} subcommand the `record` verb, when there is one + * @param {Record} values parsed options + */ +export function assertRecordOptions(command, subcommand, values) { + const given = [...new Set(Object.values(RECORD_OPTIONS).flat())].filter((option) => values[option]); + if (given.length === 0) return; + if (command !== 'record') throw new Error('This option is only supported by tracesift record. Run tracesift --help.'); + const allowed = RECORD_OPTIONS[subcommand] ?? []; + const rejected = given.find((option) => !allowed.includes(option)); + if (rejected) throw new Error(`--${rejected} is not supported by tracesift record ${subcommand}. Run tracesift --help.`); +} + +/** Accept `30`, `30s`, `500ms` or `2m`; a bare number is seconds. */ +export function parseDuration(value) { + if (value === undefined) return undefined; + const match = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(value.trim()); + if (!match) throw new Error('Duration must look like 30s, 500ms or 2m.'); + const scale = { ms: 1, s: 1000, m: 60_000 }[match[2] || 's']; + const milliseconds = Number(match[1]) * scale; + if (!(milliseconds > 0) || milliseconds > 3_600_000) throw new Error('Duration must be between 1ms and 1h.'); + return milliseconds; +} + +function describe(state) { + if (!state) return 'No recording has been made yet.'; + if (state.state === 'failed') return `Recording failed: ${state.error || 'unknown error.'}`; + if (state.state === 'captured') { + const where = state.mode === 'ingest' + ? `${state.baseUrl}/capture (capture ${state.captureId})` + : state.export?.path || state.directory; + const size = state.export?.sizeBytes ? ` · ${(state.export.sizeBytes / 1_048_576).toFixed(1)} MB` : ''; + const events = state.export?.eventCount ? ` · ${state.export.eventCount.toLocaleString()} events` : ''; + return `Recorded ${where}${size}${events}`; + } + return `Recording ${state.url || 'Chrome'} (${state.state}).`; +} + +function describeBrowser(browser) { + return `Chrome launched by \`tracesift record launch\` is open (pid ${browser.pid}${browser.url ? `, ${browser.url}` : ''}).`; +} + +async function waitFor(home, predicate, timeout, onTimeout) { + const deadline = Date.now() + timeout; + for (;;) { + const state = await readRecordState(home); + if (state && predicate(state)) return state; + if (state && !processAlive(state.pid) && state.state !== 'captured') { + throw new Error(state.error || 'The recorder stopped before it finished.'); + } + if (Date.now() > deadline) throw new Error(onTimeout); + await new Promise((resolve) => setTimeout(resolve, POLL_MS)); + } +} + +/** + * Launch Chrome under the DevTools Protocol and begin recording in a detached + * process, so a harness gets its shell back while the trace keeps running. + */ +export async function recordStart(options = {}) { + const home = getHome(); + await ensureHome(home); + const running = await activeRecordState(home); + if (running) throw new Error(`A recording is already running (${running.url || 'Chrome'}). Stop it with \`tracesift record stop\`.`); + + const browser = await liveBrowserState(home); + // Those options choose how to launch a Chrome, and none is being launched. + if (browser && (options.chrome || options.userDataDir || options.headless)) { + throw new Error('--chrome, --user-data-dir and --headless apply to a new Chrome, but a browser from `tracesift record launch` is open. Close it with `tracesift record close` or drop them.'); + } + + const payload = JSON.stringify({ + home, + url: options.url, + chrome: options.chrome, + userDataDir: options.userDataDir, + out: options.out, + duration: options.duration, + headless: Boolean(options.headless), + sink: options.sink ?? 'auto', + }); + const log = await open(`${home}/record.log`, 'a', 0o600); + const child = spawn(process.execPath, [RUNNER, payload], { + detached: true, + stdio: ['ignore', log.fd, log.fd], + }); + child.unref(); + await log.close(); + + const state = await waitFor(home, (value) => value.state === 'recording' || value.state === 'captured', + READY_TIMEOUT_MS, 'Chrome did not start recording in time. See record.log in the TraceSift home directory.'); + const sink = state.mode === 'ingest' ? `streaming into ${state.baseUrl}` : `writing to ${state.directory}`; + console.log(`Recording ${state.url || 'Chrome'}${browser ? ' in the launched browser' : ''}, ${sink}.`); + console.log(options.duration + ? `Stops automatically in ${Math.round(options.duration / 1000)}s, or run \`tracesift record stop\`.` + : 'Run `tracesift record stop` when the interaction is done.'); + return state; +} + +/** Signal the detached recorder, then wait for Chrome to flush the trace. */ +export async function recordStop() { + const home = getHome(); + const state = await activeRecordState(home); + if (!state) { + const last = await readRecordState(home); + throw new Error(last ? `No recording is running. ${describe(last)}` : 'No recording is running.'); + } + try { process.kill(state.pid, 'SIGTERM'); } + catch (error) { if (error?.code !== 'ESRCH') throw error; } + + const finished = await waitFor(home, (value) => ['captured', 'failed'].includes(value.state), + FLUSH_TIMEOUT_MS, 'Chrome did not finish flushing the trace in time.'); + if (finished.state === 'failed') throw new Error(finished.error || 'Recording failed.'); + console.log(describe(finished)); + for (const warning of finished.warnings ?? []) console.log(` warning: ${warning}`); + return finished; +} + +export async function recordStatus() { + const home = getHome(); + const state = await readRecordState(home); + console.log(describe(state)); + const browser = await liveBrowserState(home); + if (browser) console.log(describeBrowser(browser)); + return state; +} + +/** + * Start Chrome and walk away from it. Recordings attach to it by endpoint, so + * the user can sign in or navigate by hand first and profile several times + * from one session. + */ +export async function recordLaunch(options = {}) { + const home = getHome(); + await ensureHome(home); + const existing = await liveBrowserState(home); + if (existing) throw new Error(`${describeBrowser(existing)} Close it with \`tracesift record close\` first.`); + + // A Chrome that was quit by hand leaves its profile behind with nobody to + // `record close` it. + const stale = await readBrowserState(home); + if (stale?.ownsProfile) await rm(stale.userDataDir, { recursive: true, force: true }); + + const executablePath = await findChrome(options.chrome || process.env.CHROME_PATH); + const ownsProfile = !options.userDataDir; + const userDataDir = options.userDataDir || join(home, 'chrome-profiles', `browser-${process.pid}`); + const launched = await launchChrome({ + executablePath, userDataDir, url: options.url, headless: options.headless, detached: true, + }); + const state = { + apiVersion: 1, + pid: launched.child.pid, + webSocketDebuggerUrl: launched.webSocketDebuggerUrl, + port: launched.port, + userDataDir, + ownsProfile, + url: options.url ?? '', + startedAt: Date.now(), + }; + await writeBrowserState(home, state); + console.log(`Launched Chrome (pid ${state.pid}) on debugging port ${state.port}.`); + console.log('Sign in or navigate there, then run `tracesift record start`. `tracesift record close` quits it.'); + return state; +} + +/** Quit the Chrome `record launch` started and remove what it created. */ +export async function recordClose() { + const home = getHome(); + const running = await activeRecordState(home); + if (running) throw new Error(`A recording is still running (${running.url || 'Chrome'}). Stop it with \`tracesift record stop\` before closing the browser.`); + const state = await readBrowserState(home); + if (!state) throw new Error('No browser was launched with `tracesift record launch`.'); + + if (processAlive(state.pid)) { + // Browser.close lets Chrome flush its profile; the signal is for a Chrome + // that no longer answers on its endpoint. + try { + const cdp = await connectCdp(state.webSocketDebuggerUrl); + await cdp.send('Browser.close').catch(() => undefined); + cdp.close(); + } catch { /* fall through to the signal */ } + if (!(await exited(state.pid, CLOSE_TIMEOUT_MS))) { + try { process.kill(state.pid, 'SIGTERM'); } + catch (error) { if (error?.code !== 'ESRCH') throw error; } + if (!(await exited(state.pid, CLOSE_TIMEOUT_MS))) throw new Error(`Chrome (pid ${state.pid}) did not quit. Close it by hand, then run \`tracesift record close\` again.`); + } + } + // Only a profile TraceSift created is TraceSift's to delete. + if (state.ownsProfile) await rm(state.userDataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); + await clearBrowserState(home); + console.log('Closed the launched browser.'); + return state; +} + +async function exited(pid, timeout) { + const deadline = Date.now() + timeout; + while (processAlive(pid)) { + if (Date.now() > deadline) return false; + await new Promise((resolve) => setTimeout(resolve, POLL_MS)); + } + return true; +} diff --git a/packages/cli/src/trace-export.d.ts b/packages/cli/src/trace-export.d.ts new file mode 100644 index 0000000..c7e8481 --- /dev/null +++ b/packages/cli/src/trace-export.d.ts @@ -0,0 +1,37 @@ +export interface TraceExportMainFrame { + id: string; + url: string; + name: string; +} + +export interface TraceMarkerLocation { + pid: number; + tid: number; + ts: number; +} + +export interface TraceExportOptions { + /** Path to the raw trace Chrome streamed over IO.read. */ + spool: string; + /** Final `.json.gz` path; written atomically through a sibling temporary. */ + destination: string; + /** Enhanced-trace `metadata` object, serialized verbatim. */ + metadata: Record; + mainFrame?: TraceExportMainFrame; + /** Used when the main frame reported no URL of its own. */ + fallbackUrl?: string; + /** Renderer-main marker name recorded at `Tracing.start`. */ + traceMarker?: string; +} + +export function copyTraceEvents(spool: string, output: NodeJS.WritableStream): Promise; + +export function inspectTraceMetadata(spool: string, traceMarker: string): Promise<{ + hasInspectorMetadata: boolean; + marker?: TraceMarkerLocation; +}>; + +export function writeTraceExport(options: TraceExportOptions): Promise<{ + sizeBytes: number; + eventCount: number; +}>; diff --git a/packages/cli/src/trace-export.js b/packages/cli/src/trace-export.js new file mode 100644 index 0000000..961f6a7 --- /dev/null +++ b/packages/cli/src/trace-export.js @@ -0,0 +1,266 @@ +import { randomUUID } from 'node:crypto'; +import { createReadStream, createWriteStream } from 'node:fs'; +import { rename, rm, stat } from 'node:fs/promises'; +import { finished } from 'node:stream/promises'; +import { createGzip } from 'node:zlib'; + +const MAX_TRACE_PREFIX_BYTES = 1024 * 1024; +const MAX_INSPECTED_EVENT_BYTES = 512 * 1024; + +/** @typedef {{ id: string, url: string, name: string }} MainFrame */ +/** @typedef {{ pid: number, tid: number, ts: number }} TraceMarkerLocation */ + +async function writeWithBackpressure(stream, chunk) { + if (!stream.write(chunk)) await new Promise((resolveDrain) => stream.once('drain', resolveDrain)); +} + +/** + * Locate the opening bracket of the trace-event array in a spooled prefix. + * + * The stream can be either a bare trace-event array or Chrome's usual + * {"traceEvents":[...]} object. + */ +function traceEventsOpening(text) { + const first = text.search(/\S/); + if (first >= 0 && text[first] === '[') return first; + const marker = text.indexOf('"traceEvents"'); + return marker >= 0 ? text.indexOf('[', marker + 13) : -1; +} + +/** + * Copy only the traceEvents array body from Chrome's JSON trace stream. + * + * ReturnAsStream still produces one valid JSON document. We never parse or + * retain its events: this small byte-level state machine locates the array and + * streams its contents into the enhanced-trace wrapper. JSON punctuation is + * ASCII, so scanning bytes remains correct across UTF-8 and input boundaries. + * + * @param {string} spool + * @param {NodeJS.WritableStream} output + * @returns {Promise} the number of events copied + */ +export async function copyTraceEvents(spool, output) { + let prefix = Buffer.alloc(0); + let started = false; + let ended = false; + let depth = 0; + let inString = false; + let escaped = false; + let objectDepth = 0; + let eventCount = 0; + + const copyArrayBytes = async (bytes) => { + const sliceStart = 0; + for (let index = 0; index < bytes.length; index += 1) { + const byte = bytes[index]; + if (inString) { + if (escaped) escaped = false; + else if (byte === 0x5c) escaped = true; + else if (byte === 0x22) inString = false; + continue; + } + if (byte === 0x22) inString = true; + else if (byte === 0x5b) depth += 1; + else if (byte === 0x7b) { + if (depth === 1 && objectDepth === 0) eventCount += 1; + objectDepth += 1; + } + else if (byte === 0x7d) objectDepth -= 1; + else if (byte === 0x5d) { + depth -= 1; + if (depth === 0) { + if (index > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart, index)); + ended = true; + return; + } + } + } + if (bytes.length > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart)); + }; + + for await (const value of createReadStream(spool)) { + if (ended) break; + let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); + if (!started) { + prefix = Buffer.concat([prefix, chunk]); + if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) throw new Error('Chrome trace is missing a traceEvents array near its start.'); + const text = prefix.toString('utf8'); + const opening = traceEventsOpening(text); + if (opening < 0) continue; + chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), 'utf8')); + prefix = Buffer.alloc(0); + started = true; + depth = 1; + } + await copyArrayBytes(chunk); + } + if (!started || !ended || inString || depth !== 0 || objectDepth !== 0) throw new Error('Chrome returned an incomplete trace stream.'); + return eventCount; +} + +/** + * Does this event actually identify the frames the trace belongs to? + * + * The name alone is not enough. Tracing started on the browser target before + * any navigation emits a TracingStartedInBrowser whose args are empty, and + * treating that as metadata would suppress the rebuilt record and leave the + * export with no frame information at all. + */ +function describesFrames(event) { + const name = String(event.name); + if (name === 'CpuProfile' || name === 'TracingStartedInPage') return true; + if (name !== 'TracingStartedInBrowser') return false; + const frames = event.args?.data?.frames; + return Array.isArray(frames) && frames.length > 0; +} + +/** + * Scan the spooled trace for inspector metadata and the renderer-main marker. + * + * @param {string} spool + * @param {string} traceMarker + * @returns {Promise<{ hasInspectorMetadata: boolean, marker?: TraceMarkerLocation }>} + */ +export async function inspectTraceMetadata(spool, traceMarker) { + let prefix = Buffer.alloc(0); + let started = false; + let depth = 0; + let objectDepth = 0; + let inString = false; + let escaped = false; + let eventParts = []; + let eventBytes = 0; + let eventOverflow = false; + let capturingEvent = false; + let hasInspectorMetadata = false; + + const inspectEvent = () => { + if (eventOverflow) return undefined; + try { + const event = JSON.parse(Buffer.concat(eventParts, eventBytes).toString('utf8')); + if (describesFrames(event)) hasInspectorMetadata = true; + if (event.name === traceMarker && typeof event.pid === 'number' && typeof event.tid === 'number' && typeof event.ts === 'number' && Number.isFinite(event.pid) && Number.isFinite(event.tid) && Number.isFinite(event.ts)) { + return { pid: Number(event.pid), tid: Number(event.tid), ts: Number(event.ts) }; + } + } catch { /* A malformed event is rejected later by the full stream copier. */ } + return undefined; + }; + + for await (const value of createReadStream(spool)) { + let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); + if (!started) { + prefix = Buffer.concat([prefix, chunk]); + if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) break; + const text = prefix.toString('utf8'); + const opening = traceEventsOpening(text); + if (opening < 0) continue; + chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), 'utf8')); + prefix = Buffer.alloc(0); + started = true; + depth = 1; + } + + let eventStart = capturingEvent ? 0 : -1; + for (let index = 0; index < chunk.length; index += 1) { + const byte = chunk[index]; + if (inString) { + if (escaped) escaped = false; + else if (byte === 0x5c) escaped = true; + else if (byte === 0x22) inString = false; + } else if (byte === 0x22) inString = true; + else if (byte === 0x5b) depth += 1; + else if (byte === 0x5d) depth -= 1; + else if (byte === 0x7b) { + if (depth === 1 && objectDepth === 0) { + eventStart = index; + eventParts = []; + eventBytes = 0; + eventOverflow = false; + capturingEvent = true; + } + objectDepth += 1; + } else if (byte === 0x7d) { + objectDepth -= 1; + if (depth === 1 && objectDepth === 0 && eventStart >= 0) { + const part = chunk.subarray(eventStart, index + 1); + eventBytes += part.byteLength; + if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); + else eventOverflow = true; + const marker = inspectEvent(); + if (marker) return { hasInspectorMetadata, marker }; + eventStart = -1; + capturingEvent = false; + } + } + } + if (eventStart >= 0) { + const part = chunk.subarray(eventStart); + eventBytes += part.byteLength; + if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); + else eventOverflow = true; + } + } + return { hasInspectorMetadata }; +} + +/** + * Chrome 156+ intentionally removes browser-process metadata from traces + * started over the debugger protocol. When the trace carries no inspector + * metadata of its own, rebuild the equivalent frame metadata from the + * renderer-main marker the recorder left behind. + */ +function syntheticFrameMetadata(traceMetadata, mainFrame, fallbackUrl) { + if (traceMetadata.hasInspectorMetadata || !traceMetadata.marker || !mainFrame) return undefined; + return { + name: 'TracingStartedInBrowser', + cat: 'disabled-by-default-devtools.timeline', + ph: 'I', + s: 't', + pid: traceMetadata.marker.pid, + tid: traceMetadata.marker.tid, + ts: traceMetadata.marker.ts, + args: { data: { persistentIds: true, frames: [{ + frame: mainFrame.id, + url: mainFrame.url || fallbackUrl || '', + name: mainFrame.name, + processId: traceMetadata.marker.pid, + isOutermostMainFrame: true, + isInPrimaryMainFrame: true, + }] } }, + }; +} + +/** + * Write a spooled Chrome trace out as a gzipped enhanced-trace document. + * + * @param {{ + * spool: string, + * destination: string, + * metadata: Record, + * mainFrame?: MainFrame, + * fallbackUrl?: string, + * traceMarker?: string, + * }} options + * @returns {Promise<{ sizeBytes: number, eventCount: number }>} + */ +export async function writeTraceExport(options) { + const { spool, destination, metadata, mainFrame, fallbackUrl, traceMarker } = options; + const temporary = `${destination}.${randomUUID()}.tmp`; + const output = createWriteStream(temporary, { flags: 'wx', mode: 0o600 }); + const gzip = createGzip({ level: 6 }); + gzip.pipe(output); + const traceMetadata = traceMarker ? await inspectTraceMetadata(spool, traceMarker) : { hasInspectorMetadata: false }; + const synthetic = syntheticFrameMetadata(traceMetadata, mainFrame, fallbackUrl); + try { + gzip.write(`{"metadata":${JSON.stringify(metadata)},"traceEvents":[`); + if (synthetic) gzip.write(`${JSON.stringify(synthetic)},`); + const eventCount = await copyTraceEvents(spool, gzip); + gzip.end(']}'); + await finished(output); + await rename(temporary, destination); + const info = await stat(destination); + return { sizeBytes: info.size, eventCount: eventCount + (synthetic ? 1 : 0) }; + } finally { + await rm(temporary, { force: true }); + } +} diff --git a/packages/cli/test/cdp.test.js b/packages/cli/test/cdp.test.js new file mode 100644 index 0000000..92a7ee6 --- /dev/null +++ b/packages/cli/test/cdp.test.js @@ -0,0 +1,130 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; + +import { connectCdp, readProtocolStream } from '../src/cdp.js'; + +/** A WebSocket stand-in that records what the client sends and replays replies. */ +function fakeSocket() { + const handlers = new Map(); + const sent = []; + return { + readyState: 0, + sent, + addEventListener(type, handler, options) { + const list = handlers.get(type) ?? []; + list.push({ handler, once: Boolean(options?.once) }); + handlers.set(type, list); + }, + responder: null, + send(data) { + const message = JSON.parse(data); + sent.push(message); + // Reply on a later turn, as a real socket would, and only to what was + // actually asked: guessing ids makes the test race the client. + if (this.responder) queueMicrotask(() => this.reply({ id: message.id, ...this.responder(message) })); + }, + close() { this.readyState = 3; }, + emit(type, event) { + const list = handlers.get(type) ?? []; + handlers.set(type, list.filter((entry) => !entry.once)); + for (const { handler } of list) handler(event); + }, + open() { this.readyState = 1; this.emit('open', {}); }, + reply(message) { this.emit('message', { data: JSON.stringify(message) }); }, + }; +} + +async function connected() { + const socket = fakeSocket(); + const pending = connectCdp('ws://127.0.0.1:0/devtools/browser/x', { createSocket: () => socket }); + socket.open(); + return { socket, cdp: await pending }; +} + +test('a command resolves with the result that carries its id', async () => { + const { socket, cdp } = await connected(); + const first = cdp.send('Target.getTargets'); + const second = cdp.send('Page.enable', {}, 'SESSION-1'); + + assert.deepEqual(socket.sent[0], { id: 1, method: 'Target.getTargets', params: {} }); + assert.deepEqual(socket.sent[1], { id: 2, method: 'Page.enable', params: {}, sessionId: 'SESSION-1' }); + + // Replies arrive out of order; each must reach its own caller. + socket.reply({ id: 2, result: { ok: true } }); + socket.reply({ id: 1, result: { targetInfos: [] } }); + assert.deepEqual(await second, { ok: true }); + assert.deepEqual(await first, { targetInfos: [] }); +}); + +test('a protocol error rejects with the method that failed', async () => { + const { socket, cdp } = await connected(); + const pending = cdp.send('Tracing.start'); + socket.reply({ id: 1, error: { message: 'Tracing is already started' } }); + await assert.rejects(pending, /Tracing\.start failed: Tracing is already started/); +}); + +test('events reach listeners with their session, and unsubscribing stops them', async () => { + const { socket, cdp } = await connected(); + const seen = []; + const off = cdp.on((method, params, sessionId) => seen.push([method, params.scriptId, sessionId])); + + socket.reply({ method: 'Debugger.scriptParsed', params: { scriptId: '7' }, sessionId: 'CHILD-1' }); + socket.reply({ method: 'Tracing.bufferUsage', params: { percentFull: 0.5 } }); + off(); + socket.reply({ method: 'Debugger.scriptParsed', params: { scriptId: '8' } }); + + assert.deepEqual(seen, [['Debugger.scriptParsed', '7', 'CHILD-1'], ['Tracing.bufferUsage', undefined, undefined]]); +}); + +test('a listener that throws does not stop the others', async () => { + const { socket, cdp } = await connected(); + const seen = []; + cdp.on(() => { throw new Error('listener blew up'); }); + cdp.on((method) => seen.push(method)); + socket.reply({ method: 'Tracing.tracingComplete', params: {} }); + assert.deepEqual(seen, ['Tracing.tracingComplete']); +}); + +test('a dropped connection rejects everything still in flight', async () => { + const { socket, cdp } = await connected(); + const pending = cdp.send('Tracing.end'); + socket.emit('close', { code: 1006, reason: 'abnormal closure' }); + await assert.rejects(pending, /abnormal closure \(code 1006\)/); + await assert.rejects(cdp.send('Tracing.end'), /abnormal closure/); + assert.equal(cdp.closed, true); +}); + +test('connecting fails when Chrome closes the socket instead of opening it', async () => { + const socket = fakeSocket(); + const pending = connectCdp('ws://127.0.0.1:0/x', { createSocket: () => socket }); + socket.emit('close', { code: 1002, reason: 'protocol error' }); + await assert.rejects(pending, /refused the debugging connection: protocol error/); +}); + +test('a stream is read to EOF and closed, decoding base64 chunks', async () => { + const { socket, cdp } = await connected(); + const reads = [ + { data: Buffer.from('{"traceEvents":[').toString('base64'), base64Encoded: true, eof: false }, + { data: '{"name":"A"}]}', eof: true }, + ]; + socket.responder = (message) => ({ result: message.method === 'IO.read' ? reads.shift() : {} }); + + const chunks = []; + await readProtocolStream(cdp, 'HANDLE-1', { onChunk: (bytes) => { chunks.push(Buffer.from(bytes).toString('utf8')); } }); + + assert.equal(chunks.join(''), '{"traceEvents":[{"name":"A"}]}'); + assert.deepEqual(socket.sent.at(-1), { id: 3, method: 'IO.close', params: { handle: 'HANDLE-1' } }); +}); + +test('a stream read without onChunk returns its text', async () => { + const { socket, cdp } = await connected(); + socket.responder = (message) => ({ result: message.method === 'IO.read' ? { data: '{"version":3}', eof: true } : {} }); + assert.equal(await readProtocolStream(cdp, 'HANDLE-3'), '{"version":3}'); +}); + +test('a stream that outgrows its limit is rejected and still closed', async () => { + const { socket, cdp } = await connected(); + socket.responder = (message) => ({ result: message.method === 'IO.read' ? { data: 'far too much data', eof: false } : {} }); + await assert.rejects(readProtocolStream(cdp, 'HANDLE-2', { limitBytes: 4 }), /exceeded its retention limit/); + assert.equal(socket.sent.at(-1).method, 'IO.close'); +}); diff --git a/packages/cli/test/pack.test.js b/packages/cli/test/pack.test.js index 9e62499..04004e7 100644 --- a/packages/cli/test/pack.test.js +++ b/packages/cli/test/pack.test.js @@ -44,8 +44,10 @@ test('packed artifact contains executable and shared exports, runnable outside r assert.equal(await readFile(join(modules, '@callstack/tracesift/README.md'), 'utf8'), await readFile(repositoryReadme, 'utf8')); assert.equal(await readFile(join(modules, '@callstack/tracesift/LICENSE'), 'utf8'), await readFile(repositoryLicense, 'utf8')); assert.equal(pkg.license, 'MIT'); - assert.deepEqual(Object.keys(pkg.exports).sort(), ['./bootstrap', './config', './models', './oauth', './runtime']); + assert.deepEqual(Object.keys(pkg.exports).sort(), ['./bootstrap', './config', './models', './oauth', './runtime', './trace-export']); + // The web app imports the exporter from the published package, so its types must ship with it. + assert(packed.files.some(file => file.path === 'src/trace-export.d.ts')); const output = execFileSync(process.execPath, [join(modules, '@callstack/tracesift/src/cli.js'), '--help'], { cwd: temp, encoding: 'utf8' }); assert.match(output, /tracesift init/); - execFileSync(process.execPath, ['--input-type=module', '-e', "import '@callstack/tracesift/config'; import '@callstack/tracesift/models'; import '@callstack/tracesift/runtime';"], { cwd: temp }); + execFileSync(process.execPath, ['--input-type=module', '-e', "import '@callstack/tracesift/config'; import '@callstack/tracesift/models'; import '@callstack/tracesift/runtime'; import '@callstack/tracesift/trace-export';"], { cwd: temp }); }); diff --git a/packages/cli/test/record.test.js b/packages/cli/test/record.test.js new file mode 100644 index 0000000..9e42a87 --- /dev/null +++ b/packages/cli/test/record.test.js @@ -0,0 +1,250 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { createServer } from 'node:http'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { gunzipSync } from 'node:zlib'; + +import { assertRecordOptions, parseDuration, recordClose } from '../src/record.js'; +import { createIngestSink, createLocalSink } from '../src/record-sink.js'; +import { + activeRecordState, clearBrowserState, clearRecordState, liveBrowserState, readBrowserState, readRecordState, writeBrowserState, writeRecordState, +} from '../src/record-state.js'; + +const TARGET = { tabId: 0, title: 'Example', url: 'https://example.com/' }; + +async function temporaryHome(t) { + const home = await mkdtemp(join(tmpdir(), 'tracesift-record-')); + t.after(() => rm(home, { recursive: true, force: true })); + return home; +} + +/** Stand in for the capture endpoints the web app serves on loopback. */ +async function captureServer(t, { token = 'upload-token' } = {}) { + const calls = []; + let stopRequested = false; + const server = createServer((request, response) => { + const chunks = []; + request.on('data', (chunk) => chunks.push(chunk)); + request.on('end', () => { + const body = Buffer.concat(chunks); + const url = new URL(request.url, 'http://127.0.0.1'); + calls.push({ + method: request.method, + path: url.pathname, + search: url.search, + authorization: request.headers.authorization, + contentType: request.headers['content-type'], + body, + }); + const json = (value, status = 200) => { + response.writeHead(status, { 'Content-Type': 'application/json' }); + response.end(JSON.stringify(value)); + }; + if (url.pathname === '/api/captures' && request.method === 'POST') { + return json({ capture: { id: 'CAPTURE-1', state: 'pending' }, uploadToken: token }, 201); + } + if (url.pathname === '/api/captures/CAPTURE-1' && request.method === 'GET') { + return json({ capture: { id: 'CAPTURE-1', state: stopRequested ? 'stop_requested' : 'recording' } }); + } + if (url.pathname.endsWith('/ingest/raw')) { + if (request.headers.authorization !== `Bearer ${token}`) return json({ error: 'Capture authorization failed.' }, 401); + return json({ capture: { id: 'CAPTURE-1' } }); + } + if (url.pathname.endsWith('/ingest/finalize')) { + return json({ capture: { id: 'CAPTURE-1', export: { fileName: 'Trace-X.json.gz', sizeBytes: 42 }, eventCount: 7, warnings: ['minified'] } }); + } + if (url.pathname.endsWith('/ingest/status')) return json({ capture: { id: 'CAPTURE-1' } }); + return json({ error: 'Not found.' }, 404); + }); + }); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise((resolve) => server.close(resolve))); + return { + calls, + baseUrl: `http://127.0.0.1:${server.address().port}`, + requestStop() { stopRequested = true; }, + }; +} + +test('durations accept the units a harness is likely to pass', () => { + assert.equal(parseDuration(undefined), undefined); + assert.equal(parseDuration('30'), 30_000); + assert.equal(parseDuration('30s'), 30_000); + assert.equal(parseDuration('500ms'), 500); + assert.equal(parseDuration('2m'), 120_000); + assert.equal(parseDuration(' 1.5s '), 1500); + assert.throws(() => parseDuration('soon'), /30s, 500ms or 2m/); + assert.throws(() => parseDuration('0s'), /between 1ms and 1h/); + assert.throws(() => parseDuration('2h'), /30s, 500ms or 2m/); + assert.throws(() => parseDuration('120m'), /between 1ms and 1h/); +}); + +test('record state survives a round trip and is scoped to its own recorder', async (t) => { + const home = await temporaryHome(t); + assert.equal(await readRecordState(home), null); + + await writeRecordState(home, { apiVersion: 1, pid: process.pid, mode: 'local', state: 'recording', startedAt: Date.now(), url: 'https://example.com/' }); + assert.equal((await activeRecordState(home)).state, 'recording'); + + // Another recorder's state must not be removed by this process. + await clearRecordState(home, process.pid + 1); + assert.notEqual(await readRecordState(home), null); + await clearRecordState(home, process.pid); + assert.equal(await readRecordState(home), null); +}); + +test('a recorder that died leaves no active recording behind', async (t) => { + const home = await temporaryHome(t); + // PID 1 exists but is not ours; a PID that cannot exist stands in for a dead recorder. + await writeRecordState(home, { apiVersion: 1, pid: 2 ** 31 - 1, mode: 'local', state: 'recording', startedAt: Date.now(), url: '' }); + assert.equal(await activeRecordState(home), null); +}); + +test('a finished recording is not treated as active', async (t) => { + const home = await temporaryHome(t); + await writeRecordState(home, { apiVersion: 1, pid: process.pid, mode: 'local', state: 'captured', startedAt: Date.now(), url: '' }); + assert.equal(await activeRecordState(home), null); + assert.equal((await readRecordState(home)).state, 'captured'); +}); + +test('state written by a future version is ignored rather than misread', async (t) => { + const home = await temporaryHome(t); + await writeRecordState(home, { apiVersion: 2, pid: process.pid, mode: 'local', state: 'recording', startedAt: 0, url: '' }); + assert.equal(await readRecordState(home), null); +}); + +test('the ingest sink speaks the same capture protocol as the extension', async (t) => { + const server = await captureServer(t); + const sink = await createIngestSink({ baseUrl: server.baseUrl }, TARGET, 'Example'); + assert.equal(sink.mode, 'ingest'); + assert.equal(sink.captureId, 'CAPTURE-1'); + + await sink.status({ state: 'recording' }); + await sink.chunk(Buffer.from('{"traceEvents":[')); + await sink.chunk(Buffer.from(']}')); + const result = await sink.finalize({ stopReason: 'manual', scripts: [], sourceMaps: [] }); + + assert.deepEqual(result, { fileName: 'Trace-X.json.gz', sizeBytes: 42, eventCount: 7, warnings: ['minified'] }); + + const create = server.calls.find((call) => call.path === '/api/captures'); + assert.deepEqual(JSON.parse(create.body.toString('utf8')), { title: 'Example', target: TARGET }); + + const raw = server.calls.filter((call) => call.path.endsWith('/ingest/raw')); + assert.deepEqual(raw.map((call) => call.search), ['?sequence=0', '?sequence=1'], 'chunks are numbered in order'); + assert.equal(raw[0].contentType, 'application/octet-stream'); + assert.equal(raw[0].authorization, 'Bearer upload-token'); + assert.equal(Buffer.concat(raw.map((call) => call.body)).toString('utf8'), '{"traceEvents":[]}'); +}); + +test('the ingest sink reports the web app’s Stop button', async (t) => { + const server = await captureServer(t); + const sink = await createIngestSink({ baseUrl: server.baseUrl }, TARGET, 'Example'); + assert.equal(await sink.stopRequested(), false); + server.requestStop(); + assert.equal(await sink.stopRequested(), true); +}); + +test('an ingest failure surfaces the server’s own message', async (t) => { + const server = createServer((request, response) => { + response.writeHead(409, { 'Content-Type': 'application/json' }); + response.end(JSON.stringify({ error: 'A capture is already active for “Example”.' })); + }); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise((resolve) => server.close(resolve))); + const baseUrl = `http://127.0.0.1:${server.address().port}`; + await assert.rejects(createIngestSink({ baseUrl }, TARGET, 'Example'), /A capture is already active/); +}); + +test('the local sink writes a gzipped enhanced trace without a server', async (t) => { + const home = await temporaryHome(t); + const sink = await createLocalSink(home, TARGET); + assert.equal(sink.mode, 'local'); + assert.ok(sink.directory.startsWith(join(home, 'recordings'))); + assert.equal(await sink.stopRequested(), false, 'nothing can request a stop through a file'); + + await sink.chunk(Buffer.from('{"traceEvents":[{"name":"RunTask","ph":"X"}')); + await sink.chunk(Buffer.from(']}')); + const result = await sink.finalize({ scripts: [{ scriptId: '1', url: 'https://example.com/app.js' }], sourceMaps: [], warnings: ['minified'] }); + + assert.equal(result.eventCount, 1); + assert.deepEqual(result.warnings, ['minified']); + const document = JSON.parse(gunzipSync(await readFile(result.path)).toString('utf8')); + assert.equal(document.metadata.enhancedTraceVersion, 1); + assert.equal(document.metadata.traceSift.captureId, sink.captureId); + assert.deepEqual(document.metadata.traceSift.target, TARGET); + assert.equal(document.metadata.traceSift.scripts[0].url, 'https://example.com/app.js'); + assert.equal(document.traceEvents[0].name, 'RunTask'); +}); + +test('the local sink honours an explicit output path', async (t) => { + const home = await temporaryHome(t); + const destination = join(home, 'nested', 'my-trace.json.gz'); + const sink = await createLocalSink(home, TARGET, { out: destination }); + await sink.chunk(Buffer.from('{"traceEvents":[{"name":"A"}]}')); + const result = await sink.finalize({}); + assert.equal(result.path, destination); + assert.equal(result.fileName, 'my-trace.json.gz'); + assert.ok(gunzipSync(await readFile(destination)).length > 0); +}); + +test('browser state round-trips and goes stale when its Chrome is gone', async (t) => { + const home = await temporaryHome(t); + assert.equal(await readBrowserState(home), null); + assert.equal(await liveBrowserState(home), null); + + const state = { + apiVersion: 1, pid: process.pid, webSocketDebuggerUrl: 'ws://127.0.0.1:9222/devtools/browser/abc', port: 9222, + userDataDir: join(home, 'chrome-profiles', 'browser-1'), ownsProfile: true, url: 'https://example.com/', startedAt: 1, + }; + await writeBrowserState(home, state); + assert.deepEqual(await readBrowserState(home), state); + assert.deepEqual(await liveBrowserState(home), state); + + // A pid that no longer exists: the file survives, the browser does not. + const dead = spawnSync(process.execPath, ['-e', '']).pid; + await writeBrowserState(home, { ...state, pid: dead }); + assert.equal((await readBrowserState(home)).pid, dead); + assert.equal(await liveBrowserState(home), null); + + await writeFile(join(home, 'browser.json'), JSON.stringify({ ...state, apiVersion: 2 })); + assert.equal(await readBrowserState(home), null); + await clearBrowserState(home); + await clearBrowserState(home); + assert.equal(await readBrowserState(home), null); +}); + +test('close refuses while a recording is active and keeps the launched browser', async (t) => { + const home = await temporaryHome(t); + const previous = process.env.TRACE_SIFT_HOME; + process.env.TRACE_SIFT_HOME = home; + t.after(() => { if (previous === undefined) delete process.env.TRACE_SIFT_HOME; else process.env.TRACE_SIFT_HOME = previous; }); + await writeBrowserState(home, { + apiVersion: 1, pid: process.pid, webSocketDebuggerUrl: 'ws://127.0.0.1:1/devtools/browser/x', port: 1, + userDataDir: join(home, 'profile'), ownsProfile: true, url: '', startedAt: 1, + }); + await writeRecordState(home, { apiVersion: 1, pid: process.pid, mode: 'local', state: 'recording', startedAt: 1, url: 'https://example.com/' }); + await assert.rejects(recordClose(), /still running.*record stop/); + assert.equal((await readBrowserState(home)).pid, process.pid); + + await clearRecordState(home); + await clearBrowserState(home); + await assert.rejects(recordClose(), /No browser was launched/); +}); + +test('record options are rejected for the subcommands that would ignore them', () => { + assert.doesNotThrow(() => assertRecordOptions('record', 'start', { url: 'x', duration: '5s', sink: 'local', out: 'a', headless: true })); + assert.doesNotThrow(() => assertRecordOptions('record', 'launch', { url: 'x', chrome: 'c', 'user-data-dir': 'd', headless: true })); + assert.doesNotThrow(() => assertRecordOptions('record', 'close', {})); + for (const option of ['duration', 'sink', 'out']) { + assert.throws(() => assertRecordOptions('record', 'launch', { [option]: 'x' }), new RegExp(`--${option} is not supported by tracesift record launch`)); + } + for (const subcommand of ['stop', 'status', 'close']) { + assert.throws(() => assertRecordOptions('record', subcommand, { url: 'x' }), /--url is not supported/); + assert.throws(() => assertRecordOptions('record', subcommand, { headless: true }), /--headless is not supported/); + } + assert.throws(() => assertRecordOptions('explore', undefined, { url: 'x' }), /only supported by tracesift record/); + assert.throws(() => assertRecordOptions('start', undefined, { sink: 'local' }), /only supported by tracesift record/); +}); diff --git a/packages/cli/test/trace-export.test.js b/packages/cli/test/trace-export.test.js new file mode 100644 index 0000000..eb531b4 --- /dev/null +++ b/packages/cli/test/trace-export.test.js @@ -0,0 +1,146 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { gunzipSync } from 'node:zlib'; + +import { copyTraceEvents, inspectTraceMetadata, writeTraceExport } from '../src/trace-export.js'; + +const MARKER = '__tracesift_main_test'; + +async function temporaryDirectory(t) { + const directory = await mkdtemp(join(tmpdir(), 'tracesift-export-')); + t.after(() => rm(directory, { recursive: true, force: true })); + return directory; +} + +async function spoolFile(directory, trace) { + const path = join(directory, 'trace.spool'); + await writeFile(path, typeof trace === 'string' ? trace : JSON.stringify(trace)); + return path; +} + +function markerEvent(overrides = {}) { + return { name: MARKER, cat: 'blink.user_timing', ph: 'R', pid: 7, tid: 11, ts: 1234, ...overrides }; +} + +async function exported(directory, spool, options = {}) { + const destination = join(directory, 'Trace.json.gz'); + const written = await writeTraceExport({ spool, destination, metadata: { enhancedTraceVersion: 1 }, ...options }); + return { written, document: JSON.parse(gunzipSync(await readFile(destination)).toString('utf8')) }; +} + +test('a spooled trace is rewritten as a gzipped enhanced trace', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, { traceEvents: [markerEvent(), { name: 'RunTask', ph: 'X', pid: 7, tid: 11, ts: 2000, dur: 5 }] }); + const { written, document } = await exported(directory, spool); + + assert.equal(written.eventCount, 2); + assert.ok(written.sizeBytes > 0); + assert.equal(document.metadata.enhancedTraceVersion, 1); + assert.equal(document.traceEvents.length, 2); + assert.equal(document.traceEvents[1].name, 'RunTask'); +}); + +test('a bare trace-event array is accepted as well as Chrome’s wrapper object', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, [markerEvent()]); + const { document } = await exported(directory, spool); + assert.equal(document.traceEvents.length, 1); +}); + +test('frame metadata is rebuilt only when Chrome withheld its own', async (t) => { + const directory = await temporaryDirectory(t); + const mainFrame = { id: 'FRAME-1', url: '', name: 'main' }; + + const withoutSpool = await spoolFile(directory, { traceEvents: [markerEvent()] }); + const rebuilt = await exported(directory, withoutSpool, { mainFrame, traceMarker: MARKER, fallbackUrl: 'https://example.com/app' }); + const synthetic = rebuilt.document.traceEvents[0]; + assert.equal(synthetic.name, 'TracingStartedInBrowser'); + assert.equal(synthetic.pid, 7); + assert.equal(synthetic.ts, 1234); + // The frame reported no URL of its own, so the recorded target stands in. + assert.equal(synthetic.args.data.frames[0].url, 'https://example.com/app'); + assert.equal(rebuilt.written.eventCount, 2, 'the injected event is counted'); + + await rm(join(directory, 'Trace.json.gz')); + const withSpool = await spoolFile(join(directory), { traceEvents: [ + { name: 'TracingStartedInBrowser', ph: 'I', pid: 7, tid: 11, ts: 1, args: { data: { persistentIds: true, frames: [{ frame: 'FRAME-0', url: 'https://example.com/' }] } } }, + markerEvent(), + ] }); + const untouched = await exported(directory, withSpool, { mainFrame, traceMarker: MARKER }); + assert.equal(untouched.document.traceEvents.length, 2); + assert.equal(untouched.document.traceEvents[0].name, 'TracingStartedInBrowser'); + assert.equal(untouched.document.traceEvents[0].ts, 1, 'Chrome’s own metadata is preserved'); +}); + +test('a TracingStartedInBrowser that names no frames does not suppress the rebuilt one', async (t) => { + const directory = await temporaryDirectory(t); + // Tracing started before any navigation emits this empty marker. Trusting + // its name alone would leave the export with no frame information at all. + const spool = await spoolFile(directory, { traceEvents: [ + { name: 'TracingStartedInBrowser', cat: 'disabled-by-default-devtools.timeline', ph: 'I', args: {}, pid: 1, tid: 2, ts: 5 }, + markerEvent(), + ] }); + const { document } = await exported(directory, spool, { + mainFrame: { id: 'FRAME-1', url: 'https://example.com/', name: '' }, + traceMarker: MARKER, + }); + const rebuilt = document.traceEvents[0]; + assert.deepEqual(rebuilt.args.data.frames[0].frame, 'FRAME-1'); + assert.equal(rebuilt.ts, 1234, 'the rebuilt event sits at the renderer-main marker'); +}); + +test('JSON punctuation inside strings does not confuse the event scanner', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, { traceEvents: [ + { name: 'A', args: { text: 'a ] } [ { \\" brace' } }, + { name: 'B', args: { text: '}]' } }, + ] }); + const { written, document } = await exported(directory, spool); + assert.equal(written.eventCount, 2); + assert.equal(document.traceEvents[0].args.text, 'a ] } [ { \\" brace'); + assert.equal(document.traceEvents[1].name, 'B'); +}); + +test('a truncated trace stream is rejected rather than silently exported', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, '{"traceEvents":[{"name":"A"}'); + await assert.rejects(exported(directory, spool), /incomplete trace stream/); +}); + +test('a stream without a traceEvents array is rejected', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, '{"metadata":{}}'); + await assert.rejects(exported(directory, spool), /incomplete trace stream/); +}); + +test('the marker scan reports inspector metadata and the marker location', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, { traceEvents: [markerEvent({ pid: 3, tid: 4, ts: 99 })] }); + const result = await inspectTraceMetadata(spool, MARKER); + assert.equal(result.hasInspectorMetadata, false); + assert.deepEqual(result.marker, { pid: 3, tid: 4, ts: 99 }); +}); + +test('events split across read boundaries are still copied intact', async (t) => { + const directory = await temporaryDirectory(t); + // Comfortably larger than one 64 KB read, so the scanner must carry state. + const events = Array.from({ length: 2000 }, (_, index) => ({ name: `Event${index}`, ph: 'X', pid: 7, tid: 11, ts: index, args: { payload: 'x'.repeat(64) } })); + const spool = await spoolFile(directory, { traceEvents: events }); + const { written, document } = await exported(directory, spool); + assert.equal(written.eventCount, 2000); + assert.equal(document.traceEvents.length, 2000); + assert.equal(document.traceEvents.at(-1).name, 'Event1999'); +}); + +test('copyTraceEvents streams into any writable without buffering the document', async (t) => { + const directory = await temporaryDirectory(t); + const spool = await spoolFile(directory, { traceEvents: [{ name: 'A' }, { name: 'B' }] }); + const chunks = []; + const sink = { write(chunk) { chunks.push(Buffer.from(chunk)); return true; }, once() {} }; + const count = await copyTraceEvents(spool, sink); + assert.equal(count, 2); + assert.deepEqual(JSON.parse(`[${Buffer.concat(chunks).toString('utf8')}]`), [{ name: 'A' }, { name: 'B' }]); +}); diff --git a/src/lib/capture-store.ts b/src/lib/capture-store.ts index 6c50862..cc498ad 100644 --- a/src/lib/capture-store.ts +++ b/src/lib/capture-store.ts @@ -1,5 +1,4 @@ import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto"; -import { createReadStream, createWriteStream } from "node:fs"; import { appendFile, chmod, @@ -13,8 +12,8 @@ import { } from "node:fs/promises"; import { homedir } from "node:os"; import { basename, join, resolve } from "node:path"; -import { finished } from "node:stream/promises"; -import { createGzip } from "node:zlib"; + +import { writeTraceExport } from "@callstack/tracesift/trace-export"; import { ACTIVE_CAPTURE_STATES, @@ -45,8 +44,6 @@ const CAPTURE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9 // IO.read is deliberately smaller than this limit. Keeping the server limit // close to the read size prevents either side from retaining a large request. export const MAX_RAW_CHUNK_BYTES = 1024 * 1024; -const MAX_TRACE_PREFIX_BYTES = 1024 * 1024; -const MAX_INSPECTED_EVENT_BYTES = 512 * 1024; const MAX_WARNING_LENGTH = 500; const TERMINAL_STATES = new Set(["captured", "captured_with_warnings", "failed", "interrupted"]); @@ -255,176 +252,6 @@ export async function appendCaptureRawChunk(id: string, token: string, sequence: }); } -async function writeWithBackpressure(stream: NodeJS.WritableStream, chunk: Uint8Array | string): Promise { - if (!stream.write(chunk)) await new Promise((resolveDrain) => stream.once("drain", resolveDrain)); -} - -/** - * Copy only the traceEvents array body from Chrome's JSON trace stream. - * - * ReturnAsStream still produces one valid JSON document. We never parse or - * retain its events: this small byte-level state machine locates the array and - * streams its contents into the enhanced-trace wrapper. JSON punctuation is - * ASCII, so scanning bytes remains correct across UTF-8 and input boundaries. - */ -async function copyTraceEvents(spool: string, output: NodeJS.WritableStream): Promise { - let prefix = Buffer.alloc(0); - let started = false; - let ended = false; - let depth = 0; - let inString = false; - let escaped = false; - let objectDepth = 0; - let eventCount = 0; - - const copyArrayBytes = async (bytes: Buffer): Promise => { - const sliceStart = 0; - for (let index = 0; index < bytes.length; index += 1) { - const byte = bytes[index]; - if (inString) { - if (escaped) escaped = false; - else if (byte === 0x5c) escaped = true; - else if (byte === 0x22) inString = false; - continue; - } - if (byte === 0x22) inString = true; - else if (byte === 0x5b) depth += 1; - else if (byte === 0x7b) { - if (depth === 1 && objectDepth === 0) eventCount += 1; - objectDepth += 1; - } - else if (byte === 0x7d) objectDepth -= 1; - else if (byte === 0x5d) { - depth -= 1; - if (depth === 0) { - if (index > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart, index)); - ended = true; - return; - } - } - } - if (bytes.length > sliceStart) await writeWithBackpressure(output, bytes.subarray(sliceStart)); - }; - - for await (const value of createReadStream(spool)) { - if (ended) break; - let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); - if (!started) { - prefix = Buffer.concat([prefix, chunk]); - if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) throw new Error("Chrome trace is missing a traceEvents array near its start."); - const text = prefix.toString("utf8"); - const first = text.search(/\S/); - let opening = first >= 0 && text[first] === "[" ? first : -1; - if (opening < 0) { - const marker = text.indexOf('"traceEvents"'); - if (marker >= 0) opening = text.indexOf("[", marker + 13); - } - if (opening < 0) continue; - // The stream can be either a bare trace-event array or Chrome's usual - // {"traceEvents":[...]} object. Start immediately after its outer array. - chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), "utf8")); - prefix = Buffer.alloc(0); - started = true; - depth = 1; - } - await copyArrayBytes(chunk); - } - if (!started || !ended || inString || depth !== 0 || objectDepth !== 0) throw new Error("Chrome returned an incomplete trace stream."); - return eventCount; -} - -async function inspectTraceMetadata(spool: string, traceMarker: string): Promise<{ - hasInspectorMetadata: boolean; - marker?: { pid: number; tid: number; ts: number }; -}> { - let prefix = Buffer.alloc(0); - let started = false; - let depth = 0; - let objectDepth = 0; - let inString = false; - let escaped = false; - let eventParts: Buffer[] = []; - let eventBytes = 0; - let eventOverflow = false; - let capturingEvent = false; - let hasInspectorMetadata = false; - - const inspectEvent = (): { pid: number; tid: number; ts: number } | undefined => { - if (eventOverflow) return undefined; - try { - const event = JSON.parse(Buffer.concat(eventParts, eventBytes).toString("utf8")) as Record; - if (["TracingStartedInBrowser", "TracingStartedInPage", "CpuProfile"].includes(String(event.name))) { - hasInspectorMetadata = true; - } - if (event.name === traceMarker && typeof event.pid === "number" && typeof event.tid === "number" && typeof event.ts === "number" && Number.isFinite(event.pid) && Number.isFinite(event.tid) && Number.isFinite(event.ts)) { - return { pid: Number(event.pid), tid: Number(event.tid), ts: Number(event.ts) }; - } - } catch { /* A malformed event is rejected later by the full stream copier. */ } - return undefined; - }; - - for await (const value of createReadStream(spool)) { - let chunk = Buffer.isBuffer(value) ? value : Buffer.from(value); - if (!started) { - prefix = Buffer.concat([prefix, chunk]); - if (prefix.byteLength > MAX_TRACE_PREFIX_BYTES) break; - const text = prefix.toString("utf8"); - const first = text.search(/\S/); - let opening = first >= 0 && text[first] === "[" ? first : -1; - if (opening < 0) { - const marker = text.indexOf('"traceEvents"'); - if (marker >= 0) opening = text.indexOf("[", marker + 13); - } - if (opening < 0) continue; - chunk = prefix.subarray(Buffer.byteLength(text.slice(0, opening + 1), "utf8")); - prefix = Buffer.alloc(0); - started = true; - depth = 1; - } - - let eventStart = capturingEvent ? 0 : -1; - for (let index = 0; index < chunk.length; index += 1) { - const byte = chunk[index]; - if (inString) { - if (escaped) escaped = false; - else if (byte === 0x5c) escaped = true; - else if (byte === 0x22) inString = false; - } else if (byte === 0x22) inString = true; - else if (byte === 0x5b) depth += 1; - else if (byte === 0x5d) depth -= 1; - else if (byte === 0x7b) { - if (depth === 1 && objectDepth === 0) { - eventStart = index; - eventParts = []; - eventBytes = 0; - eventOverflow = false; - capturingEvent = true; - } - objectDepth += 1; - } else if (byte === 0x7d) { - objectDepth -= 1; - if (depth === 1 && objectDepth === 0 && eventStart >= 0) { - const part = chunk.subarray(eventStart, index + 1); - eventBytes += part.byteLength; - if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); - else eventOverflow = true; - const marker = inspectEvent(); - if (marker) return { hasInspectorMetadata, marker }; - eventStart = -1; - capturingEvent = false; - } - } - } - if (eventStart >= 0) { - const part = chunk.subarray(eventStart); - eventBytes += part.byteLength; - if (eventBytes <= MAX_INSPECTED_EVENT_BYTES) eventParts.push(part); - else eventOverflow = true; - } - } - return { hasInspectorMetadata }; -} - function sourceMapBasename(value: string): string { const clean = value.split(/[?#]/)[0]; return clean.slice(clean.lastIndexOf("/") + 1); @@ -464,11 +291,6 @@ function validSourceMaps(value: CaptureSourceMap[]): CaptureSourceMap[] { async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMetadata[], sourceMaps: CaptureSourceMap[], mainFrame?: CaptureMainFrame, traceMarker?: string): Promise<{ export: { fileName: string; sizeBytes: number }; eventCount: number }> { const stamp = new Date(record.createdAt).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z"); const fileName = `Trace-${stamp}.json.gz`; - const destination = join(captureDir(record.id), fileName); - const temporary = `${destination}.${randomUUID()}.tmp`; - const output = createWriteStream(temporary, { flags: "wx", mode: 0o600 }); - const gzip = createGzip({ level: 6 }); - gzip.pipe(output); const metadata = { // DevTools' enhanced-trace schema is currently version 1. The source // rundown events in traceEvents carry script content; these retained maps @@ -482,36 +304,15 @@ async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMeta scripts, }, }; - const traceMetadata = traceMarker ? await inspectTraceMetadata(spoolPath(record.id), traceMarker) : { hasInspectorMetadata: false }; - const syntheticMetadata = !traceMetadata.hasInspectorMetadata && traceMetadata.marker && mainFrame ? { - name: "TracingStartedInBrowser", - cat: "disabled-by-default-devtools.timeline", - ph: "I", - s: "t", - pid: traceMetadata.marker.pid, - tid: traceMetadata.marker.tid, - ts: traceMetadata.marker.ts, - args: { data: { persistentIds: true, frames: [{ - frame: mainFrame.id, - url: mainFrame.url || record.target.url, - name: mainFrame.name, - processId: traceMetadata.marker.pid, - isOutermostMainFrame: true, - isInPrimaryMainFrame: true, - }] } }, - } : undefined; - try { - gzip.write(`{"metadata":${JSON.stringify(metadata)},"traceEvents":[`); - if (syntheticMetadata) gzip.write(`${JSON.stringify(syntheticMetadata)},`); - const eventCount = await copyTraceEvents(spoolPath(record.id), gzip); - gzip.end("]}"); - await finished(output); - await rename(temporary, destination); - const info = await stat(destination); - return { export: { fileName, sizeBytes: info.size }, eventCount: eventCount + (syntheticMetadata ? 1 : 0) }; - } finally { - await rm(temporary, { force: true }); - } + const written = await writeTraceExport({ + spool: spoolPath(record.id), + destination: join(captureDir(record.id), fileName), + metadata, + mainFrame, + fallbackUrl: record.target.url, + traceMarker, + }); + return { export: { fileName, sizeBytes: written.sizeBytes }, eventCount: written.eventCount }; } export async function finalizeCapture(id: string, token: string, input: { From b05e96d86805f90cccd3617b388db9be6d57965b Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Mon, 2 Nov 2026 17:10:32 +0500 Subject: [PATCH 06/10] feat: add UI controls and orchestration --- .changeset/olive-moons-attack.md | 7 ++ .changeset/olive-pugs-wonder.md | 7 ++ packages/cli/CLI.md | 2 +- packages/cli/src/record-session.js | 50 +++++++++++- packages/cli/test/record-target.test.js | 88 +++++++++++++++++++++ src/app/api/analyze/route.ts | 20 ++++- src/app/api/integration/v1/analyze/route.ts | 16 +++- src/app/page.tsx | 16 ++-- src/lib/profile-upload.ts | 60 ++++++++++++++ src/lib/react-analysis-handler.ts | 14 +++- tests/integration-api.test.mjs | 30 +++++++ tests/profile-upload.test.mjs | 64 +++++++++++++++ 12 files changed, 356 insertions(+), 18 deletions(-) create mode 100644 .changeset/olive-moons-attack.md create mode 100644 .changeset/olive-pugs-wonder.md create mode 100644 packages/cli/test/record-target.test.js create mode 100644 src/lib/profile-upload.ts create mode 100644 tests/profile-upload.test.mjs diff --git a/.changeset/olive-moons-attack.md b/.changeset/olive-moons-attack.md new file mode 100644 index 0000000..76f458e --- /dev/null +++ b/.changeset/olive-moons-attack.md @@ -0,0 +1,7 @@ +--- +"@callstack/tracesift": minor +--- + +Analyze gzipped traces, so an exported recording can be opened again. + +A trace exported from a recording — by the web app's own Export trace button or by `tracesift record` with no TraceSift running — is a `.json.gz`, and nothing could read it back: the upload pane accepted only `.json` and both analyze routes parsed the upload as text. Uploads and the Integration API's `analyze` endpoint now inflate a gzipped profile before parsing it, decided by the file's own first bytes rather than its name, and refuse one that would exceed the upload ceiling once uncompressed. diff --git a/.changeset/olive-pugs-wonder.md b/.changeset/olive-pugs-wonder.md new file mode 100644 index 0000000..1e62ccd --- /dev/null +++ b/.changeset/olive-pugs-wonder.md @@ -0,0 +1,7 @@ +--- +"@callstack/tracesift": patch +--- + +Record the tab that is on screen, not the first one Chrome lists. + +`record launch` hands the browser to a person, and signing in leaves consent popups and second tabs behind. Chrome lists a newly opened background tab first, so the recorder attached to it and produced a trace of a page nobody was looking at, with nothing to say anything had gone wrong. It now picks the visible page, which a background tab is not whichever application holds the OS focus, and uses window focus only to choose between two windows that are both showing a page. diff --git a/packages/cli/CLI.md b/packages/cli/CLI.md index 54f7bbb..b89877e 100644 --- a/packages/cli/CLI.md +++ b/packages/cli/CLI.md @@ -26,7 +26,7 @@ tracesift record close `record start` accepts `--url` to navigate once tracing is live, `--duration 30s` to stop on its own, `--headless` for an unattended run, `--chrome ` (or `CHROME_PATH`) to choose the binary, and `--user-data-dir ` to record against an existing profile — that profile must not already be open in Chrome. `record stop` ends the recording and waits for Chrome to flush; `record status` reports the last one. Only one recording runs at a time, and its state lives in `record.json` with diagnostics in `record.log`. -To profile something you had to sign in or click around to reach, open the browser first: `record launch [--url ...]` starts Chrome, leaves it running after the command returns and records its debugging endpoint in `browser.json`. Use the browser by hand, then run `record start`. With a launched browser open it attaches to that Chrome and does not navigate, so the trace covers what is already on screen; pass `--url` to navigate after tracing starts anyway. `--chrome`, `--user-data-dir` and `--headless` belong to `record launch` in that case. `record stop` leaves the launched browser open, so several profiles can come from one sign-in; `record close` quits it and deletes its profile when TraceSift created it, and refuses while a recording is running. With no launched browser, `record start` behaves as above: it starts its own Chrome, traces the page load and shuts that Chrome down afterwards. `record status` also reports a launched browser that is still open. +To profile something you had to sign in or click around to reach, open the browser first: `record launch [--url ...]` starts Chrome, leaves it running after the command returns and records its debugging endpoint in `browser.json`. Use the browser by hand, then run `record start`. With a launched browser open it attaches to that Chrome and does not navigate, so the trace covers what is already on screen; pass `--url` to navigate after tracing starts anyway. `--chrome`, `--user-data-dir` and `--headless` belong to `record launch` in that case. With several tabs open it records the one on screen rather than the first Chrome happens to list, so a consent popup left over from a sign-in does not become the recording. `record stop` leaves the launched browser open, so several profiles can come from one sign-in; `record close` quits it and deletes its profile when TraceSift created it, and refuses while a recording is running. With no launched browser, `record start` behaves as above: it starts its own Chrome, traces the page load and shuts that Chrome down afterwards. `record status` also reports a launched browser that is still open. The trace goes to a running TraceSift when `service.json` points at one, arriving in its capture list exactly as an extension capture does, so the web app's own Stop button ends a CLI recording too. With no TraceSift running it writes the same `.json.gz` under `recordings/` in the TraceSift home, or wherever `--out` says. Force either with `--sink ingest` or `--sink local`. diff --git a/packages/cli/src/record-session.js b/packages/cli/src/record-session.js index 45713a6..7f4dd9d 100644 --- a/packages/cli/src/record-session.js +++ b/packages/cli/src/record-session.js @@ -101,13 +101,59 @@ async function mainFrameOf(cdp, sessionId) { } catch { return undefined; } } +/** + * Which of several open pages is the recording about? + * + * One tab needs no choosing. But `record launch` hands the browser to a person, + * and signing in opens consent popups and second tabs, so the first target + * Chrome happens to list is often not the one on screen — and recording the + * wrong tab produces a trace of nothing with no sign that anything went wrong. + * + * `visibilityState` is the signal that survives this flow: a background tab is + * `hidden` whichever application holds the OS focus, so it still tells the tabs + * apart when the recording was started from a terminal or from Codex rather + * than from Chrome itself. `document.hasFocus()` only breaks ties between two + * windows that are both showing a page. + * + * @param {{ send: (method: string, params?: object, sessionId?: string) => Promise }} cdp + * @param {{ targetId: string, url?: string }[]} pages + */ +export async function selectPageTarget(cdp, pages) { + if (pages.length < 2) return pages[0]; + let best; + for (const page of pages) { + let sessionId; + try { + ({ sessionId } = await cdp.send('Target.attachToTarget', { targetId: page.targetId, flatten: true })); + const { result } = await cdp.send('Runtime.evaluate', { + expression: '({ visible: document.visibilityState === "visible", focused: document.hasFocus() })', + returnByValue: true, + }, sessionId); + const value = result?.value ?? {}; + const rank = (value.visible ? 2 : 0) + (value.focused ? 1 : 0); + // Ties keep the earlier page, so Chrome's own order still decides when + // nothing distinguishes them. + if (!best || rank > best.rank) best = { rank, page }; + } catch { + // A page that cannot be probed is still a page; it just cannot argue for + // itself against one that answered. + if (!best) best = { rank: -1, page }; + } finally { + // Probing must leave no session behind: the caller attaches to the page + // it chose, and a stray session would keep receiving its events. + if (sessionId) await cdp.send('Target.detachFromTarget', { sessionId }).catch(() => undefined); + } + } + return best?.page ?? pages[0]; +} + /** Wait for Chrome to report a page target it is willing to let us attach to. */ async function pageTarget(cdp) { const deadline = Date.now() + 15_000; for (;;) { const { targetInfos = [] } = await cdp.send('Target.getTargets'); - const page = targetInfos.find((target) => target.type === 'page' && !/^(chrome|chrome-extension|devtools):/.test(target.url || '')); - if (page) return page; + const pages = targetInfos.filter((target) => target.type === 'page' && !/^(chrome|chrome-extension|devtools):/.test(target.url || '')); + if (pages.length) return await selectPageTarget(cdp, pages); if (Date.now() > deadline) throw new Error('Chrome did not open a page to record.'); await new Promise((resolve) => setTimeout(resolve, 100)); } diff --git a/packages/cli/test/record-target.test.js b/packages/cli/test/record-target.test.js new file mode 100644 index 0000000..4578604 --- /dev/null +++ b/packages/cli/test/record-target.test.js @@ -0,0 +1,88 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; + +import { selectPageTarget } from '../src/record-session.js'; + +/** + * A browser that answers `Runtime.evaluate` out of a table of what each page + * would say about itself. `sessions` records every attach and detach, because + * a probe that leaves a session open would go on receiving the page's events. + */ +function fakeBrowser(pages) { + const sessions = { opened: [], closed: [] }; + let next = 0; + const bySession = new Map(); + return { + sessions, + async send(method, params = {}, sessionId) { + if (method === 'Target.attachToTarget') { + const page = pages[params.targetId]; + if (page?.attachFails) throw new Error('target closed'); + const id = `session-${++next}`; + sessions.opened.push(params.targetId); + bySession.set(id, params.targetId); + return { sessionId: id }; + } + if (method === 'Runtime.evaluate') { + const page = pages[bySession.get(sessionId)]; + if (page?.evaluateFails) throw new Error('execution context destroyed'); + return { result: { value: { visible: page.visible, focused: page.focused } } }; + } + if (method === 'Target.detachFromTarget') { sessions.closed.push(params.sessionId); return {}; } + throw new Error(`unexpected ${method}`); + }, + }; +} + +const page = id => ({ targetId: id, url: `https://example.com/${id}`, type: 'page' }); + +test('one page is recorded without being probed at all', async () => { + const browser = fakeBrowser({ only: { visible: true, focused: true } }); + const chosen = await selectPageTarget(browser, [page('only')]); + assert.equal(chosen.targetId, 'only'); + assert.deepEqual(browser.sessions.opened, []); +}); + +test('the tab on screen is recorded, not the first one Chrome lists', async () => { + // What a sign-in leaves behind: the consent popup Chrome opened first, and + // the app the person came back to. + const browser = fakeBrowser({ + popup: { visible: false, focused: false }, + app: { visible: true, focused: false }, + }); + const chosen = await selectPageTarget(browser, [page('popup'), page('app')]); + assert.equal(chosen.targetId, 'app'); + // Every probe is closed, including the one for the page that won: the caller + // attaches to it itself. + assert.deepEqual(browser.sessions.opened, ['popup', 'app']); + assert.equal(browser.sessions.closed.length, 2); +}); + +test('focus decides between two windows that are both showing a page', async () => { + const browser = fakeBrowser({ + behind: { visible: true, focused: false }, + front: { visible: true, focused: true }, + }); + assert.equal((await selectPageTarget(browser, [page('behind'), page('front')])).targetId, 'front'); +}); + +test('a tab that cannot be probed loses to one that answered, and ties keep Chrome order', async () => { + const broken = fakeBrowser({ + silent: { evaluateFails: true }, + app: { visible: false, focused: false }, + }); + assert.equal((await selectPageTarget(broken, [page('silent'), page('app')])).targetId, 'app'); + + // Nothing tells these apart, so the browser's own order still decides rather + // than the recording landing on an arbitrary tab. + const tied = fakeBrowser({ first: { visible: true, focused: false }, second: { visible: true, focused: false } }); + assert.equal((await selectPageTarget(tied, [page('first'), page('second')])).targetId, 'first'); +}); + +test('a browser that answers nothing still yields a page to record', async () => { + // Every probe failing is the old behaviour, which is the right fallback: a + // recording of Chrome's first page beats refusing to record at all. + const browser = fakeBrowser({ a: { attachFails: true }, b: { attachFails: true } }); + assert.equal((await selectPageTarget(browser, [page('a'), page('b')])).targetId, 'a'); + assert.deepEqual(browser.sessions.closed, []); +}); diff --git a/src/app/api/analyze/route.ts b/src/app/api/analyze/route.ts index e2561c0..1f8a053 100644 --- a/src/app/api/analyze/route.ts +++ b/src/app/api/analyze/route.ts @@ -19,6 +19,7 @@ import { selectTaskCards } from "@/lib/task-cards"; import { selectProfileFunctions } from "@/lib/profile-functions"; import { AgentError } from "@/lib/pi-agent"; import { debugLog } from "@/lib/debug-log"; +import { decompressedProfile, ProfileUploadError } from "@/lib/profile-upload"; import type { AnalysisModel, Hotspot, TokenUsage } from "@/lib/analysis"; const LOG = "api/analyze"; @@ -42,16 +43,27 @@ export async function POST(request: Request): Promise { return json({ error: "Expected a multipart form containing the profile file." }, 400); } - const profile = form.get("profile"); - if (!(profile instanceof File) || profile.size === 0) { + const uploaded = form.get("profile"); + if (!(uploaded instanceof File) || uploaded.size === 0) { log("rejected: no profile file in request"); return json({ error: "A CPU profile file is required." }, 400); } - if (profile.size > maxUploadBytes()) { - log(`rejected: profile too large (${profile.size} bytes)`); + if (uploaded.size > maxUploadBytes()) { + log(`rejected: profile too large (${uploaded.size} bytes)`); return json({ error: uploadTooLargeMessage() }, 413); } + // An exported trace is gzipped. Inflate before anything stores or parses it. + let profile: File; + try { profile = await decompressedProfile(uploaded); } + catch (error) { + if (error instanceof ProfileUploadError) { + log(`rejected: ${error.message}`); + return json({ error: error.message }, error.status); + } + throw error; + } + log(`request received: profile="${profile.name}" (${profile.size} bytes)`); let created; diff --git a/src/app/api/integration/v1/analyze/route.ts b/src/app/api/integration/v1/analyze/route.ts index 73cc46f..522c3e7 100644 --- a/src/app/api/integration/v1/analyze/route.ts +++ b/src/app/api/integration/v1/analyze/route.ts @@ -9,6 +9,7 @@ import { type IntegrationProfileType, } from "@/lib/integration-api"; import { maxUploadBytes, uploadTooLargeMessage } from "@/lib/analysis"; +import { decompressedProfile, ProfileUploadError } from "@/lib/profile-upload"; export const runtime = "nodejs"; @@ -19,9 +20,18 @@ export async function POST(request: Request): Promise { let form: FormData; try { form = await request.formData(); } catch { return integrationJson({ error: "Expected a multipart form containing the profile file." }, 400); } - const profile = form.get("profile"); - if (!(profile instanceof File) || profile.size === 0) return integrationJson({ error: "A profile file is required." }, 400); - if (profile.size > maxUploadBytes()) return integrationJson({ error: uploadTooLargeMessage() }, 413); + const uploaded = form.get("profile"); + if (!(uploaded instanceof File) || uploaded.size === 0) return integrationJson({ error: "A profile file is required." }, 400); + if (uploaded.size > maxUploadBytes()) return integrationJson({ error: uploadTooLargeMessage() }, 413); + + // A trace captured by `tracesift record` or exported from the web app + // arrives gzipped; everything below here reads it as text. + let profile: File; + try { profile = await decompressedProfile(uploaded); } + catch (error) { + if (error instanceof ProfileUploadError) return integrationJson({ error: error.message }, error.status); + throw error; + } const requested = form.get("profileType"); if (requested !== null && requested !== "auto" && requested !== "cpu" && requested !== "react") { diff --git a/src/app/page.tsx b/src/app/page.tsx index 69c4d1b..737c0ea 100644 --- a/src/app/page.tsx +++ b/src/app/page.tsx @@ -91,9 +91,11 @@ interface AnalysisModel { modelId?: string; } +// `.gz` so a trace exported from a recording — here or by `tracesift record` — +// can be opened again without unpacking it first. const acceptedFiles: Record = { - cpu: ".json,application/json", - reactProfile: ".json,application/json", + cpu: ".json,.gz,application/json,application/gzip", + reactProfile: ".json,.gz,application/json,application/gzip", }; function formatTokens(tokens: number): string { @@ -1163,7 +1165,11 @@ function UploadPane({ const inputId = useId(); const [isDragging, setIsDragging] = useState(false); - const acceptFile = (candidate?: File) => (candidate && !candidate.name.toLowerCase().endsWith(".json") ? undefined : candidate); + const acceptFile = (candidate?: File) => { + const name = candidate?.name.toLowerCase(); + if (name && !name.endsWith(".json") && !name.endsWith(".json.gz")) return undefined; + return candidate; + }; const handleChange = (event: ChangeEvent) => { if (disabled) return; @@ -1994,9 +2000,9 @@ function InspectorApp() {
{profileType === "javascript" ? ( - updateFile("cpu", file)} /> + updateFile("cpu", file)} /> ) : ( - updateFile("reactProfile", file)} /> + updateFile("reactProfile", file)} /> )}
diff --git a/src/lib/profile-upload.ts b/src/lib/profile-upload.ts new file mode 100644 index 0000000..99ba91a --- /dev/null +++ b/src/lib/profile-upload.ts @@ -0,0 +1,60 @@ +import { gunzip } from "node:zlib"; +import { promisify } from "node:util"; + +import { maxUploadBytes } from "./analysis.ts"; + +const inflate = promisify(gunzip); + +/** The two bytes every gzip member starts with. */ +const GZIP_MAGIC = [0x1f, 0x8b]; + +export class ProfileUploadError extends Error { + readonly status: number; + constructor(status: number, message: string) { + super(message); + this.name = "ProfileUploadError"; + this.status = status; + } +} + +/** Does this upload begin with a gzip member? Sniffed, not trusted to the name. */ +async function isGzip(profile: File): Promise { + if (profile.size < GZIP_MAGIC.length) return false; + const head = new Uint8Array(await profile.slice(0, GZIP_MAGIC.length).arrayBuffer()); + return GZIP_MAGIC.every((byte, index) => head[index] === byte); +} + +/** + * The profile as the analyzers want it: plain JSON bytes. + * + * A trace exported by the web app or by `tracesift record` is gzipped — the + * uncompressed document runs to tens of megabytes — and every reader below + * this point parses the upload as text. Rather than teach each of them about + * compression, inflate once here and hand on an ordinary `File`, so an + * exported `.json.gz` can be uploaded or sent to the Integration API exactly + * as a `.json` is. + * + * Content, not the extension, decides: a trace saved without its suffix still + * opens, and a `.json` that happens to be named `.gz` is left alone. + */ +export async function decompressedProfile(profile: File): Promise { + if (!(await isGzip(profile))) return profile; + + // The size check the caller already made was against the compressed bytes. + // Parsing needs the whole document as one V8 string, so the inflated size is + // what actually has to fit, and zlib stops rather than filling memory first. + const limit = maxUploadBytes(); + let inflated: Buffer; + try { + inflated = await inflate(Buffer.from(await profile.arrayBuffer()), { maxOutputLength: limit }); + } catch (error) { + const code = (error as NodeJS.ErrnoException | undefined)?.code; + if (code === "ERR_BUFFER_TOO_LARGE") { + throw new ProfileUploadError(413, `The profile is too large once uncompressed (max ${Math.floor(limit / (1024 * 1024))} MB).`); + } + throw new ProfileUploadError(400, "The uploaded file looks gzipped but could not be decompressed."); + } + + const name = profile.name.replace(/\.gz$/i, ""); + return new File([new Uint8Array(inflated)], name || profile.name, { type: "application/json" }); +} diff --git a/src/lib/react-analysis-handler.ts b/src/lib/react-analysis-handler.ts index 8420659..ec6774b 100644 --- a/src/lib/react-analysis-handler.ts +++ b/src/lib/react-analysis-handler.ts @@ -4,6 +4,7 @@ import { tmpdir } from "node:os"; import path from "node:path"; import { maxUploadBytes, uploadTooLargeMessage, putRecord, getAnalysisSettings, saveAnalysis } from "./analysis.ts"; import { parseReactProfileOptions, ReactProfileError } from "./react-profile.ts"; +import { decompressedProfile, ProfileUploadError } from "./profile-upload.ts"; import type { extractReactProfile } from "./react-profile.ts"; import { requireReactEvidence, withinReactBudget, noReactIssues, ZERO_REACT_USAGE, discardSubBudgetReactIssues, type analyzeReactProfile } from "./react-analyzer.ts"; import { parseFrameBudget } from "./react-evidence.ts"; @@ -64,9 +65,16 @@ export function createReactAnalysisHandler(dependencies: Dependencies) { let form: FormData; try { form = await request.formData(); } catch { throw new ReactProfileError(400, "Expected a multipart form containing the profile file."); } - const profile = form.get("profile"); - if (!(profile instanceof File) || !profile.size) throw new ReactProfileError(400, "A React profile file is required."); - if (profile.size > maxUploadBytes()) throw new ReactProfileError(413, uploadTooLargeMessage()); + const uploaded = form.get("profile"); + if (!(uploaded instanceof File) || !uploaded.size) throw new ReactProfileError(400, "A React profile file is required."); + if (uploaded.size > maxUploadBytes()) throw new ReactProfileError(413, uploadTooLargeMessage()); + // An export may arrive gzipped; the readers below all want plain JSON. + let profile: File; + try { profile = await decompressedProfile(uploaded); } + catch (error) { + if (error instanceof ProfileUploadError) throw new ReactProfileError(error.status, error.message); + throw error; + } const options = parseReactProfileOptions(form); const frameBudgetMs = parseFrameBudget(form); if (request.signal.aborted) throw new ReactProfileError(499, "React profile analysis cancelled."); diff --git a/tests/integration-api.test.mjs b/tests/integration-api.test.mjs index aab35a0..a9ff9a9 100644 --- a/tests/integration-api.test.mjs +++ b/tests/integration-api.test.mjs @@ -6,6 +6,7 @@ import { tmpdir } from 'node:os'; import path from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; import test from 'node:test'; +import { gzipSync } from 'node:zlib'; import { buildReactCardPrompt } from '../src/lib/react-card-prompt.ts'; import { createReactAnalysisHandler } from '../src/lib/react-analysis-handler.ts'; @@ -162,6 +163,35 @@ test('authenticated CPU route analysis returns a card whose route handoff is det assert.equal((await secondResponse.json()).handoff, first.handoff); }); +test('a gzipped trace analyzes exactly as the uncompressed one does', async t => { + // What `tracesift record` writes with no TraceSift running, and what the web + // app's own Export trace button produces, is a `.json.gz`. If the route could + // not read it, a capture would never reach a card. + const profile = await readFile(path.resolve('sample-profiles/cpu/hermes-release-1.json')); + const analyze = async (file) => { + const form = new FormData(); + form.set('profile', file); + form.set('profileType', 'auto'); + const response = await analyzeRoute(authorized('http://localhost/api/integration/v1/analyze', { method: 'POST', body: form })); + assert.equal(response.status, 200); + return response.json(); + }; + + const plain = await analyze(new File([profile], 'hermes-release-1.json', { type: 'application/json' })); + t.after(() => destroyRecord(plain.analysisId)); + const gzipped = await analyze(new File([gzipSync(profile)], 'hermes-release-1.json.gz', { type: 'application/gzip' })); + t.after(() => destroyRecord(gzipped.analysisId)); + + assert.equal(gzipped.profileType, 'cpu'); + // The title comes from the upload, so the suffix is gone but the analysis is + // the same measurement. + assert.equal(gzipped.title, 'hermes-release-1.json'); + assert.deepEqual( + gzipped.cards.map(card => card.headline ?? card.title), + plain.cards.map(card => card.headline ?? card.title), + ); +}); + test('integration task route guards its credentials, its parameters, and missing analyses', async () => { const unauthenticated = await taskRoute(new Request('http://localhost/api/integration/v1/task?analysisId=any&taskIndex=0')); assert.equal(unauthenticated.status, 401); diff --git a/tests/profile-upload.test.mjs b/tests/profile-upload.test.mjs new file mode 100644 index 0000000..30357f9 --- /dev/null +++ b/tests/profile-upload.test.mjs @@ -0,0 +1,64 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { gzipSync } from 'node:zlib'; + +import { decompressedProfile, ProfileUploadError } from '../src/lib/profile-upload.ts'; + +const document = JSON.stringify({ metadata: { enhancedTraceVersion: 1 }, traceEvents: [{ name: 'RunTask' }] }); + +function upload(bytes, name) { + return new File([new Uint8Array(bytes)], name); +} + +test('a gzipped trace is inflated and loses its .gz suffix', async () => { + const file = upload(gzipSync(Buffer.from(document)), 'trace.json.gz'); + const plain = await decompressedProfile(file); + assert.equal(plain.name, 'trace.json'); + assert.equal(await plain.text(), document); +}); + +test('a plain JSON upload is handed back untouched', async () => { + const file = upload(Buffer.from(document), 'trace.json'); + assert.equal(await decompressedProfile(file), file); +}); + +test('content decides, not the extension', async () => { + // A trace someone renamed still opens, and a plain file named .gz is left + // alone rather than failing to decompress. + const renamed = upload(gzipSync(Buffer.from(document)), 'trace'); + assert.equal(await (await decompressedProfile(renamed)).text(), document); + + const mislabelled = upload(Buffer.from(document), 'trace.json.gz'); + assert.equal(await (await decompressedProfile(mislabelled)).text(), document); +}); + +test('a truncated gzip member is reported as a bad upload, not a crash', async () => { + const whole = gzipSync(Buffer.from(document)); + const file = upload(whole.subarray(0, whole.length - 5), 'trace.json.gz'); + await assert.rejects(decompressedProfile(file), (error) => { + assert.ok(error instanceof ProfileUploadError); + assert.equal(error.status, 400); + return true; + }); +}); + +test('a trace that inflates past the upload ceiling is refused', async () => { + process.env.TRACE_SIFT_MAX_UPLOAD_MB = '1'; + try { + const big = JSON.stringify({ traceEvents: new Array(400_000).fill({ name: 'RunTask', ph: 'X' }) }); + assert.ok(big.length > 1024 * 1024); + const file = upload(gzipSync(Buffer.from(big)), 'trace.json.gz'); + await assert.rejects(decompressedProfile(file), (error) => { + assert.ok(error instanceof ProfileUploadError); + assert.equal(error.status, 413); + return true; + }); + } finally { + delete process.env.TRACE_SIFT_MAX_UPLOAD_MB; + } +}); + +test('an empty upload is not mistaken for gzip', async () => { + const file = upload(Buffer.alloc(0), 'trace.json'); + assert.equal(await decompressedProfile(file), file); +}); From 40eb90804e461adc2f43a0c8533c5e38f31ad080 Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Tue, 3 Nov 2026 12:36:01 +0500 Subject: [PATCH 07/10] feat: add RN CDP --- packages/cli/src/cdp.js | 28 +- packages/cli/src/cli.js | 19 +- packages/cli/src/metro.js | 188 +++++++++ packages/cli/src/record-rn-session.js | 422 ++++++++++++++++++++ packages/cli/src/record-session.js | 21 +- packages/cli/src/record.js | 155 ++++++- packages/cli/src/trace-chunker.js | 71 ++++ packages/cli/test/metro.test.js | 185 +++++++++ packages/cli/test/record-rn-session.test.js | 263 ++++++++++++ packages/cli/test/record.test.js | 57 ++- packages/cli/test/trace-chunker.test.js | 139 +++++++ scripts/test-codex-local.sh | 139 +++++++ src/app/api/captures/route.ts | 23 +- src/app/capture/page.tsx | 5 +- src/app/js-profiler/normalize.ts | 13 +- src/lib/capture-store.ts | 11 +- src/lib/capture-types.ts | 8 +- src/lib/source-location.ts | 2 +- tests/capture-store.test.mjs | 14 + 19 files changed, 1713 insertions(+), 50 deletions(-) create mode 100644 packages/cli/src/metro.js create mode 100644 packages/cli/src/record-rn-session.js create mode 100644 packages/cli/src/trace-chunker.js create mode 100644 packages/cli/test/metro.test.js create mode 100644 packages/cli/test/record-rn-session.test.js create mode 100644 packages/cli/test/trace-chunker.test.js create mode 100755 scripts/test-codex-local.sh diff --git a/packages/cli/src/cdp.js b/packages/cli/src/cdp.js index 923f208..8b88f2d 100644 --- a/packages/cli/src/cdp.js +++ b/packages/cli/src/cdp.js @@ -13,8 +13,15 @@ function closeReason(event) { * Flattened sessions are the only mode used here: every command carries the * session it belongs to, so one socket drives the browser target and each * attached page, worker and frame without nesting. + * + * `label` names whatever is on the other end in the connection errors. The + * React Native inspector is not a browser, and telling its user that "Chrome + * closed the debugging connection" sends them looking for a Chrome. + * + * @param {string} url + * @param {{ createSocket?: (url: string) => WebSocket, label?: string }} [options] */ -export async function connectCdp(url, { createSocket = (target) => new WebSocket(target) } = {}) { +export async function connectCdp(url, { createSocket = (target) => new WebSocket(target), label = 'Chrome' } = {}) { const socket = createSocket(url); const pending = new Map(); const listeners = new Set(); @@ -34,7 +41,14 @@ export async function connectCdp(url, { createSocket = (target) => new WebSocket const waiter = pending.get(message.id); if (!waiter) return; pending.delete(message.id); - if (message.error) waiter.reject(new Error(`${waiter.method} failed: ${message.error.message || 'Chrome rejected the command.'}`)); + if (message.error) { + // Keep the protocol code alongside the text: -32601 is how a runtime + // says it has never heard of a domain, which is the difference between + // "record with something else" and "this version wants the older call". + const failure = new Error(`${waiter.method} failed: ${message.error.message || `${label} rejected the command.`}`); + failure.cdpCode = message.error.code; + waiter.reject(failure); + } else waiter.resolve(message.result ?? {}); return; } @@ -48,17 +62,17 @@ export async function connectCdp(url, { createSocket = (target) => new WebSocket }); socket.addEventListener('close', (event) => { - shutdown ??= new Error(`Chrome closed the debugging connection: ${closeReason(event)}`); + shutdown ??= new Error(`${label} closed the debugging connection: ${closeReason(event)}`); rejectAll(shutdown); }); socket.addEventListener('error', () => { - shutdown ??= new Error('The Chrome debugging connection failed.'); + shutdown ??= new Error(`The ${label} debugging connection failed.`); }); await new Promise((resolve, reject) => { - const timer = setTimeout(() => reject(new Error('Chrome did not accept a debugging connection in time.')), CONNECT_TIMEOUT_MS); + const timer = setTimeout(() => reject(new Error(`${label} did not accept a debugging connection in time.`)), CONNECT_TIMEOUT_MS); socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true }); - socket.addEventListener('close', (event) => { clearTimeout(timer); reject(new Error(`Chrome refused the debugging connection: ${closeReason(event)}`)); }, { once: true }); + socket.addEventListener('close', (event) => { clearTimeout(timer); reject(new Error(`${label} refused the debugging connection: ${closeReason(event)}`)); }, { once: true }); }); return { @@ -92,7 +106,7 @@ export async function connectCdp(url, { createSocket = (target) => new WebSocket }, get closed() { return Boolean(shutdown) || socket.readyState > 1; }, close() { - shutdown ??= new Error('The Chrome debugging connection was closed.'); + shutdown ??= new Error(`The ${label} debugging connection was closed.`); rejectAll(shutdown); try { socket.close(); } catch { /* already gone */ } }, diff --git a/packages/cli/src/cli.js b/packages/cli/src/cli.js index 000c37b..7e67fbc 100755 --- a/packages/cli/src/cli.js +++ b/packages/cli/src/cli.js @@ -4,7 +4,8 @@ import { prerequisites, install } from './install.js'; import { start, parsePort } from './start.js'; import { explore } from './explore.js'; import { - RECORD_SUBCOMMANDS, assertRecordOptions, parseDuration, recordClose, recordLaunch, recordStart, recordStatus, recordStop, + RECORD_SUBCOMMANDS, assertRecordOptions, parseDuration, parsePlatform, + recordClose, recordLaunch, recordStart, recordStatus, recordStop, recordTargets, } from './record.js'; try { @@ -13,17 +14,19 @@ try { task: { type: 'string' }, commit: { type: 'string' }, focus: { type: 'string' }, url: { type: 'string' }, chrome: { type: 'string' }, 'user-data-dir': { type: 'string' }, out: { type: 'string' }, duration: { type: 'string' }, headless: { type: 'boolean' }, - sink: { type: 'string' }, + sink: { type: 'string' }, platform: { type: 'string' }, metro: { type: 'string' }, + app: { type: 'string' }, device: { type: 'string' }, 'target-id': { type: 'string' }, + 'no-source-maps': { type: 'boolean' }, json: { type: 'boolean' }, } }); const [command, ...extra] = positionals; if (values.help || !command) { - console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n tracesift record start [--url https://example.com] [--duration 30s] [--headless] [--out trace.json.gz]\n tracesift record stop\n tracesift record status\n tracesift record launch [--url https://example.com] [--headless] [--chrome path] [--user-data-dir path]\n tracesift record close\n\nRecording drives Chrome over the DevTools Protocol, so it needs no browser\nextension. It streams into a running TraceSift when there is one and writes a\n.json.gz otherwise; --sink ingest|local forces either.\n\nWith no browser open, record start launches its own Chrome and traces the page\nload. To profile a state you reached by hand, record launch a browser, sign in\nor navigate, then record start: it attaches without navigating, and the\nbrowser stays open after record stop until record close.\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); + console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n tracesift record start [--url https://example.com] [--duration 30s] [--headless] [--out trace.json.gz]\n tracesift record stop\n tracesift record status [--json]\n tracesift record targets --platform rn [--metro http://127.0.0.1:8081] [--json]\n tracesift record start --platform rn [--metro URL] [--app id] [--device name] [--target-id id]\n tracesift record launch [--url https://example.com] [--headless] [--chrome path] [--user-data-dir path]\n tracesift record close\n\nRecording drives Chrome over the DevTools Protocol, so it needs no browser\nextension. It streams into a running TraceSift when there is one and writes a\n.json.gz otherwise; --sink ingest|local forces either.\n\nWith no browser open, record start launches its own Chrome and traces the page\nload. To profile a state you reached by hand, record launch a browser, sign in\nor navigate, then record start: it attaches without navigating, and the\nbrowser stays open after record stop until record close.\n\n--platform rn records a Hermes CPU profile from a React Native app that is\nalready running in a simulator, emulator or device, over the Metro inspector.\nNothing is launched and no window opens: `record targets --platform rn` lists\nthe connected apps, and `record start --platform rn` attaches to the one that\nis running. Metro must be up; release builds are not supported yet.\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); } else { if (!['init', 'start', 'explore', 'record'].includes(command)) throw new Error('Unknown command. Run tracesift --help.'); if (!['explore', 'record'].includes(command) && extra.length) throw new Error('Unknown command. Run tracesift --help.'); if (command === 'explore' && extra.length !== 1) throw new Error('Explore requires one analysis path. Run tracesift --help.'); if (command === 'record' && (extra.length !== 1 || !RECORD_SUBCOMMANDS.includes(extra[0]))) { - throw new Error('Record requires one of start, stop, status, launch or close. Run tracesift --help.'); + throw new Error('Record requires one of start, stop, status, targets, launch or close. Run tracesift --help.'); } if ((values.port || values['no-open']) && command !== 'start') throw new Error('This option is not supported for this command. Run tracesift --help.'); if ((values.task || values.commit || values.focus) && command !== 'explore') throw new Error('This option is not supported for this command. Run tracesift --help.'); @@ -33,8 +36,14 @@ try { if (command === 'init') await install(); else if (command === 'start') await start({ port: parsePort(values.port), open: !values['no-open'] }); else if (command === 'explore') await explore(extra[0], { task: values.task, commit: values.commit, focus: values.focus }); + else if (extra[0] === 'targets') await recordTargets({ + platform: parsePlatform(values.platform), metro: values.metro, json: values.json, + }); else if (extra[0] === 'start') await recordStart({ + platform: parsePlatform(values.platform), url: values.url, chrome: values.chrome, userDataDir: values['user-data-dir'], + metro: values.metro, app: values.app, device: values.device, targetId: values['target-id'], + sourceMaps: !values['no-source-maps'], out: values.out, duration: parseDuration(values.duration), headless: values.headless, sink: values.sink, }); else if (extra[0] === 'launch') await recordLaunch({ @@ -42,7 +51,7 @@ try { }); else if (extra[0] === 'close') await recordClose(); else if (extra[0] === 'stop') await recordStop(); - else await recordStatus(); + else await recordStatus({ json: values.json }); } } catch (error) { console.error(`tracesift: ${error.message}`); process.exitCode = 1; diff --git a/packages/cli/src/metro.js b/packages/cli/src/metro.js new file mode 100644 index 0000000..f822f48 --- /dev/null +++ b/packages/cli/src/metro.js @@ -0,0 +1,188 @@ +const MAX_BODY_CHARS = 1024 * 1024; +const MAX_TARGETS = 100; +const MAX_FIELD_CHARS = 512; +const DISCOVERY_TIMEOUT_MS = 5000; +const DEFAULT_METRO_PORT = 8081; +const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1', '[::1]', '0.0.0.0']; +// The inspector proxy advertises itself on loopback only, so a debugger URL that +// names anything else is either a misconfiguration or an attempt to make us +// connect somewhere the developer never chose. +const DEBUGGER_HOSTS = ['127.0.0.1', 'localhost', '[::1]']; + +/** + * @typedef {{ + * id: string, + * title: string, + * appId?: string, + * deviceName?: string, + * deviceId?: string, + * vm?: string, + * webSocketDebuggerUrl: string, + * supportsMultipleDebuggers: boolean, + * }} MetroTarget + */ + +/** Default Metro origin, honouring RCT_METRO_PORT. */ +export function defaultMetroOrigin() { + const raw = process.env.RCT_METRO_PORT; + const port = raw && /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : NaN; + const valid = Number.isInteger(port) && port >= 1 && port <= 65535; + return `http://127.0.0.1:${valid ? port : DEFAULT_METRO_PORT}`; +} + +/** + * Validate a user-supplied Metro origin. `localhost:8081` has no scheme, and + * `new URL` would read `localhost:` as one, so add the default before parsing. + * @param {string} value + * @returns {URL} + */ +export function parseMetroOrigin(value) { + const text = String(value ?? '').trim(); + const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `http://${text}`; + let url; + try { + url = new URL(withScheme); + } catch { + throw new Error('Metro URL must be an http or https address.'); + } + if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('Metro URL must be an http or https address.'); + if (!LOOPBACK_HOSTS.includes(url.hostname)) { + throw new Error(`Metro URL must point at localhost; ${url.hostname} is not a loopback address.`); + } + return url; +} + +function originLabel(origin) { + const url = origin instanceof URL ? origin : parseMetroOrigin(origin); + return url.href.replace(/\/$/, ''); +} + +function clamp(value) { + return typeof value === 'string' ? value.slice(0, MAX_FIELD_CHARS) : undefined; +} + +function notMetro(label) { + return new Error(`${label} answered, but it is not a Metro server (no inspector target list). Check the port with --metro.`); +} + +/** + * Turn one `/json/list` item into a target, or null when it is not one we may + * connect to. Anything that fails validation is dropped rather than reported: + * a stale or foreign entry should not hide the apps that are fine. + */ +function toTarget(item, base) { + if (!item || typeof item.id !== 'string' || typeof item.webSocketDebuggerUrl !== 'string') return null; + let url; + try { + url = new URL(item.webSocketDebuggerUrl, base); + } catch { + return null; + } + if (url.protocol !== 'ws:' || !DEBUGGER_HOSTS.includes(url.hostname) || url.username || url.password || url.hash) return null; + // An inspector may report localhost while discovery used 127.0.0.1, but never another port. + if (url.port !== base.port) return null; + return { + id: clamp(item.id), + title: clamp(item.title) ?? clamp(item.id), + appId: clamp(item.appId), + deviceName: clamp(item.deviceName), + deviceId: clamp(item.reactNative?.logicalDeviceId), + vm: clamp(item.vm), + webSocketDebuggerUrl: url.href, + supportsMultipleDebuggers: item.reactNative?.capabilities?.supportsMultipleDebuggers === true, + }; +} + +/** + * List the debuggable targets Metro's inspector proxy knows about. + * @param {string | URL} origin + * @param {{ signal?: AbortSignal }} [options] + * @returns {Promise} + */ +export async function metroTargets(origin, { signal } = {}) { + const base = origin instanceof URL ? origin : parseMetroOrigin(origin); + const label = originLabel(base); + let response; + let body; + try { + response = await fetch(new URL('/json/list', base), { + redirect: 'error', + signal: AbortSignal.any([AbortSignal.timeout(DISCOVERY_TIMEOUT_MS), ...(signal ? [signal] : [])]), + }); + if (response.ok) body = await response.text(); + } catch { + throw new Error( + `No Metro server is listening on ${label}. Start it with \`npx react-native start\` (or \`npx expo start\`), then run this again. Point at another port with --metro.`, + ); + } + if (!response.ok) throw notMetro(label); + if (body.length > MAX_BODY_CHARS) throw new Error('Metro returned too many targets.'); + let payload; + try { + payload = JSON.parse(body); + } catch { + throw notMetro(label); + } + if (!Array.isArray(payload)) throw notMetro(label); + return payload.slice(0, MAX_TARGETS).flatMap((item) => { + const target = toTarget(item, base); + return target ? [target] : []; + }); +} + +/** + * One-line human label, e.g. `AwesomeApp (Hermes) — iPhone 17 Pro`. + * @param {MetroTarget} target + */ +export function describeMetroTarget(target) { + let text = target.title || target.appId || target.id; + if (target.vm) text += ` (${target.vm})`; + if (target.deviceName) text += ` — ${target.deviceName}`; + return text; +} + +function sameText(a, b) { + return typeof a === 'string' && a.toLowerCase() === b.toLowerCase(); +} + +/** + * Pick the one app to record. Pure, so the ambiguity rules are testable without + * a Metro server. The proxy lists the freshest connection last, so a reloaded + * app that left a stale entry behind resolves to its newest session. + * @param {MetroTarget[]} targets + * @param {{ app?: string, device?: string, targetId?: string, origin?: string | URL }} [options] + * @returns {MetroTarget} + */ +export function selectMetroTarget(targets, { app, device, targetId, origin } = {}) { + if (targets.length === 0) { + throw new Error( + `Metro is running on ${origin ? originLabel(origin) : 'the Metro address'}, but no app is connected to it. ` + + 'Launch the app in a simulator, emulator or device and wait for the bundle to finish loading, then run this again.', + ); + } + const selector = targetId ? ['target-id', targetId] : app ? ['app', app] : device ? ['device', device] : null; + let candidates = targets.filter( + (target) => + (!targetId || target.id === targetId) && + (!app || target.appId === app || sameText(target.title, app)) && + (!device || sameText(target.deviceName, device)), + ); + if (candidates.length === 0) { + throw new Error( + `No app connected to Metro matches --${selector[0]} ${selector[1]}. Run \`tracesift record targets --platform rn\` to see what is connected.`, + ); + } + if (!selector) { + candidates = candidates.filter((target) => !target.vm || /hermes/i.test(target.vm)); + if (candidates.length === 0) { + throw new Error('That app runs on JavaScriptCore, which has no sampling profiler. Switch it to Hermes (the React Native default) and record again.'); + } + } + const key = (target) => `${target.deviceId ?? ''}|${target.appId ?? ''}`; + const last = new Map(); + candidates.forEach((target, index) => last.set(key(target), index)); + candidates = candidates.filter((target, index) => key(target) === '|' || last.get(key(target)) === index); + if (candidates.length === 1) return candidates[0]; + const lines = candidates.map((target) => ` ${describeMetroTarget(target)} — --target-id ${target.id}`); + throw new Error([`Metro has ${candidates.length} connected apps. Choose one with --app, --device or --target-id:`, ...lines].join('\n')); +} diff --git a/packages/cli/src/record-rn-session.js b/packages/cli/src/record-rn-session.js new file mode 100644 index 0000000..2a5dc90 --- /dev/null +++ b/packages/cli/src/record-rn-session.js @@ -0,0 +1,422 @@ +import { connectCdp } from './cdp.js'; +import { defaultMetroOrigin, describeMetroTarget, metroTargets, parseMetroOrigin, selectMetroTarget } from './metro.js'; +import { errorText, resolveSink, TRACE_CATEGORIES } from './record-session.js'; +import { writeRecordState } from './record-state.js'; +import { createTraceEventWriter } from './trace-chunker.js'; + +const MAX_UPLOAD_BYTES = 192 * 1024; +// A Metro development bundle is one file for the whole app, and its map runs +// past Chrome's 8 MB per-script limit routinely — an Expo starter is already +// over 10 MB. The aggregate limit is what actually bounds the export, and +// there is normally one bundle to retain. +const MAX_SOURCE_MAP_BYTES = 48 * 1024 * 1024; +const MAX_ALL_SOURCE_MAP_BYTES = 64 * 1024 * 1024; +const STOP_POLL_MS = 1000; +const FLUSH_TIMEOUT_MS = 120_000; +const METHOD_NOT_FOUND = -32601; +// A Profiler.stop profile arrives whole. Chunking it keeps each ingest POST +// under the route's 1 MB cap the same way the streamed Chrome path does. +const SAMPLES_PER_CHUNK = 10_000; + +/** + * React Native refuses to trace for three specific reasons, each of which the + * developer can act on — but only if they are told which one it was. The + * protocol only gives us the text, so match on it. + */ +function tracingStartFailure(error) { + const text = errorText(error); + if (/Debugger domain is expected to be disabled/i.test(text)) { + return 'A debugger is attached to that app. Close React Native DevTools, then run this again.'; + } + if (/already been started|already started/i.test(text)) { + return 'That app is already being profiled. Hermes has one sampler, so stop the recording in React Native DevTools (or close that window) and run this again.'; + } + if (/host/i.test(text) && /multiple|more than one/i.test(text)) { + return 'The app has more than one React Native host registered, and React Native will not trace it. Reload the app, then run this again.'; + } + return null; +} + +/** + * Turn a `Profiler.stop` result into the trace events a `Tracing` recording + * would have produced, so both routes hand the analyzer one format. + * + * @param {{ nodes: unknown[], startTime?: number, endTime?: number, samples?: number[], timeDeltas?: number[] }} profile + */ +export function cpuProfileToTraceEvents(profile, { pid = 1, tid = 1, profileId = '0x1' } = {}) { + const samples = Array.isArray(profile.samples) ? profile.samples : []; + const timeDeltas = Array.isArray(profile.timeDeltas) ? profile.timeDeltas : []; + const startTime = Number(profile.startTime) || 0; + const events = [{ + name: 'Profile', + cat: 'disabled-by-default-v8.cpu_profiler', + ph: 'P', + pid, + tid, + ts: startTime, + id: profileId, + args: { data: { startTime } }, + }]; + // The first chunk carries the node table; the rest only extend the samples, + // which is how V8 emits a long profile and what extractFromTrace expects. + for (let offset = 0; offset < Math.max(samples.length, 1); offset += SAMPLES_PER_CHUNK) { + events.push({ + name: 'ProfileChunk', + cat: 'disabled-by-default-v8.cpu_profiler', + ph: 'P', + pid, + tid, + ts: startTime, + id: profileId, + args: { + data: { + cpuProfile: { + ...(offset === 0 ? { nodes: profile.nodes ?? [] } : {}), + samples: samples.slice(offset, offset + SAMPLES_PER_CHUNK), + }, + timeDeltas: timeDeltas.slice(offset, offset + SAMPLES_PER_CHUNK), + }, + }, + }); + } + return events; +} + +/** + * Retain the Metro source maps for the bundles a profile's frames came from. + * + * Chrome harvests these over `Debugger.scriptParsed`, which React Native + * cannot offer: enabling the Debugger domain makes `Tracing.start` fail + * outright. Metro serves the map for a bundle at the same URL with a `.map` + * extension, so the bundle URLs the profile already carries are enough. + */ +function metroSourceMaps(origin) { + const seen = new Set(); + const retained = []; + const warnings = []; + let bytes = 0; + + // Metro writes a bundle's parameters inside the path rather than the query + // (`/index.bundle//&platform=ios&dev=true`), and the map is served from the + // same request with a `.map` extension. So the rewrite has to find `.bundle` + // where it sits rather than assume it ends the path. + const mapUrlFor = (bundleUrl) => { + const url = new URL(bundleUrl); + const mapped = url.pathname.replace(/\.(bundle|js)(?=$|[/?])/, '.map'); + if (mapped === url.pathname) return null; + // Expo hands the device a LAN address for the same Metro that discovery + // reached on loopback, so a frame's bundle URL is routinely + // `http://192.168.1.5:8081/...` while `origin` is `127.0.0.1:8081`. The + // port is what identifies the server; the map is then fetched from the + // loopback origin we already validated rather than from the LAN one, so + // this never reaches off the machine. + if (url.port !== origin.port) return null; + const target = new URL(origin.href); + target.pathname = mapped; + target.search = url.search; + return target; + }; + + return { + /** Note every bundle URL a batch of trace events mentions. */ + observe(events) { + for (const event of events) { + const nodes = event?.args?.data?.cpuProfile?.nodes; + if (!Array.isArray(nodes)) continue; + for (const node of nodes) { + const url = node?.callFrame?.url; + if (typeof url !== 'string' || !url.startsWith('http')) continue; + if (seen.size >= 50) return; + seen.add(url.split('#')[0]); + } + } + }, + async collect() { + const candidates = new Map(); + for (const bundleUrl of seen) { + let mapUrl; + try { mapUrl = mapUrlFor(bundleUrl); } + catch { continue; } + if (mapUrl && !candidates.has(mapUrl.href)) candidates.set(mapUrl.href, bundleUrl); + } + for (const [mapUrl, bundleUrl] of candidates) { + if (bytes >= MAX_ALL_SOURCE_MAP_BYTES) { + warnings.push(`Stopped retaining source maps after the ${MAX_ALL_SOURCE_MAP_BYTES / 1048576} MB safety limit.`); + break; + } + try { + const response = await fetch(mapUrl, { redirect: 'error', signal: AbortSignal.timeout(30_000) }); + if (!response.ok) throw new Error(`HTTP ${response.status}`); + const raw = await response.text(); + if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error(`is ${Math.round(raw.length / 1048576)} MB, past the retention limit`); + const sourceMap = JSON.parse(raw); + if (!sourceMap || typeof sourceMap !== 'object' || Array.isArray(sourceMap)) throw new Error('not a JSON object'); + bytes += raw.length; + retained.push({ url: bundleUrl, sourceMapUrl: mapUrl, sourceMap }); + } catch (error) { + warnings.push(`Could not retain the Metro source map ${mapUrl}: ${errorText(error)}`); + } + } + if (retained.length === 0) { + warnings.push('React Native frames are reported at bundle positions; no Metro source map was retained.'); + } + return { retained, warnings: [...new Set(warnings)] }; + }, + }; +} + +/** + * Reject as soon as the inspector socket goes away. + * + * @param {{ closed: boolean }} cdp + * @returns {{ promise: Promise, stop(): void }} + */ +function watchDisconnect(cdp) { + let timer; + const promise = new Promise((_resolve, reject) => { + timer = setInterval(() => { + if (!cdp.closed) return; + clearInterval(timer); + reject(new Error('The app disconnected from Metro before the recording finished. Nothing was captured — reload the app and record again.')); + }, STOP_POLL_MS); + timer.unref?.(); + }); + // Nothing awaits this promise once the recording has moved on, and an + // unobserved rejection would take the recorder down with it. + promise.catch(() => undefined); + return { promise, stop() { clearInterval(timer); } }; +} + +/** The record.json shape both the starting and recording states share. */ +function recordState(home, sink, target, state, extra = {}) { + return writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink.mode, + state, + startedAt: Date.now(), + url: target.url, + targetLabel: target.title, + captureId: sink.captureId, + ...(sink.baseUrl ? { baseUrl: sink.baseUrl } : {}), + ...(sink.directory ? { directory: sink.directory } : {}), + ...extra, + }); +} + +/** + * Record a Hermes CPU profile from an app already running on a simulator, + * emulator or device, over React Native's Metro inspector proxy. + * + * Nothing is launched and no window opens: the app is where the developer put + * it, so an agent can start and stop a recording without handing control back + * to a person. The trace is written in the same enhanced-trace envelope the + * Chrome path produces, because React Native emits the same Profile and + * ProfileChunk events V8 does. + * + * @param {{ + * home: string, + * metro?: string, + * app?: string, + * device?: string, + * targetId?: string, + * sourceMaps?: boolean, + * out?: string, + * duration?: number, + * sink?: 'auto' | 'ingest' | 'local', + * onReady?: (info: { captureId: string, mode: string }) => void, + * }} options + */ +export async function runRnRecording(options) { + const { home } = options; + const origin = parseMetroOrigin(options.metro || defaultMetroOrigin()); + let cdp; + let sink; + let target = { platform: 'react-native', title: 'React Native app', url: origin.href.replace(/\/$/, '') }; + let stopReason = 'manual'; + const warnings = []; + // Timers and signal handlers that keep the process alive. They are released + // in the outer `finally`, because the recording can end by rejection at + // several points between arming them and the ordinary stop. + let releaseStopWatchers = () => {}; + + try { + const found = await metroTargets(origin); + const selected = selectMetroTarget(found, { + app: options.app, device: options.device, targetId: options.targetId, origin, + }); + + target = { + platform: 'react-native', + title: describeMetroTarget(selected), + url: origin.href.replace(/\/$/, ''), + targetId: selected.id, + ...(selected.appId ? { appId: selected.appId } : {}), + ...(selected.deviceName ? { deviceName: selected.deviceName } : {}), + }; + + // The inspector proxy only accepts a socket whose Origin is the Metro + // server itself. Node's global WebSocket sends no Origin at all, and the + // handshake is refused without one. + cdp = await connectCdp(selected.webSocketDebuggerUrl, { + label: 'The app', + createSocket: (url) => new WebSocket(url, { headers: { Origin: origin.origin } }), + }); + + sink = await resolveSink(home, target, target.title, options); + await recordState(home, sink, target, 'starting'); + await sink.status({ state: 'attaching' }).catch(() => undefined); + + const writer = createTraceEventWriter(sink, { maxBytes: MAX_UPLOAD_BYTES }); + const sourceMaps = options.sourceMaps === false ? null : metroSourceMaps(origin); + + let stop; + const stopped = new Promise((resolve) => { stop = (reason) => { stopReason = reason; resolve(reason); }; }); + let collecting = Promise.resolve(); + let collectError = null; + + // React Native can send dataCollected throughout the recording, so the + // listener goes on now. Its deadline does not: the flush has not been + // asked for yet, and a timer started here would cap how long a recording + // may run rather than how long it may take to finish. + let completed; + const complete = new Promise((resolve) => { completed = resolve; }); + cdp.on((method, params) => { + if (method === 'Tracing.dataCollected') { + const events = Array.isArray(params.value) ? params.value : []; + if (events.length === 0) return; + sourceMaps?.observe(events); + // Serialize the writes so a burst of notifications cannot queue an + // unbounded amount of trace data ahead of the sink. + collecting = collecting.then(() => writer.write(events)).catch((error) => { collectError ??= error; }); + return; + } + if (method === 'Tracing.tracingComplete') completed(params); + }); + + // No Debugger.enable, no Page.enable, no Target.setAutoAttach: React + // Native rejects Tracing.start outright while the Debugger domain is on, + // and the proxy exposes one flat session, so nothing carries a sessionId. + let useProfilerFallback = false; + try { + await cdp.send('Tracing.start', { categories: TRACE_CATEGORIES, options: 'record-until-full' }); + } catch (error) { + const mapped = tracingStartFailure(error); + if (mapped) throw new Error(mapped); + if (error?.cdpCode !== METHOD_NOT_FOUND) throw error; + useProfilerFallback = true; + } + if (useProfilerFallback) { + try { + await cdp.send('Profiler.enable').catch(() => undefined); + await cdp.send('Profiler.start'); + } catch (error) { + const mapped = tracingStartFailure(error); + if (mapped) throw new Error(mapped); + if (error?.cdpCode === METHOD_NOT_FOUND) { + throw new Error('That app’s React Native version does not expose a CPU profiler over the Metro inspector. Upgrade React Native, or record with React Native DevTools and analyse the exported profile with `tracesift start`.'); + } + throw error; + } + warnings.push('Recorded with the older Profiler domain; task boundaries are unavailable in this React Native version.'); + } + + await recordState(home, sink, target, 'recording'); + await sink.status({ state: 'recording' }).catch(() => undefined); + options.onReady?.({ captureId: sink.captureId, mode: sink.mode }); + + const onSignal = () => stop('manual'); + process.on('SIGINT', onSignal); + process.on('SIGTERM', onSignal); + const durationTimer = options.duration ? setTimeout(() => stop('manual'), options.duration) : null; + const poller = setInterval(() => { + void sink.stopRequested().then((requested) => { if (requested) stop('manual'); }).catch(() => undefined); + }, STOP_POLL_MS); + // An app that is reloaded or killed mid-recording has nothing left to + // flush, and waiting for a tracingComplete it will never send is worse + // than saying so. This promise only ever rejects; `stop()` ends the watch. + const watch = watchDisconnect(cdp); + releaseStopWatchers = () => { + process.off('SIGINT', onSignal); + process.off('SIGTERM', onSignal); + if (durationTimer) clearTimeout(durationTimer); + clearInterval(poller); + watch.stop(); + }; + + await Promise.race([stopped, watch.promise]); + + await sink.status({ state: 'flushing', stopReason }).catch(() => undefined); + + let dataLoss = false; + try { + if (useProfilerFallback) { + const { profile } = await cdp.send('Profiler.stop'); + if (!profile) throw new Error('The app stopped profiling without returning a profile.'); + const events = cpuProfileToTraceEvents(profile); + sourceMaps?.observe(events); + await writer.write(events); + } else { + await Promise.race([cdp.send('Tracing.end'), watch.promise]); + let flushTimer; + const flushDeadline = new Promise((_resolve, reject) => { + flushTimer = setTimeout(() => reject(new Error('The app did not finish flushing the trace in time.')), FLUSH_TIMEOUT_MS); + flushTimer.unref?.(); + }); + // The deadline loses the race in the ordinary case, and a timer left + // armed would reject with nobody listening. + flushDeadline.catch(() => undefined); + try { + const finished = await Promise.race([complete, watch.promise, flushDeadline]); + dataLoss = finished.dataLossOccurred === true; + } finally { + clearTimeout(flushTimer); + } + await collecting; + if (collectError) throw collectError; + } + } finally { + releaseStopWatchers(); + } + await writer.end(); + + await sink.status({ state: 'enriching' }).catch(() => undefined); + const collected = sourceMaps ? await sourceMaps.collect() : { retained: [], warnings: [] }; + warnings.push(...collected.warnings); + + // No mainFrame and no traceMarker: React Native emits TracingStartedInPage, + // which the exporter already accepts as real frame metadata, so there is + // nothing for it to rebuild and no spool rescan to pay for. + const result = await sink.finalize({ + dataLoss, + stopReason, + scripts: [], + sourceMaps: collected.retained, + warnings, + }); + + await recordState(home, sink, target, 'captured', { + export: { path: result.path ?? '', sizeBytes: result.sizeBytes, eventCount: result.eventCount }, + warnings: result.warnings ?? warnings, + }); + return { ...result, mode: sink.mode, captureId: sink.captureId, baseUrl: sink.baseUrl }; + } catch (error) { + const message = errorText(error); + await sink?.fail(message).catch(() => undefined); + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink?.mode ?? 'local', + state: 'failed', + startedAt: Date.now(), + url: target.url, + targetLabel: target.title, + ...(sink?.captureId ? { captureId: sink.captureId } : {}), + error: message, + }).catch(() => undefined); + throw error; + } finally { + releaseStopWatchers(); + cdp?.close(); + } +} diff --git a/packages/cli/src/record-session.js b/packages/cli/src/record-session.js index 7f4dd9d..46cfb4f 100644 --- a/packages/cli/src/record-session.js +++ b/packages/cli/src/record-session.js @@ -15,7 +15,7 @@ const MAX_SOURCE_MAP_BYTES = 8 * 1024 * 1024; const MAX_ALL_SOURCE_MAP_BYTES = 16 * 1024 * 1024; const STOP_POLL_MS = 1000; -const TRACE_CATEGORIES = [ +export const TRACE_CATEGORIES = [ '-*', 'blink.console', 'blink.user_timing', @@ -33,7 +33,7 @@ const TRACE_CATEGORIES = [ 'v8.execute', ].join(','); -function errorText(error) { +export function errorText(error) { return error instanceof Error ? error.message : String(error || 'Unknown recording error.'); } @@ -253,7 +253,7 @@ function sourceMapCollector(cdp) { } /** Choose where the trace goes: a running TraceSift if there is one, else disk. */ -async function resolveSink(home, target, title, options) { +export async function resolveSink(home, target, title, options) { if (options.sink !== 'local') { try { const service = await readActiveService(home); @@ -322,7 +322,7 @@ export async function runRecording(options) { const { sessionId } = await cdp.send('Target.attachToTarget', { targetId: page.targetId, flatten: true }); await configureSession(cdp, sessionId); - const target = { tabId: 0, title: page.title || options.url || 'Chrome performance capture', url: options.url || page.url || '' }; + const target = { platform: 'chrome', title: page.title || options.url || 'Chrome performance capture', url: options.url || page.url || '' }; sink = await resolveSink(home, target, target.title, options); const traceMarker = `__tracesift_main_${sink.captureId}`; let mainFrame = await mainFrameOf(cdp, sessionId); @@ -488,10 +488,19 @@ export async function runRecording(options) { } } -/** Entry point for the detached recorder `tracesift record start` spawns. */ +/** + * Entry point for the detached recorder `tracesift record start` spawns. + * + * The React Native recorder is loaded only when it is the one being asked for, + * so a Chrome recording never pays for a module it cannot use. + */ export async function recorderMain(argv) { try { - await runRecording(JSON.parse(argv[0])); + const options = JSON.parse(argv[0]); + const run = options.platform === 'rn' + ? (await import('./record-rn-session.js')).runRnRecording + : runRecording; + await run(options); } catch (error) { // The failure is already recorded in record.json for `record stop` and // `record status` to report; the log keeps the full text. diff --git a/packages/cli/src/record.js b/packages/cli/src/record.js index a390b3c..c60b2df 100644 --- a/packages/cli/src/record.js +++ b/packages/cli/src/record.js @@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'; import { connectCdp } from './cdp.js'; import { findChrome, launchChrome } from './chrome.js'; import { ensureHome, getHome } from './config.js'; +import { defaultMetroOrigin, describeMetroTarget, metroTargets, parseMetroOrigin, selectMetroTarget } from './metro.js'; import { activeRecordState, clearBrowserState, liveBrowserState, processAlive, readBrowserState, readRecordState, writeBrowserState, } from './record-state.js'; @@ -19,14 +20,32 @@ const CLOSE_TIMEOUT_MS = 10_000; // Which options each `record` subcommand understands. `launch` only shapes the // browser; everything about the trace itself belongs to `start`. const RECORD_OPTIONS = { - start: ['url', 'chrome', 'user-data-dir', 'out', 'duration', 'headless', 'sink'], - launch: ['url', 'chrome', 'user-data-dir', 'headless'], + start: ['url', 'chrome', 'user-data-dir', 'out', 'duration', 'headless', 'sink', + 'platform', 'metro', 'app', 'device', 'target-id', 'no-source-maps'], + // `launch` and `close` take --platform only so that naming rn there gets the + // reason it makes no sense rather than a flag-not-supported error. + launch: ['url', 'chrome', 'user-data-dir', 'headless', 'platform'], + targets: ['platform', 'metro', 'json'], stop: [], - status: [], - close: [], + status: ['json'], + close: ['platform'], }; export const RECORD_SUBCOMMANDS = Object.keys(RECORD_OPTIONS); +// Flags that only mean something for one platform. Naming them against the +// wrong one is a mistake worth failing on: it would otherwise look like the +// recording honoured a setting it silently dropped. +const CHROME_ONLY = ['url', 'chrome', 'user-data-dir', 'headless']; +const RN_ONLY = ['metro', 'app', 'device', 'target-id', 'no-source-maps']; + +/** Normalise `--platform`, which defaults to Chrome. */ +export function parsePlatform(value) { + if (value === undefined) return 'chrome'; + if (value === 'chrome') return 'chrome'; + if (value === 'rn' || value === 'react-native') return 'rn'; + throw new Error('Platform must be chrome or rn.'); +} + /** * Reject an option the chosen command would silently ignore, so a typo such as * `record stop --out x` fails instead of looking like it worked. @@ -42,6 +61,19 @@ export function assertRecordOptions(command, subcommand, values) { const allowed = RECORD_OPTIONS[subcommand] ?? []; const rejected = given.find((option) => !allowed.includes(option)); if (rejected) throw new Error(`--${rejected} is not supported by tracesift record ${subcommand}. Run tracesift --help.`); + + const platform = parsePlatform(values.platform); + if (platform === 'rn' && (subcommand === 'launch' || subcommand === 'close')) { + throw new Error('There is nothing to launch for React Native: the app is already running in a simulator, emulator or device. Run tracesift record start --platform rn.'); + } + const chromeOnly = given.find((option) => CHROME_ONLY.includes(option)); + if (platform === 'rn' && chromeOnly) { + throw new Error(`--${chromeOnly} applies to Chrome. tracesift record start --platform rn attaches to an app that is already running.`); + } + const rnOnly = given.find((option) => RN_ONLY.includes(option)); + if (platform !== 'rn' && rnOnly) { + throw new Error(`--${rnOnly} applies to tracesift record start --platform rn.`); + } } /** Accept `30`, `30s`, `500ms` or `2m`; a bare number is seconds. */ @@ -66,43 +98,127 @@ function describe(state) { const events = state.export?.eventCount ? ` · ${state.export.eventCount.toLocaleString()} events` : ''; return `Recorded ${where}${size}${events}`; } - return `Recording ${state.url || 'Chrome'} (${state.state}).`; + return `Recording ${state.targetLabel || state.url || 'the app'} (${state.state}).`; } function describeBrowser(browser) { return `Chrome launched by \`tracesift record launch\` is open (pid ${browser.pid}${browser.url ? `, ${browser.url}` : ''}).`; } -async function waitFor(home, predicate, timeout, onTimeout) { +/** + * Poll record.json until it says what the caller is waiting for. + * + * `pid` scopes the wait to one recorder. The file outlives the process that + * wrote it, so a finished recording still sitting there answers `captured` + * instantly — and a caller waiting for the recorder it just spawned would + * take that as its own and report the previous capture's path. + */ +async function waitFor(home, predicate, timeout, onTimeout, pid) { const deadline = Date.now() + timeout; for (;;) { const state = await readRecordState(home); - if (state && predicate(state)) return state; - if (state && !processAlive(state.pid) && state.state !== 'captured') { - throw new Error(state.error || 'The recorder stopped before it finished.'); + const mine = state && (pid === undefined || state.pid === pid) ? state : null; + if (mine && predicate(mine)) return mine; + if (mine && !processAlive(mine.pid) && mine.state !== 'captured') { + throw new Error(mine.error || 'The recorder stopped before it finished.'); } if (Date.now() > deadline) throw new Error(onTimeout); await new Promise((resolve) => setTimeout(resolve, POLL_MS)); } } +/** + * List the apps connected to Metro, so a recording can name one — and so a + * harness can find out what is there without starting anything. + */ +export async function recordTargets(options = {}) { + const platform = options.platform ?? 'chrome'; + if (platform !== 'rn') { + throw new Error('tracesift record targets lists React Native apps. Run it with --platform rn.'); + } + const origin = parseMetroOrigin(options.metro || defaultMetroOrigin()); + const label = origin.href.replace(/\/$/, ''); + let targets; + try { + targets = await metroTargets(origin); + } catch (error) { + if (!options.json) throw error; + console.log(JSON.stringify({ apiVersion: 1, error: error.message })); + process.exitCode = 1; + return null; + } + + // `recommended` is what `record start` would pick on its own. Reporting it + // keeps the two from disagreeing when a caller lists first and records after. + let recommended; + try { recommended = selectMetroTarget(targets, { origin }); } + catch { recommended = undefined; } + + if (options.json) { + console.log(JSON.stringify({ + apiVersion: 1, + platform: 'rn', + metro: label, + targets: targets.map((target) => ({ + id: target.id, + title: target.title, + ...(target.appId ? { appId: target.appId } : {}), + ...(target.deviceName ? { deviceName: target.deviceName } : {}), + ...(target.deviceId ? { deviceId: target.deviceId } : {}), + ...(target.vm ? { vm: target.vm } : {}), + supportsMultipleDebuggers: target.supportsMultipleDebuggers, + recommended: target.id === recommended?.id, + })), + })); + return targets; + } + + if (targets.length === 0) { + console.log(`Metro on ${label} has no app connected to it.`); + console.log('Launch the app in a simulator, emulator or device and wait for the bundle to finish loading.'); + return targets; + } + console.log(`Metro on ${label}\n`); + for (const target of targets) { + console.log(` ${describeMetroTarget(target)}${target.id === recommended?.id ? ' (default)' : ''}`); + if (target.appId) console.log(` app ${target.appId}`); + console.log(` target ${target.id}`); + } + console.log(targets.length > 1 + ? '\nRecord one with: tracesift record start --platform rn --target-id ' + : '\nRecord it with: tracesift record start --platform rn'); + return targets; +} + /** * Launch Chrome under the DevTools Protocol and begin recording in a detached * process, so a harness gets its shell back while the trace keeps running. */ export async function recordStart(options = {}) { const home = getHome(); + const platform = options.platform ?? 'chrome'; await ensureHome(home); const running = await activeRecordState(home); - if (running) throw new Error(`A recording is already running (${running.url || 'Chrome'}). Stop it with \`tracesift record stop\`.`); + if (running) throw new Error(`A recording is already running (${running.targetLabel || running.url || 'Chrome'}). Stop it with \`tracesift record stop\`.`); - const browser = await liveBrowserState(home); + const browser = platform === 'rn' ? null : await liveBrowserState(home); // Those options choose how to launch a Chrome, and none is being launched. if (browser && (options.chrome || options.userDataDir || options.headless)) { throw new Error('--chrome, --user-data-dir and --headless apply to a new Chrome, but a browser from `tracesift record launch` is open. Close it with `tracesift record close` or drop them.'); } - const payload = JSON.stringify({ + const payload = JSON.stringify(platform === 'rn' ? { + home, + platform, + metro: options.metro, + app: options.app, + device: options.device, + targetId: options.targetId, + sourceMaps: options.sourceMaps !== false, + out: options.out, + duration: options.duration, + sink: options.sink ?? 'auto', + } : { home, url: options.url, chrome: options.chrome, @@ -121,9 +237,10 @@ export async function recordStart(options = {}) { await log.close(); const state = await waitFor(home, (value) => value.state === 'recording' || value.state === 'captured', - READY_TIMEOUT_MS, 'Chrome did not start recording in time. See record.log in the TraceSift home directory.'); + READY_TIMEOUT_MS, `${platform === 'rn' ? 'The app' : 'Chrome'} did not start recording in time. See record.log in the TraceSift home directory.`, + child.pid); const sink = state.mode === 'ingest' ? `streaming into ${state.baseUrl}` : `writing to ${state.directory}`; - console.log(`Recording ${state.url || 'Chrome'}${browser ? ' in the launched browser' : ''}, ${sink}.`); + console.log(`Recording ${state.targetLabel || state.url || 'Chrome'}${browser ? ' in the launched browser' : ''}, ${sink}.`); console.log(options.duration ? `Stops automatically in ${Math.round(options.duration / 1000)}s, or run \`tracesift record stop\`.` : 'Run `tracesift record stop` when the interaction is done.'); @@ -142,16 +259,20 @@ export async function recordStop() { catch (error) { if (error?.code !== 'ESRCH') throw error; } const finished = await waitFor(home, (value) => ['captured', 'failed'].includes(value.state), - FLUSH_TIMEOUT_MS, 'Chrome did not finish flushing the trace in time.'); + FLUSH_TIMEOUT_MS, 'The trace was not flushed in time.', state.pid); if (finished.state === 'failed') throw new Error(finished.error || 'Recording failed.'); console.log(describe(finished)); for (const warning of finished.warnings ?? []) console.log(` warning: ${warning}`); return finished; } -export async function recordStatus() { +export async function recordStatus(options = {}) { const home = getHome(); const state = await readRecordState(home); + if (options.json) { + console.log(JSON.stringify({ apiVersion: 1, recording: state ?? null })); + return state; + } console.log(describe(state)); const browser = await liveBrowserState(home); if (browser) console.log(describeBrowser(browser)); @@ -200,7 +321,7 @@ export async function recordLaunch(options = {}) { export async function recordClose() { const home = getHome(); const running = await activeRecordState(home); - if (running) throw new Error(`A recording is still running (${running.url || 'Chrome'}). Stop it with \`tracesift record stop\` before closing the browser.`); + if (running) throw new Error(`A recording is still running (${running.targetLabel || running.url || 'Chrome'}). Stop it with \`tracesift record stop\` before closing the browser.`); const state = await readBrowserState(home); if (!state) throw new Error('No browser was launched with `tracesift record launch`.'); diff --git a/packages/cli/src/trace-chunker.js b/packages/cli/src/trace-chunker.js new file mode 100644 index 0000000..5d6804e --- /dev/null +++ b/packages/cli/src/trace-chunker.js @@ -0,0 +1,71 @@ +/** + * Serialise parsed trace events into the byte shape a record sink expects. + * + * The React Native path receives events as objects from `Tracing.dataCollected` + * rather than as a byte stream from `IO.read`, so this rebuilds the + * `{"traceEvents":[...]}` document and hands it to `sink.chunk` in bounded + * pieces. Chunk boundaries fall at arbitrary byte offsets, even mid-string or + * mid-escape. That is fine: both sinks are pure byte pipes (the ingest sink + * POSTs each chunk, the local sink appends it to the spool) and only the + * reassembled whole is ever parsed. + * + * @param {{ chunk(bytes: Uint8Array): Promise }} sink + * @param {{ maxBytes?: number }} [options] `maxBytes` mirrors MAX_UPLOAD_BYTES + * in record-session.js, which keeps each ingest POST under the route's cap. + */ +export function createTraceEventWriter(sink, { maxBytes = 192 * 1024 } = {}) { + /** @type {string[]} */ + let parts = []; + let bufferedBytes = 0; + let opened = false; + let ended = false; + let eventCount = 0; + + const buffer = (text) => { + parts.push(text); + bufferedBytes += Buffer.byteLength(text, 'utf8'); + }; + + // Awaited, never queued: a fast producer must wait on the sink so unbounded + // data cannot pile up behind a slow upload or disk write. + const flush = async () => { + if (bufferedBytes === 0) return; + const bytes = Buffer.from(parts.join(''), 'utf8'); + parts = []; + bufferedBytes = 0; + await sink.chunk(bytes); + }; + + const open = () => { + if (opened) return; + opened = true; + buffer('{"traceEvents":['); + }; + + return { + /** @param {Record[]} events */ + async write(events) { + if (ended) throw new Error('Cannot write trace events after end().'); + open(); + for (const event of events) { + buffer(eventCount > 0 ? `,${JSON.stringify(event)}` : JSON.stringify(event)); + eventCount += 1; + // Per event rather than per batch, so one huge dataCollected payload + // still reaches the sink in bounded chunks. + if (bufferedBytes >= maxBytes) await flush(); + } + }, + + async end() { + if (ended) return; + ended = true; + open(); + buffer(']}'); + await flush(); + }, + + get eventCount() { + return eventCount; + }, + }; +} diff --git a/packages/cli/test/metro.test.js b/packages/cli/test/metro.test.js new file mode 100644 index 0000000..89d3774 --- /dev/null +++ b/packages/cli/test/metro.test.js @@ -0,0 +1,185 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; + +import { defaultMetroOrigin, describeMetroTarget, metroTargets, parseMetroOrigin, selectMetroTarget } from '../src/metro.js'; + +async function fakeMetro(t, handler) { + const server = createServer((request, response) => handler(request, response, `http://127.0.0.1:${server.address().port}`)); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise((resolve) => server.close(resolve))); + return `http://127.0.0.1:${server.address().port}`; +} + +function json(body, status = 200) { + return (request, response) => { + response.writeHead(status, { 'content-type': 'application/json' }); + response.end(typeof body === 'string' ? body : JSON.stringify(body)); + }; +} + +function entry(port, overrides = {}) { + return { id: 'a', title: 'App', webSocketDebuggerUrl: `ws://127.0.0.1:${port}/inspector/debug?device=a`, ...overrides }; +} + +function portOf(origin) { + return new URL(origin).port; +} + +function target(overrides = {}) { + return { id: 't1', title: 'App', webSocketDebuggerUrl: 'ws://127.0.0.1:8081/x', supportsMultipleDebuggers: false, ...overrides }; +} + +test('a well-formed target parses, resolves its URL and clamps fields', async (t) => { + const long = 'x'.repeat(600); + const origin = await fakeMetro(t, (req, res, base) => + json([ + entry(portOf(base), { + id: 'one', + title: long, + appId: 'com.app', + deviceName: 'iPhone 17 Pro', + vm: 'Hermes', + reactNative: { logicalDeviceId: long, capabilities: { supportsMultipleDebuggers: true } }, + }), + ])(req, res), + ); + const targets = await metroTargets(origin); + assert.equal(targets.length, 1); + const [found] = targets; + assert.equal(found.id, 'one'); + assert.equal(found.title.length, 512); + assert.equal(found.deviceId.length, 512); + assert.equal(found.appId, 'com.app'); + assert.equal(found.vm, 'Hermes'); + assert.equal(found.supportsMultipleDebuggers, true); + assert.equal(found.webSocketDebuggerUrl, `ws://127.0.0.1:${portOf(origin)}/inspector/debug?device=a`); +}); + +test('targets with unsafe or foreign debugger URLs are dropped', async (t) => { + const origin = await fakeMetro(t, (req, res, base) => { + const p = portOf(base); + json([ + entry(p, { id: 'good' }), + entry(p, { id: 'port', webSocketDebuggerUrl: 'ws://127.0.0.1:1/x' }), + entry(p, { id: 'host', webSocketDebuggerUrl: `ws://10.0.0.5:${p}/x` }), + entry(p, { id: 'wss', webSocketDebuggerUrl: `wss://127.0.0.1:${p}/x` }), + entry(p, { id: 'http', webSocketDebuggerUrl: `http://127.0.0.1:${p}/x` }), + entry(p, { id: 'user', webSocketDebuggerUrl: `ws://user:pass@127.0.0.1:${p}/x` }), + entry(p, { id: 'hash', webSocketDebuggerUrl: `ws://127.0.0.1:${p}/x#frag` }), + { title: 'noid', webSocketDebuggerUrl: `ws://127.0.0.1:${p}/x` }, + { id: 'nows', title: 'nows' }, + ])(req, res); + }); + assert.deepEqual( + (await metroTargets(origin)).map((item) => item.id), + ['good'], + ); +}); + +test('an oversized body is rejected', async (t) => { + const origin = await fakeMetro(t, json(JSON.stringify([{ id: 'x'.repeat(1024 * 1024 + 10) }]))); + await assert.rejects(metroTargets(origin), { message: 'Metro returned too many targets.' }); +}); + +test('a non-Metro answer is reported as such', async (t) => { + const missing = await fakeMetro(t, json({}, 404)); + await assert.rejects(metroTargets(missing), (error) => { + assert.match(error.message, new RegExp(`^${missing.replace(/\./g, '\\.')} answered, but it is not a Metro server`)); + return true; + }); + const object = await fakeMetro(t, json({ nope: true })); + await assert.rejects(metroTargets(object), /is not a Metro server/); +}); + +test('a closed port reports that no Metro server is listening', async (t) => { + const origin = await fakeMetro(t, json([])); + const port = portOf(origin); + const closed = await new Promise((resolve) => { + const probe = createServer(); + probe.listen(0, '127.0.0.1', () => { + const { port: free } = probe.address(); + probe.close(() => resolve(free)); + }); + }); + assert.notEqual(String(closed), port); + await assert.rejects(metroTargets(`http://127.0.0.1:${closed}`), (error) => { + assert.match(error.message, new RegExp(`^No Metro server is listening on http://127\\.0\\.0\\.1:${closed}\\. Start it with`)); + return true; + }); +}); + +test('selectMetroTarget returns a single target', () => { + const only = target(); + assert.equal(selectMetroTarget([only]), only); +}); + +test('selectMetroTarget honours each selector', () => { + const a = target({ id: 'a', title: 'Alpha', appId: 'com.alpha', deviceName: 'iPhone', deviceId: '1' }); + const b = target({ id: 'b', title: 'Beta', appId: 'com.beta', deviceName: 'Pixel', deviceId: '2' }); + assert.equal(selectMetroTarget([a, b], { targetId: 'b' }), b); + assert.equal(selectMetroTarget([a, b], { app: 'com.alpha' }), a); + assert.equal(selectMetroTarget([a, b], { app: 'BETA' }), b); + assert.equal(selectMetroTarget([a, b], { device: 'pixel' }), b); + assert.throws(() => selectMetroTarget([a, b], { app: 'nope' }), { + message: 'No app connected to Metro matches --app nope. Run `tracesift record targets --platform rn` to see what is connected.', + }); + assert.throws(() => selectMetroTarget([a, b], { targetId: 'z', app: 'nope' }), /--target-id z\./); +}); + +test('selectMetroTarget skips JavaScriptCore targets unless everything is one', () => { + const hermes = target({ id: 'h', appId: 'h', vm: 'Hermes' }); + const jsc = target({ id: 'j', appId: 'j', vm: 'JavaScriptCore' }); + assert.equal(selectMetroTarget([jsc, hermes]), hermes); + assert.throws(() => selectMetroTarget([jsc]), /JavaScriptCore, which has no sampling profiler/); +}); + +test('selectMetroTarget keeps the newest of duplicate connections', () => { + const old = target({ id: 'old', appId: 'com.a', deviceId: 'd' }); + const fresh = target({ id: 'new', appId: 'com.a', deviceId: 'd' }); + assert.equal(selectMetroTarget([old, fresh]), fresh); +}); + +test('selectMetroTarget asks to choose between distinct apps', () => { + const a = target({ id: 'a', title: 'Alpha', appId: 'com.alpha', vm: 'Hermes', deviceName: 'iPhone' }); + const b = target({ id: 'b', title: 'Beta', appId: 'com.beta' }); + assert.throws( + () => selectMetroTarget([a, b]), + (error) => { + assert.equal( + error.message, + ['Metro has 2 connected apps. Choose one with --app, --device or --target-id:', ' Alpha (Hermes) — iPhone — --target-id a', ' Beta — --target-id b'].join('\n'), + ); + return true; + }, + ); +}); + +test('selectMetroTarget explains an empty target list', () => { + assert.throws(() => selectMetroTarget([], { origin: 'http://127.0.0.1:8081' }), /^Error: Metro is running on http:\/\/127\.0\.0\.1:8081, but no app is connected to it\./); +}); + +test('describeMetroTarget falls back through appId and id', () => { + assert.equal(describeMetroTarget({ id: 'i', appId: 'com.x', title: '' }), 'com.x'); + assert.equal(describeMetroTarget({ id: 'i', title: '' }), 'i'); +}); + +test('parseMetroOrigin accepts a bare host and rejects remote hosts', () => { + assert.equal(parseMetroOrigin('localhost:8081').href, 'http://localhost:8081/'); + assert.throws(() => parseMetroOrigin('https://example.com'), { + message: 'Metro URL must point at localhost; example.com is not a loopback address.', + }); + assert.throws(() => parseMetroOrigin('ftp://localhost'), { message: 'Metro URL must be an http or https address.' }); +}); + +test('defaultMetroOrigin honours RCT_METRO_PORT', (t) => { + const previous = process.env.RCT_METRO_PORT; + t.after(() => { + if (previous === undefined) delete process.env.RCT_METRO_PORT; + else process.env.RCT_METRO_PORT = previous; + }); + process.env.RCT_METRO_PORT = '8090'; + assert.equal(defaultMetroOrigin(), 'http://127.0.0.1:8090'); + process.env.RCT_METRO_PORT = '99999'; + assert.equal(defaultMetroOrigin(), 'http://127.0.0.1:8081'); +}); diff --git a/packages/cli/test/record-rn-session.test.js b/packages/cli/test/record-rn-session.test.js new file mode 100644 index 0000000..95527f9 --- /dev/null +++ b/packages/cli/test/record-rn-session.test.js @@ -0,0 +1,263 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; +import { mkdtemp, readFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { gunzipSync } from 'node:zlib'; + +import { cpuProfileToTraceEvents, runRnRecording } from '../src/record-rn-session.js'; +import { TRACE_CATEGORIES } from '../src/record-session.js'; +import { readRecordState } from '../src/record-state.js'; + +async function temporaryDirectory(t) { + const directory = await mkdtemp(join(tmpdir(), 'tracesift-rn-')); + t.after(() => rm(directory, { recursive: true, force: true })); + return directory; +} + +const TARGET = { id: 'page-1', title: 'Hermes React Native', appId: 'com.example.app', deviceName: 'iPhone 17 Pro', vm: 'Hermes' }; + +/** + * A Metro that serves /json/list, plus a stand-in for the global WebSocket that + * speaks the CDP message protocol. `script(message, socket)` plays the app. + */ +async function fakeApp(t, script) { + const server = createServer((request, response) => { + const port = server.address().port; + response.writeHead(200, { 'content-type': 'application/json' }); + response.end(JSON.stringify([{ ...TARGET, webSocketDebuggerUrl: `ws://127.0.0.1:${port}/inspector/debug?device=a` }])); + }); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + t.after(() => new Promise((resolve) => { server.closeAllConnections?.(); server.close(resolve); })); + + const received = []; + const constructed = []; + const original = globalThis.WebSocket; + + class FakeSocket extends EventTarget { + constructor(url, options) { + super(); + this.url = url; + this.readyState = 0; + constructed.push({ url, options }); + setImmediate(() => { + this.readyState = 1; + this.dispatchEvent(new Event('open')); + }); + } + + send(data) { + const message = JSON.parse(data); + received.push(message); + setImmediate(() => script(message, this)); + } + + close() { + if (this.readyState > 1) return; + this.readyState = 3; + this.dispatchEvent(Object.assign(new Event('close'), { code: 1000, reason: '' })); + } + + reply(message, result = {}) { + this.push({ id: message.id, result }); + } + + fail(message, text, code) { + this.push({ id: message.id, error: { code, message: text } }); + } + + notify(method, params) { + this.push({ method, params }); + } + + push(payload) { + if (this.readyState !== 1) return; + this.dispatchEvent(Object.assign(new Event('message'), { data: JSON.stringify(payload) })); + } + } + + globalThis.WebSocket = FakeSocket; + t.after(() => { globalThis.WebSocket = original; }); + + return { + metro: `http://127.0.0.1:${server.address().port}`, + received, + constructed, + methods: () => received.map((message) => message.method), + }; +} + +async function record(t, app, home, overrides = {}) { + return runRnRecording({ home, metro: app.metro, sink: 'local', sourceMaps: false, duration: 50, ...overrides }); +} + +async function readExport(path) { + return JSON.parse(gunzipSync(await readFile(path)).toString('utf8')); +} + +const SAMPLE_EVENTS = [ + { name: 'RunTask', cat: 'disabled-by-default-devtools.timeline', ph: 'X', pid: 7, tid: 11, ts: 1000, dur: 40 }, + { name: 'FunctionCall', cat: 'devtools.timeline', ph: 'X', pid: 7, tid: 11, ts: 1010, dur: 20 }, +]; + +/** An app that traces successfully and flushes `SAMPLE_EVENTS` on Tracing.end. */ +function tracingApp(message, socket) { + if (message.method === 'Tracing.start') return socket.reply(message); + if (message.method === 'Tracing.end') { + socket.reply(message); + socket.notify('Tracing.dataCollected', { value: [SAMPLE_EVENTS[0]] }); + socket.notify('Tracing.dataCollected', { value: [SAMPLE_EVENTS[1]] }); + socket.notify('Tracing.tracingComplete', {}); + return undefined; + } + return socket.reply(message); +} + +test('a React Native recording is exported in the enhanced-trace envelope', async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, tracingApp); + const result = await record(t, app, home); + + const document = await readExport(result.path); + assert.equal(document.metadata.enhancedTraceVersion, 1); + const { target } = document.metadata.traceSift; + assert.equal(target.platform, 'react-native'); + assert.equal(target.targetId, TARGET.id); + assert.equal(target.appId, TARGET.appId); + assert.equal(target.deviceName, TARGET.deviceName); + + const names = document.traceEvents.map((event) => event.name); + assert.deepEqual(names.filter((name) => SAMPLE_EVENTS.some((event) => event.name === name)), SAMPLE_EVENTS.map((event) => event.name)); + for (const sent of SAMPLE_EVENTS) { + assert.ok(document.traceEvents.some((event) => event.name === sent.name && event.ts === sent.ts), `${sent.name} is exported`); + } + assert.ok(!names.includes('TracingStartedInBrowser')); + + const start = app.received.find((message) => message.method === 'Tracing.start'); + assert.equal(start.params.categories, TRACE_CATEGORIES); + assert.equal((await readRecordState(home)).state, 'captured'); +}); + +test('a React Native recording never enables the domains React Native rejects or addresses a session', async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, tracingApp); + await record(t, app, home); + + const methods = app.methods(); + assert.ok(methods.includes('Tracing.start')); + assert.ok(methods.includes('Tracing.end')); + for (const forbidden of ['Debugger.enable', 'Page.enable', 'Target.setAutoAttach']) { + assert.ok(!methods.includes(forbidden), `${forbidden} was never sent`); + } + assert.ok(app.received.every((message) => !('sessionId' in message))); +}); + +test('the inspector socket is opened with the Metro origin as its Origin header', async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, tracingApp); + await record(t, app, home); + + assert.equal(app.constructed.length, 1); + assert.match(app.constructed[0].url, new RegExp(`^ws://127\\.0\\.0\\.1:${new URL(app.metro).port}/`)); + assert.deepEqual(app.constructed[0].options, { headers: { Origin: app.metro } }); +}); + +for (const [label, text, expected] of [ + [ + 'an attached debugger', + 'Debugger domain is expected to be disabled before starting Tracing', + 'A debugger is attached to that app. Close React Native DevTools, then run this again.', + ], + [ + 'a trace already in progress', + 'Tracing has already been started', + 'That app is already being profiled. Hermes has one sampler, so stop the recording in React Native DevTools (or close that window) and run this again.', + ], + [ + 'more than one React Native host', + 'Cannot trace: multiple React Native hosts are registered', + 'The app has more than one React Native host registered, and React Native will not trace it. Reload the app, then run this again.', + ], +]) { + test(`a Tracing.start rejection for ${label} is explained to the developer`, async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, (message, socket) => { + if (message.method === 'Tracing.start') return socket.fail(message, text, -32000); + return socket.reply(message); + }); + await assert.rejects(record(t, app, home), { message: expected }); + const state = await readRecordState(home); + assert.equal(state.state, 'failed'); + assert.equal(state.error, expected); + }); +} + +test('a runtime without Tracing falls back to the Profiler domain', async (t) => { + const home = await temporaryDirectory(t); + const nodes = [ + { id: 1, callFrame: { functionName: '(root)', scriptId: '0', url: '', lineNumber: 0, columnNumber: 0 }, children: [2] }, + { id: 2, callFrame: { functionName: 'work', scriptId: '1', url: '', lineNumber: 1, columnNumber: 2 } }, + ]; + const profile = { nodes, startTime: 5000, samples: [2, 2, 1], timeDeltas: [10, 10, 10] }; + const app = await fakeApp(t, (message, socket) => { + if (message.method === 'Tracing.start') return socket.fail(message, 'Tracing.start is not found', -32601); + if (message.method === 'Profiler.stop') return socket.reply(message, { profile }); + return socket.reply(message); + }); + const result = await record(t, app, home); + + assert.ok(app.methods().includes('Profiler.start')); + const document = await readExport(result.path); + assert.ok(document.traceEvents.some((event) => event.name === 'Profile')); + const chunks = document.traceEvents.filter((event) => event.name === 'ProfileChunk'); + assert.ok(chunks.length >= 1); + assert.deepEqual(chunks[0].args.data.cpuProfile.nodes, nodes); + assert.ok(result.warnings.some((warning) => /older Profiler domain/.test(warning))); +}); + +test('a runtime with neither Tracing nor Profiler says it has no CPU profiler', async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, (message, socket) => { + if (message.method === 'Tracing.start' || message.method === 'Profiler.start') { + return socket.fail(message, `${message.method} is not found`, -32601); + } + return socket.reply(message); + }); + await assert.rejects(record(t, app, home), /does not expose a CPU profiler/); + assert.match((await readRecordState(home)).error, /does not expose a CPU profiler/); +}); + +test('an app that disconnects mid-recording fails the recording and records why', async (t) => { + const home = await temporaryDirectory(t); + const app = await fakeApp(t, (message, socket) => { + socket.reply(message); + if (message.method === 'Tracing.start') setImmediate(() => socket.close()); + }); + const expected = 'The app disconnected from Metro before the recording finished. Nothing was captured — reload the app and record again.'; + await assert.rejects(record(t, app, home, { duration: 0 }), { message: expected }); + + const state = await readRecordState(home); + assert.equal(state.state, 'failed'); + assert.equal(state.error, expected); +}); + +test('a long CPU profile is split into chunks that carry the node table once', () => { + const total = 25_000; + const nodes = [{ id: 1, callFrame: { functionName: '(root)', url: '' } }]; + const samples = Array.from({ length: total }, (_, index) => (index % 3) + 1); + const timeDeltas = Array.from({ length: total }, (_, index) => index); + const events = cpuProfileToTraceEvents({ nodes, startTime: 4242, samples, timeDeltas }); + + const [profile, ...chunks] = events; + assert.equal(profile.name, 'Profile'); + assert.equal(profile.args.data.startTime, 4242); + assert.equal(chunks.length, 3); + assert.ok(chunks.every((chunk) => chunk.name === 'ProfileChunk')); + assert.deepEqual(chunks.map((chunk) => 'nodes' in chunk.args.data.cpuProfile), [true, false, false]); + assert.deepEqual(chunks[0].args.data.cpuProfile.nodes, nodes); + assert.deepEqual(chunks.map((chunk) => chunk.args.data.cpuProfile.samples.length), [10_000, 10_000, 5_000]); + assert.deepEqual(chunks.map((chunk) => chunk.args.data.timeDeltas.length), [10_000, 10_000, 5_000]); + assert.deepEqual(chunks[1].args.data.cpuProfile.samples, samples.slice(10_000, 20_000)); + assert.deepEqual(chunks[2].args.data.timeDeltas, timeDeltas.slice(20_000)); +}); diff --git a/packages/cli/test/record.test.js b/packages/cli/test/record.test.js index 9e42a87..632e61e 100644 --- a/packages/cli/test/record.test.js +++ b/packages/cli/test/record.test.js @@ -7,7 +7,7 @@ import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { gunzipSync } from 'node:zlib'; -import { assertRecordOptions, parseDuration, recordClose } from '../src/record.js'; +import { assertRecordOptions, parseDuration, parsePlatform, recordClose, recordTargets } from '../src/record.js'; import { createIngestSink, createLocalSink } from '../src/record-sink.js'; import { activeRecordState, clearBrowserState, clearRecordState, liveBrowserState, readBrowserState, readRecordState, writeBrowserState, writeRecordState, @@ -248,3 +248,58 @@ test('record options are rejected for the subcommands that would ignore them', ( assert.throws(() => assertRecordOptions('explore', undefined, { url: 'x' }), /only supported by tracesift record/); assert.throws(() => assertRecordOptions('start', undefined, { sink: 'local' }), /only supported by tracesift record/); }); + +test('a platform is one of the two this records, and defaults to Chrome', () => { + assert.equal(parsePlatform(undefined), 'chrome'); + assert.equal(parsePlatform('chrome'), 'chrome'); + assert.equal(parsePlatform('rn'), 'rn'); + assert.equal(parsePlatform('react-native'), 'rn'); + assert.throws(() => parsePlatform('android'), /Platform must be chrome or rn\./); +}); + +test('a flag meant for the other platform is refused rather than ignored', () => { + assert.doesNotThrow(() => assertRecordOptions('record', 'start', { + platform: 'rn', metro: 'http://127.0.0.1:8081', app: 'com.example', device: 'iPhone', 'target-id': 'a-1', duration: '5s', sink: 'local', + })); + assert.doesNotThrow(() => assertRecordOptions('record', 'targets', { platform: 'rn', metro: 'http://127.0.0.1:8081', json: true })); + + for (const option of ['url', 'chrome', 'user-data-dir', 'headless']) { + assert.throws(() => assertRecordOptions('record', 'start', { platform: 'rn', [option]: 'x' }), + new RegExp(`--${option} applies to Chrome`)); + } + for (const option of ['metro', 'app', 'device', 'target-id', 'no-source-maps']) { + assert.throws(() => assertRecordOptions('record', 'start', { [option]: 'x' }), + new RegExp(`--${option} applies to tracesift record start --platform rn`)); + } +}); + +test('there is no React Native browser to launch or close', () => { + for (const subcommand of ['launch', 'close']) { + assert.throws(() => assertRecordOptions('record', subcommand, { platform: 'rn' }), + /There is nothing to launch for React Native/); + assert.doesNotThrow(() => assertRecordOptions('record', subcommand, { platform: 'chrome' })); + } +}); + +test('targets refuses to list anything but React Native apps', async () => { + await assert.rejects(() => recordTargets({ platform: 'chrome' }), /lists React Native apps/); +}); + +test('a React Native capture target carries the app and device instead of a tab', async (t) => { + const home = await temporaryHome(t); + const target = { + platform: 'react-native', title: 'AwesomeApp (Hermes) — iPhone 17 Pro', url: 'http://127.0.0.1:8081', + targetId: 'device-1-page-1', appId: 'com.awesome.app', deviceName: 'iPhone 17 Pro', + }; + const sink = await createLocalSink(home, target); + await sink.chunk(Buffer.from('{"traceEvents":[{"name":"TracingStartedInPage","ph":"I","pid":1,"tid":1,"ts":1}]}')); + const result = await sink.finalize({ scripts: [], sourceMaps: [] }); + + const document = JSON.parse(gunzipSync(await readFile(result.path)).toString('utf8')); + assert.equal(document.metadata.traceSift.target.platform, 'react-native'); + assert.equal(document.metadata.traceSift.target.appId, 'com.awesome.app'); + assert.equal(document.metadata.traceSift.target.deviceName, 'iPhone 17 Pro'); + assert.ok(!('tabId' in document.metadata.traceSift.target)); + // Nothing was rebuilt: React Native names its own frames. + assert.ok(!document.traceEvents.some((event) => event.name === 'TracingStartedInBrowser')); +}); diff --git a/packages/cli/test/trace-chunker.test.js b/packages/cli/test/trace-chunker.test.js new file mode 100644 index 0000000..ce5e843 --- /dev/null +++ b/packages/cli/test/trace-chunker.test.js @@ -0,0 +1,139 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { appendFile, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { gunzipSync } from 'node:zlib'; + +import { createTraceEventWriter } from '../src/trace-chunker.js'; +import { copyTraceEvents, writeTraceExport } from '../src/trace-export.js'; + +async function temporaryDirectory(t) { + const directory = await mkdtemp(join(tmpdir(), 'tracesift-chunker-')); + t.after(() => rm(directory, { recursive: true, force: true })); + return directory; +} + +/** A sink that behaves like the local one: appends every chunk to a spool. */ +async function fileSink(directory) { + const spool = join(directory, 'trace.spool'); + await writeFile(spool, ''); + const sizes = []; + return { spool, sizes, async chunk(bytes) { sizes.push(bytes.byteLength); await appendFile(spool, bytes); } }; +} + +async function copied(spool) { + const parts = []; + const output = { write(chunk) { parts.push(Buffer.from(chunk)); return true; }, once() {} }; + const eventCount = await copyTraceEvents(spool, output); + return { eventCount, events: JSON.parse(`[${Buffer.concat(parts).toString('utf8')}]`) }; +} + +async function roundTrip(t, events, options, batchSize = events.length || 1) { + const directory = await temporaryDirectory(t); + const sink = await fileSink(directory); + const writer = createTraceEventWriter(sink, options); + for (let index = 0; index < events.length; index += batchSize) await writer.write(events.slice(index, index + batchSize)); + await writer.end(); + return { writer, sink, ...(await copied(sink.spool)) }; +} + +test('events round-trip through copyTraceEvents and the counts agree', async (t) => { + const input = [ + { name: 'RunTask', ph: 'X', pid: 1, tid: 2, ts: 10, dur: 5 }, + { name: 'FunctionCall', ph: 'X', pid: 1, tid: 2, ts: 20, args: { data: { url: 'a.js', line: 3 } } }, + { name: 'Unicode', ph: 'I', ts: 30, args: { s: 'héllo ☃ 日本' } }, + ]; + const { writer, events, eventCount } = await roundTrip(t, input, undefined, 2); + assert.deepEqual(events, input); + assert.equal(eventCount, input.length); + assert.equal(writer.eventCount, eventCount); +}); + +test('JSON punctuation, quotes and backslashes inside strings survive the scanner', async (t) => { + const input = [ + { name: 'X', args: { s: 'a{b}c[d]e"f\\g' } }, + { name: 'Y', args: { s: '}]}]"\\"\\\\' } }, + ]; + // A tiny budget also splits chunks inside these strings. + const { writer, events, eventCount } = await roundTrip(t, input, { maxBytes: 8 }); + assert.deepEqual(events, input); + assert.equal(eventCount, 2); + assert.equal(writer.eventCount, 2); +}); + +test('a single event larger than maxBytes still round-trips', async (t) => { + const input = [{ name: 'Big', args: { s: 'x{"\\'.repeat(500) } }, { name: 'After' }]; + const { events, eventCount, sink } = await roundTrip(t, input, { maxBytes: 64 }); + assert.deepEqual(events, input); + assert.equal(eventCount, 2); + assert.ok(sink.sizes.length > 1); +}); + +test('an empty trace is still a valid document with no events', async (t) => { + const directory = await temporaryDirectory(t); + const sink = await fileSink(directory); + const writer = createTraceEventWriter(sink); + await writer.end(); + assert.equal(await readFile(sink.spool, 'utf8'), '{"traceEvents":[]}'); + const { events, eventCount } = await copied(sink.spool); + assert.deepEqual(events, []); + assert.equal(eventCount, 0); + assert.equal(writer.eventCount, 0); +}); + +test('a small maxBytes forces many chunks without changing the result', async (t) => { + const input = Array.from({ length: 200 }, (_, index) => ({ name: `Event${index}`, ph: 'X', ts: index, args: { payload: 'p'.repeat(20) } })); + const { events, eventCount, sink, writer } = await roundTrip(t, input, { maxBytes: 100 }, 7); + assert.ok(sink.sizes.length > 10, `expected many chunks, got ${sink.sizes.length}`); + assert.deepEqual(events, input); + assert.equal(eventCount, 200); + assert.equal(writer.eventCount, 200); +}); + +test('the writer awaits each sink.chunk before producing the next', async () => { + let active = 0; + let overlapped = false; + let calls = 0; + const sink = { + async chunk() { + calls += 1; + active += 1; + if (active > 1) overlapped = true; + await new Promise((resolve) => setImmediate(resolve)); + active -= 1; + }, + }; + const writer = createTraceEventWriter(sink, { maxBytes: 32 }); + await writer.write(Array.from({ length: 50 }, (_, index) => ({ name: `E${index}`, ts: index }))); + assert.equal(active, 0, 'write() resolved while a chunk was still in flight'); + await writer.end(); + assert.equal(active, 0); + assert.equal(overlapped, false); + assert.ok(calls > 5); +}); + +test('React Native shaped events export through writeTraceExport intact', async (t) => { + const directory = await temporaryDirectory(t); + const sink = await fileSink(directory); + const input = [ + { name: 'TracingStartedInPage', cat: 'disabled-by-default-devtools.timeline', ph: 'I', pid: 1, tid: 1, ts: 1, args: { data: { frames: [{ frame: 'F1', url: 'app://rn' }] } } }, + { name: 'Profile', cat: 'disabled-by-default-v8.cpu_profiler', ph: 'P', id: '0x1', pid: 1, tid: 2, ts: 2, args: { data: { startTime: 2 } } }, + { name: 'ProfileChunk', cat: 'disabled-by-default-v8.cpu_profiler', ph: 'P', id: '0x1', pid: 1, tid: 2, ts: 3, args: { data: { + cpuProfile: { nodes: [{ id: 1, callFrame: { functionName: '(root)', url: '', lineNumber: -1, columnNumber: -1 } }], samples: [1] }, + timeDeltas: [1], + } } }, + ]; + const writer = createTraceEventWriter(sink, { maxBytes: 128 }); + await writer.write(input); + await writer.end(); + + const destination = join(directory, 'Trace.json.gz'); + const metadata = { enhancedTraceVersion: 1, traceSift: { captureId: 'abc' } }; + const written = await writeTraceExport({ spool: sink.spool, destination, metadata }); + const document = JSON.parse(gunzipSync(await readFile(destination)).toString('utf8')); + + assert.deepEqual(document.traceEvents, input); + assert.deepEqual(document.metadata, metadata); + assert.equal(written.eventCount, writer.eventCount); +}); diff --git a/scripts/test-codex-local.sh b/scripts/test-codex-local.sh new file mode 100755 index 0000000..8c14a90 --- /dev/null +++ b/scripts/test-codex-local.sh @@ -0,0 +1,139 @@ +#!/bin/bash +# +# Serve this checkout of TraceSift to a locally installed Mobile Dev plugin, so +# the plugin's panel exercises the code in this working tree rather than the +# published CLI and the installed app. +# +# Two things have to come from here rather than from a release: `tracesift +# record`, which no published CLI has yet, and gzip support in the analyze +# route, without which a recorded trace reaches no cards. Both live in this +# tree, so this script points the plugin at the tree. +# +# It leaves two pointer files the plugin's own scripts/test-codex-local.sh +# reads, then stays in the foreground serving the app. Stop it with Ctrl-C. +# +# scripts/test-codex-local.sh [--port 3100] [--home ] +# +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +POINTER_FILE="${TMPDIR%/}/tracesift-codex-test-home" +CLI_POINTER_FILE="${TMPDIR%/}/tracesift-codex-test-cli" +# A stable home, so analyses and recordings survive a restart of this script. +HOME_DIR="${TMPDIR%/}/tracesift-codex-test-home.d" +PORT="" + +usage() { echo "Usage: $0 [--port ] [--home ]" >&2; } + +while [[ $# -gt 0 ]]; do + case "$1" in + --port) PORT="${2:-}"; shift ;; + --home) HOME_DIR="${2:-}"; shift ;; + *) usage; exit 2 ;; + esac + shift +done + +cd "$ROOT" + +node -e ' + const [major, minor] = process.versions.node.split(".").map(Number); + if (major < 22 || (major === 22 && minor < 19)) { + console.error(`Node.js 22.19.0 or newer is required; found ${process.version}.`); + process.exit(1); + } +' + +if [[ ! -d node_modules ]]; then + echo "Installing dependencies..." >&2 + npm ci +fi + +# Never 3000 by default: that is where the ordinary `npm run dev` lives, and +# taking it would stop the browser window you already have open. +if [[ -z "$PORT" ]]; then + PORT="$(node -e ' + const { createServer } = require("node:net"); + const server = createServer(); + server.listen(0, "127.0.0.1", () => { const { port } = server.address(); server.close(() => console.log(port)); }); + ')" +fi + +mkdir -p "$HOME_DIR" +chmod 700 "$HOME_DIR" + +# The plugin spawns this by path, so it has to be an executable that forwards +# to the CLI in this tree. +CLI_WRAPPER="$HOME_DIR/tracesift" +cat > "$CLI_WRAPPER" </dev/null 2>&1 || true + rm -f "$POINTER_FILE" "$CLI_POINTER_FILE" "$HOME_DIR/service.json" + if [[ -n "${SERVER_PID:-}" ]]; then kill "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true; fi + exit $status +} +trap cleanup INT TERM EXIT + +echo "Starting TraceSift from this checkout on $BASE_URL..." +TRACE_SIFT_HOME="$HOME_DIR" \ +TRACE_SIFT_INTEGRATION_TOKEN="$TOKEN" \ +TRACE_SIFT_INSTANCE="$INSTANCE" \ +TRACE_SIFT_VERSION="0.0.0-codex-local" \ + npm run dev -- --port "$PORT" & +SERVER_PID=$! + +# Wait for the integration API itself, not just the port: the app compiles on +# first request, and the plugin's health check is the same call. +DEADLINE=$(( $(date +%s) + 240 )) +until curl -fsS -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/integration/v1/health" >/dev/null 2>&1; do + if ! kill -0 "$SERVER_PID" 2>/dev/null; then echo "The dev server exited before it was ready." >&2; exit 1; fi + if [[ $(date +%s) -gt $DEADLINE ]]; then echo "TraceSift did not become ready in four minutes." >&2; exit 1; fi + sleep 1 +done + +# The descriptor `tracesift start` would have written. The plugin reuses a +# healthy service rather than spawning one, which is how the dev server stands +# in for an installed release. +node -e ' + const { writeFileSync } = require("node:fs"); + const [file, baseUrl, token, instance, pid] = process.argv.slice(1); + writeFileSync(file, JSON.stringify({ + version: "0.0.0-codex-local", apiVersion: 1, pid: Number(pid), childPid: Number(pid), + instance, baseUrl, token, startedAt: Date.now(), + }), { mode: 0o600 }); +' "$HOME_DIR/service.json" "$BASE_URL" "$TOKEN" "$INSTANCE" "$SERVER_PID" +chmod 600 "$HOME_DIR/service.json" + +printf '%s' "$HOME_DIR" > "$POINTER_FILE" +printf '%s' "$CLI_WRAPPER" > "$CLI_POINTER_FILE" + +cat < && scripts/test-codex-local.sh + +Then in Codex: Mobile Dev -> TraceSift -> JavaScript CPU -> Record a web app. + +Ctrl-C here when you are done; it quits any browser \`record launch\` left open. +EOF + +wait "$SERVER_PID" diff --git a/src/app/api/captures/route.ts b/src/app/api/captures/route.ts index cc2a2a6..7c9c7f3 100644 --- a/src/app/api/captures/route.ts +++ b/src/app/api/captures/route.ts @@ -7,17 +7,32 @@ export async function GET(): Promise { } export async function POST(request: Request): Promise { - let body: { title?: unknown; target?: { tabId?: unknown; title?: unknown; url?: unknown } }; + let body: { title?: unknown; target?: { + tabId?: unknown; title?: unknown; url?: unknown; + platform?: unknown; targetId?: unknown; appId?: unknown; deviceName?: unknown; + }; + }; try { body = await request.json(); } catch { return Response.json({ error: "Expected capture details." }, { status: 400 }); } const target = body.target; - if (!target || typeof target.tabId !== "number" || typeof target.title !== "string" || typeof target.url !== "string") { - return Response.json({ error: "Choose a Chrome tab to capture." }, { status: 400 }); + if ( + !target || typeof target.title !== "string" || typeof target.url !== "string" + || (target.platform !== "react-native" && typeof target.tabId !== "number") + ) { + return Response.json({ error: "Choose a Chrome tab or a React Native app to capture." }, { status: 400 }); } try { const result = await createCapture({ title: typeof body.title === "string" ? body.title : undefined, - target: { tabId: target.tabId, title: target.title, url: target.url }, + target: { + ...(typeof target.tabId === "number" ? { tabId: target.tabId } : {}), + title: target.title, + url: target.url, + ...(target.platform === "chrome" || target.platform === "react-native" ? { platform: target.platform } : {}), + ...(typeof target.targetId === "string" ? { targetId: target.targetId } : {}), + ...(typeof target.appId === "string" ? { appId: target.appId } : {}), + ...(typeof target.deviceName === "string" ? { deviceName: target.deviceName } : {}), + }, }); return Response.json(result, { status: 201 }); } catch (error) { diff --git a/src/app/capture/page.tsx b/src/app/capture/page.tsx index ddb6ad6..17cffb2 100644 --- a/src/app/capture/page.tsx +++ b/src/app/capture/page.tsx @@ -8,7 +8,8 @@ import { Button, PluginHeader, PluginShell } from "@rozenite/ui"; import { ThemeGate } from "@/app/theme-gate"; import type { CaptureRecord, CaptureTarget } from "@/lib/capture-types"; -type ExtensionReply = { ok: boolean; error?: string; targets?: CaptureTarget[] }; +type ChromeTarget = CaptureTarget & { tabId: number }; +type ExtensionReply = { ok: boolean; error?: string; targets?: ChromeTarget[] }; const REQUEST_SOURCE = "tracesift-web-v1"; const RESPONSE_SOURCE = "tracesift-extension-v1"; @@ -29,7 +30,7 @@ function stateLabel(state: CaptureRecord["state"]): string { function CapturePage() { const [extensionState, setExtensionState] = useState<"disconnected" | "connecting" | "connected">("disconnected"); - const [targets, setTargets] = useState([]); + const [targets, setTargets] = useState([]); const [selectedTab, setSelectedTab] = useState(null); const [captures, setCaptures] = useState([]); const [busy, setBusy] = useState(false); diff --git a/src/app/js-profiler/normalize.ts b/src/app/js-profiler/normalize.ts index 3517cfc..32769aa 100644 --- a/src/app/js-profiler/normalize.ts +++ b/src/app/js-profiler/normalize.ts @@ -7,6 +7,7 @@ import type { JsStackSignature, JsTimeBucket, } from "./types"; +import { stripRequest } from "../../lib/source-location.ts"; const NOISE_NAMES = new Set([ "(idle)", @@ -356,12 +357,16 @@ function isHttpUrl(url: string): boolean { function deriveModuleName(url: string): string { if (!url) return "(anonymous)"; + // Metro appends its build options to the bundle path itself, so the last + // path segment of a React Native frame's URL is the options and not a file + // name. `stripRequest` already owns that distinction. + const path = stripRequest(url); try { - const parsed = new URL(url); + const parsed = new URL(path); const parts = parsed.pathname.split("/"); - return parts.at(-1) || parsed.hostname || url; + return parts.at(-1) || parsed.hostname || path; } catch { - const parts = url.split(/[/\\]/); - return parts.at(-1) || url; + const parts = path.split(/[/\\]/); + return parts.at(-1) || path; } } diff --git a/src/lib/capture-store.ts b/src/lib/capture-store.ts index cc498ad..9b53258 100644 --- a/src/lib/capture-store.ts +++ b/src/lib/capture-store.ts @@ -76,11 +76,18 @@ function cleanText(value: string, maximum: number): string { } function safeTarget(target: CaptureTarget): CaptureTarget { - if (!Number.isSafeInteger(target.tabId) || target.tabId < 0) throw new Error("Choose a valid Chrome tab."); + if (target.tabId !== undefined && (!Number.isSafeInteger(target.tabId) || target.tabId < 0)) throw new Error("Choose a valid Chrome tab."); + const targetId = typeof target.targetId === "string" ? cleanText(target.targetId, 300) : ""; + const appId = typeof target.appId === "string" ? cleanText(target.appId, 300) : ""; + const deviceName = typeof target.deviceName === "string" ? cleanText(target.deviceName, 300) : ""; return { - tabId: target.tabId, + ...(target.tabId !== undefined ? { tabId: target.tabId } : {}), title: cleanText(target.title || "Untitled tab", 300), url: cleanText(target.url || "", 4000), + ...(target.platform === "chrome" || target.platform === "react-native" ? { platform: target.platform } : {}), + ...(targetId ? { targetId } : {}), + ...(appId ? { appId } : {}), + ...(deviceName ? { deviceName } : {}), }; } diff --git a/src/lib/capture-types.ts b/src/lib/capture-types.ts index 5928f39..8d9ca8d 100644 --- a/src/lib/capture-types.ts +++ b/src/lib/capture-types.ts @@ -22,9 +22,15 @@ export type CaptureStopReason = | "error"; export interface CaptureTarget { - tabId: number; + /** Chrome's tab id. Absent for a React Native capture, which has no tab. */ + tabId?: number; title: string; url: string; + platform?: "chrome" | "react-native"; + /** React Native: the Metro inspector target, its app bundle id and the device it runs on. */ + targetId?: string; + appId?: string; + deviceName?: string; } export interface CaptureRecord { diff --git a/src/lib/source-location.ts b/src/lib/source-location.ts index f8db71f..fcbbc42 100644 --- a/src/lib/source-location.ts +++ b/src/lib/source-location.ts @@ -124,7 +124,7 @@ function stripContentHash(fileName: string): string { * mostly separators — Metro's `//&platform=` form is one character away from it. * Scanning is the same rule with nothing to backtrack over. */ -function stripRequest(url: string): string { +export function stripRequest(url: string): string { let end = url.length; for (let index = 0; index < url.length; index += 1) { const character = url[index]; diff --git a/tests/capture-store.test.mjs b/tests/capture-store.test.mjs index c0ef529..fbffc17 100644 --- a/tests/capture-store.test.mjs +++ b/tests/capture-store.test.mjs @@ -124,4 +124,18 @@ test("only one active capture can exist", async () => { await store.failCapture(second.capture.id, second.uploadToken, { error: "test cleanup", interrupted: true }); }); +test("a React Native target without a tab id is accepted and its fields round-trip", async () => { + const native = { + title: "Sample app", url: "metro://sample", platform: "react-native", + targetId: "page-1", appId: "com.example.sample", deviceName: "iPhone 17", + }; + const { capture, uploadToken } = await store.createCapture({ target: native }); + assert.equal("tabId" in capture.target, false); + assert.equal(capture.target.platform, "react-native"); + assert.equal(capture.target.appId, native.appId); + assert.equal(capture.target.deviceName, native.deviceName); + assert.equal(capture.target.targetId, native.targetId); + await store.failCapture(capture.id, uploadToken, { error: "test cleanup", interrupted: true }); +}); + test.after(async () => { await rm(home, { recursive: true, force: true }); }); From c7c4a3cd1f2e93f140f0cd91238ad3823527be7e Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Tue, 3 Nov 2026 16:45:51 +0500 Subject: [PATCH 08/10] fix: frame namings --- package-lock.json | 4 +- package.json | 1 + packages/cli/src/record-rn-session.js | 13 +- scripts/test-codex-local.sh | 64 +++++-- src/app/api/analyze/route.ts | 12 +- src/app/js-profiler/normalize.ts | 24 ++- src/app/js-profiler/types.ts | 17 ++ src/lib/capture-store.ts | 10 +- src/lib/frame-classes.ts | 10 +- src/lib/js-profile.ts | 11 ++ src/lib/symbolicate.ts | 236 ++++++++++++++++++++++++++ tests/capture-store.test.mjs | 21 +++ tests/frame-classes.test.mjs | 14 ++ tests/symbolicate.test.mjs | 149 ++++++++++++++++ 14 files changed, 562 insertions(+), 24 deletions(-) create mode 100644 src/lib/symbolicate.ts create mode 100644 tests/symbolicate.test.mjs diff --git a/package-lock.json b/package-lock.json index aa971de..c4f0d36 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,6 +16,7 @@ "@callstack/tracesift": "workspace:*", "@callstack/tracesift-explore": "workspace:*", "@earendil-works/pi-coding-agent": "0.87.1", + "@jridgewell/trace-mapping": "^0.3.31", "@rozenite/ui": "^2.4.0", "agent-react-devtools": "0.4.0", "next": "16.3.4", @@ -3452,7 +3453,6 @@ "version": "3.1.2", "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", - "dev": true, "license": "MIT", "engines": { "node": ">=6.0.0" @@ -3462,14 +3462,12 @@ "version": "1.6.0", "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", - "dev": true, "license": "MIT" }, "node_modules/@jridgewell/trace-mapping": { "version": "0.3.31", "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz", "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==", - "dev": true, "license": "MIT", "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", diff --git a/package.json b/package.json index 6aba356..c75c2af 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,7 @@ }, "dependencies": { "@callstack/tracesift": "workspace:*", + "@jridgewell/trace-mapping": "^0.3.31", "@callstack/tracesift-explore": "workspace:*", "@earendil-works/pi-coding-agent": "0.87.1", "@rozenite/ui": "^2.4.0", diff --git a/packages/cli/src/record-rn-session.js b/packages/cli/src/record-rn-session.js index 2a5dc90..2423043 100644 --- a/packages/cli/src/record-rn-session.js +++ b/packages/cli/src/record-rn-session.js @@ -11,6 +11,12 @@ const MAX_UPLOAD_BYTES = 192 * 1024; // there is normally one bundle to retain. const MAX_SOURCE_MAP_BYTES = 48 * 1024 * 1024; const MAX_ALL_SOURCE_MAP_BYTES = 64 * 1024 * 1024; +// Metro builds a bundle's map on demand, and for a large app that is a cold +// multi-minute job: a Bluesky-sized bundle is ~900k lines. Thirty seconds was +// enough for an Expo starter and silently gave up on everything bigger, which +// is exactly the recording that needs the map most. This matches the trace +// flush budget below — the export is already waiting on the device by then. +const SOURCE_MAP_FETCH_TIMEOUT_MS = 120_000; const STOP_POLL_MS = 1000; const FLUSH_TIMEOUT_MS = 120_000; const METHOD_NOT_FOUND = -32601; @@ -144,8 +150,9 @@ function metroSourceMaps(origin) { warnings.push(`Stopped retaining source maps after the ${MAX_ALL_SOURCE_MAP_BYTES / 1048576} MB safety limit.`); break; } + const startedAt = Date.now(); try { - const response = await fetch(mapUrl, { redirect: 'error', signal: AbortSignal.timeout(30_000) }); + const response = await fetch(mapUrl, { redirect: 'error', signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const raw = await response.text(); if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error(`is ${Math.round(raw.length / 1048576)} MB, past the retention limit`); @@ -154,7 +161,9 @@ function metroSourceMaps(origin) { bytes += raw.length; retained.push({ url: bundleUrl, sourceMapUrl: mapUrl, sourceMap }); } catch (error) { - warnings.push(`Could not retain the Metro source map ${mapUrl}: ${errorText(error)}`); + // How long it ran separates a timeout from a 404: both arrive here, + // and only one of them means the derived URL was wrong. + warnings.push(`Could not retain the Metro source map ${mapUrl} after ${Math.round((Date.now() - startedAt) / 1000)}s: ${errorText(error)}`); } } if (retained.length === 0) { diff --git a/scripts/test-codex-local.sh b/scripts/test-codex-local.sh index 8c14a90..3ba766f 100755 --- a/scripts/test-codex-local.sh +++ b/scripts/test-codex-local.sh @@ -4,15 +4,16 @@ # the plugin's panel exercises the code in this working tree rather than the # published CLI and the installed app. # -# Two things have to come from here rather than from a release: `tracesift -# record`, which no published CLI has yet, and gzip support in the analyze -# route, without which a recorded trace reaches no cards. Both live in this -# tree, so this script points the plugin at the tree. +# Three things have to come from here rather than from a release: `tracesift +# record`, which no published CLI has yet; `record --platform rn`, which only +# 0.6.0 has; and gzip support in the analyze route, without which a recorded +# trace reaches no cards. All live in this tree, so this script points the +# plugin at the tree. # -# It leaves two pointer files the plugin's own scripts/test-codex-local.sh +# It leaves two pointer files the plugin's own tooling/test-codex-local.sh # reads, then stays in the foreground serving the app. Stop it with Ctrl-C. # -# scripts/test-codex-local.sh [--port 3100] [--home ] +# scripts/test-codex-local.sh [--port 3100] [--home ] [--metro ] # set -euo pipefail @@ -23,12 +24,15 @@ CLI_POINTER_FILE="${TMPDIR%/}/tracesift-codex-test-cli" HOME_DIR="${TMPDIR%/}/tracesift-codex-test-home.d" PORT="" -usage() { echo "Usage: $0 [--port ] [--home ]" >&2; } +METRO_URL="" + +usage() { echo "Usage: $0 [--port ] [--home ] [--metro ]" >&2; } while [[ $# -gt 0 ]]; do case "$1" in --port) PORT="${2:-}"; shift ;; --home) HOME_DIR="${2:-}"; shift ;; + --metro) METRO_URL="${2:-}"; shift ;; *) usage; exit 2 ;; esac shift @@ -79,6 +83,10 @@ cleanup() { local status=$? echo echo "Stopping..." + # A recording outlives this script: it runs in a detached recorder holding + # Hermes' one sampler or Chrome's tracing lock, and leaving it running means + # the next run cannot start one. + TRACE_SIFT_HOME="$HOME_DIR" "$CLI_WRAPPER" record stop >/dev/null 2>&1 || true # A Chrome left open by `record launch` belongs to this home; quitting it # here means the next run does not meet a browser nobody can reach. TRACE_SIFT_HOME="$HOME_DIR" "$CLI_WRAPPER" record close >/dev/null 2>&1 || true @@ -92,6 +100,7 @@ echo "Starting TraceSift from this checkout on $BASE_URL..." TRACE_SIFT_HOME="$HOME_DIR" \ TRACE_SIFT_INTEGRATION_TOKEN="$TOKEN" \ TRACE_SIFT_INSTANCE="$INSTANCE" \ +TRACESIFT_DEBUG=1 \ TRACE_SIFT_VERSION="0.0.0-codex-local" \ npm run dev -- --port "$PORT" & SERVER_PID=$! @@ -121,19 +130,48 @@ chmod 600 "$HOME_DIR/service.json" printf '%s' "$HOME_DIR" > "$POINTER_FILE" printf '%s' "$CLI_WRAPPER" > "$CLI_POINTER_FILE" +# Say up front whether a React Native app is reachable, because that is the +# route under test and the answer is one command away. Metro and the app are +# the developer's to start, so this only reports what it found. +METRO_URL="${METRO_URL:-http://127.0.0.1:8081}" +RN_STATUS="$( + TRACE_SIFT_HOME="$HOME_DIR" "$CLI_WRAPPER" record targets --platform rn --metro "$METRO_URL" --json 2>/dev/null | + node -e ' + let input = ""; + process.stdin.setEncoding("utf8"); + process.stdin.on("data", chunk => { input += chunk; }); + process.stdin.on("end", () => { + let payload; + try { payload = JSON.parse(input); } catch { payload = null; } + if (!payload) { process.stdout.write("Metro did not answer. Start it with `npx expo start` or `npm start`."); return; } + if (payload.error) { process.stdout.write(payload.error); return; } + const targets = payload.targets ?? []; + if (!targets.length) { process.stdout.write(`no app connected to ${payload.metro}. Open the app in a simulator or emulator.`); return; } + process.stdout.write(targets.map(target => `${target.title}${target.recommended ? " (default)" : ""}`).join(", ")); + }); + ' || true +)" + cat < && scripts/test-codex-local.sh + cd && tooling/test-codex-local.sh -Then in Codex: Mobile Dev -> TraceSift -> JavaScript CPU -> Record a web app. +Then in Codex: Mobile Dev -> TraceSift -> JavaScript CPU -> Record a running app. + React Native one press: the app is already running, so Start profile records + it. Ask the agent instead and it drives the same thing itself. + Web app two presses: Launch web app, reach the state worth profiling, + then Start profile. -Ctrl-C here when you are done; it quits any browser \`record launch\` left open. +Ctrl-C here when you are done; it stops any recording still running and quits +any browser \`record launch\` left open. EOF wait "$SERVER_PID" diff --git a/src/app/api/analyze/route.ts b/src/app/api/analyze/route.ts index 1f8a053..15995d9 100644 --- a/src/app/api/analyze/route.ts +++ b/src/app/api/analyze/route.ts @@ -83,9 +83,10 @@ export async function POST(request: Request): Promise { let tree; let tasks; let legacyBottlenecks; + let sourceMaps; try { const rawProfile = JSON.parse(await readFile(`${dir}/${PROFILE_FILE_NAME}`, "utf8")) as unknown; - ({ summary, hotspots: queriedHotspots, cards, profile: parsedProfile, tree, tasks, legacyBottlenecks } = + ({ summary, hotspots: queriedHotspots, cards, profile: parsedProfile, tree, tasks, legacyBottlenecks, sourceMaps } = summarizeCpuProfile(rawProfile, id, profile.name)); } catch (error) { const reason = error instanceof Error ? error.message : String(error); @@ -103,6 +104,15 @@ export async function POST(request: Request): Promise { // card says about which code is whose is a lookup in this table, and the // table is rules alone — so the same file always produces the same cards, // and uploading a profile costs nothing but the measurement. + log( + `source maps: ${sourceMaps.state}` + + `${sourceMaps.bundleUrls.length ? `, ${sourceMaps.resolvedSourceMapUrls.length}/${sourceMaps.bundleUrls.length} bundles` : ""}` + + `${sourceMaps.totalMappableFrameCount ? `, ${sourceMaps.symbolicatedFrameCount}/${sourceMaps.totalMappableFrameCount} frames moved to authored sources` : ""}` + + `${sourceMaps.failures.length ? `, ${sourceMaps.failures.length} unreadable` : ""}` + ); + // Without this, a React Native upload whose maps the capture failed to fetch + // looks exactly like a bare `.cpuprofile`: `state: "none"` and no reason. + for (const warning of sourceMaps.captureWarnings) log(`capture warning: ${warning}`); const settings = await getAnalysisSettings(); const classes = ruleClassTable(parsedProfile.nodes.map((node) => node.callFrame)); const taskCards = nodeCardEngineRequested() diff --git a/src/app/js-profiler/normalize.ts b/src/app/js-profiler/normalize.ts index 32769aa..ef496e3 100644 --- a/src/app/js-profiler/normalize.ts +++ b/src/app/js-profiler/normalize.ts @@ -6,6 +6,7 @@ import type { JsProfileSession, JsStackSignature, JsTimeBucket, + SourceMapsInfo, } from "./types"; import { stripRequest } from "../../lib/source-location.ts"; @@ -29,6 +30,12 @@ interface NormalizeMeta { startedAt: number; stoppedAt: number; samplingIntervalUs: number | undefined; + /** + * What `symbolicate.ts` managed to resolve before the frames reached here. + * Absent for a caller that never ran it, which is reported as `none` — the + * same answer this gave unconditionally before anything read the maps back. + */ + sourceMaps?: SourceMapsInfo; } export function normalizeProfile( @@ -94,6 +101,9 @@ export function normalizeProfile( const url = cf.url; const funcName = cf.functionName || "(anonymous)"; const isNative = cf.url.startsWith("native "); + // A symbolicated frame carries where it was sampled; `url` by then is the + // authored file, so the bundle test below has to ask the bundle URL. + const sampledUrl = cf.bundleUrl ?? cf.url; const isRuntime = RUNTIME_NAMES.has(cf.functionName) || (!cf.url && cf.functionName.startsWith("(")); const isAnonymous = !funcName || funcName === "(anonymous)"; @@ -108,7 +118,16 @@ export function normalizeProfile( isNative, isRuntime, isAnonymous, - symbolicationStatus: isHttpUrl(cf.url) ? "bundle-level" : "not-applicable", + symbolicationStatus: cf.bundleUrl + ? "symbolicated" + : isHttpUrl(sampledUrl) + ? "bundle-level" + : "not-applicable", + ...(cf.bundleUrl === undefined ? {} : { + bundleUrl: cf.bundleUrl, + bundleLineNumber: cf.bundleLineNumber, + bundleColumnNumber: cf.bundleColumnNumber, + }), }; frameByKey.set(key, frame); @@ -340,13 +359,14 @@ export function normalizeProfile( sampleHotspotIds, rawNodeToFrameId, rawProfile, - sourceMaps: { + sourceMaps: meta.sourceMaps ?? { state: "none", bundleUrls: [], resolvedSourceMapUrls: [], symbolicatedFrameCount: 0, totalMappableFrameCount: 0, failures: [], + captureWarnings: [], }, }; } diff --git a/src/app/js-profiler/types.ts b/src/app/js-profiler/types.ts index 059b721..ffd1471 100644 --- a/src/app/js-profiler/types.ts +++ b/src/app/js-profiler/types.ts @@ -5,6 +5,15 @@ export interface CdpCallFrame { url: string; lineNumber: number; columnNumber: number; + /** + * Where this frame was actually sampled, kept when `symbolicate.ts` moved + * `url`/`lineNumber`/`columnNumber` onto the authored source. Absent on a + * frame no retained map could place, which is also every frame of a + * recording that carried no maps at all. + */ + bundleUrl?: string; + bundleLineNumber?: number; + bundleColumnNumber?: number; } export interface CdpProfileNode { @@ -40,6 +49,14 @@ export interface CdpCallFrame { symbolicatedFrameCount: number; totalMappableFrameCount: number; failures: SymbolicationFailure[]; + /** + * What the capture said about the maps it could not retain. A recording + * with `state: "none"` is otherwise indistinguishable from a bare + * `.cpuprofile`, and the difference — Metro timed out, the map was past + * the size cap, the derived URL 404'd — is the whole answer to why every + * frame is still at a bundle position. + */ + captureWarnings: string[]; } // Normalized session model diff --git a/src/lib/capture-store.ts b/src/lib/capture-store.ts index 9b53258..9da6e07 100644 --- a/src/lib/capture-store.ts +++ b/src/lib/capture-store.ts @@ -295,7 +295,7 @@ function validSourceMaps(value: CaptureSourceMap[]): CaptureSourceMap[] { })); } -async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMetadata[], sourceMaps: CaptureSourceMap[], mainFrame?: CaptureMainFrame, traceMarker?: string): Promise<{ export: { fileName: string; sizeBytes: number }; eventCount: number }> { +async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMetadata[], sourceMaps: CaptureSourceMap[], warnings: string[], mainFrame?: CaptureMainFrame, traceMarker?: string): Promise<{ export: { fileName: string; sizeBytes: number }; eventCount: number }> { const stamp = new Date(record.createdAt).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z"); const fileName = `Trace-${stamp}.json.gz`; const metadata = { @@ -309,6 +309,12 @@ async function writeGzipExport(record: StoredCapture, scripts: CaptureScriptMeta target: record.target, createdAt: new Date(record.createdAt).toISOString(), scripts, + // Why a recording carries no source maps is decided at capture time and + // was, until now, written only to `record.json` — which the next + // recording overwrites. By the time someone opens the export and finds + // every frame still at a bundle position, the reason is gone. It + // belongs in the file it explains. + warnings, }, }; const written = await writeTraceExport({ @@ -357,7 +363,7 @@ export async function finalizeCapture(id: string, token: string, input: { name: cleanText(input.mainFrame.name || "", 300), } : undefined; const traceMarker = input.traceMarker ? cleanText(input.traceMarker, 300) : undefined; - const completedExport = await writeGzipExport(record, scripts, sourceMaps, mainFrame, traceMarker); + const completedExport = await writeGzipExport(record, scripts, sourceMaps, record.warnings, mainFrame, traceMarker); record.export = completedExport.export; record.eventCount = completedExport.eventCount; record.state = record.warnings.length > 0 ? "captured_with_warnings" : "captured"; diff --git a/src/lib/frame-classes.ts b/src/lib/frame-classes.ts index 0e5f95c..f424ec7 100644 --- a/src/lib/frame-classes.ts +++ b/src/lib/frame-classes.ts @@ -62,7 +62,15 @@ function isVendorChunkUrl(url: string): boolean { * its URL says nothing about either. Frames carrying one are exactly the * residue the model call exists to resolve. */ -const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#]|$)/i; +/* + * Metro writes a bundle's parameters into the path rather than the query, so + * the extension is followed by a slash and not by `?`: a React Native frame + * arrives at `/index.ts.bundle//&platform=ios&dev=true`. The `[?#]|$` tail + * refused every one of them, which left the single case this rule was written + * for falling through to `isReadableSourcePath` — false for anything carrying + * a scheme — and reaching the residue branch by accident rather than by rule. + */ +const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#/]|$)/i; /** Schemes that name no file on disk: engine internals, extensions, eval'd code. */ const VIRTUAL_SCHEME = /^(?:node|extensions|chrome|chrome-extension|v8|evalmachine|blob|data):/i; diff --git a/src/lib/js-profile.ts b/src/lib/js-profile.ts index cd1e32b..1e0434a 100644 --- a/src/lib/js-profile.ts +++ b/src/lib/js-profile.ts @@ -13,6 +13,7 @@ import { type TaskSet, } from "./tasks.ts"; import { normalizeProfile } from "../app/js-profiler/normalize.ts"; +import { collectCaptureWarnings, collectRetainedSourceMaps, symbolicateProfile } from "./symbolicate.ts"; import { queryHotspots, querySummary } from "../app/js-profiler/query.ts"; import type { CdpCallFrame, @@ -20,6 +21,7 @@ import type { CdpProfileNode, JsHotspotsResult, JsProfileSummary, + SourceMapsInfo, } from "../app/js-profiler/types.ts"; function isRecord(value: unknown): value is Record { return Boolean(value) && typeof value === "object" && !Array.isArray(value); @@ -328,11 +330,18 @@ export function summarizeCpuProfile( * asks for a comparison. */ legacyBottlenecks: () => Bottleneck[]; + /** What the retained maps resolved, for the log and the symbolication notes. */ + sourceMaps: SourceMapsInfo; } { const now = Date.now(); // Parsed once: this runs over the whole upload, and the profiles this tool // exists for are hundreds of megabytes. const profile = coerceCdpProfile(raw); + // Before anything reads a frame's URL. Classification, the call tree, the + // task splitter and every location printed downstream all take that URL at + // its word, so the move from bundle positions to authored files has to + // happen once, here, rather than in whichever of them noticed first. + const sourceMaps = symbolicateProfile(profile, collectRetainedSourceMaps(raw), collectCaptureWarnings(raw)); const session = normalizeProfile(profile, { sessionId, name, @@ -340,6 +349,7 @@ export function summarizeCpuProfile( startedAt: now, stoppedAt: now, samplingIntervalUs: undefined, + sourceMaps, }); const durationMs = session.durationMs; @@ -349,6 +359,7 @@ export function summarizeCpuProfile( summary: querySummary(session), tree, profile, + sourceMaps, tasks: extractTasks(profile), legacyBottlenecks: () => groupBottlenecks(profile, durationMs), cards: selectCards(tree), diff --git a/src/lib/symbolicate.ts b/src/lib/symbolicate.ts new file mode 100644 index 0000000..3c34132 --- /dev/null +++ b/src/lib/symbolicate.ts @@ -0,0 +1,236 @@ +/** + * Frame positions moved from the bundle they were sampled in back onto the + * files a developer wrote. + * + * Everything downstream reads a frame's URL as a statement about whose code it + * is: `frame-classes.ts` sorts `node_modules` from the product, `task-cards.ts` + * picks a card's boundary from that sorting, and `source-location.ts` decides + * whether a position is worth printing. A bundler defeats all three at once, + * because it gives every frame in the recording one URL. Chrome's own profiles + * mostly escape it — a dev server serves real paths, and a split build names a + * vendor chunk — but a React Native recording never does: Metro serves one + * `index.bundle`, so the product's screens, React's reconciler and every + * dependency arrive indistinguishable, fall to the `library` fallback, and the + * first internal with an ordinary-looking name becomes a card's headline. + * + * The capture already carries the answer. `record-session.js` harvests maps + * over `Debugger.scriptParsed`, `record-rn-session.js` fetches Metro's `.map` + * for each bundle a frame mentions, and `capture-store.ts` writes both into the + * export's `metadata.sourceMaps` under DevTools' enhanced-trace schema. Until + * now nothing read them back: `normalize.ts` reported `state: "none"` for every + * upload, and the `bundleUrl` / `symbolicationStatus` fields its own frame type + * declares were never filled. + * + * This runs once, over the parsed profile, before the frames are classified. + */ + +import { AnyMap, originalPositionFor, type TraceMap } from "@jridgewell/trace-mapping"; +import { stripRequest } from "./source-location.ts"; +import type { CdpCallFrame, CdpProfile, SourceMapsInfo, SymbolicationFailure } from "../app/js-profiler/types.ts"; + +/** One map as the capture retained it. Mirrors `CaptureSourceMap`. */ +export interface RetainedSourceMap { + url: string; + sourceMapUrl: string; + sourceMap: unknown; +} + +function isRecord(value: unknown): value is Record { + return Boolean(value) && typeof value === "object" && !Array.isArray(value); +} + +/** + * The maps an exported trace carries, or nothing. + * + * A profile uploaded as a bare `.cpuprofile`, or exported by DevTools itself, + * has none — which is not a failure, just a recording that was never enriched. + */ +export function collectRetainedSourceMaps(raw: unknown): RetainedSourceMap[] { + if (!isRecord(raw) || !isRecord(raw.metadata)) return []; + const maps = raw.metadata.sourceMaps; + if (!Array.isArray(maps)) return []; + const out: RetainedSourceMap[] = []; + for (const entry of maps) { + if (!isRecord(entry)) continue; + if (typeof entry.url !== "string" || !isRecord(entry.sourceMap)) continue; + out.push({ + url: entry.url, + sourceMapUrl: typeof entry.sourceMapUrl === "string" ? entry.sourceMapUrl : "", + sourceMap: entry.sourceMap, + }); + } + return out; +} + +/** + * The bundle URL a frame and a retained map agree on. + * + * Exact first, because that is what the capture stored. The fallback drops the + * request, which is the one difference the two can have and still name the same + * artefact: Metro writes a bundle's build options into the path itself + * (`/index.bundle//&platform=ios&dev=true&…`), and a frame recorded before the + * options changed carries a different tail for the same file. + */ +function mapKeys(url: string): string[] { + const exact = url.split("#")[0]; + const stripped = stripRequest(exact); + return stripped && stripped !== exact ? [exact, stripped] : [exact]; +} + +/** + * A map held until something asks it a question. + * + * `trace-mapping` decodes a map's `mappings` on first lookup, and a Metro dev + * map runs to tens of megabytes. A recording routinely mentions bundles no + * frame was ever sampled in — a polyfill chunk, a second entry point — so + * decoding on registration would spend that cost for nothing. + */ +interface LazyMap { + entry: RetainedSourceMap; + /** `undefined` until first use, `null` once it has failed to parse. */ + trace?: TraceMap | null; +} + +/** + * Deliberately not resolved against the map's own URL. + * + * `new AnyMap(map, mapUrl)` would rewrite every `sources` entry relative to the + * URL the map was served from, which is exactly wrong here: Metro lists its + * sources as absolute filesystem paths, and resolving `/Users/me/app/App.tsx` + * against `http://localhost:8081/index.map` yields an `http:` URL that + * `isReadableSourcePath` then refuses — turning a frame we had just located + * back into an unclassifiable one. webpack's `webpack://` sources are already + * handled downstream by `unwrapBundlerUrl`, so neither needs resolution. + */ +function traceFor(lazy: LazyMap, failures: SymbolicationFailure[]): TraceMap | null { + if (lazy.trace !== undefined) return lazy.trace; + try { + lazy.trace = new AnyMap(lazy.entry.sourceMap as never); + } catch (error) { + lazy.trace = null; + failures.push({ + bundleUrl: lazy.entry.url, + reason: error instanceof Error ? error.message : String(error), + }); + } + return lazy.trace; +} + +/** What a position resolved to, or `null` when the map had nothing for it. */ +interface Resolved { + url: string; + lineNumber: number; + columnNumber: number; +} + +function state(mappable: number, symbolicated: number, maps: number): SourceMapsInfo["state"] { + if (maps === 0) return "none"; + if (symbolicated === 0) return "failed"; + return symbolicated === mappable ? "full" : "partial"; +} + +/** + * Rewrite every frame that a retained map can place, in situ. + * + * In situ because the parsed profile is the one copy: the analyze route hands + * the same object to the call tree, the task splitter and the classification + * table, and a profile that runs to hundreds of megabytes is not duplicated to + * spare a mutation. The bundle position is kept on the frame rather than + * discarded — `normalize.ts` reports it, and it is the only way back to what + * was actually sampled. + */ +export function symbolicateProfile(profile: CdpProfile, maps: readonly RetainedSourceMap[], captureWarnings: readonly string[] = []): SourceMapsInfo { + const failures: SymbolicationFailure[] = []; + const bundleUrls = [...new Set(maps.map((entry) => entry.url))]; + const resolvedSourceMapUrls = [...new Set(maps.map((entry) => entry.sourceMapUrl).filter(Boolean))]; + const empty: SourceMapsInfo = { + state: "none", + bundleUrls, + resolvedSourceMapUrls, + symbolicatedFrameCount: 0, + totalMappableFrameCount: 0, + failures, + captureWarnings: [...captureWarnings], + }; + if (maps.length === 0) return empty; + + const byKey = new Map(); + for (const entry of maps) { + const lazy: LazyMap = { entry }; + for (const key of mapKeys(entry.url)) if (!byKey.has(key)) byKey.set(key, lazy); + } + + // One profile holds far more nodes than distinct positions — a function + // reached from twenty call paths is twenty nodes at one line and column. + const cache = new Map(); + let mappable = 0; + let symbolicated = 0; + + for (const node of profile.nodes) { + const frame = node.callFrame; + if (!frame.url || frame.lineNumber < 0) continue; + const lazy = byKey.get(frame.url.split("#")[0]) ?? byKey.get(stripRequest(frame.url.split("#")[0])); + if (!lazy) continue; + mappable += 1; + + const key = `${frame.url}\u0000${frame.lineNumber}\u0000${frame.columnNumber}`; + let resolved = cache.get(key); + if (resolved === undefined) { + resolved = resolve(lazy, frame, failures); + cache.set(key, resolved); + } + if (!resolved) continue; + + symbolicated += 1; + frame.bundleUrl = frame.url; + frame.bundleLineNumber = frame.lineNumber; + frame.bundleColumnNumber = frame.columnNumber; + frame.url = resolved.url; + frame.lineNumber = resolved.lineNumber; + frame.columnNumber = resolved.columnNumber; + } + + return { + state: state(mappable, symbolicated, maps.length), + bundleUrls, + resolvedSourceMapUrls, + symbolicatedFrameCount: symbolicated, + totalMappableFrameCount: mappable, + failures, + captureWarnings: [...captureWarnings], + }; +} + +/** + * The warnings the capture wrote into the export, if it wrote any. + * + * `record.json` holds these too, but the next recording overwrites it, so by + * the time an export is opened they are only here. + */ +export function collectCaptureWarnings(raw: unknown): string[] { + if (!isRecord(raw) || !isRecord(raw.metadata) || !isRecord(raw.metadata.traceSift)) return []; + const warnings = raw.metadata.traceSift.warnings; + if (!Array.isArray(warnings)) return []; + return warnings.filter((entry): entry is string => typeof entry === "string").slice(0, 100); +} + +/** + * CDP counts a frame's line and column from zero; a source map counts lines + * from one and columns from zero. A frame recorded with no column (`-1`) is + * asked for at the start of its line, which is the right answer for a position + * the engine only knew that precisely. + */ +function resolve(lazy: LazyMap, frame: CdpCallFrame, failures: SymbolicationFailure[]): Resolved | null { + const trace = traceFor(lazy, failures); + if (!trace) return null; + const found = originalPositionFor(trace, { + line: frame.lineNumber + 1, + column: Math.max(0, frame.columnNumber), + }); + if (!found.source) return null; + return { + url: found.source, + lineNumber: typeof found.line === "number" ? Math.max(0, found.line - 1) : -1, + columnNumber: typeof found.column === "number" ? found.column : -1, + }; +} diff --git a/tests/capture-store.test.mjs b/tests/capture-store.test.mjs index fbffc17..9668397 100644 --- a/tests/capture-store.test.mjs +++ b/tests/capture-store.test.mjs @@ -139,3 +139,24 @@ test("a React Native target without a tab id is accepted and its fields round-tr }); test.after(async () => { await rm(home, { recursive: true, force: true }); }); + +test("why a recording carries no source maps is written into the recording", async () => { + const { capture, uploadToken } = await store.createCapture({ target }); + await store.appendCaptureRawChunk(capture.id, uploadToken, 0, Buffer.from(JSON.stringify({ traceEvents: [] }), "utf8")); + const completed = await store.finalizeCapture(capture.id, uploadToken, { + stopReason: "manual", + // React Native: no scriptParsed, so no scripts, and the map is fetched + // from Metro over HTTP after the recording stops. + scripts: [], + sourceMaps: [], + warnings: ["Could not retain the Metro source map http://127.0.0.1:8081/index.ts.map//&platform=ios after 30s: timeout"], + }); + assert.equal(completed.sourceMapsSeen, 0); + + const exported = await store.captureExport(capture.id); + const decoded = JSON.parse((await unzip(await readFile(exported.path))).toString("utf8")); + // Not just in `record.json`, which the next recording overwrites: an export + // with no maps and no reason is indistinguishable from a bare `.cpuprofile`. + assert.match(decoded.metadata.traceSift.warnings.join("\n"), /after 30s: timeout/); + await store.deleteCapture(capture.id); +}); diff --git a/tests/frame-classes.test.mjs b/tests/frame-classes.test.mjs index 74363c7..5858adf 100644 --- a/tests/frame-classes.test.mjs +++ b/tests/frame-classes.test.mjs @@ -108,3 +108,17 @@ test('a webpack scheme is unwrapped, not filed with the engine', () => { assert.equal(classifyByRule(frame('handler', 'chrome-extension://abc/background.js')), 'native'); assert.equal(classifyByRule(frame('run', 'blob:http://localhost:3000/abc')), 'native'); }); + +test("Metro writes a bundle's parameters into the path, so the extension is followed by a slash", () => { + // The real shape off a React Native capture: no `?` anywhere, the build + // options live in the path. A rule anchored at `?`, `#` or end of string + // matched none of them, which left the one bundler this rule exists for + // reaching the residue branch by accident rather than by rule. + const metro = 'http://192.168.68.55:8081/index.ts.bundle//&platform=ios&dev=true&lazy=true'; + assert.equal(classifyByRule(frame('loadModuleImplementation', metro)), undefined); + // With a vendor chunk seen elsewhere in the recording, a meaningful name in + // a sibling bundle is the product's own code. + assert.equal(classifyByRule(frame('PostThread', metro), true), 'app'); + // A mangled one in the same bundle is still residue. + assert.equal(classifyByRule(frame('t.A', metro), true), undefined); +}); diff --git a/tests/symbolicate.test.mjs b/tests/symbolicate.test.mjs new file mode 100644 index 0000000..6912970 --- /dev/null +++ b/tests/symbolicate.test.mjs @@ -0,0 +1,149 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { collectCaptureWarnings, collectRetainedSourceMaps, symbolicateProfile } from '../src/lib/symbolicate.ts'; +import { ruleClassTable } from '../src/lib/frame-classes.ts'; +import { frameNameTier } from '../src/lib/frame-names.ts'; + +const BUNDLE = 'http://192.168.1.5:8081/index.bundle//&platform=ios&dev=true'; + +/** + * Three generated lines, one per source. Hand-encoded rather than generated so + * the test states the mapping it is asserting: `AAAA` is the first line at + * source 0, and each following segment carries its deltas. + */ +const sourceMap = { + version: 3, + sources: [ + '/app/src/screens/Home.tsx', + '/app/node_modules/react-native/Libraries/Pressability/Pressability.js', + '/app/node_modules/react-dom/cjs/react-dom-client.development.js', + ], + names: [], + mappings: 'AAAA;ACUI;ACLF', +}; + +const node = (id, functionName, lineNumber) => ({ + id, + callFrame: { functionName, scriptId: '1', url: BUNDLE, lineNumber, columnNumber: 0 }, +}); + +const profile = () => ({ + nodes: [ + node(1, 'HomeScreen', 0), + node(2, 'onResponderRelease', 1), + node(3, 'react_stack_bottom_frame', 2), + ], + startTime: 0, + endTime: 1000, + samples: [1, 2, 3], + timeDeltas: [0, 100, 100], +}); + +const maps = [{ url: BUNDLE, sourceMapUrl: 'http://127.0.0.1:8081/index.map', sourceMap }]; + +test('the maps an enriched export carries are read back off its metadata', () => { + assert.deepEqual(collectRetainedSourceMaps({ metadata: { sourceMaps: maps } }), maps); + // A bare .cpuprofile, or a DevTools export, carries none. Not a failure. + assert.deepEqual(collectRetainedSourceMaps({ metadata: { source: 'DevTools' } }), []); + assert.deepEqual(collectRetainedSourceMaps(null), []); +}); + +test('Metro frames move from one bundle URL onto the files they were written in', () => { + const parsed = profile(); + const info = symbolicateProfile(parsed, maps); + + assert.equal(info.state, 'full'); + assert.equal(info.symbolicatedFrameCount, 3); + assert.equal(info.totalMappableFrameCount, 3); + assert.deepEqual(info.failures, []); + + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.url), [ + '/app/src/screens/Home.tsx', + '/app/node_modules/react-native/Libraries/Pressability/Pressability.js', + '/app/node_modules/react-dom/cjs/react-dom-client.development.js', + ]); + // CDP counts lines from zero and a source map from one, so a frame recorded + // at bundle line 1 and mapped to original line 11 comes back as 10. + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.lineNumber), [0, 10, 5]); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.columnNumber), [0, 4, 2]); +}); + +test('the bundle position is kept, because it is what was actually sampled', () => { + const parsed = profile(); + symbolicateProfile(parsed, maps); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.bundleUrl), [BUNDLE, BUNDLE, BUNDLE]); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.bundleLineNumber), [0, 1, 2]); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.bundleColumnNumber), [0, 0, 0]); +}); + +test('a bundle URL recorded with different build options still finds its map', () => { + const parsed = profile(); + for (const n of parsed.nodes) n.callFrame.url = 'http://192.168.1.5:8081/index.bundle//&platform=ios&dev=false&minify=true'; + const info = symbolicateProfile(parsed, maps); + assert.equal(info.symbolicatedFrameCount, 3); +}); + +test('a recording with no retained maps is left exactly as it was', () => { + const parsed = profile(); + const info = symbolicateProfile(parsed, []); + assert.equal(info.state, 'none'); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.url), [BUNDLE, BUNDLE, BUNDLE]); + assert.equal(parsed.nodes[0].callFrame.bundleUrl, undefined); +}); + +test('an unreadable map is reported rather than thrown', () => { + const parsed = profile(); + const info = symbolicateProfile(parsed, [{ url: BUNDLE, sourceMapUrl: 'x.map', sourceMap: { version: 3 } }]); + assert.equal(info.state, 'failed'); + assert.equal(info.failures.length, 1); + assert.equal(info.failures[0].bundleUrl, BUNDLE); + assert.deepEqual(parsed.nodes.map((n) => n.callFrame.url), [BUNDLE, BUNDLE, BUNDLE]); +}); + +test('this is what makes a React Native profile classifiable at all', () => { + const before = profile(); + const unmapped = ruleClassTable(before.nodes.map((n) => n.callFrame)); + // Every frame shares one `index.bundle`, so no rule can place any of them and + // all three fall to the `library` fallback — including React's own internals, + // which is why an internal with an ordinary name ends up heading a card. + assert.deepEqual(before.nodes.map((n) => unmapped.classOf(n.callFrame)), ['library', 'library', 'library']); + assert.equal(unmapped.degraded, true); + assert.equal(frameNameTier(before.nodes[2].callFrame), 2); + + const after = profile(); + symbolicateProfile(after, maps); + const mapped = ruleClassTable(after.nodes.map((n) => n.callFrame)); + assert.deepEqual(after.nodes.map((n) => mapped.classOf(n.callFrame)), ['app', 'library', 'framework']); + assert.equal(mapped.degraded, false); +}); + +test('a capture that could not retain a map says so in the export it wrote', () => { + // `record.json` carries these too, and the next recording overwrites it. By + // the time someone opens an export and finds every frame still at a bundle + // position, this is the only place the reason survives. + const warnings = collectCaptureWarnings({ + metadata: { + sourceMaps: [], + traceSift: { + warnings: [ + 'Could not retain the Metro source map http://127.0.0.1:8081/index.ts.map//&platform=ios after 30s: The operation was aborted due to timeout', + 42, + ], + }, + }, + }); + assert.deepEqual(warnings, [ + 'Could not retain the Metro source map http://127.0.0.1:8081/index.ts.map//&platform=ios after 30s: The operation was aborted due to timeout', + ]); +}); + +test('a profile that was never enriched is not a profile whose enrichment failed', () => { + assert.deepEqual(collectCaptureWarnings({ metadata: { sourceMaps: [] } }), []); + assert.deepEqual(collectCaptureWarnings(null), []); + // And the distinction reaches the caller: both report `state: "none"`, only + // one of them can say why. + const failed = symbolicateProfile(profile(), [], ['Metro timed out']); + assert.equal(failed.state, 'none'); + assert.deepEqual(failed.captureWarnings, ['Metro timed out']); + assert.deepEqual(symbolicateProfile(profile(), []).captureWarnings, []); +}); From 078b248757f374165fa9a735bf518c659e55f83d Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Wed, 4 Nov 2026 10:30:58 +0500 Subject: [PATCH 09/10] fix: frame names --- packages/cli/src/record-rn-session.js | 19 ++++++- packages/cli/test/record-rn-session.test.js | 51 ++++++++++++++++- .../explore/src/components/task-views.tsx | 23 ++++---- packages/explore/src/lib/frame-classes.ts | 10 +++- packages/explore/src/lib/task-timeline.ts | 24 ++++++++ tests/culprit-cut.test.mjs | 57 +++++++++++++++++++ 6 files changed, 169 insertions(+), 15 deletions(-) create mode 100644 tests/culprit-cut.test.mjs diff --git a/packages/cli/src/record-rn-session.js b/packages/cli/src/record-rn-session.js index 2423043..32512f8 100644 --- a/packages/cli/src/record-rn-session.js +++ b/packages/cli/src/record-rn-session.js @@ -9,8 +9,14 @@ const MAX_UPLOAD_BYTES = 192 * 1024; // past Chrome's 8 MB per-script limit routinely — an Expo starter is already // over 10 MB. The aggregate limit is what actually bounds the export, and // there is normally one bundle to retain. +// Two different questions. The fetch limit is how much of a response we are +// willing to hold as a string at all; the retention limit is how much of it +// goes into the export, and it is applied after `sourcesContent` is dropped. +// Metro's map for Bluesky is 56 MB whole and 26 MB without it, so the old +// single 48 MB test rejected a map that is comfortably retainable. +const MAX_SOURCE_MAP_FETCH_BYTES = 256 * 1024 * 1024; const MAX_SOURCE_MAP_BYTES = 48 * 1024 * 1024; -const MAX_ALL_SOURCE_MAP_BYTES = 64 * 1024 * 1024; +const MAX_ALL_SOURCE_MAP_BYTES = 96 * 1024 * 1024; // Metro builds a bundle's map on demand, and for a large app that is a cold // multi-minute job: a Bluesky-sized bundle is ~900k lines. Thirty seconds was // enough for an Expo starter and silently gave up on everything bigger, which @@ -155,10 +161,17 @@ function metroSourceMaps(origin) { const response = await fetch(mapUrl, { redirect: 'error', signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const raw = await response.text(); - if (raw.length > MAX_SOURCE_MAP_BYTES) throw new Error(`is ${Math.round(raw.length / 1048576)} MB, past the retention limit`); + if (raw.length > MAX_SOURCE_MAP_FETCH_BYTES) throw new Error(`is ${Math.round(raw.length / 1048576)} MB, past the fetch limit`); const sourceMap = JSON.parse(raw); if (!sourceMap || typeof sourceMap !== 'object' || Array.isArray(sourceMap)) throw new Error('not a JSON object'); - bytes += raw.length; + // More than half a Metro map is the authored files inlined, and + // nothing downstream reads them: a frame is moved by `mappings`, + // `sources` and `names` alone. Carrying the sources would put a + // copy of the whole app inside every recording of it. + delete sourceMap.sourcesContent; + const size = JSON.stringify(sourceMap).length; + if (size > MAX_SOURCE_MAP_BYTES) throw new Error(`is ${Math.round(size / 1048576)} MB without its sources, past the retention limit`); + bytes += size; retained.push({ url: bundleUrl, sourceMapUrl: mapUrl, sourceMap }); } catch (error) { // How long it ran separates a timeout from a 404: both arrive here, diff --git a/packages/cli/test/record-rn-session.test.js b/packages/cli/test/record-rn-session.test.js index 95527f9..796bbbe 100644 --- a/packages/cli/test/record-rn-session.test.js +++ b/packages/cli/test/record-rn-session.test.js @@ -22,9 +22,14 @@ const TARGET = { id: 'page-1', title: 'Hermes React Native', appId: 'com.example * A Metro that serves /json/list, plus a stand-in for the global WebSocket that * speaks the CDP message protocol. `script(message, socket)` plays the app. */ -async function fakeApp(t, script) { +async function fakeApp(t, script, map) { const server = createServer((request, response) => { const port = server.address().port; + if (map && request.url.includes('.map')) { + response.writeHead(200, { 'content-type': 'application/json' }); + response.end(JSON.stringify(map)); + return; + } response.writeHead(200, { 'content-type': 'application/json' }); response.end(JSON.stringify([{ ...TARGET, webSocketDebuggerUrl: `ws://127.0.0.1:${port}/inspector/debug?device=a` }])); }); @@ -261,3 +266,47 @@ test('a long CPU profile is split into chunks that carry the node table once', ( assert.deepEqual(chunks[1].args.data.cpuProfile.samples, samples.slice(10_000, 20_000)); assert.deepEqual(chunks[2].args.data.timeDeltas, timeDeltas.slice(20_000)); }); + +/** + * Metro inlines every authored file it mapped. For an app the size of Bluesky + * that is 30 of the map's 56 MB, and it is the half nothing reads: a frame + * moves onto its source by `mappings`, `sources` and `names`. + */ +test('the authored sources Metro inlines are dropped, because a recording is not a copy of the app', async (t) => { + const home = await temporaryDirectory(t); + const sourceMap = { + version: 3, + sources: ['src/view/OpenCameraBtn.tsx'], + sourcesContent: ['x'.repeat(64 * 1024 * 1024)], + names: ['OpenCameraBtn'], + mappings: 'AAAA', + }; + const app = await fakeApp(t, (message, socket) => { + if (message.method === 'Tracing.start') return socket.reply(message); + if (message.method === 'Tracing.end') { + socket.reply(message); + socket.notify('Tracing.dataCollected', { value: [{ + name: 'ProfileChunk', cat: 'disabled-by-default-v8.cpu_profiler', ph: 'P', pid: 7, tid: 11, ts: 1000, + args: { data: { cpuProfile: { nodes: [{ id: 1, callFrame: { + functionName: 'OpenCameraBtn', scriptId: '6', lineNumber: 0, columnNumber: 0, + // Metro writes the build options into the path, not the query. + url: `${app.metro}/index.ts.bundle//&platform=ios&dev=true&lazy=true`, + } }], samples: [1] }, timeDeltas: [0] } }, + }] }); + socket.notify('Tracing.tracingComplete', {}); + return undefined; + } + return socket.reply(message); + }, sourceMap); + const result = await record(t, app, home, { sourceMaps: true }); + + const document = await readExport(result.path); + const [retained] = document.metadata.sourceMaps; + // Whole, this map is past the retention limit. Without the sources it is + // nothing, and it still resolves every frame it was fetched for. + assert.ok(retained, (await readRecordState(home)).warnings?.join('\n')); + assert.equal('sourcesContent' in retained.sourceMap, false); + assert.deepEqual(retained.sourceMap.sources, ['src/view/OpenCameraBtn.tsx']); + assert.equal(retained.sourceMap.mappings, 'AAAA'); + assert.deepEqual((await readRecordState(home)).warnings, []); +}); diff --git a/packages/explore/src/components/task-views.tsx b/packages/explore/src/components/task-views.tsx index 448a078..442af19 100644 --- a/packages/explore/src/components/task-views.tsx +++ b/packages/explore/src/components/task-views.tsx @@ -10,15 +10,17 @@ import { pickedClass, pickNumber, picking, PickTick, type FrameSelection } from import { formatMs } from "../lib/format.ts"; import type { FrameLocations } from "../lib/frame-location.ts"; import { focusedTree, type TaskCulprit, type TaskTreeNode } from "../lib/task-cards.ts"; -import { isShownFrame, SHOWN_CLASSES } from "../lib/task-timeline.ts"; +import { isShownFrame, OWN_CODE_CLASSES } from "../lib/task-timeline.ts"; import type { FrameClass } from "../lib/frame-classes.ts"; /** - * The classes the focused views keep, as the set `isShownFrame` tests against. - * `SHOWN_CLASSES` is the list and this is the lookup; the cut itself lives in - * `task-timeline.ts` so the chart, the tree and the culprit table share it. + * The classes the culprit table keeps, as the set `isShownFrame` tests + * against. Narrower than the `SHOWN_CLASSES` the chart and the tree draw by: + * they carry `library` to keep their nesting intact, a table of independent + * rows does not have to, and a reader who asked for their code only did not + * mean React Native's `Pressability` either. `task-timeline.ts` says why. */ -const DRAWN_CLASSES = new Set(SHOWN_CLASSES); +const OWN_CODE = new Set(OWN_CODE_CLASSES); /** * The focused subtree, either as it was recorded or with the framework and the @@ -93,7 +95,7 @@ export function TaskCallTree({ focus, taskMs, onFocus, locations, selection }: { export function TaskCulpritTable({ culprits, onFocus, locations, selection }: { culprits: readonly TaskCulprit[]; onFocus: (id: string) => void; locations: FrameLocations; selection?: FrameSelection }) { const [mode, setMode] = useState("full"); const rows = useMemo( - () => (mode === "focused" ? culprits.filter((culprit) => isShownFrame(culprit.name, culprit.frameClass, DRAWN_CLASSES)) : culprits), + () => (mode === "focused" ? culprits.filter((culprit) => isShownFrame(culprit.name, culprit.frameClass, OWN_CODE)) : culprits), [mode, culprits], ); const hidden = culprits.length - rows.length; @@ -159,14 +161,15 @@ export function TaskCulpritTable({ culprits, onFocus, locations, selection }: { ) : ( )} {mode === "focused" && hidden > 0 ? ( - {hidden === 1 ? "One React or engine frame is" : `${hidden} React and engine frames are`} hidden, the same cut - the Timeline draws by. Every figure above is unchanged: a culprit’s self time is measured over the whole - task, so hiding a row neither moves time onto another row nor takes it off this one. + {hidden === 1 ? "One frame from React, a dependency or the engine is" : `${hidden} frames from React, dependencies and the engine are`} hidden, + a narrower cut than the Timeline’s — a chart has to keep a dependency’s box to keep its nesting, and a + table does not. Every figure above is unchanged: a culprit’s self time is measured over the whole task, so + hiding a row neither moves time onto another row nor takes it off this one. ) : null} diff --git a/packages/explore/src/lib/frame-classes.ts b/packages/explore/src/lib/frame-classes.ts index 5cdc821..93b8bbe 100644 --- a/packages/explore/src/lib/frame-classes.ts +++ b/packages/explore/src/lib/frame-classes.ts @@ -62,7 +62,15 @@ function isVendorChunkUrl(url: string): boolean { * its URL says nothing about either. Frames carrying one are exactly the * residue the model call exists to resolve. */ -const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#]|$)/i; +/* + * Metro writes a bundle's parameters into the path rather than the query, so + * the extension is followed by a slash and not by `?`: a React Native frame + * arrives at `/index.ts.bundle//&platform=ios&dev=true`. The `[?#]|$` tail + * refused every one of them, which left the single case this rule was written + * for falling through to `isReadableSourcePath` — false for anything carrying + * a scheme — and reaching the residue branch by accident rather than by rule. + */ +const BUNDLE_URL = /\.(?:bundle|min\.js)(?:[?#/]|$)/i; /** Schemes that name no file on disk: engine internals, extensions, eval'd code. */ const VIRTUAL_SCHEME = /^(?:node|extensions|chrome|chrome-extension|v8|evalmachine|blob|data):/i; diff --git a/packages/explore/src/lib/task-timeline.ts b/packages/explore/src/lib/task-timeline.ts index 7651c04..a7d4f85 100644 --- a/packages/explore/src/lib/task-timeline.ts +++ b/packages/explore/src/lib/task-timeline.ts @@ -109,6 +109,30 @@ export interface TaskTimeline { */ export const SHOWN_CLASSES: readonly FrameClass[] = ["app", "library", "anonymous"]; +/** + * The stricter cut the culprit table draws by, because a list is not a chart. + * + * `SHOWN_CLASSES` keeps `library` to protect a drawing: a frame misread as a + * dependency still has to occupy its place, or the boxes above it move and the + * nesting stops describing the recording. A table has no such obligation. Its + * rows are independent, every figure on one is measured over the whole task, + * and a row that leaves says nothing about the rows that stay — so here the + * judgement is not cosmetic, it is the entire question the reader asked. + * + * `node_modules` is the one thing a symbolicated React Native profile can say + * with certainty, and saying it is the point of the toggle: `metroRequire`, + * `onResponderRelease` and `computeFullKey` are real costs on real frames that + * nobody reading their own code can act on. `anonymous` stays, because a + * nameless frame with no URL is as likely to be the reader's arrow function as + * anyone's, and the table would rather show one too many than hide theirs. + * + * The emptiness this risks is the honest answer, and the table already has an + * empty state that gives it. The one case it is not is a recording with no + * source map, where every bundle frame is filed `library` because no rule + * could say otherwise — there the toggle hides frames it cannot vouch for. + */ +export const OWN_CODE_CLASSES: readonly FrameClass[] = ["app", "anonymous"]; + /** * A built-in the product asked for by name: `[Native] intlDateTimeFormatFormat` * under Hermes, `toLocaleString (native date.js)` under V8. diff --git a/tests/culprit-cut.test.mjs b/tests/culprit-cut.test.mjs new file mode 100644 index 0000000..b22db72 --- /dev/null +++ b/tests/culprit-cut.test.mjs @@ -0,0 +1,57 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { classifyByRule } from '../packages/explore/src/lib/frame-classes.ts'; +import { isShownFrame, OWN_CODE_CLASSES, SHOWN_CLASSES } from '../packages/explore/src/lib/task-timeline.ts'; + +const DRAWN = new Set(SHOWN_CLASSES); +const OWN = new Set(OWN_CODE_CLASSES); + +const frame = (functionName, url) => ({ functionName, url, scriptId: '1', lineNumber: 0, columnNumber: 0 }); +const shown = (name, url, kept) => isShownFrame(name, classifyByRule(frame(name, url)), kept); + +const ROOT = '/Users/dev/social-app'; + +/** + * The eight rows a symbolicated React Native recording put in front of a + * reader who had asked for their own code. Every one of them is a dependency + * the toggle is supposed to be hiding. + */ +const DEPENDENCIES = [ + ['loadModuleImplementation', `${ROOT}/node_modules/@expo/cli/build/metro-require/require.js`], + ['computeFullKey', `${ROOT}/node_modules/react-refresh/cjs/react-refresh-runtime.development.js`], + ['metroRequire', `${ROOT}/node_modules/@expo/cli/build/metro-require/require.js`], + ['_receiveSignal', `${ROOT}/node_modules/react-native/Libraries/Pressability/Pressability.js`], + ['onResponderRelease', `${ROOT}/node_modules/react-native/Libraries/Pressability/Pressability.js`], + ['guardedLoadModule', `${ROOT}/node_modules/@expo/cli/build/metro-require/require.js`], + ['(anonymous)', `${ROOT}/node_modules/react-refresh/cjs/react-refresh-runtime.development.js`], + ['collectCustomHooksForSignature', `${ROOT}/node_modules/react-refresh/cjs/react-refresh-runtime.development.js`], +]; + +test('a dependency is not the reader’s code, however ordinary its name reads', () => { + for (const [name, url] of DEPENDENCIES) { + assert.equal(classifyByRule(frame(name, url)), 'library', name); + assert.equal(shown(name, url, OWN), false, `${name} is hidden from the culprit table`); + // The chart keeps it, and has to: dropping a box moves every box above it. + assert.equal(shown(name, url, DRAWN), true, `${name} is still drawn on the chart`); + } +}); + +test('the two cuts differ only over dependencies', () => { + assert.deepEqual([...OWN_CODE_CLASSES], ['app', 'anonymous']); + assert.deepEqual(SHOWN_CLASSES.filter((cls) => !OWN.has(cls)), ['library']); +}); + +test('what the reader came for survives the narrower cut', () => { + // Their own file. + assert.equal(shown('OpenCameraBtn', `${ROOT}/src/view/com/composer/photos/OpenCameraBtn.tsx`, OWN), true); + // A nameless frame with no URL is as likely to be their arrow function as + // anyone's, so the table would rather show one too many than hide theirs. + assert.equal(shown('(anonymous)', '', OWN), true); + assert.equal(shown('Function call', '', OWN), true); + // A built-in that names itself is a call the product made at a cost it + // controls — `isShownFrame` keeps it past either set. + assert.equal(shown('intlDateTimeFormatFormat', '', OWN), true); + // React's own internals go, under both cuts. + assert.equal(shown('commitPassiveMountOnFiber', `${ROOT}/node_modules/react-native/Libraries/Renderer/implementations/ReactFabric-dev.js`, OWN), false); + assert.equal(shown('(idle)', '', OWN), false); +}); From a5d2fbb5d893a5844ec25b093cf1cb3aeaec846d Mon Sep 17 00:00:00 2001 From: Hur Ali Date: Thu, 5 Nov 2026 16:41:45 +0500 Subject: [PATCH 10/10] feat: add rn-profiler --- .gitignore | 1 + packages/cli/src/cli.js | 32 ++- packages/cli/src/hermes-profile.js | 197 ++++++++++++++ packages/cli/src/profile-build.js | 225 +++++++++++++++ packages/cli/src/record-rn.js | 98 +++++++ packages/cli/src/record-session.js | 2 +- packages/cli/src/record.js | 98 +++++-- packages/cli/src/rn-profiler-link.js | 186 +++++++++++++ packages/cli/src/rn-release-session.js | 257 ++++++++++++++++++ packages/cli/test/hermes-profile.test.js | 149 ++++++++++ packages/cli/test/profile-build.test.js | 173 ++++++++++++ packages/cli/test/record-targets-rn.test.js | 151 ++++++++++ packages/cli/test/rn-release-session.test.js | 217 +++++++++++++++ packages/rn-profiler/README.md | 67 +++++ packages/rn-profiler/android/build.gradle | 58 ++++ .../android/src/main/AndroidManifest.xml | 24 ++ .../profiler/ProfilerInitProvider.kt | 59 ++++ .../com/tracesift/profiler/ProfilerLink.kt | 180 ++++++++++++ .../profiler/TracesiftProfilerModule.kt | 48 ++++ .../profiler/TracesiftProfilerPackage.kt | 14 + packages/rn-profiler/package.json | 27 ++ packages/rn-profiler/src/index.ts | 39 +++ scripts/test-codex-local.sh | 17 +- 23 files changed, 2288 insertions(+), 31 deletions(-) create mode 100644 packages/cli/src/hermes-profile.js create mode 100644 packages/cli/src/profile-build.js create mode 100644 packages/cli/src/record-rn.js create mode 100644 packages/cli/src/rn-profiler-link.js create mode 100644 packages/cli/src/rn-release-session.js create mode 100644 packages/cli/test/hermes-profile.test.js create mode 100644 packages/cli/test/profile-build.test.js create mode 100644 packages/cli/test/record-targets-rn.test.js create mode 100644 packages/cli/test/rn-release-session.test.js create mode 100644 packages/rn-profiler/README.md create mode 100644 packages/rn-profiler/android/build.gradle create mode 100644 packages/rn-profiler/android/src/main/AndroidManifest.xml create mode 100644 packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerInitProvider.kt create mode 100644 packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerLink.kt create mode 100644 packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerModule.kt create mode 100644 packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerPackage.kt create mode 100644 packages/rn-profiler/package.json create mode 100644 packages/rn-profiler/src/index.ts diff --git a/.gitignore b/.gitignore index c0afd95..4a067c4 100644 --- a/.gitignore +++ b/.gitignore @@ -43,5 +43,6 @@ next-env.d.ts /packages/cli/release.json /packages/cli/*.tgz +/packages/rn-profiler/android/build test-fixtures/local/ diff --git a/packages/cli/src/cli.js b/packages/cli/src/cli.js index 7e67fbc..16b9b41 100755 --- a/packages/cli/src/cli.js +++ b/packages/cli/src/cli.js @@ -4,9 +4,17 @@ import { prerequisites, install } from './install.js'; import { start, parsePort } from './start.js'; import { explore } from './explore.js'; import { - RECORD_SUBCOMMANDS, assertRecordOptions, parseDuration, parsePlatform, + RECORD_SUBCOMMANDS, assertRecordOptions, parseDuration, parsePlatform, parseProfilerPort, recordClose, recordLaunch, recordStart, recordStatus, recordStop, recordTargets, } from './record.js'; +import { PROFILE_SUBCOMMANDS, assertProfileOptions, profileBuild } from './profile-build.js'; + +/** Every flag the CLI knows, so a subcommand can refuse the ones it ignores. */ +const KNOWN_OPTIONS = [ + 'port', 'no-open', 'task', 'commit', 'focus', 'url', 'chrome', 'user-data-dir', 'out', + 'duration', 'headless', 'sink', 'platform', 'metro', 'app', 'device', 'target-id', + 'no-source-maps', 'json', 'profiler-port', 'source-map', 'variant', 'no-install', 'no-launch', +]; try { const { values, positionals } = parseArgs({ allowPositionals: true, options: { @@ -17,32 +25,46 @@ try { sink: { type: 'string' }, platform: { type: 'string' }, metro: { type: 'string' }, app: { type: 'string' }, device: { type: 'string' }, 'target-id': { type: 'string' }, 'no-source-maps': { type: 'boolean' }, json: { type: 'boolean' }, + 'profiler-port': { type: 'string' }, 'source-map': { type: 'string' }, + variant: { type: 'string' }, 'no-install': { type: 'boolean' }, 'no-launch': { type: 'boolean' }, } }); const [command, ...extra] = positionals; if (values.help || !command) { - console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n tracesift record start [--url https://example.com] [--duration 30s] [--headless] [--out trace.json.gz]\n tracesift record stop\n tracesift record status [--json]\n tracesift record targets --platform rn [--metro http://127.0.0.1:8081] [--json]\n tracesift record start --platform rn [--metro URL] [--app id] [--device name] [--target-id id]\n tracesift record launch [--url https://example.com] [--headless] [--chrome path] [--user-data-dir path]\n tracesift record close\n\nRecording drives Chrome over the DevTools Protocol, so it needs no browser\nextension. It streams into a running TraceSift when there is one and writes a\n.json.gz otherwise; --sink ingest|local forces either.\n\nWith no browser open, record start launches its own Chrome and traces the page\nload. To profile a state you reached by hand, record launch a browser, sign in\nor navigate, then record start: it attaches without navigating, and the\nbrowser stays open after record stop until record close.\n\n--platform rn records a Hermes CPU profile from a React Native app that is\nalready running in a simulator, emulator or device, over the Metro inspector.\nNothing is launched and no window opens: `record targets --platform rn` lists\nthe connected apps, and `record start --platform rn` attaches to the one that\nis running. Metro must be up; release builds are not supported yet.\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); + console.log('Usage:\n tracesift init\n tracesift start [--port 3000] [--no-open]\n tracesift explore [--task 0] [--focus node-id]\n tracesift explore --commit 1.2\n tracesift record start [--url https://example.com] [--duration 30s] [--headless] [--out trace.json.gz]\n tracesift record stop\n tracesift record status [--json]\n tracesift record targets --platform rn [--metro http://127.0.0.1:8081] [--json]\n tracesift record start --platform rn [--metro URL] [--app id] [--device name] [--target-id id]\n [--profiler-port 8089] [--source-map path]\n tracesift record launch [--url https://example.com] [--headless] [--chrome path] [--user-data-dir path]\n tracesift record close\n tracesift profile build [--platform android] [--variant release] [--device id]\n [--profiler-port 8089] [--no-install] [--no-launch]\n\nRecording drives Chrome over the DevTools Protocol, so it needs no browser\nextension. It streams into a running TraceSift when there is one and writes a\n.json.gz otherwise; --sink ingest|local forces either.\n\nWith no browser open, record start launches its own Chrome and traces the page\nload. To profile a state you reached by hand, record launch a browser, sign in\nor navigate, then record start: it attaches without navigating, and the\nbrowser stays open after record stop until record close.\n\n--platform rn records a Hermes CPU profile from a React Native app that is\nalready running in a simulator, emulator or device. Nothing is launched and no\nwindow opens: `record targets --platform rn` lists the apps connected to Metro,\nand `record start --platform rn` attaches to the one that is running.\n\nIt takes whichever of the two routes the build offers. A debug build is read\nover the Metro inspector. A release or profiling build has no inspector target,\nso it is read instead from @callstack/tracesift-rn-profiler, which the app must\ncarry: it dials 127.0.0.1:8089 (--profiler-port), which on Android needs\n`adb reverse tcp:8089 tcp:8089`. There is no Metro to serve a source map for a\nrelease build, so one is read from the path the React Native Gradle plugin\nwrites, or from --source-map.\n\n`profile build` produces that release build for you, from the root of the app:\nit adds the profiler package, assembles the variant with profiling armed,\ninstalls it, reverses the port and launches the app. Nothing in the project is\nedited — the switch is a Gradle property, so a build you run yourself ships the\npackage inert. Then record it with `record start --platform rn`.\n\nChoose the model and enter its API key in Analysis settings.\nRequires Node.js >=22.19 on x64 or arm64 macOS/Linux (WSL supported).'); } else { - if (!['init', 'start', 'explore', 'record'].includes(command)) throw new Error('Unknown command. Run tracesift --help.'); - if (!['explore', 'record'].includes(command) && extra.length) throw new Error('Unknown command. Run tracesift --help.'); + if (!['init', 'start', 'explore', 'record', 'profile'].includes(command)) throw new Error('Unknown command. Run tracesift --help.'); + if (!['explore', 'record', 'profile'].includes(command) && extra.length) throw new Error('Unknown command. Run tracesift --help.'); if (command === 'explore' && extra.length !== 1) throw new Error('Explore requires one analysis path. Run tracesift --help.'); if (command === 'record' && (extra.length !== 1 || !RECORD_SUBCOMMANDS.includes(extra[0]))) { throw new Error('Record requires one of start, stop, status, targets, launch or close. Run tracesift --help.'); } + if (command === 'profile' && (extra.length !== 1 || !PROFILE_SUBCOMMANDS.includes(extra[0]))) { + throw new Error('Profile requires one of build. Run tracesift --help.'); + } if ((values.port || values['no-open']) && command !== 'start') throw new Error('This option is not supported for this command. Run tracesift --help.'); if ((values.task || values.commit || values.focus) && command !== 'explore') throw new Error('This option is not supported for this command. Run tracesift --help.'); - assertRecordOptions(command, extra[0], values); + if (command === 'profile') assertProfileOptions(extra[0], values, KNOWN_OPTIONS); + else assertRecordOptions(command, extra[0], values); if (values.sink && !['auto', 'ingest', 'local'].includes(values.sink)) throw new Error('Sink must be auto, ingest or local.'); prerequisites(); if (command === 'init') await install(); else if (command === 'start') await start({ port: parsePort(values.port), open: !values['no-open'] }); else if (command === 'explore') await explore(extra[0], { task: values.task, commit: values.commit, focus: values.focus }); + else if (command === 'profile') await profileBuild({ + platform: values.platform ?? 'android', + variant: values.variant, device: values.device, + profilerPort: parseProfilerPort(values['profiler-port']), + install: !values['no-install'], launch: !values['no-launch'], + }); else if (extra[0] === 'targets') await recordTargets({ platform: parsePlatform(values.platform), metro: values.metro, json: values.json, + profilerPort: parseProfilerPort(values['profiler-port']), }); else if (extra[0] === 'start') await recordStart({ platform: parsePlatform(values.platform), url: values.url, chrome: values.chrome, userDataDir: values['user-data-dir'], metro: values.metro, app: values.app, device: values.device, targetId: values['target-id'], + profilerPort: parseProfilerPort(values['profiler-port']), sourceMapPath: values['source-map'], sourceMaps: !values['no-source-maps'], out: values.out, duration: parseDuration(values.duration), headless: values.headless, sink: values.sink, }); diff --git a/packages/cli/src/hermes-profile.js b/packages/cli/src/hermes-profile.js new file mode 100644 index 0000000..019a59e --- /dev/null +++ b/packages/cli/src/hermes-profile.js @@ -0,0 +1,197 @@ +// Hermes "Tracery" sampling profiles, converted to the CDP profile shape the +// rest of the pipeline already speaks. +// +// `HermesRuntime::dumpSampledTraceToFile` and `dumpSampledTraceToStream` are +// the only sampling-profiler entry points reachable without a jsi::Runtime +// reference, which is what lets a release build be profiled from a plain +// native hook with no JS and no TurboModule. They write Hermes' own Tracery +// format rather than a CDP profile: +// +// { traceEvents: [...metadata only...], +// samples: [{ cpu, name, ts, pid, tid, weight, sf }], +// stackFrames: { "": { name, category, parent?, ... } } } +// +// Hermes' other serializer does emit a CDP profile, but only from +// `IHermes::sampledTraceToStreamInDevToolsFormat`, which is per-runtime. The +// conversion is cheap and lives here, in JS, where it is testable against a +// fixture and fixable without rebuilding anybody's app. + +// Hermes' id generator starts at 1 and the first node it allocates is the +// root, which is also the only node emitted without a `parent`. +const ROOT_FRAME_ID = 1; + +/** `funcName(file:line:column)`, the name Hermes builds when debug info exists. */ +const NAMED_LOCATION = /^(.*)\((.+):(\d+):(\d+)\)$/; + +/** Hermes spells the root `[root]`; the analyzer's idle/root handling wants `(root)`. */ +const ROOT_FUNCTION_NAME = '(root)'; + +/** + * Parse the bytes a Hermes dump produced. + * + * An empty body is not corruption: `dumpTraceryTraceGlobal` writes nothing at + * all when no runtime has a profiler registered, so say what that means. + * + * @param {string} text + */ +export function parseTraceryProfile(text) { + const trimmed = typeof text === 'string' ? text.trim() : ''; + if (trimmed === '') { + throw new Error('The app returned an empty profile. Hermes writes nothing when no runtime has the sampling profiler registered — reload the app and record again.'); + } + let raw; + try { + raw = JSON.parse(trimmed); + } catch (error) { + throw new Error(`The app returned a profile that is not JSON: ${error.message}`); + } + if (!raw || typeof raw !== 'object' || Array.isArray(raw)) { + throw new Error('The app returned a profile that is not a Hermes sampling profile.'); + } + return raw; +} + +/** + * The thread that did the most sampling. + * + * Hermes folds every thread's stacks into one tree and tags only the samples + * with a `tid`, so a profile can carry the JS thread and whatever else was + * running. A CDP profile is one thread, and the busiest one is the JS thread + * in every case we care about. + * + * @param {Array>} samples + */ +function busiestThread(samples) { + const counts = new Map(); + for (const sample of samples) { + const tid = String(sample.tid ?? ''); + counts.set(tid, (counts.get(tid) ?? 0) + 1); + } + let best = ''; + let bestCount = -1; + for (const [tid, count] of counts) { + if (count > bestCount) { best = tid; bestCount = count; } + } + return best; +} + +/** + * Build a CDP `callFrame` from one Tracery stack frame. + * + * A release bundle carries no debug info, so the common case is a JavaScript + * frame with `funcVirtAddr` and `offset` and nothing else — no line, no + * column, and no url, because Tracery never emits one. Hermes generates a + * bundle's source map against the bytecode virtual offset expressed as a + * column on line 1, so that is what the frame is given, converted to CDP's + * zero-based line and column. The url is stamped by the caller, since only it + * knows which bundle the app is running, and the source map is registered + * under the same string: symbolication matches the two by exact equality. + * + * @param {Record} frame + * @param {string} bundleUrl + */ +function callFrameFor(frame, bundleUrl) { + const name = typeof frame.name === 'string' ? frame.name : ''; + const category = typeof frame.category === 'string' ? frame.category : ''; + + if (category === 'root') { + return { functionName: ROOT_FUNCTION_NAME, scriptId: '0', url: '', lineNumber: -1, columnNumber: -1 }; + } + + if (category !== 'JavaScript') { + // `[Native] fn`, `[HostFunction] fn`, `[]`, `[multiple]`. The + // names are already bracketed the way the analyzer's frame naming expects, + // so they are passed through whole. + return { functionName: name, scriptId: '0', url: '', lineNumber: -1, columnNumber: -1 }; + } + + // Debug info present: Hermes bakes the location into the name and repeats it + // in `line`/`column`, both as strings and both one-based. + if (frame.line !== undefined && frame.column !== undefined) { + const line = Number(frame.line); + const column = Number(frame.column); + const match = NAMED_LOCATION.exec(name); + return { + functionName: match ? match[1] : name, + scriptId: '1', + url: match ? match[2] : bundleUrl, + lineNumber: Number.isFinite(line) ? Math.max(-1, line - 1) : -1, + columnNumber: Number.isFinite(column) ? Math.max(-1, column - 1) : -1, + }; + } + + const funcVirtAddr = Number(frame.funcVirtAddr); + const offset = Number(frame.offset); + const position = (Number.isFinite(funcVirtAddr) ? funcVirtAddr : 0) + (Number.isFinite(offset) ? offset : 0); + return { + functionName: name, + scriptId: '1', + url: bundleUrl, + lineNumber: 0, + columnNumber: position, + }; +} + +/** + * Convert a parsed Hermes Tracery profile into the CDP profile shape + * `cpuProfileToTraceEvents` takes. + * + * Timestamps are microseconds on a steady clock — boot time on Android, the + * mach origin on Darwin — so they are only meaningful relative to each other. + * The first sample becomes the origin and the rest become deltas, which is + * what the analyzer reads anyway; it recomputes `endTime` from their sum. + * + * @param {Record} raw a parsed Tracery profile + * @param {{ bundleUrl?: string }} [options] + * @returns {{ nodes: object[], samples: number[], timeDeltas: number[], startTime: number }} + */ +export function traceryToCpuProfile(raw, { bundleUrl = '' } = {}) { + const stackFrames = raw.stackFrames && typeof raw.stackFrames === 'object' ? raw.stackFrames : null; + const rawSamples = Array.isArray(raw.samples) ? raw.samples : null; + if (!stackFrames || !rawSamples) { + throw new Error('The app returned a profile with no stackFrames or samples. This is not a Hermes sampling profile.'); + } + if (rawSamples.length === 0) { + throw new Error('The app returned a profile with no samples. The sampling profiler was enabled but nothing ran — record for longer, or make sure the app is in the foreground.'); + } + + // Every thread shares the frame tree, so the whole table is carried over and + // the samples decide which of it is reachable. The root goes first, which is + // what a CDP profile's consumers expect. + const nodes = []; + for (const [key, frame] of Object.entries(stackFrames)) { + if (!frame || typeof frame !== 'object') continue; + const id = Number(key); + if (!Number.isFinite(id)) continue; + const parent = typeof frame.parent === 'number' ? frame.parent : Number(frame.parent); + nodes.push({ + id, + callFrame: callFrameFor(frame, bundleUrl), + ...(Number.isFinite(parent) ? { parent } : {}), + }); + } + if (nodes.length === 0) throw new Error('The app returned a profile with an empty stack frame table.'); + nodes.sort((a, b) => (a.id === ROOT_FRAME_ID ? -1 : b.id === ROOT_FRAME_ID ? 1 : a.id - b.id)); + + const tid = busiestThread(rawSamples); + const samples = []; + const timestamps = []; + for (const sample of rawSamples) { + if (String(sample.tid ?? '') !== tid) continue; + // `sf` is a number while the stackFrames keys are decimal strings; the + // node ids above are numbers, so this needs no translation beyond Number. + const sf = Number(sample.sf); + const ts = Number(sample.ts); + if (!Number.isFinite(sf) || !Number.isFinite(ts)) continue; + samples.push(sf); + timestamps.push(ts); + } + if (samples.length === 0) { + throw new Error('The app returned a profile whose samples carry no usable stack frame ids.'); + } + + const startTime = timestamps[0]; + const timeDeltas = timestamps.map((ts, index) => (index === 0 ? 0 : Math.max(0, ts - timestamps[index - 1]))); + + return { nodes, samples, timeDeltas, startTime }; +} diff --git a/packages/cli/src/profile-build.js b/packages/cli/src/profile-build.js new file mode 100644 index 0000000..e22ae8d --- /dev/null +++ b/packages/cli/src/profile-build.js @@ -0,0 +1,225 @@ +// `tracesift profile build` — turn an app into a profiling build and get it +// onto the device, without the developer editing anything. +// +// Profiling a release build needs three things to line up: the profiler +// package in the app, the Gradle property that arms it, and a reverse port so +// the app's localhost is the developer's. None is difficult and all three are +// easy to get wrong in a way that fails silently — an app built without the +// property simply never dials, and the recording times out saying so. +// +// So the command does all three. It is the difference between "install this, +// add a line to your manifest, remember a -P flag, remember adb reverse" and +// one command. +import { spawn } from 'node:child_process'; +import { access, readFile } from 'node:fs/promises'; +import { constants } from 'node:fs'; +import { join, resolve } from 'node:path'; + +import { DEFAULT_PROFILER_PORT } from './rn-profiler-link.js'; + +export const PROFILER_PACKAGE = '@callstack/tracesift-rn-profiler'; +/** The Gradle property the library's manifest placeholder reads. */ +export const PROFILER_GRADLE_PROPERTY = 'tracesiftProfiler'; + +export const PROFILE_SUBCOMMANDS = ['build']; + +/** Which options each `profile` subcommand understands. */ +const PROFILE_OPTIONS = { + build: ['platform', 'variant', 'device', 'profiler-port', 'no-install', 'no-launch'], +}; + +/** + * Reject an option `profile` would silently ignore, the way `record` does: + * a flag that looks honoured but is not is worse than one that is refused. + */ +export function assertProfileOptions(subcommand, values, allKnownOptions) { + const allowed = PROFILE_OPTIONS[subcommand] ?? []; + const given = allKnownOptions.filter((option) => values[option]); + const rejected = given.find((option) => !allowed.includes(option)); + if (rejected) throw new Error(`--${rejected} is not supported by tracesift profile ${subcommand}. Run tracesift --help.`); +} + +/** `release` -> `assembleRelease`. */ +export function assembleTask(variant) { + if (!/^[a-z][a-zA-Z0-9]*$/.test(variant)) { + throw new Error('--variant must be a Gradle variant name such as release or profiling.'); + } + return `assemble${variant[0].toUpperCase()}${variant.slice(1)}`; +} + +/** + * Which package manager the project uses. + * + * Read off the lockfile rather than asked for: installing with the wrong one + * leaves two lockfiles disagreeing, which is a worse day than a missing flag. + */ +export async function detectPackageManager(root) { + const lockfiles = [ + ['pnpm-lock.yaml', 'pnpm'], + ['yarn.lock', 'yarn'], + ['bun.lockb', 'bun'], + ['package-lock.json', 'npm'], + ]; + for (const [lockfile, manager] of lockfiles) { + if (await exists(join(root, lockfile))) return manager; + } + return 'npm'; +} + +/** The argv that adds the profiler as a dev dependency. */ +export function installArgs(manager) { + switch (manager) { + case 'yarn': return ['add', '--dev', PROFILER_PACKAGE]; + case 'pnpm': return ['add', '--save-dev', PROFILER_PACKAGE]; + case 'bun': return ['add', '--dev', PROFILER_PACKAGE]; + default: return ['install', '--save-dev', PROFILER_PACKAGE]; + } +} + +async function exists(path) { + try { + await access(path, constants.F_OK); + return true; + } catch { + return false; + } +} + +/** + * Read the applicationId and apk filename out of the metadata the Android + * Gradle plugin writes beside the build. Guessing either from the Gradle + * files means reproducing AGP's variant and flavour rules, and getting it + * wrong installs the wrong apk. + * + * @param {string} androidRoot + * @param {string} variant + */ +export async function readApkMetadata(androidRoot, variant) { + const path = join(androidRoot, 'app', 'build', 'outputs', 'apk', variant, 'output-metadata.json'); + let parsed; + try { + parsed = JSON.parse(await readFile(path, 'utf8')); + } catch (error) { + throw new Error(`The build finished but left no apk metadata at ${path}: ${error.message}`); + } + const element = parsed.elements?.[0]; + if (!parsed.applicationId || !element?.outputFile) { + throw new Error(`The apk metadata at ${path} names no applicationId or output file.`); + } + return { + applicationId: parsed.applicationId, + apkPath: join(androidRoot, 'app', 'build', 'outputs', 'apk', variant, element.outputFile), + }; +} + +/** Where the React Native Gradle plugin writes the variant's source map. */ +export function sourceMapPathFor(androidRoot, variant) { + return join(androidRoot, 'app', 'build', 'generated', 'sourcemaps', 'react', variant, 'index.android.bundle.map'); +} + +/** Run a command, inheriting stdio so the build's own output is the output. */ +function run(command, args, options = {}) { + return new Promise((resolvePromise, reject) => { + const child = spawn(command, args, { stdio: 'inherit', ...options }); + child.on('error', (error) => reject(new Error(`Could not run ${command}: ${error.message}`))); + child.on('exit', (code) => { + if (code === 0) resolvePromise(); + else reject(new Error(`${command} ${args[0] ?? ''} failed with exit code ${code}.`)); + }); + }); +} + +/** Run a command and capture stdout, for the ones we read rather than show. */ +function capture(command, args) { + return new Promise((resolvePromise, reject) => { + const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] }); + let out = ''; + let err = ''; + child.stdout.on('data', (chunk) => { out += chunk; }); + child.stderr.on('data', (chunk) => { err += chunk; }); + child.on('error', (error) => reject(new Error(`Could not run ${command}: ${error.message}`))); + child.on('exit', (code) => { + if (code === 0) resolvePromise(out); + else reject(new Error(`${command} ${args[0] ?? ''} failed: ${err.trim() || out.trim() || `exit code ${code}`}`)); + }); + }); +} + +/** + * Build, install and arm a profiling build. + * + * @param {{ + * platform?: string, + * projectRoot?: string, + * variant?: string, + * device?: string, + * profilerPort?: number, + * install?: boolean, + * launch?: boolean, + * exec?: typeof run, + * execCapture?: typeof capture, + * }} options + */ +export async function profileBuild(options = {}) { + const platform = options.platform ?? 'android'; + if (platform !== 'android') { + throw new Error('tracesift profile build supports --platform android. On iOS a release build can be profiled over the Metro inspector by building React Native from source.'); + } + + const exec = options.exec ?? run; + const execCapture = options.execCapture ?? capture; + const root = resolve(options.projectRoot ?? process.cwd()); + const androidRoot = join(root, 'android'); + const variant = options.variant ?? 'release'; + const port = options.profilerPort ?? DEFAULT_PROFILER_PORT; + + if (!await exists(join(root, 'package.json'))) { + throw new Error(`There is no package.json in ${root}. Run this from the root of a React Native app.`); + } + const gradlew = join(androidRoot, process.platform === 'win32' ? 'gradlew.bat' : 'gradlew'); + if (!await exists(gradlew)) { + throw new Error(`There is no android/gradlew in ${root}. Run this from the root of a React Native app.`); + } + + if (options.install !== false && !await exists(join(root, 'node_modules', ...PROFILER_PACKAGE.split('/')))) { + const manager = await detectPackageManager(root); + console.log(`Adding ${PROFILER_PACKAGE} as a dev dependency with ${manager}.`); + await exec(manager, installArgs(manager), { cwd: root }); + } + + const task = assembleTask(variant); + console.log(`Building ${task} with profiling armed (-P${PROFILER_GRADLE_PROPERTY}=true).`); + await exec(gradlew, [task, `-P${PROFILER_GRADLE_PROPERTY}=true`], { cwd: androidRoot }); + + const { applicationId, apkPath } = await readApkMetadata(androidRoot, variant); + const adb = ['adb', ...(options.device ? ['-s', options.device] : [])]; + + console.log(`Installing ${applicationId}.`); + await exec(adb[0], [...adb.slice(1), 'install', '-r', apkPath]); + + // Without this the app's localhost is the device's own, and it dials into + // nothing. It is the step most easily forgotten and the one whose absence + // looks exactly like a broken build. + await exec(adb[0], [...adb.slice(1), 'reverse', `tcp:${port}`, `tcp:${port}`]); + console.log(`Reversed port ${port}, so the app reaches this machine on localhost.`); + + if (options.launch !== false) { + const resolved = await execCapture(adb[0], [...adb.slice(1), 'shell', 'cmd', 'package', 'resolve-activity', '--brief', applicationId]); + const component = resolved.trim().split('\n').map((line) => line.trim()).filter((line) => line.includes('/')).pop(); + if (component) { + await exec(adb[0], [...adb.slice(1), 'shell', 'am', 'start', '-n', component]); + console.log(`Launched ${component}.`); + } + } + + const sourceMap = sourceMapPathFor(androidRoot, variant); + const hasSourceMap = await exists(sourceMap); + console.log(''); + console.log('Ready. Record it with:'); + console.log(` tracesift record start --platform rn${hasSourceMap ? '' : ` --source-map `}`); + if (!hasSourceMap) { + console.log(`\nNo source map at ${sourceMap}, so frames would be reported at bundle positions. Point --source-map at the one your build produces.`); + } + + return { applicationId, apkPath, sourceMap: hasSourceMap ? sourceMap : null, port }; +} diff --git a/packages/cli/src/record-rn.js b/packages/cli/src/record-rn.js new file mode 100644 index 0000000..f560168 --- /dev/null +++ b/packages/cli/src/record-rn.js @@ -0,0 +1,98 @@ +// Choosing between the two React Native capture routes. +// +// There are two, and which one applies is a property of the build, not of the +// developer's intent: a debug build registers an inspector target with Metro, +// a release build carrying @callstack/tracesift-rn-profiler dials us instead. +// Asking the user to name the one they are on would be asking them to tell us +// something we can see for ourselves. +// +// So both are offered at once. Metro is tried first because it is a single +// HTTP request that fails immediately when nothing is listening, and because +// a debug build is what a developer has running by default. +import { defaultMetroOrigin, metroTargets, parseMetroOrigin, selectMetroTarget } from './metro.js'; +import { awaitProfilerApp, DEFAULT_PROFILER_PORT, noAppConnectedMessage } from './rn-profiler-link.js'; +import { errorText } from './record-session.js'; +import { writeRecordState } from './record-state.js'; + +// How long to hold the port open for a release build before giving up. The +// profiler retries its dial every couple of seconds, so this only has to +// outlast a few of those. It also has to leave room inside `record start`'s +// own budget for waiting on the recorder, or the caller times out first and +// reports that instead of the reason collected here. +const CONNECT_TIMEOUT_MS = 20_000; + +/** + * Record from whichever React Native app we can reach. + * + * @param {Record} options + */ +export async function runRnAnyRecording(options) { + const port = options.profilerPort ?? DEFAULT_PROFILER_PORT; + + // The listener goes up first so an app that is already retrying its dial is + // caught while Metro is still being probed. + const controller = new AbortController(); + const pending = awaitProfilerApp({ port, signal: controller.signal }); + // Nothing awaits this until Metro has been ruled out, and an unobserved + // rejection in between would take the recorder down with it. + pending.catch(() => undefined); + + const metroFailure = await probeMetro(options); + if (!metroFailure) { + controller.abort(new Error('Recording over Metro instead.')); + pending.then((link) => link.close()).catch(() => undefined); + const { runRnRecording } = await import('./record-rn-session.js'); + return runRnRecording(options); + } + + let timer; + const deadline = new Promise((_resolve, reject) => { + timer = setTimeout(() => reject(new Error(noAppConnectedMessage(metroFailure, port))), CONNECT_TIMEOUT_MS); + timer.unref?.(); + }); + deadline.catch(() => undefined); + + let link; + try { + link = await Promise.race([pending, deadline]); + } catch (error) { + // Neither recorder ever started, so neither has written a record state. + // Without one `record start` waits out its own budget and reports a + // timeout in place of the reason collected here. + await writeRecordState(options.home, { + apiVersion: 1, + pid: process.pid, + mode: 'local', + state: 'failed', + startedAt: Date.now(), + url: `http://127.0.0.1:${port}`, + targetLabel: 'React Native app', + error: errorText(error), + }).catch(() => undefined); + throw error; + } finally { + clearTimeout(timer); + controller.abort(new Error('Gave up waiting for a release build.')); + } + + const { runRnReleaseRecording } = await import('./rn-release-session.js'); + return runRnReleaseRecording({ ...options, link }); +} + +/** + * Is there a debug build on Metro we can attach to? + * + * @returns {Promise} null when there is, otherwise why not + */ +async function probeMetro(options) { + try { + const origin = parseMetroOrigin(options.metro || defaultMetroOrigin()); + const found = await metroTargets(origin); + selectMetroTarget(found, { + app: options.app, device: options.device, targetId: options.targetId, origin, + }); + return null; + } catch (error) { + return errorText(error); + } +} diff --git a/packages/cli/src/record-session.js b/packages/cli/src/record-session.js index 46cfb4f..6b0a85e 100644 --- a/packages/cli/src/record-session.js +++ b/packages/cli/src/record-session.js @@ -498,7 +498,7 @@ export async function recorderMain(argv) { try { const options = JSON.parse(argv[0]); const run = options.platform === 'rn' - ? (await import('./record-rn-session.js')).runRnRecording + ? (await import('./record-rn.js')).runRnAnyRecording : runRecording; await run(options); } catch (error) { diff --git a/packages/cli/src/record.js b/packages/cli/src/record.js index c60b2df..5089f30 100644 --- a/packages/cli/src/record.js +++ b/packages/cli/src/record.js @@ -21,11 +21,12 @@ const CLOSE_TIMEOUT_MS = 10_000; // browser; everything about the trace itself belongs to `start`. const RECORD_OPTIONS = { start: ['url', 'chrome', 'user-data-dir', 'out', 'duration', 'headless', 'sink', - 'platform', 'metro', 'app', 'device', 'target-id', 'no-source-maps'], + 'platform', 'metro', 'app', 'device', 'target-id', 'no-source-maps', + 'profiler-port', 'source-map'], // `launch` and `close` take --platform only so that naming rn there gets the // reason it makes no sense rather than a flag-not-supported error. launch: ['url', 'chrome', 'user-data-dir', 'headless', 'platform'], - targets: ['platform', 'metro', 'json'], + targets: ['platform', 'metro', 'json', 'profiler-port'], stop: [], status: ['json'], close: ['platform'], @@ -36,7 +37,7 @@ export const RECORD_SUBCOMMANDS = Object.keys(RECORD_OPTIONS); // wrong one is a mistake worth failing on: it would otherwise look like the // recording honoured a setting it silently dropped. const CHROME_ONLY = ['url', 'chrome', 'user-data-dir', 'headless']; -const RN_ONLY = ['metro', 'app', 'device', 'target-id', 'no-source-maps']; +const RN_ONLY = ['metro', 'app', 'device', 'target-id', 'no-source-maps', 'profiler-port', 'source-map']; /** Normalise `--platform`, which defaults to Chrome. */ export function parsePlatform(value) { @@ -76,6 +77,15 @@ export function assertRecordOptions(command, subcommand, values) { } } +/** The loopback port a release build's profiler dials. */ +export function parseProfilerPort(value) { + if (value === undefined) return undefined; + if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 65535) { + throw new Error('--profiler-port must be an integer between 1 and 65535.'); + } + return Number(value); +} + /** Accept `30`, `30s`, `500ms` or `2m`; a bare number is seconds. */ export function parseDuration(value) { if (value === undefined) return undefined; @@ -119,6 +129,10 @@ async function waitFor(home, predicate, timeout, onTimeout, pid) { const state = await readRecordState(home); const mine = state && (pid === undefined || state.pid === pid) ? state : null; if (mine && predicate(mine)) return mine; + // A recorder that has already recorded its own reason has nothing left to + // say, and waiting out the deadline would replace that reason with a + // generic timeout. + if (mine?.state === 'failed') throw new Error(mine.error || 'The recorder stopped before it finished.'); if (mine && !processAlive(mine.pid) && mine.state !== 'captured') { throw new Error(mine.error || 'The recorder stopped before it finished.'); } @@ -127,21 +141,46 @@ async function waitFor(home, predicate, timeout, onTimeout, pid) { } } +/** The id a release build is listed under; it needs one, but there is only ever one. */ +export const RELEASE_TARGET_ID = 'release'; + /** - * List the apps connected to Metro, so a recording can name one — and so a - * harness can find out what is there without starting anything. + * List the React Native apps a recording could attach to, over either route. + * + * Both are reported because the two are not a preference but a property of + * the build, and a caller that lists before it records — the panel does, and + * so does the agent — would otherwise conclude there is nothing to record + * whenever the app is a release build. + * + * Metro is awaited first. Only when it has nothing to show is the profiler + * port given its window, so the ordinary debug listing stays immediate. */ export async function recordTargets(options = {}) { const platform = options.platform ?? 'chrome'; if (platform !== 'rn') { throw new Error('tracesift record targets lists React Native apps. Run it with --platform rn.'); } + const { describeProfilerApp, noAppConnectedMessage, probeProfilerApp, DEFAULT_PROFILER_PORT } = + await import('./rn-profiler-link.js'); + const origin = parseMetroOrigin(options.metro || defaultMetroOrigin()); const label = origin.href.replace(/\/$/, ''); - let targets; + const port = options.profilerPort ?? DEFAULT_PROFILER_PORT; + + let targets = []; + let metroFailure = null; try { targets = await metroTargets(origin); } catch (error) { + metroFailure = error.message; + } + + const hello = targets.length === 0 ? await probeProfilerApp({ port }) : null; + + if (targets.length === 0 && !hello) { + const error = new Error(metroFailure + ? noAppConnectedMessage(metroFailure, port) + : noAppConnectedMessage(`Metro on ${label} has no app connected to it. Launch the app and wait for the bundle to finish loading.`, port)); if (!options.json) throw error; console.log(JSON.stringify({ apiVersion: 1, error: error.message })); process.exitCode = 1; @@ -154,30 +193,49 @@ export async function recordTargets(options = {}) { try { recommended = selectMetroTarget(targets, { origin }); } catch { recommended = undefined; } + const release = hello ? { + id: RELEASE_TARGET_ID, + title: describeProfilerApp(hello), + ...(typeof hello.app === 'string' ? { appId: hello.app } : {}), + ...(typeof hello.device === 'string' ? { deviceName: hello.device } : {}), + transport: 'release', + port, + } : null; + if (options.json) { console.log(JSON.stringify({ apiVersion: 1, platform: 'rn', metro: label, - targets: targets.map((target) => ({ - id: target.id, - title: target.title, - ...(target.appId ? { appId: target.appId } : {}), - ...(target.deviceName ? { deviceName: target.deviceName } : {}), - ...(target.deviceId ? { deviceId: target.deviceId } : {}), - ...(target.vm ? { vm: target.vm } : {}), - supportsMultipleDebuggers: target.supportsMultipleDebuggers, - recommended: target.id === recommended?.id, - })), + profilerPort: port, + targets: [ + ...targets.map((target) => ({ + id: target.id, + title: target.title, + ...(target.appId ? { appId: target.appId } : {}), + ...(target.deviceName ? { deviceName: target.deviceName } : {}), + ...(target.deviceId ? { deviceId: target.deviceId } : {}), + ...(target.vm ? { vm: target.vm } : {}), + transport: 'metro', + supportsMultipleDebuggers: target.supportsMultipleDebuggers, + recommended: target.id === recommended?.id, + })), + // A release build is the only thing to record when it is the only + // thing listed, which is the case whenever it is listed at all. + ...(release ? [{ ...release, supportsMultipleDebuggers: false, recommended: true }] : []), + ], })); return targets; } - if (targets.length === 0) { - console.log(`Metro on ${label} has no app connected to it.`); - console.log('Launch the app in a simulator, emulator or device and wait for the bundle to finish loading.'); + if (release) { + console.log(`Release build on port ${port}\n`); + console.log(` ${release.title}`); + if (release.appId) console.log(` app ${release.appId}`); + console.log('\nRecord it with: tracesift record start --platform rn'); return targets; } + console.log(`Metro on ${label}\n`); for (const target of targets) { console.log(` ${describeMetroTarget(target)}${target.id === recommended?.id ? ' (default)' : ''}`); @@ -214,6 +272,8 @@ export async function recordStart(options = {}) { app: options.app, device: options.device, targetId: options.targetId, + profilerPort: options.profilerPort, + sourceMapPath: options.sourceMapPath, sourceMaps: options.sourceMaps !== false, out: options.out, duration: options.duration, diff --git a/packages/cli/src/rn-profiler-link.js b/packages/cli/src/rn-profiler-link.js new file mode 100644 index 0000000..0f5564e --- /dev/null +++ b/packages/cli/src/rn-profiler-link.js @@ -0,0 +1,186 @@ +// The link to a release build carrying @callstack/tracesift-rn-profiler. +// +// The app dials us rather than the other way round. That is how React +// Native's own inspector works, and it means there is nothing to discover: no +// device list, no adb enumeration, no guessing which emulator is the one. On +// Android `adb reverse tcp:8089 tcp:8089` makes the device's localhost ours, +// and a simulator shares the host's already. +// +// The wire is newline-delimited JSON over a plain TCP socket. A websocket +// would need a server implementation this package does not ship, and buys +// nothing here: both ends are ours and the framing is one line per message. +import { createServer } from 'node:net'; + +export const DEFAULT_PROFILER_PORT = 8089; + +// A connecting app announces itself before anything else happens, and an app +// that connects without saying anything is not ours. +const HELLO_TIMEOUT_MS = 10_000; +// Base64 of a multi-megabyte profile, split so no single line is unbounded. +const MAX_LINE_BYTES = 8 * 1024 * 1024; + +/** + * Wrap a socket as a line-delimited JSON channel. + * + * @param {import('node:net').Socket} socket + */ +function jsonChannel(socket) { + let buffer = ''; + const waiting = []; + const queued = []; + let failure = null; + + const deliver = (message) => { + const next = waiting.shift(); + if (next) next.resolve(message); + else queued.push(message); + }; + const fail = (error) => { + failure ??= error; + while (waiting.length) waiting.shift().reject(failure); + }; + + socket.setEncoding('utf8'); + socket.on('data', (chunk) => { + buffer += chunk; + if (buffer.length > MAX_LINE_BYTES) { + fail(new Error('The app sent an oversized message.')); + socket.destroy(); + return; + } + let index = buffer.indexOf('\n'); + while (index !== -1) { + const line = buffer.slice(0, index).trim(); + buffer = buffer.slice(index + 1); + if (line !== '') { + try { + deliver(JSON.parse(line)); + } catch { + fail(new Error('The app sent a message that is not JSON.')); + socket.destroy(); + return; + } + } + index = buffer.indexOf('\n'); + } + }); + socket.on('error', (error) => fail(error)); + socket.on('close', () => fail(new Error('The app disconnected before the recording finished. Nothing was captured — relaunch the app and record again.'))); + + return { + get closed() { return socket.destroyed || socket.readyState !== 'open'; }, + send(message) { socket.write(`${JSON.stringify(message)}\n`); }, + /** @returns {Promise>} */ + next() { + if (queued.length) return Promise.resolve(queued.shift()); + if (failure) return Promise.reject(failure); + return new Promise((resolve, reject) => waiting.push({ resolve, reject })); + }, + close() { socket.destroy(); }, + }; +} + +/** + * Listen on loopback for a profiling-enabled app to connect, and return the + * channel once it has introduced itself. + * + * Loopback only, deliberately: this socket drives a profiler inside somebody's + * application, and it has no business being reachable from the network. + * + * @param {{ port?: number, signal?: AbortSignal }} [options] + * @returns {Promise<{ channel: ReturnType, hello: Record, close(): void }>} + */ +export function awaitProfilerApp({ port = DEFAULT_PROFILER_PORT, signal } = {}) { + return new Promise((resolve, reject) => { + const server = createServer(); + let settled = false; + const done = (fn) => (value) => { + if (settled) return; + settled = true; + fn(value); + }; + const fail = done((error) => { server.close(); reject(error); }); + + server.on('error', (error) => { + fail(error.code === 'EADDRINUSE' + ? new Error(`Port ${port} is already in use, so there is nowhere for the app to connect. Stop whatever is on it, or pass --profiler-port.`) + : error); + }); + + server.on('connection', (socket) => { + socket.setNoDelay(true); + const channel = jsonChannel(socket); + const timer = setTimeout(() => { + channel.close(); + fail(new Error('Something connected to the profiler port but did not identify itself as a React Native app.')); + }, HELLO_TIMEOUT_MS); + timer.unref?.(); + channel.next().then((hello) => { + clearTimeout(timer); + if (hello?.type !== 'hello') { + channel.close(); + fail(new Error('Something connected to the profiler port but did not identify itself as a React Native app.')); + return; + } + // One app at a time: a second connection would race for the same + // process-global Hermes sampler. + server.close(); + done(resolve)({ channel, hello, close: () => { channel.close(); server.close(); } }); + }).catch((error) => { clearTimeout(timer); fail(error); }); + }); + + signal?.addEventListener('abort', () => fail(signal.reason ?? new Error('Aborted')), { once: true }); + server.listen(port, '127.0.0.1'); + }); +} + +/** + * Look for a release build without recording one. + * + * `record targets` has to be able to see a profiling build, or a caller that + * lists before it records — the panel does, and so does the agent's skill — + * concludes there is nothing to record when there is. The app's dial loop + * retries every couple of seconds, so a short window catches one that is + * already running without making the listing feel like a wait. + * + * The connection is dropped as soon as the app has introduced itself. The app + * reconnects on its next retry, which is what leaves the port free for the + * `record start` that usually follows. + * + * @param {{ port?: number, timeoutMs?: number, signal?: AbortSignal }} [options] + * @returns {Promise | null>} the app's hello, or null + */ +export async function probeProfilerApp({ port = DEFAULT_PROFILER_PORT, timeoutMs = 6_000, signal } = {}) { + const controller = new AbortController(); + const abort = () => controller.abort(new Error('Stopped looking for a release build.')); + const timer = setTimeout(abort, timeoutMs); + timer.unref?.(); + signal?.addEventListener('abort', abort, { once: true }); + + try { + const link = await awaitProfilerApp({ port, signal: controller.signal }); + link.close(); + return link.hello; + } catch { + // Nothing dialled in, the port is somebody else's, or the caller gave up. + // All three mean the same thing to a listing: no release build to report. + return null; + } finally { + clearTimeout(timer); + abort(); + } +} + +/** Why neither React Native route found an app, said once for both. */ +export function noAppConnectedMessage(metroFailure, port = DEFAULT_PROFILER_PORT) { + return 'No React Native app connected.\n' + + ` Debug build over Metro: ${metroFailure}\n` + + ` Release build on port ${port}: nothing dialled in. Install @callstack/tracesift-rn-profiler and build with \`tracesift profile build\`, which also runs \`adb reverse tcp:${port} tcp:${port}\`.`; +} + +/** How the app describes itself, for the recording's label. */ +export function describeProfilerApp(hello) { + const app = typeof hello.app === 'string' && hello.app ? hello.app : 'React Native app'; + const platform = hello.platform === 'ios' ? 'iOS' : hello.platform === 'android' ? 'Android' : null; + return platform ? `${app} (${platform}, release)` : `${app} (release)`; +} diff --git a/packages/cli/src/rn-release-session.js b/packages/cli/src/rn-release-session.js new file mode 100644 index 0000000..4cffd37 --- /dev/null +++ b/packages/cli/src/rn-release-session.js @@ -0,0 +1,257 @@ +// Recording a release build, which has no Metro and no inspector target. +// +// The debug path attaches to the Metro inspector proxy and drives CDP +// `Tracing.*`. A release build registers no target there, so there is nothing +// to attach to — and making one appear means rebuilding React Native from +// source, which on Android is not reachable at all from the published AAR. +// +// Instead the app carries @callstack/tracesift-rn-profiler, which drives +// Hermes' process-global sampling profiler and dials us. Everything after the +// profile arrives is shared with the Metro path: the same trace-event writer, +// the same sink, the same export envelope. +import { readFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; + +import { parseTraceryProfile, traceryToCpuProfile } from './hermes-profile.js'; +import { errorText, resolveSink } from './record-session.js'; +import { cpuProfileToTraceEvents } from './record-rn-session.js'; +import { writeRecordState } from './record-state.js'; +import { awaitProfilerApp, DEFAULT_PROFILER_PORT, describeProfilerApp } from './rn-profiler-link.js'; +import { createTraceEventWriter } from './trace-chunker.js'; + +const MAX_UPLOAD_BYTES = 192 * 1024; +const STOP_POLL_MS = 1000; +const FLUSH_TIMEOUT_MS = 120_000; +const SAMPLING_HZ = 1000; +// Without its `sourcesContent` a Metro map is a few MB; with it, a copy of the +// whole app. The debug path applies the same limit after stripping. +const MAX_SOURCE_MAP_BYTES = 48 * 1024 * 1024; + +/** + * Where the React Native Gradle plugin puts a release bundle's source map. + * It is derived from the variant name, so the common ones are tried in turn. + */ +const GRADLE_SOURCE_MAP_PATHS = [ + 'android/app/build/generated/sourcemaps/react/release/index.android.bundle.map', + 'android/app/build/generated/sourcemaps/react/profiling/index.android.bundle.map', +]; + +/** + * Load the source map for the bundle the app reported. + * + * There is no Metro to fetch it from, so it comes off disk: the path the user + * gave, or the deterministic one the Gradle plugin writes. It is registered + * under the same url the converter stamps onto frames, because symbolication + * matches the two by exact string equality. + * + * @param {{ bundleUrl: string, sourceMapPath?: string, cwd?: string }} options + * @returns {Promise<{ retained: object[], warnings: string[] }>} + */ +export async function loadReleaseSourceMap({ bundleUrl, sourceMapPath, cwd = process.cwd() }) { + const warnings = []; + const candidates = sourceMapPath ? [resolve(cwd, sourceMapPath)] : GRADLE_SOURCE_MAP_PATHS.map((path) => resolve(cwd, path)); + + for (const path of candidates) { + let raw; + try { + raw = await readFile(path, 'utf8'); + } catch (error) { + // Only an explicit --source-map is worth complaining about; the Gradle + // guesses are guesses, and the catch-all below covers them. + if (sourceMapPath) warnings.push(`Could not read the source map ${path}: ${errorText(error)}`); + continue; + } + try { + const sourceMap = JSON.parse(raw); + if (!sourceMap || typeof sourceMap !== 'object' || Array.isArray(sourceMap)) throw new Error('not a JSON object'); + delete sourceMap.sourcesContent; + const size = JSON.stringify(sourceMap).length; + if (size > MAX_SOURCE_MAP_BYTES) throw new Error(`is ${Math.round(size / 1048576)} MB without its sources, past the retention limit`); + return { retained: [{ url: bundleUrl, sourceMapUrl: path, sourceMap }], warnings }; + } catch (error) { + warnings.push(`Could not retain the source map ${path}: ${errorText(error)}`); + } + } + + warnings.push(`React Native frames are reported at bundle positions in ${bundleUrl}; no source map was found. Pass --source-map to symbolicate them.`); + return { retained: [], warnings }; +} + +/** The record.json shape both the starting and recording states share. */ +function recordState(home, sink, target, state, extra = {}) { + return writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink.mode, + state, + startedAt: Date.now(), + url: target.url, + targetLabel: target.title, + captureId: sink.captureId, + ...(sink.baseUrl ? { baseUrl: sink.baseUrl } : {}), + ...(sink.directory ? { directory: sink.directory } : {}), + ...extra, + }); +} + +/** + * Read `profile` messages until the app marks one last, and reassemble them. + * + * Hermes hands the whole dump over at once and it is megabytes, so it arrives + * base64 in ordered pieces. The sequence numbers are checked rather than + * trusted: a silently dropped chunk would become a truncated profile, which + * parses into a plausible-looking lie. + * + * @param {{ next(): Promise> }} channel + */ +async function readProfile(channel, requestId) { + const pieces = []; + for (;;) { + const message = await channel.next(); + if (message.type === 'error') { + throw new Error(`The app could not produce a profile: ${message.message ?? 'no reason given'}`); + } + if (message.type !== 'profile' || message.id !== requestId) continue; + const sequence = Number(message.seq); + if (sequence !== pieces.length) { + throw new Error(`The app sent profile chunk ${sequence} where ${pieces.length} was expected, so the profile is incomplete.`); + } + pieces.push(typeof message.data === 'string' ? message.data : ''); + if (message.last === true) break; + } + return Buffer.from(pieces.join(''), 'base64').toString('utf8'); +} + +/** + * Record a Hermes CPU profile from a release build carrying the profiler + * package. + * + * @param {{ + * home: string, + * profilerPort?: number, + * sourceMapPath?: string, + * sourceMaps?: boolean, + * out?: string, + * duration?: number, + * sink?: 'auto' | 'ingest' | 'local', + * link?: { channel: object, hello: Record, close(): void }, + * onReady?: (info: { captureId: string, mode: string }) => void, + * }} options + */ +export async function runRnReleaseRecording(options) { + const { home } = options; + const port = options.profilerPort ?? DEFAULT_PROFILER_PORT; + let link = options.link ?? null; + let sink; + let target = { platform: 'react-native', title: 'React Native app', url: `http://127.0.0.1:${port}` }; + let stopReason = 'manual'; + const warnings = []; + let releaseStopWatchers = () => {}; + + try { + link ??= await awaitProfilerApp({ port }); + const { channel, hello } = link; + const bundleUrl = typeof hello.bundle === 'string' && hello.bundle ? hello.bundle : 'index.android.bundle'; + + target = { + platform: 'react-native', + title: describeProfilerApp(hello), + url: `http://127.0.0.1:${port}`, + ...(typeof hello.app === 'string' ? { appId: hello.app } : {}), + ...(typeof hello.device === 'string' ? { deviceName: hello.device } : {}), + }; + + sink = await resolveSink(home, target, target.title, options); + await recordState(home, sink, target, 'starting'); + await sink.status({ state: 'attaching' }).catch(() => undefined); + + const writer = createTraceEventWriter(sink, { maxBytes: MAX_UPLOAD_BYTES }); + const requestId = 1; + channel.send({ type: 'start', id: requestId, hz: SAMPLING_HZ }); + + await recordState(home, sink, target, 'recording'); + await sink.status({ state: 'recording' }).catch(() => undefined); + options.onReady?.({ captureId: sink.captureId, mode: sink.mode }); + + let stop; + const stopped = new Promise((resolve_) => { stop = (reason) => { stopReason = reason; resolve_(reason); }; }); + const onSignal = () => stop('manual'); + process.on('SIGINT', onSignal); + process.on('SIGTERM', onSignal); + const durationTimer = options.duration ? setTimeout(() => stop('manual'), options.duration) : null; + const poller = setInterval(() => { + void sink.stopRequested().then((requested) => { if (requested) stop('manual'); }).catch(() => undefined); + }, STOP_POLL_MS); + releaseStopWatchers = () => { + process.off('SIGINT', onSignal); + process.off('SIGTERM', onSignal); + if (durationTimer) clearTimeout(durationTimer); + clearInterval(poller); + }; + + await stopped; + await sink.status({ state: 'flushing', stopReason }).catch(() => undefined); + + let text; + try { + channel.send({ type: 'stop', id: requestId }); + let flushTimer; + const flushDeadline = new Promise((_resolve, reject) => { + flushTimer = setTimeout(() => reject(new Error('The app did not finish sending the profile in time.')), FLUSH_TIMEOUT_MS); + flushTimer.unref?.(); + }); + flushDeadline.catch(() => undefined); + try { + text = await Promise.race([readProfile(channel, requestId), flushDeadline]); + } finally { + clearTimeout(flushTimer); + } + } finally { + releaseStopWatchers(); + } + + const profile = traceryToCpuProfile(parseTraceryProfile(text), { bundleUrl }); + await writer.write(cpuProfileToTraceEvents(profile)); + await writer.end(); + + await sink.status({ state: 'enriching' }).catch(() => undefined); + const collected = options.sourceMaps === false + ? { retained: [], warnings: [] } + : await loadReleaseSourceMap({ bundleUrl, sourceMapPath: options.sourceMapPath }); + warnings.push(...collected.warnings); + + // The Hermes sampler reports nothing about tasks or frames, so unlike the + // Metro path there is no TracingStartedInPage for the exporter to lean on. + const result = await sink.finalize({ + dataLoss: false, + stopReason, + scripts: [], + sourceMaps: collected.retained, + warnings, + }); + + await recordState(home, sink, target, 'captured', { + export: { path: result.path ?? '', sizeBytes: result.sizeBytes, eventCount: result.eventCount }, + warnings: result.warnings ?? warnings, + }); + return { ...result, mode: sink.mode, captureId: sink.captureId, baseUrl: sink.baseUrl }; + } catch (error) { + const message = errorText(error); + await sink?.fail(message).catch(() => undefined); + await writeRecordState(home, { + apiVersion: 1, + pid: process.pid, + mode: sink?.mode ?? 'local', + state: 'failed', + startedAt: Date.now(), + url: target.url, + targetLabel: target.title, + ...(sink?.captureId ? { captureId: sink.captureId } : {}), + error: message, + }).catch(() => undefined); + throw error; + } finally { + releaseStopWatchers(); + link?.close(); + } +} diff --git a/packages/cli/test/hermes-profile.test.js b/packages/cli/test/hermes-profile.test.js new file mode 100644 index 0000000..ad9053f --- /dev/null +++ b/packages/cli/test/hermes-profile.test.js @@ -0,0 +1,149 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; + +import { parseTraceryProfile, traceryToCpuProfile } from '../src/hermes-profile.js'; +import { cpuProfileToTraceEvents } from '../src/record-rn-session.js'; + +const BUNDLE = 'index.android.bundle'; + +/** + * A Tracery profile the way Hermes actually writes one: frame ids are decimal + * string keys, `parent` and `sf` are numbers, `ts` is a string of microseconds + * on a steady clock, and a release bundle's JS frames carry `funcVirtAddr` and + * `offset` instead of a line, a column or a url. + */ +function tracery({ samples } = {}) { + return { + traceEvents: [ + { name: 'process_name', ph: 'M', cat: '__metadata', pid: 999, ts: '81000', tid: '-1', args: { name: 'hermes' } }, + ], + samples: samples ?? [ + { cpu: '-1', name: '', ts: '81000', pid: 999, tid: '7', weight: '1', sf: 3 }, + { cpu: '-1', name: '', ts: '81100', pid: 999, tid: '7', weight: '1', sf: 4 }, + { cpu: '-1', name: '', ts: '81350', pid: 999, tid: '7', weight: '1', sf: 3 }, + ], + stackFrames: { + 1: { name: '[root]', category: 'root' }, + 2: { name: 'global', category: 'JavaScript', parent: 1, funcVirtAddr: '100', offset: '0' }, + 3: { name: 'fibonacci', category: 'JavaScript', parent: 2, funcVirtAddr: '2048', offset: '17' }, + 4: { name: '[Native] Array.prototype.sort', category: 'Native', parent: 2 }, + 5: { name: '[GC Young Gen]', category: 'Metadata', parent: 1 }, + }, + }; +} + +test('parseTraceryProfile explains an empty dump rather than failing to parse', () => { + assert.throws(() => parseTraceryProfile(''), /no runtime has the sampling profiler registered/); + assert.throws(() => parseTraceryProfile(' '), /no runtime has the sampling profiler registered/); +}); + +test('parseTraceryProfile rejects non-JSON and non-objects', () => { + assert.throws(() => parseTraceryProfile('not json'), /is not JSON/); + assert.throws(() => parseTraceryProfile('[1,2]'), /not a Hermes sampling profile/); +}); + +test('traceryToCpuProfile carries the whole frame table with the root first', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + + assert.equal(profile.nodes[0].id, 1); + assert.equal(profile.nodes[0].callFrame.functionName, '(root)'); + assert.equal(profile.nodes[0].parent, undefined, 'the root is the node with no parent'); + assert.deepEqual(profile.nodes.map((node) => node.id), [1, 2, 3, 4, 5]); + // Frames reachable from no sample are kept: the tree is shared between + // threads and dropping them would break the parent walk. + assert.ok(profile.nodes.some((node) => node.id === 5)); +}); + +test('traceryToCpuProfile reads string ids and keeps the parent chain as numbers', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + const byId = new Map(profile.nodes.map((node) => [node.id, node])); + + assert.equal(typeof byId.get(3).id, 'number'); + assert.equal(byId.get(3).parent, 2); + assert.equal(byId.get(2).parent, 1); + + // Leaf to root, which is how the stack is reconstructed. + const walk = []; + for (let id = 3; id !== undefined; id = byId.get(id)?.parent) walk.push(id); + assert.deepEqual(walk, [3, 2, 1]); +}); + +test('traceryToCpuProfile folds funcVirtAddr and offset into a zero-based column on line 0', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + const fib = profile.nodes.find((node) => node.callFrame.functionName === 'fibonacci'); + + assert.equal(fib.callFrame.url, BUNDLE, 'the url is stamped, because Tracery emits none'); + assert.equal(fib.callFrame.lineNumber, 0); + assert.equal(fib.callFrame.columnNumber, 2048 + 17); + assert.equal(fib.callFrame.scriptId, '1'); +}); + +test('traceryToCpuProfile leaves native, host and GC frames unlocated', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + const native = profile.nodes.find((node) => node.id === 4); + const gc = profile.nodes.find((node) => node.id === 5); + + assert.equal(native.callFrame.functionName, '[Native] Array.prototype.sort'); + assert.equal(native.callFrame.url, ''); + assert.equal(native.callFrame.lineNumber, -1); + assert.equal(gc.callFrame.functionName, '[GC Young Gen]'); + assert.equal(gc.callFrame.url, ''); +}); + +test('traceryToCpuProfile uses the location Hermes bakes into a name when debug info exists', () => { + const raw = tracery(); + raw.stackFrames[3] = { + name: 'fibonacci(src/App.tsx:12:5)', category: 'JavaScript', parent: 2, line: '12', column: '5', + }; + const profile = traceryToCpuProfile(raw, { bundleUrl: BUNDLE }); + const fib = profile.nodes.find((node) => node.id === 3); + + assert.equal(fib.callFrame.functionName, 'fibonacci'); + assert.equal(fib.callFrame.url, 'src/App.tsx'); + assert.equal(fib.callFrame.lineNumber, 11, 'Hermes is one-based, CDP is zero-based'); + assert.equal(fib.callFrame.columnNumber, 4); +}); + +test('traceryToCpuProfile turns steady-clock timestamps into microsecond deltas', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + + assert.equal(profile.startTime, 81000); + assert.deepEqual(profile.samples, [3, 4, 3]); + assert.deepEqual(profile.timeDeltas, [0, 100, 250]); + assert.equal(profile.timeDeltas.length, profile.samples.length, 'deltas are index-parallel to samples'); +}); + +test('traceryToCpuProfile keeps only the busiest thread', () => { + const profile = traceryToCpuProfile(tracery({ + samples: [ + { ts: '1000', tid: '7', sf: 3 }, + { ts: '1100', tid: '9', sf: 4 }, + { ts: '1200', tid: '7', sf: 3 }, + { ts: '1300', tid: '7', sf: 2 }, + ], + }), { bundleUrl: BUNDLE }); + + assert.deepEqual(profile.samples, [3, 3, 2]); + assert.deepEqual(profile.timeDeltas, [0, 200, 100]); +}); + +test('traceryToCpuProfile explains a profile with nothing in it', () => { + assert.throws(() => traceryToCpuProfile({ samples: [], stackFrames: {} }), /no samples/); + assert.throws(() => traceryToCpuProfile({ samples: [{ ts: '1', tid: '1', sf: 1 }] }), /no stackFrames or samples/); + assert.throws( + () => traceryToCpuProfile({ samples: [{ ts: 'x', tid: '1', sf: 'y' }], stackFrames: { 1: { name: '[root]', category: 'root' } } }), + /no usable stack frame ids/, + ); +}); + +test('the converted profile survives cpuProfileToTraceEvents into Profile and ProfileChunk', () => { + const profile = traceryToCpuProfile(parseTraceryProfile(JSON.stringify(tracery())), { bundleUrl: BUNDLE }); + const events = cpuProfileToTraceEvents(profile); + + assert.equal(events[0].name, 'Profile'); + assert.equal(events[0].args.data.startTime, 81000); + assert.equal(events[1].name, 'ProfileChunk'); + assert.equal(events[1].args.data.cpuProfile.nodes.length, 5, 'the node table rides in the first chunk'); + assert.deepEqual(events[1].args.data.cpuProfile.samples, [3, 4, 3]); + assert.deepEqual(events[1].args.data.timeDeltas, [0, 100, 250]); +}); diff --git a/packages/cli/test/profile-build.test.js b/packages/cli/test/profile-build.test.js new file mode 100644 index 0000000..937b341 --- /dev/null +++ b/packages/cli/test/profile-build.test.js @@ -0,0 +1,173 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +import { + assembleTask, assertProfileOptions, detectPackageManager, installArgs, + profileBuild, readApkMetadata, sourceMapPathFor, PROFILER_PACKAGE, +} from '../src/profile-build.js'; + +async function temporaryDirectory(t) { + const directory = await mkdtemp(join(tmpdir(), 'tracesift-profile-')); + t.after(() => rm(directory, { recursive: true, force: true })); + return directory; +} + +/** A React Native project just real enough: package.json, gradlew, apk metadata. */ +async function fakeProject(t, { variant = 'release', lockfile = 'package-lock.json', sourceMap = true } = {}) { + const root = await temporaryDirectory(t); + await writeFile(join(root, 'package.json'), '{"name":"spike"}'); + await writeFile(join(root, lockfile), ''); + await mkdir(join(root, 'android'), { recursive: true }); + await writeFile(join(root, 'android', 'gradlew'), ''); + + const outputs = join(root, 'android', 'app', 'build', 'outputs', 'apk', variant); + await mkdir(outputs, { recursive: true }); + await writeFile(join(outputs, 'output-metadata.json'), JSON.stringify({ + applicationId: 'com.spikeapp', + elements: [{ outputFile: 'app-release.apk' }], + })); + + if (sourceMap) { + const maps = join(root, 'android', 'app', 'build', 'generated', 'sourcemaps', 'react', variant); + await mkdir(maps, { recursive: true }); + await writeFile(join(maps, 'index.android.bundle.map'), '{}'); + } + return root; +} + +/** Record every command instead of running it. */ +function recorder() { + const calls = []; + return { + calls, + exec: async (command, args, options) => { calls.push({ command, args, cwd: options?.cwd }); }, + execCapture: async () => 'com.spikeapp/.MainActivity\n', + }; +} + +test('assembleTask capitalises the variant and refuses anything that is not one', () => { + assert.equal(assembleTask('release'), 'assembleRelease'); + assert.equal(assembleTask('profiling'), 'assembleProfiling'); + assert.equal(assembleTask('prodRelease'), 'assembleProdRelease'); + for (const bad of ['', 'Release', 'release; rm -rf /', '--stacktrace', 'a b']) { + assert.throws(() => assembleTask(bad), /must be a Gradle variant name/, `rejects ${JSON.stringify(bad)}`); + } +}); + +test('the package manager is read off the lockfile', async (t) => { + for (const [lockfile, manager] of [['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'], ['bun.lockb', 'bun'], ['package-lock.json', 'npm']]) { + const root = await fakeProject(t, { lockfile }); + assert.equal(await detectPackageManager(root), manager); + } + const bare = await temporaryDirectory(t); + assert.equal(await detectPackageManager(bare), 'npm', 'npm is the fallback'); +}); + +test('each package manager gets its own add-a-dev-dependency argv', () => { + assert.deepEqual(installArgs('npm'), ['install', '--save-dev', PROFILER_PACKAGE]); + assert.deepEqual(installArgs('yarn'), ['add', '--dev', PROFILER_PACKAGE]); + assert.deepEqual(installArgs('pnpm'), ['add', '--save-dev', PROFILER_PACKAGE]); + assert.deepEqual(installArgs('bun'), ['add', '--dev', PROFILER_PACKAGE]); +}); + +test('the apk is located from the metadata the Android Gradle plugin writes', async (t) => { + const root = await fakeProject(t); + const { applicationId, apkPath } = await readApkMetadata(join(root, 'android'), 'release'); + assert.equal(applicationId, 'com.spikeapp'); + assert.match(apkPath, /outputs\/apk\/release\/app-release\.apk$/); +}); + +test('missing or incomplete apk metadata is reported against its path', async (t) => { + const root = await temporaryDirectory(t); + await assert.rejects(readApkMetadata(join(root, 'android'), 'release'), /left no apk metadata at/); + + const outputs = join(root, 'android', 'app', 'build', 'outputs', 'apk', 'release'); + await mkdir(outputs, { recursive: true }); + await writeFile(join(outputs, 'output-metadata.json'), '{"elements":[]}'); + await assert.rejects(readApkMetadata(join(root, 'android'), 'release'), /names no applicationId or output file/); +}); + +test('profile build assembles with the gate armed, installs, reverses and launches', async (t) => { + const root = await fakeProject(t); + const { calls, exec, execCapture } = recorder(); + + const result = await profileBuild({ projectRoot: root, install: false, exec, execCapture }); + + const gradle = calls.find((call) => call.command.endsWith('gradlew')); + assert.deepEqual(gradle.args, ['assembleRelease', '-PtracesiftProfiler=true']); + assert.equal(gradle.cwd, join(root, 'android')); + + const install = calls.find((call) => call.args.includes('install')); + assert.equal(install.command, 'adb'); + assert.match(install.args.at(-1), /app-release\.apk$/); + + const reverse = calls.find((call) => call.args.includes('reverse')); + assert.deepEqual(reverse.args, ['reverse', 'tcp:8089', 'tcp:8089']); + + const launch = calls.find((call) => call.args.includes('am')); + assert.deepEqual(launch.args, ['shell', 'am', 'start', '-n', 'com.spikeapp/.MainActivity']); + + assert.equal(result.applicationId, 'com.spikeapp'); + assert.equal(result.port, 8089); + assert.match(result.sourceMap, /sourcemaps\/react\/release\/index\.android\.bundle\.map$/); +}); + +test('the dev dependency is added only when it is not already there', async (t) => { + const root = await fakeProject(t); + const first = recorder(); + await profileBuild({ projectRoot: root, exec: first.exec, execCapture: first.execCapture }); + assert.deepEqual(first.calls[0], { command: 'npm', args: ['install', '--save-dev', PROFILER_PACKAGE], cwd: root }); + + await mkdir(join(root, 'node_modules', '@callstack', 'tracesift-rn-profiler'), { recursive: true }); + const second = recorder(); + await profileBuild({ projectRoot: root, exec: second.exec, execCapture: second.execCapture }); + assert.ok(!second.calls.some((call) => call.command === 'npm'), 'an installed package is not reinstalled'); +}); + +test('--device targets one device and --no-launch leaves the app alone', async (t) => { + const root = await fakeProject(t, { variant: 'profiling' }); + const { calls, exec, execCapture } = recorder(); + + await profileBuild({ projectRoot: root, install: false, device: 'emulator-5554', launch: false, variant: 'profiling', profilerPort: 9100, exec, execCapture }); + + const gradle = calls.find((call) => call.command.endsWith('gradlew')); + assert.deepEqual(gradle.args, ['assembleProfiling', '-PtracesiftProfiler=true']); + for (const call of calls.filter((entry) => entry.command === 'adb')) { + assert.deepEqual(call.args.slice(0, 2), ['-s', 'emulator-5554']); + } + assert.deepEqual( + calls.find((call) => call.args.includes('reverse')).args, + ['-s', 'emulator-5554', 'reverse', 'tcp:9100', 'tcp:9100'], + ); + assert.ok(!calls.some((call) => call.args.includes('am')), 'nothing is launched'); +}); + +test('a directory that is not a React Native app says so before anything runs', async (t) => { + const bare = await temporaryDirectory(t); + const { calls, exec, execCapture } = recorder(); + await assert.rejects(profileBuild({ projectRoot: bare, exec, execCapture }), /no package.json/); + + await writeFile(join(bare, 'package.json'), '{}'); + await assert.rejects(profileBuild({ projectRoot: bare, exec, execCapture }), /no android\/gradlew/); + assert.deepEqual(calls, [], 'nothing was run'); +}); + +test('iOS is refused with the route that does work there', async (t) => { + const root = await fakeProject(t); + await assert.rejects(profileBuild({ projectRoot: root, platform: 'ios' }), /supports --platform android/); +}); + +test('profile build refuses flags it would ignore', () => { + const known = ['url', 'variant', 'device', 'headless', 'metro']; + assert.throws(() => assertProfileOptions('build', { url: 'x' }, known), /--url is not supported by tracesift profile build/); + assert.throws(() => assertProfileOptions('build', { metro: 'x' }, known), /--metro is not supported/); + assert.doesNotThrow(() => assertProfileOptions('build', { variant: 'release', device: 'x' }, known)); +}); + +test('the source map path follows the variant', () => { + assert.match(sourceMapPathFor('/a', 'release'), /sourcemaps\/react\/release\/index\.android\.bundle\.map$/); + assert.match(sourceMapPathFor('/a', 'profiling'), /sourcemaps\/react\/profiling\//); +}); diff --git a/packages/cli/test/record-targets-rn.test.js b/packages/cli/test/record-targets-rn.test.js new file mode 100644 index 0000000..68e060d --- /dev/null +++ b/packages/cli/test/record-targets-rn.test.js @@ -0,0 +1,151 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { connect } from 'node:net'; +import { createServer } from 'node:http'; + +import { RELEASE_TARGET_ID, recordTargets } from '../src/record.js'; + +let nextPort = 19_300; +function freePort() { + nextPort += 1; + return nextPort; +} + +/** A Metro that serves /json/list, with whatever targets the test wants. */ +async function fakeMetro(t, targets) { + const server = createServer((request, response) => { + const { port } = server.address(); + if (!request.url.startsWith('/json/list')) { + response.writeHead(404); + response.end(); + return; + } + response.writeHead(200, { 'content-type': 'application/json' }); + response.end(JSON.stringify(targets.map((target) => ({ + id: target.id, + title: target.title, + appId: target.appId, + deviceName: target.deviceName, + vm: 'Hermes', + webSocketDebuggerUrl: `ws://127.0.0.1:${port}/inspector/debug?device=1&page=${target.id}`, + reactNative: { logicalDeviceId: target.id }, + })))); + }); + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + t.after(() => server.close()); + return `http://127.0.0.1:${server.address().port}`; +} + +/** A release build that dials the profiler port and introduces itself. */ +function fakeReleaseApp(t, port, hello) { + let socket; + const timer = setInterval(() => { + if (socket && !socket.destroyed) return; + socket = connect(port, '127.0.0.1'); + socket.on('error', () => undefined); + socket.on('connect', () => socket.write(`${JSON.stringify(hello ?? { + type: 'hello', app: 'com.example.spike', platform: 'android', bundle: 'index.android.bundle', device: 'Pixel 10 Pro', + })}\n`)); + }, 150); + timer.unref?.(); + t.after(() => { clearInterval(timer); socket?.destroy(); }); +} + +/** Run recordTargets with console.log captured. */ +async function listing(options) { + const lines = []; + const original = console.log; + console.log = (...args) => lines.push(args.join(' ')); + try { + await recordTargets(options); + } finally { + console.log = original; + } + return lines.join('\n'); +} + +async function listingJson(options) { + return JSON.parse(await listing({ ...options, json: true })); +} + +test('a debug build on Metro is listed without waiting on the profiler port', async (t) => { + const metro = await fakeMetro(t, [{ id: 'page-1', title: 'Spike', appId: 'com.example.spike', deviceName: 'Pixel' }]); + const started = Date.now(); + + const payload = await listingJson({ platform: 'rn', metro, profilerPort: freePort() }); + + assert.equal(payload.targets.length, 1); + assert.equal(payload.targets[0].transport, 'metro'); + assert.equal(payload.targets[0].recommended, true); + assert.ok(Date.now() - started < 3000, 'Metro answering means no release probe window is paid'); +}); + +test('a release build is listed when Metro has nothing', async (t) => { + const metro = await fakeMetro(t, []); + const port = freePort(); + fakeReleaseApp(t, port); + + const payload = await listingJson({ platform: 'rn', metro, profilerPort: port }); + + assert.equal(payload.targets.length, 1); + const [target] = payload.targets; + assert.equal(target.id, RELEASE_TARGET_ID); + assert.equal(target.transport, 'release'); + assert.equal(target.appId, 'com.example.spike'); + assert.equal(target.deviceName, 'Pixel 10 Pro'); + assert.equal(target.recommended, true, 'it is the only thing to record'); + assert.equal(payload.profilerPort, port); + assert.match(target.title, /com\.example\.spike \(Android, release\)/); +}); + +test('a release build is listed when Metro is not running at all', async (t) => { + const port = freePort(); + fakeReleaseApp(t, port); + + const payload = await listingJson({ platform: 'rn', metro: `http://127.0.0.1:${freePort()}`, profilerPort: port }); + + assert.equal(payload.targets.length, 1); + assert.equal(payload.targets[0].transport, 'release'); + assert.equal(payload.error, undefined, 'a dead Metro is not an error when a release build answered'); +}); + +test('the human listing names the release route and the command that records it', async (t) => { + const port = freePort(); + fakeReleaseApp(t, port); + + const text = await listing({ platform: 'rn', metro: `http://127.0.0.1:${freePort()}`, profilerPort: port }); + + assert.match(text, new RegExp(`Release build on port ${port}`)); + assert.match(text, /com\.example\.spike/); + assert.match(text, /tracesift record start --platform rn/); +}); + +test('neither route answering names both, not just Metro', async (t) => { + const metro = await fakeMetro(t, []); + await assert.rejects( + listing({ platform: 'rn', metro, profilerPort: freePort() }), + (error) => { + assert.match(error.message, /No React Native app connected/); + assert.match(error.message, /Debug build over Metro:/); + assert.match(error.message, /Release build on port/); + assert.match(error.message, /tracesift profile build/); + return true; + }, + ); +}); + +test('--json reports the same double failure as data, and exits non-zero', async (t) => { + const previous = process.exitCode; + t.after(() => { process.exitCode = previous; }); + const metro = await fakeMetro(t, []); + + const payload = await listingJson({ platform: 'rn', metro, profilerPort: freePort() }); + + assert.match(payload.error, /Debug build over Metro:/); + assert.match(payload.error, /Release build on port/); + assert.equal(process.exitCode, 1); +}); + +test('listing still refuses a platform that is not React Native', async () => { + await assert.rejects(recordTargets({ platform: 'chrome' }), /lists React Native apps/); +}); diff --git a/packages/cli/test/rn-release-session.test.js b/packages/cli/test/rn-release-session.test.js new file mode 100644 index 0000000..b1a37f1 --- /dev/null +++ b/packages/cli/test/rn-release-session.test.js @@ -0,0 +1,217 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { connect, createServer } from 'node:net'; +import { mkdtemp, rm, readFile, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { gunzipSync } from 'node:zlib'; + +import { loadReleaseSourceMap, runRnReleaseRecording } from '../src/rn-release-session.js'; +import { awaitProfilerApp } from '../src/rn-profiler-link.js'; +import { readRecordState } from '../src/record-state.js'; + +async function temporaryDirectory(t) { + const directory = await mkdtemp(join(tmpdir(), 'tracesift-rn-release-')); + t.after(() => rm(directory, { recursive: true, force: true })); + return directory; +} + +/** An unlikely-to-collide loopback port per test, since each opens a listener. */ +let nextPort = 18_900; +function freePort() { + nextPort += 1; + return nextPort; +} + +const PROFILE = { + traceEvents: [], + samples: [ + { cpu: '-1', name: '', ts: '500000', pid: 42, tid: '3', weight: '1', sf: 3 }, + { cpu: '-1', name: '', ts: '500250', pid: 42, tid: '3', weight: '1', sf: 3 }, + { cpu: '-1', name: '', ts: '500500', pid: 42, tid: '3', weight: '1', sf: 2 }, + ], + stackFrames: { + 1: { name: '[root]', category: 'root' }, + 2: { name: 'App', category: 'JavaScript', parent: 1, funcVirtAddr: '512', offset: '4' }, + 3: { name: 'fibonacci', category: 'JavaScript', parent: 2, funcVirtAddr: '1024', offset: '8' }, + }, +}; + +/** + * A release build carrying the profiler package: dials in, says hello, and + * answers `stop` with a chunked base64 Tracery dump. + * + * @param {{ port: number, chunks?: number, hello?: object, onStop?: (send: Function) => void }} options + */ +function fakeApp(t, { port, chunks = 1, hello, onStop }) { + const received = []; + const socket = connect(port, '127.0.0.1'); + t.after(() => socket.destroy()); + socket.setEncoding('utf8'); + const send = (message) => socket.write(`${JSON.stringify(message)}\n`); + + socket.on('connect', () => send(hello ?? { + type: 'hello', app: 'com.example.spike', platform: 'android', bundle: 'index.android.bundle', device: 'Pixel_10_Pro', + })); + + let buffer = ''; + socket.on('data', (chunk) => { + buffer += chunk; + let index = buffer.indexOf('\n'); + while (index !== -1) { + const line = buffer.slice(0, index).trim(); + buffer = buffer.slice(index + 1); + if (line) { + const message = JSON.parse(line); + received.push(message); + if (message.type === 'stop') { + if (onStop) onStop(send, message); + else { + const base64 = Buffer.from(JSON.stringify(PROFILE), 'utf8').toString('base64'); + const size = Math.ceil(base64.length / chunks); + for (let seq = 0; seq < chunks; seq += 1) { + send({ + type: 'profile', id: message.id, seq, + data: base64.slice(seq * size, (seq + 1) * size), + last: seq === chunks - 1, + }); + } + } + } + } + index = buffer.indexOf('\n'); + } + }); + socket.on('error', () => undefined); + return { received }; +} + +async function readExport(path) { + return JSON.parse(gunzipSync(await readFile(path)).toString('utf8')); +} + +async function record(t, home, overrides = {}) { + const port = overrides.profilerPort ?? freePort(); + const pending = runRnReleaseRecording({ + home, sink: 'local', sourceMaps: false, duration: 50, profilerPort: port, ...overrides, + }); + // Nothing is listening until the recorder binds, which it does immediately; + // the app's own retry loop is what covers this in the real world. + await new Promise((resolve) => setTimeout(resolve, 150)); + const app = fakeApp(t, { port, ...overrides }); + return { result: await pending, app, port }; +} + +test('a release recording is exported in the enhanced-trace envelope', async (t) => { + const home = await temporaryDirectory(t); + const { result, app } = await record(t, home); + + const document = await readExport(result.path); + assert.equal(document.metadata.enhancedTraceVersion, 1); + const { target } = document.metadata.traceSift; + assert.equal(target.platform, 'react-native'); + assert.equal(target.appId, 'com.example.spike'); + assert.equal(target.deviceName, 'Pixel_10_Pro'); + assert.match(target.title, /com\.example\.spike \(Android, release\)/); + + const chunk = document.traceEvents.find((event) => event.name === 'ProfileChunk'); + assert.ok(document.traceEvents.some((event) => event.name === 'Profile')); + assert.deepEqual(chunk.args.data.cpuProfile.samples, [3, 3, 2]); + assert.deepEqual(chunk.args.data.timeDeltas, [0, 250, 250]); + const fib = chunk.args.data.cpuProfile.nodes.find((node) => node.callFrame.functionName === 'fibonacci'); + assert.equal(fib.callFrame.url, 'index.android.bundle'); + assert.equal(fib.callFrame.columnNumber, 1024 + 8); + + assert.equal(app.received.filter((message) => message.type === 'start').length, 1); + assert.equal(app.received.find((message) => message.type === 'start').hz, 1000); + assert.equal((await readRecordState(home)).state, 'captured'); +}); + +test('a profile split across chunks is reassembled', async (t) => { + const home = await temporaryDirectory(t); + const { result } = await record(t, home, { chunks: 7 }); + + const document = await readExport(result.path); + const chunk = document.traceEvents.find((event) => event.name === 'ProfileChunk'); + assert.deepEqual(chunk.args.data.cpuProfile.samples, [3, 3, 2]); +}); + +test('an out-of-order chunk fails the recording rather than truncating it', async (t) => { + const home = await temporaryDirectory(t); + await assert.rejects( + record(t, home, { + onStop: (send, message) => { + send({ type: 'profile', id: message.id, seq: 0, data: 'eyJ=', last: false }); + send({ type: 'profile', id: message.id, seq: 4, data: 'eyJ=', last: true }); + }, + }), + /chunk 4 where 1 was expected/, + ); + const state = await readRecordState(home); + assert.equal(state.state, 'failed'); +}); + +test('an error from the app is reported with its reason', async (t) => { + const home = await temporaryDirectory(t); + await assert.rejects( + record(t, home, { + onStop: (send, message) => send({ type: 'error', id: message.id, message: 'sampling profiler unavailable' }), + }), + /sampling profiler unavailable/, + ); +}); + +test('an empty dump says what an empty dump means', async (t) => { + const home = await temporaryDirectory(t); + await assert.rejects( + record(t, home, { + onStop: (send, message) => send({ type: 'profile', id: message.id, seq: 0, data: '', last: true }), + }), + /no runtime has the sampling profiler registered/, + ); +}); + +test('a connection that does not introduce itself is turned away', async (t) => { + const port = freePort(); + const link = awaitProfilerApp({ port }); + await new Promise((resolve) => setTimeout(resolve, 100)); + + const socket = connect(port, '127.0.0.1'); + t.after(() => socket.destroy()); + socket.on('error', () => undefined); + socket.on('connect', () => socket.write('{"type":"something-else"}\n')); + + await assert.rejects(link, /did not identify itself as a React Native app/); +}); + +test('a port somebody else holds is reported as such', async (t) => { + const port = freePort(); + const held = await new Promise((resolve) => { + const server = createServer(); + server.listen(port, '127.0.0.1', () => resolve(server)); + }); + t.after(() => held.close()); + + await assert.rejects(awaitProfilerApp({ port }), /already in use/); +}); + +test('the source map is registered under the same url the frames carry', async (t) => { + const directory = await temporaryDirectory(t); + const path = join(directory, 'index.android.bundle.map'); + await writeFile(path, JSON.stringify({ version: 3, sources: ['App.tsx'], names: [], mappings: '', sourcesContent: ['x'] })); + + const { retained, warnings } = await loadReleaseSourceMap({ bundleUrl: 'index.android.bundle', sourceMapPath: path }); + assert.equal(warnings.length, 0); + assert.equal(retained[0].url, 'index.android.bundle', 'symbolication matches by exact string'); + assert.equal(retained[0].sourceMap.sourcesContent, undefined, 'the authored sources are dropped'); +}); + +test('a missing source map warns instead of failing the capture', async (t) => { + const directory = await temporaryDirectory(t); + const { retained, warnings } = await loadReleaseSourceMap({ + bundleUrl: 'index.android.bundle', sourceMapPath: join(directory, 'nope.map'), + }); + assert.deepEqual(retained, []); + assert.ok(warnings.some((warning) => /Could not read the source map/.test(warning))); + assert.ok(warnings.some((warning) => /no source map was found/.test(warning))); +}); diff --git a/packages/rn-profiler/README.md b/packages/rn-profiler/README.md new file mode 100644 index 0000000..011bcd6 --- /dev/null +++ b/packages/rn-profiler/README.md @@ -0,0 +1,67 @@ +# @callstack/tracesift-rn-profiler + +Record a Hermes CPU profile from a React Native **release or profiling build**, with no Metro and no debugger. + +`tracesift record start --platform rn` normally attaches to the Metro inspector, which only a debug build registers with. This package gives a release build something to attach to instead: it drives Hermes' sampling profiler directly and dials the CLI. + +Nothing is rebuilt from source. The sampling profiler is already in the published `react-android` artifact and the stock `hermes-engine` pod — it does not depend on the Hermes debugger, and it is reachable without a `jsi::Runtime` reference, which is why no React Native fork is involved. + +## Use it + +From the root of your app: + +```bash +npx tracesift profile build +``` + +```bash +npx tracesift record start --platform rn +``` + +That is the whole integration. The first command adds this package, assembles the release variant with profiling armed, installs it, reverses the port and launches the app; the second records. Stop with `tracesift record stop`. + +Nothing in your project is edited. Autolinking finds the package, so there is no import to add and no app code to write. + +## The gate + +The profiler is **off unless a build asks for it**. A release binary that opens a control socket on request is a remote-profiling backdoor, so arming it is a build-time decision — a Gradle property this package's own manifest placeholder reads: + +```bash +./gradlew assembleRelease -PtracesiftProfiler=true +``` + +`profile build` passes it for you. A build you run yourself does not, so the package ships inert: the provider is registered, reads one bundle and returns. No socket, no thread, no cost. + +To arm it permanently for a variant of your own, put `tracesiftProfiler=true` in `android/gradle.properties` — and be deliberate about which builds that reaches. + +## Source maps + +Release frames are reported at bundle positions, so a source map is needed to name them. Run `record start` from the app root and the CLI reads the one the React Native Gradle plugin writes to `android/app/build/generated/sourcemaps/react/release/index.android.bundle.map`. Otherwise point `--source-map` at it. + +## Options + +| | | +|---|---| +| `tracesift profile build --variant profiling` | assemble a variant other than `release` | +| `tracesift profile build --device emulator-5554` | pick one of several attached devices | +| `tracesift profile build --no-install` | do not touch `package.json` (for CI) | +| `tracesift profile build --no-launch` | install but leave the app closed | +| `--profiler-port 9100` | on both commands, if 8089 is taken | + +## Driving it from JS instead + +Only needed to profile something the CLI cannot bracket from outside: + +```ts +import { startProfiling, stopProfiling } from '@callstack/tracesift-rn-profiler'; + +startProfiling(); +// ... +const path = await stopProfiling(); // a Hermes sampling profile on the device +``` + +Hermes clears its buffer as it dumps, so each profile can be collected exactly once. + +## Status + +Android. iOS uses the same protocol and is not implemented yet; on iOS a release build can already be profiled over CDP by building React Native from source. diff --git a/packages/rn-profiler/android/build.gradle b/packages/rn-profiler/android/build.gradle new file mode 100644 index 0000000..e201519 --- /dev/null +++ b/packages/rn-profiler/android/build.gradle @@ -0,0 +1,58 @@ +buildscript { + repositories { + google() + mavenCentral() + } + dependencies { + classpath "com.android.tools.build:gradle:8.7.2" + classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${project.properties["TracesiftProfiler_kotlinVersion"] ?: "2.0.21"}" + } +} + +apply plugin: "com.android.library" +apply plugin: "org.jetbrains.kotlin.android" + +/** Fall back to the app's value when it sets one, so the library tracks its host. */ +def host(String name, Object fallback) { + return rootProject.ext.has(name) ? rootProject.ext.get(name) : fallback +} + +android { + namespace "com.tracesift.profiler" + compileSdk host("compileSdkVersion", 35) + + defaultConfig { + minSdk host("minSdkVersion", 24) + + // The gate lives here rather than in the app's manifest so that enabling + // profiling costs the app no edit at all — `-PtracesiftProfiler=true` + // reaches every project in the build, this one included. Off by default: + // a release binary that opens a control socket for the asking is a + // remote-profiling backdoor. + manifestPlaceholders = [ + tracesiftProfilerEnabled: (project.findProperty("tracesiftProfiler") ?: "false").toString(), + ] + } + + compileOptions { + sourceCompatibility JavaVersion.VERSION_17 + targetCompatibility JavaVersion.VERSION_17 + } +} + +kotlin { + jvmToolchain(17) +} + +repositories { + google() + mavenCentral() +} + +dependencies { + // Version-less on purpose: the React Native Gradle plugin in the host app + // pins this to whatever React Native the app is on. HermesSamplingProfiler + // comes from here — it is in the published react-android artifact, so + // nothing has to be built from source. + implementation "com.facebook.react:react-android" +} diff --git a/packages/rn-profiler/android/src/main/AndroidManifest.xml b/packages/rn-profiler/android/src/main/AndroidManifest.xml new file mode 100644 index 0000000..e380be9 --- /dev/null +++ b/packages/rn-profiler/android/src/main/AndroidManifest.xml @@ -0,0 +1,24 @@ + + + + + + + + + diff --git a/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerInitProvider.kt b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerInitProvider.kt new file mode 100644 index 0000000..2ac9054 --- /dev/null +++ b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerInitProvider.kt @@ -0,0 +1,59 @@ +package com.tracesift.profiler + +import android.content.ContentProvider +import android.content.ContentValues +import android.content.Context +import android.content.pm.PackageManager +import android.database.Cursor +import android.net.Uri +import android.util.Log + +/** + * Starts profiling without the app having to call anything. + * + * A `ContentProvider` is Android's earliest third-party entry point — it runs + * before `Application.onCreate` and needs no app code, no `index.js` import + * and no React context. That matters for two reasons: the integration stays a + * dependency and nothing else, and the sampler can be armed early enough to + * see startup. + * + * It is **off unless a build asks for it**. A release binary that opens a + * control socket for the asking is a remote-profiling backdoor, so enabling + * it is a build-time decision: this package's manifest declares the meta-data + * below from a placeholder that resolves to false unless the build passes + * `-PtracesiftProfiler=true`. Reading it costs one bundle lookup, and without + * it no socket is ever opened. + */ +class ProfilerInitProvider : ContentProvider() { + override fun onCreate(): Boolean { + val context = context ?: return false + val meta = try { + context.packageManager + .getApplicationInfo(context.packageName, PackageManager.GET_META_DATA) + .metaData + } catch (error: PackageManager.NameNotFoundException) { + null + } + + if (meta == null || !meta.getBoolean(ENABLED_KEY, false)) return false + + val port = meta.getInt(PORT_KEY, DEFAULT_PORT) + Log.i(ProfilerLink.TAG, "profiling enabled; dialling the tracesift CLI on port $port") + ProfilerLink.start(context.applicationContext, port) + return false + } + + // A provider is the hook, not a data source. Nothing here is reachable: + // the manifest declares it android:exported="false". + override fun query(uri: Uri, p: Array?, s: String?, a: Array?, o: String?): Cursor? = null + override fun getType(uri: Uri): String? = null + override fun insert(uri: Uri, values: ContentValues?): Uri? = null + override fun delete(uri: Uri, s: String?, a: Array?): Int = 0 + override fun update(uri: Uri, v: ContentValues?, s: String?, a: Array?): Int = 0 + + companion object { + const val ENABLED_KEY = "com.tracesift.profiler.enabled" + const val PORT_KEY = "com.tracesift.profiler.port" + const val DEFAULT_PORT = 8089 + } +} diff --git a/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerLink.kt b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerLink.kt new file mode 100644 index 0000000..075b5d9 --- /dev/null +++ b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/ProfilerLink.kt @@ -0,0 +1,180 @@ +package com.tracesift.profiler + +import android.content.Context +import android.os.Build +import android.util.Base64 +import android.util.Log +import com.facebook.hermes.instrumentation.HermesSamplingProfiler +import java.io.BufferedReader +import java.io.File +import java.io.InputStreamReader +import java.io.OutputStreamWriter +import java.net.InetSocketAddress +import java.net.Socket +import org.json.JSONObject + +/** + * The link to the tracesift CLI. + * + * The app dials out rather than listening, which is both how React Native's + * own inspector behaves and the only direction that works without asking for + * a network permission or opening a port on the device. On an emulator or a + * USB device `adb reverse tcp:8089 tcp:8089` points 127.0.0.1 back at the + * developer's machine. + * + * The wire is newline-delimited JSON. There is no websocket handshake because + * both ends are ours and the framing is one line per message. + */ +internal object ProfilerLink { + const val TAG = "TracesiftProfiler" + + private const val RETRY_DELAY_MS = 2_000L + // Base64 of a long profile runs to megabytes. The CLI rejects any single + // line past 8 MB, so the payload is split well under that. + private const val CHUNK_CHARS = 256 * 1024 + + @Volatile private var started = false + + /** + * Whether the sampler is running, and the reason nothing else may name + * `HermesSamplingProfiler` speculatively. + * + * That class loads Hermes through SoLoader in a static initialiser. We run + * from a ContentProvider, which Android creates *before* + * `Application.onCreate`, where React Native initialises SoLoader — so + * touching the class early throws `ExceptionInInitializerError`, and + * Android then refuses to retry the initialiser for the life of the + * process ("Rejecting re-init on previously-failed class"). One speculative + * call at startup therefore makes profiling impossible until the app is + * restarted. So the class is named only in response to a `start` or `stop` + * from the CLI, both of which are a person acting on a running app, long + * after SoLoader is up. + */ + @Volatile private var sampling = false + + /** Begin dialling, retrying until the CLI is there. Safe to call twice. */ + @Synchronized + fun start(context: Context, port: Int) { + if (started) return + started = true + val appId = context.packageName + val thread = Thread({ loop(context, appId, port) }, "tracesift-profiler") + thread.isDaemon = true + thread.start() + } + + private fun loop(context: Context, appId: String, port: Int) { + while (true) { + try { + Socket().use { socket -> + socket.tcpNoDelay = true + socket.connect(InetSocketAddress("127.0.0.1", port), 1_000) + Log.i(TAG, "connected to the tracesift CLI on 127.0.0.1:$port") + serve(context, socket, appId) + } + } catch (error: Throwable) { + // Nothing is listening yet, or the recording ended and the CLI hung + // up. Either way the next attempt is the whole recovery. + Log.d(TAG, "not connected (${error.javaClass.simpleName}); retrying") + } + // Make sure a recording cut short by a dropped connection cannot leave + // the sampler running. Only when one was actually started: see `sampling` + // for why this must not touch the class otherwise. + if (sampling) stopSampling() + Thread.sleep(RETRY_DELAY_MS) + } + } + + private fun serve(context: Context, socket: Socket, appId: String) { + val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8)) + val writer = OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8) + + fun send(message: JSONObject) { + writer.write(message.toString()) + writer.write("\n") + writer.flush() + } + + send( + JSONObject() + .put("type", "hello") + .put("app", appId) + .put("platform", "android") + .put("bundle", "index.android.bundle") + .put("device", "${Build.MANUFACTURER} ${Build.MODEL}"), + ) + + while (true) { + val line = reader.readLine() ?: return + if (line.isBlank()) continue + val message = runCatching { JSONObject(line) }.getOrNull() ?: continue + val id = message.optInt("id", 0) + when (message.optString("type")) { + // `hz` is advisory and Android cannot honour it: the Java binding + // exposes a bare `enable()`, so Hermes samples at its own ~100 Hz. + // The C++ API the iOS side will use does take a frequency. + "start" -> runCatching { startSampling() } + .onFailure { send(errorFor(id, it)) } + "stop" -> runCatching { dump(context) } + .onSuccess { profile -> sendProfile(::send, id, profile) } + .onFailure { send(errorFor(id, it)) } + } + } + } + + /** + * Hermes writes the profile to a file, so there is a round trip through the + * cache directory. Dumping also clears the sampler's buffer, which is why + * `disable` comes after and why a profile can only be collected once. + */ + private fun dump(context: Context): String { + if (!sampling) throw IllegalStateException("no profile was started") + val file = File.createTempFile("tracesift-profile", ".cpuprofile", context.cacheDir) + try { + HermesSamplingProfiler.dumpSampledTraceToFile(file.path) + sampling = false + HermesSamplingProfiler.disable() + return file.readText() + } finally { + file.delete() + } + } + + private fun startSampling() { + HermesSamplingProfiler.enable() + sampling = true + } + + private fun stopSampling() { + sampling = false + runCatching { HermesSamplingProfiler.disable() } + .onFailure { Log.w(TAG, "could not stop the sampler", it) } + } + + private fun sendProfile(send: (JSONObject) -> Unit, id: Int, profile: String) { + val encoded = Base64.encodeToString(profile.toByteArray(Charsets.UTF_8), Base64.NO_WRAP) + var sequence = 0 + var offset = 0 + do { + val end = minOf(offset + CHUNK_CHARS, encoded.length) + send( + JSONObject() + .put("type", "profile") + .put("id", id) + .put("seq", sequence) + .put("data", encoded.substring(offset, end)) + .put("last", end >= encoded.length), + ) + sequence += 1 + offset = end + } while (offset < encoded.length) + } + + private fun errorFor(id: Int, error: Throwable): JSONObject { + Log.w(TAG, "profiling failed", error) + return JSONObject() + .put("type", "error") + .put("id", id) + .put("message", error.message ?: error.javaClass.name) + } +} diff --git a/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerModule.kt b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerModule.kt new file mode 100644 index 0000000..b259806 --- /dev/null +++ b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerModule.kt @@ -0,0 +1,48 @@ +package com.tracesift.profiler + +import com.facebook.hermes.instrumentation.HermesSamplingProfiler +import com.facebook.react.bridge.Promise +import com.facebook.react.bridge.ReactApplicationContext +import com.facebook.react.bridge.ReactContextBaseJavaModule +import com.facebook.react.bridge.ReactMethod +import java.io.File + +/** + * The same profiler, driven from JS instead of from the CLI. + * + * The socket path needs none of this — it is here for the case the CLI cannot + * serve: profiling a window the developer can only reach from inside the app, + * or an automated run that starts and stops around a known interaction. + */ +class TracesiftProfilerModule( + private val reactContext: ReactApplicationContext, +) : ReactContextBaseJavaModule(reactContext) { + override fun getName() = NAME + + @ReactMethod(isBlockingSynchronousMethod = true) + fun startProfiling(): Boolean { + HermesSamplingProfiler.enable() + return true + } + + /** + * Resolves with the path of the written profile. Dumping clears Hermes' + * buffer, so each profile can be collected exactly once; the caller owns + * the file and should delete it when done. + */ + @ReactMethod + fun stopProfiling(promise: Promise) { + try { + val file = File.createTempFile("tracesift-profile", ".cpuprofile", reactContext.cacheDir) + HermesSamplingProfiler.dumpSampledTraceToFile(file.path) + HermesSamplingProfiler.disable() + promise.resolve(file.path) + } catch (error: Throwable) { + promise.reject("tracesift_profiler", error.message, error) + } + } + + companion object { + const val NAME = "TracesiftProfiler" + } +} diff --git a/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerPackage.kt b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerPackage.kt new file mode 100644 index 0000000..6df3a9c --- /dev/null +++ b/packages/rn-profiler/android/src/main/java/com/tracesift/profiler/TracesiftProfilerPackage.kt @@ -0,0 +1,14 @@ +package com.tracesift.profiler + +import com.facebook.react.ReactPackage +import com.facebook.react.bridge.NativeModule +import com.facebook.react.bridge.ReactApplicationContext +import com.facebook.react.uimanager.ViewManager + +class TracesiftProfilerPackage : ReactPackage { + override fun createNativeModules(reactContext: ReactApplicationContext): List = + listOf(TracesiftProfilerModule(reactContext)) + + override fun createViewManagers(reactContext: ReactApplicationContext): List> = + emptyList() +} diff --git a/packages/rn-profiler/package.json b/packages/rn-profiler/package.json new file mode 100644 index 0000000..6f61083 --- /dev/null +++ b/packages/rn-profiler/package.json @@ -0,0 +1,27 @@ +{ + "name": "@callstack/tracesift-rn-profiler", + "version": "0.1.0", + "description": "Record a Hermes CPU profile from a React Native release build, with tracesift", + "license": "MIT", + "main": "src/index.ts", + "types": "src/index.ts", + "files": [ + "src", + "android", + "README.md", + "LICENSE" + ], + "keywords": [ + "react-native", + "android", + "hermes", + "profiling", + "performance" + ], + "peerDependencies": { + "react-native": ">=0.76" + }, + "scripts": { + "test": "echo \"no JS tests; the conversion is tested in packages/cli\"" + } +} diff --git a/packages/rn-profiler/src/index.ts b/packages/rn-profiler/src/index.ts new file mode 100644 index 0000000..7b6d340 --- /dev/null +++ b/packages/rn-profiler/src/index.ts @@ -0,0 +1,39 @@ +import { NativeModules } from 'react-native'; + +/** + * The optional JS API. + * + * The package does not need it: with profiling enabled the native side dials + * the tracesift CLI on its own and `tracesift record start --platform rn` + * drives the whole recording. Reach for these only to profile something the + * CLI cannot bracket from outside — a path you can only trigger in-app, or an + * automated run that starts and stops around a known interaction. + */ +const native = NativeModules.TracesiftProfiler as + | { startProfiling(): boolean; stopProfiling(): Promise } + | undefined; + +function required() { + if (!native) { + throw new Error( + '@callstack/tracesift-rn-profiler is not linked. Rebuild the app after installing it.', + ); + } + return native; +} + +/** Arm Hermes' sampling profiler. */ +export function startProfiling(): boolean { + return required().startProfiling(); +} + +/** + * Stop sampling and write the profile out. + * + * Resolves with the path of a Hermes sampling profile on the device. Hermes + * clears its buffer as it dumps, so each profile can be collected once. Pass + * the file to `tracesift` to convert and analyse it. + */ +export function stopProfiling(): Promise { + return required().stopProfiling(); +} diff --git a/scripts/test-codex-local.sh b/scripts/test-codex-local.sh index 3ba766f..e20c74a 100755 --- a/scripts/test-codex-local.sh +++ b/scripts/test-codex-local.sh @@ -132,7 +132,9 @@ printf '%s' "$CLI_WRAPPER" > "$CLI_POINTER_FILE" # Say up front whether a React Native app is reachable, because that is the # route under test and the answer is one command away. Metro and the app are -# the developer's to start, so this only reports what it found. +# the developer's to start, so this only reports what it found. Both routes +# are asked about, since `record targets` now reports a release build dialling +# in as well as a debug build on Metro. METRO_URL="${METRO_URL:-http://127.0.0.1:8081}" RN_STATUS="$( TRACE_SIFT_HOME="$HOME_DIR" "$CLI_WRAPPER" record targets --platform rn --metro "$METRO_URL" --json 2>/dev/null | @@ -143,11 +145,11 @@ RN_STATUS="$( process.stdin.on("end", () => { let payload; try { payload = JSON.parse(input); } catch { payload = null; } - if (!payload) { process.stdout.write("Metro did not answer. Start it with `npx expo start` or `npm start`."); return; } - if (payload.error) { process.stdout.write(payload.error); return; } + if (!payload) { process.stdout.write("nothing answered. Start Metro with `npx expo start`, or install a build made by `tracesift profile build`."); return; } + if (payload.error) { process.stdout.write(payload.error.replace(/\n\s*/g, " ")); return; } const targets = payload.targets ?? []; - if (!targets.length) { process.stdout.write(`no app connected to ${payload.metro}. Open the app in a simulator or emulator.`); return; } - process.stdout.write(targets.map(target => `${target.title}${target.recommended ? " (default)" : ""}`).join(", ")); + if (!targets.length) { process.stdout.write(`no app connected to ${payload.metro} and no release build dialling in.`); return; } + process.stdout.write(targets.map(target => `${target.title}${target.transport === "release" ? " [release]" : ""}${target.recommended ? " (default)" : ""}`).join(", ")); }); ' || true )" @@ -159,7 +161,7 @@ TraceSift is serving this checkout. home: $HOME_DIR cli: $CLI_WRAPPER metro: $METRO_URL - ${RN_STATUS:-could not be checked} + apps: ${RN_STATUS:-could not be checked} Leave this running. In another terminal, install the plugin and relaunch Codex: cd && tooling/test-codex-local.sh @@ -167,6 +169,9 @@ Leave this running. In another terminal, install the plugin and relaunch Codex: Then in Codex: Mobile Dev -> TraceSift -> JavaScript CPU -> Record a running app. React Native one press: the app is already running, so Start profile records it. Ask the agent instead and it drives the same thing itself. + A debug build is found over Metro and a release build through + the profiler package, so test both: \`tracesift profile build\` + from an app root makes the second kind. Web app two presses: Launch web app, reach the state worth profiling, then Start profile.