diff --git a/packages/plugin/src/typert-gateway-switch.ts b/packages/plugin/src/typert-gateway-switch.ts new file mode 100644 index 0000000..e7916f9 --- /dev/null +++ b/packages/plugin/src/typert-gateway-switch.ts @@ -0,0 +1,349 @@ +import { openRemoteTerminal } from './terminal-carrier-compat.js' +import type { + LegacyWireStreamOpen, + LocalTypertGateway, + Rc1WireStreamOpen, + RemoteTypertGatewayTarget, + TypertGatewayLike, + TypertGatewayRequest, + TypertRpcResult, +} from './typert-gateway-contract.js' + +type RemoteInvoke = (request: TypertGatewayRequest) => Promise +type CarrierDispatch = (endpoint: string, payload: unknown, signal: AbortSignal, peer?: unknown) => Promise +type CarrierOpen = (endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable, peer?: unknown) => Promise> + +/** + * dsh 0.1.7-rc.1 private carrier dispatcher: + * `openWireStream(endpoint, payload, uplink, peer, signal, control)`. The public + * `wireStream.open` omits `control`; both move the signal out of the third slot. + */ +type Rc1OpenWireStream = ( + endpoint: string, + payload: unknown, + uplink: AsyncIterable, + peer: unknown, + signal: AbortSignal, + control: AbortController, +) => Promise> + +interface RuntimeGateway extends TypertGatewayLike { + // Alpha Connection adapters call these prototype methods dynamically. + dispatchRpc?: CarrierDispatch + openWireStream?: CarrierOpen | Rc1OpenWireStream +} + +const REMOTE_COMMAND_METHODS = ['execute', 'list'] as const +const LOCAL_ONLY_NAMESPACES = new Set(['dynamicCordisRunner']) + +export interface RemoteCommandSupport { + execute: boolean + list: boolean +} + +const ALL_REMOTE_COMMANDS: RemoteCommandSupport = { execute: true, list: true } + +/** Keeps the official Gateway object stable while its selected Host changes. */ +export class TypertGatewaySwitch { + private readonly runtime: RuntimeGateway + private readonly originalInvoke: TypertGatewayLike['invoke'] + private readonly localInvoke: TypertGatewayLike['invoke'] + private readonly originalStream?: NonNullable + private readonly localStream?: NonNullable + private readonly originalDispatch?: CarrierDispatch + private readonly localDispatch?: CarrierDispatch + private readonly originalOpen?: CarrierOpen | Rc1OpenWireStream + private readonly localOpen?: CarrierOpen + private remoteInvoke?: RemoteInvoke + private remoteTarget?: RemoteTypertGatewayTarget + private remoteSupport: RemoteCommandSupport = { execute: false, list: false } + private target?: { deviceId: string; name: string } + private installed = false + /** Lazily-created owner Peer supplied when a local open carries none. */ + private readonly fallbackPeer?: () => unknown + + /** + * @param gateway - official Typert Gateway service. + * @param fallbackPeer - owner Peer factory for local opens whose caller has no + * per-connection Peer. Harness 0.2.2 rejects a forwarded-event open without a + * live Peer (`peer.signal`), so a peerless local carrier must still carry one. + */ + constructor(gateway: TypertGatewayLike, fallbackPeer?: () => unknown) { + this.fallbackPeer = fallbackPeer + this.runtime = gateway as RuntimeGateway + this.originalInvoke = gateway.invoke + this.localInvoke = this.originalInvoke.bind(gateway) + this.originalStream = gateway.stream + this.localStream = gateway.stream?.bind(gateway) + this.originalDispatch = this.runtime.dispatchRpc + this.localDispatch = this.runtime.dispatchRpc?.bind(gateway) + this.originalOpen = this.runtime.openWireStream + this.localOpen = createLocalOpen(gateway, this.runtime) + } + + /** Original local dispatcher, used by the Host bridge without switch recursion. */ + local(callingPeer?: unknown): LocalTypertGateway { + // A local carrier always needs an owner Peer: the official Gateway reads + // `peer.signal`, `peer.principal` and `peer.interactions` for streams and + // access decisions. Resolve the fallback once so every call through this + // gateway shares the same peer lifetime. + const peer = callingPeer ?? this.fallbackPeer?.() + const invoke: RemoteInvoke = request => this.localInvoke({ ...request, ...(peer === undefined ? {} : { peer }) }) + const dispatch: CarrierDispatch = this.localDispatch === undefined ? (async (endpoint, payload, signal) => { + try { + const request = requestFromCarrier(endpoint, payload, signal) + return { ok: true, value: await invoke(request) } + } catch (error) { + return { ok: false, error: this.failure(error) } + } + }) : (endpoint, payload, signal) => this.localDispatch!(endpoint, payload, signal, peer) + const open: CarrierOpen = this.localOpen === undefined ? (async (endpoint, payload, signal) => { + if (this.localStream === undefined) throw new Error('The local Harness Gateway does not support Remote streams.') + return this.localStream({ ...requestFromCarrier(endpoint, payload, signal), ...(peer === undefined ? {} : { peer }) }) + }) : (endpoint, payload, signal, uplink) => this.localOpen!(endpoint, payload, signal, uplink, peer) + return { + invoke, + peer, + ...(this.localStream === undefined ? {} : { stream: (request: TypertGatewayRequest) => this.localStream!({ ...request, ...(peer === undefined ? {} : { peer }) }) }), + dispatch, + open, + failure: error => this.failure(error), + supportsCarrier: this.localDispatch !== undefined && this.localOpen !== undefined, + } + } + + supportsCarrier(): boolean { + return this.localDispatch !== undefined && this.localOpen !== undefined + } + + status(): { mode: 'local' | 'remote'; target?: { deviceId: string; name: string } } { + return this.remoteInvoke === undefined + ? { mode: 'local' } + : { mode: 'remote', ...(this.target === undefined ? {} : { target: { ...this.target } }) } + } + + install(): void { + if (this.installed) return + this.runtime.invoke = request => this.selectInvoke(request) + if (this.originalStream !== undefined) { + this.runtime.stream = request => this.remoteTarget === undefined || isLocalOnlyEndpoint(endpointOf(request)) + ? this.localStream!(request) + : this.openRemote(endpointOf(request), { args: request.args }, request.signal ?? new AbortController().signal, request.uplink) + } + if (this.originalDispatch !== undefined) { + this.runtime.dispatchRpc = (...args) => { + const [endpoint, payload, signal] = args + // The local Gateway owns the caller's Peer and its lifetime. Preserve + // every carrier argument; Peer objects never cross the Remote tunnel. + return this.remoteTarget === undefined || isLocalOnlyEndpoint(endpoint) + ? this.localDispatch!(...args) + : this.remoteTarget.dispatch(endpoint, payload, signal).then( + result => workspaceConnectionResult(endpoint, result), + error => ({ ok: false, error: this.failure(error) }), + ) + } + } + if (this.originalOpen !== undefined) { + const open = this.originalOpen + const rc1 = usesRc1Arity(open) + this.runtime.openWireStream = (...callArgs: unknown[]) => { + const endpoint = callArgs[0] as string + if (this.remoteTarget === undefined || isLocalOnlyEndpoint(endpoint)) { + return rc1 + ? Reflect.apply(open, this.runtime, callArgs) as Promise> + : (open as CarrierOpen).call(this.runtime, endpoint, callArgs[1], callArgs[2] as AbortSignal) + } + const signal = (rc1 ? callArgs[4] : callArgs[2]) as AbortSignal | undefined + return this.openRemote(endpoint, callArgs[1], signal ?? new AbortController().signal, rc1 ? callArgs[2] as AsyncIterable : undefined) + } + } + this.installed = true + } + + selectRemote( + remote: RemoteInvoke | RemoteTypertGatewayTarget, + support: RemoteCommandSupport = ALL_REMOTE_COMMANDS, + target?: { deviceId: string; name: string }, + ): void { + if (!this.installed) throw new Error('The Typert gateway switch is not installed.') + this.remoteInvoke = typeof remote === 'function' ? remote : request => remote.invoke(request) + this.remoteTarget = typeof remote === 'function' ? undefined : remote + this.remoteSupport = { ...support } + this.target = target === undefined ? undefined : { ...target } + } + + selectLocal(): void { + this.remoteInvoke = undefined + this.remoteTarget = undefined + this.remoteSupport = { execute: false, list: false } + this.target = undefined + } + + /** Keep the selected authority after transport loss; only explicit exit returns local. */ + disconnectRemote(): void { + if (this.remoteInvoke === undefined) return + const error = () => Object.assign(new Error('The Remote connection was lost. Reconnect to continue.'), { + isDSHRemoteError: true as const, + code: 'remote/disconnected', + details: {}, + }) + this.remoteTarget = { + invoke: async () => { throw error() }, + dispatch: async () => ({ ok: false, error: { code: 'remote/disconnected', message: error().message, details: {} } }), + open: async () => { throw error() }, + } + this.remoteInvoke = this.remoteTarget.invoke + } + + restore(): void { + if (!this.installed) return + this.selectLocal() + this.runtime.invoke = this.originalInvoke + if (this.originalStream !== undefined) this.runtime.stream = this.originalStream + if (this.originalDispatch !== undefined) this.runtime.dispatchRpc = this.originalDispatch + if (this.originalOpen !== undefined) this.runtime.openWireStream = this.originalOpen + this.installed = false + } + + private openRemote(endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable): Promise> { + return endpoint === 'terminal/attach' + ? openRemoteTerminal(this.remoteTarget!, payload, signal, uplink ?? endedUplink()) + : this.remoteTarget!.open(endpoint, payload, signal) + } + + private selectInvoke(request: TypertGatewayRequest): Promise { + if (isLocalOnlyEndpoint(endpointOf(request))) return this.localInvoke(request) + if (this.remoteTarget !== undefined) return this.remoteTarget.invoke(request).then(value => normalizeTerminalEnvironment(endpointOf(request), value)) + if (request.namespace !== 'commands' || !isRemoteCommandMethod(request.method) || this.remoteInvoke === undefined) { + return this.localInvoke(request) + } + if (this.remoteSupport[request.method]) return this.remoteInvoke(request) + if (request.method === 'list') return Promise.resolve([]) + return this.localInvoke(request) + } + + private failure(error: unknown): { code: string; message: string; details: Record } { + const normalized = this.runtime.wireStream?.failure(error) + if (normalized !== undefined) return normalized + const source = error instanceof Error ? error : new Error('The Harness Gateway rejected the request.') + const code = 'code' in source && typeof source.code === 'string' ? source.code : 'internal' + const details = 'details' in source && isRecord(source.details) ? source.details : {} + return { code, message: source.message, details } + } +} + +/** The local Connection HTTP hop needs the same binary envelope as the native Gateway. */ +function workspaceConnectionResult(endpoint: string, result: TypertRpcResult): TypertRpcResult { + if (endpoint === 'terminal/environment' && result.ok) return { ...result, value: normalizeTerminalEnvironment(endpoint, result.value) } + if (endpoint !== 'workspaceFiles/readBytes' && endpoint !== 'officeToPdf/render') return result + if (!result.ok || !isRecord(result.value) || !(result.value.data instanceof Uint8Array)) return result + return { + ...result, + value: { ...result.value, data: null }, + attachments: [ + ...(result.attachments ?? []).filter(attachment => attachment.path.length !== 1 || attachment.path[0] !== 'data'), + { path: ['data'], bytes: result.value.data }, + ], + } +} + +/** + * dsh 0.1.7-rc.1 moved the cancellation signal from the third parameter to the + * fifth; legacy releases keep `(endpoint, payload, signal)`. + * @param open - carrier opener captured from the running release. + * @returns whether the opener follows the rc.1 argument order. + */ +function usesRc1Arity(open: { readonly length: number }): boolean { + return open.length >= 5 +} + +/** An uplink nobody sends on, so a read-only stream opens without buffering. */ +function endedUplink(): AsyncIterable { + return { + [Symbol.asyncIterator](): AsyncIterator { + return { next: () => Promise.resolve({ done: true, value: undefined }) } + }, + } +} + +/** + * The rc.1 carrier dereferences the calling Peer for every stream (and always + * for forwarded events). Produce an actionable failure instead of a TypeError + * when no owner Peer could be created for this Host composition. + * @param endpoint - stream endpoint being opened. + * @returns the error to reject the open with. + */ +function missingPeerError(endpoint: string): Error { + return new Error(`The Harness Gateway stream ${endpoint} requires an owner Peer, but none is available in this Host composition.`) +} + +/** Controller aborted with the logical stream so the rc.1 carrier owns one lifetime. */ +function linkControl(signal: AbortSignal): AbortController { + const control = new AbortController() + if (signal.aborted) control.abort(signal.reason) + else signal.addEventListener('abort', () => control.abort(signal.reason), { once: true }) + return control +} + +/** + * Adapt the running release's carrier opener to the plugin's 3-argument + * `(endpoint, payload, signal)` seam without leaking the argument displacement. + * @param gateway - official Gateway whose public `wireStream` is the fallback. + * @param runtime - Gateway object owning the private `openWireStream` dispatcher. + * @returns a local opener that carries the signal to the release's signal slot. + */ +function createLocalOpen(gateway: TypertGatewayLike, runtime: RuntimeGateway): CarrierOpen | undefined { + const open = runtime.openWireStream + if (open !== undefined) { + return usesRc1Arity(open) + ? (endpoint, payload, signal, uplink, peer) => peer === undefined + ? Promise.reject(missingPeerError(endpoint)) + : (open as Rc1OpenWireStream).call(runtime, endpoint, payload, uplink ?? endedUplink(), peer, signal, linkControl(signal)) + : (endpoint, payload, signal) => (open as CarrierOpen).call(runtime, endpoint, payload, signal) + } + const wire = gateway.wireStream + if (wire === undefined) return undefined + const wireOpen = wire.open + if (usesRc1Arity(wireOpen)) { + const rc1 = wireOpen as Rc1WireStreamOpen + return (endpoint, payload, signal, uplink, peer) => peer === undefined + ? Promise.reject(missingPeerError(endpoint)) + : rc1.call(wire, endpoint, payload, uplink ?? endedUplink(), peer, signal) + } + const legacy = wireOpen as LegacyWireStreamOpen + return (endpoint, payload, signal) => legacy.call(wire, endpoint, payload, signal) +} + +function requestFromCarrier(endpoint: string, payload: unknown, signal: AbortSignal): TypertGatewayRequest { + const segments = endpoint.split('/') + if (segments.length !== 2 || segments.some(segment => segment.length === 0)) { + throw new Error('The Harness Gateway endpoint is invalid.') + } + if (!isRecord(payload) || !isRecord(payload.args)) { + throw new Error('The Harness Gateway payload is invalid.') + } + return { namespace: segments[0]!, method: segments[1]!, args: payload.args, signal } +} + +function endpointOf(request: TypertGatewayRequest): string { + return `${request.namespace}/${request.method}` +} + +function isLocalOnlyEndpoint(endpoint: string): boolean { + const separator = endpoint.indexOf('/') + return separator > 0 && LOCAL_ONLY_NAMESPACES.has(endpoint.slice(0, separator)) +} + +function isRemoteCommandMethod(method: string): method is typeof REMOTE_COMMAND_METHODS[number] { + return (REMOTE_COMMAND_METHODS as readonly string[]).includes(method) +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** RC.1 input flow control also applies to older Hosts and CodeX/ACP projections. */ +function normalizeTerminalEnvironment(endpoint: string, value: unknown): unknown { + if (endpoint !== 'terminal/environment' || !isRecord(value) || value.maxBufferedBytes !== undefined) return value + return { ...value, maxBufferedBytes: 256 * 1024 } +}