rollback-netcode 0.0.4

package/dist/transport/webrtc.d.ts

@@ -0,0 +1,285 @@
+/**
+ * WebRTC transport implementation.
+ *
+ * Provides peer-to-peer communication using WebRTC DataChannels.
+ * Uses dual channels: reliable (ordered, guaranteed) and unreliable (best-effort).
+ *
+ * This implementation is signaling-agnostic - you must provide your own signaling
+ * mechanism (WebSocket, HTTP, etc.) to exchange SDP offers/answers and ICE candidates.
+ */
+import type { ConnectionMetrics, TransportAdapter } from "./adapter.js";
+/**
+ * Configuration for the WebRTC transport.
+ */
+export interface WebRTCTransportConfig {
+    /** RTCPeerConnection configuration (STUN/TURN servers, etc.) */
+    rtcConfiguration?: RTCConfiguration;
+    /** Configuration for the reliable data channel */
+    reliableChannelConfig?: RTCDataChannelInit;
+    /** Configuration for the unreliable data channel */
+    unreliableChannelConfig?: RTCDataChannelInit;
+    /** Maximum reconnection attempts before giving up */
+    maxReconnectAttempts?: number;
+    /** Delay between reconnection attempts in milliseconds */
+    reconnectDelay?: number;
+    /** Interval for sending keepalive pings (0 to disable, default: 5000ms) */
+    keepaliveInterval?: number;
+    /** Time without response before considering peer dead (default: 15000ms) */
+    keepaliveTimeout?: number;
+    /** Timeout for connection establishment (default: 30000ms) */
+    connectionTimeout?: number;
+}
+/**
+ * A signaling message to be sent to a remote peer.
+ * This is a discriminated union - check the `type` field to determine the payload.
+ */
+export type SignalMessage = {
+    type: "description";
+    description: RTCSessionDescriptionInit;
+} | {
+    type: "candidate";
+    candidate: RTCIceCandidateInit;
+};
+/**
+ * Callbacks for signaling integration.
+ * You must implement this to handle WebRTC signaling exchange.
+ *
+ * The unified `onSignal` callback receives all signaling messages (SDP and ICE),
+ * making it easier to route through a single signaling path.
+ */
+export interface SignalingCallbacks {
+    /**
+     * Called when a signaling message needs to be sent to a peer.
+     * The message should be serialized and sent through your signaling server.
+     *
+     * @param peerId - The target peer's ID
+     * @param signal - The signal message (either a description or candidate)
+     *
+     * @example
+     * ```typescript
+     * transport.setSignalingCallbacks({
+     *   onSignal: (peerId, signal) => {
+     *     websocket.send(JSON.stringify({ to: peerId, signal }));
+     *   }
+     * });
+     *
+     * // On the receiving side, parse and call:
+     * if (signal.type === 'description') {
+     *   transport.handleRemoteDescription(fromPeerId, signal.description);
+     * } else {
+     *   transport.handleRemoteCandidate(fromPeerId, signal.candidate);
+     * }
+     * ```
+     */
+    onSignal: (peerId: string, signal: SignalMessage) => void;
+}
+/**
+ * WebRTC transport implementation.
+ */
+export declare class WebRTCTransport implements TransportAdapter {
+    readonly localPeerId: string;
+    private readonly rtcConfig;
+    private readonly reliableChannelConfig;
+    private readonly unreliableChannelConfig;
+    private readonly maxReconnectAttempts;
+    private readonly reconnectDelay;
+    private readonly keepaliveInterval;
+    private readonly keepaliveTimeout;
+    private readonly connectionTimeout;
+    private readonly peers;
+    private readonly _connectedPeers;
+    private readonly peerMetrics;
+    private signalingCallbacks;
+    private keepaliveTimer;
+    /** Callback for keepalive ping - set by Session to send Ping messages */
+    onKeepalivePing: ((peerId: string) => void) | null;
+    onMessage: ((peerId: string, message: Uint8Array) => void) | null;
+    onConnect: ((peerId: string) => void) | null;
+    onDisconnect: ((peerId: string) => void) | null;
+    onError: ((peerId: string | null, error: Error, context: string) => void) | null;
+    /**
+     * Create a new WebRTC transport.
+     *
+     * @param localPeerId - Unique identifier for this peer
+     * @param config - Optional configuration
+     */
+    constructor(localPeerId: string, config?: WebRTCTransportConfig);
+    /**
+     * Set of currently connected peer IDs.
+     */
+    get connectedPeers(): ReadonlySet<string>;
+    /**
+     * Set signaling callbacks for SDP and ICE candidate exchange.
+     * Must be called before initiating or accepting connections.
+     *
+     * @param callbacks - Signaling callbacks
+     */
+    setSignalingCallbacks(callbacks: SignalingCallbacks): void;
+    /**
+     * Connect to a peer by creating an offer.
+     * This initiates the WebRTC connection handshake.
+     *
+     * @param peerId - The peer's ID
+     */
+    connect(peerId: string): Promise<void>;
+    /**
+     * Create and send an offer to a peer.
+     *
+     * @param peerId - The peer's ID
+     */
+    createOffer(peerId: string): Promise<void>;
+    /**
+     * Handle a remote SDP description (offer or answer).
+     *
+     * @param peerId - The peer's ID
+     * @param description - The SDP description
+     */
+    handleRemoteDescription(peerId: string, description: RTCSessionDescriptionInit): Promise<void>;
+    /**
+     * Handle a remote ICE candidate.
+     *
+     * @param peerId - The peer's ID
+     * @param candidate - The ICE candidate
+     */
+    handleRemoteCandidate(peerId: string, candidate: RTCIceCandidateInit): Promise<void>;
+    /**
+     * Disconnect from a peer.
+     *
+     * @param peerId - The peer's ID
+     */
+    disconnect(peerId: string): void;
+    /**
+     * Disconnect from all peers.
+     */
+    disconnectAll(): void;
+    /**
+     * Destroy the transport and clean up all resources.
+     */
+    destroy(): void;
+    /**
+     * Send a message to a peer.
+     *
+     * @param peerId - The peer's ID
+     * @param message - The message data
+     * @param reliable - Whether to use the reliable channel
+     */
+    send(peerId: string, message: Uint8Array, reliable: boolean): void;
+    /**
+     * Broadcast a message to all connected peers.
+     *
+     * @param message - The message data
+     * @param reliable - Whether to use the reliable channel
+     */
+    broadcast(message: Uint8Array, reliable: boolean): void;
+    /**
+     * Get connection statistics for a peer.
+     *
+     * @param peerId - The peer's ID
+     * @returns Connection stats or null if not connected
+     */
+    getConnectionStats(peerId: string): Promise<RTCStatsReport | null>;
+    /**
+     * Get or create a peer connection.
+     */
+    private getOrCreatePeer;
+    /**
+     * Set up event handlers for a peer connection.
+     */
+    private setupPeerConnection;
+    /**
+     * Set up event handlers for a data channel.
+     */
+    private setupDataChannel;
+    /**
+     * Check if both data channels are ready and mark connection as established.
+     */
+    private checkConnectionReady;
+    /**
+     * Handle a connection failure.
+     */
+    private handleConnectionFailure;
+    /**
+     * Calculate reconnection delay with exponential backoff.
+     *
+     * @param attempt - The reconnection attempt number (1-based)
+     * @returns The base delay in milliseconds
+     */
+    private getReconnectDelay;
+    /**
+     * Calculate reconnection delay with exponential backoff and jitter.
+     * Jitter prevents multiple peers from reconnecting at exactly the same time.
+     *
+     * @param attempt - The reconnection attempt number (1-based)
+     * @returns The delay in milliseconds with random jitter applied
+     */
+    private getReconnectDelayWithJitter;
+    /**
+     * Attempt to reconnect to a peer.
+     */
+    private attemptReconnect;
+    /**
+     * Clean up a peer connection.
+     */
+    private cleanupPeer;
+    /**
+     * Get connection quality metrics for a peer.
+     *
+     * @param peerId - The peer's ID
+     * @returns Connection metrics or null if not available
+     */
+    getConnectionMetrics(peerId: string): ConnectionMetrics | null;
+    /**
+     * Record a ping sent to a peer for RTT tracking.
+     * Call this when sending a Ping message.
+     *
+     * @param peerId - The peer's ID
+     * @param timestamp - The timestamp sent in the ping
+     */
+    recordPingSent(peerId: string, timestamp: number): void;
+    /**
+     * Record a pong received from a peer for RTT calculation.
+     * Call this when receiving a Pong message.
+     *
+     * @param peerId - The peer's ID
+     * @param timestamp - The timestamp from the pong (originally from our ping)
+     */
+    recordPongReceived(peerId: string, timestamp: number): void;
+    /**
+     * Update packet loss estimate.
+     * Call this when detecting gaps in received input acks.
+     *
+     * @param peerId - The peer's ID
+     * @param received - Number of packets received
+     * @param expected - Number of packets expected
+     */
+    updatePacketLoss(peerId: string, received: number, expected: number): void;
+    /**
+     * Get or create metrics data for a peer.
+     */
+    private getOrCreateMetrics;
+    /**
+     * Start the keepalive timer.
+     */
+    private startKeepaliveTimer;
+    /**
+     * Stop the keepalive timer.
+     */
+    private stopKeepaliveTimer;
+    /**
+     * Check keepalive status for all connected peers.
+     * Sends pings and detects dead connections.
+     */
+    private checkKeepalives;
+    /**
+     * Record that we received a response from a peer.
+     * Call this when any message is received from a peer.
+     *
+     * @param peerId - The peer's ID
+     */
+    recordPeerResponse(peerId: string): void;
+    /**
+     * Update RTT metrics with a new sample.
+     */
+    private updateRttMetrics;
+}
+//# sourceMappingURL=webrtc.d.ts.map

package/dist/transport/webrtc.d.ts.map

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