hippo-memory 1.69.0 → 1.70.0

package/dist/server/routes/project-briefs.d.ts

@@ -1,8 +1,8 @@
 import type { RouteRequest } from '../types.js';
-export declare function handleCreateProjectBrief({ req, res, opts }: RouteRequest): Promise<void>;
-export declare function handleListProjectBriefs({ req, res, opts, query }: RouteRequest): Promise<void>;
-export declare function handleRefreshProjectBrief({ req, res, opts }: RouteRequest): Promise<void>;
-export declare function handleSupersedeProjectBrief({ req, res, opts }: RouteRequest, briefSupersedeMatch: RegExpMatchArray): Promise<void>;
-export declare function handleCloseProjectBrief({ req, res, opts }: RouteRequest, briefCloseMatch: RegExpMatchArray): Promise<void>;
-export declare function handleGetProjectBrief({ req, res, opts }: RouteRequest, briefByIdMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCreateProjectBrief(rr: RouteRequest): Promise<void>;
+export declare function handleListProjectBriefs(rr: RouteRequest): Promise<void>;
+export declare function handleRefreshProjectBrief(rr: RouteRequest): Promise<void>;
+export declare function handleSupersedeProjectBrief(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleCloseProjectBrief(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleGetProjectBrief(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
 //# sourceMappingURL=project-briefs.d.ts.map

package/dist/server/routes/project-briefs.js

@@ -1,10 +1,21 @@
 // /v1/project-briefs routes.
-import { assembleBriefFromReceipts, closeProjectBrief, loadProjectBriefById, loadProjectBriefs, MAX_REPO_LEN, refreshBrief, saveProjectBrief, VALID_BRIEF_STATES } from '../../project-briefs.js';
-import { HttpError, sendJson } from '../../http-util.js';
+import { briefFromReceipts, MAX_REPO_LEN, PROJECT_BRIEF, refreshedBrief } from '../../objects/project-briefs.js';
+import { sendJson } from '../../util/http-util.js';
 import { buildContextWithAuth } from '../auth.js';
-import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
-import { isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
-import { isJsonString } from '../../json.js';
+import { parseJsonBody } from '../validation.js';
+import { closeRoute, getRoute, listRoute, objectsOf, optionalString, requiredString, saveFor, supersedeRoute } from './object-routes.js';
+const briefRoutes = {
+    noun: 'project brief',
+    field: 'brief',
+    listField: 'briefs',
+    object: PROJECT_BRIEF,
+    filterParam: 'repo',
+    revise: (body) => {
+        const summary = requiredString(body, 'summary', { max: 8192 });
+        const changeSummary = optionalString(body, 'changeSummary', 4096);
+        return (existing, id) => ({ repo: existing.repo, summary, changeSummary, supersedesBriefId: id });
+    },
+};
 // ── project_brief routes ──
 //
 // 6 routes: POST /v1/project-briefs (new; body repo + summary), GET
@@ -15,123 +26,40 @@ import { isJsonString } from '../../json.js';
 // POST /v1/project-briefs/:id/close. DoS caps: repo 256, summary 8192,
 // changeSummary 4096. The store validates + throws; the boundary maps validation
 // -> 400, not-found -> 404, not-active -> 409. Mirrors /v1/skills.
-export async function handleCreateProjectBrief({ req, res, opts }) {
-    const ctx = await buildContextWithAuth(req, opts);
-    const body = await parseJsonBody(req, ctx);
-    const repo = body['repo'];
-    if (!isJsonString(repo) || repo.trim().length === 0) {
-        throw new HttpError(400, 'repo is required (non-empty string)');
-    }
-    if (repo.length > MAX_REPO_LEN) {
-        throw new HttpError(400, `repo exceeds ${MAX_REPO_LEN}-character cap`);
-    }
-    const summary = body['summary'];
-    if (!isJsonString(summary) || summary.trim().length === 0) {
-        throw new HttpError(400, 'summary is required (non-empty string)');
-    }
-    if (summary.length > 8192) {
-        throw new HttpError(400, 'summary exceeds 8192-character cap');
-    }
-    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
-        repo,
-        summary,
-    }, ctx.actor.subject);
-    sendJson(res, 201, { brief });
-    return;
+export async function handleCreateProjectBrief(rr) {
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    const body = await parseJsonBody(rr.req, ctx);
+    const brief = await saveFor(rr, PROJECT_BRIEF, ctx.tenantId, ctx.actor.subject, {
+        repo: requiredString(body, 'repo', { max: MAX_REPO_LEN }),
+        summary: requiredString(body, 'summary', { max: 8192 }),
+    });
+    sendJson(rr.res, 201, { brief });
 }
-export async function handleListProjectBriefs({ req, res, opts, query }) {
-    const status = query.get('status') ?? 'all';
-    const repoFilter = query.get('repo');
-    const limit = parseListLimit(query.get('limit'));
-    const after = parseCursor(query.get('cursor'), 'string', 'integer');
-    const ctx = await buildContextWithAuth(req, opts);
-    const listOpts = { limit: limit + 1, after };
-    if (repoFilter !== null && repoFilter.trim().length > 0) {
-        listOpts.repo = repoFilter.trim();
-    }
-    if (status !== 'all') {
-        if (!isSetMember(VALID_BRIEF_STATES, status)) {
-            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
-        }
-        listOpts.status = status;
-    }
-    const briefs = loadProjectBriefs(opts.hippoRoot, ctx.tenantId, listOpts);
-    const page = pageOf(briefs, limit, byCreatedAt);
-    sendJson(res, 200, { briefs: page.items, next_cursor: page.nextCursor });
-    return;
+export function handleListProjectBriefs(rr) {
+    return listRoute(briefRoutes, rr);
 }
 // The refresh op: must precede the /:id routes (literal 'refresh' is non-numeric
 // so the /(\d+)/ routes would not match it, but order it first).
-export async function handleRefreshProjectBrief({ req, res, opts }) {
+export async function handleRefreshProjectBrief(rr) {
+    const { req, res, opts } = rr;
     const ctx = await buildContextWithAuth(req, opts);
     const body = await parseJsonBody(req, ctx);
-    const repo = body['repo'];
-    if (!isJsonString(repo) || repo.trim().length === 0) {
-        throw new HttpError(400, 'repo is required (non-empty string)');
-    }
-    if (repo.length > MAX_REPO_LEN) {
-        throw new HttpError(400, `repo exceeds ${MAX_REPO_LEN}-character cap`);
-    }
-    const dryRun = body['dryRun'] === true;
-    if (dryRun) {
-        const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
+    const repo = requiredString(body, 'repo', { max: MAX_REPO_LEN });
+    if (body['dryRun'] === true) {
+        const { markdown, receiptCount } = await briefFromReceipts(objectsOf(rr), ctx.tenantId, repo);
         sendJson(res, 200, { markdown, receiptCount });
         return;
     }
-    const brief = refreshBrief(opts.hippoRoot, ctx.tenantId, repo, ctx.actor.subject);
+    const brief = await refreshedBrief(objectsOf(rr), { hippoRoot: opts.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor.subject }, repo);
     sendJson(res, 200, { brief });
-    return;
 }
-export async function handleSupersedeProjectBrief({ req, res, opts }, briefSupersedeMatch) {
-    const id = parseInt(briefSupersedeMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const body = await parseJsonBody(req, ctx);
-    const summary = body['summary'];
-    if (!isJsonString(summary) || summary.trim().length === 0) {
-        throw new HttpError(400, 'summary is required (non-empty string)');
-    }
-    if (summary.length > 8192) {
-        throw new HttpError(400, 'summary exceeds 8192-character cap');
-    }
-    const changeRaw = body['changeSummary'];
-    let changeSummary;
-    if (changeRaw !== undefined && changeRaw !== null) {
-        if (!isJsonString(changeRaw)) {
-            throw new HttpError(400, 'changeSummary must be a string');
-        }
-        if (changeRaw.length > 4096) {
-            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
-        }
-        changeSummary = changeRaw;
-    }
-    const existing = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
-    if (!existing) {
-        throw new HttpError(404, `project brief ${id} not found`);
-    }
-    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
-        repo: existing.repo,
-        summary,
-        changeSummary,
-        supersedesBriefId: id,
-    }, ctx.actor.subject);
-    sendJson(res, 200, { brief });
-    return;
+export function handleSupersedeProjectBrief(rr, match) {
+    return supersedeRoute(briefRoutes, rr, match);
 }
-export async function handleCloseProjectBrief({ req, res, opts }, briefCloseMatch) {
-    const id = parseInt(briefCloseMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-    sendJson(res, 200, { brief });
-    return;
+export function handleCloseProjectBrief(rr, match) {
+    return closeRoute(briefRoutes, rr, match);
 }
-export async function handleGetProjectBrief({ req, res, opts }, briefByIdMatch) {
-    const id = parseInt(briefByIdMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const brief = loadProjectBriefById(opts.hippoRoot, ctx.tenantId, id);
-    if (!brief) {
-        throw new HttpError(404, `project brief ${id} not found`);
-    }
-    sendJson(res, 200, { brief });
-    return;
+export function handleGetProjectBrief(rr, match) {
+    return getRoute(briefRoutes, rr, match);
 }
 //# sourceMappingURL=project-briefs.js.map

package/dist/server/routes/recall.js

@@ -1,16 +1,16 @@
 // Recall routes: /v1/memories search, assemble, drill and /v1/context.
 import { dirname, resolve } from 'node:path';
-import { assertCallerProject, resolveProjectIdentity } from '../../project-identity.js';
-import { isSharedStore } from '../../config.js';
-import { assembleCost, contextCost, drillCost } from '../../context-render.js';
-import { storeFor } from '../../store-port.js';
-import { biasHintEnabled } from '../../recall-history.js';
-import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api.js';
+import { assertCallerProject, resolveProjectIdentity } from '../../core/project-identity.js';
+import { isSharedStore } from '../../core/config.js';
+import { assembleCost, contextCost, drillCost } from '../../api/context-render.js';
+import { storeFor } from '../../store/index.js';
+import { biasHintEnabled } from '../../api/recall-history.js';
+import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api/index.js';
 import { httpParams, parseContextRequest, parseRecallRequest } from '../../api/recall-request.js';
 import { anchorSkippedRows, noteRecall, peekSessionRing, resetSessionRings, sessionRing } from '../../api/recall-record.js';
-import { HttpError, sendJson } from '../../http-util.js';
+import { HttpError, sendJson } from '../../util/http-util.js';
 import { buildContextWithAuth } from '../auth.js';
-import { validateIdSegment } from '../validation.js';
+import { MAX_LIST_LIMIT, parseListLimit, validateIdSegment } from '../validation.js';
 /** Test-only: reset the HTTP recall rings. Call from beforeEach. */
 export function __resetSessionRecallHistoryHttp() {
     resetSessionRings('http');
@@ -32,8 +32,7 @@ export async function handleRecallMemories({ req, res, opts, query }) {
     const ring = sessionRing('http', ctx.tenantId, sessionId);
     if (ring)
         noteRecall(ring, q, result.results[0]?.id ?? null, result.anchoringHint?.memoryId);
-    // Each recall surface counts its own hits; api.recall is no chokepoint,
-    // since the CLI never calls it and MCP shows the user a different band.
+    // HTTP counts the rows it returns here; `retrieve` cannot count for every ranker, since MCP shows a different band and counts none.
     await storeFor(ctx).bumpRecallStats(result.results.length);
     // Continuity payloads should never be cached. The caller is asking for
     // session-state-aware data; intermediaries must not reuse it across users.
@@ -78,7 +77,7 @@ export async function handleAssembleSession({ req, res, opts, query }, assembleM
         assembleExtra.summarizeOlder = summarizeOlder;
     if (scope !== undefined)
         assembleExtra.scope = scope;
-    const result = assemble(ctx, assembleMatch.id, { ...assembleExtra, cost: assembleCost(assembleMatch.id) });
+    const result = await assemble(ctx, assembleMatch.id, { ...assembleExtra, cost: assembleCost(assembleMatch.id) });
     await recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
     sendJson(res, 200, result);
     return;
@@ -96,6 +95,9 @@ export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
     if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
         throw new HttpError(400, 'limit must be a positive number');
     }
+    // Past the list ceiling the shared parser refuses, so the reply is the one every other list route gives.
+    if (limit !== undefined && limit > MAX_LIST_LIMIT)
+        parseListLimit(limitRaw);
     const budgetRaw = query.get('budget');
     const budget = budgetRaw === null ? undefined : Number(budgetRaw);
     if (budget !== undefined && (!Number.isFinite(budget) || budget <= 0)) {
@@ -120,7 +122,7 @@ export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
         drillExtra.budget = budget;
     if (depth !== undefined)
         drillExtra.depth = depth;
-    const result = drillDown(ctx, drillMatch.id, { ...drillExtra, cost: drillCost });
+    const result = await drillDown(ctx, drillMatch.id, { ...drillExtra, cost: drillCost });
     if ('failure' in result) {
         // Leaf id maps to 422 (caller-actionable). Other cases stay
         // as 404 to avoid leaking cross-tenant existence or scope grants.

package/dist/server/routes/skills.d.ts

@@ -1,8 +1,8 @@
 import type { RouteRequest } from '../types.js';
-export declare function handleCreateSkill({ req, res, opts }: RouteRequest): Promise<void>;
-export declare function handleListSkills({ req, res, opts, query }: RouteRequest): Promise<void>;
-export declare function handleExportSkills({ req, res, opts }: RouteRequest): Promise<void>;
-export declare function handleSupersedeSkill({ req, res, opts }: RouteRequest, skillSupersedeMatch: RegExpMatchArray): Promise<void>;
-export declare function handleCloseSkill({ req, res, opts }: RouteRequest, skillCloseMatch: RegExpMatchArray): Promise<void>;
-export declare function handleGetSkill({ req, res, opts }: RouteRequest, skillByIdMatch: RegExpMatchArray): Promise<void>;
+export declare function handleCreateSkill(rr: RouteRequest): Promise<void>;
+export declare function handleListSkills(rr: RouteRequest): Promise<void>;
+export declare function handleExportSkills(rr: RouteRequest): Promise<void>;
+export declare function handleSupersedeSkill(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleCloseSkill(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
+export declare function handleGetSkill(rr: RouteRequest, match: RegExpMatchArray): Promise<void>;
 //# sourceMappingURL=skills.d.ts.map

package/dist/server/routes/skills.js

@@ -1,10 +1,22 @@
 // /v1/skills routes.
-import { closeSkill, exportSkills, loadSkillById, loadSkills, MAX_SKILL_NAME_LEN, saveSkill, VALID_SKILL_STATES } from '../../skills.js';
-import { HttpError, sendJson } from '../../http-util.js';
+import { MAX_SKILL_NAME_LEN, SKILL, skillsMarkdown } from '../../objects/skills.js';
+import { sendJson } from '../../util/http-util.js';
 import { buildContextWithAuth } from '../auth.js';
-import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
-import { isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
-import { isJsonString } from '../../json.js';
+import { parseJsonBody } from '../validation.js';
+import { closeRoute, getRoute, listRoute, objectsOf, optionalString, requiredString, saveFor, supersedeRoute } from './object-routes.js';
+const INSTRUCTIONS = { max: 8192, plural: true };
+const skillRoutes = {
+    noun: 'skill',
+    field: 'skill',
+    listField: 'skills',
+    object: SKILL,
+    revise: (body) => {
+        const instructions = requiredString(body, 'instructions', INSTRUCTIONS);
+        const trigger = optionalString(body, 'trigger', 1024);
+        const changeSummary = optionalString(body, 'changeSummary', 4096);
+        return (existing, id) => ({ skillName: existing.skillName, instructions, trigger, changeSummary, supersedesSkillId: id });
+    },
+};
 // ── skills (first-class object, executable/exportable) ──
 //
 // 6 routes: POST /v1/skills (new; body skillName + instructions + trigger?),
@@ -17,135 +29,35 @@ import { isJsonString } from '../../json.js';
 // validates + throws; the boundary maps validation -> 400, not-found -> 404,
 // not-active -> 409. Mirrors /v1/processes; "executable" = exportable
 // instruction (no code exec).
-export async function handleCreateSkill({ req, res, opts }) {
-    const ctx = await buildContextWithAuth(req, opts);
-    const body = await parseJsonBody(req, ctx);
-    const skillName = body['skillName'];
-    if (!isJsonString(skillName) || skillName.trim().length === 0) {
-        throw new HttpError(400, 'skillName is required (non-empty string)');
-    }
-    if (skillName.length > MAX_SKILL_NAME_LEN) {
-        throw new HttpError(400, `skillName exceeds ${MAX_SKILL_NAME_LEN}-character cap`);
-    }
-    const instructions = body['instructions'];
-    if (!isJsonString(instructions) || instructions.trim().length === 0) {
-        throw new HttpError(400, 'instructions are required (non-empty string)');
-    }
-    if (instructions.length > 8192) {
-        throw new HttpError(400, 'instructions exceed 8192-character cap');
-    }
-    const triggerRaw = body['trigger'];
-    let trigger;
-    if (triggerRaw !== undefined && triggerRaw !== null) {
-        if (!isJsonString(triggerRaw)) {
-            throw new HttpError(400, 'trigger must be a string');
-        }
-        if (triggerRaw.length > 1024) {
-            throw new HttpError(400, 'trigger exceeds 1024-character cap');
-        }
-        trigger = triggerRaw;
-    }
-    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
-        skillName,
-        instructions,
-        trigger,
-    }, ctx.actor.subject);
-    sendJson(res, 201, { skill });
-    return;
+export async function handleCreateSkill(rr) {
+    const ctx = await buildContextWithAuth(rr.req, rr.opts);
+    const body = await parseJsonBody(rr.req, ctx);
+    const skill = await saveFor(rr, SKILL, ctx.tenantId, ctx.actor.subject, {
+        skillName: requiredString(body, 'skillName', { max: MAX_SKILL_NAME_LEN }),
+        instructions: requiredString(body, 'instructions', INSTRUCTIONS),
+        trigger: optionalString(body, 'trigger', 1024),
+    });
+    sendJson(rr.res, 201, { skill });
 }
-export async function handleListSkills({ req, res, opts, query }) {
-    const status = query.get('status') ?? 'all';
-    const limit = parseListLimit(query.get('limit'));
-    const after = parseCursor(query.get('cursor'), 'string', 'integer');
-    const ctx = await buildContextWithAuth(req, opts);
-    let skills;
-    if (status === 'all') {
-        skills = loadSkills(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
-    }
-    else {
-        if (!isSetMember(VALID_SKILL_STATES, status)) {
-            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
-        }
-        skills = loadSkills(opts.hippoRoot, ctx.tenantId, {
-            status,
-            limit: limit + 1,
-            after,
-        });
-    }
-    const page = pageOf(skills, limit, byCreatedAt);
-    sendJson(res, 200, { skills: page.items, next_cursor: page.nextCursor });
-    return;
+export function handleListSkills(rr) {
+    return listRoute(skillRoutes, rr);
 }
 // The export renderer: must precede the /:id GET (literal 'export' is
 // non-numeric so the /(\d+)/ route would not match it, but order it first).
-export async function handleExportSkills({ req, res, opts }) {
+export async function handleExportSkills(rr) {
+    const { req, res, opts } = rr;
     const ctx = await buildContextWithAuth(req, opts);
-    const markdown = exportSkills(opts.hippoRoot, ctx.tenantId);
+    const markdown = await skillsMarkdown(objectsOf(rr), ctx.tenantId);
     sendJson(res, 200, { markdown });
     return;
 }
-export async function handleSupersedeSkill({ req, res, opts }, skillSupersedeMatch) {
-    const id = parseInt(skillSupersedeMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const body = await parseJsonBody(req, ctx);
-    const instructions = body['instructions'];
-    if (!isJsonString(instructions) || instructions.trim().length === 0) {
-        throw new HttpError(400, 'instructions are required (non-empty string)');
-    }
-    if (instructions.length > 8192) {
-        throw new HttpError(400, 'instructions exceed 8192-character cap');
-    }
-    const triggerRaw = body['trigger'];
-    let trigger;
-    if (triggerRaw !== undefined && triggerRaw !== null) {
-        if (!isJsonString(triggerRaw)) {
-            throw new HttpError(400, 'trigger must be a string');
-        }
-        if (triggerRaw.length > 1024) {
-            throw new HttpError(400, 'trigger exceeds 1024-character cap');
-        }
-        trigger = triggerRaw;
-    }
-    const changeRaw = body['changeSummary'];
-    let changeSummary;
-    if (changeRaw !== undefined && changeRaw !== null) {
-        if (!isJsonString(changeRaw)) {
-            throw new HttpError(400, 'changeSummary must be a string');
-        }
-        if (changeRaw.length > 4096) {
-            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
-        }
-        changeSummary = changeRaw;
-    }
-    const existing = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
-    if (!existing) {
-        throw new HttpError(404, `skill ${id} not found`);
-    }
-    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
-        skillName: existing.skillName,
-        instructions,
-        trigger,
-        changeSummary,
-        supersedesSkillId: id,
-    }, ctx.actor.subject);
-    sendJson(res, 200, { skill });
-    return;
+export function handleSupersedeSkill(rr, match) {
+    return supersedeRoute(skillRoutes, rr, match);
 }
-export async function handleCloseSkill({ req, res, opts }, skillCloseMatch) {
-    const id = parseInt(skillCloseMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-    sendJson(res, 200, { skill });
-    return;
+export function handleCloseSkill(rr, match) {
+    return closeRoute(skillRoutes, rr, match);
 }
-export async function handleGetSkill({ req, res, opts }, skillByIdMatch) {
-    const id = parseInt(skillByIdMatch[1], 10);
-    const ctx = await buildContextWithAuth(req, opts);
-    const skill = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
-    if (!skill) {
-        throw new HttpError(404, `skill ${id} not found`);
-    }
-    sendJson(res, 200, { skill });
-    return;
+export function handleGetSkill(rr, match) {
+    return getRoute(skillRoutes, rr, match);
 }
 //# sourceMappingURL=skills.js.map

package/dist/{server-detect.js → server/server-detect.js}

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
-import { envHealthProbeMs } from './env.js';
+import { envHealthProbeMs } from '../util/env.js';
 // Pidfile sits directly inside hippoRoot. `hippoRoot` is the `.hippo`
 // directory itself (the same convention used by api.ts / store.ts /
 // openHippoDb), so this resolves to `${hippoRoot}/server.pid`.

package/dist/server/sleep-child.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sleep-child.d.ts.map

package/dist/server/sleep-child.js

@@ -0,0 +1,19 @@
+// Entry of the process that runs one POST /v1/sleep; sleep-offload.ts starts it and nothing imports it.
+// The sleep module alone: the api barrel loads far more than one sleep needs, and every sleep pays for the start.
+import { sleep } from '../api/sleep.js';
+import { isStoreBusy, runWithRequestStores, SERVER_DB_WAIT_MS } from '../db/index.js';
+import { errorMessage } from '../util/log.js';
+function failed(err) {
+    return { ok: false, busy: isStoreBusy(err), message: errorMessage(err), stack: err instanceof Error ? err.stack : undefined };
+}
+process.once('message', (message) => {
+    // SAFETY: sleep-offload.ts is the only writer on this channel and sends exactly one SleepJob.
+    const job = message;
+    const ctx = { hippoRoot: job.hippoRoot, tenantId: job.tenantId, actor: job.actor };
+    // The server's own request scope and lock wait, so a busy store answers as it did when sleep ran in the server.
+    runWithRequestStores(() => sleep(ctx, job.opts), { busyWaitMs: SERVER_DB_WAIT_MS })
+        .then((result) => ({ ok: true, result }), failed)
+        // Exit only once the reply is written, or the parent could see the process end first.
+        .then((reply) => process.send?.(reply, () => process.exit(0)));
+});
+//# sourceMappingURL=sleep-child.js.map

package/dist/server/sleep-offload.d.ts

@@ -0,0 +1,20 @@
+import { type Actor, type Context, type SleepOpts, type SleepResult } from '../api/index.js';
+/** What the child needs to rebuild the request's context; the store handle itself cannot cross a process boundary. */
+export interface SleepJob {
+    readonly hippoRoot: string;
+    readonly tenantId: string;
+    readonly actor: Actor;
+    readonly opts: SleepOpts;
+}
+export type SleepReply = {
+    readonly ok: true;
+    readonly result: SleepResult;
+} | {
+    readonly ok: false;
+    readonly busy: boolean;
+    readonly message: string;
+    readonly stack?: string;
+};
+/** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
+export declare function sleepInChild(ctx: Context, opts: SleepOpts): Promise<SleepResult>;
+//# sourceMappingURL=sleep-offload.d.ts.map

package/dist/server/sleep-offload.js

@@ -0,0 +1,70 @@
+// POST /v1/sleep runs its consolidation in a child process, so the server keeps answering and a stuck run can be stopped.
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { sleep } from '../api/index.js';
+import { StoreBusyError } from '../db/index.js';
+import { envSleepTimeoutMs } from '../util/env.js';
+import { HttpError } from '../util/http-util.js';
+const DEFAULT_SLEEP_DEADLINE_MS = 600_000;
+// Resolved from the package root, so a server run from TypeScript source starts the same built file.
+const CHILD_ENTRY = fileURLToPath(new URL('../../dist/server/sleep-child.js', import.meta.url));
+function failureOf(reply, code, signal) {
+    if (!reply || reply.ok)
+        return new Error(`sleep process ended without an answer (code ${code}, signal ${signal})`);
+    // A lock the child could not get is the same retryable 503 an in-process sleep gave.
+    if (reply.busy)
+        return new StoreBusyError(reply.message);
+    const failure = new Error(reply.message);
+    if (reply.stack)
+        failure.stack = reply.stack;
+    return failure;
+}
+function runInChild(job) {
+    const deadlineMs = envSleepTimeoutMs() ?? DEFAULT_SLEEP_DEADLINE_MS;
+    return new Promise((resolve, reject) => {
+        // The child's stderr is the server's log, so Node's SQLite notice would repeat there on every sleep.
+        const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', CHILD_ENTRY], { stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true });
+        let reply;
+        let timedOut = false;
+        // SIGKILL because the child is inside synchronous SQLite work and cannot run a handler; the OS drops its write lock.
+        const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, deadlineMs);
+        child.once('message', (message) => {
+            // SAFETY: sleep-child.ts is the only writer on this channel and sends exactly one SleepReply.
+            reply = message;
+        });
+        child.once('error', (err) => { clearTimeout(timer); reject(err); });
+        // 'close' and not 'exit': it waits for the channel to drain, so the reply is in hand and the child's store handles are gone.
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut)
+                reject(new HttpError(504, `sleep did not finish within ${deadlineMs} ms and was stopped; the next sleep carries on from there`));
+            else if (reply?.ok)
+                resolve(reply.result);
+            else
+                reject(failureOf(reply, code, signal));
+        });
+        child.send(job);
+    });
+}
+let turn = Promise.resolve();
+// One running and one waiting: each further sleep would only hold a request open behind work the waiting one already covers.
+const MAX_SLEEPS_IN_LINE = 2;
+const SLEEP_RETRY_AFTER_SEC = 30;
+let inLine = 0;
+/** `sleep` for the HTTP route: same result and errors, run outside the serving process and stopped at the deadline (10 minutes, or HIPPO_SLEEP_TIMEOUT_MS). */
+export function sleepInChild(ctx, opts) {
+    // The child reopens the store by path, which only SQLite has; any other store keeps sleep's own refusal.
+    if (ctx.store && ctx.store.kind !== 'sqlite')
+        return sleep(ctx, opts);
+    if (inLine >= MAX_SLEEPS_IN_LINE) {
+        return Promise.reject(new HttpError(503, 'a sleep is already running and another is waiting; retry when one has finished', SLEEP_RETRY_AFTER_SEC));
+    }
+    inLine += 1;
+    const job = { hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor, opts };
+    // One sleep at a time, as on the server's single thread: a second request waits its turn and does not fight the first for the write lock.
+    const run = turn.then(() => runInChild(job));
+    // A failed sleep reaches its own request through `run`; the queue only needs to know the turn is over.
+    turn = run.then(() => undefined, () => undefined).finally(() => { inLine -= 1; });
+    return run;
+}
+//# sourceMappingURL=sleep-offload.js.map

package/dist/server/tls.d.ts

@@ -0,0 +1,6 @@
+import { type RequestListener, type Server } from 'node:http';
+import type { ServeOpts } from './types.js';
+export declare function createListener(tls: ServeOpts['tls'], onRequest: RequestListener): Server;
+/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
+export declare function warnIfCleartext(host: string, tls: ServeOpts['tls'], loopbackHosts: ReadonlySet<string>): void;
+//# sourceMappingURL=tls.d.ts.map

package/dist/server/tls.js

@@ -0,0 +1,24 @@
+// The serve() listener: node:https when a certificate is given, else node:http and a boot warning off loopback.
+import { createServer as createHttpServer } from 'node:http';
+import { createServer as createHttpsServer } from 'node:https';
+import { errorMessage, log } from '../util/log.js';
+export function createListener(tls, onRequest) {
+    if (!tls)
+        return createHttpServer(onRequest);
+    try {
+        // Explicit so the floor does not move with the runtime's default.
+        return createHttpsServer({ cert: tls.cert, key: tls.key, minVersion: 'TLSv1.2' }, onRequest);
+    }
+    catch (err) {
+        // OpenSSL's own text names no file, so the operator would not know which input was refused.
+        throw new Error(`hippo serve: the TLS certificate or key was refused: ${errorMessage(err)}`, { cause: err });
+    }
+}
+/** Said once at boot: a non-loopback bind without TLS sends every key and memory over the network as plain text. */
+export function warnIfCleartext(host, tls, loopbackHosts) {
+    if (tls || loopbackHosts.has(host))
+        return;
+    log.warn(`serve: listening on ${host} without TLS, so API keys and memory text travel in cleartext unless a TLS-terminating proxy sits in front. ` +
+        'To serve HTTPS directly, pass --tls-cert and --tls-key (or set HIPPO_TLS_CERT and HIPPO_TLS_KEY).');
+}
+//# sourceMappingURL=tls.js.map