Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
index ed79a1902..e14b8ac17 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -1301,6 +1301,11 @@ Homepage: https://hocuspocus.dev
Copyright (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-server
diff --git a/packages/server/package.json b/packages/server/package.json
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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): MountMcpAndApiHandl
const 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): MountMcpAndApiHandl
socket.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.yaml
index 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.2
version: 20.10.6
+ hono:
+ specifier: ^4.12.29
+ version: 4.12.29
ignore:
specifier: ^5.3.2
version: 5.3.2
@@ -2393,6 +2399,12 @@ packages:
peerDependencies:
hono: ^4
+ 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
+ dependencies:
+ hono: 4.12.29
+
dependencies:
'@standard-schema/utils': 0.3.0