dropspace 0.0.0-stage → 0.1.1

package/dist/client/peer-connection.js

@@ -0,0 +1,647 @@
+import { TypedEventEmitter } from "./events.js";
+import { PeerChannelMultiplexer } from "./channel.js";
+let connSeq = 0;
+function nextConnectionId() {
+    connSeq = (connSeq + 1) % 1_000_000_000;
+    return `conn_${Date.now().toString(36)}_${connSeq.toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+/**
+ * Manages the WebRTC RTCPeerConnection & RTCDataChannel lifecycle for a single remote peer,
+ * including Perfect Negotiation (offer collision resolution), generation-scoped signaling,
+ * transient disconnect grace period, ICE restart, and coalesced exponential-backoff reconnection.
+ */
+export class ManagedPeerSession {
+    options;
+    events = new TypedEventEmitter();
+    multiplexer;
+    state = "idle";
+    pc = null;
+    dc = null;
+    generation = 0;
+    connectionId = "";
+    makingOffer = false;
+    ignoreOffer = false;
+    isSettingRemoteAnswerPending = false;
+    pendingRemoteCandidates = [];
+    manuallyClosed = false;
+    reconnectAttempts = 0;
+    reconnectPromise = null;
+    graceTimer = null;
+    iceRestartTimer = null;
+    connectTimeoutTimer = null;
+    reconnectBackoffTimer = null;
+    boundIceCandidateListener = null;
+    boundConnectionStateListener = null;
+    boundDataChannelListener = null;
+    boundDcOpenListener = null;
+    boundDcCloseListener = null;
+    connectPromise = null;
+    staleSignalsDropped = 0;
+    offerCollisionsHandled = 0;
+    totalReconnectCount = 0;
+    selectedRouteType = "unknown";
+    constructor(options) {
+        this.options = options;
+        this.multiplexer = new PeerChannelMultiplexer({
+            peerDeviceId: options.remoteDeviceId,
+            localDeviceId: options.localDeviceId,
+        });
+    }
+    getState() {
+        return this.state;
+    }
+    getGeneration() {
+        return this.generation;
+    }
+    getConnectionId() {
+        return this.connectionId;
+    }
+    isManuallyClosed() {
+        return this.manuallyClosed;
+    }
+    transitionState(next, reason) {
+        if (this.state === next)
+            return;
+        const prev = this.state;
+        this.state = next;
+        this.events.emit("stateChange", {
+            peerDeviceId: this.options.remoteDeviceId,
+            previousState: prev,
+            state: next,
+            generation: this.generation,
+            connectionId: this.connectionId,
+            reason,
+        });
+    }
+    /**
+     * Initiates or re-initiates a connection to the peer.
+     * Coalesces concurrent calls while connecting or reconnecting.
+     */
+    async connect(reason = "explicit_connect") {
+        if (this.manuallyClosed) {
+            this.manuallyClosed = false;
+        }
+        if (this.state === "connected" && this.dc?.readyState === "open") {
+            return;
+        }
+        if (this.reconnectPromise) {
+            return this.reconnectPromise;
+        }
+        if (this.connectPromise) {
+            return this.connectPromise;
+        }
+        if (this.state === "connecting" && this.pc) {
+            return;
+        }
+        this.generation += 1;
+        this.connectionId = nextConnectionId();
+        this.transitionState("connecting", reason);
+        this.armConnectTimeout();
+        this.connectPromise = this.setupNewPeerConnection(true).finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    /**
+     * Tears down any existing (potentially stale) RTCPeerConnection and immediately
+     * starts a fresh connection generation.
+     */
+    async forceReconnect(reason = "force_reconnect") {
+        this.manuallyClosed = false;
+        this.clearTimers();
+        this.teardownPeerConnectionOnly();
+        this.connectPromise = null;
+        this.reconnectPromise = null;
+        this.generation += 1;
+        this.connectionId = nextConnectionId();
+        this.transitionState("connecting", reason);
+        this.armConnectTimeout();
+        this.connectPromise = this.setupNewPeerConnection(true).finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    armConnectTimeout() {
+        if (this.connectTimeoutTimer) {
+            clearTimeout(this.connectTimeoutTimer);
+            this.connectTimeoutTimer = null;
+        }
+        const connectTimeoutMs = this.options.connectTimeoutMs ?? 8000;
+        this.connectTimeoutTimer = setTimeout(() => {
+            this.connectTimeoutTimer = null;
+            if (!this.manuallyClosed && this.state === "connecting") {
+                this.teardownPeerConnectionOnly();
+                void this.scheduleReconnect("connect_timeout");
+            }
+        }, connectTimeoutMs);
+    }
+    setWaitingForPeer(reason = "peer_offline") {
+        if (this.manuallyClosed || this.state === "connected")
+            return;
+        this.clearTimers();
+        this.transitionState("waiting_for_peer", reason);
+    }
+    async setupNewPeerConnection(initiateOffer) {
+        this.teardownPeerConnectionOnly();
+        this.pendingRemoteCandidates = [];
+        const iceServers = await this.options.getIceServers();
+        const pc = this.options.createPeerConnection({
+            iceServers,
+            iceTransportPolicy: this.options.iceTransportPolicy ?? "all",
+        });
+        this.pc = pc;
+        const currentGen = this.generation;
+        this.boundIceCandidateListener = (ev) => {
+            if (this.manuallyClosed || this.generation !== currentGen)
+                return;
+            if (ev.candidate && ev.candidate.candidate) {
+                void this.options
+                    .sendSignaling("webrtc.ice_candidate", this.connectionId, currentGen, {
+                    candidate: ev.candidate.candidate,
+                    sdpMid: ev.candidate.sdpMid ?? "0",
+                    sdpMLineIndex: ev.candidate.sdpMLineIndex ?? 0,
+                    usernameFragment: ev.candidate.usernameFragment ?? null,
+                })
+                    .catch(() => { });
+            }
+        };
+        this.boundConnectionStateListener = () => {
+            if (this.manuallyClosed || this.generation !== currentGen)
+                return;
+            this.handleTransportStateChange();
+        };
+        this.boundDataChannelListener = (ev) => {
+            if (this.manuallyClosed || this.generation !== currentGen)
+                return;
+            if (ev.channel) {
+                this.bindDataChannel(ev.channel);
+            }
+        };
+        pc.addEventListener("icecandidate", this.boundIceCandidateListener);
+        pc.addEventListener("connectionstatechange", this.boundConnectionStateListener);
+        pc.addEventListener("iceconnectionstatechange", this.boundConnectionStateListener);
+        pc.addEventListener("datachannel", this.boundDataChannelListener);
+        const connectTimeoutMs = this.options.connectTimeoutMs ?? 15_000;
+        if (this.connectTimeoutTimer)
+            clearTimeout(this.connectTimeoutTimer);
+        this.connectTimeoutTimer = setTimeout(() => {
+            if (!this.manuallyClosed &&
+                this.generation === currentGen &&
+                this.state !== "connected") {
+                void this.scheduleReconnect("connect_timeout");
+            }
+        }, connectTimeoutMs);
+        if (initiateOffer) {
+            const dc = pc.createDataChannel("dropspace-v1", { ordered: true });
+            this.bindDataChannel(dc);
+            await this.performOffer(false);
+        }
+    }
+    bindDataChannel(dc) {
+        if (this.dc && this.dc !== dc) {
+            if (this.boundDcOpenListener) {
+                this.dc.removeEventListener("open", this.boundDcOpenListener);
+            }
+            if (this.boundDcCloseListener) {
+                this.dc.removeEventListener("close", this.boundDcCloseListener);
+            }
+        }
+        this.dc = dc;
+        this.multiplexer.attachDataChannel(dc);
+        this.boundDcOpenListener = () => {
+            if (this.manuallyClosed)
+                return;
+            this.clearTimers();
+            this.reconnectAttempts = 0;
+            this.transitionState("connected", "datachannel_open");
+            void this.inspectSelectedRoute();
+        };
+        this.boundDcCloseListener = () => {
+            if (this.manuallyClosed)
+                return;
+            if (this.state === "connected") {
+                void this.scheduleReconnect("datachannel_closed");
+            }
+        };
+        dc.addEventListener("open", this.boundDcOpenListener);
+        dc.addEventListener("close", this.boundDcCloseListener);
+        if (dc.readyState === "open") {
+            this.boundDcOpenListener();
+        }
+    }
+    async performOffer(iceRestart) {
+        if (!this.pc || this.manuallyClosed)
+            return;
+        const currentGen = this.generation;
+        const currentConnId = this.connectionId;
+        try {
+            this.makingOffer = true;
+            if (iceRestart && typeof this.pc.restartIce === "function") {
+                this.pc.restartIce();
+            }
+            const offer = await this.pc.createOffer(iceRestart ? { iceRestart: true } : undefined);
+            if (this.generation !== currentGen || !this.pc)
+                return;
+            await this.pc.setLocalDescription({
+                type: "offer",
+                sdp: offer.sdp,
+            });
+            await this.options.sendSignaling("webrtc.offer", currentConnId, currentGen, {
+                sdp: this.pc.localDescription?.sdp ?? offer.sdp ?? "",
+                iceRestart,
+            });
+        }
+        finally {
+            this.makingOffer = false;
+        }
+    }
+    /**
+     * Handles incoming WebRTC signaling envelopes (`webrtc.offer`, `webrtc.answer`, `webrtc.ice_candidate`, `webrtc.close`).
+     * Enforces monotonic generation and Perfect Negotiation offer-collision resolution.
+     */
+    async handleSignalingEnvelope(envelope) {
+        if (this.manuallyClosed && envelope.type !== "webrtc.offer")
+            return;
+        const msgGen = envelope.generation ?? 0;
+        const msgConnId = envelope.connectionId ?? "";
+        const readyForOffer = !this.makingOffer &&
+            (!this.pc ||
+                (this.pc.signalingState === "stable" && !this.isSettingRemoteAnswerPending));
+        const isNewOfferSession = envelope.type === "webrtc.offer" &&
+            msgConnId !== "" &&
+            msgConnId !== this.connectionId &&
+            readyForOffer;
+        // Reject stale generations (Section 9 & 10), but allow a peer that restarted
+        // with a brand-new connectionId (even if our local PC still appears connected).
+        if (msgGen < this.generation && !isNewOfferSession) {
+            this.staleSignalsDropped += 1;
+            this.events.emit("staleSignalDropped", {
+                peerDeviceId: this.options.remoteDeviceId,
+                signalType: envelope.type,
+                signalGeneration: msgGen,
+                currentGeneration: this.generation,
+                signalConnectionId: msgConnId,
+                currentConnectionId: this.connectionId,
+            });
+            return;
+        }
+        if (envelope.type === "webrtc.offer") {
+            this.manuallyClosed = false;
+            const sdp = String(envelope.payload.sdp ?? "");
+            if (isNewOfferSession && this.pc) {
+                this.clearTimers();
+                this.teardownPeerConnectionOnly();
+            }
+            const offerCollision = !readyForOffer && this.pc !== null;
+            if (offerCollision) {
+                this.offerCollisionsHandled += 1;
+                this.ignoreOffer = !this.options.polite;
+                if (this.ignoreOffer) {
+                    this.events.emit("offerCollisionHandled", {
+                        peerDeviceId: this.options.remoteDeviceId,
+                        polite: false,
+                        action: "ignored_incoming",
+                        generation: msgGen,
+                    });
+                    return;
+                }
+                this.events.emit("offerCollisionHandled", {
+                    peerDeviceId: this.options.remoteDeviceId,
+                    polite: true,
+                    action: "rolled_back",
+                    generation: msgGen,
+                });
+            }
+            else {
+                this.ignoreOffer = false;
+            }
+            // Adopt incoming generation & connectionId if newer, restarted session, or if no PC exists yet
+            if (!this.pc || msgGen > this.generation || offerCollision || isNewOfferSession) {
+                this.generation = msgGen;
+                this.connectionId = msgConnId;
+            }
+            if (!this.pc) {
+                this.transitionState("connecting", "incoming_offer");
+                this.armConnectTimeout();
+                await this.setupNewPeerConnection(false);
+            }
+            else if (offerCollision && this.pc.signalingState !== "stable") {
+                // Recreate PC cleanly on initial-connect glare so no rolled-back local DataChannel remains
+                await this.setupNewPeerConnection(false);
+            }
+            if (!this.pc)
+                return;
+            await this.pc.setRemoteDescription({ type: "offer", sdp });
+            await this.flushPendingCandidates();
+            const answer = await this.pc.createAnswer();
+            await this.pc.setLocalDescription({ type: "answer", sdp: answer.sdp });
+            await this.options.sendSignaling("webrtc.answer", this.connectionId, this.generation, {
+                sdp: this.pc.localDescription?.sdp ?? answer.sdp ?? "",
+            });
+            return;
+        }
+        if (envelope.type === "webrtc.answer") {
+            if (!this.pc || msgGen !== this.generation || msgConnId !== this.connectionId) {
+                this.staleSignalsDropped += 1;
+                this.events.emit("staleSignalDropped", {
+                    peerDeviceId: this.options.remoteDeviceId,
+                    signalType: envelope.type,
+                    signalGeneration: msgGen,
+                    currentGeneration: this.generation,
+                    signalConnectionId: msgConnId,
+                    currentConnectionId: this.connectionId,
+                });
+                return;
+            }
+            this.ignoreOffer = false;
+            const sdp = String(envelope.payload.sdp ?? "");
+            this.isSettingRemoteAnswerPending = true;
+            try {
+                await this.pc.setRemoteDescription({ type: "answer", sdp });
+            }
+            finally {
+                this.isSettingRemoteAnswerPending = false;
+            }
+            await this.flushPendingCandidates();
+            return;
+        }
+        if (envelope.type === "webrtc.ice_candidate") {
+            // Drop candidate if it belongs to a stale generation or mismatched connectionId
+            if (msgGen !== this.generation ||
+                (this.connectionId !== "" && msgConnId !== this.connectionId)) {
+                this.staleSignalsDropped += 1;
+                this.events.emit("staleSignalDropped", {
+                    peerDeviceId: this.options.remoteDeviceId,
+                    signalType: envelope.type,
+                    signalGeneration: msgGen,
+                    currentGeneration: this.generation,
+                    signalConnectionId: msgConnId,
+                    currentConnectionId: this.connectionId,
+                });
+                return;
+            }
+            if (this.ignoreOffer)
+                return;
+            const candidateInit = {
+                candidate: String(envelope.payload.candidate ?? ""),
+                sdpMid: typeof envelope.payload.sdpMid === "string" ? envelope.payload.sdpMid : "0",
+                sdpMLineIndex: typeof envelope.payload.sdpMLineIndex === "number"
+                    ? envelope.payload.sdpMLineIndex
+                    : 0,
+                usernameFragment: typeof envelope.payload.usernameFragment === "string"
+                    ? envelope.payload.usernameFragment
+                    : null,
+            };
+            if (!this.pc || !this.pc.remoteDescription) {
+                this.pendingRemoteCandidates.push(candidateInit);
+                return;
+            }
+            try {
+                await this.pc.addIceCandidate(candidateInit);
+            }
+            catch (err) {
+                if (!this.ignoreOffer) {
+                    this.events.emit("error", err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            return;
+        }
+        if (envelope.type === "webrtc.close") {
+            this.manuallyClosed = false;
+            this.clearTimers();
+            this.teardownPeerConnectionOnly();
+            this.transitionState("waiting_for_peer", "remote_webrtc_close");
+        }
+    }
+    async flushPendingCandidates() {
+        if (!this.pc || !this.pc.remoteDescription)
+            return;
+        while (this.pendingRemoteCandidates.length > 0) {
+            const cand = this.pendingRemoteCandidates.shift();
+            try {
+                await this.pc.addIceCandidate(cand);
+            }
+            catch {
+                // Ignore candidate failure during flush
+            }
+        }
+    }
+    handleTransportStateChange() {
+        if (!this.pc || this.manuallyClosed)
+            return;
+        const connState = this.pc.connectionState || this.pc.iceConnectionState;
+        if (connState === "connected" || connState === "completed") {
+            this.clearTimers();
+            this.reconnectAttempts = 0;
+            if (this.dc?.readyState === "open") {
+                this.transitionState("connected", "ice_connected");
+                void this.inspectSelectedRoute();
+            }
+            return;
+        }
+        if (connState === "disconnected") {
+            // Transient disconnect: wait grace period before starting ICE restart
+            if (!this.graceTimer) {
+                const graceMs = this.options.disconnectGracePeriodMs ?? 2500;
+                this.graceTimer = setTimeout(() => {
+                    this.graceTimer = null;
+                    if (!this.manuallyClosed &&
+                        this.pc &&
+                        (this.pc.connectionState === "disconnected" ||
+                            this.pc.iceConnectionState === "disconnected")) {
+                        void this.scheduleReconnect("ice_disconnected_grace_expired");
+                    }
+                }, graceMs);
+            }
+            return;
+        }
+        if (connState === "failed") {
+            void this.scheduleReconnect("transport_failed");
+        }
+    }
+    /**
+     * Schedules a coalesced reconnect attempt with exponential backoff + jitter.
+     * First attempts an in-place ICE restart if a PC exists; otherwise creates a new RTCPeerConnection.
+     */
+    async scheduleReconnect(reason) {
+        if (this.manuallyClosed)
+            return;
+        if (this.reconnectPromise) {
+            return this.reconnectPromise;
+        }
+        const maxAttempts = this.options.maxReconnectAttempts ?? 5;
+        if (this.reconnectAttempts >= maxAttempts) {
+            this.clearTimers();
+            this.transitionState("failed", `reconnect_budget_exhausted (${reason})`);
+            return;
+        }
+        this.reconnectAttempts += 1;
+        this.totalReconnectCount += 1;
+        const attempt = this.reconnectAttempts;
+        const baseMs = this.options.baseBackoffMs ?? 200;
+        const maxMs = this.options.maxBackoffMs ?? 5000;
+        const expDelay = Math.min(maxMs, baseMs * Math.pow(2, attempt - 1));
+        const jitter = Math.floor(Math.random() * Math.max(20, Math.floor(expDelay * 0.25)));
+        const delayMs = expDelay + jitter;
+        const strategy = attempt === 1 && this.pc ? "ice_restart" : "new_pc";
+        this.transitionState("reconnecting", `${reason} (attempt ${attempt}, ${strategy})`);
+        this.events.emit("reconnectAttempt", {
+            peerDeviceId: this.options.remoteDeviceId,
+            attempt,
+            strategy,
+            delayMs,
+        });
+        this.reconnectPromise = (async () => {
+            try {
+                await new Promise((resolve) => {
+                    this.reconnectBackoffTimer = setTimeout(() => {
+                        this.reconnectBackoffTimer = null;
+                        resolve();
+                    }, delayMs);
+                });
+                if (this.manuallyClosed || this.state === "connected")
+                    return;
+                if (strategy === "ice_restart" && this.pc) {
+                    await this.performOffer(true);
+                    const iceTimeoutMs = this.options.iceRestartTimeoutMs ?? 3000;
+                    await new Promise((resolve) => {
+                        this.iceRestartTimer = setTimeout(() => {
+                            this.iceRestartTimer = null;
+                            resolve();
+                        }, iceTimeoutMs);
+                    });
+                    if (!this.manuallyClosed && this.state !== "connected") {
+                        // Escalate to full new RTCPeerConnection
+                        this.generation += 1;
+                        this.connectionId = nextConnectionId();
+                        await this.setupNewPeerConnection(true);
+                    }
+                }
+                else {
+                    this.generation += 1;
+                    this.connectionId = nextConnectionId();
+                    await this.setupNewPeerConnection(true);
+                }
+            }
+            catch (err) {
+                this.events.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+            finally {
+                this.reconnectPromise = null;
+            }
+        })();
+        return this.reconnectPromise;
+    }
+    async inspectSelectedRoute() {
+        if (!this.pc || typeof this.pc.getStats !== "function")
+            return;
+        try {
+            const stats = await this.pc.getStats();
+            let candidateType = "unknown";
+            let rttMs;
+            let protocol;
+            const entries = stats instanceof Map ? Array.from(stats.values()) : Array.isArray(stats) ? stats : [];
+            for (const report of entries) {
+                if (report.type === "candidate-pair" && (report.nominated || report.state === "succeeded")) {
+                    if (typeof report.currentRoundTripTime === "number") {
+                        rttMs = Math.round(report.currentRoundTripTime * 1000);
+                    }
+                    const localCand = entries.find((r) => r.id === report.localCandidateId);
+                    const remoteCand = entries.find((r) => r.id === report.remoteCandidateId);
+                    if (localCand?.candidateType === "relay" ||
+                        remoteCand?.candidateType === "relay") {
+                        candidateType = "relay";
+                    }
+                    else if (localCand?.candidateType || remoteCand?.candidateType) {
+                        candidateType = "direct";
+                    }
+                    protocol = localCand?.protocol;
+                }
+            }
+            if (candidateType === "unknown") {
+                candidateType =
+                    this.options.iceTransportPolicy === "relay" ? "relay" : "direct";
+            }
+            this.selectedRouteType = candidateType;
+            this.events.emit("routeSelected", {
+                peerDeviceId: this.options.remoteDeviceId,
+                candidateType,
+                protocol,
+                rttMs,
+            });
+        }
+        catch {
+            // Ignore stats failure
+        }
+    }
+    clearTimers() {
+        if (this.graceTimer) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+        if (this.iceRestartTimer) {
+            clearTimeout(this.iceRestartTimer);
+            this.iceRestartTimer = null;
+        }
+        if (this.connectTimeoutTimer) {
+            clearTimeout(this.connectTimeoutTimer);
+            this.connectTimeoutTimer = null;
+        }
+        if (this.reconnectBackoffTimer) {
+            clearTimeout(this.reconnectBackoffTimer);
+            this.reconnectBackoffTimer = null;
+        }
+    }
+    teardownPeerConnectionOnly() {
+        if (this.dc) {
+            if (this.boundDcOpenListener) {
+                this.dc.removeEventListener("open", this.boundDcOpenListener);
+            }
+            if (this.boundDcCloseListener) {
+                this.dc.removeEventListener("close", this.boundDcCloseListener);
+            }
+            try {
+                this.dc.close();
+            }
+            catch { }
+            this.dc = null;
+        }
+        if (this.pc) {
+            if (this.boundIceCandidateListener) {
+                this.pc.removeEventListener("icecandidate", this.boundIceCandidateListener);
+            }
+            if (this.boundConnectionStateListener) {
+                this.pc.removeEventListener("connectionstatechange", this.boundConnectionStateListener);
+                this.pc.removeEventListener("iceconnectionstatechange", this.boundConnectionStateListener);
+            }
+            if (this.boundDataChannelListener) {
+                this.pc.removeEventListener("datachannel", this.boundDataChannelListener);
+            }
+            try {
+                this.pc.close();
+            }
+            catch { }
+            this.pc = null;
+        }
+    }
+    /**
+     * Explicitly closes the peer connection and disables automatic reconnection.
+     */
+    close(notifyRemote = true) {
+        if (this.manuallyClosed && this.state === "closed")
+            return;
+        this.manuallyClosed = true;
+        this.clearTimers();
+        if (notifyRemote && this.connectionId) {
+            void this.options
+                .sendSignaling("webrtc.close", this.connectionId, this.generation, {
+                reason: "manual_close",
+            })
+                .catch(() => { });
+        }
+        this.teardownPeerConnectionOnly();
+        this.multiplexer.close();
+        this.transitionState("closed", "manual_close");
+    }
+}
+//# sourceMappingURL=peer-connection.js.map