From d26672a61042e63ac8d970b59e4e310dcd24681f Mon Sep 17 00:00:00 2001 From: QQ Date: Tue, 17 Nov 2026 08:48:53 +0800 Subject: [PATCH] Import packages/plugin/src/transport-upgrade.ts --- packages/plugin/src/transport-upgrade.ts | 293 +++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 packages/plugin/src/transport-upgrade.ts diff --git a/packages/plugin/src/transport-upgrade.ts b/packages/plugin/src/transport-upgrade.ts new file mode 100644 index 0000000..ad76441 --- /dev/null +++ b/packages/plugin/src/transport-upgrade.ts @@ -0,0 +1,293 @@ +import { + TRANSPORT_UPGRADE_CAPABILITY, + createEvent, + transportTierRank, + transportUpgradeAbortSchema, + transportUpgradeActivateSchema, + transportUpgradeDrainSchema, + transportUpgradeIceSchema, + transportUpgradeOfferSchema, + unwrapUpgradedTransportFrame, + wrapUpgradedTransportFrame, + type RemoteMessage, + type TransportTier, +} from '@dsh-remote/protocol' +import { + RtcDataChannelTransport, + type RtcIceCandidateInit, + type RtcIceServer, + type RtcPeerConnectionFactory, +} from '@dsh-remote/webrtc' +import type { SafeLogger } from './logging.js' +import { RpcError } from './safe-error.js' + +export { TRANSPORT_UPGRADE_CAPABILITY, wrapUpgradedTransportFrame, unwrapUpgradedTransportFrame, type TransportTier } + +interface UpgradeAttempt { + readonly attemptId: string + readonly rtc: RtcDataChannelTransport + readonly unsubscribeMessage: () => void + readonly unsubscribeClose: () => void + readonly expiryTimer: ReturnType + activated: boolean +} + +export interface TransportUpgradeHostOptions { + connectionId: string + peerDeviceId: string + currentMode: () => TransportTier | undefined + outboundCounter: () => number + loadRtcFactory: () => Promise + fetchIceServers: (connectionId: string) => Promise + onReceiveSequencedCiphertext: (counter: number, ciphertext: Uint8Array, source: RtcDataChannelTransport) => void + adoptRtc: ( + rtc: RtcDataChannelTransport, + mode: 'LAN' | 'P2P' | 'TURN', + attemptId: string, + ) => Promise + confirmPreviousLegDrain?: (attemptId: string, clientPreviousLegEndCounter: number) => void + publishEvent: (message: RemoteMessage) => Promise + logger?: SafeLogger + attemptTtlMs?: number +} + +/** + * Per-connection responder for in-band WebRTC transport upgrades + * (`Relay -> TURN -> P2P -> LAN`). + * + * Path tier classification strictly trusts the Host's own verified ICE + * candidate-pair stats (`rtc.connectionDetails()`); client hints can never + * elevate a lower-tier path into `LAN` or `P2P`. + */ +export class TransportUpgradeHost { + private candidate?: UpgradeAttempt + private closed = false + private offerEpoch = 0 + private activating = false + + constructor(private readonly options: TransportUpgradeHostOptions) {} + + async offer(rawParams: unknown): Promise<{ attemptId: string; sdp: string }> { + if (this.closed) throw new RpcError('INVALID_MESSAGE', 'The connection is closed.') + const { attemptId, sdp } = transportUpgradeOfferSchema.parse(rawParams) + const current = this.options.currentMode() + if (current === 'LAN') { + throw new RpcError('REQUEST_CONFLICT', 'Transport is already at LAN tier.') + } + const epoch = ++this.offerEpoch + await this.clearCandidate() + const factory = await this.options.loadRtcFactory() + if (this.closed || epoch !== this.offerEpoch) { + throw new RpcError('REQUEST_CONFLICT', 'Transport upgrade offer was superseded.') + } + if (factory === undefined) { + throw new RpcError('CAPABILITY_NOT_SUPPORTED', 'WebRTC is unavailable on this Host.') + } + let iceServers: RtcIceServer[] = [] + try { + iceServers = await this.options.fetchIceServers(this.options.connectionId) + } catch { + iceServers = [] + } + if (this.closed || epoch !== this.offerEpoch) { + throw new RpcError('REQUEST_CONFLICT', 'Transport upgrade offer was superseded.') + } + + let answerResolve: ((answerSdp: string) => void) | undefined + let answerReject: ((error: Error) => void) | undefined + const answerReady = new Promise((resolve, reject) => { + answerResolve = resolve + answerReject = reject + }) + + const rtc = new RtcDataChannelTransport({ + role: 'responder', + factory, + iceServers, + negotiateTimeoutMs: 12_000, + onSignal: signal => { + if (this.closed) return + if (signal.type === 'answer') { + answerResolve?.(signal.sdp) + return + } + if (signal.type === 'ice' && this.candidate?.attemptId === attemptId && !this.candidate.activated) { + void this.options.publishEvent(createEvent('remote.transport.upgrade.ice', { + attemptId, + candidate: signal.candidate, + })).catch(() => undefined) + } + }, + }) + + const unsubscribeMessage = rtc.onMessage(frame => { + try { + const parsed = unwrapUpgradedTransportFrame(frame) + this.options.onReceiveSequencedCiphertext(parsed.counter, parsed.ciphertext, rtc) + } catch { + void rtc.close().catch(() => undefined) + } + }) + const unsubscribeClose = rtc.onClose(() => { + if (this.candidate?.attemptId === attemptId && !this.candidate.activated) { + void this.clearCandidate() + } + }) + const expiryTimer = setTimeout(() => { + if (this.candidate?.attemptId === attemptId && !this.candidate.activated) { + void this.clearCandidate() + } + }, this.options.attemptTtlMs ?? 20_000) + expiryTimer.unref?.() + + const attempt: UpgradeAttempt = { + attemptId, + rtc, + unsubscribeMessage, + unsubscribeClose, + expiryTimer, + activated: false, + } + this.candidate = attempt + + void rtc.connect().catch(err => { + answerReject?.(err instanceof Error ? err : new Error(String(err))) + }) + rtc.handleSignal({ type: 'offer', sdp }) + + let timer: ReturnType | undefined + try { + const answerSdp = await Promise.race([ + answerReady, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('Timed out creating WebRTC upgrade answer.')), 8_000) + timer.unref?.() + }), + ]) + if (this.closed || this.candidate !== attempt) { + await this.disposeAttempt(attempt, true) + throw new RpcError('REQUEST_CONFLICT', 'Transport upgrade offer was superseded.') + } + return { attemptId, sdp: answerSdp } + } catch (error) { + if (this.candidate === attempt) await this.clearCandidate() + else await this.disposeAttempt(attempt, true) + if (error instanceof RpcError) throw error + throw new RpcError('CONNECTION_FAILED', error instanceof Error ? error.message : 'Failed to negotiate WebRTC upgrade.', true) + } finally { + if (timer !== undefined) clearTimeout(timer) + } + } + + async addIce(rawParams: unknown): Promise<{ ok: true }> { + const { attemptId, candidate } = transportUpgradeIceSchema.parse(rawParams) + if (this.closed || this.candidate?.attemptId !== attemptId) return { ok: true } + this.candidate.rtc.handleSignal({ type: 'ice', candidate: candidate as RtcIceCandidateInit }) + return { ok: true } + } + + async activate(rawParams: unknown): Promise<{ activated: boolean; mode: TransportTier; previousLegEndCounter?: number }> { + if (this.closed) throw new RpcError('INVALID_MESSAGE', 'The connection is closed.') + if (this.activating) throw new RpcError('REQUEST_CONFLICT', 'Another transport activation is already in progress.') + const { attemptId } = transportUpgradeActivateSchema.parse(rawParams) + const attempt = this.candidate + if (attempt === undefined || attempt.attemptId !== attemptId) { + throw new RpcError('REQUEST_CONFLICT', 'Transport upgrade attempt is no longer active.') + } + this.activating = true + try { + let timer: ReturnType | undefined + try { + await Promise.race([ + attempt.rtc.connect(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('Timed out waiting for upgraded DataChannel to open.')), 6_000) + timer.unref?.() + }), + ]) + } finally { + if (timer !== undefined) clearTimeout(timer) + } + + if (this.closed || this.candidate !== attempt) { + await this.disposeAttempt(attempt, true) + return { activated: false, mode: this.options.currentMode() ?? 'Relay' } + } + + // Authoritative path verification: only Host-observed ICE stats determine tier. + // Poll briefly (up to 200ms) if native stats have not populated the nominated pair yet. + let verifiedMode: 'LAN' | 'P2P' | 'TURN' | undefined + for (let i = 0; i < 5; i += 1) { + const details = await attempt.rtc.connectionDetails().catch(() => undefined) + verifiedMode = details?.mode + if (verifiedMode !== undefined) break + if (i < 4) await new Promise(resolve => setTimeout(resolve, 40)) + } + if (this.closed || this.candidate !== attempt) { + await this.disposeAttempt(attempt, true) + return { activated: false, mode: this.options.currentMode() ?? 'Relay' } + } + const beforeMode = this.options.currentMode() ?? 'Relay' + if (verifiedMode === undefined || transportTierRank(verifiedMode) <= transportTierRank(beforeMode)) { + await this.clearCandidate() + return { activated: false, mode: beforeMode } + } + + clearTimeout(attempt.expiryTimer) + attempt.unsubscribeClose() + attempt.activated = true + this.candidate = undefined + const hostPreviousLegEndCounter = await this.options.adoptRtc(attempt.rtc, verifiedMode, attemptId) + this.options.logger?.info('in-band transport upgraded', { + connectionId: this.options.connectionId.slice(0, 8), + from: beforeMode, + to: verifiedMode, + }) + return { + activated: true, + mode: verifiedMode, + previousLegEndCounter: hostPreviousLegEndCounter, + } + } finally { + this.activating = false + } + } + + async drain(rawParams: unknown): Promise<{ ok: true }> { + const { attemptId, previousLegEndCounter } = transportUpgradeDrainSchema.parse(rawParams) + if (!this.closed) { + this.options.confirmPreviousLegDrain?.(attemptId, previousLegEndCounter) + } + return { ok: true } + } + + async abort(rawParams: unknown): Promise<{ ok: true }> { + const { attemptId } = transportUpgradeAbortSchema.parse(rawParams ?? {}) + if (attemptId === undefined || this.candidate?.attemptId === attemptId) { + await this.clearCandidate() + } + return { ok: true } + } + + async closeAll(): Promise { + this.closed = true + this.offerEpoch += 1 + await this.clearCandidate() + } + + private async clearCandidate(): Promise { + const current = this.candidate + if (current === undefined) return + this.candidate = undefined + await this.disposeAttempt(current, !current.activated) + } + + private async disposeAttempt(attempt: UpgradeAttempt, closeRtc: boolean): Promise { + clearTimeout(attempt.expiryTimer) + attempt.unsubscribeClose() + if (closeRtc) { + attempt.unsubscribeMessage() + await attempt.rtc.close().catch(() => undefined) + } + } +}