Import packages/client-core/src/transport-upgrader.ts

This commit is contained in:
QQ 2026-11-17 08:42:35 +08:00
parent f337b2bc53
commit 46c0049787
1 changed files with 341 additions and 0 deletions

View File

@ -0,0 +1,341 @@
import {
transportTierRank,
transportUpgradeIceSchema,
wireFromTransportTier,
type TransportStats,
type TransportTier,
} from '@dsh-remote/protocol'
import {
RtcDataChannelTransport,
UpgradedRtcDataChannelTransport,
type RtcConnectionDetails,
type RtcIceCandidateInit,
type RtcIceServer,
type RtcPathMode,
type RtcDiagnosticEvent,
type RtcPeerConnectionFactory,
type SequencedOutboundTransport,
} from '@dsh-remote/webrtc'
import type { RemoteClientCore } from './index.js'
export interface UpgradeableSecureChannel {
readonly outboundCounter: number
attachIncomingLeg(leg: SequencedOutboundTransport): void
markPreviousLegEndCounter?(previousLegEndCounter: number): void
switchOutboundLeg(leg: SequencedOutboundTransport, options?: { closePrevious?: boolean; drainMs?: number }): Promise<number>
detachLeg(leg: SequencedOutboundTransport): Promise<void>
relayTrafficBytes?(): { sent: number; received: number }
}
export interface LiveTransportUpgradeTelemetry {
attemptId: string
from: TransportTier
to?: RtcPathMode
outcome: 'activated' | 'skipped-not-higher' | 'rejected' | 'failed' | 'aborted'
durationMs: number
relayBytesAtOutcome?: { sent: number; received: number }
reason?: string
}
export interface ClientLiveTransportUpgraderOptions {
connectionId: string
rpc: RemoteClientCore
channel: UpgradeableSecureChannel
rtcFactory: RtcPeerConnectionFactory
fetchIceServers?: (connectionId: string) => Promise<RtcIceServer[]>
iceServersTimeoutMs?: number
negotiateTimeoutMs?: number
onUpgraded?: (mode: RtcPathMode, transport: UpgradedRtcDataChannelTransport) => void
onDiagnostic?: (event: RtcDiagnosticEvent) => void
onTelemetry?: (telemetry: LiveTransportUpgradeTelemetry) => void
}
interface UpgradeOfferResponse {
attemptId?: unknown
sdp?: unknown
}
interface UpgradeActivateResponse {
activated?: unknown
mode?: unknown
previousLegEndCounter?: unknown
}
let nextUpgradeSeq = 1
function createAttemptId(): string {
return `upg_${Date.now().toString(36)}_${(nextUpgradeSeq++).toString(36)}`
}
/**
* Client-side live WebRTC transport upgrader (`remote.transport.upgrade.v1`).
*
* Negotiates WebRTC DataChannels over an already-authenticated Noise RPC session
* and climbs monotonically `Relay -> TURN -> P2P -> LAN` without rotating Noise
* keys or interrupting open streams.
*/
export class ClientLiveTransportUpgrader {
private currentLeg?: UpgradedRtcDataChannelTransport
private activeAttemptId?: string
private activeRtc?: RtcDataChannelTransport
private readonly pendingRemoteIce: RtcIceCandidateInit[] = []
private remoteDescReady = false
private promoting?: Promise<boolean>
private closed = false
private unsubscribeEvents?: () => void
constructor(private readonly options: ClientLiveTransportUpgraderOptions) {
this.unsubscribeEvents = options.rpc.onEvent(event => {
if (this.closed || event.event !== 'remote.transport.upgrade.ice') return
const parsed = transportUpgradeIceSchema.safeParse(event.data)
if (!parsed.success || parsed.data.attemptId !== this.activeAttemptId) return
if (!this.remoteDescReady || this.activeRtc === undefined) {
if (this.pendingRemoteIce.length < 64) this.pendingRemoteIce.push(parsed.data.candidate)
return
}
this.activeRtc.handleSignal({ type: 'ice', candidate: parsed.data.candidate })
})
}
get currentMode(): TransportTier {
return this.currentLeg?.mode ?? 'Relay'
}
get activeTransport(): UpgradedRtcDataChannelTransport | undefined {
return this.currentLeg
}
getStats(): TransportStats | undefined {
return this.currentLeg?.getStats()
}
connectionDetails(): Promise<RtcConnectionDetails> | undefined {
return this.currentLeg?.connectionDetails()
}
promote(options: { preferLan?: boolean } = {}): Promise<boolean> {
if (this.closed) return Promise.resolve(false)
if (this.currentMode === 'LAN') return Promise.resolve(false)
if (this.promoting !== undefined) return this.promoting
const run = this.runAttempt(options.preferLan === true).finally(() => {
if (this.promoting === run) this.promoting = undefined
})
this.promoting = run
return run
}
/** Wait up to `windowMs` for an in-flight upgrade so initial reads prefer direct when fast. */
async waitForInitialWindow(windowMs: number): Promise<boolean> {
if (this.currentMode !== 'Relay') return true
const inFlight = this.promoting ?? this.promote()
if (windowMs <= 0) return false
let timer: ReturnType<typeof setTimeout> | undefined
try {
return await Promise.race([
inFlight,
new Promise<boolean>(resolve => {
timer = setTimeout(() => resolve(false), windowMs)
;(timer as { unref?: () => void }).unref?.()
}),
])
} finally {
if (timer !== undefined) clearTimeout(timer)
}
}
private async runAttempt(preferLan: boolean): Promise<boolean> {
const startedAt = Date.now()
const fromMode = this.currentMode
const attemptId = createAttemptId()
this.activeAttemptId = attemptId
this.pendingRemoteIce.length = 0
this.remoteDescReady = false
const emitTelemetry = (outcome: LiveTransportUpgradeTelemetry['outcome'], extra: Partial<LiveTransportUpgradeTelemetry> = {}) => {
this.options.onTelemetry?.({
attemptId,
from: fromMode,
outcome,
durationMs: Math.max(0, Date.now() - startedAt),
relayBytesAtOutcome: this.options.channel.relayTrafficBytes?.(),
...extra,
})
}
let iceServers: RtcIceServer[] = []
if (!preferLan && this.options.fetchIceServers !== undefined) {
try {
iceServers = await withTimeout(
this.options.fetchIceServers(this.options.connectionId),
this.options.iceServersTimeoutMs ?? 4_000,
)
} catch {
iceServers = []
}
}
if (this.closed) {
emitTelemetry('aborted')
return false
}
const localIceQueue: RtcIceCandidateInit[] = []
let offerSent = false
let offerResolve: ((sdp: string) => void) | undefined
const offerCreated = new Promise<string>(resolve => { offerResolve = resolve })
const rtc = new RtcDataChannelTransport({
role: 'initiator',
factory: this.options.rtcFactory,
iceServers,
negotiateTimeoutMs: this.options.negotiateTimeoutMs ?? 6_000,
onDiagnostic: this.options.onDiagnostic,
onSignal: signal => {
if (this.closed || this.activeAttemptId !== attemptId) return
if (signal.type === 'offer') {
offerResolve?.(signal.sdp)
return
}
if (signal.type === 'ice') {
if (!offerSent) {
if (localIceQueue.length < 64) localIceQueue.push(signal.candidate)
} else {
void this.options.rpc.rpc('remote.transport.upgrade.ice', { attemptId, candidate: signal.candidate }, undefined, 5_000).catch(() => undefined)
}
}
},
})
this.activeRtc = rtc
try {
const openPromise = rtc.connect()
// Prevent unhandled rejection if offer RPC fails before awaiting openPromise.
openPromise.catch(() => undefined)
const offerSdp = await withTimeout(offerCreated, 5_000)
if (this.closed) throw new Error('Upgrader closed.')
const answer = await this.options.rpc.rpc<UpgradeOfferResponse>(
'remote.transport.upgrade.offer',
{ attemptId, sdp: offerSdp },
undefined,
8_000,
)
offerSent = true
for (const candidate of localIceQueue.splice(0)) {
void this.options.rpc.rpc('remote.transport.upgrade.ice', { attemptId, candidate }, undefined, 5_000).catch(() => undefined)
}
if (typeof answer?.sdp !== 'string' || answer.sdp.length === 0) {
throw new Error('Invalid upgrade answer.')
}
rtc.handleSignal({ type: 'answer', sdp: answer.sdp })
this.remoteDescReady = true
for (const candidate of this.pendingRemoteIce.splice(0)) {
rtc.handleSignal({ type: 'ice', candidate })
}
await openPromise
if (this.closed) throw new Error('Upgrader closed.')
let detectedMode: RtcPathMode | undefined
for (let i = 0; i < 6; i += 1) {
const details = await rtc.connectionDetails().catch(() => undefined)
detectedMode = details?.mode
if (detectedMode === 'LAN') break
if (!preferLan && detectedMode !== undefined) break
if (i < 5) await new Promise(resolve => setTimeout(resolve, 40))
}
if (detectedMode !== undefined && transportTierRank(detectedMode) <= transportTierRank(this.currentMode)) {
void this.options.rpc.rpc('remote.transport.upgrade.abort', { attemptId }, undefined, 3_000).catch(() => undefined)
await rtc.close().catch(() => undefined)
emitTelemetry('skipped-not-higher', { to: detectedMode })
return false
}
const candidateWire = detectedMode !== undefined ? wireFromTransportTier(detectedMode) : undefined
const provisionalMode: RtcPathMode = detectedMode ?? 'P2P'
const upgraded = new UpgradedRtcDataChannelTransport(rtc, provisionalMode, wireFromTransportTier(provisionalMode))
// Attach inbound leg BEFORE telling the Host to switch its outbound leg.
this.options.channel.attachIncomingLeg(upgraded)
const activation = await this.options.rpc.rpc<UpgradeActivateResponse>(
'remote.transport.upgrade.activate',
{
attemptId,
...(candidateWire !== undefined ? { transport: candidateWire } : {}),
},
undefined,
6_000,
)
if (activation?.activated !== true) {
await this.options.channel.detachLeg(upgraded)
emitTelemetry('rejected')
return false
}
const authoritativeMode: RtcPathMode = activation.mode === 'LAN' || activation.mode === 'P2P' || activation.mode === 'TURN'
? activation.mode
: provisionalMode
if (authoritativeMode !== upgraded.mode) {
upgraded.updateMode(authoritativeMode, wireFromTransportTier(authoritativeMode))
}
// Atomically retire the previous outbound leg FIRST so no further frames
// can be written to it and its close callback cannot fail the channel.
const finalOldLegCounter = await this.options.channel.switchOutboundLeg(upgraded, { closePrevious: true })
if (typeof activation.previousLegEndCounter === 'number') {
this.options.channel.markPreviousLegEndCounter?.(activation.previousLegEndCounter)
}
this.currentLeg = upgraded
// Now notify the Host of the true final frame count sent on the retired leg
// over the newly active DataChannel so the Host can drain and close it safely.
void this.options.rpc.rpc(
'remote.transport.upgrade.drain',
{ attemptId, previousLegEndCounter: finalOldLegCounter },
undefined,
5_000,
).catch(() => undefined)
this.options.onUpgraded?.(authoritativeMode, upgraded)
emitTelemetry('activated', { to: authoritativeMode })
return true
} catch (error) {
void this.options.rpc.rpc('remote.transport.upgrade.abort', { attemptId }, undefined, 3_000).catch(() => undefined)
await rtc.close().catch(() => undefined)
emitTelemetry(this.closed ? 'aborted' : 'failed', { reason: error instanceof Error ? error.name : 'Error' })
return false
} finally {
if (this.activeAttemptId === attemptId) {
this.activeAttemptId = undefined
this.activeRtc = undefined
this.pendingRemoteIce.length = 0
}
}
}
async close(): Promise<void> {
if (this.closed) return
this.closed = true
this.unsubscribeEvents?.()
this.unsubscribeEvents = undefined
const active = this.activeRtc
this.activeRtc = undefined
if (active !== undefined) await active.close().catch(() => undefined)
const leg = this.currentLeg
this.currentLeg = undefined
if (leg !== undefined) await leg.close().catch(() => undefined)
}
}
async function withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined
try {
return await Promise.race([
promise,
new Promise<T>((_, reject) => {
timer = setTimeout(() => reject(new Error('Operation timed out.')), timeoutMs)
;(timer as { unref?: () => void }).unref?.()
}),
])
} finally {
if (timer !== undefined) clearTimeout(timer)
}
}