hippo-memory 1.69.0 → 1.71.0

package/dist/server/key-check-bounds.js

@@ -0,0 +1,46 @@
+// Bounds on the scrypt work a bearer key check may start: how many derive at once, and how many one address starts for one key id.
+import { HttpError } from '../util/http-util.js';
+import { createRateLimiter } from './rate-limit.js';
+// libuv runs scrypt on a pool of four threads by default, so two stay free for file and DNS work.
+const MAX_IN_FLIGHT = 2;
+// Four rounds of two, so a burst of unproved keys waits its turn and no wait is longer than four derivations.
+const MAX_WAITING = 8;
+// Room for a mistyped or rotated secret; a secret is 160 random bits, so this bounds CPU, not guessing.
+const KEY_ADDRESS_BURST = 5;
+// One more try every 12 s: past its burst, an address starts at most five derivations a minute for one key id.
+const KEY_ADDRESS_TRIES_PER_SEC = 5 / 60;
+export function keyCheckBounds(maxKeys) {
+    // A bucket idle for a full refill is back at its burst, so dropping it then gives nothing away.
+    const idleEvictMs = (KEY_ADDRESS_BURST / KEY_ADDRESS_TRIES_PER_SEC) * 1000;
+    const perKeyAddress = createRateLimiter({ ratePerSec: KEY_ADDRESS_TRIES_PER_SEC, burst: KEY_ADDRESS_BURST, idleEvictMs, maxKeys });
+    let inFlight = 0;
+    const waiting = [];
+    return {
+        admit(keyId, address) {
+            // Each answers in the words an existing limit uses: the request limit's for a full queue, the address's scrypt bucket's for spent tries.
+            if (inFlight >= MAX_IN_FLIGHT && waiting.length >= MAX_WAITING)
+                throw new HttpError(429, 'rate limit exceeded', 1);
+            if (!perKeyAddress.check(`${keyId}\u0000${address}`)) {
+                throw new HttpError(429, 'too many key checks from this address', perKeyAddress.retryAfterSec);
+            }
+        },
+        async run(derive) {
+            if (inFlight < MAX_IN_FLIGHT)
+                inFlight++;
+            else
+                await new Promise((resolve) => { waiting.push(resolve); });
+            try {
+                return await derive();
+            }
+            finally {
+                // A waiter takes over this slot, so the count stays put across the handover and nothing slips in between.
+                const next = waiting.shift();
+                if (next)
+                    next();
+                else
+                    inFlight--;
+            }
+        },
+    };
+}
+//# sourceMappingURL=key-check-bounds.js.map

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 { log } from '../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.
- */
+import { bodyDeadlineMs } from '../util/http-util.js';
+import { log } from '../util/log.js';
+// 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.d.ts

@@ -1,11 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { Context } from '../api.js';
-import { type McpContext } from '../mcp/server.js';
-import type { CallerProject } from '../prompt-hook.js';
+import type { CallerProject } from '../api/prompt-hook.js';
 import type { ResolvedServeOpts } from './types.js';
 /** On a shared store, the caller's project from X-Hippo-Project and the comma-separated X-Hippo-Project-Aliases; any other store ignores both. */
 export declare function callerProjectFromHeaders(req: IncomingMessage, hippoRoot: string): CallerProject | undefined;
-export declare function mcpContextFor(ctx: Context, clientKey: string, autoSleep: McpContext['autoSleep'], project?: CallerProject): McpContext;
 export declare function handleMcpPost(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts): Promise<void>;
 export declare function handleMcpStream(req: IncomingMessage, res: ServerResponse, opts: ResolvedServeOpts, streamSlots: Map<string, number>): Promise<void>;
 //# sourceMappingURL=mcp-http.d.ts.map

package/dist/server/mcp-http.js

@@ -1,51 +1,29 @@
 // MCP over HTTP: POST /mcp and the GET /mcp/stream SSE keepalive.
-import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../env.js';
+import { envMcpSseHeartbeatMs, envMcpSseMaxAgeSec, envMcpSseMaxStreams } from '../util/env.js';
 import { createHash } from 'node:crypto';
-import { isSharedStore } from '../config.js';
+import { isSharedStore } from '../core/config.js';
 import { handleMcpRequest, mcpErrorResponse } from '../mcp/server.js';
-import { HttpError, isJsonObjectRecord, readBody, sendJson } from '../http-util.js';
-import { assertCallerProject } from '../project-identity.js';
+import { HttpError, readBody, sendJson } from '../util/http-util.js';
+import { assertCallerProject } from '../core/project-identity.js';
 import { buildContextWithAuth, heartbeatVerdict, readAuthHeader, requireAuth } from './auth.js';
