fix(kuna): own version-probe processes through output and cleanup

Use the shared command supervisor for installation probes and retain exact
process cleanup owners through doctor, profile resolution, and session health.
Preserve exit status, bounded captured output, cancellation reasons, and live
cleanup facts. Block subsequent inspection until retained cleanup is retried.

Generalize the existing inspection resource scope and migrate its consumers,
including verifier scripts; remove the verifier's duplicate raw version probe.

Validation: 116 distinct focused tests passed, including built CLI doctor with
inherited output, cancellation/finalization, cleanup retry, and fake-provider
verifier workflows. Build, check:fast, and test discovery passed. No real Kuna
distribution or analysis target was executed.

Synthetic Darwin inspection timing: first-call median 707ms versus 5.79ms;
same-process repeat 37.9ms versus 3.08ms. First use includes ownership-helper
preparation. Family CPU and actual peak family memory remain unmeasured.

Fixes #5557
This commit is contained in:
morluto committed 2026-10-21 00:09:34 +08:00
1 parent 90e433df06
commit ff78165978
41 files changed
+1319 -263

No files matched your search

+2 -2
View File
@@ -1,4 +1,4 @@
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import type {
DoctorProviderCheck,
DoctorProviderInspection,
@@ -15,7 +15,7 @@ import {
/** Project the validated JADX configuration into the doctor contract. */
export const inspectJadxProvider = async (
environment: Readonly<Record<string, string | undefined>>,
resourceOwner: FileCloseResourceOwner,
resourceOwner: RetainedResourceScope,
signal?: AbortSignal,
): Promise<DoctorProviderInspection> => {
const configured = environment.REA_JADX_MCP_JAR !== undefined;
+2 -2
View File
@@ -1,5 +1,5 @@
import { randomUUID } from "node:crypto";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import {
AnalysisError,
type AnalysisCapturedOutput,
@@ -27,7 +27,7 @@ const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;
const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;
export interface JadxJavaProbeOptions {
readonly resourceOwner: FileCloseResourceOwner;
readonly resourceOwner: RetainedResourceScope;
readonly signal?: AbortSignal | undefined;
readonly operation?: string;
/** The Android operation owns this deadline; the probe also has its own bound. */
+2 -2
View File
@@ -1,6 +1,6 @@
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
import { throwIfJadxInterrupted } from "./JadxInterruption.js";
import { chmod, copyFile } from "node:fs/promises";
@@ -250,7 +250,7 @@ export class JadxProvider implements AndroidAnalysisPort {
readonly #inspections = new Set<
Promise<Awaited<ReturnType<typeof inspectJadxAvailability>>>
>();
readonly #prerequisiteOwner: FileCloseResourceOwner = {
readonly #prerequisiteOwner: RetainedResourceScope = {
retain: (owner, resource) =>
this.#prerequisites.retain({
kind: "lease",
+3 -3
View File
@@ -215,8 +215,8 @@ export interface AnalysisClientContext {
readonly runId: string;
}
/** One lifecycle owner for descriptor cleanup and abortable inspection work. */
export interface FileCloseResourceOwner {
/** One lifecycle owner for retained resources and abortable inspection work. */
export interface RetainedResourceScope {
retain(
owner: {
close(): Promise<void>;
@@ -246,7 +246,7 @@ export interface AnalysisProviderInspectionOptions {
}
export interface AnalysisProfileResolutionOptions extends AnalysisProviderInspectionOptions {
readonly fileCloseResources?: FileCloseResourceOwner;
readonly resourceScope?: RetainedResourceScope;
}
interface CapabilityEffects {
+4 -7
View File
@@ -10,7 +10,7 @@ import { STARTUP_OWNER_CLOSED } from "../process/SharedStartupAttempt.js";
import { constants } from "node:fs";
import { access, readdir, stat } from "node:fs/promises";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import type { FileCloseResourceOwner } from "./AnalysisProvider.js";
import type { RetainedResourceScope } from "./AnalysisProvider.js";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
import { join } from "node:path";
@@ -480,7 +480,7 @@ export interface SystemDoctorHostOptions {
readonly environment?: NodeJS.ProcessEnv;
readonly execFileOutput?: typeof execFileOutput;
readonly providerInspections?: (
fileCloseResources: FileCloseResourceOwner,
resourceScope: RetainedResourceScope,
signal: AbortSignal,
) => Promise<readonly DoctorProviderInspection[]>;
readonly providerRegistrationEnvironment?: () => Readonly<
@@ -506,7 +506,7 @@ export const systemDoctorHost = (
const hostExecFileOutput = options.execFileOutput ?? execFileOutput;
const homeDirectory = homeDirectoryFromEnvironment(environment, platform);
const commandEnvironment = { env: environment };
const fileCloseResources: FileCloseResourceOwner = {
const resourceScope: RetainedResourceScope = {
retain: (owner, resource) =>
resources.retain({
kind: "lease",
@@ -620,10 +620,7 @@ export const systemDoctorHost = (
: {
providerInspections: () =>
resources.run(() =>
options.providerInspections!(
fileCloseResources,
inspectionSignal,
),
options.providerInspections!(resourceScope, inspectionSignal),
),
}),
...(options.providerRegistrationEnvironment === undefined
@@ -39,7 +39,7 @@ import {
type AnalysisProviderCandidateEvaluation,
} from "./AnalysisProviderEvaluation.js";
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
import type { FileCloseResourceOwner } from "../AnalysisProvider.js";
import type { RetainedResourceScope } from "../AnalysisProvider.js";
/** Deterministic discovery truth for one configured deep provider. */
export interface AnalysisProviderCandidateStatus {
@@ -108,15 +108,15 @@ export class AnalysisProviderRegistry {
>
>();
readonly #selectionCleanup = new Set<AnalysisError>();
readonly #profileFiles = new ArtifactResourceScope();
readonly #profileFileOwner: FileCloseResourceOwner = {
readonly #profileResources = new ArtifactResourceScope();
readonly #profileOwner: RetainedResourceScope = {
retain: (owner, resource) =>
this.#profileFiles.retain({
this.#profileResources.retain({
kind: "lease",
resource,
lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
}),
run: (operation) => this.#profileFiles.run(operation),
run: (operation) => this.#profileResources.run(operation),
};
#closing: Promise<Result<null, AnalysisError>> | undefined;
@@ -186,7 +186,7 @@ export class AnalysisProviderRegistry {
return (
this.#selections.size > 0 ||
this.#discoveries.size > 0 ||
this.#profileFiles.hasPending ||
this.#profileResources.hasPending ||
[...this.#selectionCleanup].some((error) => error.cleanupIncomplete) ||
this.#providers.some(
(provider) => provider.hasPendingOwnedResources?.() === true,
@@ -215,7 +215,7 @@ export class AnalysisProviderRegistry {
]);
const failures: AnalysisError[] = [];
try {
await this.#profileFiles.retryCleanup();
await this.#profileResources.retryCleanup();
} catch (cause: unknown) {
const cleanup = ArtifactReaderFailure.cleanupObservation(
cause,
@@ -564,7 +564,7 @@ export class AnalysisProviderRegistry {
provider,
initial,
target,
{ signal, fileCloseResources: this.#profileFileOwner, scope },
{ signal, resourceScope: this.#profileOwner, scope },
);
if (!evaluation.ok) return evaluation;
const evaluated = evaluation.value;
@@ -608,7 +608,7 @@ export class AnalysisProviderRegistry {
status.targetSupport.status === "supported"
? evaluateAnalysisProviderCandidate(provider, status, target, {
signal,
fileCloseResources: this.#profileFileOwner,
resourceScope: this.#profileOwner,
scope,
})
: ok({
+4 -8
View File
@@ -49,20 +49,16 @@ export const createSystemDoctorHost = (
// parser-owned error when IDA itself was explicitly selected.
return analysisProvider === "ida" ? registration : ok(undefined);
},
providerInspections: async (fileCloseResources, inspectionSignal) => [
providerInspections: async (resourceScope, inspectionSignal) => [
await inspectSystemGhidraProvider(
environment,
fileCloseResources,
resourceScope,
inspectionSignal,
),
inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),
await inspectJadxProvider(
environment,
fileCloseResources,
inspectionSignal,
),
await inspectJadxProvider(environment, resourceScope, inspectionSignal),
await inspectKunaProvider(environment, process.platform, {
fileCloseResources,
resourceScope,
signal: inspectionSignal,
}),
],
+2 -2
View File
@@ -1,6 +1,6 @@
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import type {
DoctorProviderCheck,
DoctorProviderInspection,
@@ -69,7 +69,7 @@ export const projectGhidraDoctorInspection = (
/** Inspect the process-configured BYO Ghidra installation for `rea doctor`. */
export const inspectSystemGhidraProvider = async (
environment: Readonly<NodeJS.ProcessEnv>,
resourceOwner: FileCloseResourceOwner,
resourceOwner: RetainedResourceScope,
signal?: AbortSignal,
): Promise<DoctorProviderInspection> => {
try {
+2 -2
View File
@@ -1,6 +1,6 @@
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import {
probeGhidraJava,
type GhidraJavaObservation,
@@ -160,7 +160,7 @@ const assessNativeDecompiler = (
/** Caller-owned paths and host coordinates used for one installation probe. */
export interface GhidraInstallationOptions {
readonly environment: Readonly<NodeJS.ProcessEnv>;
readonly resourceOwner: FileCloseResourceOwner;
readonly resourceOwner: RetainedResourceScope;
readonly signal?: AbortSignal;
readonly installDir?: string;
readonly javaHome?: string;
+2 -2
View File
@@ -1,5 +1,5 @@
import { createHash } from "node:crypto";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import {
ArtifactFileCancelled,
ArtifactFileCleanupFailure,
@@ -15,7 +15,7 @@ import { ghidraFileFailure } from "./GhidraFileArtifacts.js";
/** Metadata admission budget, not a Java Properties format limit. */
export const MAX_GHIDRA_INSTALLATION_PROPERTIES_BYTES = 1024 * 1024;
export interface GhidraInstallationFileOptions {
readonly resourceOwner: FileCloseResourceOwner;
readonly resourceOwner: RetainedResourceScope;
readonly signal?: AbortSignal;
}
+2 -2
View File
@@ -6,7 +6,7 @@ import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
import {
OwnedCommandFailure,
@@ -110,7 +110,7 @@ const executablePath = (path: string): boolean => {
}
};
export interface GhidraJavaProbeOptions {
readonly resourceOwner: FileCloseResourceOwner;
readonly resourceOwner: RetainedResourceScope;
readonly signal?: AbortSignal;
readonly launcher?: NonNullable<
Parameters<typeof runOwnedCommand>[2]
+3 -3
View File
@@ -14,7 +14,7 @@ import type {
AnalysisClient,
AnalysisClientContext,
AnalysisProviderInspectionOptions,
FileCloseResourceOwner,
RetainedResourceScope,
AnalysisProfileResolutionOptions,
AnalysisProfileResolution,
AnalysisProviderCandidate,
@@ -108,7 +108,7 @@ export class GhidraProvider implements AnalysisProviderCandidate {
#inspectionAttempt:
| SharedStartupAttempt<Result<GhidraInstallationInspection, AnalysisError>>
| undefined;
readonly #inspectionOwner: FileCloseResourceOwner = {
readonly #inspectionOwner: RetainedResourceScope = {
retain: (owner, resource) =>
this.#inspectionResources.retain({
kind: "lease",
@@ -601,7 +601,7 @@ export class GhidraProvider implements AnalysisProviderCandidate {
#observeInstallation(
signal: AbortSignal,
resourceOwner: FileCloseResourceOwner = this.#inspectionOwner,
resourceOwner: RetainedResourceScope = this.#inspectionOwner,
): Promise<GhidraInstallationInspection> {
const options = {
resourceOwner,
+23
View File
@@ -13,6 +13,8 @@ import {
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { bindArtifactFileCleanup } from "../artifacts/ArtifactFileOperation.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
OwnedCommandFailure,
runOwnedCommand,
@@ -130,6 +132,27 @@ export const kunaFileCleanupError = (
return analysisErrorWithCleanupFailure(primary, cleanup, operation);
};
/** Preserve the exact retryable resources when an inspection admission retries them. */
export const kunaRetainedResourceCleanupError = (
cause: unknown,
operation: string,
): AnalysisError | undefined => {
if (
!(cause instanceof ArtifactReaderFailure) ||
cause.cleanupLeases === undefined ||
cause.cleanupLeases.length === 0
)
return undefined;
const cleanup = new ProviderCleanupError(
KUNA_PROVIDER_ID,
cause.cleanup?.resources ?? [],
{ reason: message(cause) },
{ cause, operation },
);
bindArtifactFileCleanup(cause, cleanup);
return cleanup;
};
/** File metadata that, unchanged, lets a verified digest stand without re-hashing. */
const verifiedExecutables = new Map<
string,
+68 -12
View File
@@ -7,10 +7,12 @@ import type {
DoctorProviderInspection,
} from "../application/Doctor.js";
import { readKunaConfiguration } from "./KunaConfiguration.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { kunaRetainedResourceCleanupError } from "./KunaCommand.js";
import {
createKunaResourceScope,
inspectKunaInstallation,
kunaInstallationCancellation,
kunaInstallationFailureDiagnostics,
@@ -39,25 +41,60 @@ export const inspectKunaProvider = async (
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform = process.platform,
options: {
readonly fileCloseResources: FileCloseResourceOwner;
readonly resourceScope: RetainedResourceScope;
readonly signal?: AbortSignal;
},
): Promise<DoctorProviderInspection> => {
const kunaResources = createKunaResourceScope(options.resourceScope);
let installation: Awaited<ReturnType<typeof inspectKunaInstallation>>;
try {
installation = await inspectKunaInstallation(environment, {
platform,
fileCloseResources: options.fileCloseResources,
resourceScope: kunaResources.owner,
...(options.signal === undefined ? {} : { signal: options.signal }),
});
} catch (cause: unknown) {
const retainedCleanup = kunaRetainedResourceCleanupError(cause, "doctor");
if (retainedCleanup !== undefined)
return {
id: KUNA_PROVIDER_ID,
configured: environment.REA_KUNA_COMMAND !== undefined,
available: false,
providerVersion: null,
registrationEnvironment: {},
checks: [
{
name: "installation",
ok: false,
code: "cleanup_incomplete",
detail: retainedCleanup.message,
remediation: null,
classification: "config_drift",
details: {
cleanup_incomplete: true,
cleanup_resources: [...retainedCleanup.cleanupResources],
},
},
],
};
if (!(cause instanceof RegularFileCleanupFailure)) {
const cancellation = kunaInstallationCancellation(cause);
if (cancellation !== undefined)
throw new AnalysisCancelledError("doctor", {
if (cancellation !== undefined) {
const error = new AnalysisCancelledError("doctor", {
cause: cancellation.reason,
diagnostics: cancellation.diagnostics,
...(!kunaResources.hasPending
? {}
: {
cleanup: {
reason: "Kuna version-probe process cleanup is unconfirmed.",
resources: kunaResources.cleanupResources ?? [],
},
}),
});
kunaResources.bindRetainedFailure(error);
throw error;
}
throw cause;
}
return {
@@ -85,15 +122,34 @@ export const inspectKunaProvider = async (
const configured =
environment.REA_KUNA_COMMAND !== undefined &&
environment.REA_KUNA_COMMAND.length > 0;
if (!installation.ok)
const base = {
id: KUNA_PROVIDER_ID,
configured,
available: false,
providerVersion: null,
registrationEnvironment: {},
} as const;
if (!installation.ok) {
const check = installationFailure(installation.error, configured);
const cleanupResources = kunaResources.cleanupResources;
if (!kunaResources.hasPending) return { ...base, checks: [check] };
return {
id: KUNA_PROVIDER_ID,
configured,
available: false,
providerVersion: null,
registrationEnvironment: {},
checks: [installationFailure(installation.error, configured)],
...base,
checks: [
{
...check,
code: "cleanup_incomplete",
details: {
...installation.error.diagnostics,
cleanup_incomplete: true,
...(cleanupResources === undefined
? {}
: { cleanup_resources: [...cleanupResources] }),
},
},
],
};
}
const { value } = installation;
return {
id: KUNA_PROVIDER_ID,
+201 -61
View File
@@ -3,18 +3,23 @@ import {
RegularFileOperationCancelled,
} from "../filesystem/RegularFile.js";
import { constants } from "node:fs";
import { randomUUID } from "node:crypto";
import { access, realpath, stat } from "node:fs/promises";
import { join } from "node:path";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { err, ok, type Result } from "../domain/result.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
AnalysisCleanupLease,
AnalysisCleanupLeaseGroup,
} from "../artifacts/AnalysisCleanupLease.js";
import {
hashStableFile,
stableFileHashCause,
} from "../filesystem/StableFileHash.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import {
RegularFileCleanupFailure,
RegularFileCancelled,
@@ -22,10 +27,15 @@ import {
withOwnedRegularFile,
} from "../filesystem/OwnedRegularFile.js";
import {
execFileOutput,
execFileOutputFailure,
ExecFileOutputCancelledError,
} from "../process/ExecFileOutput.js";
OwnedCommandFailure,
runOwnedCommand,
} from "../process/OwnedCommand.js";
import { retainOwnedCommandCleanup } from "../providers/OwnedCommandCleanup.js";
import type {
OwnedProviderProcessSpawnOptions,
ProviderProcessSnapshot,
SpawnedOwnedProviderProcess,
} from "../process/ProviderProcess.js";
import {
readKunaConfiguration,
type KunaConfiguration,
@@ -44,6 +54,45 @@ const VERSION_PROBE_MAX_OUTPUT_BYTES = 64 * 1024;
/** Release CI prints exactly `kuna <MAJOR.MINOR>`; source builds print the Cargo version. */
const VERSION_LINE = /^kuna (\d+\.\d+(?:\.\d+)?)\r?\n?$/u;
const versionProbeOutput = (snapshot: ProviderProcessSnapshot | null) => ({
stdout: snapshot?.stdout.text ?? "",
stderr: snapshot?.stderr.text ?? "",
exitCode: snapshot?.exitCode ?? null,
signal: snapshot?.signal ?? null,
stdoutBytes: snapshot?.stdout.bytes ?? 0,
stdoutObservedBytes: snapshot?.stdout.observedBytes ?? 0,
stderrBytes: snapshot?.stderr.bytes ?? 0,
stderrObservedBytes: snapshot?.stderr.observedBytes ?? 0,
stdoutInvalidUtf8: snapshot?.stdout.invalidUtf8 === true,
stderrInvalidUtf8: snapshot?.stderr.invalidUtf8 === true,
diagnosticTruncated: snapshot?.diagnosticTruncated === true,
outputIncomplete: snapshot?.outputIncomplete === true,
truncated:
snapshot?.diagnosticTruncated === true ||
snapshot?.outputIncomplete === true ||
(snapshot !== null &&
snapshot !== undefined &&
snapshot.stdout.bytes < snapshot.stdout.observedBytes),
});
const versionProbeOutputDiagnostics = (
output: ReturnType<typeof versionProbeOutput>,
) => ({
stdout: output.stdout,
stderr: output.stderr,
exit_code: output.exitCode,
signal: output.signal,
stdout_bytes: output.stdoutBytes,
stdout_observed_bytes: output.stdoutObservedBytes,
stderr_bytes: output.stderrBytes,
stderr_observed_bytes: output.stderrObservedBytes,
...(output.stdoutInvalidUtf8 ? { stdout_invalid_utf8: true } : {}),
...(output.stderrInvalidUtf8 ? { stderr_invalid_utf8: true } : {}),
diagnostic_truncated: output.diagnosticTruncated,
output_incomplete: output.outputIncomplete,
output_truncated: output.truncated,
});
/** One observed Kuna executable, identified by its bytes as well as its version. */
export interface KunaInstallation {
readonly configuration: KunaConfiguration;
@@ -77,7 +126,11 @@ export interface KunaInstallationOptions {
readonly signal?: AbortSignal;
/** Probe deadline; tests shorten it. */
readonly probeTimeoutMs?: number;
readonly fileCloseResources: FileCloseResourceOwner;
readonly resourceScope: RetainedResourceScope;
/** Test seam for the owned command launcher; production uses the verified default. */
readonly processLauncher?: (
options: OwnedProviderProcessSpawnOptions,
) => Promise<SpawnedOwnedProviderProcess>;
}
/** Cancellation facts normalized by the installation inspection that observed them. */
@@ -113,30 +166,52 @@ export const kunaInstallationCancellation = (
};
};
/** One installation inspection's file owners and their originating errors. */
export interface KunaFileCloseScope {
readonly owner: FileCloseResourceOwner;
/** One installation inspection's retained owners and originating errors. */
export interface KunaResourceScope {
readonly owner: RetainedResourceScope;
readonly cleanupResources: readonly string[] | undefined;
readonly hasPending: boolean;
bindFailure(failure: RegularFileCleanupFailure, error: AnalysisError): void;
bindRetainedFailure(error: AnalysisError): void;
}
/** Adapt retained descriptor owners into leases and bind errors to exact owners. */
export const createKunaFileCloseScope = (
parent: FileCloseResourceOwner,
): KunaFileCloseScope => {
/** Adapt retained resource owners into leases and bind errors to exact owners. */
export const createKunaResourceScope = (
parent: RetainedResourceScope,
): KunaResourceScope => {
const leases = new Map<
Parameters<FileCloseResourceOwner["retain"]>[0],
AnalysisCleanupLease
Parameters<RetainedResourceScope["retain"]>[0],
{ readonly lease: AnalysisCleanupLease }
>();
const bindPendingFailure = (error: AnalysisError) => {
const retained = [...leases.values()]
.map(({ lease }) => lease)
.filter((lease) => !lease.released);
if (retained.length > 0) new AnalysisCleanupLeaseGroup(error, retained);
};
return {
get hasPending() {
return [...leases.values()].some(({ lease }) => !lease.released);
},
get cleanupResources() {
const pending = [...leases.values()]
.map(({ lease }) => lease)
.filter((lease) => !lease.released);
if (pending.some((lease) => lease.cleanupResources === undefined))
return undefined;
return [
...new Set(pending.flatMap((lease) => lease.cleanupResources ?? [])),
];
},
owner: {
retain: (owner, resource) => {
const lease = AnalysisCleanupLease.forCloseOwner(owner, resource);
leases.set(owner, lease);
leases.set(owner, { lease });
parent.retain(
{
close: () => lease.release(),
get cleanupResources() {
return lease.cleanupResources ?? [resource];
return lease.cleanupResources;
},
},
resource,
@@ -144,8 +219,10 @@ export const createKunaFileCloseScope = (
},
run: (operation) => parent.run(operation),
},
bindFailure: (failure, error) =>
leases.get(failure.owner)?.bindCleanupError(error),
bindFailure: (failure, error) => {
if (leases.has(failure.owner)) bindPendingFailure(error);
},
bindRetainedFailure: bindPendingFailure,
};
};
@@ -211,40 +288,105 @@ export const inspectKunaInstallation = async (
assertRegularFileActive(options.signal);
const deadline = options.probeTimeoutMs ?? VERSION_PROBE_TIMEOUT_MS;
let stdout: string;
let snapshot: ProviderProcessSnapshot;
try {
({ stdout } = await execFileOutput(executable, ["--version"], {
env: kunaChildEnvironment(configuration.value),
timeout: deadline,
maxBuffer: VERSION_PROBE_MAX_OUTPUT_BYTES,
// Escalate to SIGKILL so an executable that ignores SIGTERM cannot hang doctor.
stopSignal: "SIGTERM",
...(options.signal === undefined ? {} : { signal: options.signal }),
}));
snapshot = await options.resourceScope.run(() =>
runOwnedCommand(
{
command: executable,
arguments: ["--version"],
runId: `rea-kuna-version-${randomUUID()}`,
// The configured command may be an interpreter-driven shim.
expectedCommand: null,
hostEnvironment: kunaChildEnvironment(configuration.value),
},
{
timeoutMs: deadline,
diagnosticBytes: VERSION_PROBE_MAX_OUTPUT_BYTES,
},
{
...(options.signal === undefined ? {} : { signal: options.signal }),
...(options.processLauncher === undefined
? {}
: { launcher: options.processLauncher }),
},
),
);
} catch (cause: unknown) {
if (cause instanceof ExecFileOutputCancelledError)
throw new RegularFileOperationCancelled(cause.cause);
const output = execFileOutputFailure(cause);
if (cause instanceof ArtifactReaderFailure) throw cause;
const retainedCleanup = retainOwnedCommandCleanup(
cause,
options.resourceScope,
"kuna",
"kuna:installation",
);
const cleanupIncomplete = retainedCleanup.length > 0;
if (cause instanceof OwnedCommandFailure) {
const output = versionProbeOutput(cause.snapshot);
if (cause.reason === "cancelled") {
const cancellation = new RegularFileOperationCancelled(
cause.cancellation?.reason,
);
installationFailureDiagnostics.set(cancellation, {
kuna_version_probe: {
status: "partial",
command,
executable,
deadline_ms: deadline,
...versionProbeOutputDiagnostics(output),
probe_failure_reason: cause.reason,
stop_requested: cause.snapshot !== null,
cleanup_incomplete: cleanupIncomplete,
},
});
throw cancellation;
}
return failure(
"version_unresolved",
`${executable} --version failed: ${output.stderr.trim() || cause.message}. ${KUNA_VERSION_PROBE_REMEDIATION}`,
{
command,
executable,
probe_failure_reason: cause.reason,
stop_requested: cause.snapshot !== null,
cleanup_incomplete: cleanupIncomplete,
deadline_ms: deadline,
...versionProbeOutputDiagnostics(output),
},
);
}
return failure(
"version_unresolved",
`${executable} --version failed: ${output?.stderr.trim() || message(cause)}. ${KUNA_VERSION_PROBE_REMEDIATION}`,
`${executable} --version failed: ${message(cause)}. ${KUNA_VERSION_PROBE_REMEDIATION}`,
{
command,
executable,
exit_code: typeof output?.code === "number" ? output.code : null,
signal: output?.signal ?? null,
killed: output?.killed ?? false,
output_truncated: output?.outputTruncated ?? false,
exit_code: null,
signal: null,
cleanup_incomplete: cleanupIncomplete,
deadline_ms: deadline,
},
);
}
const version = VERSION_LINE.exec(stdout)?.[1];
const probeOutput = versionProbeOutput(snapshot);
if (probeOutput.truncated)
return failure(
"version_unresolved",
`${executable} --version output was incomplete. ${KUNA_VERSION_PROBE_REMEDIATION}`,
{
command,
executable,
deadline_ms: deadline,
output_truncated: true,
stdout: probeOutput.stdout.slice(0, 256),
},
);
const version = VERSION_LINE.exec(probeOutput.stdout)?.[1];
if (version === undefined)
return failure(
"version_unresolved",
`${executable} --version printed no recognizable Kuna version. ${KUNA_VERSION_PROBE_REMEDIATION}`,
{ command, executable, stdout: stdout.slice(0, 256) },
{ command, executable, stdout: probeOutput.stdout.slice(0, 256) },
);
let fingerprint: { readonly sha256: string; readonly bytes: number };
@@ -255,26 +397,24 @@ export const inspectKunaInstallation = async (
script?: boolean;
} = { phase: "fingerprint" };
try {
({ fingerprint, script } = await options.fileCloseResources.run(
async () => {
const fingerprint = await hashStableFile(executable, {
...(options.signal === undefined ? {} : { signal: options.signal }),
retainFailedClose: (owner) =>
options.fileCloseResources.retain(owner, executable),
});
observed.completed_hash = fingerprint;
assertRegularFileActive(options.signal);
observed.phase = "shebang";
const script = await startsWithShebang(
executable,
options.fileCloseResources,
options.signal,
);
observed.script = script;
assertRegularFileActive(options.signal);
return { fingerprint, script };
},
));
({ fingerprint, script } = await options.resourceScope.run(async () => {
const fingerprint = await hashStableFile(executable, {
...(options.signal === undefined ? {} : { signal: options.signal }),
retainFailedClose: (owner) =>
options.resourceScope.retain(owner, executable),
});
observed.completed_hash = fingerprint;
assertRegularFileActive(options.signal);
observed.phase = "shebang";
const script = await startsWithShebang(
executable,
options.resourceScope,
options.signal,
);
observed.script = script;
assertRegularFileActive(options.signal);
return { fingerprint, script };
}));
} catch (cause: unknown) {
const cancellation = regularFileCancellation(cause);
if (
@@ -332,7 +472,7 @@ export const inspectKunaInstallation = async (
const startsWithShebang = (
path: string,
fileCloseResources: FileCloseResourceOwner,
resourceScope: RetainedResourceScope,
signal?: AbortSignal,
): Promise<boolean> =>
withOwnedRegularFile(
@@ -340,7 +480,7 @@ const startsWithShebang = (
{
symlinks: "follow",
...(signal === undefined ? {} : { signal }),
retainFailedClose: (owner) => fileCloseResources.retain(owner, path),
retainFailedClose: (owner) => resourceScope.retain(owner, path),
},
async (handle) => {
const prefix = Buffer.alloc(2);
+54 -16
View File
@@ -19,6 +19,7 @@ import { RegularFileCleanupFailure } from "../filesystem/OwnedRegularFile.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import {
kunaFileCleanupError,
kunaRetainedResourceCleanupError,
type KunaProcessLauncher,
} from "./KunaCommand.js";
import {
@@ -26,7 +27,7 @@ import {
type KunaConfiguration,
} from "./KunaConfiguration.js";
import {
createKunaFileCloseScope,
createKunaResourceScope,
inspectKunaInstallation,
kunaInstallationCancellation,
} from "./KunaInstallation.js";
@@ -55,6 +56,7 @@ export class KunaProvider implements AnalysisProviderCandidate {
readonly #environment: Readonly<NodeJS.ProcessEnv>;
readonly #platform: NodeJS.Platform;
readonly #launcher: KunaProcessLauncher | undefined;
readonly #probeTimeoutMs: number | undefined;
readonly #singleFunctionRuns: number | undefined;
#cache: KunaProjectCache | undefined;
#runSlots: KunaRunSlots | undefined;
@@ -64,6 +66,8 @@ export class KunaProvider implements AnalysisProviderCandidate {
options: {
readonly platform?: NodeJS.Platform;
readonly launcher?: KunaProcessLauncher;
/** Test seam for bounded installation-probe lifecycle cases. */
readonly probeTimeoutMs?: number;
/** Test seam for foreground native runs; production derives it from the host. */
readonly singleFunctionRuns?: number;
} = {},
@@ -71,6 +75,7 @@ export class KunaProvider implements AnalysisProviderCandidate {
this.#platform = options.platform ?? process.platform;
this.#environment = snapshotEnvironment(environment, this.#platform);
this.#launcher = options.launcher;
this.#probeTimeoutMs = options.probeTimeoutMs;
this.#singleFunctionRuns = options.singleFunctionRuns;
}
@@ -175,40 +180,73 @@ export class KunaProvider implements AnalysisProviderCandidate {
}),
);
let installation: Awaited<ReturnType<typeof inspectKunaInstallation>>;
const fileCloseResources = options?.fileCloseResources;
if (fileCloseResources === undefined)
const resourceScope = options?.resourceScope;
if (resourceScope === undefined)
return err(
kunaUnavailable(
"kuna:profile",
"Kuna profile inspection requires a durable file resource owner",
"Kuna profile inspection requires a durable resource scope",
),
);
const fileCloseScope = createKunaFileCloseScope(fileCloseResources);
const kunaResources = createKunaResourceScope(resourceScope);
try {
installation = await inspectKunaInstallation(this.#environment, {
platform: this.#platform,
...(options?.signal === undefined ? {} : { signal: options.signal }),
fileCloseResources: fileCloseScope.owner,
resourceScope: kunaResources.owner,
...(this.#launcher === undefined
? {}
: { processLauncher: this.#launcher }),
...(this.#probeTimeoutMs === undefined
? {}
: { probeTimeoutMs: this.#probeTimeoutMs }),
});
} catch (cause: unknown) {
const retainedCleanup = kunaRetainedResourceCleanupError(
cause,
"kuna:profile",
);
if (retainedCleanup !== undefined) return err(retainedCleanup);
const cancellation = kunaInstallationCancellation(cause);
if (
!(cause instanceof RegularFileCleanupFailure) &&
cancellation !== undefined
)
return err(
new AnalysisCancelledError("kuna:profile", {
cause: cancellation.reason,
diagnostics: cancellation.diagnostics,
}),
);
) {
const error = new AnalysisCancelledError("kuna:profile", {
cause: cancellation.reason,
diagnostics: cancellation.diagnostics,
...(!kunaResources.hasPending
? {}
: {
cleanup: {
reason: "Kuna version-probe process cleanup is unconfirmed.",
resources: kunaResources.cleanupResources ?? [],
},
}),
});
kunaResources.bindRetainedFailure(error);
return err(error);
}
if (!(cause instanceof RegularFileCleanupFailure)) throw cause;
const error = kunaFileCleanupError(cause, "kuna:profile");
fileCloseScope.bindFailure(cause, error);
kunaResources.bindFailure(cause, error);
return err(error);
}
if (!installation.ok) {
const error = kunaUnavailable("open_binary", installation.error.reason, {
diagnostics: installation.error.diagnostics,
...(!kunaResources.hasPending
? {}
: {
cleanup: {
reason: "Kuna version-probe process cleanup is unconfirmed.",
resources: kunaResources.cleanupResources ?? [],
},
}),
});
kunaResources.bindRetainedFailure(error);
return err(error);
}
if (!installation.ok)
return err(kunaUnavailable("open_binary", installation.error.reason));
const { value } = installation;
return ok({
profile: createAnalysisProfile(
+49 -19
View File
@@ -7,7 +7,7 @@ import {
type AnalysisExecution,
type AnalysisOperation,
type ExecutionOptions,
type FileCloseResourceOwner,
type RetainedResourceScope,
} from "../application/AnalysisProvider.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
@@ -38,11 +38,12 @@ import { SharedStartupAttempt } from "../process/SharedStartupAttempt.js";
import {
KUNA_INVENTORY_OUTPUT_BYTES,
kunaFileCleanupError,
kunaRetainedResourceCleanupError,
type KunaProcessLauncher,
} from "./KunaCommand.js";
import { kunaFunctionDeadline } from "./KunaConfiguration.js";
import {
createKunaFileCloseScope,
createKunaResourceScope,
inspectKunaInstallation,
kunaInstallationCancellation,
type KunaInstallation,
@@ -236,7 +237,8 @@ export class KunaSessionClient implements AnalysisClient {
readonly #cache: KunaProjectCache;
readonly #environment: Readonly<NodeJS.ProcessEnv>;
readonly #runSlots: KunaRunSlots;
readonly #fileCloseResources = new ArtifactResourceScope();
readonly #launcher: KunaProcessLauncher | undefined;
readonly #resourceScope = new ArtifactResourceScope();
/** Single-function runs in flight, by entry address. */
readonly #singleFunctionRuns = new Map<string, SingleFunctionRun>();
/** Completed single-function texts by address, least recently used first. */
@@ -289,6 +291,7 @@ export class KunaSessionClient implements AnalysisClient {
this.#cache = dependencies.cache;
this.#runSlots = dependencies.runSlots;
this.#environment = dependencies.environment;
this.#launcher = dependencies.launcher;
this.#commands = new KunaTargetCommands(target, {
signal: this.#session.signal,
...(dependencies.launcher === undefined
@@ -450,7 +453,7 @@ export class KunaSessionClient implements AnalysisClient {
const commands = await this.#commands.close();
if (!commands.ok) failures.push(commands.error);
try {
await this.#fileCloseResources.close();
await this.#resourceScope.close();
} catch (cause: unknown) {
const observation = ArtifactReaderFailure.cleanupObservation(
cause,
@@ -1376,24 +1379,40 @@ export class KunaSessionClient implements AnalysisClient {
async #inspectInstallation(
signal: AbortSignal,
): Promise<Result<KunaInstallation, AnalysisError>> {
const parentFileCloseResources: FileCloseResourceOwner = {
const parentResourceScope: RetainedResourceScope = {
retain: (owner, resource) =>
this.#fileCloseResources.retain({
this.#resourceScope.retain({
kind: "lease",
resource,
lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
}),
run: <T>(operation: () => Promise<T>) =>
this.#fileCloseResources.run(operation),
this.#resourceScope.run(operation),
};
const fileCloseScope = createKunaFileCloseScope(parentFileCloseResources);
const kunaResources = createKunaResourceScope(parentResourceScope);
try {
const inspected = await inspectKunaInstallation(this.#environment, {
fileCloseResources: fileCloseScope.owner,
resourceScope: kunaResources.owner,
signal,
...(this.#launcher === undefined
? {}
: { processLauncher: this.#launcher }),
});
if (!inspected.ok)
return err(kunaUnavailable("health", inspected.error.reason));
if (!inspected.ok) {
const error = kunaUnavailable("health", inspected.error.reason, {
diagnostics: inspected.error.diagnostics,
...(!kunaResources.hasPending
? {}
: {
cleanup: {
reason: "Kuna version-probe process cleanup is unconfirmed.",
resources: kunaResources.cleanupResources ?? [],
},
}),
});
kunaResources.bindRetainedFailure(error);
return err(error);
}
const committed = this.#profile?.parameters["kuna_sha256"];
if (committed !== undefined && committed !== inspected.value.sha256)
return err(
@@ -1408,21 +1427,32 @@ export class KunaSessionClient implements AnalysisClient {
);
return ok(inspected.value);
} catch (cause: unknown) {
const retainedCleanup = kunaRetainedResourceCleanupError(cause, "health");
if (retainedCleanup !== undefined) return err(retainedCleanup);
const cancellation = kunaInstallationCancellation(cause);
if (
!(cause instanceof RegularFileCleanupFailure) &&
cancellation !== undefined
)
return err(
new AnalysisCancelledError("health", {
cause: cancellation.reason,
diagnostics: cancellation.diagnostics,
}),
);
) {
const error = new AnalysisCancelledError("health", {
cause: cancellation.reason,
diagnostics: cancellation.diagnostics,
...(!kunaResources.hasPending
? {}
: {
cleanup: {
reason: "Kuna version-probe process cleanup is unconfirmed.",
resources: kunaResources.cleanupResources ?? [],
},
}),
});
kunaResources.bindRetainedFailure(error);
return err(error);
}
if (!(cause instanceof RegularFileCleanupFailure))
return err(failure("health", cause));
const error = kunaFileCleanupError(cause, "health");
fileCloseScope.bindFailure(cause, error);
kunaResources.bindFailure(cause, error);
return err(error);
}
}
+3 -3
View File
@@ -8,7 +8,7 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type {
AnalysisClient,
ExecutionOptions,
FileCloseResourceOwner,
RetainedResourceScope,
} from "../application/AnalysisProvider.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
@@ -21,7 +21,7 @@ import { closeAnalysisClient } from "./AnalysisClientCleanup.js";
/** Own deferred client creation while callers wait independently and close joins it. */
export class AnalysisClientCreation {
readonly #inspectionResources = new ArtifactResourceScope();
readonly #inspectionOwner: FileCloseResourceOwner = {
readonly #inspectionOwner: RetainedResourceScope = {
retain: (owner, resource) =>
this.#inspectionResources.retain({
kind: "lease",
@@ -44,7 +44,7 @@ export class AnalysisClientCreation {
private readonly providerId: string,
private readonly create: (
signal: AbortSignal,
resourceOwner: FileCloseResourceOwner,
resourceOwner: RetainedResourceScope,
) => Promise<AnalysisClient>,
) {}
+2 -2
View File
@@ -1,6 +1,6 @@
import type {
AnalysisClient,
FileCloseResourceOwner,
RetainedResourceScope,
ProviderRuntimeLineageSnapshot,
ProviderRequestActivitySnapshot,
} from "../application/AnalysisProvider.js";
@@ -29,7 +29,7 @@ export class DeferredAnalysisClient implements AnalysisClient {
constructor(
loadClient: (
signal: AbortSignal,
resourceOwner: FileCloseResourceOwner,
resourceOwner: RetainedResourceScope,
) => Promise<AnalysisClient>,
providerId: string,
) {
+2 -2
View File
@@ -1,6 +1,6 @@
import { jsonValueSchema } from "../domain/jsonValue.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { FileCloseResourceOwner } from "../application/AnalysisProvider.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
@@ -9,7 +9,7 @@ import { OwnedCommandFailure } from "../process/OwnedCommand.js";
/** Transfer exact helper and command cleanup capabilities to the caller's scope. */
export const retainOwnedCommandCleanup = (
cause: unknown,
resourceOwner: FileCloseResourceOwner,
resourceOwner: RetainedResourceScope,
providerId: string,
operation: string,
): readonly AnalysisError[] => {