From b6363efc97fbeb6f813f8488d15e89d3c68dac72 Mon Sep 17 00:00:00 2001 From: Anant <111563424+anant8140@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:21:28 +0530 Subject: [PATCH] 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 * style(test): format the Playwright cleanup test with oxfmt Co-Authored-By: Claude Opus 5.5 * 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 --------- Co-authored-by: Anant Mandanka Co-authored-by: Claude Opus 5.5 Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- .../baselines/cleanup-dependency-binding.json | 5 +- src/browser/CdpBrowserProvider.ts | 18 +-- src/browser/CdpElectronProvider.ts | 18 +-- .../PlaywrightBrowserScenarioProvider.test.ts | 51 ++++++++ .../PlaywrightBrowserScenarioProvider.ts | 18 +-- src/domain/analysisErrorCleanup.test.ts | 68 +++++++++++ src/domain/analysisErrorCleanup.ts | 27 ++++ src/frida/FridaInstrumentationManager.ts | 14 +-- .../cdpProviderCloseComposition.test.ts | 115 ++++++++++++++++++ 9 files changed, 295 insertions(+), 39 deletions(-) create mode 100644 tests/boundary/browser/cdpProviderCloseComposition.test.ts diff --git a/scripts/verify/baselines/cleanup-dependency-binding.json b/scripts/verify/baselines/cleanup-dependency-binding.json index bd30cb07e7..5dd9a11d33 100644 --- a/scripts/verify/baselines/cleanup-dependency-binding.json +++ b/scripts/verify/baselines/cleanup-dependency-binding.json @@ -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, diff --git a/src/browser/CdpBrowserProvider.ts b/src/browser/CdpBrowserProvider.ts index b16ece541c..c9713e845b 100644 --- a/src/browser/CdpBrowserProvider.ts +++ b/src/browser/CdpBrowserProvider.ts @@ -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 }, + ); } } diff --git a/src/browser/CdpElectronProvider.ts b/src/browser/CdpElectronProvider.ts index b2aff1ecfa..d5b39f2ad8 100644 --- a/src/browser/CdpElectronProvider.ts +++ b/src/browser/CdpElectronProvider.ts @@ -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 }, + ); } } diff --git a/src/browser/PlaywrightBrowserScenarioProvider.test.ts b/src/browser/PlaywrightBrowserScenarioProvider.test.ts index ce099e1c82..88ea2eef5f 100644 --- a/src/browser/PlaywrightBrowserScenarioProvider.test.ts +++ b/src/browser/PlaywrightBrowserScenarioProvider.test.ts @@ -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((resolve) => { diff --git a/src/browser/PlaywrightBrowserScenarioProvider.ts b/src/browser/PlaywrightBrowserScenarioProvider.ts index 75e525faa7..b1004ec1d5 100644 --- a/src/browser/PlaywrightBrowserScenarioProvider.ts +++ b/src/browser/PlaywrightBrowserScenarioProvider.ts @@ -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" }, + ); } } diff --git a/src/domain/analysisErrorCleanup.test.ts b/src/domain/analysisErrorCleanup.test.ts index 6767d43bda..c9687993b4 100644 --- a/src/domain/analysisErrorCleanup.test.ts +++ b/src/domain/analysisErrorCleanup.test.ts @@ -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 }; diff --git a/src/domain/analysisErrorCleanup.ts b/src/domain/analysisErrorCleanup.ts index 4b16befbb6..92cc572c18 100644 --- a/src/domain/analysisErrorCleanup.ts +++ b/src/domain/analysisErrorCleanup.ts @@ -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 diff --git a/src/frida/FridaInstrumentationManager.ts b/src/frida/FridaInstrumentationManager.ts index 80dbfd7186..1a37209423 100644 --- a/src/frida/FridaInstrumentationManager.ts +++ b/src/frida/FridaInstrumentationManager.ts @@ -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 { diff --git a/tests/boundary/browser/cdpProviderCloseComposition.test.ts b/tests/boundary/browser/cdpProviderCloseComposition.test.ts new file mode 100644 index 0000000000..5efeda6801 --- /dev/null +++ b/tests/boundary/browser/cdpProviderCloseComposition.test.ts @@ -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): Promise => { + 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); + }, +);