-import { clientIpForRateLimit } from './client-ip.js';
-import { requestIds } from './request.js';
-import { isJsonString } from '../json.js';
-/**
- * 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.
- */
+import { clientLimitKey, subscriberKey } from './client-ip.js';
+import { noteAccess } from './request.js';
+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;
+/** 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'
-        ? createHash('sha256').update(auth.token).digest('hex').slice(0, 16)
+        ? createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)
         : 'noauth';
-    const addr = req.socket.remoteAddress ?? 'unknown';
+    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) {
@@ -77,7 +55,7 @@ export function callerProjectFromHeaders(req, hippoRoot) {
     assertCallerProject({ name, aliases });
     return { name, legacyName: name, aliases };
 }
-export function mcpContextFor(ctx, clientKey, autoSleep, project) {
+function mcpContextFor(ctx, clientKey, autoSleep, project) {
     const mcpCtx = {
         hippoRoot: ctx.hippoRoot,
         tenantId: ctx.tenantId,
@@ -98,12 +76,10 @@ export 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);
     const raw = await readBody(req);
     let mcpReq;
@@ -113,19 +89,18 @@ export async function handleMcpPost(req, res, opts) {
     catch {
         throw new HttpError(400, 'invalid JSON-RPC body');
     }
-    if (!isJsonObjectRecord(mcpReq) || !isJsonString(mcpReq.method)) {
+    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 {
         mcpRes = await handleMcpRequest(rpcReq, mcpContextFor(ctx, buildMcpClientKey(req), opts.autoSleep, project));
     }
     catch (err) {
-        mcpRes = mcpErrorResponse(rpcReq.id, err, requestIds.get(req));
+        mcpRes = mcpErrorResponse(rpcReq.id, err);
     }
     if (mcpRes === null) {
         // Notification — no body, 202 Accepted.
@@ -141,8 +116,8 @@ const DEFAULT_MAX_STREAMS_PER_CLIENT = 8;
 function streamSlotKey(req) {
     const auth = readAuthHeader(req);
     if (auth.kind === 'bearer')
-        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, 16)}`;
-    return `ip:${clientIpForRateLimit(req)}`;
+        return `key:${createHash('sha256').update(auth.token).digest('hex').slice(0, FINGERPRINT_HEX_CHARS)}`;
+    return `ip:${clientLimitKey(req)}`;
 }
 /** Takes a stream slot or throws 429; the slot is released once, when the response closes. */
 function acquireStreamSlot(req, res, slots) {
@@ -174,15 +149,13 @@ 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.
-    const heartbeatMs = envMcpSseHeartbeatMs() ?? 60000;
-    const maxAgeMs = (envMcpSseMaxAgeSec() ?? 3600) * 1000;
+    // 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) {
+    const heartbeatMs = envMcpSseHeartbeatMs() ?? DEFAULT_SSE_HEARTBEAT_MS;
+    const maxAgeMs = (envMcpSseMaxAgeSec() ?? DEFAULT_SSE_MAX_AGE_SEC) * 1000;
     const startedAt = Date.now();
     let closed = false;
     let checking = false;
@@ -190,14 +163,7 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
         if (closed)
             return;
         closed = true;
-        try {
-            res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);
-        }
-        catch { /* socket already gone */ }
-        try {
-            res.end();
-        }
-        catch { /* socket already gone */ }
+        endStreamWithReason(res, reason);
     };
     const ping = setInterval(() => {
         if (closed) {
@@ -239,4 +205,14 @@ export async function handleMcpStream(req, res, opts, streamSlots) {
         clearInterval(ping);
     });
 }
+function endStreamWithReason(res, reason) {
+    try {
+        res.write(`event: closed\ndata: ${JSON.stringify({ reason })}\n\n`);
+    }
+    catch { /* socket already gone */ }
+    try {
+        res.end();
+    }
+    catch { /* socket already gone */ }
+}
 //# sourceMappingURL=mcp-http.js.map

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

@@ -0,0 +1,21 @@
+/** 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`: 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;
+}
+export interface RateLimiterOpts {
+    /** Sustained refill rate in tokens per second. */
+    ratePerSec: number;
+    /** Bucket capacity — the largest burst a fresh client may spend at once. */
+    burst: number;
+    /** A bucket untouched for this many ms is dropped by the throttled sweep. */
+    idleEvictMs: number;
+    /** Hard cap on tracked keys; the least-recently-used key is evicted on overflow. */
+    maxKeys: number;
+}
+/** 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/{rate-limit.js → 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/ready.d.ts

@@ -0,0 +1,7 @@
+import type { HippoStore } from '../store/index.js';
+export type ReadyProbe = () => Promise<boolean>;
+/** The shared probe for a served store, so every request to that server draws on one remembered answer. */
+export declare function readyProbeFor(store: HippoStore, readiness: {
+    ping(): Promise<void>;
+}, now?: () => number): ReadyProbe;
+//# sourceMappingURL=ready.d.ts.map

