hippo-memory 1.70.0 → 1.71.0

package/dist/server/boot.js

@@ -14,17 +14,18 @@ import { createRateLimiter } from './rate-limit.js';
 import { RecallContractError } from '../api/index.js';
 import { handleSlackEventsWebhook } from '../connectors/slack/webhook.js';
 import { handleGitHubEventsWebhook } from '../connectors/github/webhook.js';
-import { bodyDeadlineMs, BodyTimeoutError, BodyTooLargeError, closeAfterReply, DeadlineExceededError, HttpError, JSON_HEADERS, sendJson } from '../util/http-util.js';
+import { BodyTimeoutError, BodyTooLargeError, closeAfterReply, DeadlineExceededError, HttpError, JSON_HEADERS, sendJson } from '../util/http-util.js';
 import { workerCounts } from '../store/sqlite/executor-counts.js';
-import { isLoopback, LIMITER_MAX_KEYS } from './auth.js';
+import { isLocalCaller, LIMITER_MAX_KEYS } from './auth.js';
 import { enforceRateLimit, warnIfClientIpHeaderUnpinned } from './client-ip.js';
 import { answerAtDeadline, handlerDeadlineCount, isAbandoned, requestDeadlineFor } from './deadline.js';
-import { drainAndClose } from './lifecycle.js';
+import { DEFAULT_SHUTDOWN_DRAIN_MS, drainAndClose, setKeepAliveTimeouts, shutdownBoundMs } from './lifecycle.js';
 import { readyProbeFor } from './ready.js';
