Import packages/plugin/src/typert-gateway-switch.ts

This commit is contained in:
QQ 2026-11-14 14:58:10 +08:00
parent 6708a899b4
commit 26b4ba7807
1 changed files with 349 additions and 0 deletions

View File

@ -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<unknown>
type CarrierDispatch = (endpoint: string, payload: unknown, signal: AbortSignal, peer?: unknown) => Promise<TypertRpcResult>
type CarrierOpen = (endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>, peer?: unknown) => Promise<AsyncIterable<unknown>>
/**
* 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<unknown>,
peer: unknown,
signal: AbortSignal,
control: AbortController,
) => Promise<AsyncIterable<unknown>>
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<TypertGatewayLike['stream']>
private readonly localStream?: NonNullable<TypertGatewayLike['stream']>
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<AsyncIterable<unknown>>
: (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<unknown> : 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<unknown>): Promise<AsyncIterable<unknown>> {
return endpoint === 'terminal/attach'
? openRemoteTerminal(this.remoteTarget!, payload, signal, uplink ?? endedUplink())
: this.remoteTarget!.open(endpoint, payload, signal)
}
private selectInvoke(request: TypertGatewayRequest): Promise<unknown> {
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<string, unknown> } {
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<unknown> {
return {
[Symbol.asyncIterator](): AsyncIterator<unknown> {
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<string, unknown> {
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 }
}