Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-8398 Move content and asset serving to native Hono routes (#4362)

omar-inkeep21f07a68d73c
diff --git a/.changeset/native-content-assets.md b/.changeset/native-content-assets.md
new file mode 100644
index 000000000..d2bbd7461
--- /dev/null
+++ b/.changeset/native-content-assets.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Internal refactor (no user-facing change): move static files, content assets, and asset previews to the native HTTP router. Serving precedence, admission checks, response contracts, and streaming behavior are unchanged.
diff --git a/packages/server/src/api-agent-write-native-preservation.test.ts b/packages/server/src/api-agent-write-native-preservation.test.ts
index 612a01a5e..66f04878e 100644
--- a/packages/server/src/api-agent-write-native-preservation.test.ts
+++ b/packages/server/src/api-agent-write-native-preservation.test.ts
@@ -21,8 +21,6 @@ const TEST_PATHS = [
'/api/test-rescan-files',
];
const RESIDUAL = [
- '/api/asset',
- '/api/asset-text',
'/api/skill/uninstall',
'/api/agent-write',
'/api/agent-write-batch',
@@ -56,7 +54,7 @@ afterAll(async () => {
test('native ownership is exclusive and the remaining legacy registry matches its explicit owners', () => {
for (const server of [enabled, disabled]) {
- for (const path of [...READS, ...WRITES])
+ for (const path of [...READS, ...WRITES, '/api/asset', '/api/asset-text'])
expect(server.serverInstance.nativeApi.paths.filter((entry) => entry === path)).toHaveLength(
1,
);
@@ -76,7 +74,7 @@ test('native ownership is exclusive and the remaining legacy registry matches it
});
test('ingress rejects every migrated route before method or malformed-body admission', async () => {
- for (const path of [...READS, ...WRITES, ...TEST_PATHS]) {
+ for (const path of [...READS, ...WRITES, ...TEST_PATHS, '/api/asset', '/api/asset-text']) {
for (const [headers, type] of [
[{ Host: 'evil.example' }, 'urn:ok:error:host-not-allowed'],
[{ Origin: 'https://evil.example' }, 'urn:ok:error:invalid-origin'],
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 6fb09532e..621a13693 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -5,7 +5,6 @@ export { ROLLBACK_ORIGIN } from './http/agent-write-routes.ts';
import { randomUUID } from 'node:crypto';
import {
- createReadStream,
type Dirent,
existsSync,
mkdirSync,
@@ -14,11 +13,10 @@ import {
realpathSync,
statSync,
} from 'node:fs';
-import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { readdir, realpath, stat } from 'node:fs/promises';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { homedir } from 'node:os';
import { dirname, extname, join, relative, resolve, sep } from 'node:path';
-import { pipeline } from 'node:stream/promises';
import type { Document, Extension, Hocuspocus } from '@hocuspocus/server';
import type { EnvTier } from '@inkeep/open-knowledge-core';
import {
@@ -39,7 +37,6 @@ import {
DEFAULT_LINTER_CONFIG,
type DiskEditReconciledWarning,
type DocumentListEntry,
- EmptyRequestSchema,
estimateSkillCost,
FrontmatterSchemaWriteRequestSchema,
type HeadingEntry,
@@ -252,6 +249,7 @@ import {
} from './fs-traced.ts';
import { withParentLock } from './git-handle.ts';
import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';
+import { createAssetRoutes } from './http/asset-routes.ts';
import { catchErrors } from './http/catch-errors.ts';
import { createCommentRoutes } from './http/comment-routes.ts';
import { createConfigSystemRoutes } from './http/config-system-routes.ts';
@@ -3720,112 +3718,6 @@ export function createApiExtension(
isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,
getAttachmentFolderPath,
});
- const ASSET_SERVE_ERRORS = {
- 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],
- 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],
- 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],
- 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],
- } as const;
-
- const handleAsset = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const assetPath = url.searchParams.get('path');
- const resolution = assetService.resolveServableAsset(assetPath);
- if (!resolution.ok) {
- const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
- errorResponse(res, status, type, title, {
- handler: 'asset',
- ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
- });
- return;
- }
- const { asset } = resolution;
- const headers: Record<string, string> = {
- 'Content-Type': asset.contentType,
- 'Content-Length': String(asset.size),
- 'X-Content-Type-Options': 'nosniff',
- 'Content-Disposition': asset.disposition,
- 'Cache-Control': 'no-store',
- };
- if (asset.csp !== null) {
- headers['Content-Security-Policy'] = asset.csp;
- }
- const canonicalPath = asset.canonicalPath;
- res.writeHead(200, headers);
- try {
- await pipeline(createReadStream(canonicalPath), res);
- } catch (streamError) {
- log.error(
- {
- event: 'api.asset.pipeline-failed',
- handler: 'asset',
- assetPath,
- err: streamError,
- },
- '[asset] pipeline failed mid-stream',
- );
- if (!res.destroyed) {
- res.destroy(streamError instanceof Error ? streamError : undefined);
- }
- }
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'asset',
- cause: e,
- });
- }
- },
- { handler: 'asset', method: 'GET', skipBodyParse: true },
- );
-
- const TEXT_VIEW_MAX_BYTES = 1_048_576;
- const handleAssetText = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const assetPath = url.searchParams.get('path');
- const resolution = assetService.resolveTextAsset(assetPath);
- if (!resolution.ok) {
- const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
- errorResponse(res, status, type, title, {
- handler: 'asset-text',
- ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
- });
- return;
- }
- if (resolution.size > TEXT_VIEW_MAX_BYTES) {
- errorResponse(
- res,
- 413,
- 'urn:ok:error:payload-too-large',
- `File exceeds the ${TEXT_VIEW_MAX_BYTES}-byte text-viewer cap.`,
- { handler: 'asset-text' },
- );
- return;
- }
- const bytes = await readFile(resolution.canonicalPath);
- const text = bytes.toString('utf-8');
- res.writeHead(200, {
- 'Content-Type': 'text/plain; charset=utf-8',
- 'X-Content-Type-Options': 'nosniff',
- 'Content-Disposition': 'inline',
- 'Cache-Control': 'no-store',
- });
- res.end(text);
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'asset-text',
- cause: e,
- });
- }
- },
- { handler: 'asset-text', method: 'GET', skipBodyParse: true },
- );
-
const fileOpsService = createFileOpsService({
contentDir,
resolveContentEntryPath,
@@ -5116,8 +5008,6 @@ export function createApiExtension(
);
const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
- '/api/asset': handleAsset,
- '/api/asset-text': handleAssetText,
'/api/skill/uninstall': handleSkillUninstall,
'/api/lint/markdownlint-config': handleWriteMarkdownlintRule,
'/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
@@ -5481,6 +5371,7 @@ export function createApiExtension(
splitContentPath,
mutateFileIndex,
});
+ const assetRoutes = createAssetRoutes({ assetService, log });
const handoffInstallRoutes = createHandoffInstallRoutes({ checkLocalOpSecurity });
const skillsInstallRoutes = createSkillsInstallRoutes({
resolveSkillsRoot,
@@ -5595,6 +5486,7 @@ export function createApiExtension(
rescanFiles,
});
const nativeGroups = [
+ assetRoutes,
agentWriteRoutes,
...(enableTestRoutes ? [testRoutes] : []),
skillsTrackingRoutes,
diff --git a/packages/server/src/content-assets-composition.test.ts b/packages/server/src/content-assets-composition.test.ts
new file mode 100644
index 000000000..71f999361
--- /dev/null
+++ b/packages/server/src/content-assets-composition.test.ts
@@ -0,0 +1,235 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { request } from 'node:http';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { gunzipSync, gzipSync } from 'node:zlib';
+import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+import * as httpApp from './http/http-app.ts';
+
+const shell = '<!doctype html><html><body>native shell marker</body></html>';
+const binary = Buffer.from(Array.from({ length: 2_000_000 }, (_, i) => i % 256));
+let root: string;
+let server: BootedServer;
+const legacyDispatch = vi.fn();
+beforeEach(() => legacyDispatch.mockClear());
+
+function wire(path: string, headers: Record<string, string> = {}) {
+ return new Promise<{
+ status: number;
+ headers: import('node:http').IncomingHttpHeaders;
+ bytes: Buffer;
+ }>((resolveResponse, reject) => {
+ const req = request(
+ { hostname: '127.0.0.1', port: server.port, path, headers, agent: false },
+ (res) => {
+ const chunks: Buffer[] = [];
+ res.on('data', (chunk: Buffer) => chunks.push(chunk));
+ res.on('error', reject);
+ res.on('end', () =>
+ resolveResponse({
+ status: res.statusCode ?? 0,
+ headers: res.headers,
+ bytes: Buffer.concat(chunks),
+ }),
+ );
+ },
+ );
+ req.on('error', reject);
+ req.end();
+ });
+}
+
+beforeAll(async () => {
+ root = mkdtempSync(resolve(tmpdir(), 'ok-native-content-'));
+ const content = resolve(root, 'content');
+ const dist = resolve(root, 'dist');
+ for (const base of [content, dist]) {
+ for (const prefix of ['assets', 'excalidraw-assets', 'docs'])
+ mkdirSync(resolve(base, prefix), { recursive: true });
+ }
+ writeFileSync(resolve(dist, 'index.html'), shell);
+ writeFileSync(resolve(dist, 'docs', 'missing.html'), '<h1>shell HTML fallback</h1>');
+ for (const prefix of ['assets', 'excalidraw-assets']) {
+ writeFileSync(resolve(dist, prefix, 'collision.png'), `bundled ${prefix}`);
+ writeFileSync(resolve(content, prefix, 'collision.png'), `content ${prefix}`);
+ writeFileSync(resolve(content, prefix, 'only.png'), `content only ${prefix}`);
+ }
+ writeFileSync(resolve(dist, 'assets', 'app.js'), 'bundled javascript');
+ writeFileSync(resolve(dist, 'assets', 'app.js.gz'), gzipSync('bundled javascript'));
+ writeFileSync(resolve(dist, 'docs', 'collision.png'), 'shell collision');
+ writeFileSync(resolve(content, 'docs', 'collision.png'), 'content collision');
+ writeFileSync(resolve(content, 'docs', 'page.html'), '<h1>content HTML</h1>');
+ writeFileSync(resolve(content, 'docs', 'large.png'), binary);
+ writeFileSync(resolve(content, 'docs', 'ignored.txt'), 'ignored text readable by explicit API');
+ writeFileSync(resolve(content, '.okignore'), 'docs/ignored.txt\n');
+ const createHttpApp = httpApp.createHttpApp;
+ const composition = vi.spyOn(httpApp, 'createHttpApp').mockImplementation((options) =>
+ createHttpApp({
+ ...options,
+ legacyDispatch: (req, res) => {
+ legacyDispatch(req.url);
+ options.legacyDispatch(req, res);
+ },
+ }),
+ );
+ try {
+ server = await bootCompositionRig(content, {
+ reactShellDistDir: dist,
+ serveContentAssets: true,
+ });
+ } finally {
+ composition.mockRestore();
+ }
+ await server.ready;
+}, 60_000);
+
+afterAll(async () => {
+ await server?.destroy();
+ await rm(root, { recursive: true, force: true });
+});
+
+describe('native serving over the real booted listener', () => {
+ test('bundled prefixes win collisions while missing bundles fall through to content', async () => {
+ const legacy = vi.spyOn(server.serverInstance.hocuspocus, 'hooks');
+ try {
+ for (const prefix of ['assets', 'excalidraw-assets']) {
+ const bundled = await wire(`/${prefix}/collision.png`);
+ expect(bundled.bytes.toString()).toBe(`bundled ${prefix}`);
+ expect(bundled.headers['content-type']).toContain('image/png');
+ expect(bundled.headers['content-disposition']).toBeUndefined();
+ const content = await wire(`/${prefix}/only.png`);
+ expect(content.bytes.toString()).toBe(`content only ${prefix}`);
+ expect(content.headers['content-disposition']).toBe('inline');
+ }
+ const encodedPrefix = await wire('/%61ssets/collision.png');
+ expect(encodedPrefix.bytes.toString()).toBe('content assets');
+ expect(encodedPrefix.headers['content-disposition']).toBe('inline');
+ const content = await wire('/docs/collision.png');
+ expect(content.bytes.toString()).toBe('content collision');
+ expect(content.headers['content-disposition']).toBe('inline');
+ expect(legacy.mock.calls.filter(([name]) => name === 'onRequest')).toHaveLength(0);
+ expect(legacyDispatch).not.toHaveBeenCalled();
+ } finally {
+ legacy.mockRestore();
+ }
+ });
+
+ test('missing assets terminate while shell fallthrough preserves sirv extension rules', async () => {
+ const legacy = vi.spyOn(server.serverInstance.hocuspocus, 'hooks');
+ try {
+ const missing = await wire('/docs/missing.png');
+ expect(missing.status).toBe(404);
+ expect(missing.bytes.length).toBe(0);
+ for (const path of [
+ '/docs/page',
+ '/%ZZ',
+ '/API/asset',
+ '/api',
+ '/mcp/',
+ '/%61pi/asset',
+ '/%6dcp',
+ ]) {
+ const response = await wire(path);
+ expect(response.status, path).toBe(200);
+ expect(response.bytes.toString(), path).toBe(shell);
+ expect(response.headers['content-security-policy'], path).toBeUndefined();
+ expect(response.headers['content-disposition'], path).toBeUndefined();
+ }
+ const html = await wire('/docs/missing.html');
+ expect(html.bytes.toString()).toBe('<h1>shell HTML fallback</h1>');
+ expect(html.headers['content-security-policy']).toBeUndefined();
+ expect(html.headers['content-disposition']).toBeUndefined();
+ expect(html.headers['x-content-type-options']).toBeUndefined();
+ expect(html.headers['cache-control']).not.toBe('no-store');
+ for (const path of ['/docs/missing.md', '/docs/ignored.txt', '/docs/absent.html']) {
+ const missingFile = await wire(path);
+ expect(missingFile.status, path).toBe(404);
+ expect(missingFile.headers['content-type']).toBe('application/problem+json');
+ expect(missingFile.headers['content-security-policy']).toBeUndefined();
+ expect(missingFile.headers['content-disposition']).toBeUndefined();
+ }
+ expect(legacy.mock.calls.filter(([name]) => name === 'onRequest')).toHaveLength(0);
+ expect(legacyDispatch).not.toHaveBeenCalled();
+ const api = await rawRequest(server.port, '/api/not-a-route');
+ expect(legacyDispatch).toHaveBeenCalledWith('/api/not-a-route');
+ expect(parseProblem(api.body).title).toBe('API endpoint not found.');
+ expect(legacy.mock.calls.some(([name]) => name === 'onRequest')).toBe(true);
+ } finally {
+ legacy.mockRestore();
+ }
+ });
+
+ test('content HTML keeps its sandbox and shell routing does not reject Origin', async () => {
+ const html = await wire('/docs/page.html', { Origin: 'https://untrusted.example' });
+ expect(html.bytes.toString()).toBe('<h1>content HTML</h1>');
+ expect(html.headers['content-security-policy']).toContain('sandbox');
+ expect(html.headers['content-disposition']).toBe('inline');
+ const response = await wire('/', { Origin: 'https://untrusted.example' });
+ expect(response.bytes.toString()).toBe(shell);
+ const shellHost = await wire('/', { Host: 'untrusted.example' });
+ expect(shellHost.bytes.toString()).toBe(shell);
+ const contentHost = await wire('/docs/page.html', { Host: 'untrusted.example' });
+ expect(contentHost.status).toBe(403);
+ expect(contentHost.bytes.toString()).toContain('Host header not allowed');
+ });
+
+ test('sirv retains HEAD, byte ranges, validators and precompressed bytes', async () => {
+ const head = await rawRequest(server.port, '/assets/app.js', { method: 'HEAD' });
+ expect(head.status).toBe(200);
+ expect(head.body).toBe('');
+ expect(head.headers['content-length']).toBe(String(Buffer.byteLength('bundled javascript')));
+ const range = await wire('/docs/large.png', { Range: 'bytes=2-17' });
+ expect(range.status).toBe(206);
+ expect(range.bytes).toEqual(binary.subarray(2, 18));
+ const asset = await wire('/assets/app.js');
+ const etag = asset.headers.etag;
+ expect(etag).toBeTypeOf('string');
+ if (typeof etag !== 'string') throw new Error('Missing static validator');
+ const unchanged = await wire('/assets/app.js', { 'If-None-Match': etag });
+ expect(unchanged.status).toBe(304);
+ expect(unchanged.bytes.length).toBe(0);
+ const compressed = await wire('/assets/app.js', { 'Accept-Encoding': 'gzip' });
+ expect(compressed.headers['content-encoding']).toBe('gzip');
+ expect(gunzipSync(compressed.bytes).toString()).toBe('bundled javascript');
+ });
+
+ test('asset APIs preserve binary bytes, text ignore distinction, errors and method admission without legacy hooks', async () => {
+ const legacy = vi.spyOn(server.serverInstance.hocuspocus, 'hooks');
+ try {
+ const asset = await wire('/api/asset?path=docs/large.png');
+ expect(asset.bytes).toEqual(binary);
+ expect(asset.headers['content-length']).toBe(String(binary.length));
+ expect(asset.headers['cache-control']).toBe('no-store');
+ expect(asset.headers['content-disposition']).toBe('inline');
+ const ignored = await wire('/api/asset?path=docs/ignored.txt');
+ expect(ignored.status).toBe(404);
+ const text = await wire('/api/asset-text?path=docs/ignored.txt');
+ expect(text.bytes.toString()).toBe('ignored text readable by explicit API');
+ expect(text.headers['content-type']).toBe('text/plain; charset=utf-8');
+ const cap = await wire('/api/asset-text?path=docs/large.png');
+ expect(cap.status).toBe(413);
+ for (const path of ['/api/asset', '/api/asset-text']) {
+ const method = await rawRequest(server.port, path, { method: 'HEAD' });
+ expect(method.status).toBe(405);
+ expect(method.headers.allow).toBe('GET');
+ const origin = await rawRequest(server.port, path, {
+ headers: { Origin: 'https://untrusted.example' },
+ });
+ expect(origin.status).toBe(403);
+ const preflight = await rawRequest(server.port, path, {
+ method: 'OPTIONS',
+ headers: { Origin: 'http://localhost:5173' },
+ });
+ expect(preflight.status).toBe(204);
+ expect(preflight.headers['access-control-allow-origin']).toBe('http://localhost:5173');
+ }
+ expect(legacy.mock.calls.filter(([name]) => name === 'onRequest')).toHaveLength(0);
+ expect(legacyDispatch).not.toHaveBeenCalled();
+ } finally {
+ legacy.mockRestore();
+ }
+ });
+});
diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.ts
index 267583880..1338bb524 100644
--- a/packages/server/src/http/api-pipeline.test.ts
+++ b/packages/server/src/http/api-pipeline.test.ts
@@ -1,12 +1,14 @@
import { createServer } from 'node:http';
import { describe, expect, test } from 'vitest';
import { parseProblem, rawRequest } from '../composition-rig.test-helper.ts';
+import { buildIngressPolicy } from '../ingress-policy.ts';
import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
import {
type ApiRouteTable,
createApiRequestPipeline,
createApiRouteGroup,
} from './api-pipeline.ts';
+import { createContentDispatch } from './content-dispatch.ts';
import { createHttpApp, type NativeApiHandle } from './http-app.ts';
const fakeLog = {
@@ -71,6 +73,7 @@ async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<Native
};
const { requestListener } = createHttpApp({
nativeApi,
+ contentDispatch: createContentDispatch({ ingressPolicy: buildIngressPolicy({}), log: fakeLog }),
legacyDispatch: (req, res) => {
legacyCalls.push(req.url ?? '');
res.writeHead(299, { 'Content-Type': 'text/plain' });
diff --git a/packages/server/src/http/asset-routes.test.ts b/packages/server/src/http/asset-routes.test.ts
new file mode 100644
index 000000000..d196ddd49
--- /dev/null
+++ b/packages/server/src/http/asset-routes.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, test } from 'vitest';
+import { loggerFactory } from '../logger.ts';
+import { createAssetService } from '../services/assets.ts';
+import { createAssetRoutes } from './asset-routes.ts';
+
+const paths = ['/api/asset', '/api/asset-text'];
+
+describe('asset read route table', () => {
+ test('owns exactly the two non-mutating read routes', () => {
+ const group = createAssetRoutes({
+ assetService: createAssetService({ contentDir: '/nonexistent-assets' }),
+ log: loggerFactory.getLogger('test'),
+ });
+ expect(group.paths).toEqual(paths);
+ for (const path of paths) {
+ expect(group.table.resolve(path)?.dispatch).toBeTypeOf('function');
+ expect(group.table.isMutating(path)).toBe(false);
+ expect(group.table.resolve(`${path}/`)).toBeNull();
+ }
+ });
+});
diff --git a/packages/server/src/http/asset-routes.ts b/packages/server/src/http/asset-routes.ts
new file mode 100644
index 000000000..4da1fcf95
--- /dev/null
+++ b/packages/server/src/http/asset-routes.ts
@@ -0,0 +1,141 @@
+import { createReadStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { EmptyRequestSchema } from '@inkeep/open-knowledge-core';
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import { ATTR_ERROR_TYPE } from '@opentelemetry/semantic-conventions';
+import type { PinoLogger } from '../logger.ts';
+import type { AssetService } from '../services/assets.ts';
+import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { errnoCode } from './handler-utils.ts';
+import { withValidation } from './request-validation.ts';
+
+export interface AssetRouteDeps {
+ assetService: AssetService;
+ log: PinoLogger;
+}
+
+export function createAssetRoutes(deps: AssetRouteDeps): ApiRouteGroup {
+ const { assetService, log } = deps;
+ const ASSET_SERVE_ERRORS = {
+ 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],
+ 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],
+ 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],
+ 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],
+ } as const;
+
+ const handleAsset = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const assetPath = url.searchParams.get('path');
+ const resolution = assetService.resolveServableAsset(assetPath);
+ if (!resolution.ok) {
+ const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
+ errorResponse(res, status, type, title, {
+ handler: 'asset',
+ ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
+ });
+ return;
+ }
+ const { asset } = resolution;
+ const headers: Record<string, string> = {
+ 'Content-Type': asset.contentType,
+ 'Content-Length': String(asset.size),
+ 'X-Content-Type-Options': 'nosniff',
+ 'Content-Disposition': asset.disposition,
+ 'Cache-Control': 'no-store',
+ };
+ if (asset.csp !== null) {
+ headers['Content-Security-Policy'] = asset.csp;
+ }
+ const canonicalPath = asset.canonicalPath;
+ res.writeHead(200, headers);
+ try {
+ await pipeline(createReadStream(canonicalPath), res);
+ } catch (streamError) {
+ const span = trace.getActiveSpan();
+ const code = errnoCode(streamError);
+ const connectionClosed =
+ code === 'ERR_STREAM_PREMATURE_CLOSE' || code === 'ECONNRESET' || code === 'EPIPE';
+ span?.setAttribute(
+ ATTR_ERROR_TYPE,
+ connectionClosed ? 'connection_closed' : 'stream_failure',
+ );
+ span?.recordException(streamError instanceof Error ? streamError : String(streamError));
+ span?.setStatus({ code: SpanStatusCode.ERROR, message: 'Asset transfer incomplete' });
+ log.error(
+ {
+ event: 'api.asset.pipeline-failed',
+ handler: 'asset',
+ assetPath,
+ err: streamError,
+ },
+ '[asset] pipeline failed mid-stream',
+ );
+ if (!res.destroyed) {
+ res.destroy(streamError instanceof Error ? streamError : undefined);
+ }
+ }
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'asset',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'asset', method: 'GET', skipBodyParse: true },
+ );
+
+ const TEXT_VIEW_MAX_BYTES = 1_048_576;
+ const handleAssetText = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const assetPath = url.searchParams.get('path');
+ const resolution = assetService.resolveTextAsset(assetPath);
+ if (!resolution.ok) {
+ const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];
+ errorResponse(res, status, type, title, {
+ handler: 'asset-text',
+ ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),
+ });
+ return;
+ }
+ if (resolution.size > TEXT_VIEW_MAX_BYTES) {
+ errorResponse(
+ res,
+ 413,
+ 'urn:ok:error:payload-too-large',
+ `File exceeds the ${TEXT_VIEW_MAX_BYTES}-byte text-viewer cap.`,
+ { handler: 'asset-text' },
+ );
+ return;
+ }
+ const bytes = await readFile(resolution.canonicalPath);
+ const text = bytes.toString('utf-8');
+ res.writeHead(200, {
+ 'Content-Type': 'text/plain; charset=utf-8',
+ 'X-Content-Type-Options': 'nosniff',
+ 'Content-Disposition': 'inline',
+ 'Cache-Control': 'no-store',
+ });
+ res.end(text);
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'asset-text',
+ cause: e,
+ });
+ }
+ },
+ { handler: 'asset-text', method: 'GET', skipBodyParse: true },
+ );
+
+ return createApiRouteGroup({
+ '/api/asset': handleAsset,
+ '/api/asset-text': handleAssetText,
+ });
+}
diff --git a/packages/server/src/http/asset-stream-composition.test.ts b/packages/server/src/http/asset-stream-composition.test.ts
new file mode 100644
index 000000000..0dc265b28
--- /dev/null
+++ b/packages/server/src/http/asset-stream-composition.test.ts
@@ -0,0 +1,276 @@
+import { createReadStream, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { createServer, request, type Server } from 'node:http';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { context, SpanStatusCode, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import {
+ BasicTracerProvider,
+ InMemorySpanExporter,
+ SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { ATTR_ERROR_TYPE } from '@opentelemetry/semantic-conventions';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { buildIngressPolicy } from '../ingress-policy.ts';
+import { loggerFactory } from '../logger.ts';
+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
+import { createAssetService } from '../services/assets.ts';
+import { createApiRequestPipeline } from './api-pipeline.ts';
+import { createAssetRoutes } from './asset-routes.ts';
+import { createContentDispatch } from './content-dispatch.ts';
+import { createHttpApp } from './http-app.ts';
+
+vi.mock('node:fs', async (importOriginal) => {
+ const fs = await importOriginal<typeof import('node:fs')>();
+ return { ...fs, createReadStream: vi.fn(fs.createReadStream) };
+});
+
+let exporter: InMemorySpanExporter;
+let provider: BasicTracerProvider;
+
+beforeEach(() => {
+ exporter = new InMemorySpanExporter();
+ provider = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] });
+ trace.setGlobalTracerProvider(provider);
+ context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable());
+});
+
+async function expectTransferSpan(status: SpanStatusCode, errorType: string | undefined) {
+ await vi.waitFor(() => {
+ const span = exporter.getFinishedSpans().find((entry) => entry.name === 'HTTP GET /api/asset');
+ expect(span).toBeDefined();
+ expect(span?.status.code).toBe(status);
+ expect(span?.attributes[ATTR_ERROR_TYPE]).toBe(errorType);
+ expect(span?.attributes['http.response.status_code']).toBe(200);
+ expect(span?.events.some((event) => event.name === 'exception')).toBe(
+ status === SpanStatusCode.ERROR,
+ );
+ });
+}
+
+let root: string;
+let server: Server | undefined;
+
+async function start() {
+ root = mkdtempSync(resolve(tmpdir(), 'ok-asset-stream-'));
+ mkdirSync(resolve(root, 'docs'));
+ const file = resolve(root, 'docs', 'large.png');
+ writeFileSync(file, Buffer.alloc(8_000_000, 97));
+ const log = loggerFactory.getLogger('asset-stream-test');
+ const logError = vi.spyOn(log, 'error');
+ const group = createAssetRoutes({ assetService: createAssetService({ contentDir: root }), log });
+ const legacy = vi.fn(
+ (_req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => {
+ res.end('legacy sentinel');
+ },
+ );
+ const app = createHttpApp({
+ log,
+ legacyDispatch: legacy,
+ contentDispatch: createContentDispatch({ ingressPolicy: buildIngressPolicy({}), log }),
+ nativeApi: {
+ paths: group.paths,
+ dispatch: createApiRequestPipeline({
+ log,
+ policy: buildIngressPolicy({}),
+ table: group.table,
+ }),
+ },
+ });
+ server = createServer(app.requestListener);
+ const { port } = await listenOnLoopback(server);
+ return { port, file, legacy, logError };
+}
+
+afterEach(async () => {
+ vi.mocked(createReadStream).mockReset();
+ const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+ vi.mocked(createReadStream).mockImplementation(fs.createReadStream);
+ if (server) {
+ server.closeAllConnections();
+ await new Promise<void>((resolveClosed, reject) =>
+ server?.close((error) => (error ? reject(error) : resolveClosed())),
+ );
+ server = undefined;
+ }
+ if (root) await rm(root, { recursive: true, force: true });
+ await provider.shutdown();
+ trace.disable();
+ context.disable();
+ vi.restoreAllMocks();
+});
+
+describe('native asset raw stream lifetime over HTTP', () => {
+ test('a complete transfer leaves the HTTP span successful', async () => {
+ const { port, legacy } = await start();
+ const response = await fetch(`http://127.0.0.1:${port}/api/asset?path=docs/large.png`);
+ expect(response.status).toBe(200);
+ expect((await response.arrayBuffer()).byteLength).toBe(8_000_000);
+ await expectTransferSpan(SpanStatusCode.UNSET, undefined);
+ expect(legacy).not.toHaveBeenCalled();
+ });
+
+ test('a file disappearing after resolution aborts the socket without a JSON or SPA fallback', async () => {
+ const { port, legacy } = await start();
+ const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+ vi.mocked(createReadStream).mockImplementationOnce((path) => {
+ fs.unlinkSync(path);
+ return fs.createReadStream(path);
+ });
+ const outcome = await new Promise<{ body: string; aborted: boolean }>((resolveOutcome) => {
+ const req = request(
+ { hostname: '127.0.0.1', port, path: '/api/asset?path=docs/large.png' },
+ (res) => {
+ let body = '';
+ res.on('data', (chunk) => {
+ body += String(chunk);
+ });
+ res.on('aborted', () => resolveOutcome({ body, aborted: true }));
+ res.on('error', () => resolveOutcome({ body, aborted: true }));
+ res.on('end', () => resolveOutcome({ body, aborted: false }));
+ },
+ );
+ req.on('error', () => resolveOutcome({ body: '', aborted: true }));
+ req.end();
+ });
+ expect(outcome).toEqual({ body: '', aborted: true });
+ expect(legacy).not.toHaveBeenCalled();
+ await expectTransferSpan(SpanStatusCode.ERROR, 'stream_failure');
+ });
+
+ test('a source failure after bytes arrive leaves only the original binary prefix', async () => {
+ const { port, file, legacy } = await start();
+ const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+ const stream = fs.createReadStream(file, { highWaterMark: 4096 });
+ stream.pause();
+ stream.once('data', () => stream.pause());
+ vi.mocked(createReadStream).mockReturnValueOnce(stream);
+ const response = await new Promise<{
+ bytes: Buffer;
+ aborted: boolean;
+ contentType: string | undefined;
+ }>((resolveResponse, reject) => {
+ const req = request(
+ { hostname: '127.0.0.1', port, path: '/api/asset?path=docs/large.png' },
+ (res) => {
+ const chunks: Buffer[] = [];
+ res.on('data', (chunk: Buffer) => {
+ chunks.push(chunk);
+ stream.destroy(new Error('injected disk read failure'));
+ });
+ res.on('error', reject);
+ res.on('aborted', () =>
+ resolveResponse({
+ bytes: Buffer.concat(chunks),
+ aborted: true,
+ contentType: res.headers['content-type'],
+ }),
+ );
+ res.on('end', () =>
+ resolveResponse({
+ bytes: Buffer.concat(chunks),
+ aborted: false,
+ contentType: res.headers['content-type'],
+ }),
+ );
+ },
+ );
+ req.on('error', reject);
+ req.end();
+ });
+ expect(response.aborted).toBe(true);
+ expect(response.contentType).toBe('image/png');
+ expect(response.bytes.length).toBeGreaterThan(0);
+ expect(response.bytes.length).toBeLessThan(8_000_000);
+ expect(response.bytes.equals(Buffer.alloc(response.bytes.length, 97))).toBe(true);
+ expect(legacy).not.toHaveBeenCalled();
+ await expectTransferSpan(SpanStatusCode.ERROR, 'stream_failure');
+ });
+
+ test.each(['destroy', 'resetAndDestroy'] as const)(
+ 'client %s destroys the file stream and does not enter legacy dispatch',
+ async (disconnect) => {
+ const { port, file, legacy, logError } = await start();
+ const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+ let streamClosed: Promise<unknown> | undefined;
+ vi.mocked(createReadStream).mockImplementationOnce(() => {
+ const stream = fs.createReadStream(file, { highWaterMark: 4096 });
+ streamClosed = new Promise<void>((resolveClosed) => stream.once('close', resolveClosed));
+ return stream;
+ });
+ await new Promise<void>((resolveAborted, reject) => {
+ const req = request(
+ { hostname: '127.0.0.1', port, path: '/api/asset?path=docs/large.png' },
+ (res) => {
+ res.once('data', () => {
+ if (disconnect === 'resetAndDestroy') res.socket.resetAndDestroy();
+ else res.destroy();
+ resolveAborted();
+ });
+ },
+ );
+ req.on('error', reject);
+ req.end();
+ });
+ expect(streamClosed).toBeDefined();
+ await streamClosed;
+ expect(legacy).not.toHaveBeenCalled();
+ await expectTransferSpan(SpanStatusCode.ERROR, 'connection_closed');
+ expect(logError).toHaveBeenCalledWith(
+ expect.objectContaining({
+ event: 'api.asset.pipeline-failed',
+ err: expect.objectContaining({ code: 'ERR_STREAM_PREMATURE_CLOSE' }),
+ }),
+ '[asset] pipeline failed mid-stream',
+ );
+ },
+ );
+
+ test.each(['EPIPE', 'ECONNRESET'])(
+ 'a destination %s retains the binary prefix and records connection closure',
+ async (code) => {
+ const { port, file, legacy, logError } = await start();
+ const fs = await vi.importActual<typeof import('node:fs')>('node:fs');
+ const stream = fs.createReadStream(file, { highWaterMark: 4096 });
+ stream.once('data', () => stream.pause());
+ vi.mocked(createReadStream).mockReturnValueOnce(stream);
+ let response: import('node:http').ServerResponse | undefined;
+ server?.once('request', (_req, res) => {
+ response = res;
+ });
+ const bytes = await new Promise<Buffer>((resolveAborted, reject) => {
+ const req = request(
+ { hostname: '127.0.0.1', port, path: '/api/asset?path=docs/large.png' },
+ (res) => {
+ const chunks: Buffer[] = [];
+ res.on('data', (chunk: Buffer) => {
+ chunks.push(chunk);
+ response?.emit(
+ 'error',
+ Object.assign(new Error('injected destination failure'), { code }),
+ );
+ });
+ res.on('aborted', () => resolveAborted(Buffer.concat(chunks)));
+ res.on('error', reject);
+ res.on('end', () => reject(new Error('transfer unexpectedly completed')));
+ },
+ );
+ req.on('error', reject);
+ req.end();
+ });
+ expect(bytes.length).toBeGreaterThan(0);
+ expect(bytes.length).toBeLessThan(8_000_000);
+ expect(bytes.equals(Buffer.alloc(bytes.length, 97))).toBe(true);
+ await expectTransferSpan(SpanStatusCode.ERROR, 'connection_closed');
+ expect(logError).toHaveBeenCalledWith(
+ expect.objectContaining({
+ event: 'api.asset.pipeline-failed',
+ err: expect.objectContaining({ code }),
+ }),
+ '[asset] pipeline failed mid-stream',
+ );
+ expect(legacy).not.toHaveBeenCalled();
+ },
+ );
+});
diff --git a/packages/server/src/http/content-dispatch.test.ts b/packages/server/src/http/content-dispatch.test.ts
new file mode 100644
index 000000000..053805cc3
--- /dev/null
+++ b/packages/server/src/http/content-dispatch.test.ts
@@ -0,0 +1,146 @@
+import { readFileSync } from 'node:fs';
+import { createServer, type Server } from 'node:http';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { makeCaptureRes, makeSyntheticReq, rawRequest } from '../composition-rig.test-helper.ts';
+import { buildIngressPolicy } from '../ingress-policy.ts';
+import { loggerFactory } from '../logger.ts';
+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
+import { type ContentDispatchOptions, createContentDispatch } from './content-dispatch.ts';
+import { createHttpApp } from './http-app.ts';
+
+const servers: Server[] = [];
+
+async function start(options: Partial<ContentDispatchOptions> = {}) {
+ const log = loggerFactory.getLogger('content-dispatch-test');
+ const legacy = vi.fn(
+ (_req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => {
+ res.writeHead(418);
+ res.end('legacy sentinel');
+ },
+ );
+ const app = createHttpApp({
+ log,
+ legacyDispatch: legacy,
+ contentDispatch: createContentDispatch({
+ ingressPolicy: buildIngressPolicy({}),
+ log,
+ ...options,
+ }),
+ });
+ const server = createServer(app.requestListener);
+ servers.push(server);
+ const { port } = await listenOnLoopback(server);
+ return { port, legacy };
+}
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(
+ (server) =>
+ new Promise<void>((resolve, reject) => {
+ server.closeAllConnections();
+ server.close((error) => (error ? reject(error) : resolve()));
+ }),
+ ),
+ );
+});
+
+describe('native content fallback ownership and middleware failures', () => {
+ test('non-API failures and no-shell hints never traverse legacy dispatch', async () => {
+ const { port, legacy } = await start();
+ const missing = await rawRequest(port, '/unrecognized');
+ expect(missing.status).toBe(404);
+ expect(missing.body).toContain('running without the web UI');
+ expect(legacy).not.toHaveBeenCalled();
+ const api = await rawRequest(port, '/api/remaining');
+ expect(api.status).toBe(418);
+ expect(api.body).toBe('legacy sentinel');
+ });
+
+ test.each(['contentAssetMiddleware', 'reactShellMiddleware'] as const)(
+ '%s failure before headers is a problem response',
+ async (key) => {
+ const { port, legacy } = await start({
+ [key]: () => {
+ readFileSync('/nonexistent-ok-middleware-failure');
+ },
+ });
+ const response = await rawRequest(port, '/route');
+ expect(response.status).toBe(500);
+ expect(response.headers['content-type']).toBe('application/problem+json');
+ expect(response.body).toContain('urn:ok:error:internal-server-error');
+ expect(legacy).not.toHaveBeenCalled();
+ },
+ );
+
+ test.each(['contentAssetMiddleware', 'reactShellMiddleware'] as const)(
+ '%s failure after headers ends only the original bytes',
+ async (key) => {
+ const { port, legacy } = await start({
+ [key]: (_req, res) => {
+ res.writeHead(200, { 'Content-Type': 'application/octet-stream' });
+ res.write('partial bytes');
+ readFileSync('/nonexistent-ok-middleware-failure');
+ },
+ });
+ const response = await rawRequest(port, '/route');
+ expect(response.status).toBe(200);
+ expect(response.headers['content-type']).toBe('application/octet-stream');
+ expect(response.body).toBe('partial bytes');
+ expect(legacy).not.toHaveBeenCalled();
+ },
+ );
+
+ test('next after a response cannot append shell bytes', async () => {
+ const { port, legacy } = await start({
+ contentAssetMiddleware: (_req, res, next) => {
+ res.end('content');
+ next();
+ },
+ reactShellMiddleware: (_req, res) => {
+ res.end('shell');
+ },
+ });
+ expect((await rawRequest(port, '/route')).body).toBe('content');
+ expect(legacy).not.toHaveBeenCalled();
+ });
+
+ test('forwarded admission precedes content execution and ephemeral Host admission precedes a content miss', async () => {
+ const { port, legacy } = await start({
+ ephemeral: true,
+ contentAssetMiddleware: (_req, res) => {
+ res.end('content reached');
+ },
+ });
+ const forwarded = await rawRequest(port, '/route', {
+ headers: { 'X-Forwarded-Host': 'public.example' },
+ });
+ expect(forwarded.status).toBe(403);
+ expect(forwarded.body).toContain('Proxied request refused');
+ const host = await rawRequest(port, '/route', { headers: { Host: 'evil.example' } });
+ expect(host.status).toBe(403);
+ expect(host.body).toContain('Host header not allowed');
+ expect(legacy).not.toHaveBeenCalled();
+ });
+});
+
+test('ephemeral peer refusal precedes Host admission and content execution', () => {
+ const content = vi.fn();
+ const shell = vi.fn();
+ const dispatch = createContentDispatch({
+ ephemeral: true,
+ ingressPolicy: buildIngressPolicy({}),
+ log: loggerFactory.getLogger('content-peer-test'),
+ contentAssetMiddleware: content,
+ reactShellMiddleware: shell,
+ });
+ const { res, captured } = makeCaptureRes();
+ dispatch(
+ makeSyntheticReq({ url: '/document.png', remoteAddress: '203.0.113.7', host: 'evil.example' }),
+ res,
+ );
+ expect(captured.status).toBe(403);
+ expect(JSON.parse(captured.body).type).toBe('urn:ok:error:loopback-required');
+ expect(content).not.toHaveBeenCalled();
+ expect(shell).not.toHaveBeenCalled();
+});
diff --git a/packages/server/src/http/content-dispatch.ts b/packages/server/src/http/content-dispatch.ts
new file mode 100644
index 000000000..190427a2a
--- /dev/null
+++ b/packages/server/src/http/content-dispatch.ts
@@ -0,0 +1,108 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+ HOST_NOT_ADMITTED_REMEDIATION,
+ type IngressPolicy,
+ isHostAdmitted,
+ isPeerAdmitted,
+} from '../ingress-policy.ts';
+import type { PinoLogger } from '../logger.ts';
+import { errorResponse } from './error-response.ts';
+import { admitRequestSurface } from './http-app.ts';
+
+type ServingMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void;
+
+export interface ContentDispatchOptions {
+ contentAssetMiddleware?: ServingMiddleware;
+ reactShellMiddleware?: ServingMiddleware;
+ ephemeral?: boolean;
+ ingressPolicy: IngressPolicy;
+ log: PinoLogger;
+}
+
+export function createContentDispatch({
+ contentAssetMiddleware,
+ reactShellMiddleware,
+ ephemeral,
+ ingressPolicy,
+ log,
+}: ContentDispatchOptions): (req: IncomingMessage, res: ServerResponse) => void {
+ return (req, res) => {
+ const url = req.url?.split('?')[0];
+ if (!admitRequestSurface(req, res, ingressPolicy, 'mcp-mount', log)) return;
+ const runMiddleware = (
+ middleware:
+ | ((req: IncomingMessage, res: ServerResponse, next: () => void) => void)
+ | undefined,
+ label: string,
+ onMiss: () => void,
+ ): void => {
+ if (middleware === undefined) {
+ onMiss();
+ return;
+ }
+ try {
+ middleware(req, res, () => {
+ if (res.writableEnded || res.headersSent) return;
+ onMiss();
+ });
+ } catch (err) {
+ log.error({ err }, `Unhandled ${label} middleware error`);
+ if (!res.writableEnded && !res.headersSent) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'mcp-mount',
+ cause: err,
+ });
+ } else if (!res.writableEnded) {
+ res.end();
+ }
+ }
+ };
+ const runContent = (onMiss: () => void): void => {
+ if (ephemeral === true && contentAssetMiddleware !== undefined) {
+ if (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
+ handler: 'content-asset-gate',
+ });
+ return;
+ }
+ if (!isHostAdmitted(req.headers.host, ingressPolicy)) {
+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
+ handler: 'content-asset-gate',
+ detail: HOST_NOT_ADMITTED_REMEDIATION,
+ });
+ return;
+ }
+ }
+ runMiddleware(contentAssetMiddleware, 'content-asset', onMiss);
+ };
+ const runShell = (onMiss: () => void): void =>
+ runMiddleware(reactShellMiddleware, 'react-shell', onMiss);
+ const notFound = (): void => {
+ if (res.writableEnded || res.headersSent) return;
+ const uiHint =
+ reactShellMiddleware === undefined
+ ? 'This server is running without the web UI. Restart it with plain `ok start` to serve the editor. '
+ : '';
+ errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {
+ handler: 'mcp-mount',
+ detail: `${uiHint}No handler for ${url ?? '/'}`,
+ });
+ };
+
+ if (
+ reactShellMiddleware !== undefined &&
+ (url?.startsWith('/assets/') || url?.startsWith('/excalidraw-assets/'))
+ ) {
+ runShell(() => runContent(notFound));
+ return;
+ }
+ if (contentAssetMiddleware !== undefined || reactShellMiddleware !== undefined) {
+ runContent(() => runShell(notFound));
+ return;
+ }
+ errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {
+ handler: 'mcp-mount',
+ detail: `This server is running without the web UI. Restart it with plain \`ok start\` to serve the editor. No handler for ${url ?? '/'}`,
+ });
+ };
+}
diff --git a/packages/server/src/http/http-app.test.ts b/packages/server/src/http/http-app.test.ts
index 782a71875..21c77340a 100644
--- a/packages/server/src/http/http-app.test.ts
+++ b/packages/server/src/http/http-app.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, test } from 'vitest';
import { rawRequest } from '../composition-rig.test-helper.ts';
import { buildIngressPolicy } from '../ingress-policy.ts';
import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';
+import { createContentDispatch } from './content-dispatch.ts';
import {
assertSingleRouterOwnership,
type CreateHttpAppOptions,
@@ -25,6 +26,10 @@ async function serveWith(
) {
const { requestListener } = createHttpApp({
legacyDispatch,
+ contentDispatch: createContentDispatch({
+ ingressPolicy: ingressPolicy ?? buildIngressPolicy({}),
+ log: fakeLog,
+ }),
mcpDispatch,
ingressPolicy,
log: fakeLog,
@@ -50,7 +55,7 @@ describe('createHttpApp adapter boundary', () => {
res.end();
});
try {
- const res = await fetch(`${rig.baseUrl}/anything`);
+ const res = await fetch(`${rig.baseUrl}/api/anything`);
expect(res.status).toBe(204);
expect(globalThis.Request).toBe(RequestBefore);
expect(globalThis.Response).toBe(ResponseBefore);
@@ -71,7 +76,7 @@ describe('createHttpApp adapter boundary', () => {
});
try {
const payload = 'x'.repeat(64 * 1024);
- const res = await fetch(`${rig.baseUrl}/echo`, { method: 'POST', body: payload });
+ const res = await fetch(`${rig.baseUrl}/api/echo`, { method: 'POST', body: payload });
expect(res.status).toBe(200);
expect(await res.text()).toBe(payload);
} finally {
@@ -85,7 +90,7 @@ describe('createHttpApp adapter boundary', () => {
throw new Error('post-head boom');
});
try {
- const res = await fetch(`${rig.baseUrl}/partial`, {
+ const res = await fetch(`${rig.baseUrl}/api/partial`, {
signal: AbortSignal.timeout(5_000),
});
expect(res.status).toBe(200);
@@ -134,7 +139,7 @@ describe('createHttpApp native /mcp mount', () => {
}
});
- test('a Hono-normalized alias of /mcp falls through to the legacy dispatch', async () => {
+ test('a Hono-normalized alias of /mcp reaches content without legacy dispatch', async () => {
let handled = 0;
let legacyUrl: string | undefined;
const dispatch = mcpDispatchOver(async (_req, res) => {
@@ -155,13 +160,15 @@ describe('createHttpApp native /mcp mount', () => {
const res = await rawRequest(rig.port, '/./mcp', { method: 'POST' });
expect(res.status).toBe(404);
expect(handled).toBe(0);
- expect(legacyUrl).toBe('/./mcp');
+ expect(legacyUrl).toBeUndefined();
+ expect(res.body).toContain('running without the web UI');
+ expect(res.body).toContain('No handler for /./mcp');
} finally {
await rig.close();
}
});
- test('without an MCP handler /mcp falls through the strangler catch-all', async () => {
+ test('without an MCP handler /mcp reaches the native content fallback', async () => {
let legacyUrl: string | undefined;
const rig = await serveWith((req, res) => {
legacyUrl = req.url;
@@ -171,7 +178,8 @@ describe('createHttpApp native /mcp mount', () => {
try {
const res = await fetch(`${rig.baseUrl}/mcp`, { method: 'POST' });
expect(res.status).toBe(404);
- expect(legacyUrl).toBe('/mcp');
+ expect(legacyUrl).toBeUndefined();
+ expect(await res.text()).toContain('running without the web UI');
} finally {
await rig.close();
}
diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.ts
index 67780df9e..33f2b99e2 100644
--- a/packages/server/src/http/http-app.ts
+++ b/packages/server/src/http/http-app.ts
@@ -93,9 +93,14 @@ export function assertSingleRouterOwnership(
}
}
+function isApiPath(url: string | undefined): boolean {
+ return (url?.split('?')[0] ?? '').startsWith('/api/');
+}
+
export interface CreateHttpAppOptions {
health?: HealthProvider;
legacyDispatch: (req: IncomingMessage, res: ServerResponse) => void;
+ contentDispatch: (req: IncomingMessage, res: ServerResponse) => void;
nativeApi?: NativeApiHandle;
mcpDispatch?: McpDispatch;
ingressPolicy?: IngressPolicy;
@@ -166,6 +171,14 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
const ingressPolicy = opts.ingressPolicy ?? buildIngressPolicy({});
+ const dispatchFallback = (req: IncomingMessage, res: ServerResponse): void => {
+ if (!isApiPath(req.url)) {
+ opts.contentDispatch(req, res);
+ return;
+ }
+ opts.legacyDispatch(req, res);
+ };
+
const mcpDispatch = opts.mcpDispatch;
if (mcpDispatch !== undefined) {
app.all('/mcp', (c) => {
@@ -173,7 +186,7 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
const res = c.env.outgoing;
const url = req.url?.split('?')[0];
if (url !== '/mcp') {
- opts.legacyDispatch(req, res);
+ dispatchFallback(req, res);
return RESPONSE_ALREADY_SENT;
}
if (!admitRequestSurface(req, res, ingressPolicy, 'native-mcp-surface', opts.log)) {
@@ -195,7 +208,7 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
}
try {
const handled = await nativeApi.dispatch(req, res);
- if (!handled) opts.legacyDispatch(req, res);
+ if (!handled) dispatchFallback(req, res);
} catch (err) {
opts.log.error({ err }, 'Unhandled onRequest error');
if (!res.writableEnded && !res.headersSent) {
@@ -219,7 +232,7 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {
}
app.all('*', (c) => {
- opts.legacyDispatch(c.env.incoming, c.env.outgoing);
+ dispatchFallback(c.env.incoming, c.env.outgoing);
return RESPONSE_ALREADY_SENT;
});
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index e73afa8be..5a2f52d91 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -7,6 +7,7 @@ import type { AgentFocusBroadcaster } from './agent-focus.ts';
import type { AgentPresenceBroadcaster } from './agent-presence.ts';
import type { AgentSessionManager } from './agent-sessions.ts';
import { createCollaborationHost } from './collaboration-host.ts';
+import { createContentDispatch } from './http/content-dispatch.ts';
import { errorResponse } from './http/error-response.ts';
import {
admitRequestSurface,
@@ -17,10 +18,7 @@ import {
import { createMcpDispatch } from './http/mcp-route.ts';
import {
buildIngressPolicy,
- HOST_NOT_ADMITTED_REMEDIATION,
type IngressPolicy,
- isHostAdmitted,
- isPeerAdmitted,
tripsForwardedHeaderTripwire,
warnForwardedHeaderRefusalOnce,
} from './ingress-policy.ts';
@@ -85,51 +83,18 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
const url = req.url?.split('?')[0];
if (!admitRequestSurface(req, res, ingressPolicy, 'mcp-mount', log)) return;
- if (url?.startsWith('/api/')) {
- hocuspocus
- // biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequest
- .hooks('onRequest', { request: req, response: res } as any)
- .then(() => {
- if (res.writableEnded || res.headersSent) return;
- errorResponse(res, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
- handler: 'mcp-mount',
- detail: `No handler for ${req.method ?? 'GET'} ${url}`,
- });
- })
- .catch((err) => {
- log.error({ err }, 'Unhandled onRequest error');
- if (!res.writableEnded && !res.headersSent) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Internal server error.',
- { handler: 'mcp-mount', cause: err },
- );
- } else if (!res.writableEnded) {
- res.end();
- }
- });
- return;
- }
- const runMiddleware = (
- middleware:
- | ((req: IncomingMessage, res: ServerResponse, next: () => void) => void)
- | undefined,
- label: string,
- onMiss: () => void,
- ): void => {
- if (middleware === undefined) {
- onMiss();
- return;
- }
- try {
- middleware(req, res, () => {
- if (res.writableEnded || res.headersSent) return;
- onMiss();
+ hocuspocus
+ // biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequest
+ .hooks('onRequest', { request: req, response: res } as any)
+ .then(() => {
+ if (res.writableEnded || res.headersSent) return;
+ errorResponse(res, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {
+ handler: 'mcp-mount',
+ detail: `No handler for ${req.method ?? 'GET'} ${url}`,
});
- } catch (err) {
- log.error({ err }, `Unhandled ${label} middleware error`);
+ })
+ .catch((err) => {
+ log.error({ err }, 'Unhandled onRequest error');
if (!res.writableEnded && !res.headersSent) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: 'mcp-mount',
@@ -138,55 +103,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
} else if (!res.writableEnded) {
res.end();
}
- }
- };
- const runContent = (onMiss: () => void): void => {
- if (ephemeral === true && contentAssetMiddleware !== undefined) {
- if (!isPeerAdmitted(req.socket.remoteAddress, ingressPolicy)) {
- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
- handler: 'content-asset-gate',
- });
- return;
- }
- if (!isHostAdmitted(req.headers.host, ingressPolicy)) {
- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
- handler: 'content-asset-gate',
- detail: HOST_NOT_ADMITTED_REMEDIATION,
- });
- return;
- }
- }
- runMiddleware(contentAssetMiddleware, 'content-asset', onMiss);
- };
- const runShell = (onMiss: () => void): void =>
- runMiddleware(reactShellMiddleware, 'react-shell', onMiss);
- const notFound = (): void => {
- if (res.writableEnded || res.headersSent) return;
- const uiHint =
- reactShellMiddleware === undefined
- ? 'This server is running without the web UI. Restart it with plain `ok start` to serve the editor. '
- : '';
- errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {
- handler: 'mcp-mount',
- detail: `${uiHint}No handler for ${url ?? '/'}`,
});
- };
-
- if (
- reactShellMiddleware !== undefined &&
- (url?.startsWith('/assets/') || url?.startsWith('/excalidraw-assets/'))
- ) {
- runShell(() => runContent(notFound));
- return;
- }
- if (contentAssetMiddleware !== undefined || reactShellMiddleware !== undefined) {
- runContent(() => runShell(notFound));
- return;
- }
- errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {
- handler: 'mcp-mount',
- detail: `This server is running without the web UI. Restart it with plain \`ok start\` to serve the editor. No handler for ${url ?? '/'}`,
- });
};
const onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
@@ -210,6 +127,13 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
: undefined,
ingressPolicy,
legacyDispatch: onRequest,
+ contentDispatch: createContentDispatch({
+ contentAssetMiddleware,
+ reactShellMiddleware,
+ ephemeral,
+ ingressPolicy,
+ log,
+ }),
log,
});
httpServer.on('request', requestListener);