package/dist/server/ready.js

@@ -0,0 +1,38 @@
+import { SERVER_DB_WAIT_MS, runWithRequestStores } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+// A prober must never see a 429, so the store read is bounded by remembering its answer instead of rate-limiting the route.
+const READY_WINDOW_MS = 1000;
+/** True when the store answered; one read per window whatever the caller count, and a failed read is remembered for the same window. */
+function createReadyProbe(readiness, now = Date.now) {
+    let answer;
+    let inFlight;
+    async function read() {
+        let ok = true;
+        try {
+            await runWithRequestStores(() => readiness.ping(), { busyWaitMs: SERVER_DB_WAIT_MS });
+        }
+        catch (err) {
+            log.warn(`GET /ready: the store did not answer: ${errorMessage(err)}`, errorFields(err));
+            ok = false;
+        }
+        answer = { at: now(), ok };
+        return ok;
+    }
+    return () => {
+        if (answer !== undefined && now() - answer.at < READY_WINDOW_MS)
+            return Promise.resolve(answer.ok);
+        inFlight ??= read().finally(() => { inFlight = undefined; });
+        return inFlight;
+    };
+}
+const probes = new WeakMap();
+/** The shared probe for a served store, so every request to that server draws on one remembered answer. */
+export function readyProbeFor(store, readiness, now = Date.now) {
+    let probe = probes.get(store);
+    if (probe === undefined) {
+        probe = createReadyProbe(readiness, now);
+        probes.set(store, probe);
+    }
+    return probe;
+}
+//# sourceMappingURL=ready.js.map

package/dist/server/request.d.ts

@@ -1,13 +1,22 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-/** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
-export declare function resolveRequestId(header: string | string[] | undefined): string;
 /** One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on this store, so none logs as an error. */
-export declare function logRequestFailure<E>(req: IncomingMessage, err: E, requestId: string, status: number): void;
+export declare function logRequestFailure<E>(req: IncomingMessage, err: E, status: number): void;
 /** The status and client message for a failed request; a held write lock is a retryable 503, never a 500. */
 export declare function replyFor<E>(err: E): {
     status: number;
     message: string;
 };
+/** What the route layer learned about a request, for its access line. */
+interface AccessNote {
+    route?: string;
+    tenant?: string;
+}
+/** 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;
 interface ParsedRoute {
     method: string;
@@ -16,15 +25,8 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-export declare const requestIds: WeakMap<IncomingMessage, string>;
-/**
- * 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

package/dist/server/request.js

@@ -1,29 +1,87 @@
 import { randomUUID } from 'node:crypto';
-import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db.js';
-import { errorFields, log } from '../log.js';
-import { HttpError, mapApiError, sendJson } from '../http-util.js';
+import { isStoreBusy, STORE_BUSY_MESSAGE } from '../db/index.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { HttpError, mapApiError, sendJson } from '../util/http-util.js';
 // The caller's id lands in a response header and in logs, so only a short plain token is echoed back.
 const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 /** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
-export function resolveRequestId(header) {
+function resolveRequestId(header) {
     const value = Array.isArray(header) ? undefined : header;
     return value && REQUEST_ID_RE.test(value) ? value : randomUUID();
 }
 /** One line per failed request; 4xx is the caller's mistake, a busy 503 is back-pressure and a 501 is a route not on this store, so none logs as an error. */
