hippo-memory 1.68.0 → 1.70.0

package/dist/server/boot.js

@@ -0,0 +1,465 @@
+import { envPort, envRequireAuth, envV1Rps } from '../util/env.js';
+import { existsSync } from 'node:fs';
+import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
+import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, outsideRequestStores, outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
+import { startWalCheckpointer } from '../db/wal-checkpointer.js';
+import { requireGroup } from '../store/index.js';
+import { workerSqliteStore } from '../store/sqlite/worker-store.js';
+import { markSharedStore } from '../core/config.js';
+import { auditWriteFailureCount } from '../store/audit.js';
+import { PACKAGE_VERSION } from '../util/version.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { runWithRequestId } from '../util/request-scope.js';
+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 { workerCounts } from '../store/sqlite/executor-counts.js';
+import { isLoopback, 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 { readyProbeFor } from './ready.js';
+import { installCrashHandlers } 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 { 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
+// listening, a string only for pipe/unix-socket listeners (never used here).
+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.
+const VERSION = PACKAGE_VERSION;
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+async function handleRequest(req, res, opts, options) {
+    const { startedAt, streamSlots, limiter } = options;
+    // Pre-decode raw-URL slash check. Catches `%2F` / `%2f` before
+    // Node's URL parser collapses them and they slip past the route table.
+    rejectEncodedSlash(req.url ?? '/');
+    const { method, path, query } = parseRequest(req);
+    // An older core ignores X-Hippo-Project, so every /mcp reply, a 429 or 401 too, tells the client this one filters by it.
+    if (path === '/mcp')
+        res.setHeader(MCP_PROJECT_SCOPED_HEADER, '1');
+    if (method === 'GET' && path === '/health') {
+        noteAccess(req, { route: path });
+        sendHealth(req, res, startedAt);
+        return;
+    }
+    if (method === 'GET' && path === '/ready') {
+        noteAccess(req, { route: path });
+        await sendReady(res, opts.store);
+        return;
+    }
+    enforceRateLimit(req, path, limiter);
+    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.
+    if (method === 'GET' && path === '/mcp/stream') {
+        noteAccess(req, { route: path });
+        await runWithRequestStores(() => handleMcpStream(req, res, opts, streamSlots), { busyWaitMs: SERVER_DB_WAIT_MS });
+        return;
+    }
+    res.writeHead(404, JSON_HEADERS);
+    res.end(JSON.stringify({ error: 'not found' }));
+}
+const WEBHOOK_GROUPS = ['entryWrites', 'connectorWrites', 'connectorEvents'];
+/** A store missing a group a delivery writes through refuses the webhook up front, so no delivery is acknowledged and then half stored. */
+function requireWebhookGroups(store) {
+    for (const group of WEBHOOK_GROUPS)
+        requireGroup(store, group);
+}
+/** Every route that runs inside a request scope, so it opens each store once: the /v1 table, public JSON, add-on routes, the webhooks and POST /mcp. */
+async function dispatchScopedRoute(r, method, path) {
+    if (await dispatchV1Route(r, method, path))
+        return true;
+    if (dispatchPublicJson(r, method, path))
+        return true;
+    if (await dispatchAddonRoute(r, method, path))
+        return true;
+    const { req, res, opts } = r;
+    if (method === 'POST' && path === '/v1/connectors/slack/events') {
+        noteAccess(req, { route: path });
+        // Bearer auth deliberately skipped: this route is in PUBLIC_ROUTES and authenticates via the Slack HMAC signature.
+        if (!isPublicRoute(method, path)) {
+            // Defensive: PUBLIC_ROUTES drift would land here. Fail closed.
+            throw new HttpError(401, 'auth required');
+        }
+        requireWebhookGroups(opts.store);
+        await handleSlackEventsWebhook({ req, res, opts }, opts.store);
+        return true;
+    }
+    if (method === 'POST' && path === '/v1/connectors/github/events') {
+        noteAccess(req, { route: path });
+        if (!isPublicRoute(method, path)) {
+            throw new HttpError(401, 'auth required');
+        }
+        requireWebhookGroups(opts.store);
+        await handleGitHubEventsWebhook({ req, res, opts }, opts.store);
+        return true;
+    }
+    // Store-ready: under another store the MCP layer lists and runs only the tools ported to the port.
+    if (method === 'POST' && path === '/mcp') {
+        noteAccess(req, { route: path });
+        await handleMcpPost(req, res, opts);
+        return true;
+    }
+    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)) {
+        sendJson(res, 200, {
+            ok: true,
+            version: VERSION,
+            started_at: startedAt,
+            pid: process.pid,
+            audit_write_failures: auditWriteFailureCount(),
+            store_queue_refusals: workerCounts.queueRefusals,
+            store_jobs_expired: workerCounts.jobsExpired,
+            store_workers_replaced: workerCounts.workersReplaced,
+            handler_deadlines: handlerDeadlineCount(),
+        });
+    }
+    else {
+        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. */
+async function sendReady(res, store) {
+    const { readiness } = store;
+    if (readiness === undefined) {
+        sendJson(res, 200, { ok: true, store: 'unchecked' });
+        return;
+    }
+    if (!(await readyProbeFor(store, readiness)())) {
+        sendJson(res, 503, { ok: false, error: 'store_unavailable' });
+        return;
+    }
+    sendJson(res, 200, { ok: true });
+}
+function assertBindable(host) {
+    if (!LOOPBACK_HOSTS.has(host) && !envRequireAuth()) {
+        throw new Error(`Refusing to bind hippo serve to non-loopback host '${host}' without auth. ` +
+            `Set HIPPO_REQUIRE_AUTH=1 to bind non-loopback; every request then requires ` +
+            `a valid API key. Bind to 127.0.0.1 / ::1 / localhost otherwise.`);
+    }
+}
+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.
+    const existing = await detectServer(hippoRoot);
+    if (existing) {
+        throw new Error(`hippo serve: already running on port ${existing.port} (pid ${existing.pid}). ` +
+            `Stop that server before starting another on the same hippoRoot.`);
+    }
+}
+// SHORTCUT: buckets live in this process and reset on restart or LRU eviction; move them to the store if serve ever runs as several processes.
+function limiterFor({ ratePerSec, burst }) {
+    return createRateLimiter({ ratePerSec, burst, idleEvictMs: 60000, maxKeys: LIMITER_MAX_KEYS });
+}
+function bootRateLimiter(perAddress) {
+    if (perAddress === 'off')
+        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).
+    const v1Rps = Number(envV1Rps() ?? 20);
+    return Number.isFinite(v1Rps) && v1Rps > 0 ? limiterFor({ ratePerSec: v1Rps, burst: v1Rps * 2 }) : undefined;
+}
+const DEFAULT_FAILED_AUTH = { ratePerSec: 20, burst: 40 };
+function assertRateLimitSpec(name, { ratePerSec, burst }) {
+    if (!Number.isFinite(ratePerSec) || ratePerSec <= 0)
+        throw new Error(`rateLimits.${name}.ratePerSec must be a finite number above 0`);
+    if (!Number.isFinite(burst) || burst < 1)
+        throw new Error(`rateLimits.${name}.burst must be a finite number of at least 1`);
+}
+/** Refuses a bad spec at boot, since a NaN or zero rate would otherwise turn a bucket off or refuse every request. */
+function bootLimiters(rateLimits) {
+    const { perCaller, perAddress, failedAuthPerAddress = DEFAULT_FAILED_AUTH } = rateLimits ?? {};
+    if (perCaller !== undefined)
+        assertRateLimitSpec('perCaller', perCaller);
+    if (perAddress !== undefined && perAddress !== 'off')
+        assertRateLimitSpec('perAddress', perAddress);
+    assertRateLimitSpec('failedAuthPerAddress', failedAuthPerAddress);
+    warnIfClientIpHeaderUnpinned();
+    return {
+        perAddress: bootRateLimiter(perAddress),
+        callerLimiter: perCaller === undefined ? undefined : limiterFor(perCaller),
+        failedAuthLimiter: limiterFor(failedAuthPerAddress),
+    };
+}
+function createStoreHolder(hippoRoot, store) {
+    if (store.kind !== 'sqlite') {
+        log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
+        return { hold: () => { }, afterResponse: () => { }, release: async () => { } };
+    }
+    // Handlers open and close their own connections; while this one is held, none of those closes is SQLite's last,
+    // which checkpoints and deletes the WAL. It opens only once the store exists, so serving never creates one.
+    let heldDb;
+    let checkpointer;
+    let stopHolding = false;
+    const hold = () => {
+        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 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));
+        }
+        catch (err) {
+            stopHolding = true;
+            log.warn(`serve: could not hold a store connection; requests still work, only slower: ${errorMessage(err)}`);
+        }
+    };
+    const afterResponse = () => {
+        hold();
+        checkpointer?.noteResponse();
+    };
+    const release = async () => {
+        stopHolding = true;
+        // The worker's connection closes first, so the held one is SQLite's last and its close checkpoints and deletes the WAL.
+        await checkpointer?.stop();
+        if (heldDb)
+            closeHippoDb(heldDb);
+        heldDb = undefined;
+    };
+    return { hold, afterResponse, release };
+}
+// A plugin's resolver may read hippo.db through this package's synchronous functions, so it runs outside the block of a `loop: 'off'` route.
+function outsideRouteBlock(resolver) {
+    return resolver && ((token) => outsideSqliteOffLoop(() => resolver(token)));
+}
+function replyWithFailure(req, res, err, requestId) {
+    const mapped = replyFor(err);
+    logRequestFailure(req, err, mapped.status);
+    if (res.headersSent) {
+        try {
+            res.end();
+        }
+        catch { /* socket already gone */ }
+        return;
+    }
+    if (isStoreBusy(err))
+        res.setHeader('Retry-After', '1');
+    else if (err instanceof HttpError && err.retryAfterSec !== undefined)
+        res.setHeader('Retry-After', String(err.retryAfterSec));
+    if (mapped.status === 500) {
+        // The id lets an operator find the logged cause without the client seeing internal text.
+        sendJson(res, 500, { error: mapped.message, requestId });
+        return;
+    }
+    // RecallContractError keeps the shared {error} shape and adds `code` so clients branch without parsing prose.
+    if (err instanceof RecallContractError) {
+        sendJson(res, 400, { error: err.message, code: err.code });
+        return;
+    }
+    if (err instanceof DeadlineExceededError) {
+        sendJson(res, 504, { error: err.message, code: err.code, requestId });
+        return;
+    }
+    // readBody hit its cap or deadline, so close once the 413 or 408 is out rather than drain what the client keeps sending.
+    if (err instanceof BodyTooLargeError || err instanceof BodyTimeoutError)
+        res.once('finish', () => closeAfterReply(req));
+    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)}`);
+}
+function replyOrClose(req, res, err, requestId) {
+    try {
+        replyWithFailure(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)}`);
+        res.destroy();
+    }
+}
+/** Runs `handle` under the request's id and deadline; a failure becomes the reply, unless the deadline has already answered. */
+function answerRequest(req, res, handle, slowWarnMs) {
+    const requestId = openRequest(req, res, slowWarnMs);
+    const deadline = requestDeadlineFor(req);
+    // Inside the scope, so the failure reply's log line carries the id too.
+    runWithRequestId(requestId, () => {
+        if (deadline)
+            answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId));
+        handle().catch((err) => {
+            if (isAbandoned(res))
+                logLateFailure(req, err);
+            else
+                replyOrClose(req, res, 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) => {
+            server.removeListener('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            // With no listener, an 'error' event after boot is an uncaught exception that stops the server for every caller.
+            server.on('error', (err) => log.error(`serve: listener error: ${err.message}`, errorFields(err)));
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        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'); });
+}
+/**
+ * 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.
+ */
+export async function serve(opts) {
+    const host = opts.host ?? '127.0.0.1';
+    const requestedPort = opts.port ?? Number(envPort() ?? 6789);
+    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.
+    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();
+    const served = servedOptsFor(opts, routes, publicJsonBodies, limiters);
+    // A store other than hippo.db is a team's central server, so its folder's config.json must not decide shared-ness.
+    if (served.store.kind !== 'sqlite')
+        markSharedStore(opts.hippoRoot);
+    const holder = createStoreHolder(opts.hippoRoot, served.store);
+    const inflight = new Set();
+    const server = acceptingServer(served, holder, inflight, { startedAt, streamSlots, limiter: limiters.perAddress });
+    setKeepAliveTimeouts(server);
+    const { port: actualPort, url } = await listenAndDescribe(server, requestedPort, host, opts.tls);
+    writePidfile(opts.hippoRoot, { port: actualPort, url, startedAt });
+    holder.hold();
+    let stopping = false;
+    const stop = async () => {
+        if (stopping)
+            return;
+        stopping = true;
+        await stopListening(opts, server, inflight, startedAt);
+        // The store's worker threads close their connections first, so the held one is still SQLite's last.
+        if (!opts.store)
+            await served.store.close();
+        await holder.release();
+    };
+    if (opts.handleSignals) {
+        installSignalHandlers(stop);
+        installCrashHandlers('serve', stop);
+    }
+    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 })));
+    assertAddonRoutes(routes);
+    return routes;
+}
+function servedOptsFor(opts, routes, publicJsonBodies, { callerLimiter, failedAuthLimiter }) {
+    return {
+        ...opts, routes, publicJsonBodies, store: opts.store ?? workerSqliteStore(opts.hippoRoot), callerLimiter, failedAuthLimiter,
+        authResolver: outsideRouteBlock(opts.authResolver),
+    };
+}
+function acceptingServer(served, holder, inflight, options) {
+    const { kind } = served.store;
+    return createListener(served.tls, (req, res) => {
+        res.once('finish', holder.afterResponse);
+        inflight.add(res);
+        res.once('close', () => inflight.delete(res));
+        const run = () => handleRequest(req, res, served, options);
+        // A missed port under another store would otherwise create and write a hippo.db that store never reads.
+        answerRequest(req, res, () => (kind === 'sqlite' ? run() : withSqliteBlocked(kind, run)), served.slowRequestWarnMs);
+    });
+}
+async function listenAndDescribe(server, port, host, tls) {
+    await listenOn(server, port, host);
+    const address = server.address();
+    if (!isAddressInfo(address)) {
+        throw new Error('server.address() returned unexpected shape');
+    }
+    const addressInfo = address;
+    const actualPort = addressInfo.port;
+    const url = `${tls ? 'https' : 'http'}://${host.includes(':') ? `[${host}]` : host}:${actualPort}`;
+    warnIfCleartext(host, tls, LOOPBACK_HOSTS);
+    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.
+    removePidfileIfOwned(opts.hippoRoot, { pid: process.pid, startedAt });
+    await drainAndClose(server, inflight, opts.shutdownDrainMs ?? 5000);
+}
+//# sourceMappingURL=boot.js.map

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

