mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
* refactor(kernel): give error-to-message text one owner in a new src/kernel layer * fix(kernel): keep the regex worker's own error text inside its isolated source * refactor(kernel): exclude copies that run in another realm from the error-message guard by name The regex worker's source string and the page.evaluate fetch in PlaywrightScenarioRequest cannot import errorMessage. The guard now names them, so the counted baseline does not invite a later slice to rewrite them. * refactor(kernel): migrate the long tail of inline error-message copies to errorMessage (#11552) Every provider and adapter folder with six or fewer copies now calls errorMessage from src/kernel. Local helpers whose whole body was the copy (failureMessage, gdbErrorMessage, message, describe, reasonOf, recoveryFailureMessage and four local errorMessage definitions) are removed and their call sites call the owner. Refs #11548 * refactor(kernel): give byte-to-hex formatting one owner in src/kernel (#11560) byteToHex returns the two lowercase hexadecimal digits of one byte. All eight inline copies (native, contracts, domain firmware and desktop, pcap) call it, keeping their own 0x, % or \x notation, and a counted guard with an empty baseline keeps new copies out. Refs #11548 * refactor(kernel): give one-shot SHA-256 hex digests one owner in src/kernel (#11562) sha256Hex digests one in-memory value. A counted guard records the one-shot createHash("sha256").update(x).digest("hex") chains (115 in 101 files) and the first slice migrates domain, contracts and process (35 copies), removing local wrappers (sha256, sha256Text, hash) and the exported sha256Text. Incremental and streamed hashing is not counted. Refs #11548 * refactor(kernel): migrate the application layer's inline error-message copies to errorMessage (#11563) All 69 copies in src/application call errorMessage from src/kernel. Local helpers whose whole body was the copy (errorDetail, causeReason and five local errorMessage definitions) are removed and their call sites call the owner. Refs #11548 * refactor(kernel): migrate the native provider's inline error-message copies to errorMessage (#11567) All 49 copies in src/native call errorMessage from src/kernel. The local errorReason helpers in LldbCallTracer and LldbRetainedObservations, whose whole body was the copy, are removed and their call sites call the owner. Refs #11548 * refactor(kernel): migrate the remaining inline error-message copies to errorMessage (#11569)
475 lines
15 KiB
TypeScript
475 lines
15 KiB
TypeScript
import { selectCdpDiscoveryTarget } from "./CdpDiscoveryTargets.js";
|
|
import {
|
|
DEFAULT_ASAR_HEADER_ADMISSION,
|
|
type AsarHeaderAdmission,
|
|
} from "../config/asarHeaderAdmission.js";
|
|
import type {
|
|
ExecutionOptions,
|
|
ProviderIdentity,
|
|
} from "../ports/AnalysisProvider.js";
|
|
import type { ElectronObservationPort } from "../ports/javascript/ElectronObservationPort.js";
|
|
import {
|
|
electronPageInspectionSchema,
|
|
electronTargetListSchema,
|
|
type ElectronPageInspection,
|
|
type ElectronTargetList,
|
|
type InspectElectronPageInput,
|
|
type ListElectronTargetsInput,
|
|
} from "../domain/javascript/electronObservation.js";
|
|
import { selectedCdpCommandTimeoutMs } from "../domain/browserDeadline.js";
|
|
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { cancelledBy } from "../domain/analysisErrorCore.js";
|
|
import { BrowserObservationError } from "../domain/browserObservationError.js";
|
|
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import {
|
|
discoverCdpEndpoint,
|
|
hasCdpTargetWebSocket,
|
|
type CdpEndpointDiscovery,
|
|
type CdpEndpointTarget,
|
|
} from "./CdpEndpoint.js";
|
|
import {
|
|
closeCdpTargetSession,
|
|
openCdpTargetSession,
|
|
type CdpTargetSession,
|
|
} from "./CdpTargetSession.js";
|
|
import { inspectCdpElectronPage } from "./CdpElectronInspection.js";
|
|
import {
|
|
authorizedElectronFile,
|
|
mapElectronFileAuthorizationFailure,
|
|
retryElectronFileCleanup,
|
|
} from "./ElectronFileScope.js";
|
|
|
|
import { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
|
|
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
|
|
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
|
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
|
|
import {
|
|
CdpTargetSessionOwner,
|
|
bindCdpTransportCleanup,
|
|
} from "./CdpTargetSessionOwner.js";
|
|
import { errorMessage } from "../kernel/errorMessage.js";
|
|
/** Passive Electron provider for local file pages exposed by loopback CDP. */
|
|
export class CdpElectronProvider implements ElectronObservationPort {
|
|
readonly #owner = new CdpTargetSessionOwner();
|
|
readonly #asarHeaderAdmission: AsarHeaderAdmission;
|
|
|
|
/** The admission comes from the composition root's environment; default otherwise. */
|
|
constructor(
|
|
asarHeaderAdmission: AsarHeaderAdmission = DEFAULT_ASAR_HEADER_ADMISSION,
|
|
) {
|
|
this.#asarHeaderAdmission = asarHeaderAdmission;
|
|
}
|
|
#activeOperations = 0;
|
|
#closing = false;
|
|
#closePromise: Promise<void> | undefined;
|
|
readonly #idleWaiters = new Set<() => void>();
|
|
|
|
async close(): Promise<void> {
|
|
if (this.#closePromise === undefined) {
|
|
this.#closing = true;
|
|
const attempt = this.#closeAfterOperations();
|
|
let tracked: Promise<void>;
|
|
tracked = attempt.catch((cause: unknown) => {
|
|
if (this.#closePromise === tracked) this.#closePromise = undefined;
|
|
throw cause;
|
|
});
|
|
this.#closePromise = tracked;
|
|
}
|
|
await this.#closePromise;
|
|
}
|
|
|
|
async #closeAfterOperations(): Promise<void> {
|
|
while (this.#activeOperations > 0)
|
|
await new Promise<void>((resolve) => this.#idleWaiters.add(resolve));
|
|
const outcomes = await Promise.allSettled([
|
|
this.#owner.close(),
|
|
retryElectronFileCleanup(),
|
|
]);
|
|
const failures = outcomes.flatMap((outcome) =>
|
|
outcome.status === "rejected" ? [outcome.reason as unknown] : [],
|
|
);
|
|
const mapped = failures.map(
|
|
(failure) =>
|
|
mapElectronFileAuthorizationFailure(
|
|
failure,
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
"inspect_electron_page",
|
|
) ?? failure,
|
|
);
|
|
if (mapped.length === 1) throw mapped[0];
|
|
if (mapped.length > 1) {
|
|
const typed = mapped.filter(
|
|
(failure): failure is AnalysisError => failure instanceof AnalysisError,
|
|
);
|
|
throw new ProviderCleanupError(
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
typed.flatMap((failure) => failure.cleanupResources),
|
|
{ reason: "Electron transport and file cleanup remain incomplete" },
|
|
{
|
|
operation: "inspect_electron_page",
|
|
cause: new AggregateError(mapped),
|
|
},
|
|
).bindCleanupDependencies(typed);
|
|
}
|
|
}
|
|
|
|
identity(): ProviderIdentity {
|
|
return CDP_ELECTRON_PROVIDER_IDENTITY;
|
|
}
|
|
|
|
async listTargets(
|
|
input: ListElectronTargetsInput,
|
|
options: ExecutionOptions = {},
|
|
): Promise<Result<ElectronTargetList, AnalysisError>> {
|
|
return await this.#withAdmission(
|
|
"list_electron_targets",
|
|
async () => await this.#listTargets(input, options),
|
|
);
|
|
}
|
|
|
|
async #listTargets(
|
|
input: ListElectronTargetsInput,
|
|
options: ExecutionOptions,
|
|
): Promise<Result<ElectronTargetList, AnalysisError>> {
|
|
const allowed: ElectronTargetList["targets"] = [];
|
|
let discovery: CdpEndpointDiscovery | undefined;
|
|
let unsupportedUrl = 0;
|
|
let nonPage = 0;
|
|
let unconnectable = 0;
|
|
let examined = 0;
|
|
try {
|
|
discovery = await discoverCdpEndpoint(
|
|
input.cdp_endpoint,
|
|
"list_electron_targets",
|
|
options.signal,
|
|
);
|
|
throwIfElectronOperationCancelled(
|
|
options.signal,
|
|
"list_electron_targets",
|
|
);
|
|
for (const target of discovery.targets) {
|
|
throwIfElectronOperationCancelled(
|
|
options.signal,
|
|
"list_electron_targets",
|
|
);
|
|
if (target.type !== "page") {
|
|
examined += 1;
|
|
nonPage += 1;
|
|
continue;
|
|
}
|
|
const path = await authorizedElectronFile(
|
|
target.url,
|
|
options.signal,
|
|
"list_electron_targets",
|
|
this.#asarHeaderAdmission,
|
|
);
|
|
if (path === undefined) {
|
|
examined += 1;
|
|
unsupportedUrl += 1;
|
|
continue;
|
|
}
|
|
if (!hasCdpTargetWebSocket(discovery, target)) {
|
|
examined += 1;
|
|
unconnectable += 1;
|
|
continue;
|
|
}
|
|
examined += 1;
|
|
allowed.push({
|
|
target_id: target.id,
|
|
type: target.type,
|
|
title: target.title,
|
|
file_path: path,
|
|
attached: target.attached,
|
|
});
|
|
}
|
|
allowed.sort((left, right) =>
|
|
compareUnicodeCodePoints(left.target_id, right.target_id),
|
|
);
|
|
throwIfElectronOperationCancelled(
|
|
options.signal,
|
|
"list_electron_targets",
|
|
);
|
|
return ok(
|
|
electronTargetListSchema.parse({
|
|
browser: discovery.version,
|
|
targets: allowed,
|
|
excluded: {
|
|
unsupported_url: unsupportedUrl,
|
|
non_page: nonPage,
|
|
},
|
|
limitations: [
|
|
...(discovery.limitations ?? []),
|
|
"Every local file page exposed by the selected loopback CDP endpoint is eligible for listing.",
|
|
...(unconnectable === 0
|
|
? []
|
|
: [
|
|
`${String(unconnectable)} otherwise allowed page target(s) lacked a validated direct CDP WebSocket and were excluded.`,
|
|
]),
|
|
...(allowed.some((target) => target.attached === null)
|
|
? [
|
|
"CDP discovery could not establish debugger attachment state for one or more targets.",
|
|
]
|
|
: []),
|
|
],
|
|
}),
|
|
);
|
|
} catch (cause: unknown) {
|
|
const completedPrefix = {
|
|
browser_version: discovery?.version ?? null,
|
|
examined_targets: examined,
|
|
discovered_targets: discovery?.targets.length ?? null,
|
|
allowed_targets: allowed,
|
|
excluded: {
|
|
unsupported_url: unsupportedUrl,
|
|
non_page: nonPage,
|
|
},
|
|
unconnectable_targets: unconnectable,
|
|
coverage:
|
|
"partial: target authorization stopped; remaining targets are unknown",
|
|
};
|
|
const fileFailure = mapElectronFileAuthorizationFailure(
|
|
cause,
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
"list_electron_targets",
|
|
{
|
|
completed_prefix: completedPrefix,
|
|
},
|
|
);
|
|
if (fileFailure !== undefined) return err(fileFailure);
|
|
return err(
|
|
options.signal?.aborted === true
|
|
? cancelledBy("list_electron_targets", options.signal, {
|
|
diagnostics: {
|
|
completed_prefix: completedPrefix,
|
|
},
|
|
})
|
|
: providerError(cause, "list_electron_targets"),
|
|
);
|
|
}
|
|
}
|
|
|
|
async inspectPage(
|
|
input: InspectElectronPageInput,
|
|
options: ExecutionOptions = {},
|
|
): Promise<Result<ElectronPageInspection, AnalysisError>> {
|
|
return await this.#withAdmission(
|
|
"inspect_electron_page",
|
|
async () => await this.#inspectPage(input, options),
|
|
);
|
|
}
|
|
|
|
async #inspectPage(
|
|
input: InspectElectronPageInput,
|
|
options: ExecutionOptions,
|
|
): Promise<Result<ElectronPageInspection, AnalysisError>> {
|
|
let targetSession: CdpTargetSession | undefined;
|
|
let cleanupFailure: AnalysisError | undefined;
|
|
let result: Result<ElectronPageInspection, AnalysisError>;
|
|
try {
|
|
const discovery = await discoverCdpEndpoint(
|
|
input.cdp_endpoint,
|
|
"inspect_electron_page",
|
|
options.signal,
|
|
);
|
|
const target = await authorizeTarget(
|
|
discovery,
|
|
input.target_id,
|
|
this.#asarHeaderAdmission,
|
|
options.signal,
|
|
);
|
|
targetSession = await openCdpTargetSession(
|
|
discovery,
|
|
target,
|
|
"inspect_electron_page",
|
|
options.signal,
|
|
{
|
|
commandTimeoutMs: selectedCdpCommandTimeoutMs(
|
|
input.command_timeout_ms,
|
|
),
|
|
},
|
|
this.#owner,
|
|
);
|
|
result = ok(
|
|
electronPageInspectionSchema.parse(
|
|
await inspectCdpElectronPage({
|
|
connection: targetSession.connection,
|
|
sessionId: targetSession.sessionId,
|
|
discovery,
|
|
target,
|
|
input,
|
|
asarHeaderAdmission: this.#asarHeaderAdmission,
|
|
...(options.signal === undefined ? {} : { signal: options.signal }),
|
|
...(options.progress === undefined
|
|
? {}
|
|
: { progress: options.progress }),
|
|
}),
|
|
),
|
|
);
|
|
} catch (cause: unknown) {
|
|
result = err(providerError(cause, "inspect_electron_page"));
|
|
} finally {
|
|
if (targetSession !== undefined)
|
|
try {
|
|
await closeCdpTargetSession(
|
|
targetSession,
|
|
["Debugger", "Runtime", "Page"],
|
|
options.signal,
|
|
this.#owner,
|
|
);
|
|
} catch (cause: unknown) {
|
|
cleanupFailure =
|
|
cause instanceof AnalysisError
|
|
? cause
|
|
: new ProviderCleanupError(
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
[input.target_id],
|
|
{
|
|
reason: errorMessage(cause),
|
|
},
|
|
{ operation: "inspect_electron_page", cause },
|
|
);
|
|
}
|
|
}
|
|
const finalCancellation =
|
|
result.ok && options.signal?.aborted === true
|
|
? cancelledBy("inspect_electron_page", options.signal, {
|
|
partialObservation: {
|
|
kind: "electron-page-observation",
|
|
inspection: result.value,
|
|
cleanup:
|
|
cleanupFailure === undefined
|
|
? "transport-closed"
|
|
: "incomplete",
|
|
},
|
|
})
|
|
: undefined;
|
|
if (cleanupFailure !== undefined) {
|
|
if (finalCancellation !== undefined)
|
|
return err(
|
|
bindCdpTransportCleanup(
|
|
cleanupFailure,
|
|
analysisErrorWithCleanupFailure(
|
|
finalCancellation,
|
|
cleanupFailure,
|
|
"inspect_electron_page",
|
|
),
|
|
),
|
|
);
|
|
if (!result.ok)
|
|
return err(
|
|
bindCdpTransportCleanup(
|
|
cleanupFailure,
|
|
analysisErrorWithCleanupFailure(
|
|
result.error,
|
|
cleanupFailure,
|
|
"inspect_electron_page",
|
|
),
|
|
),
|
|
);
|
|
return err(
|
|
bindCdpTransportCleanup(
|
|
cleanupFailure,
|
|
new ProviderCleanupError(
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
cleanupFailure.cleanupResources,
|
|
{ cleanup_error: cleanupFailure.message },
|
|
{
|
|
operation: "inspect_electron_page",
|
|
cause: cleanupFailure,
|
|
partialObservation: {
|
|
kind: "electron-page-observation",
|
|
inspection: result.value,
|
|
cleanup: "incomplete",
|
|
},
|
|
},
|
|
),
|
|
),
|
|
);
|
|
}
|
|
if (!result.ok) return result;
|
|
if (finalCancellation !== undefined) return err(finalCancellation);
|
|
return result;
|
|
}
|
|
|
|
async #withAdmission<Value>(
|
|
operation: "list_electron_targets" | "inspect_electron_page",
|
|
work: () => Promise<Result<Value, AnalysisError>>,
|
|
): Promise<Result<Value, AnalysisError>> {
|
|
if (this.#closing)
|
|
return err(
|
|
new ProviderAdapterError(CDP_ELECTRON_PROVIDER_IDENTITY.id, operation, {
|
|
diagnostics: { reason: "provider_closed" },
|
|
userMessage: "Electron provider is closed to new observations.",
|
|
}),
|
|
);
|
|
this.#activeOperations += 1;
|
|
try {
|
|
return await work();
|
|
} catch (cause: unknown) {
|
|
return err(providerError(cause, operation));
|
|
} finally {
|
|
this.#activeOperations -= 1;
|
|
if (this.#activeOperations === 0) {
|
|
for (const resolve of this.#idleWaiters) resolve();
|
|
this.#idleWaiters.clear();
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
const authorizeTarget = async (
|
|
discovery: CdpEndpointDiscovery,
|
|
targetId: string,
|
|
asarHeaderAdmission: AsarHeaderAdmission,
|
|
signal?: AbortSignal,
|
|
): Promise<CdpEndpointTarget> => {
|
|
throwIfElectronOperationCancelled(signal, "inspect_electron_page");
|
|
const target = selectCdpDiscoveryTarget(
|
|
discovery.targets,
|
|
targetId,
|
|
"inspect_electron_page",
|
|
discovery.ambiguousTargetIds,
|
|
);
|
|
if (target === undefined)
|
|
throw new BrowserObservationError("inspect_web_page", "target_not_found");
|
|
if (target.type !== "page")
|
|
throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
|
|
const path = await authorizedElectronFile(
|
|
target.url,
|
|
signal,
|
|
"inspect_electron_page",
|
|
asarHeaderAdmission,
|
|
);
|
|
throwIfElectronOperationCancelled(signal, "inspect_electron_page");
|
|
if (path === undefined)
|
|
throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
|
|
return target;
|
|
};
|
|
|
|
const throwIfElectronOperationCancelled = (
|
|
signal: AbortSignal | undefined,
|
|
operation: "list_electron_targets" | "inspect_electron_page",
|
|
): void => {
|
|
if (signal?.aborted === true) throw cancelledBy(operation, signal);
|
|
};
|
|
|
|
const providerError = (
|
|
cause: unknown,
|
|
operation: "list_electron_targets" | "inspect_electron_page",
|
|
): AnalysisError => {
|
|
const fileFailure = mapElectronFileAuthorizationFailure(
|
|
cause,
|
|
CDP_ELECTRON_PROVIDER_IDENTITY.id,
|
|
operation,
|
|
);
|
|
if (fileFailure !== undefined) return fileFailure;
|
|
return cause instanceof BrowserObservationError
|
|
? cause.forOperation(operation)
|
|
: cause instanceof AnalysisError
|
|
? cause
|
|
: new ProviderAdapterError(CDP_ELECTRON_PROVIDER_IDENTITY.id, operation, {
|
|
cause,
|
|
});
|
|
};
|