Import packages/webrtc/src/rtc-data-channel.ts

This commit is contained in:
QQ 2026-11-14 15:05:49 +08:00
parent eea57a078e
commit e704f15821
1 changed files with 913 additions and 0 deletions

View File

@ -0,0 +1,913 @@
import type { TransportStats } from '@dsh-remote/protocol'
import {
RTC_DATA_CHANNEL_LABEL,
RTC_DATA_CHANNEL_OPTIONS,
summarizeAddress,
summarizeIceCandidate,
type RtcAddressFamily,
type RtcAddressScope,
type RtcCandidateSummary,
type RtcCandidateType,
type RtcDataChannel,
type RtcIceCandidateInit,
type RtcIceServer,
type RtcPeerConnectionDiagnosticEvent,
type RtcPeerConnection,
type RtcPeerConnectionFactory,
type RtcStats,
type RtcStatsEntry,
} from './rtc-adapter.js'
import { RtcChunkCodec, RTC_CHUNK_MAX_MESSAGE_BYTES } from './rtc-chunking.js'
export type RtcRole = 'initiator' | 'responder'
export type RtcSelectedTransport = 'lan' | 'p2p' | 'turn'
export type RtcPathMode = 'LAN' | 'P2P' | 'TURN'
export interface RtcSelectedPath {
transport: RtcSelectedTransport
mode: RtcPathMode
}
export interface RtcPathDetails {
transport?: RtcSelectedTransport
mode?: RtcPathMode
relayUrl?: string
localCandidateType?: string
remoteCandidateType?: string
localAddressScope?: RtcAddressScope
remoteAddressScope?: RtcAddressScope
localAddress?: string
remoteAddress?: string
protocol?: string
relayProtocol?: string
currentRoundTripTimeMs?: number
availableOutgoingBitrate?: number
bytesSent?: number
bytesReceived?: number
}
export interface RtcConnectionDetails extends RtcPathDetails {
connectionState: string
iceConnectionState: string
dataChannelState?: RtcDataChannel['readyState']
diagnostics: RtcConnectionDiagnostics
}
export interface RtcCandidateTelemetry {
total: number
byType: Partial<Record<RtcCandidateType, number>>
byFamily: Partial<Record<RtcAddressFamily, number>>
byScope: Partial<Record<RtcAddressScope, number>>
byProtocol: Record<string, number>
}
export interface RtcCandidatePairTelemetry {
total: number
nominated: number
selected: number
byState: Record<string, number>
byLocalType: Partial<Record<RtcCandidateType, number>>
byRemoteType: Partial<Record<RtcCandidateType, number>>
byLocalFamily: Partial<Record<RtcAddressFamily, number>>
byRemoteFamily: Partial<Record<RtcAddressFamily, number>>
byLocalScope: Partial<Record<RtcAddressScope, number>>
byRemoteScope: Partial<Record<RtcAddressScope, number>>
}
export interface RtcSelectedPathTelemetry {
transport?: RtcSelectedTransport
mode?: RtcPathMode
relayUrl?: string
localCandidateType?: string
remoteCandidateType?: string
localAddressScope?: RtcAddressScope
remoteAddressScope?: RtcAddressScope
protocol?: string
relayProtocol?: string
currentRoundTripTimeMs?: number
availableOutgoingBitrate?: number
}
export interface RtcConnectionDiagnostics {
role: RtcRole
label?: string
connectionState: string
iceConnectionState: string
iceGatheringState: string
localCandidates: RtcCandidateTelemetry
remoteCandidates: RtcCandidateTelemetry
candidatePairs: RtcCandidatePairTelemetry
filteredLocalCandidates: RtcCandidateTelemetry
filteredCandidatePairs: RtcCandidateTelemetry
selectedPath?: RtcSelectedPathTelemetry
}
export type RtcDiagnosticEvent =
| { type: 'local-candidate'; candidate: RtcCandidateSummary; diagnostics: RtcConnectionDiagnostics }
| { type: 'remote-candidate'; candidate: RtcCandidateSummary; action: 'buffered' | 'added' | 'ignored'; diagnostics: RtcConnectionDiagnostics }
| { type: 'local-candidate-filtered'; candidate: RtcCandidateSummary; reason: string; diagnostics: RtcConnectionDiagnostics }
| { type: 'candidate-pair-filtered'; localCandidate?: RtcCandidateSummary; reason: string; diagnostics: RtcConnectionDiagnostics }
| { type: 'state-change'; connectionState: string; iceConnectionState: string; iceGatheringState: string; diagnostics: RtcConnectionDiagnostics }
| { type: 'selected-path'; selectedPath: RtcSelectedPathTelemetry; diagnostics: RtcConnectionDiagnostics }
export type RtcSignal =
| { type: 'offer'; sdp: string }
| { type: 'answer'; sdp: string }
| { type: 'ice'; candidate: RtcIceCandidateInit }
export interface RtcDataChannelTransportOptions {
role: RtcRole
iceServers?: RtcIceServer[]
iceTransportPolicy?: 'all' | 'relay'
factory: RtcPeerConnectionFactory
onSignal: (signal: RtcSignal) => void
negotiateTimeoutMs?: number
channelLabel?: string
/**
* Optional send watchdog for RTC implementations whose `bufferedAmount`
* reliably returns to zero. Disabled by default because React Native and
* some werift versions retain a positive value after data was delivered.
*/
sendTimeoutMs?: number
/** Human-readable diagnostic label; never logged with sensitive content. */
label?: string
/** Candidate/state telemetry hook. Events never contain SDP, credentials, or payload bytes. */
onDiagnostic?: (event: RtcDiagnosticEvent) => void
}
const DEFAULT_NEGOTIATE_TIMEOUT_MS = 8_000
const SELECTED_PATH_RETRY_COUNT = 5
const SELECTED_PATH_RETRY_DELAY_MS = 50
/**
* Complete WebRTC DataChannel transport state machine (webrtc plan §6.1).
*
* Owns one `RTCPeerConnection` + ordered `dsh` DataChannel for a single
* connection establishment. It emits offer/answer/trickle-ICE via `onSignal`
* and consumes the peer's signaling through `handleSignal`; the owner wires
* those two ends to the Server control channel. `connect()` resolves only
* once the DataChannel reaches `open`.
*/
export class RtcDataChannelTransport {
private readonly pc: RtcPeerConnection
private readonly role: RtcRole
private readonly onSignal: (signal: RtcSignal) => void
private readonly negotiateTimeoutMs: number
private readonly channelLabel: string
private readonly sendTimeoutMs?: number
private readonly label?: string
private readonly onDiagnostic?: (event: RtcDiagnosticEvent) => void
private channel?: RtcDataChannel
private readonly remoteCandidates: RtcIceCandidateInit[] = []
private remoteDescriptionSet = false
private opened = false
private closed = false
private readonly messageHandlers = new Set<(data: Uint8Array) => void>()
private readonly closeHandlers = new Set<() => void>()
private readonly errorHandlers = new Set<(error: Error) => void>()
private connectPromise?: Promise<void>
private openResolve?: () => void
private openReject?: (error: Error) => void
private negotiateTimer?: ReturnType<typeof setTimeout>
private removeAbort?: () => void
private watchdogTimer?: ReturnType<typeof setTimeout>
private readonly outgoing = new RtcChunkCodec()
private readonly incoming = new RtcChunkCodec()
private bytesSent = 0
private bytesReceived = 0
private selected?: RtcSelectedTransport
private selectedMode?: RtcPathMode
private selectedRelayUrlValue?: string
private selectedPathTelemetry?: RtcSelectedPathTelemetry
private readonly localCandidateTelemetry = emptyCandidateTelemetry()
private readonly remoteCandidateTelemetry = emptyCandidateTelemetry()
private candidatePairTelemetry = emptyCandidatePairTelemetry()
private readonly filteredLocalCandidateTelemetry = emptyCandidateTelemetry()
private readonly filteredCandidatePairTelemetry = emptyCandidateTelemetry()
private lastBufferedAmount = 0
constructor(options: RtcDataChannelTransportOptions) {
this.role = options.role
this.onSignal = options.onSignal
this.negotiateTimeoutMs = options.negotiateTimeoutMs ?? DEFAULT_NEGOTIATE_TIMEOUT_MS
this.channelLabel = options.channelLabel ?? RTC_DATA_CHANNEL_LABEL
this.sendTimeoutMs = options.sendTimeoutMs
this.label = options.label
this.onDiagnostic = options.onDiagnostic
this.pc = options.factory.create({
iceServers: options.iceServers,
iceTransportPolicy: options.iceTransportPolicy,
onDiagnostic: event => this.handlePeerDiagnostic(event),
})
this.pc.ondatachannel = event => this.adoptChannel(event.channel)
this.pc.onicecandidate = event => {
if (event.candidate !== null && !this.closed) {
const candidate = summarizeIceCandidate(event.candidate)
recordCandidate(this.localCandidateTelemetry, candidate)
this.emitDiagnostic({ type: 'local-candidate', candidate, diagnostics: this.diagnostics() })
this.onSignal({ type: 'ice', candidate: event.candidate })
}
}
this.pc.onconnectionstatechange = () => {
this.emitStateChange()
this.checkConnectionState()
}
this.pc.oniceconnectionstatechange = () => {
this.emitStateChange()
this.checkConnectionState()
}
this.pc.onicegatheringstatechange = () => this.emitStateChange()
}
/** Begin negotiation; resolves when the DataChannel is open. */
connect(signal?: AbortSignal): Promise<void> {
if (this.closed) return Promise.reject(new RtcConnectError('RTC_CLOSED', 'WebRTC transport closed.'))
if (signal?.aborted) return Promise.reject(new RtcConnectError('RTC_ABORTED', 'WebRTC negotiation was aborted.'))
if (this.opened) return Promise.resolve()
if (this.connectPromise !== undefined) return this.connectPromise
this.armAbort(signal)
this.connectPromise = new Promise<void>((resolve, reject) => {
this.openResolve = resolve
this.openReject = reject
this.negotiateTimer = setTimeout(() => {
void this.failOpenAfterStats(new RtcConnectError('RTC_CONNECT_TIMEOUT', `WebRTC negotiation timed out after ${this.negotiateTimeoutMs}ms.`))
}, this.negotiateTimeoutMs)
if (this.role === 'initiator') {
void this.startInitiator().catch(error => this.failOpen(asError(error)))
}
})
return this.connectPromise
}
handleSignal(signal: RtcSignal): void {
if (this.closed) return
if (signal.type === 'offer') void this.handleOffer(signal.sdp)
else if (signal.type === 'answer') void this.handleAnswer(signal.sdp)
else void this.handleIce(signal.candidate)
}
async send(data: Uint8Array): Promise<void> {
const channel = this.requireOpenChannel()
if (channel.readyState !== 'open') throw new Error('WebRTC data channel is not open.')
for (const frame of this.outgoing.encode(data)) {
try {
channel.send(toArrayBuffer(frame))
} catch (error) {
console.error('[rtc-send-error] bytes=' + frame.byteLength, error instanceof Error ? error.message : error)
throw error
}
}
this.bytesSent += data.byteLength
this.armWatchdog(channel)
}
onMessage(handler: (data: Uint8Array) => void): () => void {
this.messageHandlers.add(handler)
return () => this.messageHandlers.delete(handler)
}
onClose(handler: () => void): () => void {
this.closeHandlers.add(handler)
return () => this.closeHandlers.delete(handler)
}
onError(handler: (error: Error) => void): () => void {
this.errorHandlers.add(handler)
return () => this.errorHandlers.delete(handler)
}
selectedTransport(): RtcSelectedTransport | undefined {
return this.selected
}
selectedRelayUrl(): string | undefined {
return this.selectedRelayUrlValue
}
selectedPathMode(): RtcPathMode | undefined {
return this.selectedMode
}
diagnostics(): RtcConnectionDiagnostics {
return {
role: this.role,
...(this.label === undefined ? {} : { label: this.label }),
connectionState: this.pc.connectionState,
iceConnectionState: this.pc.iceConnectionState,
iceGatheringState: this.pc.iceGatheringState,
localCandidates: cloneCandidateTelemetry(this.localCandidateTelemetry),
remoteCandidates: cloneCandidateTelemetry(this.remoteCandidateTelemetry),
candidatePairs: cloneCandidatePairTelemetry(this.candidatePairTelemetry),
filteredLocalCandidates: cloneCandidateTelemetry(this.filteredLocalCandidateTelemetry),
filteredCandidatePairs: cloneCandidateTelemetry(this.filteredCandidatePairTelemetry),
...(this.selectedPathTelemetry === undefined ? {} : { selectedPath: { ...this.selectedPathTelemetry } }),
}
}
async connectionDetails(): Promise<RtcConnectionDetails> {
let statsDetails: RtcPathDetails = {}
try {
statsDetails = await this.refreshStatsDiagnostics()
} catch {
// Peer/DataChannel state remains useful if the RTC backend withholds stats.
}
return {
...statsDetails,
mode: statsDetails.mode ?? this.selectedMode,
connectionState: this.pc.connectionState,
iceConnectionState: this.pc.iceConnectionState,
dataChannelState: this.channel?.readyState,
diagnostics: this.diagnostics(),
}
}
getStats(): TransportStats {
const connected = this.channel?.readyState === 'open'
return {
mode: !connected
? 'Disconnected'
: this.selectedMode ?? (this.selected === 'turn' ? 'TURN' : this.selected === 'lan' ? 'LAN' : 'P2P'),
connected,
bytesSent: this.bytesSent,
bytesReceived: this.bytesReceived,
}
}
/** Idempotent close: releases PeerConnection, DataChannel, timers and listeners. */
async close(): Promise<void> {
if (this.closed) return
this.closed = true
this.clearNegotiation()
this.openReject?.(new RtcConnectError('RTC_CLOSED', 'WebRTC transport closed during negotiation.'))
this.openResolve = undefined
this.openReject = undefined
this.clearWatchdog()
const channel = this.channel
this.channel = undefined
if (channel !== undefined) {
channel.onopen = null
channel.onmessage = null
channel.onclose = null
channel.onerror = null
channel.onbufferedamountlow = null
try { channel.close() } catch { /* already closed */ }
}
this.pc.onicecandidate = null
this.pc.ondatachannel = null
this.pc.onconnectionstatechange = null
this.pc.oniceconnectionstatechange = null
try { this.pc.close() } catch { /* already closed */ }
if (this.opened) {
this.opened = false
for (const handler of this.closeHandlers) handler()
}
}
private armAbort(signal: AbortSignal | undefined): void {
this.removeAbort?.()
this.removeAbort = undefined
if (signal === undefined) return
const onAbort = () => {
this.failOpen(new RtcConnectError('RTC_ABORTED', 'WebRTC negotiation was aborted.'))
}
signal.addEventListener('abort', onAbort, { once: true })
this.removeAbort = () => signal.removeEventListener('abort', onAbort)
if (signal.aborted) onAbort()
}
private async startInitiator(): Promise<void> {
const channel = this.pc.createDataChannel(this.channelLabel, RTC_DATA_CHANNEL_OPTIONS)
this.adoptChannel(channel)
const offer = await this.pc.createOffer()
if (this.closed) return
await this.pc.setLocalDescription(offer)
if (this.closed) return
this.onSignal({ type: 'offer', sdp: requireSdp(offer) })
}
private async handleOffer(sdp: string): Promise<void> {
if (this.role !== 'responder' || this.remoteDescriptionSet) {
this.failOpen(new RtcConnectError('RTC_INVALID_STATE', 'Received an unexpected WebRTC offer.'))
return
}
try {
await this.pc.setRemoteDescription({ type: 'offer', sdp })
this.remoteDescriptionSet = true
await this.flushRemoteCandidates()
const answer = await this.pc.createAnswer()
await this.pc.setLocalDescription(answer)
this.onSignal({ type: 'answer', sdp: requireSdp(answer) })
} catch (error) {
this.failOpen(asError(error))
}
}
private async handleAnswer(sdp: string): Promise<void> {
if (this.role !== 'initiator' || this.remoteDescriptionSet) {
this.failOpen(new RtcConnectError('RTC_INVALID_STATE', 'Received an unexpected WebRTC answer.'))
return
}
try {
await this.pc.setRemoteDescription({ type: 'answer', sdp })
this.remoteDescriptionSet = true
await this.flushRemoteCandidates()
} catch (error) {
this.failOpen(asError(error))
}
}
private async handleIce(candidate: RtcIceCandidateInit): Promise<void> {
const summary = summarizeIceCandidate(candidate)
if (!this.remoteDescriptionSet) {
recordCandidate(this.remoteCandidateTelemetry, summary)
this.emitDiagnostic({ type: 'remote-candidate', candidate: summary, action: 'buffered', diagnostics: this.diagnostics() })
this.remoteCandidates.push(candidate)
return
}
try {
await this.pc.addIceCandidate(candidate)
recordCandidate(this.remoteCandidateTelemetry, summary)
this.emitDiagnostic({ type: 'remote-candidate', candidate: summary, action: 'added', diagnostics: this.diagnostics() })
} catch {
this.emitDiagnostic({ type: 'remote-candidate', candidate: summary, action: 'ignored', diagnostics: this.diagnostics() })
// Ignore malformed/duplicate candidates; the connection either proceeds
// or the negotiation timeout surfaces the failure.
}
}
private async flushRemoteCandidates(): Promise<void> {
const buffered = this.remoteCandidates.splice(0, this.remoteCandidates.length)
for (const candidate of buffered) {
try { await this.pc.addIceCandidate(candidate) } catch { /* ignored */ }
}
}
private adoptChannel(channel: RtcDataChannel): void {
if (this.channel !== undefined && this.channel !== channel) {
try { channel.close() } catch { /* ignored */ }
return
}
this.channel = channel
channel.binaryType = 'arraybuffer'
channel.onopen = () => {
if (this.closed || this.opened) return
this.opened = true
const resolve = this.openResolve
this.clearNegotiation()
void this.resolveSelectedTransport().then(() => {
if (this.closed) return
this.openResolve = undefined
this.openReject = undefined
resolve?.()
})
}
channel.onmessage = event => {
if (this.closed || !this.opened) return
const data = event.data
const frame = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data)
this.bytesReceived += frame.byteLength
try {
const message = this.incoming.decode(frame)
if (message === undefined) return
for (const handler of this.messageHandlers) handler(message)
} catch {
void this.close()
}
}
channel.onclose = () => {
if (this.closed) return
this.failOpen(new RtcConnectError('RTC_CLOSED', 'WebRTC data channel closed.'))
if (this.opened) {
this.opened = false
for (const handler of this.closeHandlers) handler()
}
}
channel.onerror = () => {
const error = new RtcConnectError('RTC_FAILED', 'WebRTC data channel reported an error.')
this.failOpen(error)
for (const handler of this.errorHandlers) handler(error)
}
}
private async resolveSelectedTransport(): Promise<void> {
try {
let selected = await this.refreshStatsDiagnostics()
// Native libwebrtc can open the DataChannel one tick before the selected
// candidate pair is exposed through getStats(). A one-shot read leaves
// selectedMode undefined forever, which is then incorrectly presented as
// generic P2P even when the eventual pair is LAN or TURN.
for (let attempt = 0;
attempt < SELECTED_PATH_RETRY_COUNT
&& !this.closed
&& (selected.transport === undefined || selected.mode === undefined || selected.mode === 'P2P');
attempt += 1) {
await sleep(SELECTED_PATH_RETRY_DELAY_MS)
selected = await this.refreshStatsDiagnostics()
}
this.selected = selected?.transport
this.selectedMode = selected?.mode
this.selectedRelayUrlValue = selected?.relayUrl
this.selectedPathTelemetry = selectedPathTelemetry(selected)
this.emitDiagnostic({
type: 'selected-path',
selectedPath: this.selectedPathTelemetry,
diagnostics: this.diagnostics(),
})
} catch {
this.selected = undefined
this.selectedMode = undefined
}
}
private checkConnectionState(): void {
if (this.closed || this.opened) return
if (this.pc.connectionState === 'failed' || this.pc.iceConnectionState === 'failed'
|| this.pc.connectionState === 'closed' || this.pc.iceConnectionState === 'closed') {
void this.failOpenAfterStats(new RtcConnectError('RTC_FAILED', 'WebRTC peer connection failed before the data channel opened.'))
}
}
private async failOpenAfterStats(error: Error): Promise<void> {
await this.refreshStatsDiagnostics().catch(() => undefined)
this.failOpen(error)
}
private failOpen(error: Error): void {
if (this.closed || this.opened || this.openReject === undefined) return
const reject = this.openReject
this.clearNegotiation()
this.openResolve = undefined
this.openReject = undefined
reject(error)
void this.close()
}
private clearNegotiation(): void {
if (this.negotiateTimer !== undefined) clearTimeout(this.negotiateTimer)
this.negotiateTimer = undefined
this.removeAbort?.()
this.removeAbort = undefined
}
private requireOpenChannel(): RtcDataChannel {
const channel = this.channel
if (channel === undefined || channel.readyState !== 'open' || this.closed || !this.opened) {
throw new Error('WebRTC data channel is not open.')
}
return channel
}
private armWatchdog(channel: RtcDataChannel): void {
if (this.closed || this.sendTimeoutMs === undefined || this.sendTimeoutMs <= 0) return
if (this.watchdogTimer !== undefined) clearTimeout(this.watchdogTimer)
this.watchdogTimer = undefined
const baseline = channel.bufferedAmount
if (baseline <= 0) {
this.lastBufferedAmount = 0
return
}
this.lastBufferedAmount = baseline
this.watchdogTimer = setTimeout(() => {
this.watchdogTimer = undefined
if (this.closed || this.channel !== channel || channel.readyState !== 'open') return
const current = channel.bufferedAmount
if (current > 0 && current >= this.lastBufferedAmount) {
// The outbound queue has not drained since the last check: the peer is
// not ACKing. Treat the transport as unhealthy so the owner can fall
// back instead of leaving the RPC sender queue blocked forever.
const error = new RtcConnectError('RTC_SEND_TIMEOUT', 'DataChannel send stalled.')
for (const handler of this.errorHandlers) handler(error)
void this.close()
return
}
this.lastBufferedAmount = current
if (current > 0) this.armWatchdog(channel)
}, this.sendTimeoutMs)
}
private clearWatchdog(): void {
if (this.watchdogTimer !== undefined) clearTimeout(this.watchdogTimer)
this.watchdogTimer = undefined
this.lastBufferedAmount = 0
}
private async refreshStatsDiagnostics(): Promise<RtcPathDetails> {
// Native getStats() must not leave startup waiting after the channel opens.
const stats = [...await new Promise<RtcStats>((resolve, reject) => {
const timer = setTimeout(() => reject(new Error('WebRTC statistics timed out.')), 250)
Promise.resolve().then(() => this.pc.getStats()).then(resolve, reject).finally(() => clearTimeout(timer))
})]
if (this.closed) return {}
this.candidatePairTelemetry = inspectCandidatePairs(stats)
return inspectSelectedPath(stats)
}
private handlePeerDiagnostic(event: RtcPeerConnectionDiagnosticEvent): void {
if (event.type === 'local-candidate-filtered') {
recordCandidate(this.filteredLocalCandidateTelemetry, event.candidate)
this.emitDiagnostic({
type: event.type,
candidate: event.candidate,
reason: event.reason,
diagnostics: this.diagnostics(),
})
return
}
if (event.localCandidate !== undefined) recordCandidate(this.filteredCandidatePairTelemetry, event.localCandidate)
this.emitDiagnostic({
type: event.type,
localCandidate: event.localCandidate,
reason: event.reason,
diagnostics: this.diagnostics(),
})
}
private emitStateChange(): void {
this.emitDiagnostic({
type: 'state-change',
connectionState: this.pc.connectionState,
iceConnectionState: this.pc.iceConnectionState,
iceGatheringState: this.pc.iceGatheringState,
diagnostics: this.diagnostics(),
})
}
private emitDiagnostic(event: RtcDiagnosticEvent): void {
try { this.onDiagnostic?.(event) } catch { /* diagnostics must not affect transport state */ }
}
}
export class RtcConnectError extends Error {
constructor(readonly code: string, message: string) { super(message) }
}
export function detectSelectedTransport(stats: RtcStats): RtcSelectedTransport | undefined {
return detectSelectedPath(stats)?.transport
}
export function detectSelectedPath(stats: RtcStats): RtcSelectedPath | undefined {
const details = inspectSelectedPath(stats)
return details.transport === undefined || details.mode === undefined
? undefined
: { transport: details.transport, mode: details.mode }
}
export function inspectSelectedPath(stats: RtcStats): RtcPathDetails {
// candidate-pair `localCandidateId`/`remoteCandidateId` reference the `id`
// member of the local/remote-candidate stats (not the report map key).
const candidates = new Map<string, RtcStatsEntry>()
const candidatePairs = new Map<string, RtcStatsEntry>()
const selectedPairs: RtcStatsEntry[] = []
const selectedPairIds = new Set<string>()
for (const [reportId, entry] of stats) {
if (entry.type === 'local-candidate' || entry.type === 'remote-candidate') {
if (typeof entry.candidateType === 'string' && entry.id !== undefined) {
candidates.set(String(entry.id), entry)
}
} else if (entry.type === 'candidate-pair') {
candidatePairs.set(String(entry.id ?? reportId), entry)
if (entry.selected === true || entry.nominated === true) selectedPairs.push(entry)
} else if (entry.type === 'transport' && typeof entry.selectedCandidatePairId === 'string') {
selectedPairIds.add(entry.selectedCandidatePairId)
}
}
const pairs = [
...[...selectedPairIds].map(id => candidatePairs.get(id)).filter((pair): pair is RtcStatsEntry => pair !== undefined),
...selectedPairs,
]
for (const pair of pairs) {
const local = candidates.get(String(pair.localCandidateId))
const remote = candidates.get(String(pair.remoteCandidateId))
const localType = local?.candidateType
const remoteType = remote?.candidateType
const localAddressScope = summarizeAddress(candidateAddressValue(local)).addressScope
const remoteAddressScope = summarizeAddress(candidateAddressValue(remote)).addressScope
let selected: RtcSelectedPath | undefined
if (localType === 'relay' || remoteType === 'relay') selected = { transport: 'turn', mode: 'TURN' }
const relayUrl = localType === 'relay' ? stringStat(local, 'url') : undefined
if (local === undefined && remote === undefined) continue
const lan = isLanCandidatePair(localType, remoteType, localAddressScope, remoteAddressScope)
selected ??= { transport: lan ? 'lan' : 'p2p', mode: lan ? 'LAN' : 'P2P' }
const currentRoundTripTime = numberStat(pair, 'currentRoundTripTime')
return {
...selected,
...(relayUrl === undefined ? {} : { relayUrl }),
localCandidateType: stringStat(local, 'candidateType'),
remoteCandidateType: stringStat(remote, 'candidateType'),
localAddressScope,
remoteAddressScope,
localAddress: candidateAddress(local),
remoteAddress: candidateAddress(remote),
protocol: stringStat(local, 'protocol') ?? stringStat(remote, 'protocol'),
relayProtocol: stringStat(local, 'relayProtocol') ?? stringStat(remote, 'relayProtocol'),
currentRoundTripTimeMs: currentRoundTripTime === undefined
? undefined
: Math.round(currentRoundTripTime * 1000),
availableOutgoingBitrate: numberStat(pair, 'availableOutgoingBitrate'),
bytesSent: numberStat(pair, 'bytesSent'),
bytesReceived: numberStat(pair, 'bytesReceived'),
}
}
return {}
}
export function inspectCandidatePairs(stats: RtcStats): RtcCandidatePairTelemetry {
const candidates = new Map<string, RtcStatsEntry>()
const telemetry = emptyCandidatePairTelemetry()
const pairs: RtcStatsEntry[] = []
for (const [reportId, entry] of stats) {
if (entry.type === 'local-candidate' || entry.type === 'remote-candidate') {
if (typeof entry.candidateType === 'string' && entry.id !== undefined) {
candidates.set(String(entry.id), entry)
}
} else if (entry.type === 'candidate-pair') {
pairs.push({ ...entry, id: entry.id ?? reportId })
}
}
for (const pair of pairs) {
telemetry.total += 1
if (pair.nominated === true) telemetry.nominated += 1
if (pair.selected === true) telemetry.selected += 1
increment(telemetry.byState, stringStat(pair, 'state') ?? (pair.selected === true ? 'selected' : 'unknown'))
const local = candidates.get(String(pair.localCandidateId))
const remote = candidates.get(String(pair.remoteCandidateId))
recordCandidateStats(telemetry.byLocalType, telemetry.byLocalFamily, telemetry.byLocalScope, local)
recordCandidateStats(telemetry.byRemoteType, telemetry.byRemoteFamily, telemetry.byRemoteScope, remote)
}
return telemetry
}
function candidateAddress(candidate: RtcStatsEntry | undefined): string | undefined {
const address = stringStat(candidate, 'address') ?? stringStat(candidate, 'ip')
if (address === undefined) return undefined
const port = numberStat(candidate, 'port')
return port === undefined ? address : `${address}:${port}`
}
function stringStat(entry: RtcStatsEntry | undefined, key: string): string | undefined {
const value = entry?.[key]
return typeof value === 'string' && value.length > 0 ? value : undefined
}
function numberStat(entry: RtcStatsEntry | undefined, key: string): number | undefined {
const value = entry?.[key]
return typeof value === 'number' && Number.isFinite(value) ? value : undefined
}
function emptyCandidateTelemetry(): RtcCandidateTelemetry {
return {
total: 0,
byType: {},
byFamily: {},
byScope: {},
byProtocol: {},
}
}
function cloneCandidateTelemetry(value: RtcCandidateTelemetry): RtcCandidateTelemetry {
return {
total: value.total,
byType: { ...value.byType },
byFamily: { ...value.byFamily },
byScope: { ...value.byScope },
byProtocol: { ...value.byProtocol },
}
}
function emptyCandidatePairTelemetry(): RtcCandidatePairTelemetry {
return {
total: 0,
nominated: 0,
selected: 0,
byState: {},
byLocalType: {},
byRemoteType: {},
byLocalFamily: {},
byRemoteFamily: {},
byLocalScope: {},
byRemoteScope: {},
}
}
function cloneCandidatePairTelemetry(value: RtcCandidatePairTelemetry): RtcCandidatePairTelemetry {
return {
total: value.total,
nominated: value.nominated,
selected: value.selected,
byState: { ...value.byState },
byLocalType: { ...value.byLocalType },
byRemoteType: { ...value.byRemoteType },
byLocalFamily: { ...value.byLocalFamily },
byRemoteFamily: { ...value.byRemoteFamily },
byLocalScope: { ...value.byLocalScope },
byRemoteScope: { ...value.byRemoteScope },
}
}
function recordCandidate(telemetry: RtcCandidateTelemetry, candidate: RtcCandidateSummary): void {
telemetry.total += 1
increment(telemetry.byType, candidate.candidateType)
increment(telemetry.byFamily, candidate.addressFamily)
increment(telemetry.byScope, candidate.addressScope)
if (candidate.protocol !== undefined) increment(telemetry.byProtocol, candidate.protocol)
}
function recordCandidateStats(
byType: Partial<Record<RtcCandidateType, number>>,
byFamily: Partial<Record<RtcAddressFamily, number>>,
byScope: Partial<Record<RtcAddressScope, number>>,
candidate: RtcStatsEntry | undefined,
): void {
const candidateType = candidateTypeStat(candidate)
const address = summarizeAddress(candidateAddressValue(candidate))
increment(byType, candidateType)
increment(byFamily, address.addressFamily)
increment(byScope, address.addressScope)
}
function candidateTypeStat(candidate: RtcStatsEntry | undefined): RtcCandidateType {
const value = stringStat(candidate, 'candidateType')
if (value === 'host' || value === 'srflx' || value === 'prflx' || value === 'relay') return value
return 'unknown'
}
function candidateAddressValue(candidate: RtcStatsEntry | undefined): string | undefined {
return stringStat(candidate, 'address') ?? stringStat(candidate, 'ip')
}
function isLanCandidatePair(
localType: unknown,
remoteType: unknown,
localScope: RtcAddressScope,
remoteScope: RtcAddressScope,
): boolean {
if (localType === 'host' && remoteType === 'host') {
// Keep address-hidden/mDNS host pairs compatible, but do not label an
// explicitly identified overlay or public host pair as physical LAN.
return !isExplicitlyNonLanScope(localScope) && !isExplicitlyNonLanScope(remoteScope)
}
const directTypes = new Set(['host', 'prflx'])
if (!directTypes.has(String(localType)) || !directTypes.has(String(remoteType))) return false
if (isLocalNetworkScope(localScope) && isLocalNetworkScope(remoteScope)) return true
// libwebrtc commonly represents an mDNS-obscured LAN endpoint as prflx and
// withholds its address from getStats(). Keep an explicitly public/cgnat
// peer-reflexive endpoint as P2P, but accept the private host + unknown prflx
// shape emitted by Android and @roamhq/wrtc for a selected LAN path.
return (localType === 'host' && isLocalNetworkScope(localScope)
&& remoteType === 'prflx' && remoteScope === 'unknown')
|| (remoteType === 'host' && isLocalNetworkScope(remoteScope)
&& localType === 'prflx' && localScope === 'unknown')
}
function isLocalNetworkScope(scope: RtcAddressScope): boolean {
return scope === 'private' || scope === 'link-local' || scope === 'loopback'
}
function isExplicitlyNonLanScope(scope: RtcAddressScope): boolean {
return scope === 'public' || scope === 'cgnat' || scope === 'reserved'
}
function increment(map: Record<string, number>, key: string): void {
map[key] = (map[key] ?? 0) + 1
}
function selectedPathTelemetry(details: RtcPathDetails): RtcSelectedPathTelemetry {
return {
...(details.transport === undefined ? {} : { transport: details.transport }),
...(details.mode === undefined ? {} : { mode: details.mode }),
...(details.relayUrl === undefined ? {} : { relayUrl: details.relayUrl }),
...(details.localCandidateType === undefined ? {} : { localCandidateType: details.localCandidateType }),
...(details.remoteCandidateType === undefined ? {} : { remoteCandidateType: details.remoteCandidateType }),
...(details.localAddressScope === undefined ? {} : { localAddressScope: details.localAddressScope }),
...(details.remoteAddressScope === undefined ? {} : { remoteAddressScope: details.remoteAddressScope }),
...(details.protocol === undefined ? {} : { protocol: details.protocol }),
...(details.relayProtocol === undefined ? {} : { relayProtocol: details.relayProtocol }),
...(details.currentRoundTripTimeMs === undefined ? {} : { currentRoundTripTimeMs: details.currentRoundTripTimeMs }),
...(details.availableOutgoingBitrate === undefined ? {} : { availableOutgoingBitrate: details.availableOutgoingBitrate }),
}
}
function requireSdp(description: { type: 'offer' | 'answer'; sdp?: string }): string {
if (typeof description.sdp !== 'string' || description.sdp.length === 0) {
throw new RtcConnectError('RTC_FAILED', 'The RTC backend produced an empty session description.')
}
return description.sdp
}
function toArrayBuffer(data: Uint8Array): ArrayBuffer {
if (data.byteOffset === 0 && data.byteLength === data.buffer.byteLength) return data.buffer as ArrayBuffer
return data.slice().buffer as ArrayBuffer
}
function asError(error: unknown): Error {
return error instanceof Error ? error : new RtcConnectError('RTC_FAILED', 'WebRTC negotiation failed.')
}
function sleep(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms))
}