From c620cf8d24eaab56c3aa4bc839f0075fe166c9ef Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:44:28 +0800 Subject: [PATCH] Import packages/client-core/src/remote-gateway.ts --- packages/client-core/src/remote-gateway.ts | 595 +++++++++++++++++++++ 1 file changed, 595 insertions(+) create mode 100644 packages/client-core/src/remote-gateway.ts diff --git a/packages/client-core/src/remote-gateway.ts b/packages/client-core/src/remote-gateway.ts new file mode 100644 index 0000000..3c397ad --- /dev/null +++ b/packages/client-core/src/remote-gateway.ts @@ -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 +} + +export type RemoteGatewayResult = + | { ok: true; value?: T } + | { ok: false; error: RemoteGatewayFailure } + +export interface RemoteGatewayStream extends AsyncIterable { + close(notifyRemote?: boolean): Promise +} + +export interface TypertGatewayRequest { + namespace: string + method: string + args: Readonly> + signal?: AbortSignal +} + +export class RemoteGatewayError extends Error { + constructor( + readonly code: string, + message: string, + readonly details: Record = {}, + 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 { + 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 { + 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( + endpoint: string, + payload: unknown, + signal?: AbortSignal, + options?: RemoteGatewayOptions, + ): Promise { + const result = await this.dispatch(endpoint, payload, signal, options) + if (result.ok) return result.value as T + throw remoteFailure(result.error) + } + + async dispatch( + endpoint: string, + payload: unknown, + signal?: AbortSignal, + options?: RemoteGatewayOptions, + ): Promise> { + 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('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(response) + if (!result.ok) return result + return { + ...result, + value: normalizeWorkspaceBinaryResult(endpoint, result.value), + } + } + + async open(endpoint: string, payload: unknown, signal?: AbortSignal): Promise { + 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 { + 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 { + 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 = {}): 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( + '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( + '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, + private readonly queue: AsyncValueQueue, + private readonly remoteClose: { enabled: boolean }, + ) {} + + [Symbol.asyncIterator](): AsyncIterator { + return this.generator + } + + async close(notifyRemote = true): Promise { + this.remoteClose.enabled = notifyRemote + this.queue.close() + await this.generator.return(undefined) + } +} + +class AsyncValueQueue implements AsyncIterable { + private readonly values: unknown[] = [] + private readonly waiters: Array<(result: IteratorResult) => 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 { + 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>(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 + 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 + 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(value: unknown): RemoteGatewayResult { + 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(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 { + 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 +}