From 2a0b58e4403daba872e19b6bd24f494ddf1027a6 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 11 Oct 2026 00:03:18 +0800 Subject: [PATCH] refactor(cleanup): share failure composition and retain native UI owners Validation: integrated changes passed formatting, typecheck, lint, resolved module-boundary verification and git diff --check. Tests and real-provider workflows were not run. --- src/application/DirectAnalysisCleanup.ts | 2 +- .../binary/AnalysisClientCleanup.test.ts | 6 +- .../binary/AnalysisClientCleanup.ts | 33 ---- src/application/binary/BinarySession.ts | 6 +- src/domain/analysisErrorBase.ts | 4 +- src/domain/analysisErrorCleanup.ts | 39 +++++ src/domain/native/nativeUiObservation.ts | 2 + src/ghidra/GhidraProviderClient.ts | 2 +- src/hopper/HopperClient.ts | 2 +- src/native/NativeMacOSProvider.ts | 165 ++++++++++++++++-- src/native/NativeUiHelperRuntime.ts | 16 +- src/native/NativeUiObservation.ts | 11 +- 12 files changed, 225 insertions(+), 63 deletions(-) create mode 100644 src/domain/analysisErrorCleanup.ts diff --git a/src/application/DirectAnalysisCleanup.ts b/src/application/DirectAnalysisCleanup.ts index 3f073f7b5..0a49f0d5f 100644 --- a/src/application/DirectAnalysisCleanup.ts +++ b/src/application/DirectAnalysisCleanup.ts @@ -6,7 +6,7 @@ import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { err, type Result } from "../domain/result.js"; import type { AnalysisExecution } from "./AnalysisProvider.js"; import type { BinarySession } from "./binary/BinarySession.js"; -import { analysisErrorWithCleanupFailure } from "./binary/AnalysisClientCleanup.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; /** Await one-shot cleanup and retain either the outcome or both failures. */ export const withSessionCleanup = async ( diff --git a/src/application/binary/AnalysisClientCleanup.test.ts b/src/application/binary/AnalysisClientCleanup.test.ts index f4ada3822..e3dae7646 100644 --- a/src/application/binary/AnalysisClientCleanup.test.ts +++ b/src/application/binary/AnalysisClientCleanup.test.ts @@ -5,10 +5,8 @@ import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; import { err } from "../../domain/result.js"; import type { AnalysisClient } from "../AnalysisProvider.js"; -import { - analysisErrorWithCleanupFailure, - closeAnalysisClient, -} from "./AnalysisClientCleanup.js"; +import { closeAnalysisClient } from "./AnalysisClientCleanup.js"; +import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; const clientClosingWith = (cause: unknown): AnalysisClient => ({ execute: () => Promise.resolve(err(new ProviderCleanupError("x", [], {}))), diff --git a/src/application/binary/AnalysisClientCleanup.ts b/src/application/binary/AnalysisClientCleanup.ts index a693d2d8b..db283cc25 100644 --- a/src/application/binary/AnalysisClientCleanup.ts +++ b/src/application/binary/AnalysisClientCleanup.ts @@ -1,6 +1,4 @@ import { ProviderCleanupError } from "../../domain/providerCleanupError.js"; -import { ProviderAdapterError } from "../../domain/providerAdapterError.js"; -import { projectAnalysisError } from "../../domain/analysisErrorProjection.js"; import { err, type Result } from "../../domain/result.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; import type { AnalysisClient, ExecutionOptions } from "../AnalysisProvider.js"; @@ -29,34 +27,3 @@ export const closeAnalysisClient = async ( ); } }; - -/** Preserve the original lifecycle failure alongside incomplete cleanup. */ -export const analysisErrorWithCleanupFailure = ( - primary: AnalysisError, - cleanup: AnalysisError, - operation = "close_binary", -): AnalysisError => { - const projected = projectAnalysisError(cleanup); - return new ProviderAdapterError( - cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea", - operation, - { - cause: primary, - userMessage: projectAnalysisError(primary).message, - ...(primary.capturedOutput === undefined - ? {} - : { capturedOutput: primary.capturedOutput }), - ...(primary.partialObservation === undefined - ? {} - : { partialObservation: primary.partialObservation }), - cleanup: { - reason: projected.message, - resources: cleanup.cleanupResources, - }, - diagnostics: { - primary_error: projectAnalysisError(primary), - cleanup_error: projected, - }, - }, - ); -}; diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.ts index b9ff6a23c..bcf4da184 100644 --- a/src/application/binary/BinarySession.ts +++ b/src/application/binary/BinarySession.ts @@ -44,10 +44,8 @@ import { commitExecutionProfile, prepareSessionExecution, } from "./BinarySessionExecution.js"; -import { - analysisErrorWithCleanupFailure, - closeAnalysisClient, -} from "./AnalysisClientCleanup.js"; +import { closeAnalysisClient } from "./AnalysisClientCleanup.js"; +import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js"; const OFFICIAL_OPERATIONS: ReadonlySet = new Set( OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name), ); diff --git a/src/domain/analysisErrorBase.ts b/src/domain/analysisErrorBase.ts index 90056c3b2..172adda8e 100644 --- a/src/domain/analysisErrorBase.ts +++ b/src/domain/analysisErrorBase.ts @@ -99,6 +99,7 @@ import type { BrowserScenarioPartialObservation } from "./browserScenarioCapture import type { Evidence } from "./evidence.js"; import type { AndroidPartialObservation } from "./android/androidPartialObservation.js"; import type { FirmwarePartialObservation } from "./firmware/firmwareAnalysis.js"; +import type { NativeUiObservationResult } from "./native/nativeUiObservation.js"; /** Provider-neutral evidence collected before a typed analysis failure. */ export type AnalysisPartialObservation = @@ -111,4 +112,5 @@ export type AnalysisPartialObservation = | ArtifactInventoryPartialObservation | Evidence | AndroidPartialObservation - | FirmwarePartialObservation; + | FirmwarePartialObservation + | NativeUiObservationResult; diff --git a/src/domain/analysisErrorCleanup.ts b/src/domain/analysisErrorCleanup.ts new file mode 100644 index 000000000..df1f95b75 --- /dev/null +++ b/src/domain/analysisErrorCleanup.ts @@ -0,0 +1,39 @@ +import { ProviderAdapterError } from "./providerAdapterError.js"; +import { projectAnalysisError } from "./analysisErrorProjection.js"; +import type { AnalysisError } from "./analysisErrorBase.js"; + +/** Preserve the original lifecycle failure alongside incomplete cleanup. */ +export const analysisErrorWithCleanupFailure = ( + primary: AnalysisError, + cleanup: AnalysisError, + operation = "close_binary", +): AnalysisError => { + const projected = projectAnalysisError(cleanup); + return new ProviderAdapterError( + cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea", + operation, + { + cause: primary, + userMessage: projectAnalysisError(primary).message, + ...(primary.capturedOutput === undefined + ? {} + : { capturedOutput: primary.capturedOutput }), + ...(primary.partialObservation === undefined + ? {} + : { partialObservation: primary.partialObservation }), + cleanup: { + reason: projected.message, + resources: [ + ...new Set([ + ...primary.cleanupResources, + ...cleanup.cleanupResources, + ]), + ], + }, + diagnostics: { + primary_error: projectAnalysisError(primary), + cleanup_error: projected, + }, + }, + ); +}; diff --git a/src/domain/native/nativeUiObservation.ts b/src/domain/native/nativeUiObservation.ts index a9378ad7b..392d4d8db 100644 --- a/src/domain/native/nativeUiObservation.ts +++ b/src/domain/native/nativeUiObservation.ts @@ -156,3 +156,5 @@ export const nativeUiResultSchema = z.strictObject({ restore: z.literal("leave-as-is"), limitations: z.array(z.string()), }); + +export type NativeUiObservationResult = z.infer; diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts index bd4015ac1..4ee4c8b82 100644 --- a/src/ghidra/GhidraProviderClient.ts +++ b/src/ghidra/GhidraProviderClient.ts @@ -1,4 +1,4 @@ -import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { fileURLToPath } from "node:url"; import { diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts index 345076969..14c5d6965 100644 --- a/src/hopper/HopperClient.ts +++ b/src/hopper/HopperClient.ts @@ -5,7 +5,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import writeFileAtomic from "write-file-atomic"; -import { analysisErrorWithCleanupFailure } from "../application/binary/AnalysisClientCleanup.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js"; import { HopperCancelledError, diff --git a/src/native/NativeMacOSProvider.ts b/src/native/NativeMacOSProvider.ts index d63db2506..d44409984 100644 --- a/src/native/NativeMacOSProvider.ts +++ b/src/native/NativeMacOSProvider.ts @@ -36,10 +36,13 @@ import { AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js"; +import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { BinaryTargetError } from "../domain/configurationErrors.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; +import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import { AnalysisError } from "../domain/analysisErrorBase.js"; import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js"; +import type { NativeUiObservationResult } from "../domain/native/nativeUiObservation.js"; import { omittedPrototypeKeysLimitation, parseXmlPropertyList, @@ -77,6 +80,11 @@ import { architectureLocations, inspectNativeMacho, } from "./NativeMachoInspection.js"; +import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; +import { + createNativeUiHelperRuntime, + type NativeUiHelperRuntime, +} from "./NativeUiHelperRuntime.js"; /** Read-only semantic provider composed from Xcode command-line utilities. */ export class NativeMacOSProvider implements AnalysisProvider { @@ -117,6 +125,10 @@ export class NativeMacOSProvider implements AnalysisProvider { } class NativeMacOSClient implements AnalysisClient { + readonly #pendingNativeUiRuntimes = new Set(); + #nativeUiTail: Promise = Promise.resolve(); + #closed = false; + constructor( private readonly target: BinaryTarget, private readonly runner: NativeCommandRunner, @@ -129,6 +141,14 @@ class NativeMacOSClient implements AnalysisClient { parameters: Readonly>, options?: { readonly signal?: AbortSignal }, ) { + if (this.#closed) + return err( + new AnalysisCapabilityUnavailableError( + IDENTITY.id, + operation, + "Native provider client is closed", + ), + ); if (options?.signal?.aborted === true) return err(new AnalysisCancelledError(operation)); if (operation === "health") @@ -212,17 +232,7 @@ class NativeMacOSClient implements AnalysisClient { operation === "observe_native_ui" || operation === "capture_native_ui_scenario" ) { - const result = await observeNativeUi(this.target, operation, parameters, { - environment: this.environment, - signal: options?.signal, - }); - return result.ok - ? ok( - createAnalysisExecution(result.value, IDENTITY, { - limitations: result.value.limitations, - }), - ) - : result; + return this.#observeNativeUi(operation, parameters, options?.signal); } try { const observation = await this.#dispatch( @@ -247,8 +257,137 @@ class NativeMacOSClient implements AnalysisClient { } } - close(): Promise> { - return this.tracer.close(); + async close(): Promise> { + this.#closed = true; + const uiCleanupFailures = await this.#serializeNativeUi(() => + this.#retryNativeUiCleanup(), + ); + const tracer = await this.tracer.close(); + if (uiCleanupFailures.length === 0) return tracer; + const uiCleanup = this.#nativeUiCleanupFailure( + uiCleanupFailures, + "close_binary", + ); + return tracer.ok + ? err(uiCleanup) + : err(analysisErrorWithCleanupFailure(tracer.error, uiCleanup)); + } + + #observeNativeUi( + operation: "observe_native_ui" | "capture_native_ui_scenario", + parameters: Readonly>, + signal?: AbortSignal, + ) { + return this.#serializeNativeUi(async () => { + if (this.#closed) + return err( + new AnalysisCapabilityUnavailableError( + IDENTITY.id, + operation, + "Native provider client is closed", + ), + ); + const earlierCleanupFailures = await this.#retryNativeUiCleanup(); + if (earlierCleanupFailures.length > 0) + return err( + this.#nativeUiCleanupFailure(earlierCleanupFailures, operation), + ); + const runtime = createNativeUiHelperRuntime(this.environment); + this.#pendingNativeUiRuntimes.add(runtime); + let result: Awaited>; + try { + result = await observeNativeUi(this.target, operation, parameters, { + environment: this.environment, + signal, + runtime, + }); + } catch (cause: unknown) { + result = err( + cause instanceof AnalysisError + ? cause + : new ProviderAdapterError(IDENTITY.id, operation, { cause }), + ); + } + try { + await runtime.close(); + this.#pendingNativeUiRuntimes.delete(runtime); + } catch (cause: unknown) { + const cleanup = this.#nativeUiCleanupFailure( + [{ runtime, cause }], + operation, + result.ok ? result.value : undefined, + ); + return err( + result.ok + ? cleanup + : analysisErrorWithCleanupFailure(result.error, cleanup, operation), + ); + } + return result.ok + ? ok( + createAnalysisExecution(result.value, IDENTITY, { + limitations: result.value.limitations, + }), + ) + : result; + }); + } + + #serializeNativeUi(operation: () => Promise): Promise { + const call = this.#nativeUiTail.then(operation, operation); + this.#nativeUiTail = call.then( + () => undefined, + () => undefined, + ); + return call; + } + + async #retryNativeUiCleanup(): Promise< + Array<{ readonly runtime: NativeUiHelperRuntime; readonly cause: unknown }> + > { + const failures: Array<{ + readonly runtime: NativeUiHelperRuntime; + readonly cause: unknown; + }> = []; + for (const runtime of this.#pendingNativeUiRuntimes) { + try { + await runtime.close(); + this.#pendingNativeUiRuntimes.delete(runtime); + } catch (cause: unknown) { + failures.push({ runtime, cause }); + } + } + return failures; + } + + #nativeUiCleanupFailure( + failures: readonly { + readonly runtime: NativeUiHelperRuntime; + readonly cause: unknown; + }[], + operation: string, + partialObservation?: NativeUiObservationResult, + ): ProviderCleanupError { + const resources = failures.flatMap(({ runtime }) => runtime.resources()); + return new ProviderCleanupError( + IDENTITY.id, + resources.length === 0 ? ["native-ui-runtime"] : resources, + { + reason: "Native UI runtime cleanup remains incomplete", + failures: failures.map(({ runtime, cause }) => ({ + resources: [...runtime.resources()], + reason: cause instanceof Error ? cause.message : String(cause), + })), + }, + { + operation, + cause: new AggregateError( + failures.map(({ cause }) => cause), + "Native UI runtime cleanup failed", + ), + ...(partialObservation === undefined ? {} : { partialObservation }), + }, + ); } #dispatch( diff --git a/src/native/NativeUiHelperRuntime.ts b/src/native/NativeUiHelperRuntime.ts index 3107a4b33..dfeae245d 100644 --- a/src/native/NativeUiHelperRuntime.ts +++ b/src/native/NativeUiHelperRuntime.ts @@ -9,10 +9,16 @@ import { safeParseJson } from "../domain/safeJson.js"; import type { NativeUiHelper } from "./NativeUiObservation.js"; import { NATIVE_UI_HELPER_MAX_BUFFER } from "./NativeUiOutputBudget.js"; +export interface NativeUiHelperRuntime { + readonly invoke: NativeUiHelper; + close(): Promise; + resources(): readonly string[]; +} + /** Lazily compile one owned helper per observation/scenario and remove its compiler cache. */ export const createNativeUiHelperRuntime = ( environment: Readonly, -) => { +): NativeUiHelperRuntime => { const selectedEnvironment = snapshotEnvironment(environment); let root: string | undefined; let executable: string | undefined; @@ -62,6 +68,7 @@ export const createNativeUiHelperRuntime = ( { timeout: 30_000, maxBuffer: NATIVE_UI_HELPER_MAX_BUFFER, + stopSignal: "SIGTERM", env: selectedEnvironment, ...(signal === undefined ? {} : { signal }), }, @@ -76,7 +83,12 @@ export const createNativeUiHelperRuntime = ( return { invoke, close: async () => { - if (root !== undefined) await rm(root, { recursive: true, force: true }); + if (root !== undefined) { + await rm(root, { recursive: true, force: true }); + root = undefined; + executable = undefined; + } }, + resources: () => (root === undefined ? [] : [root]), }; }; diff --git a/src/native/NativeUiObservation.ts b/src/native/NativeUiObservation.ts index 73d301042..9dc337189 100644 --- a/src/native/NativeUiObservation.ts +++ b/src/native/NativeUiObservation.ts @@ -15,7 +15,10 @@ import { import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { type AnalysisError } from "../domain/analysisErrorBase.js"; import { err, ok, type Result } from "../domain/result.js"; -import { createNativeUiHelperRuntime } from "./NativeUiHelperRuntime.js"; +import { + createNativeUiHelperRuntime, + type NativeUiHelperRuntime, +} from "./NativeUiHelperRuntime.js"; import { NATIVE_UI_OUTPUT_BUDGET_BYTES, NATIVE_UI_OUTPUT_WEIGHT, @@ -47,16 +50,18 @@ export const observeNativeUi = async ( environment: Readonly; signal?: AbortSignal | undefined; invoke?: NativeUiHelper; + runtime?: NativeUiHelperRuntime; }, ): Promise, AnalysisError>> => { - const runtime = createNativeUiHelperRuntime(options.environment); + const runtime = + options.runtime ?? createNativeUiHelperRuntime(options.environment); try { return await observeWithHelper(target, operation, parameters, { ...options, invoke: options.invoke ?? runtime.invoke, }); } finally { - await runtime.close(); + if (options.runtime === undefined) await runtime.close(); } };