pluto-rtc 0.0.2

package/README.md

@@ -0,0 +1,84 @@
+# PlutoRTC
+
+A bare bones package for developers to create RTC apps quickly and painlessly.
+Leverages Pluto/Iroh for connectivity and Firebase for signaling/auth.
+
+## Installation
+
+```bash
+npm install pluto-rtc
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+import { ConnectionManager } from 'pluto-rtc';
+
+const rtc = new ConnectionManager({
+  firebaseConfig: { ... }, // Your Firebase Config
+  tag: 'my-awesome-game'
+});
+
+// Initialize and Listen
+await rtc.startListening();
+```
+
+### Authentication
+
+Redirects to the configured auth provider (e.g. Plutonium Identity).
+
+```typescript
+rtc.signIn(); // Triggers redirect
+```
+
+### Discovery & Connection
+
+Connect to other devices belonging to the same user:
+
+```typescript
+// Search for my devices
+const devices = await rtc.searchDevices();
+
+// Connect to a device
+const conn = await rtc.connect(devices[0].ticket);
+
+conn.send("Hello World!");
+
+conn.onMessage((msg) => {
+  console.log("Received:", msg);
+});
+```
+
+### Rooms (Multi-User / Custom Signaling)
+
+Create a room for others to join (using short IDs):
+
+```typescript
+// Host a room
+const roomId = await rtc.createRoom('my-game-rooms');
+console.log(`Room created: ${roomId}`);
+
+// Handle join requests
+rtc.onRoomJoinRequest(async (req) => {
+  console.log(`User ${req.userId} wants to join`);
+  await rtc.acceptJoinRequest(roomId, req.id, 'my-game-rooms');
+});
+
+rtc.onConnection((conn) => {
+  console.log("New peer connected:", conn.id);
+});
+```
+
+Join a room:
+
+```typescript
+// Join a room
+try {
+  const conn = await rtc.joinRoom('ROOM_ID', 'my-game-rooms');
+  console.log("Joined room!");
+} catch (e) {
+  console.error("Join rejected or failed", e);
+}
+```

package/dist/Connection.d.ts

@@ -0,0 +1,35 @@
+export interface ConnectionOptions {
+    reliable?: boolean;
+}
+export declare class Connection {
+    private listeners;
+    private closeListeners;
+    private writer;
+    private reader;
+    private isClosed;
+    private receiveBuffer;
+    readonly id: string;
+    readonly deviceId: string;
+    constructor(id: string, deviceId: string, writer: WritableStreamDefaultWriter<Uint8Array>, reader: ReadableStreamDefaultReader<Uint8Array>);
+    /**
+     * Send a message to the other peer.
+     * Messages can be strings or objects (JSON stringified).
+     */
+    send(message: string | object | ArrayBuffer | Uint8Array): Promise<void>;
+    /**
+     * Disconnect the connection
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Listen for incoming messages
+     */
+    onMessage(callback: (message: any) => void): void;
+    /**
+     * Listen for disconnection
+     */
+    onDisconnect(callback: () => void): void;
+    private close;
+    private readLoop;
+    private handleData;
+    private emitMessage;
+}

package/dist/Connection.js

