Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): mount the canonical Hono app in front of server dispatch (PRD-7783) (#3195)
omar-inkeepe1462877a8a4
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.mdindex ed79a1902..e14b8ac17 100644--- a/THIRD_PARTY_NOTICES.md+++ b/THIRD_PARTY_NOTICES.md@@ -1301,6 +1301,11 @@ Homepage: https://hocuspocus.devCopyright (c) 2023, Tiptap GmbH+### `@hono/[email protected]`+Homepage: https://github.com/honojs/node-server++Copyright (c) 2022 - present, Yusuke Wada and Hono contributors+### `@hono/[email protected]`Homepage: https://github.com/honojs/node-serverdiff --git a/packages/server/package.json b/packages/server/package.jsonindex ffb7cb94f..b647c0885 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -23,6 +23,7 @@"dependencies": {"@agentclientprotocol/sdk": "^1.1.0","@hocuspocus/server": "4.0.0-rc.1",+ "@hono/node-server": "^2.0.12","@inkeep/open-knowledge-core": "workspace:*","@modelcontextprotocol/sdk": "^1.28.0","@opentelemetry/api": "^1.9.0",@@ -44,6 +45,7 @@"diff": "^8.0.4","file-type": "^22.0.1","happy-dom": "^20.10.2",+ "hono": "^4.12.29","ignore": "^5.3.2","ipaddr.js": "^2.3.0","jsonc-parser": "^3.3.1",diff --git a/packages/server/src/health-routes.test.ts b/packages/server/src/health-routes.test.tsindex 0afc380db..94b1f651b 100644--- a/packages/server/src/health-routes.test.ts+++ b/packages/server/src/health-routes.test.ts@@ -204,6 +204,34 @@ describe('/readyz provider states (mounted harness)', () => {expect(probe.body).toEqual({ ready: true, status: 'ready', degraded: ['shadow-repo'] });});+ test('a throwing provider yields a structured 500, not the router default', async () => {+ const httpServer = createServer();+ const mount = mountMcpAndApi({+ httpServer,+ hocuspocus: fakeHocuspocus,+ log: fakeLog as never,+ health: {+ readiness: () => {+ throw new Error('provider exploded');+ },+ degraded: () => [],+ },+ });+ const port = await getFreeLoopbackPort();+ await new Promise<void>((r) => httpServer.listen(port, '127.0.0.1', () => r()));+ try {+ const res = await fetch(`http://127.0.0.1:${port}/readyz`);+ expect(res.status).toBe(500);+ expect(res.headers.get('content-type')).toBe('application/problem+json');+ const body = (await res.json()) as { type: string };+ expect(body.type).toBe('urn:ok:error:internal-server-error');+ } finally {+ await mount.shutdown();+ await new Promise<void>((r) => mount.wss.close(() => r()));+ await new Promise<void>((r) => httpServer.close(() => r()));+ }+ });+test('an omitted provider reports ready (synchronous-init harness posture)', async () => {const probe = await probeWithReadiness(undefined);expect(probe.status).toBe(200);diff --git a/packages/server/src/http/http-app.test.ts b/packages/server/src/http/http-app.test.tsnew file mode 100644index 000000000..e900d2cfd--- /dev/null+++ b/packages/server/src/http/http-app.test.ts@@ -0,0 +1,89 @@+import { createServer } from 'node:http';+import { describe, expect, test } from 'vitest';+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';+import { type CreateHttpAppOptions, createHttpApp } from './http-app.ts';++/**+ * Adapter-boundary pins the composition suite cannot see: these assert+ * properties of the router mount itself — global-object hygiene, body+ * passthrough to the legacy dispatch, and error finalization after headers+ * are sent — independent of any real route behavior.+ */++const fakeLog = {+ error: () => {},+ warn: () => {},+ info: () => {},+ debug: () => {},+ child: () => fakeLog,+} as never;++async function serveWith(legacyDispatch: CreateHttpAppOptions['legacyDispatch']) {+ const { requestListener } = createHttpApp({ legacyDispatch, log: fakeLog });+ const server = createServer(requestListener);+ const { baseUrl } = await listenOnLoopback(server);+ return {+ baseUrl,+ close: () =>+ new Promise<void>((resolvePromise, reject) => {+ server.close((err) => (err ? reject(err) : resolvePromise()));+ }),+ };+}++describe('createHttpApp adapter boundary', () => {+ test('mounting and serving leaves globalThis.Request/Response untouched', async () => {+ const RequestBefore = globalThis.Request;+ const ResponseBefore = globalThis.Response;+ const rig = await serveWith((_req, res) => {+ res.writeHead(204);+ res.end();+ });+ try {+ const res = await fetch(`${rig.baseUrl}/anything`);+ expect(res.status).toBe(204);+ expect(globalThis.Request).toBe(RequestBefore);+ expect(globalThis.Response).toBe(ResponseBefore);+ } finally {+ await rig.close();+ }+ });++ test('the catch-all leaves the request body for the legacy dispatch to consume', async () => {+ const rig = await serveWith((req, res) => {+ const chunks: Buffer[] = [];+ req.on('data', (chunk) => chunks.push(Buffer.from(chunk)));+ req.on('end', () => {+ const body = Buffer.concat(chunks);+ res.writeHead(200, { 'Content-Type': 'application/octet-stream' });+ res.end(body);+ });+ });+ try {+ const payload = 'x'.repeat(64 * 1024);+ const res = await fetch(`${rig.baseUrl}/echo`, { method: 'POST', body: payload });+ expect(res.status).toBe(200);+ expect(await res.text()).toBe(payload);+ } finally {+ await rig.close();+ }+ });++ test('a handler throw after headers are sent finalizes the response instead of hanging', async () => {+ const rig = await serveWith((_req, res) => {+ res.writeHead(200, { 'Content-Type': 'text/plain' });+ throw new Error('post-head boom');+ });+ try {+ // The onError fallback branch must end the response — a hang here+ // would leave the fetch pending until the test times out.+ const res = await fetch(`${rig.baseUrl}/partial`, {+ signal: AbortSignal.timeout(5_000),+ });+ expect(res.status).toBe(200);+ expect(await res.text()).toBe('');+ } finally {+ await rig.close();+ }+ });+});diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.tsnew file mode 100644index 000000000..5d7586f59--- /dev/null+++ b/packages/server/src/http/http-app.ts@@ -0,0 +1,140 @@+import type { IncomingMessage, ServerResponse } from 'node:http';+import { getRequestListener, type HttpBindings } from '@hono/node-server';+import { RESPONSE_ALREADY_SENT } from '@hono/node-server/utils/response';+import { Hono } from 'hono';+import type { PinoLogger } from '../logger.ts';+import { errorResponse } from './error-response.ts';++/**+ * The canonical HTTP application, introduced strangler-fig style: a Hono app+ * owns top-level routing, and every surface that has not yet been migrated to+ * a native handler falls through a catch-all into the pre-existing raw-Node+ * dispatch byte-for-byte unchanged. Surfaces migrate route by route; when the+ * legacy dispatch handles nothing, it gets deleted and the app stands alone.+ *+ * Handlers here write through the adapter's raw escape hatch+ * (`c.env.incoming`/`c.env.outgoing` + `RESPONSE_ALREADY_SENT`) rather than+ * returning web-standard Responses. That is deliberate for the migration+ * window: the characterization suite pins responses byte-for-byte, and the+ * existing response helpers (`errorResponse` et al.) write imperatively to+ * `ServerResponse`. Native `c.json()`-style handlers come later, surface by+ * surface, when the response-helper seam is rewritten.+ */++/** Async-init lifecycle as reported by /readyz. Only `ready` answers 200. */+export type ReadinessState = 'pending' | 'ready' | 'failed' | 'draining';++export interface HealthProvider {+ readiness: () => ReadinessState;+ degraded: () => readonly string[];+}++export interface CreateHttpAppOptions {+ /** Readiness provider for /readyz; omitted means always-ready (harnesses with synchronous init). */+ health?: HealthProvider;+ /** The pre-router dispatch. Every route without a native handler flows through here unchanged. */+ legacyDispatch: (req: IncomingMessage, res: ServerResponse) => void;+ /** Structured logger for handler errors the router catches. */+ log: PinoLogger;+}++export interface HttpAppHandle {+ /** Adapter-agnostic Node request listener — attach with `httpServer.on('request', ...)`. */+ requestListener: (req: IncomingMessage, res: ServerResponse) => void;+}++function writeHealthResponse(+ path: '/healthz' | '/readyz',+ req: IncomingMessage,+ res: ServerResponse,+ health: HealthProvider | undefined,+): void {+ if (req.method !== 'GET' && req.method !== 'HEAD') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'health',+ extraHeaders: { Allow: 'GET, HEAD' },+ });+ return;+ }+ const probeHeaders = {+ 'Cache-Control': 'no-store',+ 'X-Content-Type-Options': 'nosniff',+ };+ if (path === '/healthz') {+ res.writeHead(200, { ...probeHeaders, 'Content-Type': 'text/plain; charset=utf-8' });+ res.end('ok');+ return;+ }+ // Single-shaped body in both branches so consumers can read `status` and+ // `degraded` unconditionally. `degraded` is only meaningful once ready —+ // mid-init the list is still being populated.+ const readiness = health?.readiness() ?? 'ready';+ const ready = readiness === 'ready';+ res.writeHead(ready ? 200 : 503, { ...probeHeaders, 'Content-Type': 'application/json' });+ res.end(+ JSON.stringify({+ ready,+ status: readiness,+ degraded: ready ? (health?.degraded() ?? []) : [],+ }),+ );+}++export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {+ const app = new Hono<{ Bindings: HttpBindings }>();++ // Keep 500s on the server's error contract: without this, a throwing+ // handler gets Hono's plain-text default — no pino line, no problem+json.+ app.onError((err, c) => {+ const res = c.env.outgoing;+ opts.log.error({ err }, 'Unhandled router handler error');+ if (!res.headersSent && !res.writableEnded && !res.destroyed) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'http-app',+ cause: err,+ });+ } else if (!res.writableEnded) {+ res.end();+ }+ return RESPONSE_ALREADY_SENT;+ });++ // Health surface, mounted ABOVE the legacy dispatch and therefore above+ // every admission gate that lives inside it: orchestrator probes arrive+ // with an IP Host header, no Origin, and often through a proxy that adds+ // forwarding headers — all of which the gates refuse. The exemption is+ // safe because the surface is liveness/readiness only.+ for (const path of ['/healthz', '/readyz'] as const) {+ app.all(path, (c) => {+ writeHealthResponse(path, c.env.incoming, c.env.outgoing, opts.health);+ return RESPONSE_ALREADY_SENT;+ });+ }++ // Strangler catch-all: hand the raw req/res to the legacy dispatch and+ // tell the adapter the response is owned elsewhere. The legacy handlers+ // finish asynchronously; Node keeps the response open until they end it.+ app.all('*', (c) => {+ opts.legacyDispatch(c.env.incoming, c.env.outgoing);+ return RESPONSE_ALREADY_SENT;+ });++ // `overrideGlobalObjects: false` — the adapter otherwise replaces+ // globalThis.Request/Response with its lightweight shims at first call, a+ // process-wide mutation that would leak into the MCP SDK, OTel exporters,+ // and every other fetch consumer. Nothing here needs the shims; if native+ // handlers ever want them, opting in must be a deliberate decision.+ //+ // `autoCleanupIncoming: false` — the adapter otherwise drains rejected+ // non-GET/HEAD request bodies after the response, which would let a caller+ // refused by the admission gates force the server to read their upload+ // anyway. The legacy dispatch manages its own body lifecycle (the+ // reject-before-consuming contract), and this keeps the pre-router+ // connection semantics byte-identical.+ return {+ requestListener: getRequestListener(app.fetch, {+ overrideGlobalObjects: false,+ autoCleanupIncoming: false,+ }),+ };+}diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex ec4b6d974..4cfbf923b 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -31,6 +31,7 @@ import type { AgentSessionManager } from './agent-sessions.ts';import { isAllowedApiOrigin } from './api-origin.ts';import { createCollaborationHost } from './collaboration-host.ts';import { errorResponse } from './http/error-response.ts';+import { createHttpApp, type HealthProvider } from './http/http-app.ts';import type { PinoLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';@@ -41,8 +42,7 @@ import {type ResolvedRemoteAccess,} from './remote-access.ts';-/** Async-init lifecycle as reported by /readyz. Only `ready` answers 200. */-export type ReadinessState = 'pending' | 'ready' | 'failed' | 'draining';+export type { ReadinessState } from './http/http-app.ts';const MCP_CORS_HEADERS = {'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',@@ -138,10 +138,7 @@ export interface MountMcpAndApiOptions {* When omitted (restartable test harness, whose init is synchronous), the* health routes still mount and report ready with no degraded subsystems.*/- health?: {- readiness: () => ReadinessState;- degraded: () => readonly string[];- };+ health?: HealthProvider;/*** Resolved `remote:` config (null/undefined ⇒ remote access disabled).* When set, EVERY surface (`/mcp`, `/api/*`, `/collab`, content assets,@@ -218,44 +215,6 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlconst onRequest = (req: IncomingMessage, res: ServerResponse): void => {const url = req.url?.split('?')[0];- // Health surface, deliberately ABOVE every admission gate: orchestrator- // probes (Docker healthcheck, k8s, Railway/Fly) arrive with an IP Host- // header, no Origin, and often through a proxy that adds forwarding- // headers — all three of which the gates below refuse. The exemption is- // safe because the surface is liveness/readiness only; the sole- // project-adjacent disclosure is degraded subsystem names.- if (url === '/healthz' || url === '/readyz') {- if (req.method !== 'GET' && req.method !== 'HEAD') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'health',- extraHeaders: { Allow: 'GET, HEAD' },- });- return;- }- const probeHeaders = {- 'Cache-Control': 'no-store',- 'X-Content-Type-Options': 'nosniff',- };- if (url === '/healthz') {- res.writeHead(200, { ...probeHeaders, 'Content-Type': 'text/plain; charset=utf-8' });- res.end('ok');- return;- }- // Single-shaped body in both branches so consumers can read `status`- // and `degraded` unconditionally. `degraded` is only meaningful once- // ready — mid-init the list is still being populated.- const readiness = opts.health?.readiness() ?? 'ready';- const ready = readiness === 'ready';- res.writeHead(ready ? 200 : 503, { ...probeHeaders, 'Content-Type': 'application/json' });- res.end(- JSON.stringify({- ready,- status: readiness,- degraded: ready ? (opts.health?.degraded() ?? []) : [],- }),- );- return;- }// Tripwire: proxy-forwarding headers on a server that never opted into// remote access mean a tunnel is pointed at us. Refuse with the fix// instruction — the alternative is silently serving a public tunnel with@@ -486,7 +445,16 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlsocket.destroy();};- httpServer.on('request', onRequest);+ // The canonical Hono app owns top-level routing (health natively; every+ // unmigrated surface falls through its catch-all into `onRequest`+ // unchanged). The WS upgrade path stays a raw listener — it never routes+ // through HTTP dispatch.+ const { requestListener } = createHttpApp({+ health: opts.health,+ legacyDispatch: onRequest,+ log,+ });+ httpServer.on('request', requestListener);httpServer.on('upgrade', onUpgrade);let shutdownPromise: Promise<void> | undefined;diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 94d13d4b1..6774d28b5 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1171,6 +1171,9 @@ importers:'@hocuspocus/server':specifier: 4.0.0-rc.1+ '@hono/node-server':+ specifier: ^2.0.12+ version: 2.0.12([email protected])'@inkeep/open-knowledge-core':specifier: workspace:*version: link:../core@@ -1234,6 +1237,9 @@ importers:happy-dom:specifier: ^20.10.2version: 20.10.6+ hono:+ specifier: ^4.12.29+ version: 4.12.29ignore:specifier: ^5.3.2version: 5.3.2@@ -2393,6 +2399,12 @@ packages:peerDependencies:hono: ^4+ '@hono/[email protected]':+ resolution: {integrity: sha512-eWpQYr67tqJLeaSUl0Q+TquuYfUdTibpOJlUMV2FfUP7+KqCC5TufnwnlXL6mobZBJbGAYRd7ZvEBDCbLInjhg==}+ engines: {node: '>=20'}+ peerDependencies:+ hono: ^4+'@hookform/[email protected]':resolution: {integrity: sha512-EIsqr/t/qbinPIhGjMdtvutIN1Kk4uwbROE9/UQ93CAVGR7GkA7Y92+fX80OzXi/OB67jVFYwKGO1WzkxmkFZw==}peerDependencies:@@ -12789,6 +12801,10 @@ snapshots:dependencies:hono: 4.12.29+ '@hono/[email protected]([email protected])':+ dependencies:+ hono: 4.12.29+dependencies:'@standard-schema/utils': 0.3.0