Import packages/webrtc/src/rtc-adapter.ts
This commit is contained in:
parent
6420de56f7
commit
f6266225d1
|
|
@ -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<RtcSessionDescriptionInit>
|
||||
createAnswer(): Promise<RtcSessionDescriptionInit>
|
||||
setLocalDescription(description?: RtcSessionDescriptionInit): Promise<void>
|
||||
setRemoteDescription(description: RtcSessionDescriptionInit): Promise<void>
|
||||
addIceCandidate(candidate?: RtcIceCandidateInit): Promise<void>
|
||||
getStats(): Promise<RtcStats>
|
||||
close(): void
|
||||
}
|
||||
|
||||
/** A single WebRTC stats report entry (id -> typed record). */
|
||||
export interface RtcStatsEntry {
|
||||
type?: string
|
||||
[key: string]: unknown
|
||||
}
|
||||
|
||||
export type RtcStats = Iterable<readonly [string, RtcStatsEntry]>
|
||||
|
||||
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<RtcCandidateSummary, 'relatedAddressFamily' | 'relatedAddressScope'> {
|
||||
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() },
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue