refactor(errors): compose multi-part provider cleanup failures through one owner (#12002)

* refactor(errors): compose multi-part provider cleanup failures through one owner

CdpBrowserProvider, CdpElectronProvider, FridaInstrumentationManager and
PlaywrightBrowserScenarioProvider each built the same composite by hand: a
ProviderCleanupError listing the parts' resources, an AggregateError cause,
and bindCleanupDependencies over the parts. providerCleanupErrorFromFailures
in src/domain/analysisErrorCleanup.ts now owns that composition. `causes`
keeps non-AnalysisError failures in the aggregate cause without making them
own completion, as the CDP providers did; `message` keeps the aggregate
messages Frida and Playwright used.

Tests: helper unit tests, new close-composition tests for both CDP providers,
and a Playwright test with two failed cleanup retries. They pass on the base
revision and on this change, and fail when the helper drops the dependency
binding, the extra causes or the message.

Lowers the cleanup-dependency-binding baseline to 43 files / 73 sites.

Refs #11859

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style(test): format the Playwright cleanup test with oxfmt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(errors): assert cleanup composition facts instead of reason prose

Follows docs/development/testing.md: the close-composition tests now check
provider, operation, resources, aggregate causes and completion, not the
explanatory reason or aggregate message. A harmless wording change passes;
a lost binding, lost cause or wrong operation still fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Anant Mandanka <anant.mandanka@renaissancejewel.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-19 12:51:28 +00:00
1 parent f175382ed7
commit b6363efc97
9 files changed
+295 -39

No files matched your search

@@ -7,9 +7,7 @@
"src/application/desktop/DesktopApplicationExport.ts": 2,
"src/application/frida/FridaInstrumentationService.ts": 2,
"src/application/releaseExposure/ReleaseExposureService.ts": 1,
"src/browser/CdpBrowserProvider.ts": 1,
"src/browser/CdpElectronProvider.ts": 1,
"src/browser/PlaywrightBrowserScenarioProvider.ts": 2,
"src/browser/PlaywrightBrowserScenarioProvider.ts": 1,
"src/browser/WebSourceMapFetcher.ts": 2,
"src/cli/desktopCaptureCommands.ts": 1,
"src/cutter/CutterBridgeClient.ts": 1,
@@ -18,7 +16,6 @@
"src/evm/EvmoleInterfaceProvider.ts": 3,
"src/firmware/FirmwareProvider.ts": 1,
"src/flutter/FlutterBuildProvider.ts": 1,
"src/frida/FridaInstrumentationManager.ts": 1,
"src/gdb/GdbSessionManager.ts": 2,
"src/hopper/BridgeLauncher.ts": 3,
"src/hopper/HopperAnalysisProfile.ts": 1,
+9 -9
View File
@@ -57,7 +57,10 @@ import {
AnalysisError,
type AnalysisPartialObservation,
} from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import {
analysisErrorWithCleanupFailure,
providerCleanupErrorFromFailures,
} from "../domain/analysisErrorCleanup.js";
import {
AnalysisInputError,
cancelledBy,
@@ -158,15 +161,12 @@ export class CdpBrowserProvider implements BrowserObservationPort {
const typed = failures.filter(
(failure): failure is AnalysisError => failure instanceof AnalysisError,
);
throw new ProviderCleanupError(
throw providerCleanupErrorFromFailures(
CDP_BROWSER_PROVIDER_IDENTITY.id,
typed.flatMap((failure) => failure.cleanupResources),
{ reason: "Browser transport and analyzer cleanup remain incomplete" },
{
operation: "analyze_web_bundle",
cause: new AggregateError(failures),
},
).bindCleanupDependencies(typed);
typed,
"Browser transport and analyzer cleanup remain incomplete",
{ operation: "analyze_web_bundle", causes: failures },
);
}
}
+9 -9
View File
@@ -42,7 +42,10 @@ import {
import { CDP_ELECTRON_PROVIDER_IDENTITY } from "./providerIdentities.js";
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import {
analysisErrorWithCleanupFailure,
providerCleanupErrorFromFailures,
} from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
CdpTargetSessionOwner,
@@ -102,15 +105,12 @@ export class CdpElectronProvider implements ElectronObservationPort {
const typed = mapped.filter(
(failure): failure is AnalysisError => failure instanceof AnalysisError,
);
throw new ProviderCleanupError(
throw providerCleanupErrorFromFailures(
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);
typed,
"Electron transport and file cleanup remain incomplete",
{ operation: "inspect_electron_page", causes: mapped },
);
}
}
@@ -13,6 +13,7 @@ import { describe, expect, it, vi } from "vitest";
import type { BrowserScenarioSessionPort } from "./BrowserScenarioSessionPort.js";
import { PlaywrightBrowserScenarioProvider } from "./PlaywrightBrowserScenarioProvider.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { PlaywrightScenarioSession } from "./PlaywrightScenarioSession.js";
import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
@@ -1282,6 +1283,56 @@ it("retries every retained opening cleanup and preserves the original failure th
}
});
it("composes several failed cleanup retries and completes only after each releases", async () => {
const denied = { first: true, second: true };
const provider = new PlaywrightBrowserScenarioProvider(
async (_scenario, options) => {
options.retainCleanup?.(
new AnalysisCleanupLease(async () => {
if (denied.first) throw new Error("first cleanup denied");
}, ["first cleanup"]),
);
options.retainCleanup?.(
new AnalysisCleanupLease(async () => {
if (denied.second) throw new Error("second cleanup denied");
}, ["second cleanup"]),
);
throw new AnalysisOutputError(
"capture_browser_scenario",
"authored open failure",
);
},
);
try {
const result = await provider.captureScenario(scenario());
if (result.ok) throw new Error("Expected opening failure");
const composite: unknown = await provider
.close()
.catch((cause: unknown) => cause);
if (!(composite instanceof ProviderCleanupError))
throw new Error("Expected a provider cleanup failure");
expect(composite).toMatchObject({
operation: "capture_browser_scenario",
cleanupIncomplete: true,
cleanupResources: ["first cleanup", "second cleanup"],
});
expect(composite.cause).toBeInstanceOf(AggregateError);
expect((composite.cause as AggregateError).errors).toHaveLength(2);
denied.first = false;
await provider.close().catch(() => undefined);
expect(composite.cleanupIncomplete).toBe(true);
denied.second = false;
await provider.close();
expect(composite.cleanupIncomplete).toBe(false);
} finally {
denied.first = false;
denied.second = false;
await provider.close();
}
});
it("keeps a cancelled opening incomplete until its retained late cleanup finishes", async () => {
let finish: () => void = () => {};
const late = new Promise<void>((resolve) => {
@@ -2,7 +2,10 @@ import {
withPlaywrightExecutionBoundary,
PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS,
} from "./PlaywrightExecutionBoundary.js";
import { analysisErrorWithCleanupDependencies } from "../domain/analysisErrorCleanup.js";
import {
analysisErrorWithCleanupDependencies,
providerCleanupErrorFromFailures,
} from "../domain/analysisErrorCleanup.js";
import {
AnalysisCleanupLease,
AnalysisCleanupLeaseGroup,
@@ -551,14 +554,11 @@ export class PlaywrightBrowserScenarioProvider implements BrowserScenarioCapture
}
if (failures.length === 0) return undefined;
if (failures.length === 1) return failures[0];
return new ProviderCleanupError(
return providerCleanupErrorFromFailures(
PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id,
failures.flatMap((failure) => failure.cleanupResources),
{ reason: "One or more browser scenario resources remain owned." },
{
operation: OPERATION,
cause: new AggregateError(failures, "Browser scenario cleanup failed"),
},
).bindCleanupDependencies(failures);
failures,
"One or more browser scenario resources remain owned.",
{ operation: OPERATION, message: "Browser scenario cleanup failed" },
);
}
}
+68
View File
@@ -10,6 +10,7 @@ import {
} from "./analysisErrorCore.js";
import {
analysisErrorWithCleanupFailure,
providerCleanupErrorFromFailures,
withInheritedCleanupOwnership,
} from "./analysisErrorCleanup.js";
import {
@@ -530,6 +531,73 @@ it.each(["primary", "cleanup", "default", "cleanup-continuing"] as const)(
},
);
it("composes cleanup failures that complete only after every part releases", () => {
const first = new ProviderCleanupError(
"fixture",
["first-handle"],
{ reason: "first" },
{ operation: "fixture_close" },
);
const second = new ProviderCleanupError(
"fixture",
["second-handle"],
{ reason: "second" },
{ operation: "fixture_close" },
);
const untyped = new Error("untyped close failure");
const composite = providerCleanupErrorFromFailures(
"fixture-provider",
[first, second],
"Fixture cleanup remains incomplete",
{
operation: "fixture_close",
causes: [first, untyped, second],
message: "Fixture cleanup failed",
},
);
expect(composite).toBeInstanceOf(ProviderCleanupError);
expect(composite).toMatchObject({
providerId: "fixture-provider",
operation: "fixture_close",
cleanupIncomplete: true,
cleanupResources: ["first-handle", "second-handle"],
diagnostics: { reason: "Fixture cleanup remains incomplete" },
});
expect(composite.cause).toBeInstanceOf(AggregateError);
expect((composite.cause as AggregateError).errors).toEqual([
first,
untyped,
second,
]);
expect((composite.cause as AggregateError).message).toBe(
"Fixture cleanup failed",
);
releaseOwnedCleanup(first);
expect(composite.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(second);
expect(composite.cleanupIncomplete).toBe(false);
});
it("defaults the aggregate cause to the owned failures", () => {
const only = new ProviderCleanupError(
"fixture",
["only-handle"],
{ reason: "only" },
{ operation: "fixture_close" },
);
const composite = providerCleanupErrorFromFailures(
"fixture-provider",
[only],
"Fixture cleanup remains incomplete",
{ operation: "fixture_close" },
);
expect((composite.cause as AggregateError).errors).toEqual([only]);
expect((composite.cause as AggregateError).message).toBe("");
});
it("follows an existing owner's release via withInheritedCleanupOwnership", () => {
const owner = new ProviderCleanupError("fixture", ["owned-handle"], {});
const cleanup = { reason: owner.message, resources: owner.cleanupResources };
+27
View File
@@ -1,4 +1,5 @@
import { ProviderAdapterError } from "./providerAdapterError.js";
import { ProviderCleanupError } from "./providerCleanupError.js";
import { childFailureDiagnostics } from "./analysisErrorProjection.js";
import type { AnalysisError } from "./analysisErrorBase.js";
import {
@@ -103,6 +104,32 @@ export const analysisErrorWithCloseRejections = (
? analysisErrorWithCloseRejection(first, second, operation)
: analysisErrorWithCleanupFailure(first, second, operation);
/**
* Compose several cleanup failures into one provider cleanup failure. It lists
* the parts' resources and completes once every part reports release. Pass
* `causes` to keep failures that are not AnalysisErrors in the aggregate
* cause; only `failures` own completion.
*/
export const providerCleanupErrorFromFailures = (
providerId: string,
failures: readonly AnalysisError[],
reason: string,
options: {
readonly operation: string;
readonly causes?: readonly unknown[];
readonly message?: string;
},
): ProviderCleanupError =>
new ProviderCleanupError(
providerId,
failures.flatMap((failure) => failure.cleanupResources),
{ reason },
{
operation: options.operation,
cause: new AggregateError(options.causes ?? failures, options.message),
},
).bindCleanupDependencies(failures);
/**
* Follow an existing live owner's cleanup completion from a wrapper error while
* keeping its released resource history empty once that owner finishes. If the
+6 -8
View File
@@ -38,6 +38,7 @@ import { AnalysisError } from "../domain/analysisErrorBase.js";
import { isValidFridaRemoteAddress } from "../domain/fridaRemoteAddress.js";
import { redactExplicitFailure } from "../domain/explicitSensitiveFailure.js";
import { explicitValueSpans } from "../domain/explicitSensitiveValues.js";
import { providerCleanupErrorFromFailures } from "../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { AnalysisCleanupLease } from "../resources/index.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -935,18 +936,15 @@ export class FridaInstrumentationManager implements FridaInstrumentationPort {
}
}
if (failures.length > 0)
throw new ProviderCleanupError(
throw providerCleanupErrorFromFailures(
"frida",
failures.flatMap((failure) => failure.cleanupResources),
{ reason: "Frida session cleanup was incomplete" },
failures,
"Frida session cleanup was incomplete",
{
operation: "frida_cleanup",
cause: new AggregateError(
failures,
"Frida session cleanup was incomplete",
),
message: "Frida session cleanup was incomplete",
},
).bindCleanupDependencies(failures);
);
}
#cleanupStartup(pending: PendingStartupCleanup): Promise<readonly string[]> {
@@ -0,0 +1,115 @@
import { expect, it, onTestFinished, vi } from "vitest";
import { CdpBrowserProvider } from "../../../src/browser/CdpBrowserProvider.js";
import { CdpElectronProvider } from "../../../src/browser/CdpElectronProvider.js";
import { CdpTargetSessionOwner } from "../../../src/browser/CdpTargetSessionOwner.js";
import { ElectronFileScope } from "../../../src/browser/ElectronFileScope.js";
import { IsolatedWebBundleAnalyzer } from "../../../src/browser/IsolatedWebBundleAnalyzer.js";
import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js";
import { releaseOwnedCleanup } from "../../support/cleanupRelease.js";
const cleanupFailure = (resource: string) =>
new ProviderCleanupError(
"fixture",
[resource],
{ reason: `${resource} remains owned` },
{ operation: "fixture_close" },
);
const closeFailure = async (close: () => Promise<void>): Promise<unknown> => {
try {
await close();
} catch (cause: unknown) {
return cause;
}
throw new Error("Expected close to fail");
};
const providers = [
{
name: "CdpBrowserProvider",
providerId: "rea-cdp-browser",
operation: "analyze_web_bundle",
create: () => new CdpBrowserProvider(),
failSecondClose: (cause: unknown) =>
vi
.spyOn(IsolatedWebBundleAnalyzer.prototype, "close")
.mockRejectedValueOnce(cause),
},
{
name: "CdpElectronProvider",
providerId: "rea-cdp-electron",
operation: "inspect_electron_page",
create: () => new CdpElectronProvider(),
failSecondClose: (cause: unknown) =>
vi
.spyOn(ElectronFileScope.prototype, "retryCleanup")
.mockRejectedValueOnce(cause),
},
] as const;
it.each(providers)(
"$name keeps both close failures and completes only after both release",
async ({ providerId, operation, create, failSecondClose }) => {
onTestFinished(() => {
vi.restoreAllMocks();
});
const transport = cleanupFailure("transport-handle");
const second = cleanupFailure("second-handle");
vi.spyOn(CdpTargetSessionOwner.prototype, "close").mockRejectedValueOnce(
transport,
);
failSecondClose(second);
const provider = create();
const composite = await closeFailure(() => provider.close());
if (!(composite instanceof ProviderCleanupError))
throw new Error("Expected a provider cleanup failure");
expect(composite).toMatchObject({
providerId,
operation,
cleanupIncomplete: true,
cleanupResources: ["transport-handle", "second-handle"],
});
expect(composite.cause).toBeInstanceOf(AggregateError);
expect((composite.cause as AggregateError).errors).toEqual([
transport,
second,
]);
releaseOwnedCleanup(transport);
expect(composite.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(second);
expect(composite.cleanupIncomplete).toBe(false);
},
);
it.each(providers)(
"$name keeps an untyped close failure in the cause without owning its completion",
async ({ create, failSecondClose }) => {
onTestFinished(() => {
vi.restoreAllMocks();
});
const transport = cleanupFailure("transport-handle");
const untyped = new Error("untyped close failure");
vi.spyOn(CdpTargetSessionOwner.prototype, "close").mockRejectedValueOnce(
transport,
);
failSecondClose(untyped);
const provider = create();
const composite = await closeFailure(() => provider.close());
if (!(composite instanceof ProviderCleanupError))
throw new Error("Expected a provider cleanup failure");
expect(composite.cleanupResources).toEqual(["transport-handle"]);
expect((composite.cause as AggregateError).errors).toEqual([
transport,
untyped,
]);
expect(composite.cleanupIncomplete).toBe(true);
releaseOwnedCleanup(transport);
expect(composite.cleanupIncomplete).toBe(false);
},
);