@@ -1,5 +1,5 @@
 import type { IncomingMessage } from 'node:http';
-import type { RateLimiter } from '../rate-limit.js';
+import type { RateLimiter } from './rate-limit.js';
 /**
  * Rate-limit key for a request. Defaults to the socket's remote address.
  *
@@ -21,7 +21,11 @@ import type { RateLimiter } from '../rate-limit.js';
  * the client sent, so they never pick the bucket.
  */
 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;
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
 export declare function subscriberKey(ip: string): string;
+/** The one key every per-address limit and slot count uses, so rotating inside a /64 never buys a fresh bucket. */
+export declare function clientLimitKey(req: IncomingMessage): string;
 export declare function enforceRateLimit(req: IncomingMessage, path: string, limiter?: RateLimiter): void;
 //# sourceMappingURL=client-ip.d.ts.map

package/dist/server/client-ip.js

@@ -1,8 +1,9 @@
 // Client IP keying and the per-IP rate limit for /v1 and /mcp.
-import { envClientIpHeader, envTrustedProxies } from '../env.js';
+import { envClientIpHeader, envTrustedProxies } from '../util/env.js';
 import { BlockList, isIP } from 'node:net';
-import { log } from '../log.js';
-import { HttpError } from '../http-util.js';
+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.
  *
