hippo-memory 2.0.0 → 2.1.0

package/dist/server/auth.js

@@ -1,6 +1,8 @@
 // Bearer and loopback auth for the HTTP server.
 import { envAllowKeylessLocal, envKeylessLocalRole, envRequireAuth } from '../util/env.js';
+import { loadConfig } from '../core/config.js';
 import { resolveTenantId } from '../store/tenant.js';
+import { sqliteReach } from '../store/sqlite/store.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { API_KEY_PREFIX, verifyApiKeyCached } from '../store/auth.js';
 import { ownerOrSubject } from '../api/index.js';
@@ -9,38 +11,40 @@ import { MAX_ID_LEN } from '../util/limits.js';
 import { clientLimitKey } from './client-ip.js';
 import { keyCheckBounds } from './key-check-bounds.js';
 import { isJsonString } from '../util/json.js';
-/** Recognises loopback remote addresses, including the IPv6-mapped '::ffff:127.0.0.1' Node reports on dual-stack sockets; anything else is remote. */
-export function isLoopback(remoteAddress) {
-    if (!remoteAddress)
-        return false;
-    if (remoteAddress === '127.0.0.1')
-        return true;
-    if (remoteAddress === '::1')
-        return true;
-    if (remoteAddress === '::ffff:127.0.0.1')
-        return true;
-    return false;
-}
-// A proxy on this host (nginx, Caddy, cloudflared) connects from loopback, so these headers mean the caller is not local.
+import { MINUTE_MS } from '../util/time.js';
+import { isLoopbackAddress } from '../util/net.js';
+/** Kept under its old name because src/server.ts publishes it. */
+export const isLoopback = isLoopbackAddress;
+// A proxy on this host (nginx, Caddy, cloudflared) connects
+// from loopback, so these headers mean the caller is not local.
 const PROXY_HEADERS = [
-    'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
+    'forwarded',
+    'x-forwarded-for',
+    'x-forwarded-host',
+    'x-forwarded-proto',
+    'x-real-ip',
+    'cf-connecting-ip',
+    'true-client-ip',
     'fly-client-ip',
 ];
 function proxyHeaderOf(req) {
     return PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
 }
-/** A page in a browser on this machine: another site's request, or a hostile name resolved to loopback (DNS rebinding). */
+/** A page in a browser on this machine: another site's request,
+ * or a hostile name resolved to loopback (DNS rebinding). */
 function isForeignPage(req) {
     const host = req.headers.host;
     return (host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req);
 }
-/** True only for a request made on this machine by its own user: a proxy and a browser page are loopback too, so the socket alone proves nothing. */
+/** True only for a request made on this machine by its own user: a proxy and a browser page are loopback too, so the
+ * socket alone proves nothing. */
 export function isLocalCaller(req) {
-    return isLoopback(req.socket.remoteAddress) && proxyHeaderOf(req) === undefined && !isForeignPage(req);
+    return isLoopbackAddress(req.socket.remoteAddress) && proxyHeaderOf(req) === undefined && !isForeignPage(req);
 }