-import { installCrashHandlers } from '../util/crash-handlers.js';
+import { DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from './defaults.js';
+import { installCrashHandlers, installSignalHandlers } from '../util/crash-handlers.js';
 import { handleMcpPost, handleMcpStream } from './mcp-http.js';
 import { MCP_PROJECT_SCOPED_HEADER } from '../core/project-identity.js';
-import { logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
+import { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
 import { createListener, warnIfCleartext } from './tls.js';
 import { assertAddonRoutes, assertPublicJson, dispatchAddonRoute, dispatchPublicJson, dispatchV1Route, isPublicRoute } from './route-table.js';
 // server.address() returns AddressInfo once a TCP socket is bound; null before
@@ -32,10 +33,8 @@ import { assertAddonRoutes, assertPublicJson, dispatchAddonRoute, dispatchPublic
 function isAddressInfo(a) {
     return a !== null && typeof a !== 'string';
 }
-// Pinned at module load. Bumped alongside package.json on releases. The
-// HTTP /health response uses this; reading package.json synchronously here
-// would couple the daemon to its on-disk install path, which we want to
-// avoid for tests that mkdtemp a hippoRoot.
+// Pinned at module load, bumped with package.json on releases; reading package.json synchronously here would couple the daemon to its install path,
+// which tests that mkdtemp a hippoRoot avoid.
 const VERSION = PACKAGE_VERSION;
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 async function handleRequest(req, res, opts, options) {
@@ -61,7 +60,8 @@ async function handleRequest(req, res, opts, options) {
     const routeRequest = { req, res, opts, query };
     if (await runWithRequestStores(() => dispatchScopedRoute(routeRequest, method, path), { busyWaitMs: SERVER_DB_WAIT_MS }))
         return;
-    // A scope of its own, which the heartbeat timer keeps after it closes, so the key check and every heartbeat wait the server's lock wait. Store-ready: the stream only authenticates, through the port.
+    // A scope of its own, which the heartbeat timer keeps after it closes, so the key check and every
+    // heartbeat wait the server's lock wait. Store-ready: the stream only authenticates, through the port.
     if (method === 'GET' && path === '/mcp/stream') {
         noteAccess(req, { route: path });
         await runWithRequestStores(() => handleMcpStream(req, res, opts, streamSlots), { busyWaitMs: SERVER_DB_WAIT_MS });
@@ -114,11 +114,9 @@ async function dispatchScopedRoute(r, method, path) {
     return false;
 }
 function sendHealth(req, res, startedAt) {
-    // Loopback callers (detectServer's stale-pidfile probe reads version and
-    // pid) get the full body. Non-loopback callers get liveness only: the
-    // version string would fingerprint the build for the public internet and
-    // the pid is noise. Platform health checks only need the 200.
-    if (isLoopback(req.socket.remoteAddress)) {
+    // A caller on this machine (detectServer's probe reads version and pid) gets the full body; anyone else, even a proxied caller or a browser page on loopback,
+    // gets liveness only: the version would fingerprint the build and the pid is noise. Platform health checks only need the 200.
+    if (isLocalCaller(req)) {
         sendJson(res, 200, {
             ok: true,
             version: VERSION,
@@ -135,7 +133,8 @@ function sendHealth(req, res, startedAt) {
         sendJson(res, 200, { ok: true });
     }
 }
-/** Readiness: one cheap read on the served store under the server's lock wait. /health stays liveness only, so a probe can tell a store that does not answer from a dead process. */
+/** Readiness: one cheap read on the served store under the server's lock wait. /health stays
+ * liveness only, so a probe can tell a store that does not answer from a dead process. */
 async function sendReady(res, store) {
     const { readiness } = store;
     if (readiness === undefined) {
@@ -156,10 +155,8 @@ function assertBindable(host) {
     }
 }
 async function assertNoLiveServer(hippoRoot) {
-    // Refuse to start if a live hippo server already serves this hippoRoot.
-    // detectServer probes the recorded /health — a stale pidfile is unlinked and
-    // ignored, but a live peer means a concurrent `hippo serve` would race for
-    // the port and clobber the pidfile.
+    // Refuse to start if a live hippo server already serves this hippoRoot (detectServer probes the recorded /health and unlinks a stale pidfile):
+    // a concurrent `hippo serve` would race for the port and clobber the pidfile.
     const existing = await detectServer(hippoRoot);
     if (existing) {
         throw new Error(`hippo serve: already running on port ${existing.port} (pid ${existing.pid}). ` +
@@ -175,10 +172,8 @@ function bootRateLimiter(perAddress) {
         return undefined;
     if (perAddress !== undefined)
         return limiterFor(perAddress);
-    // Per-IP rate limiter for /v1/* and /mcp*. Built here (not at module scope) so
-    // HIPPO_V1_RPS is read at boot, matching HIPPO_PORT above and letting a test
-    // set the rate before serve(). A non-positive or non-finite value disables
-    // limiting (the opt-out knob).
+    // Per-IP rate limiter for /v1/* and /mcp*, built here (not at module scope) so HIPPO_V1_RPS is read at boot and a test can set it before serve().
+    // A non-positive or non-finite value disables limiting (the opt-out knob).
     const v1Rps = Number(envV1Rps() ?? 20);
     return Number.isFinite(v1Rps) && v1Rps > 0 ? limiterFor({ ratePerSec: v1Rps, burst: v1Rps * 2 }) : undefined;
 }
@@ -218,8 +213,7 @@ function createStoreHolder(hippoRoot, store) {
         if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
             return;
         try {
-            // The 'finish' listener can fire inside a request scope, which would close this connection with the request,
-            // and inside the block of a `loop: 'off'` route, which would refuse the open.
+            // The 'finish' listener can fire inside a request scope (closing this connection with the request) and inside a `loop: 'off'` block (refusing the open).
             // The server's lock wait: this open runs on the event loop, where SQLite's 5 s default and the 30 s journal-mode retry would stall every request.
             heldDb = outsideSqliteOffLoop(() => outsideRequestStores(() => openHippoDb(hippoRoot, { busyWaitMs: SERVER_DB_WAIT_MS })));
             checkpointer = startWalCheckpointer(getHippoDbPath(hippoRoot));
@@ -281,9 +275,23 @@ function replyWithFailure(req, res, err, requestId) {
     sendError(res, mapped.status, mapped.message);
 }
 const HANDLER_LATE = 'the request did not finish by its deadline and was abandoned; a write it started may or may not be saved';
-// The caller already has its 504, so a second reply would be written into a finished response.
-function logLateFailure(req, err) {
-    log.debug(`${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} ended after its deadline reply: ${errorMessage(err)}`);
+// The caller already has its 504, so this line is the only trace of the failure. The path and the error text can hold caller data, so it carries neither.
+function logLateFailure(req, err, requestId) {
+    const fields = { requestId, method: req.method ?? 'GET', route: accessRouteOf(req), failureStatus: replyFor(err).status };
+    log.warn('request failed after its deadline reply', { ...fields, errorClass: errorFields(err).errorClass });
+}
+// A handler that ends after the 504 finds the response finished, so sending its own reply throws this: its work ran to the end.
+function isDroppedLateReply(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ERR_HTTP_HEADERS_SENT';
+}
+/** A GET only reads; every other method this server routes can write. */
+const isRead = (method) => method === 'GET';
+// A read that ends late changed nothing. A write that ends late ran to its end after its caller was told it may not have been saved.
+function logLateFinish(req, requestId) {
+    const method = req.method ?? 'GET';
+    if (isRead(method))
+        return;
+    log.info('request finished after its deadline reply; its own reply was dropped', { requestId, method, route: accessRouteOf(req) });
 }
 function replyOrClose(req, res, err, requestId) {
     try {
@@ -291,7 +299,7 @@ function replyOrClose(req, res, err, requestId) {
     }
     catch (replyErr) {
         // A throw here would be an unhandled rejection, which stops the daemon for every caller.
-        log.error(`serve: failure reply not sent, socket closed: ${errorMessage(replyErr)}`);
+        log.error(`serve: failure reply not sent, socket closed: ${errorMessage(replyErr)}`, errorFields(replyErr));
         res.destroy();
     }
 }
@@ -303,24 +311,19 @@ function answerRequest(req, res, handle, slowWarnMs) {
     runWithRequestId(requestId, () => {
         if (deadline)
             answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId));
-        handle().catch((err) => {
+        handle().then(() => {
             if (isAbandoned(res))
-                logLateFailure(req, err);
-            else
+                logLateFinish(req, requestId);
+        }, (err) => {
+            if (!isAbandoned(res))
                 replyOrClose(req, res, err, requestId);
+            else if (isDroppedLateReply(err))
+                logLateFinish(req, requestId);
+            else
+                logLateFailure(req, err, requestId);
         });
     }, deadline);
 }
-// Node's own default, named so the three socket deadlines read together. It times the request arriving, never the handler, so a 10 minute sleep is not cut.
-const REQUEST_RECEIVE_TIMEOUT_MS = 300_000;
-function setKeepAliveTimeouts(server) {
-    // The default 5s keepAliveTimeout closes idle sockets just as clients reuse them (ECONNRESET).
-    // headersTimeout must stay ABOVE keepAliveTimeout + keepAliveTimeoutBuffer (1s), or it closes idle reused sockets itself.
-    server.keepAliveTimeout = 65_000;
-    server.headersTimeout = 70_000;
-    // Never below what a raised body deadline allows, or Node's bare 408 would come before the route's own.
-    server.requestTimeout = Math.max(REQUEST_RECEIVE_TIMEOUT_MS, server.headersTimeout + bodyDeadlineMs());
-}
 function listenOn(server, port, host) {
     return new Promise((resolve, reject) => {
         const onError = (err) => {
@@ -338,57 +341,23 @@ function listenOn(server, port, host) {
         server.listen(port, host);
     });
 }
-function installSignalHandlers(stop) {
-    let shuttingDown = false;
-    const gracefulShutdown = async (signal) => {
-        if (shuttingDown)
-            return;
-        shuttingDown = true;
-        log.warn(`received ${signal}, shutting down`);
-        try {
-            await stop();
-            process.exit(0);
-        }
-        catch (err) {
-            log.error(`error during stop: ${errorMessage(err)}`, errorFields(err));
-            process.exit(1);
-        }
-    };
-    process.once('SIGTERM', () => { void gracefulShutdown('SIGTERM'); });
-    process.once('SIGINT', () => { void gracefulShutdown('SIGINT'); });
+function exitOnSignalOrCrash(stop, drainMs) {
+    const shutdown = { run: stop, boundMs: shutdownBoundMs(drainMs) };
+    installSignalHandlers('serve', shutdown);
+    installCrashHandlers('serve', shutdown);
 }
-/**
- * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
- *
- * Refuses non-loopback hosts at boot unless
- * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
- * requireAuth) has shipped and every route checks it except GET /health
- * (public by design for platform health checks) and the two connector
- * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
- * secrets and 404 when those secrets are unset, and any publicJson GET path. But the loopback
- * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address (unless they carry Forwarded,
- * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip, True-Client-Ip or Fly-Client-Ip, which mark a same-host proxy and get
- * a 401 like any keyless remote request), so binding to a non-loopback host
- * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
- * which forces every request (loopback or not) through Bearer-token
- * validation. Without that env var set, a non-loopback bind would expose the
- * DB to the network with no auth, so we fail fast instead.
- *
- * Use port: 0 in tests to bind to an ephemeral port and read the actual
- * port back via server.address() after listen.
- */
+/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses non-loopback hosts unless HIPPO_REQUIRE_AUTH=1.
+ * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export async function serve(opts) {
-    const host = opts.host ?? '127.0.0.1';
-    const requestedPort = opts.port ?? Number(envPort() ?? 6789);
+    const host = opts.host ?? DEFAULT_SERVER_HOST;
+    const requestedPort = opts.port ?? Number(envPort() ?? DEFAULT_SERVER_PORT);
     const routes = frozenAddonRoutes(opts.routes);
     const publicJsonBodies = assertPublicJson(opts.publicJson ?? {});
     const limiters = bootLimiters(opts.rateLimits);
     assertBindable(host);
     await assertNoLiveServer(opts.hippoRoot);
-    // The server's start time. Single source of truth: it is returned by every
-    // GET /health response and (below) written into the pidfile, so detectServer
-    // can match the two and prove a pid-reusing impostor is not the real server.
+    // Single source of truth for the start time: returned by GET /health and written into the pidfile, so detectServer can prove a pid-reusing impostor is not
+    // this server.
     const startedAt = new Date().toISOString();
     // Open /mcp/stream count per client key, so the cap is per server rather than per process.
     const streamSlots = new Map();
@@ -414,15 +383,15 @@ export async function serve(opts) {
             await served.store.close();
         await holder.release();
     };
-    if (opts.handleSignals) {
-        installSignalHandlers(stop);
-        installCrashHandlers('serve', stop);
-    }
+    if (opts.handleSignals)
+        exitOnSignalOrCrash(stop, opts.shutdownDrainMs ?? DEFAULT_SHUTDOWN_DRAIN_MS);
     return { port: actualPort, url, stop, server };
 }
 function frozenAddonRoutes(addonRoutes) {
     // A frozen copy, so a route the caller adds or renames after boot never skips the check below.
-    const routes = Object.freeze((addonRoutes ?? []).map(({ path, handler, storeReady }) => Object.freeze(storeReady === undefined ? { path, handler } : { path, handler, storeReady })));
+    const routes = Object.freeze((addonRoutes ?? []).map(({ path, handler, storeReady }) => Object.freeze(storeReady === undefined
+        ? { path, handler }
+        : { path, handler, storeReady })));
     assertAddonRoutes(routes);
     return routes;
 }
@@ -456,10 +425,8 @@ async function listenAndDescribe(server, port, host, tls) {
     return { port: actualPort, url };
 }
 async function stopListening(opts, server, inflight, startedAt) {
-    // Remove the pidfile only if it still names this server. A newer server
-    // may have started on this hippoRoot and rewritten the pidfile; an
-    // unconditional unlink here would orphan it.
+    // Remove the pidfile only if it still names this server: a newer server may have rewritten it, and an unconditional unlink would orphan it.
     removePidfileIfOwned(opts.hippoRoot, { pid: process.pid, startedAt });
-    await drainAndClose(server, inflight, opts.shutdownDrainMs ?? 5000);
+    await drainAndClose(server, inflight, opts.shutdownDrainMs ?? DEFAULT_SHUTDOWN_DRAIN_MS);
 }
 //# sourceMappingURL=boot.js.map

package/dist/server/client-ip.d.ts

@@ -1,25 +1,9 @@
 import type { IncomingMessage } from 'node:http';
 import type { RateLimiter } from './rate-limit.js';
 /**
- * Rate-limit key for a request. Defaults to the socket's remote address.
- *
- * Behind a TLS-terminating proxy (Fly, most PaaS ingress) every socket
- * carries the proxy's address, so per-IP buckets collapse into one global
- * bucket that unauthenticated traffic can drain before auth runs. Set
- * HIPPO_CLIENT_IP_HEADER to the header the proxy stamps with the real
- * client address (fly-client-ip on Fly, which the edge always overwrites)
- * to key buckets per client instead.
- *
- * Only set this when a trusted proxy fronts EVERY request: a directly
- * reachable server honoring the header would let clients mint a fresh
- * bucket per request and bypass the limiter entirely.
- *
- * HIPPO_TRUSTED_PROXIES (comma-separated IPs or CIDRs) pins which peers count
- * as that proxy: the header is read only when the socket peer is listed, and
- * listed hops are skipped. In a comma-joined chain (X-Forwarded-For) the key is
- * the rightmost hop no trusted proxy added; entries to its left are whatever
- * the client sent, so they never pick the bucket.
- */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
+ * Set HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) only when a trusted proxy fronts EVERY request, or clients could mint a fresh bucket per request.
+ * HIPPO_TRUSTED_PROXIES (IPs or CIDRs) pins which peers count as that proxy; in a comma-joined chain the key is the rightmost hop no trusted proxy added. */
 export declare function clientIpForRateLimit(req: IncomingMessage): string;
 /** Said once at boot: with no proxy list, a caller that reaches the port without the proxy picks its own bucket by sending the header. */
 export declare function warnIfClientIpHeaderUnpinned(): void;

package/dist/server/client-ip.js

@@ -5,25 +5,9 @@ import { log } from '../util/log.js';
 import { HttpError } from '../util/http-util.js';
 const IPV6_PREFIX_GROUPS = 4;
 /**
- * Rate-limit key for a request. Defaults to the socket's remote address.
- *
- * Behind a TLS-terminating proxy (Fly, most PaaS ingress) every socket
- * carries the proxy's address, so per-IP buckets collapse into one global
- * bucket that unauthenticated traffic can drain before auth runs. Set
- * HIPPO_CLIENT_IP_HEADER to the header the proxy stamps with the real
- * client address (fly-client-ip on Fly, which the edge always overwrites)
- * to key buckets per client instead.
- *
- * Only set this when a trusted proxy fronts EVERY request: a directly
- * reachable server honoring the header would let clients mint a fresh
- * bucket per request and bypass the limiter entirely.
- *
- * HIPPO_TRUSTED_PROXIES (comma-separated IPs or CIDRs) pins which peers count
- * as that proxy: the header is read only when the socket peer is listed, and
- * listed hops are skipped. In a comma-joined chain (X-Forwarded-For) the key is
- * the rightmost hop no trusted proxy added; entries to its left are whatever
- * the client sent, so they never pick the bucket.
- */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
+ * Set HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) only when a trusted proxy fronts EVERY request, or clients could mint a fresh bucket per request.
+ * HIPPO_TRUSTED_PROXIES (IPs or CIDRs) pins which peers count as that proxy; in a comma-joined chain the key is the rightmost hop no trusted proxy added. */
 export function clientIpForRateLimit(req) {
     const socketIp = req.socket.remoteAddress ?? 'unknown';
     const header = envClientIpHeader();
@@ -101,15 +85,8 @@ function isTrustedProxy(list, ip) {
     return family !== 0 && list.check(bare, family === 6 ? 'ipv6' : 'ipv4');
 }
 export function enforceRateLimit(req, path, limiter) {
-    // Per-IP rate limit on /v1/* and /mcp* to bound api-key-id enumeration. /health
-    // (a liveness probe) and other paths are never throttled. A 429 thrown
-    // here lands in the createServer catch like any other HttpError.
-    //
-    // Keyed on the socket's remote address by default. Behind a TLS-terminating
-    // proxy every socket carries the proxy's address, collapsing the per-IP
-    // buckets into one global bucket that pre-auth traffic can drain; set
-    // HIPPO_CLIENT_IP_HEADER there so each real client gets its own bucket
-    // (see clientIpForRateLimit).
+    // Per-IP rate limit on /v1/* and /mcp* to bound api-key-id enumeration; /health and other paths are never throttled, and a 429 lands in the createServer
+    // catch. Keyed per clientIpForRateLimit (set HIPPO_CLIENT_IP_HEADER behind a TLS-terminating proxy, or all clients share one bucket).
     if (limiter && (path.startsWith('/v1/') || path === '/mcp' || path === '/mcp/stream')) {
         if (!limiter.check(clientLimitKey(req))) {
             throw new HttpError(429, 'rate limit exceeded', limiter.retryAfterSec);

package/dist/server/defaults.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_SERVER_PORT = 6789;
+export declare const DEFAULT_SERVER_HOST = "127.0.0.1";
+//# sourceMappingURL=defaults.d.ts.map

package/dist/server/defaults.js

@@ -0,0 +1,4 @@
+// `hippo serve` reads these without loading the server, so the CLI and serve() cannot disagree on a default.
+export const DEFAULT_SERVER_PORT = 6789;
+export const DEFAULT_SERVER_HOST = '127.0.0.1';
+//# sourceMappingURL=defaults.js.map

package/dist/server/key-check-bounds.d.ts

@@ -1,5 +1,6 @@
 export interface KeyCheckBounds {
-    /** Throws the 429 a refused key check answers, before any derivation: no room left to wait (Retry-After 1), or `address` has spent its tries on `keyId` (Retry-After 12). */
+    /** Throws the 429 a refused key check answers, before any derivation: no room left to
+     * wait (Retry-After 1), or `address` has spent its tries on `keyId` (Retry-After 12). */
     admit(keyId: string, address: string): void;
     /** Runs `derive` now or once a slot frees; `admit` in the same tick keeps the queue within its cap. */
     run<T>(derive: () => Promise<T>): Promise<T>;

package/dist/server/lifecycle.d.ts

@@ -1,7 +1,8 @@
 import type { Server, ServerResponse } from 'node:http';
-/**
- * Stop accepting, end streams at once (they never finish on their own), give other in-flight
- * requests up to `drainMs`, then close whatever is left.
- */
+export declare function setKeepAliveTimeouts(server: Server): void;
+export declare const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
+/** How long a signal or crash shutdown may run before the process is ended without it. */
+export declare function shutdownBoundMs(drainMs: number): number;
+/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what is left. */
 export declare function drainAndClose(server: Server, inflight: ReadonlySet<ServerResponse>, drainMs: number): Promise<void>;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/server/lifecycle.js

@@ -1,8 +1,23 @@
+import { bodyDeadlineMs } from '../util/http-util.js';
 import { log } from '../util/log.js';
-/**
- * Stop accepting, end streams at once (they never finish on their own), give other in-flight
- * requests up to `drainMs`, then close whatever is left.
- */
+// Node's own default, named so the three socket deadlines read together. It times the request arriving, never the handler, so a 10 minute sleep is not cut.
+const REQUEST_RECEIVE_TIMEOUT_MS = 300_000;
+export function setKeepAliveTimeouts(server) {
+    // The default 5s keepAliveTimeout closes idle sockets just as clients reuse them (ECONNRESET).
+    // headersTimeout must stay ABOVE keepAliveTimeout + keepAliveTimeoutBuffer (1s), or it closes idle reused sockets itself.
+    server.keepAliveTimeout = 65_000;
+    server.headersTimeout = 70_000;
+    // Never below what a raised body deadline allows, or Node's bare 408 would come before the route's own.
+    server.requestTimeout = Math.max(REQUEST_RECEIVE_TIMEOUT_MS, server.headersTimeout + bodyDeadlineMs());
+}
+export const DEFAULT_SHUTDOWN_DRAIN_MS = 5000;
+// Past the request drain, a stop only waits for each store thread to end its statement and close: seconds at most, so longer means a thread that will not end.
+const STORE_CLOSE_GRACE_MS = 10_000;
+/** How long a signal or crash shutdown may run before the process is ended without it. */
+export function shutdownBoundMs(drainMs) {
+    return drainMs + STORE_CLOSE_GRACE_MS;
+}
+/** Stops accepting, ends streams at once (they never finish on their own), gives other in-flight requests up to `drainMs`, then closes what is left. */
 export async function drainAndClose(server, inflight, drainMs) {
     const closed = new Promise((resolve, reject) => {
         server.close((err) => (err ? reject(err) : resolve()));

package/dist/server/mcp-http.js

@@ -12,17 +12,8 @@ import { isJsonString, isJsonObject } from '../util/json.js';
 import { FINGERPRINT_HEX_CHARS } from '../util/token-text.js';
 const DEFAULT_SSE_HEARTBEAT_MS = 60000;
 const DEFAULT_SSE_MAX_AGE_SEC = 3600;
-/**
- * Build a per-client key for MCP state isolation under HTTP-MCP. Used by
- * mcp/server.ts to scope `lastRecalledIds` to the calling client so two
- * clients on the same tenant cannot poison each other's outcome feedback.
- *
- * Token is hashed (sha256, 16-hex-char prefix) so we never log or persist
- * the raw bearer. Combined with remoteAddress so two clients sharing a key
- * (e.g. on a shared Postman environment) are still separable in the common
- * case. 'noauth' covers loopback no-auth and is acceptable because that
- * path is single-host single-user.
- */
+/** Per-client key for MCP state isolation under HTTP-MCP (scopes `lastRecalledIds`): sha256 of the token (16 hex chars, so the raw bearer is never logged)
+ * plus remoteAddress, so clients sharing a key stay separable; 'noauth' covers loopback no-auth, which is single-host single-user. */
 function buildMcpClientKey(req) {
     const auth = readAuthHeader(req);
     const tokenHash = auth.kind === 'bearer'
@@ -31,24 +22,8 @@ function buildMcpClientKey(req) {
     const addr = subscriberKey(req.socket.remoteAddress ?? 'unknown');
     return `http:${tokenHash}:${addr}`;
 }
-// ── MCP-over-HTTP/SSE transport ──
-//
-// Two routes implement an MCP HTTP transport alongside the stdio one. Both
-// dispatch to the same `handleMcpRequest` as the stdio loop in src/mcp/server.ts.
-//
-// POST /mcp        — Send a JSON-RPC request, get a JSON-RPC response synchronously
-//                    in the body. Content-type: application/json both ways.
-// GET  /mcp/stream — Open an SSE stream for server-initiated messages.
-//                    v1 simplification: this stream is keepalive-only. Clients
-//                    that need server-pushed notifications/progress will see
-//                    only `: ping` comments every 30s. All real responses come
-//                    back synchronously on POST /mcp. This matches the
-//                    "synchronous JSON in body" leg of the MCP HTTP spec and
-//                    is enough for `tools/list` / `tools/call` round-trips.
-//                    Server-initiated SSE messages will be wired in a later task.
-//
-// Auth: same as /v1/* — Bearer token validated via `requireAuth`, with the
-// loopback no-auth fallback. SSE check runs once at stream-open.
+// MCP-over-HTTP/SSE: POST /mcp answers a JSON-RPC request synchronously; GET /mcp/stream is a keepalive-only SSE stream (`: ping` every 30s) in v1.
+// Both dispatch to handleMcpRequest as stdio does. Auth matches /v1/* (Bearer via `requireAuth`, loopback fallback); SSE is checked once at stream-open.
 // Percent-encoded by the client, so any lowercase Unicode name fits a Latin-1 header.
 const HEADER_PIECE = /^[A-Za-z0-9\-_.!~*'()%]+$/;
 function decodeHeaderPiece(raw, header) {
@@ -101,11 +76,8 @@ function mcpContextFor(ctx, clientKey, autoSleep, project) {
     return mcpCtx;
 }
 export async function handleMcpPost(req, res, opts) {
-    // Build the same Context the /v1/* routes use so MCP tool calls inherit
-    // the server's bound hippoRoot and the auth-resolved tenantId / actor.
-    // Without this, executeTool would walk from cwd via findHippoRoot() and
-    // pull tenant from HIPPO_TENANT, dropping a valid Bearer for tenant B
-    // back to whatever the env says.
+    // Same Context the /v1/* routes use, so MCP tool calls inherit the bound hippoRoot and the auth-resolved tenantId/actor; otherwise executeTool would walk
+    // from cwd and read HIPPO_TENANT, dropping a valid Bearer for tenant B to the env's tenant.
     const ctx = await buildContextWithAuth(req, opts);
     noteAccess(req, { tenant: ctx.tenantId });
     const project = callerProjectFromHeaders(req, ctx.hippoRoot);
@@ -120,9 +92,8 @@ export async function handleMcpPost(req, res, opts) {
     if (!isJsonObject(mcpReq) || !isJsonString(mcpReq.method)) {
         throw new HttpError(400, 'JSON-RPC body must include a method string');
     }
-    // SAFETY: validated above as a plain JSON object carrying a string method;
-    // the remaining McpRequest wire fields (jsonrpc, id, params) are checked or
-    // safely defaulted inside handleMcpRequest's JSON-RPC dispatch.
+    // SAFETY: validated above as a plain JSON object with a string method; the other McpRequest wire fields (jsonrpc, id, params) are checked or defaulted in
+    // handleMcpRequest.
     const rpcReq = mcpReq;
     let mcpRes;
     try {
@@ -178,13 +149,8 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
     // Initial ping so smoke tests can confirm the stream is live without
     // waiting for the first keepalive interval.
     res.write(': ping\n\n');
-    // SSE hardening:
-    //   - Heartbeat re-validates the bearer (default 60s). If the key was
-    //     revoked or rotated, close the stream with reason='auth_revoked'.
-    //   - MCP_SSE_MAX_AGE_SEC (default 3600) caps stream lifetime; close
-    //     with reason='max_age_exceeded' when reached.
-    //   - MCP_SSE_HEARTBEAT_MS (default 60000) lets tests run with a short
-    //     interval without waiting a full minute.
+    // SSE hardening: the heartbeat re-validates the bearer (MCP_SSE_HEARTBEAT_MS, default 60000) and closes with 'auth_revoked' if the key was revoked or
+    // rotated; MCP_SSE_MAX_AGE_SEC (default 3600) caps stream lifetime and closes with 'max_age_exceeded'.
     keepStreamAlive(req, res, opts);
 }
 function keepStreamAlive(req, res, opts) {

package/dist/server/rate-limit.d.ts

@@ -1,16 +1,7 @@
-/**
- * Per-key token-bucket rate limiter for inbound /v1/* requests.
- *
- * Bounds api-key-id enumeration: a
- * client that drains its bucket is denied until it refills. Dependency-free
- * and unit-testable in isolation via the injectable `now`.
- */
+/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+ * unit-testable. */
 export interface RateLimiter {
-    /**
-     * Consume one token for `key`. Returns true if the request is allowed,
-     * false if the key's bucket is exhausted. `now` (epoch ms) is injectable
-     * for deterministic tests.
-     */
+    /** Consume one token for `key`: true if allowed, false if the bucket is exhausted; `now` (epoch ms) is injectable for deterministic tests. */
     check(key: string, now?: number): boolean;
     readonly retryAfterSec: number;
 }
@@ -24,11 +15,7 @@ export interface RateLimiterOpts {
     /** Hard cap on tracked keys; the least-recently-used key is evicted on overflow. */
     maxKeys: number;
 }
-/**
- * Build a token-bucket limiter. Memory is bounded two ways: a sweep (throttled
- * to once per `idleEvictMs`) drops idle buckets, and a hard `maxKeys` cap evicts
- * the least-recently-used key, so a client rotating source addresses cannot
- * grow the map without bound between sweeps.
- */
+/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
+ * key, so a client rotating source addresses cannot grow the map without bound. */
 export declare function createRateLimiter(opts: RateLimiterOpts): RateLimiter;
 //# sourceMappingURL=rate-limit.d.ts.map

package/dist/server/rate-limit.js

@@ -1,16 +1,7 @@
-/**
- * Per-key token-bucket rate limiter for inbound /v1/* requests.
- *
- * Bounds api-key-id enumeration: a
- * client that drains its bucket is denied until it refills. Dependency-free
- * and unit-testable in isolation via the injectable `now`.
- */
-/**
- * Build a token-bucket limiter. Memory is bounded two ways: a sweep (throttled
- * to once per `idleEvictMs`) drops idle buckets, and a hard `maxKeys` cap evicts
- * the least-recently-used key, so a client rotating source addresses cannot
- * grow the map without bound between sweeps.
- */
+/** Per-key token-bucket rate limiter for inbound /v1/* requests, bounding api-key-id enumeration. Dependency-free; the injectable `now` makes it
+ * unit-testable. */
+/** Token-bucket limiter with bounded memory: a sweep (at most once per `idleEvictMs`) drops idle buckets and a `maxKeys` cap evicts the least-recently-used
+ * key, so a client rotating source addresses cannot grow the map without bound. */
 export function createRateLimiter(opts) {
     const { ratePerSec, burst, idleEvictMs, maxKeys } = opts;
     const buckets = new Map();

package/dist/server/request.d.ts

@@ -13,6 +13,8 @@ interface AccessNote {
 }
 /** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
 export declare function noteAccess(req: IncomingMessage, note: AccessNote): void;
+/** The route name the request's access line carries, for a line about the same request logged after its reply. */
+export declare function accessRouteOf(req: IncomingMessage): string;
 /** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
 export declare function openRequest(req: IncomingMessage, res: ServerResponse, slowWarnMs?: number): string;
 export declare function sendError(res: ServerResponse, status: number, message: string): void;
@@ -23,14 +25,8 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-/**
- * Reject URL-encoded slashes in path segments BEFORE the URL parser decodes
- * them — otherwise `%2F` becomes `/`, path-split runs, and the route either
- * silently 404s or matches the wrong template.
- *
- * Only the PATHNAME is scanned (split on the first `?`), so recall queries
- * containing URLs like `?q=https%3A%2F%2Fexample.com` are not rejected.
- */
+/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+ * Only the PATHNAME is scanned, so recall queries like `?q=https%3A%2F%2Fexample.com` are not rejected. */
 export declare function rejectEncodedSlash(rawUrl: string): void;
 export {};
 //# sourceMappingURL=request.d.ts.map