Files
rea/src/android/JadxProvider.ts
T
morluto 3ad1032b11 fix(android): finalize startup diagnostics before reporting failure
Record the first transport failure before SDK teardown, then capture terminal stderr after owned retirement. Preserve exact opaque cancellation reasons and keep foreign cleanup ownership separate through retries.

Validation: 119 focused tests across eight files; five selected baseline regressions; check:fast, docs:check, test discovery; nine real CLI and nine real MCP tiny-APK inspections. Native Windows/Linux startup failures and actual JVM OOM remain unverified.

Closes #4844
2026-10-18 01:28:36 +08:00

567 lines
17 KiB
TypeScript

import { throwIfJadxInterrupted } from "./JadxInterruption.js";
import { chmod, copyFile } from "node:fs/promises";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import type { AndroidAnalysisPort } from "../application/android/AndroidAnalysisPort.js";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisInputError,
} from "../domain/analysisErrorCore.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import type { AndroidRequest } from "../domain/android/androidAnalysis.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { err, ok, type Result } from "../domain/result.js";
import {
createJadxWorkspaceRoot,
type JadxWorkspaceRoot,
} from "./JadxWorkspaceRoot.js";
import {
snapshotAndroidEngine,
snapshotAndroidTarget,
} from "./AndroidTargetSnapshot.js";
import {
hashStableFile,
stableFileHashCause,
} from "../filesystem/StableFileHash.js";
import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
import { RegularFileChangedError } from "../filesystem/RegularFile.js";
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
import {
inspectJadxAvailability,
resolveJadxConfigurationInputs,
resolveJadxOperationTimeout,
validateJadxConfiguration,
} from "./JadxConfiguration.js";
import type { JadxLauncher } from "./JadxMcpTransport.js";
import { JadxSession } from "./JadxSession.js";
import { captureJadxFailure } from "./JadxFailure.js";
const BRIDGE_SOURCE = fileURLToPath(
new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url),
);
type Outcome = Awaited<ReturnType<AndroidAnalysisPort["execute"]>>;
const waitForTurn = (
predecessor: Promise<void>,
request: AndroidRequest,
signal?: AbortSignal,
): Promise<void> =>
new Promise((resolve, reject) => {
const abort = () =>
reject(
new AnalysisCancelledError(request.operation, {
cause: signal?.reason,
}),
);
signal?.addEventListener("abort", abort, { once: true });
if (signal?.aborted === true) abort();
void predecessor.then(() => {
signal?.removeEventListener("abort", abort);
resolve();
});
});
const androidTargetChanged = (
operation: string,
path: string,
cause?: unknown,
): AnalysisInputError =>
new AnalysisInputError(
operation,
cause === undefined ? undefined : { cause },
[
{
path: ["path"],
reason: "invalid_value",
message: `APK bytes changed after admission at ${path}; retry against a stable file.`,
},
],
);
const androidSourceChanged = (
operation: string,
source: string,
cause?: unknown,
): AnalysisCapabilityUnavailableError =>
new AnalysisCapabilityUnavailableError(
"jadx",
operation,
`Selected JADX input bytes changed during admission at ${source}; retry with a stable installation.`,
cause === undefined ? undefined : { cause },
);
const hashAndroidSource = async (
path: string,
operation: string,
signal: AbortSignal,
retainFailedClose: (owner: OwnedFileHandle) => void,
): Promise<string> => {
try {
return (await hashStableFile(path, { signal, retainFailedClose })).sha256;
} catch (cause: unknown) {
const physical = stableFileHashCause(cause);
if (physical instanceof RegularFileChangedError)
throw androidSourceChanged(operation, path, physical);
throw cause;
}
};
interface PendingCleanup {
readonly operation: string;
session: JadxSession | undefined;
root: JadxWorkspaceRoot | undefined;
readonly fileHandles: Map<OwnedFileHandle, string>;
readonly previousError: AnalysisError | undefined;
readonly operationCause: unknown;
reportedErrors: WeakRef<AnalysisError>[];
}
const cleanupResources = (resources: PendingCleanup): readonly string[] => [
...(resources.session === undefined
? []
: [resources.session.transport.runId]),
...(resources.root === undefined ? [] : [resources.root.path]),
...resources.fileHandles.values(),
];
/** The retained acquisition record owns both retry and current resource attribution. */
const cleanupFailure = (
resources: PendingCleanup,
cleanup: ProviderCleanupError,
): AnalysisError =>
(resources.previousError === undefined
? cleanup
: analysisErrorWithCleanupFailure(
resources.previousError,
cleanup,
resources.operation,
)
).bindCleanupResourceOwner({
get cleanupResources() {
return cleanupResources(resources);
},
});
const cleanup = async (
resources: PendingCleanup,
): Promise<Result<void, AnalysisError>> => {
const { session, root } = resources;
let sessionCloseFailed = false;
let sessionCloseCause: unknown;
try {
await session?.close();
resources.session = undefined;
} catch (cause) {
// Still drain independent hash descriptors, but keep the workspace until
// this session's process ownership is proven stopped.
sessionCloseFailed = true;
sessionCloseCause = cause;
}
const fileCloseCauses: unknown[] = [];
for (const owner of resources.fileHandles.keys()) {
try {
await owner.close();
if (
resources.operationCause instanceof RegularFileCleanupFailure &&
resources.operationCause.owner === owner
)
resources.previousError?.resolveCleanup();
resources.fileHandles.delete(owner);
} catch (cause: unknown) {
fileCloseCauses.push(cause);
}
}
if (sessionCloseFailed || fileCloseCauses.length > 0) {
const cleanupCauses = [
...(sessionCloseFailed ? [sessionCloseCause] : []),
...fileCloseCauses,
];
const cleanupError = new ProviderCleanupError(
"jadx",
cleanupResources(resources),
{
reason: cleanupCauses
.map((failure) =>
failure instanceof Error ? failure.message : String(failure),
)
.join("; "),
cleanup_causes: cleanupCauses.map((failure) =>
failure instanceof Error ? failure.message : String(failure),
),
provider_cleanup: cleanupCauses.map((failure) =>
failure instanceof ProviderCleanupError
? (failure.diagnostics ?? null)
: null,
),
},
{
operation: resources.operation,
cause: new AggregateError(
cleanupCauses,
"JADX resource cleanup failed",
),
},
);
return err(cleanupFailure(resources, cleanupError));
}
try {
await root?.close();
resources.root = undefined;
} catch (cause) {
const error = new ProviderCleanupError(
"jadx",
cleanupResources(resources),
{
reason: cause instanceof Error ? cause.message : String(cause),
},
{ operation: resources.operation, cause },
);
return err(cleanupFailure(resources, error));
}
return ok(undefined);
};
interface RetainedSession {
readonly key: string;
readonly root: JadxWorkspaceRoot;
readonly session: JadxSession;
readonly snapshot: string;
readonly jarHash: string;
readonly bridgeHash: string;
}
/** One serialized, immutable APK session per REA instance, retired on idle or shutdown. */
export class JadxProvider implements AndroidAnalysisPort {
#tail: Promise<void> = Promise.resolve();
#pendingCleanup: PendingCleanup | undefined;
#retained: RetainedSession | undefined;
#idle: NodeJS.Timeout | undefined;
readonly #shutdown = new AbortController();
#closePromise: Promise<void> | undefined;
constructor(
readonly environment: Readonly<Record<string, string | undefined>>,
readonly launcher?: JadxLauncher,
) {}
/** Report actual local prerequisites without starting JADX or opening a target. */
inspectAvailability(signal?: AbortSignal) {
return inspectJadxAvailability(this.environment, signal);
}
/** Serialize expensive work and bind both raw and normalized results to the APK. */
async execute(
target: BinaryTarget,
request: AndroidRequest,
options?: ExecutionOptions,
): Promise<Outcome> {
if (this.#shutdown.signal.aborted)
return err(
new AnalysisCancelledError(request.operation, {
cause: this.#shutdown.signal.reason,
}),
);
const signal =
options?.signal === undefined
? this.#shutdown.signal
: AbortSignal.any([options.signal, this.#shutdown.signal]);
const predecessor = this.#tail;
let release: () => void = () => {};
this.#tail = new Promise<void>((resolve) => {
release = resolve;
});
try {
await waitForTurn(predecessor, request, signal);
} catch (cause) {
void predecessor.then(release);
return err(
cause instanceof AnalysisError
? cause
: new AnalysisCancelledError(request.operation, { cause }),
);
}
try {
if (signal.aborted)
return err(
new AnalysisCancelledError(request.operation, {
cause: signal.reason,
}),
);
clearTimeout(this.#idle);
if (this.#pendingCleanup !== undefined) {
const retired = await this.#retire();
if (!retired.ok) return retired;
}
const outcome = await this.#execute(target, request, { signal });
if (outcome.ok) this.#scheduleIdle();
return outcome;
} finally {
release();
}
}
/** Cancel queued/active operations and join the owned engine and workspace cleanup. */
close(): Promise<void> {
this.#shutdown.abort();
clearTimeout(this.#idle);
this.#closePromise ??= this.#tail
.then(async () => {
const retired = await this.#retire();
if (!retired.ok) throw retired.error;
})
.catch((cause: unknown) => {
this.#closePromise = undefined;
throw cause;
});
return this.#closePromise;
}
async #retire(): Promise<Result<void, AnalysisError>> {
if (this.#pendingCleanup === undefined && this.#retained !== undefined) {
this.#pendingCleanup = {
operation: "close_binary",
session: this.#retained.session,
root: this.#retained.root,
fileHandles: new Map(),
previousError: undefined,
operationCause: undefined,
reportedErrors: [],
};
this.#retained = undefined;
}
if (this.#pendingCleanup === undefined) return ok(undefined);
const pending = this.#pendingCleanup;
const result = await cleanup(pending);
if (result.ok) {
for (const reportedError of pending.reportedErrors)
reportedError.deref()?.resolveCleanup();
pending.reportedErrors = [];
this.#pendingCleanup = undefined;
} else {
pending.reportedErrors = [
...pending.reportedErrors.filter(
(reportedError) => reportedError.deref() !== undefined,
),
new WeakRef(result.error),
];
}
return result;
}
#scheduleIdle(): void {
this.#idle = setTimeout(() => {
this.#tail = this.#tail.then(async () => {
await this.#retire();
});
}, 60_000);
this.#idle.unref();
}
async #execute(
target: BinaryTarget,
request: AndroidRequest,
options?: ExecutionOptions,
): Promise<Outcome> {
// The deadline is fixed per provider environment; an unusable value is
// refused before any file handle, workspace, or engine is acquired.
const timeoutMs = resolveJadxOperationTimeout(
this.environment,
request.operation,
);
if (!timeoutMs.ok) return timeoutMs;
const timeout = AbortSignal.timeout(timeoutMs.value);
const signal =
options?.signal === undefined
? timeout
: AbortSignal.any([options.signal, timeout]);
let root: JadxWorkspaceRoot | undefined;
let session: JadxSession | undefined;
const fileHandles: PendingCleanup["fileHandles"] = new Map();
const retainFailedClose =
(path: string) =>
(owner: OwnedFileHandle): void => {
fileHandles.set(owner, path);
};
try {
if (target.format !== "apk")
throw new AnalysisCapabilityUnavailableError(
"jadx",
request.operation,
`Target ${target.path} is ${target.format}; provide one standalone APK.`,
);
const configuration = await resolveJadxConfigurationInputs(
this.environment,
request.operation,
signal,
);
throwIfJadxInterrupted(signal);
const jarHash = await hashAndroidSource(
configuration.jar,
request.operation,
signal,
retainFailedClose(configuration.jar),
);
const bridgeHash = await hashAndroidSource(
BRIDGE_SOURCE,
request.operation,
signal,
retainFailedClose(BRIDGE_SOURCE),
);
let targetHash: string;
try {
targetHash = (
await hashStableFile(target.path, {
signal,
retainFailedClose: retainFailedClose(target.path),
})
).sha256;
} catch (cause: unknown) {
if (signal.aborted) throw cause;
if (cause instanceof RegularFileChangedError)
throw androidTargetChanged(request.operation, target.path, cause);
throw cause;
}
if (targetHash !== target.sha256)
throw androidTargetChanged(request.operation, target.path);
const key = JSON.stringify({
path: target.path,
sha256: target.sha256,
jar: configuration.jar,
jarHash,
bridgeHash,
java: configuration.java,
arguments: configuration.jvmArguments,
options: [
this.environment.JAVA_TOOL_OPTIONS,
this.environment._JAVA_OPTIONS,
this.environment.JDK_JAVA_OPTIONS,
this.environment.PATH,
this.environment.JAVA_HOME,
],
});
if (this.#retained !== undefined && this.#retained.key !== key) {
const retired = await this.#retire();
if (!retired.ok) return retired;
}
let retained = this.#retained;
if (retained === undefined) {
await validateJadxConfiguration(
configuration,
this.environment,
request.operation,
signal,
);
root = await createJadxWorkspaceRoot();
const workspaceSignal =
root.failureSignal === undefined
? signal
: AbortSignal.any([signal, root.failureSignal]);
const engine = await snapshotAndroidEngine(
configuration.jar,
jarHash,
root.path,
request.operation,
workspaceSignal,
);
const snapshot = await snapshotAndroidTarget(
target.path,
target.sha256,
root.path,
request.operation,
workspaceSignal,
);
const bridge = join(root.path, "ReaJadxBridge.java");
await copyFile(BRIDGE_SOURCE, bridge);
await chmod(bridge, 0o400);
const copiedBridgeHash = await hashAndroidSource(
bridge,
request.operation,
workspaceSignal,
retainFailedClose(bridge),
);
if (copiedBridgeHash !== bridgeHash)
throw androidSourceChanged(
request.operation,
BRIDGE_SOURCE,
undefined,
);
throwIfJadxInterrupted(workspaceSignal);
session = new JadxSession(
{
command: configuration.java,
arguments: [
...configuration.jvmArguments,
"--class-path",
engine.path,
bridge,
],
cwd: root.path,
hostEnvironment: this.environment,
signal: workspaceSignal,
},
this.launcher,
);
retained = {
key,
root,
session,
snapshot,
jarHash: engine.sha256,
bridgeHash,
};
}
root = retained.root;
session = retained.session;
const activeSignal =
root.failureSignal === undefined
? signal
: AbortSignal.any([signal, root.failureSignal]);
const { snapshot } = retained;
const outcome = ok(
await session.execute({
request,
target,
snapshot,
jarHash: retained.jarHash,
bridgeHash: retained.bridgeHash,
signal: activeSignal,
timeoutMs: timeoutMs.value,
}),
);
throwIfJadxInterrupted(activeSignal);
this.#retained = retained;
return outcome;
} catch (cause) {
const failure = captureJadxFailure({
cause,
request,
timeout,
timeoutMs: timeoutMs.value,
signal: options?.signal,
session,
});
// Admission can fail before selecting an existing session for execution.
root ??= this.#retained?.root;
session ??= this.#retained?.session;
this.#retained = undefined;
this.#pendingCleanup = {
operation: request.operation,
session,
root,
fileHandles,
get previousError() {
return failure();
},
operationCause: cause,
reportedErrors: [],
};
const retired = await this.#retire();
return retired.ok ? err(failure()) : retired;
}
}
}