import type { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http' import type { ControlResult } from './control-result.js' /** Namespaced loopback RPC prefix shared by the Host runtime and browser UI. */ export const CONTROL_RPC_PREFIX = '/ds-harness-remote' /** Loopback control endpoint carrying the status event stream. */ export const STATUS_STREAM_ENDPOINT = 'status.events' /** Full URL path of the loopback status event stream. */ export const STATUS_STREAM_PATH = `${CONTROL_RPC_PREFIX}/${STATUS_STREAM_ENDPOINT}` const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/ const INVALID_REQUEST_RPC_ID = 'invalid-request' interface HostConnectionHandleLike { requestRejection?(request: { headers: IncomingHttpHeaders }): number | undefined rpc: { handle?( channel: string, handler: ControlRouteHandler, options: { authority: 'loopback' | 'trusted-host' }, ): () => Promise } } export interface HostWebServerLike { register(route: { kind: 'prefix' path: string handler(req: IncomingMessage, res: ServerResponse): void | Promise }): () => void | Promise } export type ControlRouteHandler = ( endpoint: string, payload: unknown, signal: AbortSignal, ) => Promise> /** Long-lived loopback response owner for the status event stream. */ export interface ControlStatusStreamLike { handle(response: ServerResponse): Promise close(): void } export function registerControlRoute( connection: HostConnectionHandleLike, handler: ControlRouteHandler, webServer?: HostWebServerLike, statusStream?: ControlStatusStreamLike, ): () => Promise { if (webServer !== undefined && connection.requestRejection !== undefined) { const dispose = webServer.register({ kind: 'prefix', path: CONTROL_RPC_PREFIX, handler: (req, res) => handleControlRequest(connection, handler, req, res, statusStream), }) return async () => { statusStream?.close() await dispose() } } // A plain RPC channel owns POST only, so the browser falls back to unary // status reads on hosts that do not expose the Web server route. const rpcHandle = connection.rpc.handle // Older or partially initialized carriers may expose neither the Web Server // route registry nor the legacy RPC helper. Do not let that optional // compatibility path abort plugin activation and leave the UI stuck in // "control is still starting". if (rpcHandle === undefined) return async () => undefined return rpcHandle(CONTROL_RPC_PREFIX, handler, { authority: 'loopback', }) } async function handleControlRequest( connection: HostConnectionHandleLike, handler: ControlRouteHandler, req: IncomingMessage, res: ServerResponse, statusStream?: ControlStatusStreamLike, ): Promise { const rejection = connection.requestRejection?.(req) if (rejection !== undefined) { res.writeHead(rejection) res.end(rejection === 401 ? 'unauthorized' : 'forbidden') return } const endpoint = endpointFromPath(CONTROL_RPC_PREFIX, new URL(req.url ?? '/', 'http://dsh.internal').pathname) if (req.method === 'GET' && endpoint === STATUS_STREAM_ENDPOINT && statusStream !== undefined) { await statusStream.handle(res) return } if (req.method !== 'POST' || endpoint === undefined) { writeText(res, 404, 'not found') return } if (contentType(req.headers) !== 'application/json') { writeText(res, 415, 'content type must be application/json') return } let body: unknown try { body = await readJsonBody(req) } catch { writeText(res, 400, 'body is not JSON') return } const message = clientRequest(body) if (message === undefined) { writeJson(res, 200, errorResponse(rpcId(body), { code: 'gateway/bad-request', message: 'invalid client-request message', details: { issues: [] }, })) return } if (message.method !== endpoint) { writeJson(res, 200, errorResponse(message.rpcId, { code: 'gateway/bad-request', message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`, details: { issues: [] }, })) return } try { const result = await handler(endpoint, message.payload, requestSignal(req)) writeJson(res, 200, fullResponse(message.rpcId, result)) } catch (error) { writeText(res, 500, `handler failure: ${String(error)}`) } } function endpointFromPath(channel: string, pathname: string): string | undefined { if (!pathname.startsWith(`${channel}/`)) return undefined const endpoint = pathname.slice(channel.length + 1) if (endpoint.split('/').some(segment => segment === '' || segment === '.' || segment === '..' || !ENDPOINT_SEGMENT_PATTERN.test(segment))) { return undefined } return endpoint } function contentType(headers: IncomingHttpHeaders): string | undefined { const raw = headers['content-type'] const value = Array.isArray(raw) ? raw[0] : raw return value?.split(';', 1)[0]?.trim().toLowerCase() } async function readJsonBody(req: IncomingMessage): Promise { const chunks: Buffer[] = [] for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)) return JSON.parse(Buffer.concat(chunks).toString('utf8')) } function requestSignal(req: IncomingMessage): AbortSignal { const abort = new AbortController() req.on('close', () => { if (!req.complete) abort.abort() }) return abort.signal } interface ClientRequestWire { type: 'client-request' rpcId: string method: string payload: unknown } function clientRequest(value: unknown): ClientRequestWire | undefined { if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined const record = value as Record if (record.type !== 'client-request' || typeof record.rpcId !== 'string' || typeof record.method !== 'string') return undefined return { type: 'client-request', rpcId: record.rpcId, method: record.method, payload: record.payload } } function rpcId(value: unknown): string { if (typeof value !== 'object' || value === null || Array.isArray(value)) return INVALID_REQUEST_RPC_ID const record = value as Record return typeof record.rpcId === 'string' ? record.rpcId : INVALID_REQUEST_RPC_ID } function errorResponse(rpcId: string, error: { code: string; message: string; details: Record }): Record { return fullResponse(rpcId, { ok: false, error }) } function fullResponse(rpcId: string, result: unknown): Record { return { type: 'server-response', rpcId, result } } function writeJson(res: ServerResponse, status: number, body: unknown): void { res.writeHead(status, { 'content-type': 'application/json' }) res.end(JSON.stringify(body)) } function writeText(res: ServerResponse, status: number, body: string): void { res.writeHead(status) res.end(body) }