@edryslabs/genericprovider 1.0.1

package/dist/providers/simple-peer/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * SimplePeer Transport Provider
+ *
+ * Peer-to-peer transport using WebRTC data channels with simple-peer library.
+ * Connects directly to other clients without going through a central server.
+ *
+ * Features:
+ * - Direct peer-to-peer connections
+ * - Mesh network (each peer connects to multiple others)
+ * - Uses signaling server only for peer discovery (not for data)
+ * - Optional encryption
+ * - Automatic connection management
+ * - Resilient to peer disconnections
+ *
+ * @example
+ * ```typescript
+ * import { GenericProvider } from 'y-generic'
+ * import { SimplePeerTransport } from 'y-generic/providers/simple-peer'
+ * import Peer from 'simple-peer'
+ *
+ * const doc = new Y.Doc()
+ * const transport = new SimplePeerTransport({
+ *   peer: Peer, // Pass the simple-peer constructor
+ *   signaling: ['wss://signaling.example.com'],
+ *   password: 'optional-encryption-key'
+ * })
+ * const provider = new GenericProvider(doc, transport)
+ * await provider.connect({ room: 'my-room' })
+ * ```
+ */
+import type { Transport, ConnectionConfig } from '../../transport';
+/**
+ * SimplePeer constructor type (from simple-peer library).
+ */
+export type SimplePeerConstructor = any;
+/**
+ * ICE server configuration for STUN/TURN servers.
+ * Used to establish WebRTC connections through NAT/firewalls.
+ */
+export interface IceServer {
+    /**
+     * STUN/TURN server URLs.
+     * @example ['stun:stun.l.google.com:19302']
+     * @example ['turn:turn.example.com:3478']
+     */
+    urls: string | string[];
+    /**
+     * Username for TURN server authentication.
+     */
+    username?: string;
+    /**
+     * Credential for TURN server authentication.
+     */
+    credential?: string;
+}
+/**
+ * Configuration options for SimplePeer transport.
+ */
+export interface SimplePeerTransportOptions {
+    /**
+     * The simple-peer library constructor.
+     * Users must provide this to avoid bundling the library.
+     * @example
+     * ```typescript
+     * import Peer from 'simple-peer'
+     * const transport = new SimplePeerTransport({ peer: Peer })
+     * ```
+     */
+    peer: SimplePeerConstructor;
+    /**
+     * Array of signaling server URLs for peer discovery.
+     * Signaling servers are only used to discover peers, not for data transfer.
+     * @default ['wss://signaling.yjs.dev']
+     */
+    signaling?: string[];
+    /**
+     * ICE servers for STUN/TURN configuration.
+     * Used to establish WebRTC connections through NAT/firewalls.
+     * @default [{ urls: 'stun:stun.l.google.com:19302' }]
+     * @example
+     * ```typescript
+     * iceServers: [
+     *   { urls: 'stun:stun.l.google.com:19302' },
+     *   {
+     *     urls: 'turn:turn.example.com:3478',
+     *     username: 'user',
+     *     credential: 'pass'
+     *   }
+     * ]
+     * ```
+     */
+    iceServers?: IceServer[];
+    /**
+     * Optional password for encrypting messages.
+     * When provided, all messages are encrypted before sending.
+     * @default undefined
+     */
+    password?: string;
+    /**
+     * Maximum number of WebRTC peer connections.
+     * Too many connections can overwhelm the browser.
+     * @default 20 + random(0-15)
+     */
+    maxConns?: number;
+    /**
+     * Options passed to simple-peer.
+     * See https://github.com/feross/simple-peer#api
+     * Note: iceServers will be merged into peerOpts.config if not already present
+     * @default {}
+     */
+    peerOpts?: Record<string, any>;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * SimplePeer transport implementation using simple-peer library.
+ * Creates direct peer-to-peer connections for data transfer.
+ */
+export declare class SimplePeerTransport implements Transport {
+    private options;
+    private _connected;
+    private _room;
+    private _callback?;
+    private _peerConnectCallbacks;
+    private _peerDisconnectCallbacks;
+    private _controlCallbacks;
+    private peerId;
+    private peers;
+    private signalingConns;
+    private announcedPeers;
+    private announceInterval?;
+    /**
+     * Create a new SimplePeer transport.
+     *
+     * @param options - Configuration options (must include peer constructor)
+     */
+    constructor(options: SimplePeerTransportOptions);
+    /**
+     * Connect to the room via signaling servers and start discovering peers.
+     */
+    connect(config: ConnectionConfig): Promise<void>;
+    /**
+     * Disconnect from all peers and signaling servers.
+     */
+    disconnect(): void;
+    /**
+     * Send data to all connected peers.
+     * Large messages are automatically chunked to fit within WebRTC DataChannel limits.
+     */
+    send(data: Uint8Array): void;
+    /**
+     * Send data to a single connected peer by ID (targeted delivery).
+     */
+    sendTo(peerId: string, data: Uint8Array): void;
+    /**
+     * Send data to a single peer, chunking if necessary.
+     * Uses flow control to avoid overwhelming the WebRTC buffer.
+     */
+    private sendToPeer;
+    /**
+     * Send chunks with backpressure handling.
+     * Waits for buffer to drain before sending more data.
+     */
+    private sendChunksWithFlowControl;
+    /**
+     * Register callback for incoming messages.
+     */
+    onMessage(callback: (data: Uint8Array) => void): () => void;
+    /**
+     * Register callback for new peer data-channel connections.
+     */
+    onPeerConnect(callback: (peerId: string) => void): () => void;
+    /**
+     * Register callback for peer disconnects (channel close or error). Only fires
+     * for peers that had reached the connected state.
+     */
+    onPeerDisconnect(callback: (peerId: string) => void): () => void;
+    /**
+     * Register callback for consumer control frames (MSG_TYPE_CONTROL).
+     * These bypass the provider pipe — use for per-peer handshakes/auth.
+     */
+    onControlFrame(callback: (peerId: string, payload: Uint8Array) => void): () => void;
+    /**
+     * Tear down a single peer connection (e.g. to reject a peer that failed an
+     * out-of-band handshake). Fires onPeerDisconnect if the peer was connected.
+     */
+    disconnectPeer(peerId: string): void;
+    /**
+     * Send a control frame to a single peer. Not chunked or encrypted — keep
+     * payloads small (they must fit one DataChannel message).
+     */
+    sendControl(peerId: string, payload: Uint8Array): void;
+    /**
+     * Check if connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Get number of connected peers (for debugging).
+     */
+    get connectedPeers(): number;
+    /**
+     * Connect to a signaling server.
+     */
+    private connectSignaling;
+    /**
+     * Handle messages from signaling server.
+     */
+    private handleSignalingMessage;
+    /**
+     * Send message to signaling server.
+     */
+    private sendSignaling;
+    /**
+     * Broadcast message to all signaling servers.
+     */
+    private broadcastSignaling;
+    /**
+     * Create a WebRTC peer connection.
+     */
+    private createPeerConnection;
+    /**
+     * Handle WebRTC signal from peer.
+     */
+    private handlePeerSignal;
+    /**
+     * Remove and cleanup a peer connection.
+     */
+    private removePeer;
+    /**
+     * Generate a unique peer ID.
+     */
+    private generatePeerId;
+    /**
+     * Simple XOR encryption (not cryptographically secure, just obfuscation).
+     */
+    private encrypt;
+    /**
+     * Simple XOR decryption.
+     */
+    private decrypt;
+    /**
+     * Hash password to key.
+     */
+    private hashPassword;
+    /**
+     * Log debug messages if enabled.
+     */
+    private log;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/simple-peer/index.d.ts.map

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