ds-harness-remote-fast/packages/plugin/src/client-connection.ts

254 lines
11 KiB
TypeScript

import { RemoteClientCore } from '@dsh-remote/client-core'
import type { RtcPeerConnectionFactory } from '@dsh-remote/webrtc'
import { AdaptiveTransport } from '@dsh-remote/webrtc'
import { probeRemoteHostFeatures } from './client-capabilities.js'
import type {
ConnectedRemote,
ConnectionProgressState,
TransportAttempt,
} from './client-runtime-contract.js'
import {
assertAuthorizedHost,
ClientModeError,
diagnosticReason,
DIRECT_LAN_PROGRESS_DISPLAY_MS,
DIRECT_WEBRTC_NEGOTIATE_TIMEOUT_MS,
iceServersForAttempt,
preferredTransportsForAttempt,
shortId,
transportPreferenceForMode,
webrtcDiagnosticsLogFields,
websocketUrl,
} from './client-runtime-contract.js'
import { ClientSecureTransport } from './client-secure-transport.js'
import { isForceRelayEnabled, transportAttempts } from './relay-preference.js'
import type { ResolvedConfig } from './config.js'
import type { HostIdentity, IdentityStore, TrustedPeer } from './identity-store.js'
import type { SafeLogger } from './logging.js'
import type { ServerHostDevice } from './server-api.js'
import { ClientServerApi } from './server-api.js'
import type { WeriftFactoryOptions } from './werift-rtc.js'
/** Collaborates with one ClientModeRuntime; never creates a second session or connection state. */
export interface ClientConnectionContext {
connectionProgressRun: number
connectionProgress: ConnectionProgressState | undefined
readonly requireIdentity: () => HostIdentity
readonly server: ClientServerApi
readonly config: ResolvedConfig
readonly rtcFactoryProvider: (options?: WeriftFactoryOptions) => Promise<RtcPeerConnectionFactory | undefined>
readonly logger: SafeLogger
readonly identities: IdentityStore
}
export class ClientConnection {
constructor(private readonly context: ClientConnectionContext) {}
async connect(targetDeviceId: string, signal?: AbortSignal, options: { background?: boolean } = {}): Promise<ConnectedRemote> {
signal?.throwIfAborted()
// Runtime toggle wins over the value captured when the plugin was built.
const forceRelay = isForceRelayEnabled() || this.context.config.forceRelay
const progressRunId = options.background ? -1 : this.context.connectionProgressRun + 1
if (!options.background) {
this.context.connectionProgressRun = progressRunId
this.context.connectionProgress = { runId: progressRunId, targetDeviceId, phase: 'checking-host' }
}
const identity = this.context.requireIdentity()
let client: RemoteClientCore | undefined
let closed = false
let closeError: Error | undefined
// Keep cancellation attached through capability discovery as well as the
// handshake: the candidate is not yet owned by context.connected there.
const onAbort = () => { void client?.close().catch(() => undefined) }
signal?.addEventListener('abort', onAbort, { once: true })
try {
const serverDevice = (await this.context.server.listDevices(signal)).find(device => device.deviceId === targetDeviceId)
signal?.throwIfAborted()
if (serverDevice === undefined) {
throw new ClientModeError('MEMBERSHIP_REQUIRED', 'The selected Host is not authorized for this account.')
}
this.updateConnectionProgress(progressRunId, 'authorizing-peer')
const target = await this.authorizeHostPeer(serverDevice, signal)
signal?.throwIfAborted()
const presence = await this.context.server.presenceFor(targetDeviceId, signal)
signal?.throwIfAborted()
if (!presence.online) throw new ClientModeError('HOST_OFFLINE', 'The selected Host is offline.', true)
const credentials = await this.context.server.authenticate(identity)
signal?.throwIfAborted()
const rtcFactory = forceRelay
? undefined
: await this.context.rtcFactoryProvider({ routeTargets: [this.context.server.baseUrl] }).catch(() => undefined)
if (!forceRelay && rtcFactory === undefined) {
this.context.logger.warn('remote Harness WebRTC backend unavailable; using relay', {
targetDeviceId: shortId(target.deviceId),
})
}
let webRtcFallback = false
const createTransport = (attempt: TransportAttempt): AdaptiveTransport => new AdaptiveTransport(
websocketUrl(this.context.server.baseUrl),
{
role: 'client',
deviceId: identity.deviceId,
accessToken: credentials.accessToken,
refreshAccessToken: async () => (await this.context.server.authenticate(identity)).accessToken,
targetDeviceId,
forceRelay: forceRelay || attempt === 'relay',
preferredTransports: preferredTransportsForAttempt(attempt),
negotiateTimeoutMs: attempt === 'direct' ? DIRECT_WEBRTC_NEGOTIATE_TIMEOUT_MS : undefined,
...(rtcFactory === undefined || attempt === 'relay' ? {} : { rtcFactory }),
fetchIceServers: async connectionId => iceServersForAttempt(attempt, await this.context.server.turnCredentials(connectionId)),
onWebRtcFallback: (error, diagnostics) => {
webRtcFallback = true
this.context.logger.warn(attempt === 'direct'
? 'remote Harness direct WebRTC failed; trying TURN'
: 'remote Harness TURN WebRTC failed; using relay', {
targetDeviceId: shortId(target.deviceId),
attempt,
reason: diagnosticReason(error),
})
if (diagnostics !== undefined) {
this.context.logger.debug('remote Harness WebRTC fallback diagnostics', {
targetDeviceId: shortId(target.deviceId),
attempt,
...webrtcDiagnosticsLogFields(diagnostics),
})
}
},
},
)
const attempts: TransportAttempt[] = transportAttempts(forceRelay, rtcFactory !== undefined)
let transport: AdaptiveTransport | undefined
for (const attempt of attempts) {
webRtcFallback = false
const stopProgressTimer = options.background ? () => undefined : this.beginAttemptProgress(progressRunId, attempt)
try {
transport = createTransport(attempt)
client = new RemoteClientCore(new ClientSecureTransport(transport, identity, target), 60_000)
closed = false
closeError = undefined
client.onClose(error => { closed = true; closeError = error })
const attemptClient = client
signal?.throwIfAborted()
await attemptClient.connect()
signal?.throwIfAborted()
} finally {
stopProgressTimer()
}
if (attempt === 'relay' || !webRtcFallback) break
await client.close()
client = undefined
transport = undefined
if (attempt === 'turn') {
this.context.logger.info('remote Harness relay fallback re-established', {
targetDeviceId: shortId(target.deviceId),
})
}
}
if (client === undefined || transport === undefined) {
throw new ClientModeError('CONNECTION_FAILED', 'Unable to establish a remote transport.', true)
}
const connectedClient = client
const connectedTransport = transport
const connectedPreference = transportPreferenceForMode(connectedClient.getStats().mode)
this.updateConnectionProgress(
progressRunId,
'connected',
connectedPreference === undefined ? undefined : [connectedPreference],
)
const connectionDetails = await connectedTransport.connectionDetails().catch(() => undefined)
this.context.logger.info('remote Harness transport ready', {
targetDeviceId: shortId(target.deviceId),
transport: connectedClient.getStats().mode,
...(connectionDetails === undefined ? {} : {
preferredTransports: connectionDetails.preferredTransports,
negotiatedCapabilities: connectionDetails.negotiatedCapabilities,
webRtcEnabled: connectionDetails.webRtcEnabled,
}),
})
if (connectionDetails?.webRtc?.diagnostics !== undefined) {
this.context.logger.debug('remote Harness transport diagnostics', {
targetDeviceId: shortId(target.deviceId),
...webrtcDiagnosticsLogFields(connectionDetails.webRtc.diagnostics),
})
}
const features = await probeRemoteHostFeatures(connectedClient, serverDevice.clientVersion)
signal?.throwIfAborted()
if (closed) throw closeError ?? new ClientModeError('TRANSPORT_CLOSED', 'The Remote connection closed during discovery.', true)
return {
client: connectedClient,
target,
transport: connectedTransport,
features,
progressRunId,
...(serverDevice.clientVersion === undefined ? {} : { clientVersion: serverDevice.clientVersion }),
...(serverDevice.harnessVersion === undefined ? {} : { harnessVersion: serverDevice.harnessVersion }),
}
} catch (error) {
this.clearConnectionProgress(progressRunId)
const failure = closed && closeError !== undefined ? closeError : error
await client?.close().catch(() => undefined)
throw failure
} finally {
signal?.removeEventListener('abort', onAbort)
}
}
beginAttemptProgress(runId: number, attempt: TransportAttempt): () => void {
if (attempt !== 'direct') {
this.updateConnectionProgress(runId, 'probing', [attempt])
return () => undefined
}
this.updateConnectionProgress(runId, 'probing', ['lan'])
// LAN and P2P candidates are gathered inside one ICE attempt. The
// linear Remote UI still needs a single active route, so advance the
// visible cue if direct negotiation takes longer than a local probe.
const timer = setTimeout(() => {
if (this.context.connectionProgress?.runId === runId && this.context.connectionProgress.phase === 'probing') {
this.updateConnectionProgress(runId, 'probing', ['p2p'])
}
}, DIRECT_LAN_PROGRESS_DISPLAY_MS)
return () => clearTimeout(timer)
}
updateConnectionProgress(
runId: number,
phase: ConnectionProgressState['phase'],
activeTransports?: ConnectionProgressState['activeTransports'],
): void {
if (this.context.connectionProgress?.runId !== runId) return
this.context.connectionProgress = {
runId,
targetDeviceId: this.context.connectionProgress.targetDeviceId,
phase,
...(activeTransports === undefined ? {} : { activeTransports }),
}
}
clearConnectionProgress(runId: number): void {
if (this.context.connectionProgress?.runId === runId) this.context.connectionProgress = undefined
}
async authorizeHostPeer(serverDevice: ServerHostDevice, signal?: AbortSignal): Promise<TrustedPeer> {
const descriptor = await this.context.server.deviceFor(serverDevice.deviceId, signal)
signal?.throwIfAborted()
assertAuthorizedHost(serverDevice, descriptor)
const existing = this.context.identities.trustedPeer(descriptor.deviceId)
if (existing !== undefined && existing.publicKey !== descriptor.identityKey) {
throw new ClientModeError('PEER_IDENTITY_MISMATCH', 'The authorized Host identity key changed unexpectedly.')
}
if (existing !== undefined
&& existing.membershipId === descriptor.membershipId
&& existing.name === descriptor.name
&& existing.platform === descriptor.platform) {
return existing
}
return this.context.identities.trustPeer({
deviceId: descriptor.deviceId,
name: descriptor.name,
platform: descriptor.platform,
publicKey: descriptor.identityKey,
membershipId: descriptor.membershipId,
})
}
}