Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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): MountMcpAndApiHandlconst 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);