Import packages/plugin/src/transport-upgrade.ts
This commit is contained in:
parent
60927632df
commit
d26672a610
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue