// No imports at all: this module is evaluated before anything a crash guard // protects, so it must not load `effect` or any other package at runtime. /** * The slice of the host process {@link ProcessGuard.run} uses. Node's * `process` satisfies it. * * @remarks * Structural on purpose: the guard never reads a global, so a test passes a * double and a front end passes `process` from its own `main`. * * @public */ export interface ProcessGuardHost { /** Register the `uncaughtException` listener. */ on(event: "uncaughtException", listener: (error: Error, origin: string) => void): unknown; /** Register the `unhandledRejection` listener. */ on(event: "unhandledRejection", listener: (reason: unknown) => void): unknown; /** Raise an `uncaughtException` to the registered listeners. Used only by {@link ProcessGuardOptions.injectCrash}. */ emit(event: "uncaughtException", error: Error, origin: "uncaughtException" | "unhandledRejection"): unknown; /** Raise an `unhandledRejection` to the registered listeners. Used only by {@link ProcessGuardOptions.injectCrash}. */ emit(event: "unhandledRejection", reason: unknown, promise: Promise): unknown; /** Where every guard report is written. For a stdio server, never stdout: that is the protocol wire. */ readonly stderr: { write(chunk: string): unknown }; /** End the process at once. */ exit(code?: number): never; } /** * When a stray exception or rejection ends the process. * * @remarks * `"exit"` exits 1 whenever it happens. `"exitBeforeConnect"` exits 1 until * the caller reports the server connected with * {@link ProcessGuardControl.markConnected}, then logs and keeps serving: a * server that dies mid-session drops every client attached to it. `"log"` * never exits. * * @public */ export interface ProcessGuardPolicy { /** For `uncaughtException`. */ readonly onUncaught: "exit" | "exitBeforeConnect"; /** For `unhandledRejection`. Defaults to `"exit"`. */ readonly onRejection?: "exit" | "exitBeforeConnect" | "log" | undefined; } /** * One crash {@link ProcessGuardOptions.injectCrash} raises: which event, and * when. * * @public */ export interface ProcessGuardInjection { /** `"load"`: before `load` is called. `"connected"`: after the first {@link ProcessGuardControl.markConnected}. */ readonly at: "load" | "connected"; /** Which event to raise. */ readonly kind: "uncaughtException" | "unhandledRejection"; } /** * What {@link ProcessGuardOptions.load} is handed: the two moments only the * caller can see. * * @remarks * Plain callbacks, so a caller with no Effect runtime (a * `vscode-languageserver` server, a hand-written socket loop) uses them the * same way an Effect launcher does: an MCP launcher passes `markConnected` * to `McpStdio.launch`'s `onReady`; an LSP calls it once its connection is * listening. * * @public */ export interface ProcessGuardControl { /** * Report the server connected: from here on `"exitBeforeConnect"` logs and * keeps going. Call it once the server is serving. Later calls do nothing. * Safe to call after `load` has resolved, which is the usual case. * * @remarks * For a server framed over stdio (MCP, LSP), "serving" is the moment its * transport is built and reading stdin, before the first request arrives: * from then on a client is attached, and a stray error should be logged, * not end the session. */ readonly markConnected: () => void; /** * Format every report from here on with `format`, in place of the guard's * own dependency-free formatter. A `format` that throws falls back to the * guard's own, so a broken formatter never hides a crash. */ readonly useFormat: (format: (error: unknown) => string) => void; } /** * Options for {@link ProcessGuard.run}. * * @public */ export interface ProcessGuardOptions { /** Prefixes every report the guard writes, as in `my-server: uncaughtException (…): …`. */ readonly label: string; /** The process: pass `process`. */ readonly host: ProcessGuardHost; /** Defaults to `{ onUncaught: "exit", onRejection: "exit" }`. */ readonly policy?: ProcessGuardPolicy | undefined; /** * Import, assemble and start the server. Everything that can throw while * loading belongs here, behind a dynamic `import()`, so the guards are * already listening when it runs. A rejection is reported as * `startup failed` and exits 1, whatever the policy. */ readonly load: (guard: ProcessGuardControl) => Promise; /** * For a test of the guards themselves: raise one stray `kind` at `at`, so * both halves of a policy can be driven end to end in a real process. * * @remarks * - `"load"` raises it once both listeners are installed and before * `load` is called, then waits for the guard to handle it: `load` is * not called until the listener has run. If a test double's `exit` * throws instead of ending the process, `run` rejects with what it * threw and never calls `load`. The pre-connect half of the policy * applies, so `"exitBeforeConnect"` exits 1 here, and only an * `onRejection` of `"log"` lets the process go on to load and serve. * The report uses the guard's own formatter, since no `useFormat` has * run yet. * - `"connected"` raises it after the first `markConnected`, where * `"exitBeforeConnect"` logs and keeps serving. It is never raised if * `markConnected` is never called. A throw from a test double's `exit` * there is dropped. * * **The `"connected"` report is asynchronous.** It is raised on a later * tick, a `setTimeout(0)` after `markConnected`, so it can land after the * first responses the server sends: a test that reads stderr once, right * after its first response, can see nothing. Wait for the report (with * `McpProcess.stderrUntil` from `@effected/mcp-kit/testing`, for an MCP * server) rather than reading it once. * * Either is raised only through `host.emit`, on a `setTimeout(0)` tick, * never as a real throw or rejection, so the guard's listeners handle it * the same way under the real `process` and under a test double. Under * `process`, every listener registered for the event sees it, not only * the guard's. It carries an `[injected]` message; a rejection is emitted * with an already-handled rejected promise. `undefined`, or an `at` or * `kind` outside these values, does nothing at all. Wire it to an * environment variable only a test sets. */ readonly injectCrash?: ProcessGuardInjection | undefined; } type InjectedKind = ProcessGuardInjection["kind"]; const isInjectedKind = (kind: unknown): kind is InjectedKind => kind === "uncaughtException" || kind === "unhandledRejection"; const INJECT_AT: ReadonlyArray = ["load", "connected"]; const INJECT_KIND: ReadonlyArray = ["uncaughtException", "unhandledRejection"]; /** Emit one injected crash through the host, to the listeners the guard installed there. */ const emitInjected = (host: ProcessGuardHost, kind: InjectedKind): void => { const error = new Error(`[injected] ${kind}`); if (kind === "uncaughtException") { host.emit("uncaughtException", error, "uncaughtException"); return; } const promise = Promise.reject(error); // Handled, so only the emitted event reaches a listener, never a real unhandled rejection. promise.catch(() => undefined); host.emit("unhandledRejection", error, promise); }; const fallbackFormat = (error: unknown): string => error instanceof Error ? (error.stack ?? error.message) : String(error); /** * Transport-neutral crash guards for a server process, installed before the * server's module graph loads. Imported from `@effected/kit/guard`. * * @remarks * {@link ProcessGuard.run} registers `uncaughtException` and * `unhandledRejection` listeners on `host`, then awaits `load`. It launches * nothing itself: `load` starts the server, over whatever transport, and * calls `markConnected` once it is serving. `@effected/mcp-kit/guard`'s * `McpGuard.run` is this guard with an MCP stdio launch in its `load`. * * - This entrypoint has no runtime import at all, so a throw while the * server graph evaluates is still reported on stderr. * - A `load` that rejects is reported as `startup failed` and exits 1 * whatever the policy. Left to a log-only rejection listener, it would let * the event loop drain and exit 0 with no server. * - Installing an `unhandledRejection` listener switches off Node's default * of throwing on one, so `"log"` really does keep the process running. * - An exit from a guard skips every finalizer the server registered. * - Every report is one line: `