@@ -0,0 +1,146 @@
+export class Connection {
+    constructor(id, deviceId, writer, reader) {
+        this.listeners = [];
+        this.closeListeners = [];
+        // We'll keep track of the internal stream
+        this.writer = null;
+        this.reader = null;
+        this.isClosed = false;
+        // Buffer for incoming data
+        this.receiveBuffer = new Uint8Array(0);
+        this.id = id;
+        this.deviceId = deviceId;
+        this.writer = writer;
+        this.reader = reader;
+        this.readLoop();
+    }
+    /**
+     * Send a message to the other peer.
+     * Messages can be strings or objects (JSON stringified).
+     */
+    async send(message) {
+        if (this.isClosed || !this.writer) {
+            throw new Error('Connection is closed');
+        }
+        let payload;
+        if (typeof message === 'string') {
+            payload = new TextEncoder().encode(message);
+        }
+        else if (message instanceof Uint8Array) {
+            payload = message;
+        }
+        else if (message instanceof ArrayBuffer) {
+            payload = new Uint8Array(message);
+        }
+        else {
+            payload = new TextEncoder().encode(JSON.stringify(message));
+        }
+        // Framing: 4 bytes length (Big Endian) + payload
+        const frame = new Uint8Array(4 + payload.length);
+        const view = new DataView(frame.buffer);
+        view.setUint32(0, payload.length, false);
+        frame.set(payload, 4);
+        try {
+            await this.writer.write(frame);
+        }
+        catch (err) {
+            console.error('[Connection] Send error:', err);
+            this.close();
+            throw err;
+        }
+    }
+    /**
+     * Disconnect the connection
+     */
+    async disconnect() {
+        this.close();
+    }
+    /**
+     * Listen for incoming messages
+     */
+    onMessage(callback) {
+        this.listeners.push(callback);
+    }
+    /**
+     * Listen for disconnection
+     */
+    onDisconnect(callback) {
+        this.closeListeners.push(callback);
+    }
+    close() {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        // Close writer/reader
+        this.writer?.close().catch(() => { });
+        this.reader?.cancel().catch(() => { });
+        this.writer = null;
+        this.reader = null;
+        // Notify listeners
+        this.closeListeners.forEach(cb => cb());
+    }
+    async readLoop() {
+        if (!this.reader)
+            return;
+        try {
+            while (!this.isClosed) {
+                const { done, value } = await this.reader.read();
+                if (done) {
+                    this.close();
+                    break;
+                }
+                if (value) {
+                    this.handleData(value);
+                }
+            }
+        }
+        catch (err) {
+            console.error('[Connection] Read loop error:', err);
+            this.close();
+        }
+    }
+    handleData(chunk) {
+        // Append to buffer
+        const newBuffer = new Uint8Array(this.receiveBuffer.length + chunk.length);
+        newBuffer.set(this.receiveBuffer);
+        newBuffer.set(chunk, this.receiveBuffer.length);
+        this.receiveBuffer = newBuffer;
+        // Process messages
+        while (true) {
+            if (this.receiveBuffer.length < 4)
+                break; // Need at least length header
+            const view = new DataView(this.receiveBuffer.buffer, this.receiveBuffer.byteOffset, this.receiveBuffer.byteLength);
+            const length = view.getUint32(0, false);
+            if (this.receiveBuffer.length < 4 + length)
+                break; // Wait for full message
+            // Extract message
+            const messageData = this.receiveBuffer.slice(4, 4 + length);
+            this.receiveBuffer = this.receiveBuffer.slice(4 + length);
+            // Check if it's text/JSON
+            try {
+                const text = new TextDecoder().decode(messageData);
+                // Try to parse JSON, if it looks like object/array, return parsed
+                // Otherwise return string
+                try {
+                    const json = JSON.parse(text);
+                    if (typeof json === 'object' && json !== null) {
+                        this.emitMessage(json);
+                    }
+                    else {
+                        this.emitMessage(text);
+                    }
+                }
+                catch {
+                    this.emitMessage(text);
+                }
+            }
+            catch {
+                // Validation failed, send raw? For now assume it wraps text/json
+                this.emitMessage(messageData);
+            }
+        }
+    }
+    emitMessage(msg) {
+        this.listeners.forEach(cb => cb(msg));
+    }
+}

package/dist/ConnectionManager.d.ts