-export function logRequestFailure(req, err, requestId, status) {
-    const message = err instanceof Error ? err.message : String(err);
+export function logRequestFailure(req, err, status) {
+    const message = errorMessage(err);
     const line = `${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} failed: ${message}`;
-    if (isStoreBusy(err))
-        log.warn(line, { requestId, status });
+    // A 5xx that tells the caller when to retry is back-pressure too.
+    if (isStoreBusy(err) || (status >= 500 && err instanceof HttpError && err.retryAfterSec !== undefined))
+        log.warn(line, { status });
     else if (status >= 500 && status !== 501)
-        log.error(line, { requestId, status, ...errorFields(err) });
+        log.error(line, { status, ...errorFields(err) });
     else
-        log.info(line, { requestId, status });
+        log.info(line, { status });
 }
 /** The status and client message for a failed request; a held write lock is a retryable 503, never a 500. */
 export function replyFor(err) {
     return isStoreBusy(err) ? { status: 503, message: STORE_BUSY_MESSAGE } : mapApiError(err);
 }
+// Above the 30 s body deadline and the 5 s resolver deadline, so a request those govern is answered before it is called slow.
+const SLOW_REQUEST_WARN_MS = 60_000;
+/** Logs one warn when `res` has sent nothing after `afterMs`. It never ends the request
+ * or touches the reply; the timer goes when the reply finishes or the socket closes. */
+function watchSlowRequest(req, res, requestId, afterMs = SLOW_REQUEST_WARN_MS) {
+    const startedAt = Date.now();
+    const timer = setTimeout(() => {
+        // A reply already under way is a stream doing its job, not a stuck request.
+        if (res.headersSent)
+            return;
+        log.warn(`${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} is still running`, { requestId, elapsedMs: Date.now() - startedAt });
+    }, afterMs);
+    // The watchdog alone must never keep the process alive.
+    timer.unref();
+    const clear = () => clearTimeout(timer);
+    res.once('finish', clear);
+    res.once('close', clear);
+}
+const accessNotes = new WeakMap();
+// A path that matched no route is caller data, so the access line never repeats it.
+const UNMATCHED_ROUTE = 'unmatched';
+/** Names the matched route (the table's pattern, never the path sent) or the caller's tenant for the request's access line. */
+export function noteAccess(req, note) {
+    const held = accessNotes.get(req);
+    if (held)
+        Object.assign(held, note);
+}
+/** The route name the request's access line carries, for a line about the same request logged after its reply. */
+export function accessRouteOf(req) {
+    return accessNotes.get(req)?.route ?? UNMATCHED_ROUTE;
+}
+/** One info line per finished request. A path id and a query string can both hold caller data, so the line carries neither. */
+function logAccessWhenFinished(req, res, requestId) {
+    const note = {};
+    accessNotes.set(req, note);
+    const startedAt = performance.now();
+    res.once('finish', () => {
+        log.info('request', {
+            requestId,
+            method: req.method ?? 'GET',
+            route: note.route ?? UNMATCHED_ROUTE,
+            status: res.statusCode,
+            durationMs: Math.round(performance.now() - startedAt),
+            tenant: note.tenant,
+        });
+    });
+}
+/** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
+export function openRequest(req, res, slowWarnMs) {
+    const requestId = resolveRequestId(req.headers['x-request-id']);
+    res.setHeader('X-Request-Id', requestId);
+    // Memory text is caller-written, so no browser may guess a reply into HTML or script.
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    watchSlowRequest(req, res, requestId, slowWarnMs);
+    logAccessWhenFinished(req, res, requestId);
+    return requestId;
+}
 export function sendError(res, status, message) {
     sendJson(res, status, { error: message });
 }
@@ -44,14 +102,7 @@ export function parseRequest(req) {
         query: url.searchParams,
     };
 }
-/**
- * Lightweight pattern matcher for /v1/memories/:id/<action>. Avoids pulling
- * in a router dependency for the half-dozen patterns we actually use.
- *
- * Returns null if `path` does not match `pattern`. Otherwise returns an object
- * mapping each :param name to its value. Path segments are exact-matched
- * except for parameter slots.
- */
+/** Pattern matcher for /v1/memories/:id/<action> (no router dependency); null if `path` does not match, else each :param name mapped to its value. */
 function decodePathSegment(segment) {
     try {
         return decodeURIComponent(segment);
@@ -82,16 +133,8 @@ export function matchPath(pattern, path) {
     }
     return params;
 }
-// The auth helpers only see the request, so its id rides here for their log lines.
-export const requestIds = new WeakMap();
-/**
- * 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 function rejectEncodedSlash(rawUrl) {
     const queryIdx = rawUrl.indexOf('?');
     const pathname = queryIdx === -1 ? rawUrl : rawUrl.slice(0, queryIdx);

package/dist/server/route-table.d.ts

@@ -0,0 +1,15 @@
+import type { AddonRoute, ResolvedServeOpts, RouteRequest } from './types.js';
+import type { JsonValue } from '../util/json.js';
+export declare function isPublicRoute(method: string, path: string): boolean;
+/** Run the first /v1 route whose method and path match. */
+export declare function dispatchV1Route(r: RouteRequest, method: string, path: string): Promise<boolean>;
+/** Boot-time check: an add-on path must be plain, unique and not one core serves, so no add-on shadows a core route or hides from dispatch. */
+export declare function assertAddonRoutes(routes: readonly AddonRoute[]): void;
+/** Boot-time check and serialization: a public path that a core GET route serves would open that route to anyone. */
+export declare function assertPublicJson(publicJson: Readonly<Record<string, JsonValue>>): ReadonlyMap<string, string>;
+/** Core authenticates and parses before the handler runs, so an add-on route gets the same 401, 400 and 501 as a core one. */
+export declare function dispatchAddonRoute({ req, res, opts }: RouteRequest, method: string, path: string): Promise<boolean>;
+/** No auth, body read or store access, so a caller with no key gets it under any store. */
+export declare function dispatchPublicJson({ req, res, opts }: RouteRequest, method: string, path: string): boolean;
+export declare function assertSqliteStore(opts: ResolvedServeOpts): void;
+//# sourceMappingURL=route-table.d.ts.map