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

322 lines
16 KiB
TypeScript

import { CONTROL_RPC_PREFIX } from './control-route.js'
type Fetch = typeof globalThis.fetch
class PluginRouteFailure extends Error {
constructor(
readonly code: string,
message: string,
readonly details: Record<string, unknown> = {},
) { super(message) }
}
const KNOWN_ERROR_NAMES = new Set([
'TimeoutError',
'TypeError',
'RangeError',
'SyntaxError',
'ReferenceError',
'URIError',
'EvalError',
'Error',
'AbortError',
'DOMException',
])
function sanitizeErrorName(error: unknown): string {
if (typeof error === 'object' && error !== null && 'name' in error) {
const name = (error as { name?: unknown }).name
if (typeof name === 'string' && KNOWN_ERROR_NAMES.has(name)) return name
}
return 'Error'
}
/** A timeout is distinguishable from a caller abort: only the former may be retried. */
function isTimeoutError(error: unknown): boolean {
for (let current: unknown = error, depth = 0; current !== undefined && current !== null && depth < 4; depth++) {
if (typeof current !== 'object') return false
const candidate = current as { name?: unknown; code?: unknown; cause?: unknown }
if (candidate.name === 'TimeoutError') return true
if (candidate.code === 'UND_ERR_CONNECT_TIMEOUT' || candidate.code === 'ETIMEDOUT') return true
current = candidate.cause
}
return false
}
function isAbortFailure(error: unknown, signal?: AbortSignal): boolean {
if (signal?.aborted === true) return true
return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'AbortError'
}
export interface PluginRouteClientOptions {
/** Publish a remote roster only after the official Session catalog has caught up. */
beforeResponse?(status: Record<string, unknown>, body: Record<string, unknown>, json: unknown, signal: AbortSignal): Promise<void>
}
/** Route authority is read before each plugin request, including the first page load. */
export function createPluginRouteFetch(original: Fetch, baseUrl: string, options: PluginRouteClientOptions = {}): Fetch {
const routeUrl = new URL('api/bot', baseUrl)
let nextRpcId = 0
const control = async (method: string, payload: unknown, signal?: AbortSignal): Promise<unknown> => {
const rpcId = `plugin-route-${++nextRpcId}`
let response: Response
try {
response = await original(new URL(`${CONTROL_RPC_PREFIX.slice(1)}/${method}`, baseUrl), {
method: 'POST',
credentials: 'same-origin',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ type: 'client-request', rpcId, method, payload }),
signal,
})
} catch (error) {
// A caller abort or an expired deadline is cancellation, not a dead
// control channel, so it must keep propagating as `AbortError`.
if (isAbortFailure(error, signal) || isTimeoutError(error)) throw error
throw new PluginRouteFailure('remote-plugin/control-unavailable', 'The local Remote control request failed. Reload the Remote plugin.', {
stage: 'transport',
method,
errorName: sanitizeErrorName(error),
})
}
if (!response.ok) {
throw new PluginRouteFailure('remote-plugin/control-unavailable', `The local Remote control request failed (HTTP ${response.status}). Reload the Remote plugin.`, {
stage: 'transport',
method,
httpStatus: response.status,
})
}
const envelope: unknown = await response.json()
if (!isRecord(envelope) || envelope.type !== 'server-response' || envelope.rpcId !== rpcId
|| !isRecord(envelope.result)) {
throw new PluginRouteFailure('remote-plugin/control-invalid', 'The local Remote control response is invalid. Reload the Remote plugin.')
}
if (envelope.result.ok !== true) {
const error = isRecord(envelope.result.error) ? envelope.result.error : undefined
const details = isRecord(error?.details) ? error.details : undefined
const code = details?.remoteCode ?? error?.code
if (code === 'FEATURE_NOT_SUPPORTED' || code === 'METHOD_NOT_FOUND') {
throw new PluginRouteFailure('remote-plugin/host-unsupported', 'The selected Host does not support plugin route forwarding. Update and reload Remote on the Host, then reconnect.')
}
if (code === 'REMOTE_NOT_CONNECTED' || code === 'TRANSPORT_CLOSED') {
throw new PluginRouteFailure('remote-plugin/disconnected', 'The Remote Host is disconnected. Reconnect to load DS Bot.')
}
if (code === 'INVALID_MESSAGE') {
throw new PluginRouteFailure('remote-plugin/operation-not-allowed', 'This DS Bot operation is not allowed over Remote. Use the Host locally.')
}
throw new PluginRouteFailure('remote-plugin/control-rejected', 'The Remote plugin route request was rejected by the control channel.')
}
return envelope.result.value
}
return async (input, init) => {
const requestUrl = new URL(input instanceof Request ? input.url : String(input), baseUrl)
const method = init?.method ?? (input instanceof Request ? input.method : 'GET')
if (method.toUpperCase() !== 'POST' || requestUrl.href !== routeUrl.href) return original(input, init)
const signal = init?.signal !== undefined ? init.signal ?? undefined : input instanceof Request ? input.signal : undefined
const lifetime = signal ?? AbortSignal.timeout(45_000)
try {
lifetime.throwIfAborted()
// The 10s probe deadline is ours, not the caller's: while the outer
// lifetime is still live, a probe timeout means the local control
// channel is wedged, which needs a distinct reload-the-plugin signal.
let status: unknown
const probeTimeout = AbortSignal.timeout(10_000)
const probeSignal = AbortSignal.any([lifetime, probeTimeout])
try {
status = await control('status', {}, probeSignal)
} catch (error) {
if (error instanceof PluginRouteFailure) throw error
lifetime.throwIfAborted()
if (probeTimeout.aborted) {
throw new PluginRouteFailure('remote-plugin/control-timeout', 'The local Remote control probe timed out. Reload the Remote plugin.', {
stage: 'status',
timeoutMs: 10_000,
errorName: sanitizeErrorName(error),
})
}
if (isTimeoutError(error)) {
throw new PluginRouteFailure('remote-plugin/control-timeout', 'The local Remote control request timed out. Reload the Remote plugin.', {
stage: 'transport',
method: 'status',
errorName: sanitizeErrorName(error),
})
}
throw error
}
lifetime.throwIfAborted()
if (!isRecord(status)) throw new PluginRouteFailure('remote-plugin/authority-unavailable', 'The Remote plugin route authority is unavailable.')
if (status.mode === 'local') return original(input, init)
// Once Remote owns the page, never read the local plugin's roster on a
// disconnect, missing capability, or virtual CodeX/ACP Session catalog.
if (status.mode !== 'remote') throw new PluginRouteFailure('remote-plugin/authority-unavailable', 'The Remote plugin route authority is unavailable.')
if (status.connected !== true) throw new PluginRouteFailure('remote-plugin/disconnected', 'The Remote Host is disconnected. Reconnect to load DS Bot.')
if (!isRecord(status.remoteFeatures) || status.remoteFeatures.pluginRoute !== true) throw new PluginRouteFailure('remote-plugin/host-unsupported', 'The selected Host does not support plugin route forwarding. Update and reload Remote on the Host, then reconnect.')
if (status.backend !== undefined && status.backend !== 'harness') throw new PluginRouteFailure('remote-plugin/backend-unsupported', 'DS Bot requires the Remote Harness catalog. Select a Harness workspace on this Host.')
const request = input instanceof Request
? new Request(input, init)
: new Request(requestUrl, init)
const body: unknown = await request.clone().json().catch((error: unknown) => {
throw new PluginRouteFailure('remote-plugin/route-request-invalid', 'The plugin route body must be a JSON object.', {
stage: 'request-body',
errorName: sanitizeErrorName(error),
})
})
if (!isRecord(body)) {
throw new PluginRouteFailure('remote-plugin/route-request-invalid', 'The plugin route body must be a JSON object.', { stage: 'request-body' })
}
const result = await control('plugin.route', { route: 'api/bot', body }, lifetime)
if (!isRecord(result) || !Number.isInteger(result.status)
|| (result.status as number) < 200 || (result.status as number) > 599) {
throw new PluginRouteFailure('remote-plugin/route-response-invalid', 'The plugin route response is invalid.', { stage: 'response-structure' })
}
const statusCode = result.status as number
// DS Bot polls state even when it is absent on the selected Host.
// Absence is an empty roster; mutations must still report the missing route.
// Probe each time so enabling the plugin needs no reconnect or cache reset.
if (statusCode === 404 && body.endpoint === 'state') {
return new Response(JSON.stringify({ ok: true, value: { bots: [], rooms: [], agents: [] } }), {
status: 200, headers: { 'content-type': 'application/json' },
})
}
if (statusCode === 404) throw new PluginRouteFailure('remote-plugin/bot-not-loaded', 'The Host has no DS Bot route. Enable ds-bot in the same DSH instance/profile as the connected Host.')
if (statusCode === 503) throw new PluginRouteFailure('remote-plugin/host-carrier-unavailable', 'The Host plugin route carrier is unavailable. Update and reload Remote on the Host.')
if (statusCode >= 200 && statusCode < 300 && options.beforeResponse !== undefined) {
try {
await waitWithSignal(options.beforeResponse(status, body, result.json, lifetime), lifetime)
} catch {
lifetime.throwIfAborted()
throw new PluginRouteFailure('remote-plugin/catalog-unavailable', 'The Remote Harness Session catalog is not ready. Reconnect before loading DS Bot.')
}
}
lifetime.throwIfAborted()
return new Response([204, 205, 304].includes(statusCode) ? null : JSON.stringify(result.json ?? null), {
status: statusCode,
headers: { 'content-type': 'application/json' },
})
} catch (error) {
lifetime.throwIfAborted()
// Unexpected failures collapse into one stable code: the original
// message may carry private upstream data and must never be echoed.
const failure = error instanceof PluginRouteFailure ? error
: isTimeoutError(error)
? new PluginRouteFailure('remote-plugin/control-timeout', 'The Remote plugin route request timed out. Reload the Remote plugin.', {
stage: 'route',
errorName: sanitizeErrorName(error),
})
: new PluginRouteFailure('remote-plugin/unavailable', 'The Remote plugin route is unavailable.', {
errorName: sanitizeErrorName(error),
})
// DS Bot reads its error envelope only for HTTP success. A synthetic 502
// hides every refusal behind "HTTP 502" before it can read the reason.
return new Response(JSON.stringify({
ok: false,
error: {
code: failure.code,
message: failure.message,
details: failure.details,
},
}), { status: 200, headers: { 'content-type': 'application/json' } })
}
}
}
export interface PluginRouteSessions {
list: { getSnapshot(): { ids: readonly string[]; phase: string } }
refresh?(): Promise<void>
}
/** `ready` is monotone in Harness; prove membership instead of trusting refresh's void result. */
export function createPluginRouteCatalogGuard(
readSessions: () => Promise<PluginRouteSessions>,
): NonNullable<PluginRouteClientOptions['beforeResponse']> {
return async (_status, body, json, signal) => {
if (!isRecord(json) || json.ok !== true || !isRecord(json.value)) return
const required = botSessionIds(body.endpoint, json.value)
if (required.size === 0) return
const sessions = await readSessions()
const containsSessions = () => {
const snapshot = sessions.list.getSnapshot()
const known = new Set(snapshot.ids)
return snapshot.phase === 'ready' && [...required].every(id => known.has(id))
}
// A first refresh may join a pull that started before the Bot mutation.
// One further pull lets that in-flight baseline finish without an unbounded retry loop.
for (let attempt = 0; attempt < 2; attempt++) {
signal.throwIfAborted()
if (containsSessions()) return
if (sessions.refresh === undefined) break
await sessions.refresh()
}
signal.throwIfAborted()
if (!containsSessions()) throw new Error('The Remote Session catalog does not contain the published Sessions.')
}
}
function botSessionIds(endpoint: unknown, value: Record<string, unknown>): Set<string> {
const ids = new Set<string>()
const add = (id: unknown) => {
if (id === undefined || id === null) return
if (typeof id !== 'string' || id.length === 0) throw new Error('Invalid Bot Session identity.')
ids.add(id)
}
const addArray = (input: unknown) => {
if (input === undefined) return
if (!Array.isArray(input)) throw new Error('Invalid Bot Session identities.')
input.forEach(add)
}
const bot = (input: unknown) => {
if (!isRecord(input)) throw new Error('Invalid Bot catalog entry.')
add(input.id)
add(input.sessionId)
addArray(input.parts)
if (Array.isArray(input.segments)) input.segments.forEach(segment => {
if (!isRecord(segment)) throw new Error('Invalid Bot Session segment.')
add(segment.sessionId)
})
}
const room = (input: unknown) => {
if (!isRecord(input)) throw new Error('Invalid Bot room entry.')
add(input.id)
add(input.sessionId)
addArray(input.ownParts)
addArray(input.parts)
if (isRecord(input.sessions)) Object.values(input.sessions).forEach(add)
}
const agent = (input: unknown) => {
if (!isRecord(input)) throw new Error('Invalid Bot agent entry.')
// Agent IDs are roster identities, not Harness Session IDs.
addArray(input.sessions)
}
const roster = () => {
for (const [key, visit] of [['bots', bot], ['rooms', room], ['agents', agent]] as const) {
if (value[key] === undefined) continue
if (!Array.isArray(value[key])) throw new Error('Invalid Bot roster.')
value[key].forEach(visit)
}
}
switch (endpoint) {
case 'state': case 'delete-bot': case 'delete-room': case 'set-main': case 'remove-agent': case 'goal-draft': case 'goal-control': roster(); break
case 'create-bot': case 'duplicate-bot': case 'update-bot': bot(value); break
case 'create-room': room(value); break
case 'update-room': room(value.room); break
case 'add-agent': agent(value); break
case 'agent-session': case 'agent-adopt': add(value.sessionId); break
case 'set-flags': Array.isArray(value.sessions) ? agent(value) : Array.isArray(value.members) ? room(value) : bot(value); break
}
return ids
}
function waitWithSignal<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
return new Promise<T>((resolve, reject) => {
const onAbort = () => reject(signal.reason)
signal.addEventListener('abort', onAbort, { once: true })
if (signal.aborted) onAbort()
void pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
})
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}