@@ -0,0 +1,38 @@
+import { ClientOptions } from './core/Client';
+import { Connection } from './core/Connection';
+import { JoinRequest } from './core/Room';
+/**
+ * @deprecated Use Client instead. This class is a backward-compatible wrapper.
+ */
+export declare class ConnectionManager {
+    private client;
+    constructor(options: ClientOptions);
+    get currentUser(): import("@firebase/auth").User | null;
+    onAuthChange(callback: (user: any) => void): void;
+    init(): Promise<void>;
+    connect(ticket: string): Promise<Connection>;
+    getConnections(): Connection[];
+    getTicket(): Promise<string>;
+    getNodeId(): Promise<string>;
+    startListening(): Promise<void>;
+    stopListening(): void;
+    searchDevices(): Promise<{
+        deviceId: string;
+        deviceName: string;
+        online: boolean;
+        ticket: string;
+    }[]>;
+    onDevicesChange(callback: any): () => void;
+    createRoom(): Promise<string>;
+    joinRoom(roomId: string): Promise<Connection[]>;
+    leaveRoom(roomId: string): Promise<void>;
+    onConnection(callback: (conn: Connection) => void): void;
+    onDisconnection(callback: (conn: Connection) => void): void;
+    onMessage(callback: (conn: Connection, msg: any) => void): void;
+    onRoomJoinRequest(callback: (request: JoinRequest) => void): void;
+    signInWithPluto(): void;
+    signOut(): Promise<void>;
+    signInAnonymously(): Promise<void>;
+}
+export * from './core/Connection';
+export * from './core/Client';

package/dist/ConnectionManager.js

@@ -0,0 +1,78 @@
+import { Client } from './core/Client';
+/**
+ * @deprecated Use Client instead. This class is a backward-compatible wrapper.
+ */
+export class ConnectionManager {
+    constructor(options) {
+        this.client = new Client(options);
+    }
+    get currentUser() {
+        return this.client.signaling.currentUser;
+    }
+    onAuthChange(callback) {
+        return this.client.signaling.onAuthChange(callback);
+    }
+    async init() {
+        return this.client.init();
+    }
+    async connect(ticket) {
+        return this.client.connect(ticket);
+    }
+    getConnections() {
+        return this.client.getConnections();
+    }
+    async getTicket() {
+        return this.client.getTicket();
+    }
+    async getNodeId() {
+        return this.client.getNodeId();
+    }
+    async startListening() {
+        return this.client.startListening();
+    }
+    stopListening() {
+        return this.client.stopListening();
+    }
+    // Discovery (delegated to Signaling)
+    async searchDevices() {
+        return this.client.signaling.searchDevices();
+    }
+    onDevicesChange(callback) {
+        return this.client.signaling.onDevicesChange(callback);
+    }
+    // Rooms (delegated to RoomManager)
+    async createRoom() {
+        return this.client.rooms.createRoom();
+    }
+    async joinRoom(roomId) {
+        return this.client.rooms.joinRoom(roomId);
+    }
+    async leaveRoom(roomId) {
+        return this.client.rooms.leaveRoom(roomId);
+    }
+    // Listeners
+    onConnection(callback) {
+        this.client.onConnection(callback);
+    }
+    onDisconnection(callback) {
+        this.client.onDisconnection(callback);
+    }
+    onMessage(callback) {
+        this.client.onMessage(callback);
+    }
+    onRoomJoinRequest(callback) {
+        this.client.onRoomJoinRequest(callback);
+    }
+    // Auth helpers
+    signInWithPluto() {
+        this.client.signaling.signInWithPluto();
+    }
+    async signOut() {
+        await this.client.signaling.signOut();
+    }
+    async signInAnonymously() {
+        await this.client.signaling.signInAnonymously();
+    }
+}
+export * from './core/Connection';
+export * from './core/Client'; // Export Client so users can switch

package/dist/api/MediaTransport.d.ts

@@ -0,0 +1,7 @@
+export declare class MediaTransport {
+    static sendTrack(track: MediaStreamTrack, sendFn: (data: Uint8Array) => Promise<void>): Promise<{
+        stop: () => void;
+        requestKeyFrame: () => void;
+    } | void>;
+    static receiveTrack(kind: 'audio' | 'video', onKeyFrameRequest?: () => void): MediaStreamTrack | null;
+}

package/dist/api/MediaTransport.js