-// The throwing twin of isLocalCaller, for the no-key fallback: each refusal has its own status, and a proxied one is logged.
+// The throwing twin of isLocalCaller, for the no-key fallback:
+// each refusal has its own status, and a proxied one is logged.
 function assertLocalCaller(req) {
-    if (!isLoopback(req.socket.remoteAddress))
+    if (!isLoopbackAddress(req.socket.remoteAddress))
         throw new HttpError(401, 'auth required');
     const proxyHeader = proxyHeaderOf(req);
     if (proxyHeader !== undefined) {
@@ -52,10 +56,11 @@ function assertLocalCaller(req) {
         throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
     }
 }
-/** The 401 a keyless request from this machine gets by default; it names both fixes, since an upgrade is where most people meet it. */
+/** The 401 a keyless request from this machine gets by default; it names both fixes, since an upgrade is where most
+ * people meet it. */
 const KEY_REQUIRED_MESSAGE = 'auth required: this server takes no request without an API key. Mint one with `hippo auth create` and send it as ' +
-    '"Authorization: Bearer <key>" (the hippo CLI reads HIPPO_API_KEY), or start the server with HIPPO_ALLOW_KEYLESS_LOCAL=1 ' +
-    'to let requests from this machine in without a key.';
+    '"Authorization: Bearer <key>" (the hippo CLI reads HIPPO_API_KEY), or start the server with ' +
+    'HIPPO_ALLOW_KEYLESS_LOCAL=1 to let requests from this machine in without a key.';
 export function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -149,7 +154,8 @@ async function askResolver(resolver, token, deadlineMs) {
     return clean;
 }
 const DEFAULT_RESOLVER_DEADLINE_MS = 5000;
-/** Runs only before scrypt, so junk, unknown, revoked and expired tokens and a proven key's re-check never spend a colleague's budget. */
+/** Runs only before scrypt, so junk, unknown, revoked and expired
+ * tokens and a proven key's re-check never spend a colleague's budget. */
 function chargeScryptRun(req, opts) {
     const limiter = opts.failedAuthLimiter;
     // Reserving rather than peeking bounds scrypt runs exactly, even when concurrent misses await a slow store.
@@ -164,17 +170,24 @@ async function resolveBearer(req, token, opts) {
         const t = opts.authResolverTimeoutMs;
         const deadlineMs = t !== undefined && Number.isFinite(t) && t > 0 ? t : DEFAULT_RESOLVER_DEADLINE_MS;
         const clean = await askResolver(opts.authResolver, token, deadlineMs);
-        return { ...clean, viaAuthResolver: true, owner: clean.subject }; // a resolver vouches for a person, never names one
+        // A resolver vouches for a person, never names one.
+        return { ...clean, viaAuthResolver: true, owner: clean.subject };
     }
     const key = await verifyApiKeyCached(token, opts.store, (keyId, derive) => {
-        // The key's own bucket first, so a flood on one key id ends at its five tries and leaves the address's budget to the callers who share it.
+        // The key's own bucket first, so a flood on one key id ends at its five tries and leaves the address's budget to
+        // the callers who share it.
         keyChecks.admit(keyId, clientLimitKey(req));
         chargeScryptRun(req, opts);
         return keyChecks.run(derive);
     });
     if (!key)
         throw new HttpError(401, 'invalid api key');
-    const id = { tenantId: key.tenantId, subject: `api_key:${key.keyId}`, role: key.role, scopes: key.scopes };
+    const id = {
+        tenantId: key.tenantId,
+        subject: `api_key:${key.keyId}`,
+        role: key.role,
+        scopes: key.scopes,
+    };
     if (key.ownerSubject)
         id.owner = key.ownerSubject;
     return id;
@@ -213,7 +226,7 @@ function bearerActor(id) {
 export const LIMITER_MAX_KEYS = 10_000;
 // One for the process, as the thread pool its derivations run on is.
 const keyChecks = keyCheckBounds(LIMITER_MAX_KEYS);
-const CALLER_WARN_EVERY_MS = 60_000;
+const CALLER_WARN_EVERY_MS = MINUTE_MS;
 const callerWarnedAt = new Map();
 function warnCallerLimited(key, tenantId, person) {
     const now = Date.now();
@@ -240,8 +253,8 @@ function chargeCaller(tenantId, actor, opts) {
     warnCallerLimited(key, tenantId, person);
     throw new HttpError(429, 'rate limit exceeded for this caller', limiter.retryAfterSec);
 }
-/** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) for invalid or missing credentials.
- * Reads the store only for an API-key-shaped Bearer (or any Bearer when no auth resolver is registered), so keyless local requests stay cheap. */
+/** Builds a per-request Context from the Authorization header and remote address; throws HttpError(401) on bad ones.
+ * Reads the store only for an API-key-shaped Bearer (or any Bearer with no resolver), so keyless calls stay cheap. */
 export async function buildContextWithAuth(req, opts) {
     const id = await checkAuth(req, opts);
     const ctx = contextFor(id, opts);
@@ -249,28 +262,46 @@ export async function buildContextWithAuth(req, opts) {
         chargeCaller(id.tenantId, ctx.actor, opts);
     return ctx;
 }
-/** The auth check again, uncharged, for a handler that authenticated with requireAuth before a slow body read and must re-check right before it acts. */
+/** The auth check again, uncharged, for a handler that authenticated with requireAuth before a slow body read and
+ * must re-check right before it acts. */
 export async function recheckContextWithAuth(req, opts) {
     return contextFor(await checkAuth(req, opts), opts);
 }
-/** The keyless local caller: any process on this machine can reach loopback, so it is a member unless the operator names admin. */
+/** The keyless local caller: any process on this machine can reach
+ * loopback, so it is a member unless the operator names admin. */
 function keylessLocalActor(opts) {
     const role = opts.keylessLocalRole ?? envKeylessLocalRole();
-    return role === 'admin' ? { subject: 'localhost:cli', role: 'admin', hostAdmin: true } : { subject: 'localhost:cli', role: 'member' };
+    return role === 'admin'
+        ? { subject: 'localhost:cli', role: 'admin', hostAdmin: true }
+        : { subject: 'localhost:cli', role: 'member' };
 }
 function contextFor(id, opts) {
-    if (id !== null)
-        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor: bearerActor(id), store: opts.store };
-    return { hippoRoot: opts.hippoRoot, tenantId: resolveTenantId({}), actor: keylessLocalActor(opts), store: opts.store };
+    // Per request, never cached at serve: the global store can be created while the server runs.
+    const reach = sqliteReach(opts.hippoRoot, opts.store);
+    // loadConfig caches by file mtime, so each request still sees an edit made while the server runs.
+    const config = loadConfig(opts.hippoRoot);
+    if (id !== null) {
+        const actor = bearerActor(id);
+        return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor, store: opts.store, reach, config };
+    }
+    return {
+        hippoRoot: opts.hippoRoot,
+        tenantId: resolveTenantId({}),
+        actor: keylessLocalActor(opts),
+        store: opts.store,
+        reach,
+        config,
+    };
 }
-/** Auth check for routes that need no tenant Context (e.g. the MCP transport, which resolves its own root): throws HttpError 401 like buildContextWithAuth.
- * A keyless local request passes only under HIPPO_ALLOW_KEYLESS_LOCAL=1. */
+/** Auth check for routes that need no tenant Context (e.g. the MCP transport, which resolves its own root): throws
+ * HttpError 401 like buildContextWithAuth. A keyless local request passes only under HIPPO_ALLOW_KEYLESS_LOCAL=1. */
 export async function requireAuth(req, opts) {
     const id = await checkAuth(req, opts);
     if (id !== null)
         chargeCaller(id.tenantId, bearerActor(id), opts);
 }
-/** Never rejects or charges a caller bucket: an outage (5xx) or a throttle (429) skips one tick; only a definite 4xx denial closes the stream. */
+/** Never rejects or charges a caller bucket: an outage (5xx) or a throttle (429) skips one tick; only a definite 4xx
+ * denial closes the stream. */
 export async function heartbeatVerdict(req, opts) {
     try {
         await checkAuth(req, opts);

package/dist/server/boot.d.ts

@@ -1,5 +1,7 @@
 import type { ServeOpts, ServerHandle } from './types.js';
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless HIPPO_REQUIRE_AUTH=1 and
+/**
+ * Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless
+ * HIPPO_REQUIRE_AUTH=1 and
  * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export declare function serve(opts: ServeOpts): Promise<ServerHandle>;

package/dist/server/boot.js

@@ -1,18 +1,18 @@
 import { envAllowCleartext, envCallerRps, envPort, envRequireAuth, envV1Rps } from '../util/env.js';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
-import { outsideSqliteOffLoop, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from '../db/index.js';
 import { hasGroup } from '../store/index.js';
-import { isStoreBusy } from '../store/sqlite/busy.js';
-import { holdSqliteConnection } from '../store/sqlite/held-connection.js';
+import { isStoreBusy } from '../api/busy.js';
+import { createStoreHolder, offLoopFor, outsideRouteBlock, } from '../store/sqlite/held-connection.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 { MINUTE_MS } from '../util/time.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 { 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 { isLocalCaller, LIMITER_MAX_KEYS } from './auth.js';
 import { assertClientIpHeaderPinned, enforceRateLimit } from './client-ip.js';
@@ -23,7 +23,7 @@ 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 { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError } from './request.js';
+import { accessRouteOf, logRequestFailure, noteAccess, openRequest, parseRequest, rejectEncodedSlash, replyFor, sendError, } from './request.js';
 import { assertTlsOrCleartextAllowed, createListener } from './tls.js';
 import { assertAddonRoutes, assertPublicJson } from './route-checks.js';
 import { dispatchAddonRoute, dispatchPublicJson, dispatchV1Route } from './route-table.js';
@@ -32,7 +32,8 @@ import { dispatchAddonRoute, dispatchPublicJson, dispatchV1Route } from './route
 function isAddressInfo(a) {
     return a !== null && typeof a !== 'string';
 }
-// Pinned at module load, bumped with package.json on releases; reading package.json synchronously here would couple the daemon to its install path,
+// 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']);
@@ -42,7 +43,8 @@ async function handleRequest(req, res, opts, options) {
     // 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.
+    // 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') {
@@ -57,19 +59,22 @@ async function handleRequest(req, res, opts, options) {
     }
     enforceRateLimit(req, path, limiter);
     const routeRequest = { req, res, opts, query };
-    if (await runWithRequestStores(() => dispatchScopedRoute(routeRequest, method, path), { busyWaitMs: SERVER_DB_WAIT_MS }))
+    if (await dispatchScopedRoute(routeRequest, method, path))
         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.
+    // The request scope (the server's lock wait) is kept by the heartbeat timer after it closes, so the key check and
+    // every heartbeat wait that long. 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 });
+        await handleMcpStream(req, res, opts, streamSlots);
         return;
     }
     res.writeHead(404, JSON_HEADERS);
     res.end(JSON.stringify({ error: 'not found' }));
 }
-/** Every route that runs inside a request scope, so it opens each store once: the /v1 table with the webhooks, public JSON, add-on routes and POST /mcp. */
+/**
+ * Every route that runs inside a request scope, so it opens each store once: the /v1 table with the webhooks, public
+ * JSON, add-on routes and POST /mcp.
+ */
 async function dispatchScopedRoute(r, method, path) {
     if (await dispatchV1Route(r, method, path))
         return true;
@@ -87,8 +92,10 @@ async function dispatchScopedRoute(r, method, path) {
     return false;
 }
 function sendHealth(req, res, startedAt) {
-    // 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.
+    // 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,
@@ -128,7 +135,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 and unlinks a stale 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) {
@@ -136,35 +144,47 @@ async function assertNoLiveServer(hippoRoot) {
             `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.
+// 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 });
+    return createRateLimiter({ ratePerSec, burst, idleEvictMs: MINUTE_MS, 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 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;
+    // 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 typo must not switch the limit off, so only an explicit 0 does.
+    const raw = envV1Rps();
+    const v1Rps = raw === undefined ? 20 : Number(raw);
+    if (!Number.isFinite(v1Rps) || v1Rps < 0) {
+        throw new Error(`HIPPO_V1_RPS must be a number of at least 0 (0 turns the per-address limit off), not '${raw}'`);
+    }
+    return 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)
+    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)
+    }
+    if (!Number.isFinite(burst) || burst < 1) {
         throw new Error(`rateLimits.${name}.burst must be a finite number of at least 1`);
+    }
 }
 const DEFAULT_CALLER_RPS = 20;
-/** The per-caller spec when serve() names none: HIPPO_CALLER_RPS (0 is off), else 20 per second with a burst of twice that. */
+/**
+ * The per-caller spec when serve() names none: HIPPO_CALLER_RPS (0 is off), else 20 per second with a burst of twice
+ * that.
+ */
 function defaultCallerSpec() {
     const raw = envCallerRps();
     const rps = raw === undefined ? DEFAULT_CALLER_RPS : Number(raw);
     // A typo must not switch the limit off, so only an explicit 0 does.
-    if (!Number.isFinite(rps) || rps < 0)
+    if (!Number.isFinite(rps) || rps < 0) {
         throw new Error(`HIPPO_CALLER_RPS must be a number of at least 0 (0 turns the per-caller limit off), not '${raw}'`);
+    }
     return rps === 0 ? 'off' : { ratePerSec: rps, burst: Math.max(1, rps * 2) };
 }
 /** Refuses a bad spec at boot, since a NaN or zero rate would otherwise turn a bucket off or refuse every request. */
@@ -182,17 +202,6 @@ function bootLimiters(rateLimits) {
         failedAuthLimiter: limiterFor(failedAuthPerAddress),
     };
 }
-function createStoreHolder(hippoRoot, store) {
-    if (hasGroup(store, 'localFiles'))
-        return holdSqliteConnection(hippoRoot);
-    log.info(`serve: the '${store.kind}' store serves ${hippoRoot}, so no hippo.db connection is held`);
-    // A missed port under another store would otherwise create and write a hippo.db that store never reads.
-    return { hold: () => { }, afterResponse: () => { }, release: async () => { }, runRequest: (run) => withSqliteBlocked(store.kind, run) };
-}
-// 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);
@@ -203,10 +212,12 @@ function replyWithFailure(req, res, err, requestId) {
         catch { /* socket already gone */ }
         return;
     }
-    if (isStoreBusy(err))
+    if (isStoreBusy(err)) {
         res.setHeader('Retry-After', '1');
-    else if (err instanceof HttpError && err.retryAfterSec !== undefined)
+    }
+    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 });
@@ -221,29 +232,43 @@ function replyWithFailure(req, res, err, requestId) {
         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)
+    // 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 this line is the only trace of the failure. The path and the error text can hold caller data, so it carries neither.
+// 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 };
+    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.
+// 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.
+// 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) });
+    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 {
@@ -255,14 +280,19 @@ function replyOrClose(req, res, err, requestId) {
         res.destroy();
     }
 }
-/** Runs `handle` under the request's id and deadline; a failure becomes the reply, unless the deadline has already answered. */
+/**
+ * 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);
+    const abort = deadline ? new AbortController() : undefined;
     // 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));
+        if (deadline) {
+            answerAtDeadline(res, deadline, () => replyOrClose(req, res, new DeadlineExceededError(HANDLER_LATE), requestId), () => abort?.abort(new DeadlineExceededError(HANDLER_LATE)));
+        }
         handle().then(() => {
             if (isAbandoned(res))
                 logLateFinish(req, requestId);
@@ -274,7 +304,7 @@ function answerRequest(req, res, handle, slowWarnMs) {
             else
                 logLateFailure(req, err, requestId);
         });
-    }, deadline);
+    }, deadline, abort?.signal);
 }
 function listenOn(server, port, host) {
     return new Promise((resolve, reject) => {
@@ -298,7 +328,9 @@ function exitOnSignalOrCrash(stop, drainMs) {
     installSignalHandlers('serve', shutdown);
     installCrashHandlers('serve', shutdown);
 }
-/** Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless HIPPO_REQUIRE_AUTH=1 and
+/**
+ * Boots the HTTP daemon on host:port and writes the pidfile under hippoRoot; refuses a non-loopback host unless
+ * HIPPO_REQUIRE_AUTH=1 and
  * either `tls` or allowCleartext is given, and refuses HIPPO_CLIENT_IP_HEADER without HIPPO_TRUSTED_PROXIES.
  * Use port: 0 in tests for an ephemeral port. See docs/ARCHITECTURE.md#srcserverbootts. */
 export async function serve(opts) {
@@ -310,7 +342,8 @@ export async function serve(opts) {
     assertBindable(host);
     assertTlsOrCleartextAllowed(host, opts.tls, LOOPBACK_HOSTS, opts.allowCleartext ?? envAllowCleartext());
     await assertNoLiveServer(opts.hippoRoot);
-    // 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
+    // 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.
@@ -343,15 +376,20 @@ export async function serve(opts) {
 }
 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;
 }
 function servedOptsFor(opts, routes, publicJsonBodies, { callerLimiter, failedAuthLimiter }) {
+    const store = opts.store ?? workerSqliteStore(opts.hippoRoot);
     return {
-        ...opts, routes, publicJsonBodies, store: opts.store ?? workerSqliteStore(opts.hippoRoot), callerLimiter, failedAuthLimiter,
+        ...opts,
+        routes,
+        publicJsonBodies,
+        store,
+        offLoop: offLoopFor(store),
+        callerLimiter,
+        failedAuthLimiter,
         authResolver: outsideRouteBlock(opts.authResolver),
     };
 }
@@ -375,7 +413,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 rewritten it, and an unconditional unlink 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 ?? DEFAULT_SHUTDOWN_DRAIN_MS);
 }

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

@@ -1,11 +1,18 @@
 import type { IncomingMessage } from 'node:http';
 import type { RateLimiter } from './rate-limit.js';
 /**
- * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
- * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*` for any peer),
- * so a caller that reaches the port past the proxy cannot pick its own bucket. In a comma-joined chain the key is the rightmost hop no trusted proxy added. */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated
+ * traffic can drain.
+ * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*`
+ * for any peer),
+ * so a caller that reaches the port past the proxy cannot pick its own bucket. In a comma-joined chain the key is the
+ * rightmost hop no trusted proxy added.
+ */
 export declare function clientIpForRateLimit(req: IncomingMessage): string;
-/** serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the setting is a mistake. */
+/**
+ * serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the
+ * setting is a mistake.
+ */
 export declare class UntrustedClientIpHeaderError extends Error {
     readonly header: string;
     constructor(header: string);

package/dist/server/client-ip.js

@@ -5,9 +5,13 @@ import { log } from '../util/log.js';
 import { HttpError } from '../util/http-util.js';
 const IPV6_PREFIX_GROUPS = 4;
 /**
- * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated traffic can drain.
- * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*` for any peer),
- * so a caller that reaches the port past the proxy cannot pick its own bucket. In a comma-joined chain the key is the rightmost hop no trusted proxy added. */
+ * Rate-limit key: the socket's remote address, which behind a TLS proxy collapses into one bucket unauthenticated
+ * traffic can drain.
+ * HIPPO_CLIENT_IP_HEADER (fly-client-ip on Fly) is read only from a peer in HIPPO_TRUSTED_PROXIES (IPs or CIDRs, or `*`
+ * for any peer),
+ * so a caller that reaches the port past the proxy cannot pick its own bucket. 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();
@@ -57,12 +61,17 @@ function proxyTrust(raw) {
     trustedProxyCache = { raw: value, list };
     return list;
 }
-/** serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the setting is a mistake. */
+/**
+ * serve() refused HIPPO_CLIENT_IP_HEADER with no HIPPO_TRUSTED_PROXIES: the header would be read from no one, so the
+ * setting is a mistake.
+ */
 export class UntrustedClientIpHeaderError extends Error {
     header;
     constructor(header) {
-        super(`hippo serve: HIPPO_CLIENT_IP_HEADER is ${header} but HIPPO_TRUSTED_PROXIES is unset, so no peer may set that header. ` +
-            "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, or to * when the proxy is the only peer that can reach this port.");
+        super(`hippo serve: HIPPO_CLIENT_IP_HEADER is ${header} but HIPPO_TRUSTED_PROXIES is unset, so no peer may set that ` +
+            `header. ` +
+            "Set HIPPO_TRUSTED_PROXIES to the proxy's addresses or CIDRs, or to * when the proxy is the only peer that " +
+            "can reach this port.");
         this.header = header;
         this.name = 'UntrustedClientIpHeaderError';
     }
@@ -76,7 +85,10 @@ export function assertClientIpHeaderPinned() {
     if (trust === undefined)
         throw new UntrustedClientIpHeaderError(header);
     if (trust === ANY_PEER) {
-        log.warn(`serve: HIPPO_TRUSTED_PROXIES is *, so ${header} is read from any peer; keep the proxy the only route to this port.`);
+        log.warn(`serve: HIPPO_TRUSTED_PROXIES is *, so ${header} is read from any peer: a client that reaches this port ` +
+            `without the proxy can put any address ` +
+            `in ${header} and so escape every per-address limit. Keep the proxy the only route to this port, or list the ` +
+            `proxy's addresses instead of *.`);
     }
 }
 /** The key for one subscriber: an IPv6 address's /64, since one host may hold the whole /64; any other key as is. */
@@ -92,7 +104,10 @@ 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, IPV6_PREFIX_GROUPS).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) {
@@ -104,8 +119,10 @@ 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 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).
+    // 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);