898 lines
39 KiB
TypeScript
898 lines
39 KiB
TypeScript
import { ControlLease } from './control-lease.js'
|
|
import { waitForRelayCapacity } from './websocket-backpressure.js'
|
|
import {
|
|
PROTOCOL_VERSION,
|
|
errorCodeSchema,
|
|
type ErrorCode,
|
|
WEBRTC_RESUME_CAPABILITY,
|
|
RELAY_RESUME_CAPABILITY,
|
|
type ConnectionLeaseAck,
|
|
acceptNegotiatedCapabilities,
|
|
createControlFrame,
|
|
createRelayDataFrame,
|
|
decodeControlFrame,
|
|
decodeRelayDataFrame,
|
|
encodeControlFrame,
|
|
encodeRelayDataFrame,
|
|
type ControlFrameByteLimits,
|
|
type ConnectAcceptedPayload,
|
|
type HelloAckPayload,
|
|
type RelayPayload,
|
|
type SecureHandshakePayload,
|
|
type SelectedTransport,
|
|
type TransportSelectedPayload,
|
|
type TransportStats,
|
|
isHeartbeatTimeoutClose,
|
|
isServerShutdownClose,
|
|
} from '@dsh-remote/protocol'
|
|
import { browserRtcFactory, type RtcIceServer, type RtcPeerConnectionFactory } from './rtc-adapter.js'
|
|
import {
|
|
RtcConnectError,
|
|
RtcDataChannelTransport,
|
|
type RtcConnectionDiagnostics,
|
|
type RtcConnectionDetails,
|
|
type RtcDiagnosticEvent,
|
|
type RtcSelectedTransport,
|
|
type RtcSignal,
|
|
} from './rtc-data-channel.js'
|
|
import { BaseTransport } from './transport.js'
|
|
import { fromBase64Url, toBase64Url } from './util.js'
|
|
|
|
type RelayAssignment = Pick<ConnectAcceptedPayload, 'relayEndpoint' | 'relayTicket' | 'relayNodeId' | 'relayEpoch'>
|
|
|
|
export interface AdaptiveTransportOptions {
|
|
role: 'client'
|
|
deviceId: string
|
|
accessToken: string
|
|
refreshAccessToken?: () => Promise<string>
|
|
targetDeviceId: string
|
|
capabilities?: string[]
|
|
preferredTransports?: Array<'lan' | 'p2p' | 'turn' | 'relay'>
|
|
forceRelay?: boolean
|
|
/** Control authorization only, ending at connect.accepted. */
|
|
handshakeTimeoutMs?: number
|
|
negotiateTimeoutMs?: number
|
|
iceServersTimeoutMs?: number
|
|
signal?: AbortSignal
|
|
rtcFactory?: RtcPeerConnectionFactory
|
|
fetchIceServers?: (connectionId: string, signal?: AbortSignal) => Promise<RtcIceServer[]>
|
|
onWebRtcFallback?: (error: Error, diagnostics?: RtcConnectionDiagnostics) => void
|
|
onWebRtcDiagnostic?: (event: RtcDiagnosticEvent) => void
|
|
/** Payload-free diagnostics for an established carrier closing. */
|
|
onDisconnect?: (event: AdaptiveDisconnectDiagnostic) => void
|
|
}
|
|
|
|
export interface AdaptiveDisconnectDiagnostic {
|
|
reason: 'control-closed' | 'control-error' | 'invalid-control-frame' | 'webrtc-closed'
|
|
closeCode?: number
|
|
errorCode?: ErrorCode
|
|
closeReason?: string
|
|
/** Selected data-plane transport of an established WebRTC path that closed. */
|
|
transport?: 'lan' | 'p2p' | 'turn'
|
|
}
|
|
|
|
export interface AdaptiveConnectionDetails {
|
|
connectionId?: string
|
|
connectedAt?: number
|
|
heartbeatIntervalMs?: number
|
|
lastControlReceivedAt?: number
|
|
lastControlSentAt?: number
|
|
recoveryExpiresAt?: number
|
|
controlChannelUrl: string
|
|
controlChannelState: 'connecting' | 'open' | 'closing' | 'closed'
|
|
preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'>
|
|
negotiatedCapabilities: string[]
|
|
webRtcEnabled: boolean
|
|
webRtc?: RtcConnectionDetails
|
|
}
|
|
|
|
const DEFAULT_CAPABILITIES = [WEBRTC_RESUME_CAPABILITY, RELAY_RESUME_CAPABILITY, 'transport.lan', 'transport.p2p', 'transport.turn', 'transport.relay', 'transport.relay.attach', 'harness.api.v1']
|
|
const DEFAULT_PREFERRED_TRANSPORTS = ['lan', 'p2p', 'turn', 'relay'] as const
|
|
|
|
/**
|
|
* Client-side adaptive transport: `p2p -> turn -> relay` (webrtc plan §4/§6.4).
|
|
*
|
|
* Owns the Server control WebSocket and negotiates the data plane after
|
|
* `connect.accepted`. WebRTC (initiator) is attempted first unless
|
|
* `forceRelay` is set or no RTC backend is available; every failure path
|
|
* closes the RTC state and falls back to the WebSocket Relay data plane.
|
|
* Noise IK always runs over `secure.handshake` control frames; only the Noise
|
|
* ciphertext moves to the DataChannel once WebRTC is established.
|
|
*/
|
|
export class AdaptiveTransport extends BaseTransport {
|
|
private readonly handshakeHandlers = new Set<(step: number, data: Uint8Array) => void>()
|
|
private socket?: WebSocket
|
|
private dataSocket?: WebSocket
|
|
private connectionId?: string
|
|
private relayCounter = 0
|
|
private bytesSent = 0
|
|
private bytesReceived = 0
|
|
private dataMode: 'relay' | 'webrtc' = 'relay'
|
|
private selected?: SelectedTransport
|
|
private rtc?: RtcDataChannelTransport
|
|
private readyResolve?: () => void
|
|
private readyReject?: (error: Error) => void
|
|
private handshakeTimer?: ReturnType<typeof setTimeout>
|
|
private lifetime?: AbortController
|
|
private removeAbort?: () => void
|
|
private webrtcEnabled = true
|
|
private serverNegotiateTimeoutMs?: number
|
|
private negotiatedCapabilities: string[] = ['transport.relay']
|
|
private controlFrameLimits: ControlFrameByteLimits = {}
|
|
private connectedAt?: number
|
|
private heartbeatIntervalMs?: number
|
|
private lastControlReceivedAt?: number
|
|
private lastControlSentAt?: number
|
|
private lastRtcDiagnostics?: RtcConnectionDiagnostics
|
|
private relayAssignment?: RelayAssignment
|
|
private dataReady = false
|
|
private recoveryTicket?: string
|
|
private relayRecoveryTicket?: string
|
|
private lease?: ControlLease
|
|
private recoveryTimer?: ReturnType<typeof setTimeout>
|
|
private recoveryOpeningTimer?: ReturnType<typeof setTimeout>
|
|
private recoveryAttempt = 0
|
|
private controlReady = false
|
|
|
|
constructor(
|
|
private readonly url: string,
|
|
private readonly options: AdaptiveTransportOptions,
|
|
) {
|
|
super()
|
|
}
|
|
|
|
async connect(): Promise<void> {
|
|
if (this.socket !== undefined || this.connectedAt !== undefined) return
|
|
throwIfAborted(this.options.signal)
|
|
const lifetime = new AbortController()
|
|
this.lifetime = lifetime
|
|
this.webrtcEnabled = true
|
|
this.serverNegotiateTimeoutMs = undefined
|
|
this.dataMode = 'relay'
|
|
this.selected = undefined
|
|
this.connectedAt = undefined
|
|
this.relayCounter = 0
|
|
this.socket = new WebSocket(this.url)
|
|
this.controlFrameLimits = {}
|
|
this.socket.binaryType = 'arraybuffer'
|
|
await new Promise<void>((resolve, reject) => {
|
|
this.readyResolve = resolve
|
|
this.readyReject = reject
|
|
const onAbort = () => this.failConnection(new Error('Adaptive connection was aborted'))
|
|
this.options.signal?.addEventListener('abort', onAbort, { once: true })
|
|
this.removeAbort = () => this.options.signal?.removeEventListener('abort', onAbort)
|
|
this.handshakeTimer = setTimeout(
|
|
() => this.failConnection(new Error('Adaptive control handshake timed out')),
|
|
this.options.handshakeTimeoutMs ?? 15_000,
|
|
)
|
|
const socket = this.socket!
|
|
socket.onmessage = event => { if (this.socket === socket) void this.handleSocketMessage(event.data, lifetime) }
|
|
socket.onopen = () => {
|
|
if (this.lifetime !== lifetime) return
|
|
this.sendControl('hello', {
|
|
role: this.options.role,
|
|
deviceId: this.options.deviceId,
|
|
accessToken: this.options.accessToken,
|
|
protocols: [PROTOCOL_VERSION],
|
|
capabilities: this.options.capabilities ?? DEFAULT_CAPABILITIES,
|
|
})
|
|
}
|
|
socket.onerror = () => {
|
|
if (this.lifetime === lifetime && this.socket === socket) this.controlLost(new Error('Control socket failed'), { reason: 'control-error' })
|
|
}
|
|
socket.onclose = event => {
|
|
if (this.lifetime === lifetime && this.socket === socket) this.controlLost(adaptiveControlCloseError(event), { reason: 'control-closed', closeCode: event.code, closeReason: event.reason })
|
|
}
|
|
})
|
|
}
|
|
|
|
async send(data: Uint8Array): Promise<void> {
|
|
if (this.lease && !this.lease.valid()) throw new Error('Control lease expired')
|
|
if (this.connectionId === undefined) throw new Error('adaptive transport has not been authorized')
|
|
if (this.dataMode === 'webrtc') {
|
|
const rtc = this.rtc
|
|
if (rtc === undefined) throw new Error('webrtc data channel is not available')
|
|
this.bytesSent += data.byteLength
|
|
await rtc.send(data)
|
|
return
|
|
}
|
|
const socket = this.dataSocket ?? this.socket
|
|
if (socket?.readyState !== WebSocket.OPEN) throw new Error('adaptive transport is not connected')
|
|
await waitForRelayCapacity(socket)
|
|
const payload = {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
counter: this.relayCounter,
|
|
ciphertext: toBase64Url(data),
|
|
} satisfies RelayPayload
|
|
if (this.dataSocket !== undefined) {
|
|
this.dataSocket.send(encodeRelayDataFrame(createRelayDataFrame('relay', payload), this.controlFrameLimits))
|
|
}
|
|
else this.sendControl('relay', payload)
|
|
this.bytesSent += data.byteLength
|
|
this.relayCounter += 1
|
|
}
|
|
|
|
connectionInfo(): { connectionId: string; localDeviceId: string; remoteDeviceId: string } {
|
|
if (this.connectionId === undefined) throw new Error('adaptive transport has not been authorized')
|
|
return {
|
|
connectionId: this.connectionId,
|
|
localDeviceId: this.options.deviceId,
|
|
remoteDeviceId: this.options.targetDeviceId,
|
|
}
|
|
}
|
|
|
|
async connectionDetails(): Promise<AdaptiveConnectionDetails> {
|
|
const remainingMs = this.lease?.remainingMs()
|
|
return {
|
|
...(this.connectionId === undefined ? {} : { connectionId: this.connectionId }),
|
|
...(this.connectedAt === undefined ? {} : { connectedAt: this.connectedAt }),
|
|
...(this.heartbeatIntervalMs === undefined ? {} : { heartbeatIntervalMs: this.heartbeatIntervalMs }),
|
|
...(this.lastControlReceivedAt === undefined ? {} : { lastControlReceivedAt: this.lastControlReceivedAt }),
|
|
...(this.lastControlSentAt === undefined ? {} : { lastControlSentAt: this.lastControlSentAt }),
|
|
recoveryExpiresAt: remainingMs === undefined ? undefined : Date.now() + remainingMs,
|
|
controlChannelUrl: this.url,
|
|
controlChannelState: socketState(this.socket?.readyState),
|
|
preferredTransports: this.options.forceRelay === true
|
|
? ['relay']
|
|
: [...(this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS)],
|
|
negotiatedCapabilities: [...this.negotiatedCapabilities],
|
|
webRtcEnabled: this.webrtcEnabled,
|
|
...(this.rtc === undefined ? {} : { webRtc: await this.rtc.connectionDetails() }),
|
|
}
|
|
}
|
|
|
|
async sendHandshake(step: number, data: Uint8Array): Promise<void> {
|
|
if (this.socket?.readyState !== WebSocket.OPEN || this.connectionId === undefined) {
|
|
throw new Error('adaptive transport has not been authorized')
|
|
}
|
|
this.sendControl('secure.handshake', {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
step,
|
|
data: toBase64Url(data),
|
|
} satisfies SecureHandshakePayload)
|
|
}
|
|
|
|
onHandshake(cb: (step: number, data: Uint8Array) => void): () => void {
|
|
this.handshakeHandlers.add(cb)
|
|
return () => this.handshakeHandlers.delete(cb)
|
|
}
|
|
|
|
async close(): Promise<void> {
|
|
this.failConnection(new Error('Adaptive transport closed'))
|
|
}
|
|
|
|
getStats(): TransportStats {
|
|
const webrtcConnected = this.dataMode === 'webrtc' && this.rtc?.getStats().connected === true
|
|
const relayConnected = this.dataMode === 'relay'
|
|
&& (this.dataSocket?.readyState === WebSocket.OPEN && this.dataReady || this.socket?.readyState === WebSocket.OPEN)
|
|
&& this.connectionId !== undefined
|
|
const connected = webrtcConnected || relayConnected
|
|
let mode: TransportStats['mode'] = 'Disconnected'
|
|
if (this.selected === 'relay') mode = relayConnected ? 'Relay' : 'Disconnected'
|
|
else if (this.selected === 'lan' || this.selected === 'turn' || this.selected === 'p2p') {
|
|
mode = webrtcConnected ? this.rtc!.getStats().mode : 'Disconnected'
|
|
}
|
|
return { mode, connected, bytesSent: this.bytesSent, bytesReceived: this.bytesReceived }
|
|
}
|
|
|
|
private async handleSocketMessage(raw: string | ArrayBuffer | Blob, lifetime: AbortController): Promise<void> {
|
|
if (this.lifetime !== lifetime) return
|
|
try {
|
|
if (typeof raw !== 'string') throw new Error('Adaptive control frames must be text JSON')
|
|
const frame = decodeControlFrame(raw, this.controlFrameLimits)
|
|
this.lastControlReceivedAt = Date.now()
|
|
if (frame.type === 'hello.ack') {
|
|
this.controlReady = true
|
|
const payload = frame.payload as Partial<HelloAckPayload>
|
|
if (payload.protocol !== PROTOCOL_VERSION) throw new Error('Server selected an unsupported protocol version')
|
|
this.heartbeatIntervalMs = payload.heartbeatIntervalMs
|
|
const offered = this.options.capabilities ?? DEFAULT_CAPABILITIES
|
|
this.negotiatedCapabilities = acceptNegotiatedCapabilities(offered, payload.capabilities)
|
|
this.controlFrameLimits = {
|
|
maxControlFrameBytes: payload.maxControlFrameBytes,
|
|
maxRelayFrameBytes: payload.maxRelayFrameBytes,
|
|
}
|
|
const preferredTransports = this.negotiatedTransports()
|
|
if (preferredTransports.length === 0) {
|
|
throw new Error('Server did not negotiate a supported transport capability')
|
|
}
|
|
if (payload.webrtcEnabled === false) this.webrtcEnabled = false
|
|
if (typeof payload.webrtcFallbackTimeoutMs === 'number'
|
|
&& Number.isSafeInteger(payload.webrtcFallbackTimeoutMs)
|
|
&& payload.webrtcFallbackTimeoutMs > 0) {
|
|
this.serverNegotiateTimeoutMs = payload.webrtcFallbackTimeoutMs
|
|
}
|
|
if (this.lease) {
|
|
if (!this.negotiatedCapabilities.includes(this.dataMode === 'webrtc' ? WEBRTC_RESUME_CAPABILITY : RELAY_RESUME_CAPABILITY)) throw new Error('Server no longer supports control recovery')
|
|
clearTimeout(this.recoveryOpeningTimer)
|
|
this.recoveryAttempt = 0
|
|
this.lease.tick(true)
|
|
return
|
|
}
|
|
this.sendControl('connect.request', {
|
|
hostDeviceId: this.options.targetDeviceId,
|
|
preferredTransports,
|
|
})
|
|
return
|
|
}
|
|
if (frame.type === 'connect.accepted') {
|
|
if (this.connectionId !== undefined) throw new Error('Duplicate connect.accepted')
|
|
const payload = frame.payload as Partial<ConnectAcceptedPayload>
|
|
if (typeof payload.connectionId !== 'string' || payload.connectionId.length === 0) {
|
|
throw new Error('connect.accepted did not include a connectionId')
|
|
}
|
|
this.connectionId = payload.connectionId
|
|
if (this.negotiatedCapabilities.includes(WEBRTC_RESUME_CAPABILITY)) this.recoveryTicket = payload.recoveryTicket
|
|
if (this.negotiatedCapabilities.includes(RELAY_RESUME_CAPABILITY)) this.relayRecoveryTicket = payload.relayRecoveryTicket
|
|
const assignment = payload as RelayAssignment
|
|
if (typeof assignment.relayEndpoint === 'string' && typeof assignment.relayTicket === 'string') {
|
|
this.relayAssignment = assignment
|
|
}
|
|
this.clearHandshake()
|
|
void this.negotiate(lifetime.signal).catch(error => {
|
|
if (this.lifetime === lifetime) this.failConnection(error instanceof Error ? error : new Error('Adaptive transport negotiation failed'))
|
|
})
|
|
return
|
|
}
|
|
if (frame.type === 'connection.lease.ack') {
|
|
if (!this.lease) throw new Error('Unexpected connection lease')
|
|
this.lease.acknowledge(frame.payload as ConnectionLeaseAck)
|
|
return
|
|
}
|
|
if (frame.type === 'connect.rejected' || frame.type === 'error') {
|
|
const payload = frame.payload as { message?: unknown; code?: unknown; retryable?: unknown }
|
|
const message = typeof payload.message === 'string' ? payload.message : 'Server rejected the connection'
|
|
const failure = Object.assign(new Error(message), { code: payload.code, retryable: payload.retryable })
|
|
const code = errorCodeSchema.safeParse(payload.code)
|
|
this.failConnection(failure, {
|
|
reason: payload.retryable === true ? 'control-error' : 'invalid-control-frame',
|
|
...(code.success ? { errorCode: code.data } : {}),
|
|
})
|
|
return
|
|
}
|
|
if (frame.type === 'relay') {
|
|
if (this.dataSocket !== undefined) return
|
|
if (this.dataMode !== 'relay') return
|
|
this.handleRelay(frame.payload as Partial<RelayPayload>)
|
|
return
|
|
}
|
|
if (frame.type === 'secure.handshake') {
|
|
const payload = frame.payload as Partial<SecureHandshakePayload>
|
|
if (payload.connectionId !== this.connectionId
|
|
|| payload.targetDeviceId !== this.options.deviceId
|
|
|| !Number.isSafeInteger(payload.step)
|
|
|| typeof payload.data !== 'string') {
|
|
throw new Error('Received a secure handshake frame for an unknown connection')
|
|
}
|
|
const data = fromBase64Url(payload.data)
|
|
for (const handler of this.handshakeHandlers) handler(payload.step!, data)
|
|
return
|
|
}
|
|
if (frame.type === 'signal.answer') {
|
|
const payload = frame.payload as { connectionId?: unknown; targetDeviceId?: unknown; sdp?: unknown }
|
|
if (payload.connectionId === this.connectionId && typeof payload.sdp === 'string') {
|
|
this.rtc?.handleSignal({ type: 'answer', sdp: payload.sdp })
|
|
}
|
|
return
|
|
}
|
|
if (frame.type === 'signal.ice') {
|
|
const payload = frame.payload as { connectionId?: unknown; candidate?: unknown }
|
|
if (payload.connectionId === this.connectionId && isObject(payload.candidate)) {
|
|
this.rtc?.handleSignal({ type: 'ice', candidate: payload.candidate })
|
|
}
|
|
return
|
|
}
|
|
if (frame.type === 'signal.offer' || frame.type === 'transport.selected') return
|
|
if (frame.type === 'ping') this.sendControl('pong', frame.payload)
|
|
} catch (error) {
|
|
const failure = error instanceof Error ? error : new Error('Invalid adaptive control frame')
|
|
if (!('code' in failure)) Object.assign(failure, { code: 'INVALID_MESSAGE' })
|
|
const code = errorCodeSchema.safeParse((failure as Error & { code?: unknown }).code)
|
|
this.failConnection(failure, { reason: 'invalid-control-frame', ...(code.success ? { errorCode: code.data } : {}) })
|
|
}
|
|
}
|
|
|
|
private handleRelay(payload: Partial<RelayPayload>): void {
|
|
if (payload.connectionId !== this.connectionId
|
|
|| payload.targetDeviceId !== this.options.deviceId
|
|
|| !Number.isSafeInteger(payload.counter)
|
|
|| typeof payload.ciphertext !== 'string') {
|
|
throw new Error('Received a relay frame for an unknown connection')
|
|
}
|
|
const data = fromBase64Url(payload.ciphertext)
|
|
this.bytesReceived += data.byteLength
|
|
this.emit(data)
|
|
}
|
|
|
|
private async negotiate(signal: AbortSignal): Promise<void> {
|
|
if (this.connectionId === undefined) return
|
|
const preferred = this.negotiatedTransports()
|
|
const wantWebRtc = !this.options.forceRelay && this.webrtcEnabled
|
|
&& (preferred.includes('lan') || preferred.includes('p2p') || preferred.includes('turn'))
|
|
let selected: SelectedTransport = 'relay'
|
|
this.lastRtcDiagnostics = undefined
|
|
if (wantWebRtc) {
|
|
try {
|
|
const rtcSelected = (await this.tryWebRtc(signal)).transport
|
|
throwIfAborted(signal)
|
|
const wireSelected = rtcSelected === 'lan' && !preferred.includes('lan') && preferred.includes('p2p')
|
|
? 'p2p'
|
|
: rtcSelected
|
|
if (!preferred.includes(wireSelected)) {
|
|
await this.rtc?.close()
|
|
throwIfAborted(signal)
|
|
this.rtc = undefined
|
|
if (!preferred.includes('relay')) {
|
|
throw new Error(`WebRTC selected unnegotiated transport: ${rtcSelected}`)
|
|
}
|
|
this.dataMode = 'relay'
|
|
selected = 'relay'
|
|
} else {
|
|
this.dataMode = 'webrtc'
|
|
selected = wireSelected
|
|
}
|
|
} catch (error) {
|
|
throwIfAborted(signal)
|
|
const reason = error instanceof Error ? error : new Error('WebRTC negotiation failed.')
|
|
try { this.options.onWebRtcFallback?.(reason, this.lastRtcDiagnostics) } catch { /* diagnostics must not block fallback */ }
|
|
await this.rtc?.close()
|
|
throwIfAborted(signal)
|
|
this.rtc = undefined
|
|
if (!preferred.includes('relay')) throw reason
|
|
this.dataMode = 'relay'
|
|
selected = 'relay'
|
|
}
|
|
} else {
|
|
if (!preferred.includes('relay')) throw new Error('No negotiated transport is available')
|
|
this.dataMode = 'relay'
|
|
selected = 'relay'
|
|
}
|
|
this.selected = selected
|
|
if (selected === 'relay' && this.relayAssignment !== undefined) {
|
|
await this.openDataSocket(this.relayAssignment)
|
|
}
|
|
const turnNode = selected === 'turn' ? this.rtc?.selectedRelayUrl() : undefined
|
|
this.sendControl('transport.selected', {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
transport: selected,
|
|
...(turnNode === undefined ? {} : { turnNode }),
|
|
} satisfies TransportSelectedPayload)
|
|
this.finishConnection()
|
|
}
|
|
|
|
private negotiatedTransports(): Array<'lan' | 'p2p' | 'turn' | 'relay'> {
|
|
const preferred = this.options.forceRelay === true
|
|
? ['relay'] as const
|
|
: this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS
|
|
return preferred.filter(transport => {
|
|
if (transport === 'lan') return this.negotiatedCapabilities.includes('transport.lan')
|
|
if (transport === 'p2p') return this.negotiatedCapabilities.includes('transport.p2p')
|
|
return this.negotiatedCapabilities.includes(`transport.${transport}`)
|
|
})
|
|
}
|
|
|
|
private async tryWebRtc(signal: AbortSignal): Promise<{ transport: RtcSelectedTransport, relayUrl?: string }> {
|
|
const connectionId = this.connectionId
|
|
if (connectionId === undefined) throw new RtcConnectError('RTC_UNAVAILABLE', 'No connection id for WebRTC negotiation.')
|
|
const factory = this.options.rtcFactory
|
|
?? (typeof RTCPeerConnection === 'undefined' ? undefined : browserRtcFactory())
|
|
if (factory === undefined) {
|
|
throw new RtcConnectError('RTC_UNAVAILABLE', 'No RTC backend is available in this environment.')
|
|
}
|
|
let iceServers: RtcIceServer[] = []
|
|
try {
|
|
iceServers = await this.fetchIceServers(connectionId, signal)
|
|
} catch {
|
|
// TURN/STUN unavailable: still attempt direct P2P with host candidates.
|
|
iceServers = []
|
|
}
|
|
throwIfAborted(signal)
|
|
const negotiatedMs = negotiateTimeout(this.serverNegotiateTimeoutMs, this.options.negotiateTimeoutMs)
|
|
// Without STUN/TURN servers only same-LAN host candidates can succeed;
|
|
// fail fast instead of waiting the full timeout on cross-network links.
|
|
const effectiveNegotiateTimeoutMs = iceServers.length === 0
|
|
? Math.min(negotiatedMs ?? DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS, DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS)
|
|
: negotiatedMs
|
|
const rtc = new RtcDataChannelTransport({
|
|
role: 'initiator',
|
|
factory,
|
|
iceServers,
|
|
// A TURN-only attempt must constrain ICE itself. Otherwise a faster
|
|
// direct pair wins, then gets rejected as an unnegotiated transport.
|
|
iceTransportPolicy: this.negotiatedTransports().includes('turn')
|
|
&& !this.negotiatedTransports().some(transport => transport === 'lan' || transport === 'p2p')
|
|
? 'relay'
|
|
: 'all',
|
|
onSignal: signal => this.sendRtcSignal(signal),
|
|
negotiateTimeoutMs: effectiveNegotiateTimeoutMs,
|
|
label: `client->${this.options.targetDeviceId}`,
|
|
onDiagnostic: event => {
|
|
this.lastRtcDiagnostics = event.diagnostics
|
|
try { this.options.onWebRtcDiagnostic?.(event) } catch { /* diagnostics must not block negotiation */ }
|
|
},
|
|
})
|
|
this.rtc = rtc
|
|
rtc.onMessage(data => {
|
|
if (this.lease && !this.lease.valid()) return
|
|
this.bytesReceived += data.byteLength
|
|
this.emit(data)
|
|
})
|
|
rtc.onClose(() => {
|
|
// A negotiation failure closes the provisional data channel before this
|
|
// transport switches to Relay. That is not a loss of the established
|
|
// Adaptive transport, so only surface closes from an active WebRTC path.
|
|
if (this.rtc === rtc && this.dataMode === 'webrtc') {
|
|
const transport = this.selected
|
|
this.failConnection(new Error('Active WebRTC channel closed'), {
|
|
reason: 'webrtc-closed',
|
|
...(transport === 'lan' || transport === 'p2p' || transport === 'turn' ? { transport } : {}),
|
|
})
|
|
}
|
|
})
|
|
try {
|
|
await rtc.connect(signal)
|
|
} catch (error) {
|
|
throwIfAborted(signal)
|
|
this.lastRtcDiagnostics = rtc.diagnostics()
|
|
await rtc.close()
|
|
if (this.rtc === rtc) this.rtc = undefined
|
|
throwIfAborted(signal)
|
|
throw error
|
|
}
|
|
throwIfAborted(signal)
|
|
this.lastRtcDiagnostics = rtc.diagnostics()
|
|
return { transport: rtc.selectedTransport() ?? 'p2p', relayUrl: rtc.selectedRelayUrl() }
|
|
}
|
|
|
|
markSecureReady(): void {
|
|
const ticket = this.dataMode === 'webrtc' ? this.recoveryTicket : this.dataReady && this.dataSocket?.readyState === WebSocket.OPEN ? this.relayRecoveryTicket : undefined
|
|
if (!ticket || !this.connectionId || this.lease) return
|
|
this.lease = new ControlLease(this.connectionId, ticket, payload => {
|
|
if (this.controlReady && this.lastControlReceivedAt !== undefined && Date.now() - this.lastControlReceivedAt >= 75_000) {
|
|
this.controlLost(new Error('Control heartbeat timed out'), { reason: 'control-error' })
|
|
throw new Error('Control heartbeat timed out')
|
|
}
|
|
this.sendControl('connection.lease.request', payload)
|
|
}, () => this.failConnection(Object.assign(new Error('Control authorization lease expired'), { code: 'TRANSPORT_CLOSED', retryable: true })))
|
|
this.lease.start()
|
|
}
|
|
|
|
private controlLost(error: Error, diagnostic: AdaptiveDisconnectDiagnostic): void {
|
|
if ((error as Error & { retryable?: boolean }).retryable === false || !this.lease?.canDetach()
|
|
|| !(this.dataMode === 'webrtc' ? this.rtc?.getStats().connected : this.dataReady && this.dataSocket?.readyState === WebSocket.OPEN)) {
|
|
this.failConnection(error, diagnostic)
|
|
return
|
|
}
|
|
const socket = this.socket
|
|
this.controlReady = false
|
|
this.socket = undefined
|
|
clearTimeout(this.recoveryOpeningTimer)
|
|
socket?.close()
|
|
if (this.recoveryTimer !== undefined) return
|
|
const delay = recoveryDelayMs(this.recoveryAttempt, diagnostic)
|
|
this.recoveryAttempt++
|
|
this.recoveryTimer = setTimeout(() => {
|
|
this.recoveryTimer = undefined
|
|
void this.reopenControl()
|
|
}, delay)
|
|
}
|
|
|
|
private async reopenControl(): Promise<void> {
|
|
const lifetime = this.lifetime
|
|
if (!lifetime || !this.lease?.canDetach()) return
|
|
try {
|
|
const token = this.options.refreshAccessToken ? await this.options.refreshAccessToken() : this.options.accessToken
|
|
if (this.lifetime !== lifetime || !this.lease?.canDetach()) return
|
|
const socket = new WebSocket(this.url)
|
|
this.socket = socket
|
|
socket.binaryType = 'arraybuffer'
|
|
this.recoveryOpeningTimer = setTimeout(() => {
|
|
if (this.socket === socket) this.controlLost(new Error('Control recovery handshake timed out'), { reason: 'control-error' })
|
|
}, 15_000)
|
|
socket.onopen = () => {
|
|
if (this.socket !== socket || this.lifetime !== lifetime) return
|
|
this.sendControl('hello', { role: this.options.role, deviceId: this.options.deviceId,
|
|
accessToken: token, protocols: [PROTOCOL_VERSION], capabilities: this.options.capabilities ?? DEFAULT_CAPABILITIES })
|
|
}
|
|
socket.onmessage = event => {
|
|
if (this.socket === socket && this.lifetime === lifetime) void this.handleSocketMessage(event.data, lifetime)
|
|
}
|
|
socket.onerror = () => {
|
|
if (this.socket === socket) this.controlLost(new Error('Control recovery failed'), { reason: 'control-error' })
|
|
}
|
|
socket.onclose = event => {
|
|
if (this.socket === socket) this.controlLost(adaptiveControlCloseError(event), { reason: 'control-closed', closeCode: event.code, closeReason: event.reason })
|
|
}
|
|
} catch (error) {
|
|
if (this.lifetime !== lifetime) return
|
|
if (typeof error === 'object' && error && (('retryable' in error && error.retryable === false)
|
|
|| ('code' in error && ['AUTH_INVALID', 'DEVICE_REVOKED', 'MEMBERSHIP_REQUIRED', 'PEER_IDENTITY_MISMATCH', 'DEVICE_NOT_FOUND', 'TOKEN_REUSED'].includes(String(error.code))))) {
|
|
this.failConnection(error instanceof Error ? error : new Error('Control recovery authorization failed'))
|
|
} else this.controlLost(new Error('Control recovery unavailable'), { reason: 'control-error' })
|
|
}
|
|
}
|
|
|
|
private async fetchIceServers(connectionId: string, signal: AbortSignal): Promise<RtcIceServer[]> {
|
|
if (this.options.fetchIceServers === undefined) return []
|
|
return new Promise<RtcIceServer[]>((resolve, reject) => {
|
|
const request = new AbortController()
|
|
let settled = false
|
|
const finish = (error?: Error, servers: RtcIceServer[] = []) => {
|
|
if (settled) return
|
|
settled = true
|
|
clearTimeout(timer)
|
|
signal.removeEventListener('abort', onAbort)
|
|
if (error) reject(error)
|
|
else resolve(servers)
|
|
}
|
|
const onAbort = () => {
|
|
finish(new Error('ICE configuration request was aborted'))
|
|
request.abort()
|
|
}
|
|
const timer = setTimeout(() => {
|
|
finish(new Error('ICE configuration request timed out'))
|
|
request.abort()
|
|
}, this.options.iceServersTimeoutMs ?? 10_000)
|
|
signal.addEventListener('abort', onAbort, { once: true })
|
|
if (signal.aborted) { onAbort(); return }
|
|
Promise.resolve().then(() => {
|
|
throwIfAborted(request.signal)
|
|
return this.options.fetchIceServers!(connectionId, request.signal)
|
|
}).then(
|
|
servers => finish(undefined, servers),
|
|
error => finish(error instanceof Error ? error : new Error('ICE configuration request failed')),
|
|
)
|
|
})
|
|
}
|
|
|
|
private sendRtcSignal(signal: RtcSignal): void {
|
|
if (this.connectionId === undefined) return
|
|
if (signal.type === 'offer') {
|
|
this.sendControl('signal.offer', {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
sdp: signal.sdp,
|
|
})
|
|
} else if (signal.type === 'answer') {
|
|
this.sendControl('signal.answer', {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
sdp: signal.sdp,
|
|
})
|
|
} else {
|
|
this.sendControl('signal.ice', {
|
|
connectionId: this.connectionId,
|
|
targetDeviceId: this.options.targetDeviceId,
|
|
candidate: signal.candidate,
|
|
})
|
|
}
|
|
}
|
|
|
|
private async openDataSocket(assignment: RelayAssignment): Promise<void> {
|
|
if (this.connectionId === undefined || this.dataSocket !== undefined) return
|
|
const socket = new WebSocket(assignment.relayEndpoint!)
|
|
socket.binaryType = 'arraybuffer'
|
|
this.dataSocket = socket
|
|
await new Promise<void>((resolve, reject) => {
|
|
const timer = setTimeout(() => {
|
|
reject(new Error('Relay data attach timed out'))
|
|
socket.close()
|
|
}, this.options.handshakeTimeoutMs ?? 15_000)
|
|
socket.onopen = () => socket.send(encodeRelayDataFrame(createRelayDataFrame('relay.attach', {
|
|
connectionId: this.connectionId,
|
|
deviceId: this.options.deviceId,
|
|
peerDeviceId: this.options.targetDeviceId,
|
|
ticket: assignment.relayTicket,
|
|
}), this.controlFrameLimits))
|
|
socket.onmessage = event => {
|
|
try {
|
|
if (typeof event.data !== 'string') throw new Error('Relay data frames must be text JSON')
|
|
const data = decodeRelayDataFrame(event.data, this.controlFrameLimits)
|
|
if (data.type === 'relay.ready') {
|
|
if (data.payload.connectionId !== this.connectionId
|
|
|| (assignment.relayEpoch !== undefined && data.payload.epoch !== assignment.relayEpoch)) {
|
|
throw new Error('Relay data attach assignment mismatch')
|
|
}
|
|
clearTimeout(timer)
|
|
this.dataReady = true
|
|
resolve()
|
|
return
|
|
}
|
|
void this.handleDataSocketFrame(data.type, data.payload).catch(error => {
|
|
this.failConnection(error instanceof Error ? error : new Error('Invalid Relay data frame'))
|
|
})
|
|
} catch (error) {
|
|
clearTimeout(timer)
|
|
reject(error instanceof Error ? error : new Error('Invalid Relay data frame'))
|
|
this.failConnection(error instanceof Error ? error : new Error('Invalid Relay data frame'))
|
|
}
|
|
}
|
|
socket.onerror = () => {
|
|
clearTimeout(timer)
|
|
reject(new Error('Relay data socket failed'))
|
|
}
|
|
socket.onclose = () => {
|
|
clearTimeout(timer)
|
|
if (!this.dataReady) reject(new Error('Relay data socket closed before attach'))
|
|
else this.failConnection(new Error('Relay data socket closed'))
|
|
}
|
|
})
|
|
}
|
|
|
|
private async handleDataSocketFrame(type: string, payload: Record<string, unknown>): Promise<void> {
|
|
if (type === 'relay.detach') {
|
|
this.failConnection(new Error('Relay peer detached'))
|
|
return
|
|
}
|
|
if (type === 'ping') {
|
|
if (this.dataSocket?.readyState === WebSocket.OPEN) {
|
|
this.dataSocket.send(encodeRelayDataFrame(createRelayDataFrame('pong', payload), this.controlFrameLimits))
|
|
}
|
|
return
|
|
}
|
|
if (type === 'relay') {
|
|
if (payload.connectionId !== this.connectionId || payload.targetDeviceId !== this.options.deviceId
|
|
|| !Number.isSafeInteger(payload.counter) || typeof payload.ciphertext !== 'string') {
|
|
throw new Error('Received a relay frame for an unknown connection')
|
|
}
|
|
const data = fromBase64Url(payload.ciphertext)
|
|
this.bytesReceived += data.byteLength
|
|
this.emit(data)
|
|
return
|
|
}
|
|
if (type === 'secure.handshake') {
|
|
if (payload.connectionId !== this.connectionId || payload.targetDeviceId !== this.options.deviceId
|
|
|| !Number.isSafeInteger(payload.step) || typeof payload.data !== 'string') {
|
|
throw new Error('Received a secure handshake frame for an unknown connection')
|
|
}
|
|
const data = fromBase64Url(payload.data)
|
|
for (const handler of this.handshakeHandlers) handler(payload.step as number, data)
|
|
}
|
|
}
|
|
|
|
private sendControl(type: Parameters<typeof createControlFrame>[0], payload: unknown): void {
|
|
if (this.socket?.readyState !== WebSocket.OPEN) throw Object.assign(new Error('adaptive control socket is not open'), { code: 'TRANSPORT_CLOSED' })
|
|
this.socket.send(encodeControlFrame(createControlFrame(type, payload), this.controlFrameLimits))
|
|
this.lastControlSentAt = Date.now()
|
|
}
|
|
|
|
private finishConnection(): void {
|
|
this.clearHandshake()
|
|
this.removeAbort?.()
|
|
this.removeAbort = undefined
|
|
this.connectedAt ??= Date.now()
|
|
this.readyResolve?.()
|
|
this.readyResolve = undefined
|
|
this.readyReject = undefined
|
|
}
|
|
|
|
private failConnection(error: Error, diagnostic?: AdaptiveDisconnectDiagnostic): void {
|
|
if (this.lease && this.connectionId && this.socket?.readyState === WebSocket.OPEN) {
|
|
try { this.sendControl('connection.lease.close', { connectionId: this.connectionId }) } catch { /* local cleanup proceeds */ }
|
|
}
|
|
const established = this.connectedAt !== undefined
|
|
this.controlReady = false
|
|
// Start every new connection lifetime from a fresh backoff sequence; the
|
|
// counter is reset on a successful recovery hello too, but a terminal
|
|
// failure here must not inherit (or leak) a previous lifetime's attempt
|
|
// count when the transport is reused.
|
|
this.recoveryAttempt = 0
|
|
this.lease?.stop()
|
|
this.lease = undefined
|
|
this.recoveryTicket = undefined
|
|
this.relayRecoveryTicket = undefined
|
|
clearTimeout(this.recoveryTimer)
|
|
clearTimeout(this.recoveryOpeningTimer)
|
|
this.recoveryTimer = undefined
|
|
this.clearHandshake()
|
|
const reject = this.readyReject
|
|
this.readyResolve = undefined
|
|
this.readyReject = undefined
|
|
this.removeAbort?.()
|
|
this.removeAbort = undefined
|
|
const lifetime = this.lifetime
|
|
this.lifetime = undefined
|
|
const rtc = this.rtc
|
|
const socket = this.socket
|
|
const dataSocket = this.dataSocket
|
|
this.rtc = undefined
|
|
this.socket = undefined
|
|
this.dataSocket = undefined
|
|
this.dataReady = false
|
|
this.relayAssignment = undefined
|
|
this.connectionId = undefined
|
|
this.connectedAt = undefined
|
|
lifetime?.abort()
|
|
reject?.(error)
|
|
void rtc?.close()
|
|
dataSocket?.close()
|
|
socket?.close()
|
|
if (established && diagnostic !== undefined) {
|
|
try { this.options.onDisconnect?.(diagnostic) } catch { /* diagnostics must not prevent close */ }
|
|
}
|
|
if (socket !== undefined || established) this.emitClose(error)
|
|
}
|
|
|
|
private clearHandshake(): void {
|
|
if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer)
|
|
this.handshakeTimer = undefined
|
|
}
|
|
}
|
|
|
|
function adaptiveControlCloseError(event: CloseEvent): Error {
|
|
// Close semantics live in @dsh-remote/protocol: the reason string is the
|
|
// semantic key because deployments disagree on the code (self-hosted Server
|
|
// sends 4009/'server shutdown', the hosted Server closes with
|
|
// 4001/'server shutdown' and reserves 4009 for heartbeat expiry). Only an
|
|
// expected Server outage, a peer heartbeat expiry or a documented transient
|
|
// code is retryable; authorization, replacement, protocol and unknown
|
|
// application codes stay terminal, exactly as before this change.
|
|
const serverShutdown = isServerShutdownClose(event.code, event.reason)
|
|
const heartbeatTimeout = isHeartbeatTimeoutClose(event.code, event.reason)
|
|
const reason = event.reason.trim().slice(0, 300)
|
|
const detail = reason.length > 0
|
|
? `${reason} (WebSocket ${event.code})`
|
|
: `WebSocket closed with code ${event.code}`
|
|
return Object.assign(new Error(`Adaptive control channel closed: ${detail}`), {
|
|
// Preserve the specific self-hosted authorization reasons so the Client
|
|
// runtime can surface a terminal reauthorization state instead of a generic
|
|
// transport loss (PR #285). Every other close keeps the shared semantics.
|
|
code: event.code === 4003 ? 'CONNECTION_REPLACED'
|
|
: event.code === 4001 && ['AUTH_INVALID', 'TOKEN_EXPIRED', 'DEVICE_REVOKED'].includes(reason)
|
|
? reason : 'TRANSPORT_CLOSED',
|
|
retryable: serverShutdown || heartbeatTimeout
|
|
|| [1000, 1001, 1006, 1011, 1012, 1013].includes(event.code),
|
|
})
|
|
}
|
|
|
|
/** Full-jitter window of every control-recovery attempt. */
|
|
export const CONTROL_RECOVERY_MAX_DELAY_MS = 15_000
|
|
|
|
/**
|
|
* Delay before the next control-recovery attempt.
|
|
*
|
|
* `attempt` is the index of the attempt *about to be scheduled*: 0 is the
|
|
* first retry after losing the control channel.
|
|
*
|
|
* Every disconnect backs off into the widest window (`[0, 15s]`, full jitter)
|
|
* and stays there: a short outage still recovers quickly on average, while a
|
|
* tight retry loop against a failing control plane is impossible. The Server
|
|
* restart reason is classified separately for session retention but no longer
|
|
* changes the delay, because a restart is already the worst case of the same
|
|
* window.
|
|
*/
|
|
export function recoveryDelayMs(_attempt: number, _diagnostic: AdaptiveDisconnectDiagnostic): number {
|
|
return Math.random() * CONTROL_RECOVERY_MAX_DELAY_MS
|
|
}
|
|
|
|
function isObject(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
}
|
|
|
|
function socketState(readyState: number | undefined): AdaptiveConnectionDetails['controlChannelState'] {
|
|
if (readyState === 0) return 'connecting'
|
|
if (readyState === 1) return 'open'
|
|
if (readyState === 2) return 'closing'
|
|
return 'closed'
|
|
}
|
|
|
|
function negotiateTimeout(serverMs: number | undefined, localMs: number | undefined): number | undefined {
|
|
// An explicit local setting wins; the server fallback hint must never be
|
|
// able to stretch a mobile client's WebRTC wait beyond its own budget.
|
|
if (localMs !== undefined) return localMs
|
|
if (serverMs === undefined) return undefined
|
|
return Math.min(SERVER_NEGOTIATE_TIMEOUT_MAX_MS, Math.max(SERVER_NEGOTIATE_TIMEOUT_MIN_MS, serverMs))
|
|
}
|
|
|
|
const DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS = 4_000
|
|
const SERVER_NEGOTIATE_TIMEOUT_MIN_MS = 6_000
|
|
const SERVER_NEGOTIATE_TIMEOUT_MAX_MS = 12_000
|
|
|
|
// React Native AbortSignal implementations may omit throwIfAborted().
|
|
function throwIfAborted(signal: AbortSignal | undefined): void {
|
|
if (signal?.aborted) throw new Error('Adaptive connection was aborted')
|
|
}
|