@@ -0,0 +1,262 @@
+// Protocol-ish logic for transforming MediaStreamTracks into Chunks and back.
+// Since we don't have VideoEncoder/VideoDecoder in standard ts environment (it's web only),
+// we will just define the interfaces or classes here.
+// We use type 'any' for WebCodecs interfaces to avoid TS errors in environemnts without @types/dom-webcodecs
+export class MediaTransport {
+    // Encodes a track into the connection
+    static async sendTrack(track, sendFn) {
+        console.log(`[MediaTransport] sendTrack called for ${track.kind}`);
+        if ((typeof VideoEncoder === 'undefined') && (typeof AudioEncoder === 'undefined')) {
+            console.error("WebCodecs API not supported.");
+            return;
+        }
+        const processor = new window.MediaStreamTrackProcessor({ track });
+        const reader = processor.readable.getReader();
+        // Very basic encoder setup. 
+        // In reality we need to negotiate codecs. We assume VP8 for video and Opus for audio.
+        let encoder = null;
+        if (track.kind === 'video') {
+            let seqNum = 0;
+            encoder = new window.VideoEncoder({
+                output: (chunk, metadata) => {
+                    if (chunk.type === 'key') {
+                        console.log(`[MediaTransport] Generated KEY frame for video. Size: ${chunk.byteLength}`);
+                    }
+                    // console.log(`[MediaTransport] Encoded video chunk. Key: ${chunk.type}, Size: ${chunk.byteLength}`);
+                    // Send chunk
+                    // We need to serialize the chunk. 
+                    // [MAGIC 1b][timestamp 8 bytes][isKey 1 byte][seq 2 bytes][data...]
+                    const buffer = new ArrayBuffer(12 + chunk.byteLength);
+                    const view = new DataView(buffer);
+                    view.setUint8(0, 0x77); // Magic byte
+                    view.setBigInt64(1, BigInt(chunk.timestamp), false); // Big Endian
+                    view.setUint8(9, chunk.type === 'key' ? 1 : 0);
+                    const seq = (seqNum++) % 65536;
+                    view.setUint16(10, seq, false);
+                    const data = new Uint8Array(buffer);
+                    chunk.copyTo(new Uint8Array(buffer, 12));
+                    sendFn(data).catch(e => {
+                        const msg = (e.message || String(e)).toLowerCase();
+                        if (msg.includes("connection is closed") || msg.includes("connection closed") || msg.includes("sending stopped by peer")) {
+                            console.log(`[MediaTransport] Connection closed/stopped, stopping video encoder.`);
+                            if (encoder) {
+                                encoder.close();
+                                encoder = null;
+                            }
+                        }
+                        else {
+                            console.error("Send media failed", e);
+                        }
+                    });
+                },
+                error: (e) => console.error("VideoEncoder error", e)
+            });
+            encoder.configure({
+                codec: 'vp8',
+                width: 640,
+                height: 480,
+                bitrate: 500000, // 500 Kbps - Reduce congestion
+                framerate: 24, // slightly lower framerate
+                latencyMode: 'realtime', // Critical for low latency streaming
+            });
+        }
+        else if (track.kind === 'audio') {
+            encoder = new window.AudioEncoder({
+                output: (chunk, metadata) => {
+                    const buffer = new ArrayBuffer(9 + chunk.byteLength);
+                    const view = new DataView(buffer);
+                    view.setUint8(0, 0x77); // Magic
+                    view.setBigInt64(1, BigInt(chunk.timestamp), false);
+                    const data = new Uint8Array(buffer);
+                    chunk.copyTo(new Uint8Array(buffer, 9));
+                    sendFn(data).catch(e => {
+                        const msg = (e.message || String(e)).toLowerCase();
+                        if (msg.includes("connection is closed") || msg.includes("connection closed")) {
+                            console.log(`[MediaTransport] Connection closed, stopping audio encoder.`);
+                            if (encoder) {
+                                encoder.close();
+                                encoder = null;
+                            }
+                        }
+                        else {
+                            console.error("Send audio failed", e);
+                        }
+                    });
+                },
+                error: (e) => console.error("AudioEncoder error", e)
+            });
+            encoder.configure({
+                codec: 'opus',
+                sampleRate: 48000,
+                numberOfChannels: 1
+            });
+        }
+        // Read loop - Run asynchronously so we can return the controller immediately
+        (async () => {
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        console.log(`[MediaTransport] Reader done for ${track.kind}`);
+                        break;
+                    }
+                    if (value) {
+                        try {
+                            if (encoder && encoder.state !== 'closed') {
+                                const forceKey = encoder.forceKeyFrame;
+                                if (forceKey) {
+                                    console.log(`[MediaTransport] Forcing Key Frame now.`);
+                                    encoder.encode(value, { keyFrame: true });
+                                    encoder.forceKeyFrame = false;
+                                }
+                                else {
+                                    encoder.encode(value);
+                                }
+                            }
+                        }
+                        finally {
+                            value.close();
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                console.error(`[MediaTransport] Read loop error for ${track.kind}:`, e);
+            }
+        })();
+        // Return controller
+        return {
+            stop: () => {
+                // TODO: Close processor and reader
+            },
+            requestKeyFrame: () => {
+                if (encoder && encoder.state === 'configured') {
+                    console.log(`[MediaTransport] Key Frame Requested for ${track.kind}`);
+                    // We can't force it here directly because we are in a read loop.
+                    // But we can set a flag that the loop checks.
+                    encoder.forceKeyFrame = true;
+                }
+                else {
+                    console.warn(`[MediaTransport] Impossible to request KeyFrame: Encoder state is ${encoder?.state}`);
+                }
+            }
+        };
+    }
+    // Receives chunks and outputs a MediaStreamTrack
+    static receiveTrack(kind, onKeyFrameRequest) {
+        if ((typeof VideoDecoder === 'undefined') && (typeof AudioDecoder === 'undefined')) {
+            console.warn("WebCodecs API not supported.");
+            return null;
+        }
+        const generator = new window.MediaStreamTrackGenerator({ kind });
+        const writer = generator.writable.getWriter();
+        let decoder = null;
+        // Throttling for PLI
+        let lastPli = 0;
+        let expectedSeq = null;
+        if (kind === 'video') {
+            decoder = new window.VideoDecoder({
+                output: (frame) => {
+                    try {
+                        writer.write(frame);
+                    }
+                    finally {
+                        frame.close();
+                    }
+                },
+                error: (e) => console.error("VideoDecoder error", e)
+            });
+            decoder.configure({
+                codec: 'vp8'
+            });
+            // Force wait for key frame immediately
+            decoder.waitingForKeyFrame = true;
+        }
+        else {
+            decoder = new window.AudioDecoder({
+                output: (data) => {
+                    writer.write(data);
+                    data.close();
+                },
+                error: (e) => console.error("AudioDecoder error", e)
+            });
+            decoder.configure({
+                codec: 'opus',
+                sampleRate: 48000,
+                numberOfChannels: 1
+            });
+        }
+        // Attach a method to the track object or return a controller?
+        // We will just return the track, but we need a way to feed data into the decoder.
+        // We can monkey-patch the track or store it in a map in PeerConnection.
+        generator.feed = (data) => {
+            if (decoder.state === 'closed')
+                return;
+            // Verify Magic
+            if (data.byteLength < 1 || data[0] !== 0x77) {
+                console.error("[MediaTransport] Invalid magic byte in media stream! Dropping packet.");
+                return;
+            }
+            if (kind === 'video') {
+                // Parse
+                const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+                const timestamp = Number(view.getBigInt64(1, false));
+                const isKey = view.getUint8(9) === 1;
+                const seq = view.getUint16(10, false);
+                const chunkData = data.slice(12);
+                // Sequence Check
+                if (expectedSeq !== null) {
+                    if (seq !== expectedSeq) {
+                        console.warn(`[MediaTransport] Sequence Mismatch! Expected ${expectedSeq}, got ${seq}. Dropping and requesting PLI.`);
+                        decoder.waitingForKeyFrame = true;
+                        if (onKeyFrameRequest)
+                            onKeyFrameRequest();
+                        // We also reset expectedSeq to this new one + 1? 
+                        // No, we better wait for KeyFrame.
+                        // But we must update expectedSeq to avoid infinite loops if the stream just continues.
+                        expectedSeq = (seq + 1) % 65536;
+                        return;
+                    }
+                }
+                expectedSeq = (seq + 1) % 65536;
+                const chunk = new window.EncodedVideoChunk({
+                    type: isKey ? 'key' : 'delta',
+                    timestamp: timestamp,
+                    data: chunkData
+                });
+                if (decoder.state === 'configured' && !isKey && decoder.waitingForKeyFrame !== false) {
+                    // Drop delta frames until we get a keyframe
+                    const now = Date.now();
+                    if (now - lastPli > 1000) {
+                        console.log("[MediaTransport] Dropping delta frame, waiting for key frame. Requesting PLI.");
+                        if (onKeyFrameRequest)
+                            onKeyFrameRequest();
+                        lastPli = now;
+                    }
+                    return;
+                }
+                if (isKey) {
+                    decoder.waitingForKeyFrame = false;
+                }
+                try {
+                    decoder.decode(chunk);
+                }
+                catch (e) {
+                    console.error("[MediaTransport] Decode error:", e);
+                }
+            }
+            else {
+                const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+                const timestamp = Number(view.getBigInt64(1, false));
+                const chunkData = data.slice(9);
+                const chunk = new window.EncodedAudioChunk({
+                    type: 'key', // Audio usually all key frames or dependent? Opus is complicated.
+                    timestamp: timestamp,
+                    data: chunkData
+                });
+                decoder.decode(chunk);
+            }
+        };
+        return generator;
+    }
+}

