Import packages/client-core/src/remote-gateway.ts

This commit is contained in:
QQ 2026-11-14 14:44:28 +08:00
parent 8eb047a67a
commit c620cf8d24
1 changed files with 595 additions and 0 deletions

View File

@ -0,0 +1,595 @@
import {
HARNESS_API_TRANSFER_CHUNK_BYTES,
MAX_HARNESS_API_TRANSFER_BYTES,
MAX_REMOTE_CAPABILITY_ENTRIES,
parseRemoteWorkspaceTypes,
type EventPayload,
type HarnessRemoteFrameData,
type HarnessRemoteStreamClosedData,
type HarnessTransportDescription,
type HarnessApiTransferCommitResult,
type HarnessApiTransferReadResult,
type RemoteWorkspaceTypeDescription,
} from '@dsh-remote/protocol'
import type { RemoteClientCore, RemoteRpcOptions } from './index.js'
const DIRECT_REMOTE_CALL_BYTES = 2 * 1024 * 1024
const REMOTE_COMMAND_LIST_MIN_VERSION = [0, 3, 16] as const
const REMOTE_FILE_VIEWER_MIN_VERSION = [0, 3, 17] as const
// A cancelled call is never replayed; cleanup must not wait out the default deadline.
const TRANSFER_CLOSE_TIMEOUT_MS = 5_000
const DEFAULT_TRANSFER_TIMEOUT_MS = 60_000
const DEFAULT_TRANSFER_CHUNK_TIMEOUT_MS = 30_000
/** Gateway call options; `maxResponseBytes` caps what a transferred response may allocate locally. */
export interface RemoteGatewayOptions extends RemoteRpcOptions {
maxResponseBytes?: number
chunkTimeoutMs?: number
}
export interface RemoteHostFeatures {
commandList: boolean
fileViewer: boolean
apiProxy: boolean
apiTransfer: boolean
remoteGateway: boolean
sessionFormat?: 3
remoteTransfer: boolean
pluginRoute: boolean
capabilities: readonly string[]
workspaceTypes?: readonly RemoteWorkspaceTypeDescription[]
}
/** Optional type declarations refine negotiated capabilities; legacy Hosts omit them. */
export function remoteWorkspaceTypeAvailable(
capabilities: readonly string[],
workspaceTypes: readonly RemoteWorkspaceTypeDescription[] | undefined,
id: string,
capability: string,
): boolean {
if (!capabilities.includes(capability)) return false
if (workspaceTypes === undefined) return true
const entries = workspaceTypes.filter(item => item.id === id)
return entries.length === 1 && entries[0]?.capability === capability && entries[0].available
}
export interface RemoteGatewayFailure {
code: string
message: string
details: Record<string, unknown>
}
export type RemoteGatewayResult<T = unknown> =
| { ok: true; value?: T }
| { ok: false; error: RemoteGatewayFailure }
export interface RemoteGatewayStream extends AsyncIterable<unknown> {
close(notifyRemote?: boolean): Promise<void>
}
export interface TypertGatewayRequest {
namespace: string
method: string
args: Readonly<Record<string, unknown>>
signal?: AbortSignal
}
export class RemoteGatewayError extends Error {
constructor(
readonly code: string,
message: string,
readonly details: Record<string, unknown> = {},
options?: ErrorOptions,
) {
super(message, options)
this.name = 'RemoteGatewayError'
}
}
/** Conservative feature profile for Hosts that predate capability discovery. */
export function remoteHostFeatures(clientVersion?: string): RemoteHostFeatures {
return {
commandList: isVersionAtLeast(clientVersion, REMOTE_COMMAND_LIST_MIN_VERSION),
fileViewer: isVersionAtLeast(clientVersion, REMOTE_FILE_VIEWER_MIN_VERSION),
apiProxy: true,
apiTransfer: true,
remoteGateway: false,
remoteTransfer: false,
pluginRoute: false,
capabilities: ['harness.api.v1'],
}
}
export async function probeRemoteHostFeatures(
client: RemoteClientCore,
clientVersion?: string,
): Promise<RemoteHostFeatures> {
const fallback = remoteHostFeatures(clientVersion)
let value: unknown
try {
value = await client.rpc('harness.transport.describe', {})
} catch (error) {
if (hasErrorCode(error, 'METHOD_NOT_FOUND')) return fallback
throw error
}
if (!isRecord(value) || !Array.isArray(value.capabilities)
|| value.capabilities.length > MAX_REMOTE_CAPABILITY_ENTRIES
|| value.capabilities.some(capability => typeof capability !== 'string')) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned invalid transport capabilities.')
}
const description = value as unknown as HarnessTransportDescription
const capabilities = new Set(description.capabilities)
const apiProxy = capabilities.has('harness.api.v1')
const remoteV1 = capabilities.has('harness.remote.v1')
const remoteV3 = capabilities.has('harness.remote.v3')
if (remoteV1 && remoteV3) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host advertised conflicting Harness Session formats.')
}
const sessionFormat = remoteV3 ? 3 as const : undefined
const remoteGateway = remoteV3 || remoteV1
if (!apiProxy && !remoteGateway) {
throw new RemoteGatewayError('FEATURE_NOT_SUPPORTED', 'The remote Host exposes no supported Harness transport.')
}
const workspaceTypes = isRecord(value) && 'workspaceTypes' in value ? parseRemoteWorkspaceTypes(value.workspaceTypes) : undefined
return {
commandList: remoteGateway || (apiProxy && fallback.commandList),
fileViewer: capabilities.has('fileviewer.read.v1'),
apiProxy,
apiTransfer: capabilities.has('harness.api.transfer.v1') || apiProxy,
remoteGateway,
...(sessionFormat === undefined ? {} : { sessionFormat }),
remoteTransfer: capabilities.has('harness.remote.transfer.v1'),
pluginRoute: capabilities.has('plugin.route.v1'),
capabilities: description.capabilities,
...(workspaceTypes === undefined ? {} : { workspaceTypes }),
}
}
/** Client-side alpha Gateway carrier over the authenticated Remote channel. */
export class RemoteTypertGateway {
constructor(private readonly client: RemoteClientCore) {}
async invoke(request: TypertGatewayRequest): Promise<unknown> {
const result = await this.dispatch(
`${request.namespace}/${request.method}`,
{ args: request.args },
request.signal,
)
if (result.ok) return result.value
throw remoteFailure(result.error)
}
async call<T = unknown>(
endpoint: string,
payload: unknown,
signal?: AbortSignal,
options?: RemoteGatewayOptions,
): Promise<T> {
const result = await this.dispatch<T>(endpoint, payload, signal, options)
if (result.ok) return result.value as T
throw remoteFailure(result.error)
}
async dispatch<T = unknown>(
endpoint: string,
payload: unknown,
signal?: AbortSignal,
options?: RemoteGatewayOptions,
): Promise<RemoteGatewayResult<T>> {
const request = { endpoint, payload }
const encoded = new TextEncoder().encode(JSON.stringify(request))
let response: unknown
const activeSignal = signal ?? new AbortController().signal
if (encoded.byteLength > DIRECT_REMOTE_CALL_BYTES) {
response = await this.callTransferred(encoded, activeSignal, options)
} else {
try {
response = await this.client.rpc<unknown>('harness.remote.call', request, activeSignal, options)
} catch (error) {
if (!hasErrorCode(error, 'RESPONSE_TOO_LARGE')) throw error
response = await this.callTransferred(encoded, activeSignal, options)
}
}
const result = parseRpcResult<T>(response)
if (!result.ok) return result
return {
...result,
value: normalizeWorkspaceBinaryResult(endpoint, result.value),
}
}
async open(endpoint: string, payload: unknown, signal?: AbortSignal): Promise<RemoteGatewayStream> {
const activeSignal = signal ?? new AbortController().signal
const streamId = createRemoteId()
const queue = new AsyncValueQueue()
const remoteClose = { enabled: true }
const unsubscribe = this.client.onEvent(event => routeStreamEvent(event, streamId, queue))
const unsubscribeClose = this.client.onClose(() => {
queue.fail(new RemoteGatewayError('TRANSPORT_CLOSED', 'The remote Harness stream transport closed.'))
})
const onAbort = () => queue.close()
activeSignal.addEventListener('abort', onAbort, { once: true })
try {
await this.client.rpc('harness.remote.stream.open', { streamId, endpoint, payload }, activeSignal)
} catch (error) {
activeSignal.removeEventListener('abort', onAbort)
unsubscribe()
unsubscribeClose()
// The Host registers the stream before the open RPC settles: a failed or
// aborted open must still release the slot or it leaks until the
// connection drops (every open consumes one of the per-connection limit).
void this.client.rpc('harness.remote.stream.close', { streamId }).catch(() => undefined)
throw error
}
return new RemoteGatewayStreamController(this.iterate(
streamId,
queue,
unsubscribe,
unsubscribeClose,
activeSignal,
onAbort,
remoteClose,
), queue, remoteClose)
}
failure(error: unknown): RemoteGatewayFailure {
if (error instanceof RemoteGatewayError) {
return { code: error.code, message: error.message, details: error.details }
}
if (error instanceof Error && 'code' in error && typeof error.code === 'string') {
return {
code: error.code,
message: error.message,
details: 'details' in error && isRecord(error.details) ? error.details : {},
}
}
return {
code: 'internal',
message: error instanceof Error ? error.message : String(error),
details: {},
}
}
private async *iterate(
streamId: string,
queue: AsyncValueQueue,
unsubscribe: () => void,
unsubscribeClose: () => void,
signal: AbortSignal,
onAbort: () => void,
remoteClose: { enabled: boolean },
): AsyncGenerator<unknown> {
try {
yield* queue
} finally {
signal.removeEventListener('abort', onAbort)
unsubscribe()
unsubscribeClose()
queue.close()
if (remoteClose.enabled) await this.client.rpc('harness.remote.stream.close', { streamId }).catch(() => undefined)
}
}
private async callTransferred(
encoded: Uint8Array,
signal: AbortSignal,
options?: RemoteGatewayOptions,
): Promise<unknown> {
if (encoded.byteLength > MAX_HARNESS_API_TRANSFER_BYTES) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The Harness Remote request exceeds the transfer limit.')
}
const maxResponseBytes = transferResponseLimit(options)
const totalChunks = Math.ceil(encoded.byteLength / HARNESS_API_TRANSFER_CHUNK_BYTES)
const overallTimeoutMs = options?.timeoutMs ?? Math.max(DEFAULT_TRANSFER_TIMEOUT_MS, totalChunks * 2_000)
if (!Number.isSafeInteger(overallTimeoutMs) || overallTimeoutMs <= 0 || overallTimeoutMs > 2_147_483_647) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The requested Harness transfer timeout is invalid.')
}
const deadline = performance.now() + overallTimeoutMs
const customChunkTimeout = transferChunkTimeout(options)
const transferId = createRemoteId()
const stepTimeout = (step: string, limitMs = overallTimeoutMs, details: Record<string, unknown> = {}): number => {
const remainingMs = Math.floor(deadline - performance.now())
if (remainingMs <= 0) {
throw new RemoteGatewayError(
'RPC_TIMEOUT',
`The Harness Remote transfer timed out after ${overallTimeoutMs}ms before step: ${step}.`,
{ transferId, step, totalChunks, timeoutMs: overallTimeoutMs, ...details },
)
}
// RemoteClientCore accepts only positive integer timer durations.
return Math.min(remainingMs, limitMs)
}
let opened = false
try {
await this.client.rpc('harness.remote.transfer.open', {
transferId,
totalBytes: encoded.byteLength,
totalChunks,
}, signal, { ...options, timeoutMs: stepTimeout('open', customChunkTimeout ?? DEFAULT_TRANSFER_CHUNK_TIMEOUT_MS) })
opened = true
for (let index = 0; index < totalChunks; index += 1) {
const start = index * HARNESS_API_TRANSFER_CHUNK_BYTES
const chunk = encoded.subarray(start, Math.min(start + HARNESS_API_TRANSFER_CHUNK_BYTES, encoded.byteLength))
await this.client.rpc('harness.remote.transfer.chunk', {
transferId,
index,
data: bytesToBase64(chunk),
}, signal, { ...options, timeoutMs: stepTimeout(`chunk:${index}`, customChunkTimeout ?? DEFAULT_TRANSFER_CHUNK_TIMEOUT_MS) })
}
const committed = await this.client.rpc<HarnessApiTransferCommitResult>(
'harness.remote.transfer.commit',
{ transferId },
signal,
// Commit runs the endpoint itself, so retain long Office conversion budgets.
{ ...options, timeoutMs: stepTimeout('commit') },
)
if (committed.kind === 'inline') return committed.response
if (committed.kind !== 'chunked'
|| committed.transferId !== transferId
|| !Number.isSafeInteger(committed.totalBytes)
|| committed.totalBytes <= 0
|| committed.totalBytes > MAX_HARNESS_API_TRANSFER_BYTES
|| !Number.isSafeInteger(committed.totalChunks)
|| committed.totalChunks !== Math.ceil(committed.totalBytes / HARNESS_API_TRANSFER_CHUNK_BYTES)) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned an invalid Harness Remote transfer descriptor.')
}
// Checked before allocating: an oversized response must not reserve hundreds of megabytes.
if (maxResponseBytes !== undefined && committed.totalBytes > maxResponseBytes) {
throw new RemoteGatewayError(
'RESPONSE_TOO_LARGE',
'The remote Harness response exceeds the requested transfer limit.',
{ totalBytes: committed.totalBytes, maxResponseBytes },
)
}
const responseBytes = new Uint8Array(committed.totalBytes)
let offset = 0
for (let index = 0; index < committed.totalChunks; index += 1) {
const chunkTimeoutMs = stepTimeout(`read:${index}`, customChunkTimeout ?? DEFAULT_TRANSFER_CHUNK_TIMEOUT_MS, {
index, receivedChunks: index, totalChunks: committed.totalChunks, totalBytes: committed.totalBytes,
})
try {
const result = await this.client.rpc<HarnessApiTransferReadResult>(
'harness.remote.transfer.read',
{ transferId, index },
signal,
{ ...options, timeoutMs: chunkTimeoutMs },
)
if (result.transferId !== transferId || result.index !== index) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned an out-of-order Harness Remote transfer chunk.', {
transferId,
index,
receivedChunks: index,
totalChunks: committed.totalChunks,
})
}
const chunk = base64ToBytes(result.data)
const expectedBytes = Math.min(HARNESS_API_TRANSFER_CHUNK_BYTES, committed.totalBytes - offset)
if (chunk.byteLength !== expectedBytes) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned an invalid Harness Remote transfer chunk.', {
transferId,
index,
receivedChunks: index,
totalChunks: committed.totalChunks,
})
}
responseBytes.set(chunk, offset)
offset += chunk.byteLength
} catch (error) {
if (error instanceof RemoteGatewayError) throw error
if (signal.aborted || hasErrorCode(error, 'RPC_ABORTED')) throw error
if (hasErrorCode(error, 'RPC_TIMEOUT')) {
throw new RemoteGatewayError(
'RPC_TIMEOUT',
`The Harness Remote transfer timed out while reading chunk ${index + 1}/${committed.totalChunks} after ${chunkTimeoutMs}ms.`,
{ transferId, index, receivedChunks: index, totalChunks: committed.totalChunks, timeoutMs: chunkTimeoutMs },
{ cause: error },
)
}
throw new RemoteGatewayError(
error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : 'TRANSFER_FAILED',
`Failed reading Harness Remote transfer chunk ${index + 1}/${committed.totalChunks}: ${error instanceof Error ? error.message : String(error)}`,
{ transferId, index, receivedChunks: index, totalChunks: committed.totalChunks, offset },
{ cause: error },
)
}
}
try {
return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(responseBytes)) as unknown
} catch (error) {
throw new RemoteGatewayError(
'INVALID_MESSAGE',
`The Harness Remote transfer payload could not be decoded as JSON: ${error instanceof Error ? error.message : String(error)}`,
{ transferId, totalBytes: committed.totalBytes, totalChunks: committed.totalChunks },
{ cause: error },
)
}
} finally {
// Best-effort and bounded: the close may go out while unwinding an abort.
if (opened) {
await this.client.rpc('harness.remote.transfer.close', { transferId }, undefined, {
timeoutMs: TRANSFER_CLOSE_TIMEOUT_MS,
}).catch(() => undefined)
}
}
}
}
class RemoteGatewayStreamController implements RemoteGatewayStream {
constructor(
private readonly generator: AsyncGenerator<unknown>,
private readonly queue: AsyncValueQueue,
private readonly remoteClose: { enabled: boolean },
) {}
[Symbol.asyncIterator](): AsyncIterator<unknown> {
return this.generator
}
async close(notifyRemote = true): Promise<void> {
this.remoteClose.enabled = notifyRemote
this.queue.close()
await this.generator.return(undefined)
}
}
class AsyncValueQueue implements AsyncIterable<unknown> {
private readonly values: unknown[] = []
private readonly waiters: Array<(result: IteratorResult<unknown>) => void> = []
private closed = false
private error?: Error
push(value: unknown): void {
if (this.closed) return
const waiter = this.waiters.shift()
if (waiter === undefined) this.values.push(value)
else waiter({ done: false, value })
}
close(): void {
if (this.closed) return
this.closed = true
for (const waiter of this.waiters.splice(0)) waiter({ done: true, value: undefined })
}
fail(error: Error): void {
if (this.closed) return
this.error = error
this.close()
}
async *[Symbol.asyncIterator](): AsyncIterator<unknown> {
while (true) {
if (this.values.length > 0) {
yield this.values.shift()
continue
}
if (this.closed) {
if (this.error !== undefined) throw this.error
return
}
const next = await new Promise<IteratorResult<unknown>>(resolve => this.waiters.push(resolve))
if (next.done) {
if (this.error !== undefined) throw this.error
return
}
yield next.value
}
}
}
function routeStreamEvent(event: EventPayload, streamId: string, queue: AsyncValueQueue): void {
if (event.event === 'harness.remote.frame') {
const data = event.data as Partial<HarnessRemoteFrameData>
if (data.streamId === streamId && data.hasValue === true) queue.push(data.value)
return
}
if (event.event !== 'harness.remote.stream.closed') return
const data = event.data as Partial<HarnessRemoteStreamClosedData>
if (data.streamId !== streamId) return
if (data.reason === 'failed') {
const failure = data.failure
queue.fail(remoteFailure({
code: typeof failure?.code === 'string' ? failure.code : 'internal',
message: typeof failure?.message === 'string' ? failure.message : 'The remote Harness stream failed.',
details: isRecord(failure?.details) ? failure.details : {},
}))
} else {
queue.close()
}
}
function parseRpcResult<T>(value: unknown): RemoteGatewayResult<T> {
if (!isRecord(value)) throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned an invalid Gateway result.')
if (value.ok === true) return Object.hasOwn(value, 'value') ? { ok: true, value: value.value as T } : { ok: true }
if (value.ok !== false || !isRecord(value.error)
|| typeof value.error.code !== 'string'
|| typeof value.error.message !== 'string'
|| !isRecord(value.error.details)) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned an invalid Gateway failure.')
}
return {
ok: false,
error: { code: value.error.code, message: value.error.message, details: value.error.details },
}
}
/** Restore bounded native workspace binary fields after the JSON-only Remote carrier. */
function normalizeWorkspaceBinaryResult<T>(endpoint: string, value: T | undefined): T | undefined {
if (endpoint !== 'workspaceFiles/readBytes' && endpoint !== 'officeToPdf/render') return value
if (!isRecord(value) || typeof value.data !== 'string') return value
return { ...value, data: base64ToBytes(value.data) } as T
}
function remoteFailure(failure: RemoteGatewayFailure): RemoteGatewayError {
return new RemoteGatewayError(failure.code, failure.message, failure.details)
}
function transferResponseLimit(options: RemoteGatewayOptions | undefined): number | undefined {
const maxResponseBytes = options?.maxResponseBytes
if (maxResponseBytes === undefined) return undefined
if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes <= 0) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The requested Harness transfer response limit is invalid.')
}
return Math.min(maxResponseBytes, MAX_HARNESS_API_TRANSFER_BYTES)
}
function transferChunkTimeout(options: RemoteGatewayOptions | undefined): number | undefined {
const chunkTimeoutMs = options?.chunkTimeoutMs
if (chunkTimeoutMs === undefined) return undefined
if (!Number.isSafeInteger(chunkTimeoutMs) || chunkTimeoutMs <= 0 || chunkTimeoutMs > 2_147_483_647) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The requested Harness transfer chunk timeout is invalid.')
}
return chunkTimeoutMs
}
function bytesToBase64(bytes: Uint8Array): string {
let binary = ''
for (let offset = 0; offset < bytes.byteLength; offset += 0x8000) {
binary += String.fromCharCode(...bytes.subarray(offset, Math.min(offset + 0x8000, bytes.byteLength)))
}
return btoa(binary)
}
function base64ToBytes(value: string): Uint8Array {
let binary: string
try {
binary = atob(value)
} catch {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned malformed Harness Remote transfer data.')
}
const bytes = new Uint8Array(binary.length)
for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index)
if (bytesToBase64(bytes) !== value) {
throw new RemoteGatewayError('INVALID_MESSAGE', 'The remote Host returned non-canonical Harness Remote transfer data.')
}
return bytes
}
export function createRemoteId(): string {
const crypto = globalThis.crypto
if (crypto?.randomUUID !== undefined) return crypto.randomUUID()
return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value)
}
function hasErrorCode(error: unknown, code: string): boolean {
return error instanceof Error && 'code' in error && error.code === code
}
function isVersionAtLeast(value: string | undefined, minimum: readonly [number, number, number]): boolean {
const match = value?.match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/)
if (match === undefined || match === null) return false
const version = match.slice(1, 4).map(part => Number(part))
for (let index = 0; index < minimum.length; index += 1) {
const part = version[index] ?? 0
const expected = minimum[index] ?? 0
if (part > expected) return true
if (part < expected) return false
}
return true
}