Import packages/plugin/src/transport-upgrade.ts

This commit is contained in:
QQ 2026-11-17 08:48:53 +08:00
parent 60927632df
commit d26672a610
1 changed files with 293 additions and 0 deletions

View File

@ -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<typeof setTimeout>
activated: boolean
}
export interface TransportUpgradeHostOptions {
connectionId: string
peerDeviceId: string
currentMode: () => TransportTier | undefined
outboundCounter: () => number
loadRtcFactory: () => Promise<RtcPeerConnectionFactory | undefined>
fetchIceServers: (connectionId: string) => Promise<RtcIceServer[]>
onReceiveSequencedCiphertext: (counter: number, ciphertext: Uint8Array, source: RtcDataChannelTransport) => void
adoptRtc: (
rtc: RtcDataChannelTransport,
mode: 'LAN' | 'P2P' | 'TURN',
attemptId: string,
) => Promise<number>
confirmPreviousLegDrain?: (attemptId: string, clientPreviousLegEndCounter: number) => void
publishEvent: (message: RemoteMessage) => Promise<void>
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<string>((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<typeof setTimeout> | undefined
try {
const answerSdp = await Promise.race([
answerReady,
new Promise<string>((_, 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<typeof setTimeout> | undefined
try {
await Promise.race([
attempt.rtc.connect(),
new Promise<void>((_, 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<void> {
this.closed = true
this.offerEpoch += 1
await this.clearCandidate()
}
private async clearCandidate(): Promise<void> {
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<void> {
clearTimeout(attempt.expiryTimer)
attempt.unsubscribeClose()
if (closeRtc) {
attempt.unsubscribeMessage()
await attempt.rtc.close().catch(() => undefined)
}
}
}