ds-harness-remote-fast/packages/plugin/src/control-route.ts

206 lines
6.8 KiB
TypeScript

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<void>
}
}
export interface HostWebServerLike {
register(route: {
kind: 'prefix'
path: string
handler(req: IncomingMessage, res: ServerResponse): void | Promise<void>
}): () => void | Promise<void>
}
export type ControlRouteHandler = (
endpoint: string,
payload: unknown,
signal: AbortSignal,
) => Promise<ControlResult<unknown>>
/** Long-lived loopback response owner for the status event stream. */
export interface ControlStatusStreamLike {
handle(response: ServerResponse): Promise<void>
close(): void
}
export function registerControlRoute(
connection: HostConnectionHandleLike,
handler: ControlRouteHandler,
webServer?: HostWebServerLike,
statusStream?: ControlStatusStreamLike,
): () => Promise<void> {
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<void> {
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<unknown> {
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<string, unknown>
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<string, unknown>
return typeof record.rpcId === 'string' ? record.rpcId : INVALID_REQUEST_RPC_ID
}
function errorResponse(rpcId: string, error: { code: string; message: string; details: Record<string, unknown> }): Record<string, unknown> {
return fullResponse(rpcId, { ok: false, error })
}
function fullResponse(rpcId: string, result: unknown): Record<string, unknown> {
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)
}