Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { createApiExtension } from './api-extension.test-helper.ts';
import type { FileIndexEntry } from './file-watcher.ts';
import { loggerFactory } from './logger.ts';
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
interface CapturedResponse {
status: number;
headers: Record<string, string>;
setHeaders: Record<string, string>;
body: string;
}
function makeReq(url: string, extraHeaders: Record<string, string> = {}): IncomingMessage {
const readable = Readable.from(Buffer.from('')) as unknown as IncomingMessage;
readable.method = 'GET';
readable.url = url;
readable.headers = { host: 'localhost', ...extraHeaders };
return readable;
}
function makeRes(): { res: ServerResponse; captured: CapturedResponse } {
const captured: CapturedResponse = { status: 0, headers: {}, setHeaders: {}, body: '' };
const listeners: Record<string, Array<() => void>> = {};
const res = {
statusCode: 200,
headersSent: false,
writableEnded: false,
writableFinished: false,
destroyed: false,
setHeader(name: string, value: string) {
captured.setHeaders[name.toLowerCase()] = value;
},
once(event: string, fn: () => void) {
listeners[event] ??= [];
listeners[event].push(fn);
return res;
},
writeHead(status: number, headers?: Record<string, string>) {
captured.status = status;
res.statusCode = status;
res.headersSent = true;
if (headers) Object.assign(captured.headers, headers);
return res;
},
end(body?: string) {
captured.body = body ?? '';
res.writableEnded = true;
res.writableFinished = true;
for (const fn of listeners.finish ?? []) fn();
for (const fn of listeners.close ?? []) fn();
},
};
return { res: res as unknown as ServerResponse, captured };
}
describe('onRequest request identity + access log', () => {
let projectDir: string;
let contentDir: string;
beforeEach(() => {
projectDir = mkdtempSync(join(tmpdir(), 'ok-request-id-'));
contentDir = join(projectDir, 'content');
mkdirSync(contentDir, { recursive: true });
});
afterEach(() => {
rmSync(projectDir, { recursive: true, force: true });
vi.restoreAllMocks();
});
async function callRoute(
url: string,
headers: Record<string, string> = {},
): Promise<CapturedResponse> {
const ext = createApiExtension({
hocuspocus: {} as never,
sessionManager: {} as never,
contentDir,
getFileIndex: () => new Map<string, FileIndexEntry>(),
});
const req = makeReq(url, headers);
const { res, captured } = makeRes();
await (
ext as {
onRequest: (ctx: { request: IncomingMessage; response: ServerResponse }) => Promise<void>;
}
).onRequest({ request: req, response: res });
return captured;
}
test('mints a UUID x-request-id echo when the client sends none', async () => {
const captured = await callRoute('/api/nonexistent-route');
expect(captured.status).toBe(404);
expect(captured.setHeaders['x-request-id']).toMatch(UUID_RE);
});
test('honors a well-formed incoming x-request-id', async () => {
const captured = await callRoute('/api/nonexistent-route', {
'x-request-id': 'caller-supplied.001',
});
expect(captured.setHeaders['x-request-id']).toBe('caller-supplied.001');
});
test('replaces a malformed incoming x-request-id with a minted UUID', async () => {
const captured = await callRoute('/api/nonexistent-route', {
'x-request-id': 'bad id with spaces',
});
expect(captured.setHeaders['x-request-id']).toMatch(UUID_RE);
expect(captured.setHeaders['x-request-id']).not.toBe('bad id with spaces');
});
test('origin-gate 403 rejections still carry the x-request-id echo', async () => {
const captured = await callRoute('/api/nonexistent-route', {
origin: 'https://evil.example.com',
});
expect(captured.status).toBe(403);
expect(JSON.parse(captured.body).type).toBe('urn:ok:error:invalid-origin');
expect(captured.setHeaders['x-request-id']).toMatch(UUID_RE);
});
test('exposes the header to cross-origin readers and allows it on requests', async () => {
const captured = await callRoute('/api/nonexistent-route', {
origin: 'http://localhost:5173',
});
expect(captured.setHeaders['access-control-expose-headers']).toBe('x-request-id');
expect(captured.setHeaders['access-control-allow-headers']).toContain('x-request-id');
});
test('emits ONE api.access line with the route TEMPLATE, status, duration, and request id', async () => {
const log = loggerFactory.getLogger('api');
const infoSpy = vi.spyOn(log, 'info');
const captured = await callRoute('/api/history/');
const accessCalls = infoSpy.mock.calls.filter(
(c) => (c[0] as { event?: string })?.event === 'api.access',
);
expect(accessCalls).toHaveLength(1);
const line = accessCalls[0]?.[0] as {
requestId: string;
method: string;
route: string;
status: number;
durationMs: number;
};
expect(line.route).toBe('/api/history/:sha');
expect(line.route).not.toBe('/api/history/');
expect(line.method).toBe('GET');
expect(line.status).toBe(404);
expect(typeof line.durationMs).toBe('number');
expect(line.requestId).toBe(captured.setHeaders['x-request-id']);
});
test('unmatched routes collapse to the /api/* template on the access line', async () => {
const log = loggerFactory.getLogger('api');
const infoSpy = vi.spyOn(log, 'info');
await callRoute('/api/no-such-endpoint-xyz');
const accessCalls = infoSpy.mock.calls.filter(
(c) => (c[0] as { event?: string })?.event === 'api.access',
);
expect(accessCalls).toHaveLength(1);
expect((accessCalls[0]?.[0] as { route: string } | undefined)?.route).toBe('/api/*');
});
async function accessLineFor(headers: Record<string, string>) {
const log = loggerFactory.getLogger('api');
const infoSpy = vi.spyOn(log, 'info');
await callRoute('/api/history/', headers);
const accessCalls = infoSpy.mock.calls.filter(
(c) => (c[0] as { event?: string })?.event === 'api.access',
);
expect(accessCalls).toHaveLength(1);
infoSpy.mockRestore();
return accessCalls[0]?.[0] as { clientSurface?: string };
}
test('the access line carries the client surface the app sends on x-ok-client-kind', async () => {
for (const surface of [
'desktop',
'browser',
'embedded:cursor',
'embedded:codex',
'embedded:claude-desktop',
]) {
const line = await accessLineFor({ 'x-ok-client-kind': surface });
expect(line.clientSurface).toBe(surface);
}
});
test("an older client's kind=web is logged as an unknown surface", async () => {
const line = await accessLineFor({ 'x-ok-client-kind': 'web' });
expect(line.clientSurface).toBe('unknown');
});
test('requests without an app kind log no surface', async () => {
expect((await accessLineFor({})).clientSurface).toBeUndefined();
expect((await accessLineFor({ 'x-ok-client-kind': 'mcp' })).clientSurface).toBeUndefined();
expect((await accessLineFor({ 'x-ok-client-kind': 'cli' })).clientSurface).toBeUndefined();
expect(
(await accessLineFor({ 'x-ok-client-kind': 'desktop-main' })).clientSurface,
).toBeUndefined();
});
test('the HTTP server span carries ok.client.surface', async () => {
const { context: apiContext, trace } = await import('@opentelemetry/api');
const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');
const { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } = await import(
'@opentelemetry/sdk-trace-base'
);
const exporter = new InMemorySpanExporter();
const provider = new BasicTracerProvider({
spanProcessors: [new SimpleSpanProcessor(exporter)],
});
trace.setGlobalTracerProvider(provider);
apiContext.setGlobalContextManager(new AsyncLocalStorageContextManager());
try {
await callRoute('/api/history/', { 'x-ok-client-kind': 'embedded:codex' });
await callRoute('/api/history/', { 'x-ok-client-kind': 'web' });
await callRoute('/api/history/');
const surfaces = exporter
.getFinishedSpans()
.filter((span) => span.name.startsWith('HTTP '))
.map((span) => span.attributes['ok.client.surface']);
expect(surfaces).toEqual(['embedded:codex', 'unknown', undefined]);
} finally {
await provider.shutdown();
trace.disable();
apiContext.disable();
}
});
test('non-API requests get no x-request-id echo and no access line', async () => {
const log = loggerFactory.getLogger('api');
const infoSpy = vi.spyOn(log, 'info');
const captured = await callRoute('/some/static/path.css');
expect(captured.setHeaders['x-request-id']).toBeUndefined();
const accessCalls = infoSpy.mock.calls.filter(
(c) => (c[0] as { event?: string })?.event === 'api.access',
);
expect(accessCalls).toHaveLength(0);
});
});