diff --git a/.changeset/everything-evict-idle-sessions.md b/.changeset/everything-evict-idle-sessions.md new file mode 100644 index 0000000000..e8fca08a5c --- /dev/null +++ b/.changeset/everything-evict-idle-sessions.md @@ -0,0 +1,5 @@ +--- +"@modelcontextprotocol/server-everything": minor +--- + +The Streamable HTTP transport now evicts a 2025-era session that has been idle for 30 minutes: one with no request in flight and no stream open. Until now a session whose client never sent a DELETE stayed in memory, with its server instance, for the life of the process. An evicted session's next request is answered `404 Session not found`, the spec's signal for the client to initialize again. Set the new `SESSION_IDLE_TIMEOUT_MILLIS` environment variable to change the timeout, or to `0` to keep sessions until their client ends them. 2026-07-28 clients have no sessions and are unaffected. Thanks to [Pierpaolo1223](https://github.com/Pierpaolo1223) for the report and the measurements in [#5558](https://github.com/modelcontextprotocol/servers/issues/5558). diff --git a/src/everything/README.md b/src/everything/README.md index 0d597af143..2258954702 100644 --- a/src/everything/README.md +++ b/src/everything/README.md @@ -133,6 +133,9 @@ Both HTTP transports (Streamable HTTP and HTTP+SSE) listen on the loopback inter | --- | --- | --- | | `PORT` | `3001` | The port the HTTP transport listens on | | `HOST` | `127.0.0.1` | The address it binds; `0.0.0.0` (or `::`) for every interface | +| `SESSION_IDLE_TIMEOUT_MILLIS` | `1800000` (30 minutes) | Streamable HTTP only: how long a 2025-era session may sit idle before the server ends it; `0` never ends one | + +A 2025-era Streamable HTTP session normally ends when its client sends a `DELETE`. One whose client goes away without doing so is ended by the server once it has been idle for `SESSION_IDLE_TIMEOUT_MILLIS`: its server instance is closed and its timers and subscriptions are released. Idle means no request in flight and no stream open, so a client that keeps its `GET` stream open, or is waiting on a long tool call, is never timed out; the clock starts when the session's last response closes, and idle sessions are looked for every tenth of the timeout (no less than a second and no more than a minute apart), so one is ended that much late at most. A request for a session the server has ended is answered `404 Not Found` (`Session not found`), which is the [specification's signal](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) for the client to start a new session with a fresh `initialize`. Set a short timeout to exercise that path in a client under test, or `0` to keep every session until its client ends it. A value that is not a non-negative number is ignored in favor of the default. 2026-07-28 clients have no sessions, and an HTTP+SSE session ends when its stream's connection closes, so neither is affected. Both HTTP transports (Streamable HTTP and HTTP+SSE) accept browser requests only from a localhost origin: an `Origin` header whose host is `localhost`, `127.0.0.1` or `[::1]`, on any port, such as the MCP Inspector's. A request carrying any other `Origin` is refused with `403 Forbidden`. Clients that send no `Origin` header, which is every non-browser client, are unaffected. diff --git a/src/everything/__tests__/idle-sessions.test.ts b/src/everything/__tests__/idle-sessions.test.ts new file mode 100644 index 0000000000..b4729891ef --- /dev/null +++ b/src/everything/__tests__/idle-sessions.test.ts @@ -0,0 +1,180 @@ +/** + * The timing of idle-session eviction (#5558), with fake timers and no HTTP: + * what `SESSION_IDLE_TIMEOUT_MILLIS` is read as, that a session is evicted + * once, only after it has had no open response for the timeout, and that a + * timeout of 0 and `stop()` both end the watching. A response is an + * `EventEmitter` here, since "close" is all the module listens for. What + * eviction does to a real session is in `streamable-http.test.ts`. + */ +import { EventEmitter } from "node:events"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { + DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS, + sessionIdleTimeoutMillis, + watchIdleSessions, +} from "../transports/idle-sessions.js"; + +describe("sessionIdleTimeoutMillis", () => { + afterEach(() => { + vi.unstubAllEnvs(); + }); + + it("defaults to 30 minutes", () => { + expect(DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS).toBe(1_800_000); + expect(sessionIdleTimeoutMillis(undefined)).toBe(1_800_000); + }); + + it("reads SESSION_IDLE_TIMEOUT_MILLIS from the environment", () => { + vi.stubEnv("SESSION_IDLE_TIMEOUT_MILLIS", "5000"); + expect(sessionIdleTimeoutMillis()).toBe(5000); + }); + + it("takes a number of milliseconds, and 0 as disabled", () => { + expect(sessionIdleTimeoutMillis("60000")).toBe(60_000); + expect(sessionIdleTimeoutMillis(" 250 ")).toBe(250); + expect(sessionIdleTimeoutMillis("0")).toBe(0); + }); + + it.each(["", " ", "-1", "soon", "Infinity"])( + "falls back to the default for %j", + (value) => { + expect(sessionIdleTimeoutMillis(value)).toBe( + DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS, + ); + }, + ); +}); + +describe("watchIdleSessions", () => { + beforeEach(() => { + vi.useFakeTimers(); + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it("evicts a session once, after it has been idle for the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + vi.advanceTimersByTime(4999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + vi.advanceTimersByTime(60_000); + expect(evict).toHaveBeenCalledOnce(); + idle.stop(); + }); + + it("keeps a session with an open response, and times it from when the response closes", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("active"); + idle.add("abandoned"); + const stream = new EventEmitter(); + const call = new EventEmitter(); + idle.hold("active", stream); + idle.hold("active", call); + vi.advanceTimersByTime(5000); + expect(evict).toHaveBeenCalledExactlyOnceWith("abandoned"); + + // One of two responses closing leaves the session in use. + call.emit("close"); + vi.advanceTimersByTime(60_000); + expect(evict).toHaveBeenCalledOnce(); + + // The clock starts when the last one closes, not when it opened. + stream.emit("close"); + vi.advanceTimersByTime(4999); + expect(evict).toHaveBeenCalledOnce(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenLastCalledWith("active"); + expect(evict).toHaveBeenCalledTimes(2); + idle.stop(); + }); + + it("restarts a session's clock on each request", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + for (let i = 0; i < 4; i++) { + vi.advanceTimersByTime(4000); + const res = new EventEmitter(); + idle.hold("a", res); + res.emit("close"); + } + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("does not evict a session that was removed, or hold one it does not watch", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("ended"); + idle.remove("ended"); + const res = new EventEmitter(); + idle.hold("unknown", res); + expect(res.listenerCount("close")).toBe(0); + vi.advanceTimersByTime(60_000); + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("looks for idle sessions every tenth of the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(50_000, evict); + // Idle from 2 s in: past the timeout at 52 s, and seen at the 55 s look. + vi.advanceTimersByTime(2000); + idle.add("a"); + vi.advanceTimersByTime(52_999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("looks at least every minute, however long the timeout", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(30 * 60_000, evict); + vi.advanceTimersByTime(60_000); + idle.add("a"); + // Idle from 1:00, so past the timeout at 31:00, the next look. + vi.advanceTimersByTime(30 * 60_000 - 1); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("looks no more often than once a second when the timeout is shorter", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(10, evict); + idle.add("a"); + vi.advanceTimersByTime(999); + expect(evict).not.toHaveBeenCalled(); + vi.advanceTimersByTime(1); + expect(evict).toHaveBeenCalledExactlyOnceWith("a"); + idle.stop(); + }); + + it("never evicts, and runs no timer, when the timeout is 0", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(0, evict); + expect(vi.getTimerCount()).toBe(0); + idle.add("a"); + vi.advanceTimersByTime(24 * 60 * 60 * 1000); + expect(evict).not.toHaveBeenCalled(); + idle.stop(); + }); + + it("stops looking once stopped", () => { + const evict = vi.fn(); + const idle = watchIdleSessions(5000, evict); + idle.add("a"); + idle.stop(); + expect(vi.getTimerCount()).toBe(0); + vi.advanceTimersByTime(60_000); + expect(evict).not.toHaveBeenCalled(); + }); +}); diff --git a/src/everything/__tests__/streamable-http.test.ts b/src/everything/__tests__/streamable-http.test.ts index 7a4043654a..61bd68f883 100644 --- a/src/everything/__tests__/streamable-http.test.ts +++ b/src/everything/__tests__/streamable-http.test.ts @@ -18,6 +18,13 @@ * A browser request is served only from a localhost origin: the tests pin * that a foreign `Origin` is refused with a 403 and no CORS grant at every * route, preflights included, and that a localhost one is served. + * + * A 2025-era session left idle is evicted (#5558): the "idle sessions" block + * serves an app with a five-second idle timeout and moves a fake clock past + * it (only `setInterval` and `Date` are faked, so the HTTP round trips stay + * real), pinning that the abandoned session is closed, cleaned up and then + * answered 404 while one with an open stream is left alone. The timing rules + * themselves are in `idle-sessions.test.ts`. */ import type { Server } from "node:http"; import { once } from "node:events"; @@ -604,6 +611,156 @@ describe("shutdown", () => { }); }); +describe("idle sessions (#5558)", () => { + const IDLE = 5000; + const ping = { jsonrpc: "2.0", id: 7, method: "ping" }; + + /** Replace the default app with one whose sessions idle out after `timeout`. */ + async function serveWithIdleTimeout(timeout: number) { + await new Promise((resolve) => http.close(resolve)); + vi.useFakeTimers({ toFake: ["setInterval", "clearInterval", "Date"] }); + app = createApp({ sessionIdleTimeoutMillis: timeout }); + http = app.app.listen(0, "127.0.0.1"); + await once(http, "listening"); + const address = http.address(); + if (address === null || typeof address === "string") + throw new Error("no port"); + mcp = `http://127.0.0.1:${address.port}/mcp`; + } + + afterEach(() => { + vi.useRealTimers(); + }); + + it("evicts an abandoned session and releases what it held, leaving one with an open stream alone", async () => { + await serveWithIdleTimeout(IDLE); + const timers = vi.getTimerCount(); + + // The abandoned session starts a timer of its own, then goes quiet. + const abandoned = await rawInitialize(); + const toggled = await post( + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { name: "toggle-simulated-logging", arguments: {} }, + }, + abandoned.sessionId, + ); + await toggled.text(); + expect(vi.getTimerCount()).toBe(timers + 1); + + // The active session keeps its standalone stream open and sends nothing. + const active = await rawInitialize(); + const controller = new AbortController(); + const stream = await fetch(mcp, { + headers: { + accept: "text/event-stream", + "mcp-session-id": active.sessionId, + "mcp-protocol-version": "2025-11-25", + }, + signal: controller.signal, + }); + expect(stream.status).toBe(200); + const timersBeforeEviction = vi.getTimerCount(); + + vi.advanceTimersByTime(IDLE); + await vi.waitFor(() => + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${abandoned.sessionId}, removing from transports map`, + ), + ); + expect(log).toHaveBeenCalledWith( + `Session ${abandoned.sessionId} idle for ${IDLE} ms, closing it`, + ); + // Its cleanup ran: the simulated-logging timer is gone. + expect(vi.getTimerCount()).toBe(timersBeforeEviction - 1); + const evicted = await post(ping, abandoned.sessionId); + expect(evicted.status).toBe(404); + expect(await evicted.json()).toEqual({ ...SESSION_NOT_FOUND, id: 7 }); + + // The session with the open stream was idle just as long, and is served. + const kept = await post(ping, active.sessionId); + expect(kept.status).toBe(200); + await kept.text(); + expect(log).not.toHaveBeenCalledWith( + `Session ${active.sessionId} idle for ${IDLE} ms, closing it`, + ); + + // Once its stream closes it is idle too, and is evicted in its turn. + controller.abort(); + await vi.waitFor(() => { + vi.advanceTimersByTime(IDLE); + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${active.sessionId}, removing from transports map`, + ); + }); + expect((await post(ping, active.sessionId)).status).toBe(404); + }); + + it("keeps a session that is still being used", async () => { + await serveWithIdleTimeout(IDLE); + const { sessionId } = await rawInitialize(); + for (let i = 0; i < 3; i++) { + vi.advanceTimersByTime(IDLE - 1000); + const response = await post(ping, sessionId); + expect(response.status).toBe(200); + await response.text(); + } + expect(log).not.toHaveBeenCalledWith( + `Session ${sessionId} idle for ${IDLE} ms, closing it`, + ); + }); + + it("evicts nothing when the timeout is 0", async () => { + await serveWithIdleTimeout(0); + expect(vi.getTimerCount()).toBe(0); + const { sessionId } = await rawInitialize(); + vi.advanceTimersByTime(24 * 60 * 60 * 1000); + const response = await post(ping, sessionId); + expect(response.status).toBe(200); + await response.text(); + }); + + it("logs an idle session that fails to close, and evicts it at a later look", async () => { + await serveWithIdleTimeout(IDLE); + const { sessionId } = await rawInitialize(); + const failure = new Error("close failed"); + vi.spyOn( + NodeStreamableHTTPServerTransport.prototype, + "close", + ).mockRejectedValueOnce(failure); + vi.advanceTimersByTime(IDLE); + await vi.waitFor(() => + expect(log).toHaveBeenCalledWith( + `Error closing idle session ${sessionId}:`, + failure, + ), + ); + // The failed close left the session in place, and still served. + const held = await post(ping, sessionId); + expect(held.status).toBe(200); + await held.text(); + + // It is watched again, so the next timeout closes it for real. + await vi.waitFor(() => { + vi.advanceTimersByTime(IDLE); + expect(log).toHaveBeenCalledWith( + `Transport closed for session ${sessionId}, removing from transports map`, + ); + }); + expect((await post(ping, sessionId)).status).toBe(404); + }); + + it("stops looking for idle sessions on shutdown", async () => { + vi.spyOn(process, "exit").mockImplementation(() => undefined as never); + await serveWithIdleTimeout(IDLE); + expect(vi.getTimerCount()).toBe(1); + await app.shutdown(); + expect(vi.getTimerCount()).toBe(0); + }); +}); + describe("startStreamableHttpServer", () => { afterEach(() => { vi.doUnmock("../transports/listen.js"); diff --git a/src/everything/docs/startup.md b/src/everything/docs/startup.md index e93a85577b..bc0f6ba40a 100644 --- a/src/everything/docs/startup.md +++ b/src/everything/docs/startup.md @@ -34,6 +34,7 @@ - **Streamable HTTP**: one `/mcp` endpoint for both eras. - **2026-07-28**: a session-less **POST** carrying the per-request `_meta` envelope is served by the SDK's `createMcpHandler`, which builds a fresh server per request with `createServer({ era: "modern", publish })`. There are no sessions. Change notifications are published on the handler's subscription bus (`publish`), which reaches every open `subscriptions/listen` stream. - **2025 era**: everything else, classified by the SDK's `isLegacyRequest`, keeps the sessionful wiring: a server per session, created on the `initialize` **POST**, with **GET** for the standalone SSE stream and **DELETE** to end the session. Transports are stored by `sessionId`, an event store makes streams resumable, and the session's `cleanup()` runs when it closes. Sessionful serving keeps the server-to-client channel the legacy shim needs for elicitation, sampling and roots. + - A 2025-era session with no request in flight and no stream open for `SESSION_IDLE_TIMEOUT_MILLIS` (default 30 minutes; `0` disables it) is closed by the server, as if its client had sent the DELETE; its next request is answered `404`. - A session-less POST's body is parsed once (up to 4 MiB) to classify it and serve it. - **SSE** and **Streamable HTTP** bind their port (`PORT`, default `3001`) through `listenOrExit()` in `transports/listen.ts`. - The listening line is printed only once the port is bound. diff --git a/src/everything/docs/structure.md b/src/everything/docs/structure.md index 440702593f..a8a3601f4e 100644 --- a/src/everything/docs/structure.md +++ b/src/everything/docs/structure.md @@ -68,6 +68,7 @@ src/everything │ ├── trigger-sampling-request.ts │ └── trigger-url-elicitation.ts └── transports + ├── idle-sessions.ts ├── in-memory-event-store.ts ├── listen.ts ├── sse.ts @@ -228,6 +229,9 @@ src/everything ### `transports/` +- `idle-sessions.ts` + - `watchIdleSessions(timeoutMillis, evict)`: decides when a 2025-era Streamable HTTP session has been idle too long. A request counts as activity until its response closes, so an open stream or a running call keeps its session; `evict` is called once for a session with no open response for the timeout. + - `sessionIdleTimeoutMillis()`: reads `SESSION_IDLE_TIMEOUT_MILLIS` (default 30 minutes; `0` disables eviction). - `in-memory-event-store.ts` - `InMemoryEventStore`: the Streamable HTTP transport's event store for resumability. Replays only the events of the stream a `Last-Event-ID` belongs to, and reports an unknown event ID as having no stream, so the SDK refuses the resume. - `listen.ts` @@ -250,4 +254,5 @@ src/everything - 2025 era: POST (JSON‑RPC), GET (SSE stream), and DELETE (session termination) using `NodeStreamableHTTPServerTransport` from `@modelcontextprotocol/node`. - Uses an `InMemoryEventStore` for resumable sessions and tracks transports by `sessionId`. - Answers a request for an unknown or ended `Mcp-Session-Id` with `404 Not Found`, and closes every open session on `SIGINT`. + - Closes a session that has been idle for `SESSION_IDLE_TIMEOUT_MILLIS` (`idle-sessions.ts`), which removes it and runs its `cleanup()` as a DELETE does. - Connects a fresh server instance on initialization POST and reuses the transport for subsequent requests. diff --git a/src/everything/transports/idle-sessions.ts b/src/everything/transports/idle-sessions.ts new file mode 100644 index 0000000000..930455a61e --- /dev/null +++ b/src/everything/transports/idle-sessions.ts @@ -0,0 +1,128 @@ +// Idle-session eviction for the Streamable HTTP transport's 2025-era sessions +// (#5558). +// +// A 2025-era session holds a server instance, a transport and an event store +// until its client ends it with a DELETE. A client that initializes and then +// goes away never does, so without this every abandoned session stayed in +// memory for the life of the process. The spec lets a server end a session at +// any time, after which it answers that session id with 404 and the client +// starts a new one, so an idle session is closed after a timeout. +// +// "Idle" means no request in flight and no stream open: every request served +// for a session is held as activity until its response closes, so a session +// with an open SSE stream, or a tool call still running, is never evicted +// however long it has been quiet. The clock starts when the last response +// closes. +// +// This module only decides when; the transport manager supplies what evicting +// means (closing the session's transport). It is kept apart from +// `streamableHttp.ts` so the timing can be tested with fake timers and no +// HTTP. The HTTP+SSE transport needs none of this: its session is its +// `GET /sse` stream, and it is cleaned up when that stream's socket closes. + +/** How long a session may sit idle before it is evicted, by default: 30 minutes. */ +export const DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS = 30 * 60 * 1000; + +/** + * Idle sessions are looked for every tenth of the timeout, so one is evicted + * at most a tenth late, but no less often than this ... + */ +const MAX_SWEEP_INTERVAL_MILLIS = 60 * 1000; + +/** ... and no more often than this, however short the timeout. */ +const MIN_SWEEP_INTERVAL_MILLIS = 1000; + +/** + * The idle timeout `SESSION_IDLE_TIMEOUT_MILLIS` asks for, in milliseconds: + * `0` disables eviction, and anything that is not a non-negative number + * (unset, empty, negative, not a number) means the default. + */ +export function sessionIdleTimeoutMillis( + value: string | undefined = process.env.SESSION_IDLE_TIMEOUT_MILLIS, +): number { + const millis = Number(value?.trim() || NaN); + return Number.isFinite(millis) && millis >= 0 + ? millis + : DEFAULT_SESSION_IDLE_TIMEOUT_MILLIS; +} + +/** The part of a response this module needs: to learn when it has closed. */ +export type ClosableResponse = { + once(event: "close", listener: () => void): unknown; +}; + +/** The sessions being watched for idleness. */ +export type IdleSessions = { + /** Start watching a session; it is idle from now. */ + add(sessionId: string): void; + /** Count a request as the session's activity until its response closes. */ + hold(sessionId: string, res: ClosableResponse): void; + /** Stop watching a session that has ended. */ + remove(sessionId: string): void; + /** Stop looking for idle sessions, for shutdown. */ + stop(): void; +}; + +type Activity = { + /** Requests whose responses are still open. */ + open: number; + /** When `open` last reached zero. */ + idleSince: number; +}; + +/** + * Watch sessions for idleness, calling `evict` once for each session that has + * had no open response for `timeoutMillis`. A session is checked on a timer + * (unref'd, so it never keeps the process alive) that fires every tenth of + * the timeout, kept between a second and a minute, so it is evicted within + * one such interval after its timeout. A `timeoutMillis` of `0` disables + * eviction: no timer runs and nothing is ever evicted. + */ +export function watchIdleSessions( + timeoutMillis: number, + evict: (sessionId: string) => void, +): IdleSessions { + const sessions = new Map(); + + const sweep = () => { + const now = Date.now(); + for (const [sessionId, activity] of [...sessions]) { + if (activity.open === 0 && now - activity.idleSince >= timeoutMillis) { + sessions.delete(sessionId); + evict(sessionId); + } + } + }; + + const timer = + timeoutMillis > 0 + ? setInterval( + sweep, + Math.max( + MIN_SWEEP_INTERVAL_MILLIS, + Math.min(timeoutMillis / 10, MAX_SWEEP_INTERVAL_MILLIS), + ), + ).unref() + : undefined; + + return { + add(sessionId) { + sessions.set(sessionId, { open: 0, idleSince: Date.now() }); + }, + hold(sessionId, res) { + const activity = sessions.get(sessionId); + if (!activity) return; + activity.open++; + res.once("close", () => { + activity.open--; + activity.idleSince = Date.now(); + }); + }, + remove(sessionId) { + sessions.delete(sessionId); + }, + stop() { + clearInterval(timer); + }, + }; +} diff --git a/src/everything/transports/streamableHttp.ts b/src/everything/transports/streamableHttp.ts index d5b9ac9510..003f4b9cae 100644 --- a/src/everything/transports/streamableHttp.ts +++ b/src/everything/transports/streamableHttp.ts @@ -20,6 +20,10 @@ // classified by the SDK's own `isLegacyRequest`, from a body parsed once and // handed to whichever side serves it. // +// A 2025-era session whose client never ends it is evicted once it has been +// idle for `SESSION_IDLE_TIMEOUT_MILLIS` (#5558); `idle-sessions.ts` holds the +// reasoning and decides when, and this file closes the transport. +// // `createApp()` builds the Express app without binding a port or installing a // signal handler (#4854), so a test can serve it on a free port, drive it with // a real client, and call its shutdown handler directly; each app has its own @@ -44,6 +48,10 @@ import { randomUUID } from "node:crypto"; import cors from "cors"; import { bindHost, hostAndPort, listenOrExit } from "./listen.js"; import { InMemoryEventStore } from "./in-memory-event-store.js"; +import { + sessionIdleTimeoutMillis, + watchIdleSessions, +} from "./idle-sessions.js"; /** The most bytes of a refused POST's body read to find its request id. */ const MAX_ID_BODY_BYTES = 64 * 1024; @@ -126,6 +134,16 @@ function bodyError( } } +/** What `createApp()` can be told; the launcher passes nothing. */ +export type StreamableHttpAppOptions = { + /** + * How long a 2025-era session may sit idle before it is evicted, in + * milliseconds; `0` disables eviction. Defaults to what + * `SESSION_IDLE_TIMEOUT_MILLIS` asks for. + */ + sessionIdleTimeoutMillis?: number; +}; + /** The Streamable HTTP app, and the handler the launcher installs for SIGINT. */ export type StreamableHttpApp = { app: Express; @@ -135,10 +153,12 @@ export type StreamableHttpApp = { /** * Build the Streamable HTTP transport's Express app: Origin validation, CORS, * the `/mcp` POST, GET and DELETE routes, the map from session id to - * transport that they share, the 2026-07-28 handler, and the shutdown handler - * that closes them. + * transport that they share, the eviction of idle sessions from it, the + * 2026-07-28 handler, and the shutdown handler that closes them. */ -export function createApp(): StreamableHttpApp { +export function createApp( + options: StreamableHttpAppOptions = {}, +): StreamableHttpApp { const app = express(); // A browser page may reach this server only from a localhost origin. The // SDK's guard answers any other Origin with a 403 before a route or the @@ -191,6 +211,27 @@ export function createApp(): StreamableHttpApp { NodeStreamableHTTPServerTransport >(); + // A session nobody has used for the idle timeout is closed, which runs its + // onclose below, so it is removed and cleaned up as a DELETE would have. + // Its next request is answered 404, the client's signal to initialize again. + const idleTimeoutMillis = + options.sessionIdleTimeoutMillis ?? sessionIdleTimeoutMillis(); + const idle = watchIdleSessions(idleTimeoutMillis, (sessionId) => { + console.log( + `Session ${sessionId} idle for ${idleTimeoutMillis} ms, closing it`, + ); + transports + .get(sessionId) + ?.close() + .catch((error: unknown) => { + console.log(`Error closing idle session ${sessionId}:`, error); + // The session is still held, so watch it again: it is tried again + // after another timeout rather than kept for good. (If it did end, + // that later look finds no transport and just forgets it.) + idle.add(sessionId); + }); + }); + // A session-less POST's body is parsed once, to classify it and serve it. // A POST with a session id is a 2025-era session's, and its transport reads // the body itself. @@ -236,6 +277,7 @@ export function createApp(): StreamableHttpApp { // This avoids race conditions where requests might come in before the session is stored console.log(`Session initialized with ID: ${sessionId}`); transports.set(sessionId, transport); + idle.add(sessionId); }, }); @@ -247,6 +289,7 @@ export function createApp(): StreamableHttpApp { `Transport closed for session ${sid}, removing from transports map`, ); transports.delete(sid); + idle.remove(sid); cleanup(); } }; @@ -264,6 +307,8 @@ export function createApp(): StreamableHttpApp { // Handle the request with existing transport - no need to reconnect // The existing transport is already connected to the server + // (a request in flight keeps its session from being evicted as idle) + idle.hold(sessionId, res); await transport.handleRequest(req, res); } catch (error) { console.log("Error handling MCP request:", error); @@ -309,6 +354,8 @@ export function createApp(): StreamableHttpApp { console.log(`Establishing new SSE stream for session ${sessionId}`); } + // The session is in use for as long as this stream stays open + idle.hold(sessionId, res); const transport = transports.get(sessionId); await transport!.handleRequest(req, res); }); @@ -359,6 +406,9 @@ export function createApp(): StreamableHttpApp { const shutdown = async () => { console.log("Shutting down server..."); + // Stop looking for idle sessions: every session is closed below + idle.stop(); + // End the 2026-07-28 requests and subscription streams in flight await modern.close();