Files
reverse-engineering-anything/src/domain/debuggerSessionErrors.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

150 lines
5.7 KiB
TypeScript

import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
} from "./analysisErrorCore.js";
/** Tool names and wording for one persistent debugger's session errors. */
export interface DebuggerSessionTools {
readonly providerId: string;
readonly name: string;
readonly start: string;
readonly close: string;
}
/** A session_id this server does not hold, unlike a retained stopped session. */
export const unknownDebuggerSessionError = (
tools: DebuggerSessionTools,
operation: string,
): AnalysisInputError =>
new AnalysisInputError(
operation,
{
conformsToInputContract: true,
userMessage: `No ${tools.name} debug session has this session_id in this REA server.`,
remediationAction: `Use a session_id that ${tools.start} returned in this server process; ${tools.close} releases a session's ID. Call ${tools.start} to begin a new session.`,
},
[
{
path: ["session_id"],
reason: "invalid_value",
message: `No ${tools.name} debug session has this session_id in this REA server.`,
},
],
);
/**
* Why a retained debugger session accepts no more commands:
* - `input-stream-failure`: the debugger's stdin closed, errored or refused a write.
* - `output-correlation-failure`: debugger output could no longer be attributed
* to one command, such as an oversized or invalid record or a missing marker.
* - `command-deadline` / `command-cancelled`: a command's deadline or caller
* cancellation stopped the session, because late output could not be correlated.
* - `server-shutdown`: REA is closing every session.
* - `close-requested`: the close tool started releasing this session.
* - `process-exited`: the debugger process exited.
* - `stopped`: REA stopped the session for another reason.
*/
export const DEBUGGER_SESSION_STOP_CODES = [
"input-stream-failure",
"output-correlation-failure",
"command-deadline",
"command-cancelled",
"server-shutdown",
"close-requested",
"process-exited",
"stopped",
] as const;
export type DebuggerSessionStopCode =
(typeof DEBUGGER_SESSION_STOP_CODES)[number];
/** A stopped session's reason code and its explanation. */
export interface DebuggerSessionStop {
readonly code: DebuggerSessionStopCode;
readonly reason: string;
}
/**
* Refuse a command on a retained session that stopped, naming why it stopped.
* The code projects as `details.diagnostics.session_stop`.
*/
export const stoppedDebuggerSessionError = (
tools: DebuggerSessionTools,
operation: string,
stop: DebuggerSessionStop,
): AnalysisCapabilityUnavailableError =>
new AnalysisCapabilityUnavailableError(
tools.providerId,
operation,
stop.reason,
{
diagnostics: { session_stop: stop.code },
userMessage: `The ${tools.name} debug session stopped and accepts no more commands. ${stop.reason}`,
remediationAction: `Call ${tools.close} with this session_id to release the stopped session, then call ${tools.start} to begin a new one. Earlier commands may have changed the target, so confirm their effects before repeating them.`,
},
);
/**
* Why REA could not confirm an owned debugger process stopped, so it retains
* the session for cleanup retry:
* - `output-unsettled`: the process leader exited, but inherited output
* streams (or the Windows Job Object) did not settle or could not be checked.
* - `detach-pending`: an inferior detach was still running when the debugger exited.
* - `inferior-disposition-unverified`: the debugger exited before the inferior
* was detached or confirmed absent, and no owner proof shows it ended.
* - `inferior-identity-unverified`: the inferior's process identity could not
* be read after the debugger exited.
* - `windows-stop-unsafe`: stopping the debugger on Windows could also end its inferior.
* - `detach-unsupported`: the provider has no detach capability.
* - `detach-timeout`: detach did not complete within its fixed allowance.
* - `detach-unconfirmed`: the provider confirmed neither no inferior nor a
* detach with a durable output sink.
* - `inferior-state-unknown`: the debugger could not report a complete,
* synchronized inferior list.
* - `multiple-inferiors`: automatic detach supports only one inferior.
* - `no-durable-output-sink`: no durable inferior output sink was verified, so
* detaching the live inferior is refused.
* - `inferior-tty-changed`: the debugger no longer reports the caller-selected inferior TTY.
* - `detach-failed`: the detach request failed or was not confirmed.
* - `process-did-not-exit`: the debugger did not exit after direct termination.
* - `stop-failed`: the stop attempt itself failed.
*/
export const DEBUGGER_CLEANUP_INCOMPLETE_CODES = [
"output-unsettled",
"detach-pending",
"inferior-disposition-unverified",
"inferior-identity-unverified",
"windows-stop-unsafe",
"detach-unsupported",
"detach-timeout",
"detach-unconfirmed",
"inferior-state-unknown",
"multiple-inferiors",
"no-durable-output-sink",
"inferior-tty-changed",
"detach-failed",
"process-did-not-exit",
"stop-failed",
] as const;
export type DebuggerCleanupIncompleteCode =
(typeof DEBUGGER_CLEANUP_INCOMPLETE_CODES)[number];
/** A debugger stop REA could not confirm: its code and explanation. */
export interface DebuggerCleanupIncomplete {
readonly code: DebuggerCleanupIncompleteCode;
readonly reason: string;
}
export const RIZIN_DEBUG_SESSION_TOOLS = {
providerId: "rizin",
name: "Rizin",
start: "start_rizin_debug_session",
close: "close_rizin_debug_session",
} as const satisfies DebuggerSessionTools;
export const GDB_SESSION_TOOLS = {
providerId: "gdb",
name: "GDB",
start: "start_gdb_session",
close: "close_gdb_session",
} as const satisfies DebuggerSessionTools;