hippo-memory 1.72.0 → 2.1.0

package/dist/server/request.d.ts

@@ -1,5 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-/** 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. */
+/**
+ * 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, 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): {
@@ -11,11 +14,17 @@ 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. */
+/**
+ * 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. */
+/**
+ * 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 {
@@ -25,7 +34,9 @@ interface ParsedRoute {
 }
 export declare function parseRequest(req: IncomingMessage): ParsedRoute;
 export declare function matchPath(pattern: string, path: string): Record<string, string> | null;
-/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+/**
+ * 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 {};

package/dist/server/request.js

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { STORE_BUSY_MESSAGE } from '../store/port.js';
-import { isStoreBusy } from '../store/sqlite/busy.js';
+import { isStoreBusy } from '../api/busy.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
 import { mapApiError } from '../api/error-reply.js';
 import { HttpError, sendJson } from '../util/http-util.js';
+import { MINUTE_MS } from '../util/time.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. */
@@ -11,27 +12,36 @@ 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. */
+/**
+ * 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, status) {
     const message = errorMessage(err);
     const line = `${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} failed: ${message}`;
     // A 5xx that tells the caller when to retry is back-pressure too.
-    if (isStoreBusy(err) || (status >= 500 && err instanceof HttpError && err.retryAfterSec !== undefined))
+    if (isStoreBusy(err) || (status >= 500 && err instanceof HttpError && err.retryAfterSec !== undefined)) {
         log.warn(line, { status });
-    else if (status >= 500 && status !== 501)
+    }
+    else if (status >= 500 && status !== 501) {
         log.error(line, { status, ...errorFields(err) });
-    // A failed login is the one 4xx an operator needs by default; the id (never the credential) is stamped from the request scope.
-    else if (status === 401 || status === 403)
+    }
+    else if (status === 401 || status === 403) {
+        // A failed login is the one 4xx an operator needs by default; the id (never the credential) is stamped from the
+        // request scope.
         log.warn(line, { status });
-    else
+    }
+    else {
         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;
+// 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 = MINUTE_MS;
 /** 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) {
@@ -40,7 +50,10 @@ function watchSlowRequest(req, res, requestId, afterMs = SLOW_REQUEST_WARN_MS) {
         // 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 });
+        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();
@@ -51,7 +64,10 @@ function watchSlowRequest(req, res, requestId, afterMs = SLOW_REQUEST_WARN_MS) {
 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. */
+/**
+ * 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)
@@ -61,7 +77,10 @@ export function noteAccess(req, note) {
 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. */
+/**
+ * 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);
@@ -77,7 +96,10 @@ function logAccessWhenFinished(req, res, requestId) {
         });
     });
 }
-/** The request's id, after stamping the headers every reply carries and starting the slow-request watchdog and the access line. */
+/**
+ * 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);
@@ -107,7 +129,10 @@ export function parseRequest(req) {
         query: url.searchParams,
     };
 }
-/** Pattern matcher for /v1/memories/:id/<action> (no router dependency); null if `path` does not match, else each :param name mapped to its value. */
+/**
+ * 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);
@@ -138,7 +163,9 @@ export function matchPath(pattern, path) {
     }
     return params;
 }
-/** Rejects URL-encoded slashes in path segments BEFORE the URL parser decodes them (`%2F` would become `/` and 404 or match the wrong template).
+/**
+ * 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('?');

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

@@ -1,6 +1,9 @@
 import type { JsonValue } from '../util/json.js';
 import type { AddonRoute } from './types.js';
-/** 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. */
+/**
+ * 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>;

package/dist/server/route-checks.js

@@ -8,12 +8,16 @@ function isPlainV1Path(path) {
 function isCorePath(method, path) {
     return V1_ROUTES.some((route) => routeMatches(route, method, path) !== null);
 }
-/** 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. */
+/**
+ * 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 function assertAddonRoutes(routes) {
     const seen = new Set();
     for (const { path } of routes) {
-        if (!isPlainV1Path(path))
+        if (!isPlainV1Path(path)) {
             throw new Error(`add-on route '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        }
         if (seen.has(path))
             throw new Error(`add-on route '${path}' is registered twice`);
         if (isCorePath('POST', path))
@@ -26,8 +30,9 @@ const PUBLIC_JSON_MAX_BYTES = 64 * 1024;
 export function assertPublicJson(publicJson) {
     const bodies = new Map();
     for (const [path, value] of Object.entries(publicJson)) {
-        if (!isPlainV1Path(path))
+        if (!isPlainV1Path(path)) {
             throw new Error(`public JSON path '${path}' is not a plain /v1/ path (segments use A-Z a-z 0-9 . _ ~ -)`);
+        }
         if (isCorePath('GET', path))
             throw new Error(`public JSON path '${path}' is already served by core`);
         const text = JSON.stringify(value);

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

@@ -1,15 +1,17 @@
 import type { Route, RouteRequest } from './types.js';
-/** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. Each row's `auth` is what the
- *  dispatch gate proves before its handler runs, so a handler never checks the caller itself. */
+/** The /v1 routes in dispatch order; the first entry whose method and path match handles the request. Each row's `auth`
+ * is what the dispatch gate proves before its handler runs, so a handler never checks the caller itself. */
 export declare const V1_ROUTES: readonly Route[];
-/** The route's run for this request, gate first, or null when method or path differ. The matcher runs before the method check,
- *  as the inline route blocks did, so a malformed `%` escape still throws from matchPath on any method. */
+/** The route's run for this request, gate first, or null when method or path differ. The matcher runs before the method
+ * check, as the inline route blocks did, so a malformed `%` escape still throws from matchPath on any method. */
 export declare function routeMatches(route: Route, method: string, path: string): ((r: RouteRequest) => Promise<void>) | null;
-/** The route as the access line names it; a regex route reads as its pattern would, so no line carries a caller's id. */
+/** The route as the access line names it; a regex route reads
+ * as its pattern would, so no line carries a caller's id. */
 export declare function routeLabel(route: Route): string;
 /** Run the first /v1 route whose method and path match. */
 export declare function dispatchV1Route(r: RouteRequest, method: string, path: string): Promise<boolean>;
-/** Core authenticates and parses before the handler runs, so an add-on route gets the same 401, 400 and 501 as a core one. */
+/** 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;