dropspace 0.0.0-stage → 0.1.1

package/dist/client/peer-connection.d.ts

@@ -0,0 +1,190 @@
+import type { SignalingEnvelope } from "../protocol/index.js";
+import { TypedEventEmitter } from "./events.js";
+import { PeerChannelMultiplexer, type DataChannelLike } from "./channel.js";
+export type PeerConnectionLifecycleState = "idle" | "waiting_for_peer" | "connecting" | "connected" | "reconnecting" | "failed" | "closed";
+export interface RtcSessionDescriptionInitLike {
+    type: "offer" | "answer" | "pranswer" | "rollback";
+    sdp?: string;
+}
+export interface RtcIceCandidateInitLike {
+    candidate: string;
+    sdpMid?: string | null;
+    sdpMLineIndex?: number | null;
+    usernameFragment?: string | null;
+}
+export interface RtcPeerConnectionLike {
+    signalingState: string;
+    connectionState: string;
+    iceConnectionState: string;
+    localDescription: {
+        type: string;
+        sdp: string;
+    } | null;
+    remoteDescription: {
+        type: string;
+        sdp: string;
+    } | null;
+    createDataChannel(label: string, options?: {
+        ordered?: boolean;
+    }): DataChannelLike;
+    createOffer(options?: {
+        iceRestart?: boolean;
+    }): Promise<{
+        type: string;
+        sdp?: string;
+    }>;
+    createAnswer(): Promise<{
+        type: string;
+        sdp?: string;
+    }>;
+    setLocalDescription(desc?: RtcSessionDescriptionInitLike): Promise<void>;
+    setRemoteDescription(desc: RtcSessionDescriptionInitLike): Promise<void>;
+    addIceCandidate(candidate?: RtcIceCandidateInitLike | null): Promise<void>;
+    restartIce?(): void;
+    getStats?(): Promise<Map<string, any> | Array<any>>;
+    close(): void;
+    addEventListener(type: string, listener: (ev: any) => void): void;
+    removeEventListener(type: string, listener: (ev: any) => void): void;
+}
+export type PeerConnectionFactory = (config: {
+    iceServers: Array<{
+        urls: string | string[];
+        username?: string;
+        credential?: string;
+    }>;
+    iceTransportPolicy?: "all" | "relay";
+}) => RtcPeerConnectionLike;
+export interface ManagedPeerSessionOptions {
+    localDeviceId: string;
+    remoteDeviceId: string;
+    spaceId: string;
+    polite: boolean;
+    createPeerConnection: PeerConnectionFactory;
+    getIceServers: () => Promise<Array<{
+        urls: string | string[];
+        username?: string;
+        credential?: string;
+    }>>;
+    sendSignaling: (type: "webrtc.offer" | "webrtc.answer" | "webrtc.ice_candidate" | "webrtc.ice_restart" | "webrtc.close", connectionId: string, generation: number, payload: Record<string, unknown>) => Promise<void>;
+    iceTransportPolicy?: "all" | "relay";
+    disconnectGracePeriodMs?: number;
+    iceRestartTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    maxReconnectAttempts?: number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+export type ManagedPeerSessionEvents = {
+    stateChange: {
+        peerDeviceId: string;
+        previousState: PeerConnectionLifecycleState;
+        state: PeerConnectionLifecycleState;
+        generation: number;
+        connectionId: string;
+        reason: string;
+    };
+    staleSignalDropped: {
+        peerDeviceId: string;
+        signalType: string;
+        signalGeneration: number;
+        currentGeneration: number;
+        signalConnectionId?: string;
+        currentConnectionId: string;
+    };
+    offerCollisionHandled: {
+        peerDeviceId: string;
+        polite: boolean;
+        action: "rolled_back" | "ignored_incoming";
+        generation: number;
+    };
+    routeSelected: {
+        peerDeviceId: string;
+        candidateType: "direct" | "relay" | "unknown";
+        protocol?: string;
+        rttMs?: number;
+    };
+    reconnectAttempt: {
+        peerDeviceId: string;
+        attempt: number;
+        strategy: "ice_restart" | "new_pc";
+        delayMs: number;
+    };
+    error: Error;
+};
+/**
+ * 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 declare class ManagedPeerSession {
+    private readonly options;
+    readonly events: TypedEventEmitter<ManagedPeerSessionEvents>;
+    readonly multiplexer: PeerChannelMultiplexer;
+    private state;
+    private pc;
+    private dc;
+    private generation;
+    private connectionId;
+    private makingOffer;
+    private ignoreOffer;
+    private isSettingRemoteAnswerPending;
+    private pendingRemoteCandidates;
+    private manuallyClosed;
+    private reconnectAttempts;
+    private reconnectPromise;
+    private graceTimer;
+    private iceRestartTimer;
+    private connectTimeoutTimer;
+    private reconnectBackoffTimer;
+    private boundIceCandidateListener;
+    private boundConnectionStateListener;
+    private boundDataChannelListener;
+    private boundDcOpenListener;
+    private boundDcCloseListener;
+    private connectPromise;
+    staleSignalsDropped: number;
+    offerCollisionsHandled: number;
+    totalReconnectCount: number;
+    selectedRouteType: "direct" | "relay" | "unknown";
+    constructor(options: ManagedPeerSessionOptions);
+    getState(): PeerConnectionLifecycleState;
+    getGeneration(): number;
+    getConnectionId(): string;
+    isManuallyClosed(): boolean;
+    private transitionState;
+    /**
+     * Initiates or re-initiates a connection to the peer.
+     * Coalesces concurrent calls while connecting or reconnecting.
+     */
+    connect(reason?: string): Promise<void>;
+    /**
+     * Tears down any existing (potentially stale) RTCPeerConnection and immediately
+     * starts a fresh connection generation.
+     */
+    forceReconnect(reason?: string): Promise<void>;
+    private armConnectTimeout;
+    setWaitingForPeer(reason?: string): void;
+    private setupNewPeerConnection;
+    private bindDataChannel;
+    private performOffer;
+    /**
+     * Handles incoming WebRTC signaling envelopes (`webrtc.offer`, `webrtc.answer`, `webrtc.ice_candidate`, `webrtc.close`).
+     * Enforces monotonic generation and Perfect Negotiation offer-collision resolution.
+     */
+    handleSignalingEnvelope(envelope: SignalingEnvelope): Promise<void>;
+    private flushPendingCandidates;
+    private handleTransportStateChange;
+    /**
+     * 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.
+     */
+    scheduleReconnect(reason: string): Promise<void>;
+    private inspectSelectedRoute;
+    private clearTimers;
+    private teardownPeerConnectionOnly;
+    /**
+     * Explicitly closes the peer connection and disables automatic reconnection.
+     */
+    close(notifyRemote?: boolean): void;
+}
+//# sourceMappingURL=peer-connection.d.ts.map

package/dist/client/peer-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-connection.d.ts","sourceRoot":"","sources":["../../src/client/peer-connection.ts"],"names":[],"mappings":"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"}