mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
* refactor(errors): require a reason for every analysis cancellation Add cancelledBy, the one constructor for AnalysisCancelledError. Its reason argument is required: an aborted signal, an earlier cancellation, a reason carried from an inner failure, or an OwnerCancellation when REA closed the work's owner itself. Closed adb, apktool, firmware, sqlite, gdb, web-bundle analyzer and binary-session record owners now report OwnerCancellation.ownerClosed instead of an absent reason. Firmware's predecessor wait returns its cancellation as a Result, removing an unreachable reason-less fallback. An architecture guard rejects new direct constructions, with a counted per-file baseline that can only shrink. * refactor(errors): share one aborted-signal predicate with cancelledBy * refactor(process): return a departing caller's reason from a shared startup wait * refactor(browser): build browser cancellations with a required reason Migrate every AnalysisCancelledError construction under src/browser, src/javascript, src/electron, src/inspector and src/captures to cancelledBy and lower the guard baseline from 671 to 572. Service-worker setup aborts with OwnerCancellation.ownerClosed on close. * refactor(providers): build decompiler-provider cancellations with a required reason (#10587) Migrate every AnalysisCancelledError construction under src/ghidra, src/ida, src/cutter, src/jeb and src/kuna to cancelledBy and lower the guard baseline from 671 to 572. Closed Kuna target commands report OwnerCancellation.ownerClosed instead of an absent reason, and Kuna and JEB close abort their lifetimes with that typed reason. * fix(errors): read the reason of any signal-shaped cancellation source * test(ci): cover the counted-baseline comparison behind the architecture guard * refactor(electron): drop an unused error import from the fuse failure mapper
198 lines
8.7 KiB
TypeScript
198 lines
8.7 KiB
TypeScript
import { AnalysisError } from "../../domain/analysisErrorBase.js";
|
|
import { BrowserObservationError } from "../../domain/browserObservationError.js";
|
|
import { cancelledBy } from "../../domain/analysisErrorCore.js";
|
|
import type {
|
|
ObserveWebExecutionInput,
|
|
WebExecution,
|
|
WebExecutionObservation,
|
|
} from "../../domain/webExecution.js";
|
|
import { CdpExecutionCollection } from "./CdpExecutionCollection.js";
|
|
import type { CdpCommandResult } from "../protocol/CdpCommands.js";
|
|
import { normalizePreciseCoverage } from "./CdpPreciseCoverage.js";
|
|
import type { CdpRuntimeSources } from "./CdpRuntimeSources.js";
|
|
|
|
/** Capture one explicit resetting coverage sample and its request-source relationships. */
|
|
export const captureWebExecution = async (
|
|
input: ObserveWebExecutionInput,
|
|
sources: CdpRuntimeSources,
|
|
): Promise<WebExecutionObservation> => {
|
|
const session = sources.session;
|
|
const collection = new CdpExecutionCollection(sources);
|
|
const { window, requests } = collection;
|
|
try {
|
|
for (const domain of [
|
|
"Page",
|
|
"Runtime",
|
|
"Debugger",
|
|
"Network",
|
|
"Profiler",
|
|
] as const)
|
|
await session.enable(domain);
|
|
await session.assertDocument();
|
|
sources.check();
|
|
session.preciseCoverageMayBeActive = true;
|
|
const started = await session.command("Profiler.startPreciseCoverage", {
|
|
callCount: true,
|
|
detailed: true,
|
|
allowTriggeredUpdates: false,
|
|
});
|
|
sources.check();
|
|
window.check();
|
|
if (window.reason !== undefined)
|
|
throw new BrowserObservationError(
|
|
session.operation,
|
|
window.reason === "session_detached"
|
|
? "target_session_detached"
|
|
: "target_changed",
|
|
{
|
|
detail: executionWindowEndDetail(
|
|
session.target.target_id,
|
|
window.reason,
|
|
),
|
|
},
|
|
);
|
|
const waiting = window.start(input.observation_ms);
|
|
// Cancellation may arrive while asynchronous progress is being delivered.
|
|
void waiting.catch(() => undefined);
|
|
await session.options.progress?.report({
|
|
phase: "browser_execution",
|
|
completed: 1,
|
|
total: 2,
|
|
message:
|
|
"Browser execution observation armed; perform the requested action now",
|
|
});
|
|
const reason = await waiting;
|
|
session.beginCompletion();
|
|
if (session.options.signal?.aborted)
|
|
throw cancelledBy(session.operation, session.options.signal);
|
|
sources.check();
|
|
requests.check();
|
|
let sampled: CdpCommandResult<"Profiler.takePreciseCoverage"> | undefined;
|
|
if (reason === "window_elapsed") {
|
|
await session.assertDocument();
|
|
sampled = await session.command("Profiler.takePreciseCoverage");
|
|
}
|
|
collection.freezeMetadata();
|
|
await stopPreciseCoverage(session, reason);
|
|
session.preciseCoverageMayBeActive = false;
|
|
const requestItems = requests.result();
|
|
const mainScripts = [...sources.scripts.keys()].filter((id) =>
|
|
sources.belongsToDocument(id),
|
|
);
|
|
const reportedIds = new Set(
|
|
sampled?.result.map((script) => script.scriptId) ?? [],
|
|
);
|
|
const ids = [
|
|
...mainScripts,
|
|
...requestItems
|
|
.flatMap((request) => request.callsites.map((site) => site.script_id))
|
|
.filter((id) => id.length > 0),
|
|
];
|
|
const retained = await sources.read(ids);
|
|
if (reason === "window_elapsed") await session.assertDocument();
|
|
sources.check();
|
|
const verifiedRequests = requests.result();
|
|
const verifiedMainScripts = mainScripts.filter((id) =>
|
|
sources.belongsToDocument(id),
|
|
);
|
|
const sample =
|
|
sampled === undefined
|
|
? undefined
|
|
: normalizePreciseCoverage(sampled, sources, retained);
|
|
await session.options.progress?.report({
|
|
phase: "browser_execution",
|
|
completed: 2,
|
|
total: 2,
|
|
message: "Browser execution observation ended",
|
|
terminal: true,
|
|
});
|
|
return {
|
|
browser: session.discovery.version,
|
|
target: session.target,
|
|
window: {
|
|
armed_at: window.armedAt ?? new Date().toISOString(),
|
|
ended_at: window.endedAt ?? new Date().toISOString(),
|
|
requested_ms: input.observation_ms,
|
|
end_reason: reason,
|
|
producer_started_seconds: started.timestamp,
|
|
producer_sampled_seconds: sample?.timestamp ?? null,
|
|
},
|
|
coverage: sample?.coverage ?? {
|
|
state: "unavailable",
|
|
reason: `The observation ended with ${reason}; no complete final precise-coverage sample was retained.`,
|
|
offset_units: "utf16-code-units",
|
|
end_offset: "exclusive",
|
|
scripts: [],
|
|
excluded_scripts: 0,
|
|
},
|
|
requests: verifiedRequests,
|
|
excluded_requests: requests.excluded,
|
|
script_inventory: {
|
|
main_document_scripts: verifiedMainScripts.length,
|
|
not_reported_script_ids: verifiedMainScripts.filter(
|
|
(id) => !reportedIds.has(id),
|
|
),
|
|
coverage_absence: "unknown",
|
|
},
|
|
sources: retained,
|
|
instrumentation: {
|
|
resets_execution_counters: true,
|
|
disables_optimized_execution: true,
|
|
takes_one_resetting_sample: sample !== undefined,
|
|
executes_selected_code: false,
|
|
cleanup: "unconfirmed",
|
|
page_ownership: "external",
|
|
},
|
|
limitations: [
|
|
...(session.discovery.limitations ?? []),
|
|
"Website source ownership requires the selected main frame and a proven default execution world. Isolated, worker and unknown worlds are excluded from coverage/source joins; referenced producer context metadata is retained.",
|
|
"Precise coverage resets counters, retains execution records and prevents optimized execution until stopped. Timing and JIT behavior are affected.",
|
|
"Only the selected main document's proven frame/context scripts are attributed. Child frames, workers, service workers, WebAssembly and scripts without ownership metadata remain outside this operation.",
|
|
"V8 reports nested function/block ranges and counts, not a chronological trace. Counts must not be summed across overlapping ranges; zero counts concern this instrumented window only.",
|
|
"Previously parsed scripts may be absent from a precise sample. Their source inventory is retained, but missing coverage never means zero execution or an unexecuted function.",
|
|
"A detailed-coverage request does not guarantee block granularity for already compiled functions. When is_block_coverage is false, branch execution is unknown; REA preserves the function-only producer ranges.",
|
|
"The local armed/end clock and backend coverage timestamps are distinct clocks. Counters start when the backend accepts instrumentation, before the armed receipt, and end at the resetting sample after the requested window. Counts may include execution during those command intervals; requests are restricted to the locally armed window.",
|
|
"Source metadata is collected through the final resetting sample, then frozen for source joins. Known identities remain checked during asynchronous source completion; newly parsed scripts after that cutoff are outside this evidence.",
|
|
"Request callsites are producer-reported initiators associated by session script ID; they do not establish UI causality. Unresolved asynchronous parent IDs are retained without fetching their stacks.",
|
|
"Producer hashes and UTF-8 digests of retained text are distinct identities. Inline script locations use reported resource offsets; anonymous/eval/sourceURL names are declarations.",
|
|
"Metadata has an 8 MiB script budget and 8 MiB request budget; complete retained sources have a 32 MiB budget. Resource failures return no partial success. The externally owned browser's CPU and memory are not controlled by REA.",
|
|
],
|
|
};
|
|
} finally {
|
|
collection.close();
|
|
}
|
|
};
|
|
|
|
const stopPreciseCoverage = async (
|
|
session: CdpRuntimeSources["session"],
|
|
reason: WebExecution["window"]["end_reason"],
|
|
): Promise<void> => {
|
|
try {
|
|
await session.command("Profiler.stopPreciseCoverage");
|
|
} catch (cause: unknown) {
|
|
if (
|
|
(reason !== "target_terminated" && reason !== "session_detached") ||
|
|
!(cause instanceof AnalysisError)
|
|
)
|
|
throw cause;
|
|
cause.retainDiagnostics({
|
|
observed_window: {
|
|
target_id: session.target.target_id,
|
|
end_reason: reason,
|
|
},
|
|
});
|
|
throw cause;
|
|
}
|
|
};
|
|
|
|
const executionWindowEndDetail = (
|
|
targetId: string,
|
|
reason: WebExecution["window"]["end_reason"],
|
|
): string => {
|
|
if (reason === "session_detached")
|
|
return `The debugging session for selected target ${targetId} detached before execution observation could be armed; the target may still exist.`;
|
|
if (reason === "target_terminated")
|
|
return `Selected target ${targetId} crashed before execution observation could be armed.`;
|
|
return `Selected target ${targetId} changed documents before execution observation could be armed.`;
|
|
};
|