diff --git a/packages/plugin/src/client-connection.ts b/packages/plugin/src/client-connection.ts new file mode 100644 index 0000000..1f77831 --- /dev/null +++ b/packages/plugin/src/client-connection.ts @@ -0,0 +1,253 @@ +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 + readonly logger: SafeLogger + readonly identities: IdentityStore +} + +export class ClientConnection { + constructor(private readonly context: ClientConnectionContext) {} + + async connect(targetDeviceId: string, signal?: AbortSignal, options: { background?: boolean } = {}): Promise { + 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 { + 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, + }) + } +}