Files
reverse-engineering-anything/src/process/ownedDebuggerCleanupError.ts
T
morluto ff6467ca97 feat(debuggers): name why an owned debugger stop is incomplete (#11517)
* feat(debuggers): name why an owned debugger stop is incomplete

Owned debugger stop results carry a cleanup code; retained Rizin and GDB
cleanup failures project it as details.diagnostics.debugger_cleanup, close-all
failures carry it, and GDB detach refusals name multiple inferiors, a missing
durable output sink, unknown inferior state or a changed inferior TTY.
GdbSessionManagerCoverage asserts the codes instead of reason prose.

* fix(debuggers): put the cleanup code on every returned failure

incompleteStopFacts builds the cleanup observation and debugger_cleanup
diagnostic together, so GDB startup, cancellation and timeout failures carry
the code; Rizin's composed cleanup failure retains it at its top level; and
one-shot debug commands report debugger_cleanup_codes from the close-all
failure.
2026-11-16 07:33:16 +08:00

89 lines
3.1 KiB
TypeScript

import type {
DebuggerCleanupIncomplete,
DebuggerCleanupIncompleteCode,
} from "../domain/debuggerSessionErrors.js";
/** Closing all sessions could not confirm that these debuggers stopped. */
export class OwnedDebuggerCleanupError extends AggregateError {
/** Process IDs when cleanup gave up. Observations, not lasting proof of identity. */
readonly retainedProcessIds: readonly number[];
constructor(
failures: readonly Error[],
message: string,
retainedProcessIds: readonly number[],
) {
super(failures, message);
this.retainedProcessIds = retainedProcessIds;
}
}
/** One owned debugger whose stop could not be confirmed, naming why. */
export class OwnedDebuggerStopFailure extends Error {
readonly code: DebuggerCleanupIncompleteCode;
constructor(stop: DebuggerCleanupIncomplete) {
super(stop.reason);
this.name = "OwnedDebuggerStopFailure";
this.code = stop.code;
}
}
/** Visit every error in a composed cleanup failure once. */
const visitCleanupFailure = (
cause: unknown,
onError: (error: Error) => void,
): void => {
const visited = new WeakSet<object>();
const visit = (node: unknown): void => {
if (typeof node !== "object" || node === null || visited.has(node)) return;
visited.add(node);
if (node instanceof Error) onError(node);
if (node instanceof AggregateError)
for (const error of node.errors) visit(error);
if (node instanceof Error) visit(node.cause);
};
visit(cause);
};
/** Retained debugger process IDs anywhere in a composed cleanup failure. */
export const retainedDebuggerProcessIds = (
cause: unknown,
): readonly number[] => {
const found = new Set<number>();
visitCleanupFailure(cause, (error) => {
if (error instanceof OwnedDebuggerCleanupError)
for (const pid of error.retainedProcessIds) found.add(pid);
});
return [...found];
};
/** Why each unconfirmed debugger stop in a composed cleanup failure is incomplete. */
export const debuggerCleanupCodes = (
cause: unknown,
): readonly DebuggerCleanupIncompleteCode[] => {
const found = new Set<DebuggerCleanupIncompleteCode>();
visitCleanupFailure(cause, (error) => {
if (error instanceof OwnedDebuggerStopFailure) found.add(error.code);
});
return [...found];
};
/** Log or diagnostic fields naming those processes; empty when none are known. */
export const retainedDebuggerDiagnostics = (
cause: unknown,
): {
readonly retained_debugger_pids?: number[];
readonly debugger_cleanup_codes?: DebuggerCleanupIncompleteCode[];
} => {
const pids = retainedDebuggerProcessIds(cause);
const codes = debuggerCleanupCodes(cause);
return {
...(pids.length === 0 ? {} : { retained_debugger_pids: [...pids] }),
...(codes.length === 0 ? {} : { debugger_cleanup_codes: [...codes] }),
};
};
/** What a caller must do once REA ends with these debuggers unconfirmed. */
export const retainedDebuggerRemediation = (pids: readonly number[]): string =>
`REA exits without confirming that the debugger stopped, and no later REA command can retry this cleanup. Check process ${pids.join(", ")} and its target, and stop them if they are still running.`;