@@ -67,6 +68,14 @@ function trustedProxyList(raw) {
     trustedProxyCache = { raw, list };
     return list;
 }
+/** 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 function warnIfClientIpHeaderUnpinned() {
+    const header = envClientIpHeader();
+    if (!header || trustedProxyList(envTrustedProxies()))
+        return;
+    log.warn(`serve: HIPPO_CLIENT_IP_HEADER is ${header} and HIPPO_TRUSTED_PROXIES is unset, so any caller that reaches this port without passing the proxy can send that header and pick its own rate-limit bucket. ` +
+        "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, so the header is read from the proxy alone.");
+}
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
 export function subscriberKey(ip) {
     const bare = ip.split('%')[0];
@@ -80,7 +89,11 @@ export function subscriberKey(ip) {
     // A trailing dotted quad holds two groups; isIP has already checked the shape.
     const rightGroups = right.length + (right.at(-1)?.includes('.') ? 1 : 0);
     const groups = tail === undefined ? left : [...left, ...Array(8 - left.length - rightGroups).fill('0'), ...right];
-    return `${groups.slice(0, 4).map((g) => parseInt(g, 16).toString(16)).join(':')}::/64`;
+    return `${groups.slice(0, IPV6_PREFIX_GROUPS).map((g) => parseInt(g, 16).toString(16)).join(':')}::/64`;
+}
+/** The one key every per-address limit and slot count uses, so rotating inside a /64 never buys a fresh bucket. */
+export function clientLimitKey(req) {
+    return subscriberKey(clientIpForRateLimit(req));
 }
 function isTrustedProxy(list, ip) {
     const bare = ip.startsWith('::ffff:') && isIP(ip.slice(7)) === 4 ? ip.slice(7) : ip;
@@ -98,8 +111,7 @@ export function enforceRateLimit(req, path, limiter) {
     // HIPPO_CLIENT_IP_HEADER there so each real client gets its own bucket
     // (see clientIpForRateLimit).
     if (limiter && (path.startsWith('/v1/') || path === '/mcp' || path === '/mcp/stream')) {
-        const ip = clientIpForRateLimit(req);
-        if (!limiter.check(ip)) {
+        if (!limiter.check(clientLimitKey(req))) {
             throw new HttpError(429, 'rate limit exceeded', limiter.retryAfterSec);
         }
     }

package/dist/server/cursor.d.ts

@@ -1,5 +1,5 @@
 import type { ServerResponse } from 'node:http';
-import type { KeysetPosition } from '../keyset.js';
+import type { KeysetPosition } from '../util/keyset.js';
 type CursorPart = 'string' | 'integer';
 /** Bare-array routes cannot grow a body field without breaking clients, so their next cursor rides this header. */
 export declare const NEXT_CURSOR_HEADER = "X-Next-Cursor";

package/dist/server/cursor.js

@@ -1,6 +1,5 @@
-import { HttpError } from '../http-util.js';
-import { isJsonNumber } from './validation.js';
-import { isJsonString } from '../json.js';
+import { HttpError } from '../util/http-util.js';
+import { isJsonString, isJsonNumber } from '../util/json.js';
 /** Bare-array routes cannot grow a body field without breaking clients, so their next cursor rides this header. */
 export const NEXT_CURSOR_HEADER = 'X-Next-Cursor';
 const MAX_CURSOR_CHARS = 1024;

package/dist/server/deadline.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { RequestDeadline } from '../util/request-scope.js';
+/** Requests answered 504 by the handler deadline since the process started; /health reports it. */
+export declare function handlerDeadlineCount(): number;
+/** Whether `res` was answered at its deadline, so whatever its handler does later has no caller. */
+export declare function isAbandoned(res: ServerResponse): boolean;
+/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
+export declare function requestDeadlineMs(): number;
+/** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
+export declare function requestDeadlineFor(req: IncomingMessage): RequestDeadline | undefined;
+/** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */
+export declare function answerAtDeadline(res: ServerResponse, deadline: RequestDeadline, reply: () => void): void;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/server/deadline.js

@@ -0,0 +1,45 @@
+import { envRequestDeadlineMs } from '../util/env.js';
+import { RequestDeadline } from '../util/request-scope.js';
+const DEFAULT_REQUEST_DEADLINE_MS = 120_000;
+// Each has a deadline of its own kind: sleep stops its child process, and the stream is meant to stay open.
+const EXEMPT = new Set(['POST /v1/sleep', 'GET /mcp/stream']);
+const abandoned = new WeakSet();
+let handlerDeadlines = 0;
+/** Requests answered 504 by the handler deadline since the process started; /health reports it. */
+export function handlerDeadlineCount() {
+    return handlerDeadlines;
+}
+/** Whether `res` was answered at its deadline, so whatever its handler does later has no caller. */
+export function isAbandoned(res) {
+    return abandoned.has(res);
+}
+/** How long a request may run: 120 s, or HIPPO_REQUEST_DEADLINE_MS, where 0 turns the deadline off. */
+export function requestDeadlineMs() {
+    return envRequestDeadlineMs() ?? DEFAULT_REQUEST_DEADLINE_MS;
+}
+/** The deadline of `req`, for every /v1 and /mcp route but the two exempt ones. */
+export function requestDeadlineFor(req) {
+    const ms = requestDeadlineMs();
+    const path = (req.url ?? '/').split('?')[0] ?? '/';
+    if (ms === 0 || EXEMPT.has(`${req.method ?? 'GET'} ${path}`))
+        return undefined;
+    return path.startsWith('/v1/') || path === '/mcp' ? new RequestDeadline(Date.now() + ms) : undefined;
+}
+/** Calls `reply` when `res` has sent nothing by `deadline`. A store call still in flight answers first, since only the store knows what became of a write. */
+export function answerAtDeadline(res, deadline, reply) {
+    const expire = () => {
+        if (res.headersSent || res.destroyed)
+            return;
+        handlerDeadlines += 1;
+        abandoned.add(res);
+        reply();
+    };
+    // One turn of the loop later, so a handler that fails on the store's answer sends that answer itself.
+    const timer = setTimeout(() => deadline.onceIdle(() => setImmediate(expire)), deadline.at - Date.now());
+    // The open socket keeps the process alive; this timer alone must not.
+    timer.unref();
+    const clear = () => clearTimeout(timer);
+    res.once('finish', clear);
+    res.once('close', clear);
+}
+//# sourceMappingURL=deadline.js.map

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

@@ -0,0 +1,8 @@
+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). */
+    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>;
+}
+export declare function keyCheckBounds(maxKeys: number): KeyCheckBounds;
+//# sourceMappingURL=key-check-bounds.d.ts.map