package/dist/api/PlutoPeerConnection.d.ts

@@ -0,0 +1,38 @@
+import { Client } from '../core/Client';
+import { Connection } from '../core/Connection';
+export declare class PlutoPeerConnection extends EventTarget {
+    static defaultClient: Client | null;
+    static setDefaultClient(client: Client): void;
+    onicecandidate: ((ev: RTCPeerConnectionIceEvent) => any) | null;
+    oniceconnectionstatechange: ((ev: Event) => any) | null;
+    ontrack: ((ev: RTCTrackEvent) => any) | null;
+    onsignalingstatechange: ((ev: Event) => any) | null;
+    connectionState: RTCPeerConnectionState;
+    iceConnectionState: RTCIceConnectionState;
+    signalingState: RTCSignalingState;
+    localDescription: RTCSessionDescription | null;
+    remoteDescription: RTCSessionDescription | null;
+    private client;
+    private connection;
+    constructor(configuration?: RTCConfiguration, clientInstance?: Client);
+    createOffer(options?: RTCOfferOptions): Promise<RTCSessionDescriptionInit>;
+    createAnswer(options?: RTCAnswerOptions): Promise<RTCSessionDescriptionInit>;
+    setLocalDescription(desc: RTCSessionDescriptionInit): Promise<void>;
+    setRemoteDescription(desc: RTCSessionDescriptionInit): Promise<void>;
+    addIceCandidate(candidate: RTCIceCandidateInit | RTCIceCandidate): Promise<void>;
+    /**
+     * Manually provide an existing connection (e.g. from an incoming connection listener)
+     */
+    private bufferTracks;
+    handleIncomingConnection(connection: Connection): Promise<void>;
+    private receivers;
+    private setupHooks;
+    addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender;
+    private mediaSenders;
+    private startIrohStream;
+    createDataChannel(label: string): RTCDataChannel;
+    sendData(data: any): void;
+    private connect;
+    close(): void;
+    private updateState;
+}