From f6266225d1d7d60a3750d796f8301e1c631961c8 Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 15:05:43 +0800 Subject: [PATCH] Import packages/webrtc/src/rtc-adapter.ts --- packages/webrtc/src/rtc-adapter.ts | 257 +++++++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 packages/webrtc/src/rtc-adapter.ts diff --git a/packages/webrtc/src/rtc-adapter.ts b/packages/webrtc/src/rtc-adapter.ts new file mode 100644 index 0000000..fc64232 --- /dev/null +++ b/packages/webrtc/src/rtc-adapter.ts @@ -0,0 +1,257 @@ +/** + * Environment-agnostic RTC peer-connection surface. + * + * The transport state machine only talks to these narrow interfaces so the + * browser native `RTCPeerConnection` and a future Node host backend can both + * provide the underlying peer connection without the business code depending + * on a specific RTC implementation (webrtc-implementation-plan.md §6.1/§6.2). + */ + +export interface RtcIceServer { + urls: string | string[] + username?: string + credential?: string +} + +export interface RtcIceCandidateInit { + candidate?: string + sdpMid?: string | null + sdpMLineIndex?: number | null + usernameFragment?: string | null +} + +export type RtcCandidateType = 'host' | 'srflx' | 'prflx' | 'relay' | 'unknown' +export type RtcAddressFamily = 'ipv4' | 'ipv6' | 'unknown' +export type RtcAddressScope = 'private' | 'public' | 'loopback' | 'link-local' | 'cgnat' | 'reserved' | 'unknown' + +export interface RtcCandidateSummary { + candidateType: RtcCandidateType + protocol?: string + addressFamily: RtcAddressFamily + addressScope: RtcAddressScope + relatedAddressFamily?: RtcAddressFamily + relatedAddressScope?: RtcAddressScope +} + +export type RtcPeerConnectionDiagnosticEvent = + | { type: 'local-candidate-filtered'; candidate: RtcCandidateSummary; reason: string } + | { type: 'candidate-pair-filtered'; localCandidate?: RtcCandidateSummary; reason: string } + +export interface RtcPeerConnectionConfiguration { + iceServers?: RtcIceServer[] + iceTransportPolicy?: 'all' | 'relay' + onDiagnostic?: (event: RtcPeerConnectionDiagnosticEvent) => void +} + +export interface RtcSessionDescriptionInit { + type: 'offer' | 'answer' + sdp?: string +} + +export interface RtcDataChannelInit { + ordered?: boolean +} + +export interface RtcDataChannel { + readonly label: string + readonly ordered: boolean + readyState: 'connecting' | 'open' | 'closing' | 'closed' + bufferedAmount: number + binaryType: string + onopen: (() => void) | null + onmessage: ((event: { data: ArrayBuffer | string }) => void) | null + onclose: (() => void) | null + onerror: (() => void) | null + onbufferedamountlow: (() => void) | null + send(data: ArrayBuffer | string): void + close(): void +} + +export interface RtcPeerConnection { + connectionState: string + iceConnectionState: string + iceGatheringState: string + signalingState: string + onconnectionstatechange: (() => void) | null + oniceconnectionstatechange: (() => void) | null + onicegatheringstatechange: (() => void) | null + onicecandidate: ((event: { candidate: RtcIceCandidateInit | null }) => void) | null + ondatachannel: ((event: { channel: RtcDataChannel }) => void) | null + createDataChannel(label: string, options?: RtcDataChannelInit): RtcDataChannel + createOffer(): Promise + createAnswer(): Promise + setLocalDescription(description?: RtcSessionDescriptionInit): Promise + setRemoteDescription(description: RtcSessionDescriptionInit): Promise + addIceCandidate(candidate?: RtcIceCandidateInit): Promise + getStats(): Promise + close(): void +} + +/** A single WebRTC stats report entry (id -> typed record). */ +export interface RtcStatsEntry { + type?: string + [key: string]: unknown +} + +export type RtcStats = Iterable + +export interface RtcPeerConnectionFactory { + create(configuration: RtcPeerConnectionConfiguration): RtcPeerConnection +} + +export const RTC_DATA_CHANNEL_LABEL = 'dsh' +export const RTC_DATA_CHANNEL_OPTIONS = { ordered: true } as const + +/** + * Default browser-backed factory. This module is the only place in the webrtc + * package that references the DOM `RTCPeerConnection` global, so Node hosts + * inject their own factory and never import browser natives. + */ +export function browserRtcFactory(): RtcPeerConnectionFactory { + return { + create(configuration) { + // `any` keeps the DOM handler `this`/event typing out of the adapter. + // eslint-disable-next-line @typescript-eslint/no-explicit-any + const raw = new RTCPeerConnection({ + iceServers: configuration.iceServers, + iceTransportPolicy: configuration.iceTransportPolicy, + }) as any + return { + get connectionState(): string { return raw.connectionState as string }, + get iceConnectionState(): string { return raw.iceConnectionState as string }, + get iceGatheringState(): string { return raw.iceGatheringState as string }, + get signalingState(): string { return raw.signalingState as string }, + set onconnectionstatechange(value) { raw.onconnectionstatechange = value }, + get onconnectionstatechange() { return raw.onconnectionstatechange as (() => void) | null }, + set oniceconnectionstatechange(value) { raw.oniceconnectionstatechange = value }, + get oniceconnectionstatechange() { return raw.oniceconnectionstatechange as (() => void) | null }, + set onicegatheringstatechange(value) { raw.onicegatheringstatechange = value }, + get onicegatheringstatechange() { return raw.onicegatheringstatechange as (() => void) | null }, + set onicecandidate(value) { raw.onicecandidate = value }, + get onicecandidate() { return raw.onicecandidate as ((event: { candidate: RtcIceCandidateInit | null }) => void) | null }, + set ondatachannel(value) { raw.ondatachannel = value }, + get ondatachannel() { return raw.ondatachannel as ((event: { channel: RtcDataChannel }) => void) | null }, + createDataChannel(label, options) { return adaptDataChannel(raw.createDataChannel(label, options)) }, + createOffer() { return raw.createOffer() }, + createAnswer() { return raw.createAnswer() }, + setLocalDescription(description) { return raw.setLocalDescription(description) }, + setRemoteDescription(description) { return raw.setRemoteDescription(description) }, + addIceCandidate(candidate) { return raw.addIceCandidate(candidate) }, + async getStats() { return await raw.getStats() }, + close() { raw.close() }, + } + }, + } +} + +export function summarizeIceCandidate(candidate: RtcIceCandidateInit | undefined): RtcCandidateSummary { + const value = candidate?.candidate?.trim() + if (value === undefined || value.length === 0) return emptyCandidateSummary() + const parts = value.replace(/^candidate:/, '').split(/\s+/) + const typeIndex = parts.indexOf('typ') + const relatedAddressIndex = parts.indexOf('raddr') + return { + candidateType: parseCandidateType(parts[typeIndex + 1]), + protocol: normalizeProtocol(parts[2]), + ...summarizeAddress(parts[4]), + ...(relatedAddressIndex < 0 + ? {} + : relatedAddressSummary(parts[relatedAddressIndex + 1])), + } +} + +export function summarizeAddress(address: string | undefined): { addressFamily: RtcAddressFamily; addressScope: RtcAddressScope } { + if (address === undefined || address.length === 0) return { addressFamily: 'unknown', addressScope: 'unknown' } + if (address.includes(':')) return { addressFamily: 'ipv6', addressScope: summarizeIpv6Scope(address) } + const parts = address.split('.').map(Number) + if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0 || part > 255)) { + return { addressFamily: 'unknown', addressScope: 'unknown' } + } + return { addressFamily: 'ipv4', addressScope: summarizeIpv4Scope(parts) } +} + +export function stunOnlyIceServers(iceServers: readonly RtcIceServer[]): RtcIceServer[] { + const direct: RtcIceServer[] = [] + for (const server of iceServers) { + const sourceUrls = Array.isArray(server.urls) ? server.urls : [server.urls] + const urls = sourceUrls.filter(isStunUrl) + if (urls.length === 0) continue + direct.push({ urls: Array.isArray(server.urls) ? urls : urls[0]! }) + } + return direct +} + +function isStunUrl(url: string): boolean { + const value = url.trim().toLowerCase() + return value.startsWith('stun:') || value.startsWith('stuns:') +} + +function emptyCandidateSummary(): RtcCandidateSummary { + return { candidateType: 'unknown', addressFamily: 'unknown', addressScope: 'unknown' } +} + +function parseCandidateType(value: string | undefined): RtcCandidateType { + if (value === 'host' || value === 'srflx' || value === 'prflx' || value === 'relay') return value + return 'unknown' +} + +function normalizeProtocol(value: string | undefined): string | undefined { + if (value === undefined || value.length === 0) return undefined + return value.toLowerCase() +} + +function relatedAddressSummary(address: string | undefined): Pick { + const summary = summarizeAddress(address) + return { + relatedAddressFamily: summary.addressFamily, + relatedAddressScope: summary.addressScope, + } +} + +function summarizeIpv4Scope(parts: number[]): RtcAddressScope { + if (parts[0] === 0 || parts[0] >= 240) return 'reserved' + if (parts[0] === 127) return 'loopback' + if (parts[0] === 169 && parts[1] === 254) return 'link-local' + if (parts[0] === 100 && parts[1] >= 64 && parts[1] <= 127) return 'cgnat' + if (parts[0] >= 224) return 'reserved' + if (parts[0] === 10) return 'private' + if (parts[0] === 192 && parts[1] === 168) return 'private' + if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return 'private' + return 'public' +} + +function summarizeIpv6Scope(address: string): RtcAddressScope { + const value = address.toLowerCase() + if (value === '::1') return 'loopback' + if (value.startsWith('fe80:')) return 'link-local' + // Tailscale assigns overlay addresses from fd7a:115c:a1e0::/48. They are + // ULA-shaped, but a selected pair using them is not evidence of a physical + // LAN path. Reuse the non-LAN cgnat scope used for Tailscale's IPv4 range. + if (value.startsWith('fd7a:115c:a1e0:')) return 'cgnat' + if (value.startsWith('fc') || value.startsWith('fd')) return 'private' + if (value.startsWith('ff')) return 'reserved' + return 'public' +} + +function adaptDataChannel(raw: RTCDataChannel): RtcDataChannel { + return { + get label(): string { return raw.label }, + get ordered(): boolean { return raw.ordered }, + get readyState() { return raw.readyState }, + get bufferedAmount(): number { return raw.bufferedAmount }, + get binaryType(): string { return raw.binaryType }, + set binaryType(value: string) { raw.binaryType = value as typeof raw.binaryType }, + set onopen(value) { raw.onopen = value }, + get onopen() { return raw.onopen as (() => void) | null }, + set onmessage(value) { raw.onmessage = value }, + get onmessage() { return raw.onmessage as ((event: { data: ArrayBuffer | string }) => void) | null }, + set onclose(value) { raw.onclose = value }, + get onclose() { return raw.onclose as (() => void) | null }, + set onerror(value) { raw.onerror = value }, + get onerror() { return raw.onerror as (() => void) | null }, + set onbufferedamountlow(value) { raw.onbufferedamountlow = value }, + get onbufferedamountlow() { return raw.onbufferedamountlow as (() => void) | null }, + send(data) { raw.send(data as never) }, + close() { raw.close() }, + } +}