@peers-app/peers-sdk 0.27.4 → 0.28.0

package/dist/device/binary-peer-connection.js

@@ -1,516 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createBinaryPeerSocket = createBinaryPeerSocket;
-exports.wrapBinaryPeer = wrapBinaryPeer;
-exports.wrapWrtc = wrapWrtc;
-const msgpack_1 = require("@msgpack/msgpack");
-const utils_1 = require("../utils");
-const connection_1 = require("./connection");
-const get_trust_level_fn_1 = require("./get-trust-level-fn");
-const streamed_socket_1 = require("./streamed-socket");
-const tx_encoding_1 = require("./tx-encoding");
-// Protocol discriminator bytes for multiplexing RPC and raw byte streams
-const PROTOCOL_RPC = 0x00;
-const PROTOCOL_RAW_BYTES = 0x01;
-// Threshold for routing large RPC messages through raw bytes streaming.
-// Messages larger than this are sent via the __rpc raw bytes stream,
-// automatically chunked to fit transport limits with backpressure.
-const LARGE_MESSAGE_THRESHOLD = 64 * 1024; // 64KB
-// Transport-specific chunk sizes for the __rpc raw bytes path.
-// Must stay under the SCTP single-message limit (~256KB practical max).
-const RPC_CHUNK_SIZE_WRTC = 16 * 1024; // 16KB for WebRTC (fits in Unix socket kernel buffer)
-const RPC_CHUNK_SIZE_DEFAULT = 512 * 1024; // 512KB for WebSocket
-// Reserved stream ID for RPC messages sent via raw bytes
-const RPC_STREAM_ID = "__rpc";
-// Flags for __rpc stream chunking protocol:
-// Each message on the __rpc stream starts with a 1-byte flag.
-const RPC_FLAG_SINGLE = 0x00; // [0x00][encoded message] - complete in one message
-const RPC_FLAG_START = 0x01; // [0x01][4 bytes: totalSize][chunk data] - first chunk
-const RPC_FLAG_CONT = 0x02; // [0x02][chunk data] - continuation chunk
-// Cache for encoded stream IDs to avoid TextEncoder allocation on every send/receive
-const streamIdBytesCache = new Map();
-function getStreamIdBytes(streamId) {
-    let cached = streamIdBytesCache.get(streamId);
-    if (!cached) {
-        cached = new TextEncoder().encode(streamId);
-        streamIdBytesCache.set(streamId, cached);
-    }
-    return cached;
-}
-// Reverse cache: decode stream IDs from raw bytes without re-creating TextDecoder
-const streamIdStringCache = new Map();
-function decodeStreamId(bytes) {
-    // Build a key that uniquely identifies the byte content to avoid collisions
-    let key = `${bytes.length}`;
-    for (let i = 0; i < bytes.length; i++) {
-        key += `:${bytes[i]}`;
-    }
-    let cached = streamIdStringCache.get(key);
-    if (cached !== undefined)
-        return cached;
-    cached = new TextDecoder().decode(bytes);
-    streamIdStringCache.set(key, cached);
-    return cached;
-}
-// Encode message metadata + data into a single Uint8Array
-function encodeMessage(message) {
-    // Check if args/result is a Uint8Array - if so, flag it to keep it as raw bytes
-    let isUint8ArrayData = false;
-    if (message.type === "call" && message.args instanceof Uint8Array) {
-        isUint8ArrayData = true;
-    }
-    else if (message.type === "callback" && message.result instanceof Uint8Array) {
-        isUint8ArrayData = true;
-    }
-    // Encode metadata using msgpack (without args/result/error - those go in data)
-    const metadata = {
-        type: message.type,
-        callbackId: message.callbackId,
-        ...(message.eventName !== undefined && { eventName: message.eventName }),
-        ...(isUint8ArrayData && { isUint8ArrayData: true }),
-    };
-    const metadataBytes = (0, msgpack_1.encode)(metadata);
-    const metadataLength = metadataBytes.length;
-    // Encode the data payload (args, result, or error)
-    let dataBytes;
-    if (message.type === "call" && message.args !== undefined) {
-        // If args is already a Uint8Array, use it directly without txEncode
-        if (isUint8ArrayData) {
-            dataBytes = message.args;
-        }
-        else {
-            dataBytes = (0, tx_encoding_1.txEncode)(message.args);
-        }
-    }
-    else if (message.type === "callback") {
-        if (message.error !== undefined) {
-            dataBytes = (0, tx_encoding_1.txEncode)({ error: message.error });
-        }
-        else if (isUint8ArrayData) {
-            // If result is a Uint8Array, use it directly
-            dataBytes = message.result;
-        }
-        else {
-            dataBytes = (0, tx_encoding_1.txEncode)({ result: message.result });
-        }
-    }
-    else {
-        dataBytes = new Uint8Array(0);
-    }
-    // Create combined buffer: [4 bytes length][metadata][data]
-    const combined = new Uint8Array(4 + metadataLength + dataBytes.length);
-    // Write metadata length as 32-bit unsigned integer (big-endian)
-    const view = new DataView(combined.buffer, combined.byteOffset, combined.byteLength);
-    view.setUint32(0, metadataLength, false); // big-endian
-    // Write metadata
-    combined.set(metadataBytes, 4);
-    // Write data
-    combined.set(dataBytes, 4 + metadataLength);
-    return combined;
-}
-// Decode binary message back into IMessage
-function decodeMessage(bytes) {
-    // Read metadata length
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    const metadataLength = view.getUint32(0, false); // big-endian
-    // Extract metadata
-    const metadataBytes = bytes.subarray(4, 4 + metadataLength);
-    const metadata = (0, msgpack_1.decode)(metadataBytes);
-    // Extract data
-    const dataBytes = bytes.subarray(4 + metadataLength);
-    const message = {
-        type: metadata.type,
-        callbackId: metadata.callbackId,
-        eventName: metadata.eventName,
-    };
-    // Decode the data payload
-    if (dataBytes.length > 0) {
-        if (message.type === "call") {
-            // If it was a Uint8Array, use it directly without txDecode
-            if (metadata.isUint8ArrayData) {
-                message.args = dataBytes;
-            }
-            else {
-                message.args = (0, tx_encoding_1.txDecode)(dataBytes);
-            }
-        }
-        else if (message.type === "callback") {
-            if (metadata.isUint8ArrayData) {
-                // If it was a Uint8Array result, use it directly
-                message.result = dataBytes;
-            }
-            else {
-                const decoded = (0, tx_encoding_1.txDecode)(dataBytes);
-                if (decoded.error !== undefined) {
-                    message.error = decoded.error;
-                }
-                else {
-                    message.result = decoded.result;
-                }
-            }
-        }
-    }
-    return message;
-}
-const DEFAULT_RECEIVE_LIMITS = Object.freeze({
-    maxRpcMessageBytes: 256 * 1024 * 1024,
-    maxStreamMessageBytes: 256 * 1024 * 1024,
-    reassemblyTimeoutMs: 30_000,
-});
-/**
- * Creates an ISocket from a binary peer without creating a full Connection.
- * Useful when you need to pass custom localServerAddresses to the Connection.
- */
-function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receiveLimitOverrides = {}) {
-    const handlers = {};
-    const callbacks = {};
-    const rawBytesHandlers = {};
-    let isClosed = false;
-    const stats = (0, streamed_socket_1.createSocketStats)();
-    const receiveLimits = { ...DEFAULT_RECEIVE_LIMITS, ...receiveLimitOverrides };
-    for (const [name, value] of Object.entries(receiveLimits)) {
-        if (!Number.isSafeInteger(value) || value <= 0) {
-            throw new Error(`Invalid binary peer receive limit ${name}: ${value}`);
-        }
-    }
-    // Map protocol string to TransportType (needed early for threshold calculations)
-    const transportType = protocol === "wrtc" ? "wrtc" : protocol === "ws" ? "ws" : "unknown";
-    // Transport-specific thresholds (computed once)
-    const HIGH_WATER_MARK = transportType === "wrtc" ? 128 * 1024 : 4 * 1024 * 1024;
-    const LOW_WATER_MARK = transportType === "wrtc" ? 32 * 1024 : 2 * 1024 * 1024;
-    const RPC_CHUNK_SIZE = transportType === "wrtc" ? RPC_CHUNK_SIZE_WRTC : RPC_CHUNK_SIZE_DEFAULT;
-    // Core sendRawBytes implementation - defined early so sendRPCData can use it
-    const sendRawBytesImpl = async (streamId, data) => {
-        const sidBytes = getStreamIdBytes(streamId);
-        const headerLen = 1 + 2 + sidBytes.length;
-        const packet = new Uint8Array(headerLen + data.length);
-        packet[0] = PROTOCOL_RAW_BYTES;
-        const view = new DataView(packet.buffer, packet.byteOffset, packet.byteLength);
-        view.setUint16(1, sidBytes.length, false);
-        packet.set(sidBytes, 3);
-        packet.set(data, headerLen);
-        // Backpressure: wait for buffer to drain before sending more
-        if (peer.getBufferedAmount && peer.getBufferedAmount() > HIGH_WATER_MARK) {
-            await new Promise((resolve) => {
-                const checkDrain = () => {
-                    if (!peer.getBufferedAmount || peer.getBufferedAmount() < LOW_WATER_MARK) {
-                        resolve();
-                    }
-                    else {
-                        setTimeout(checkDrain, 5);
-                    }
-                };
-                peer.on("drain", resolve);
-                checkDrain();
-            });
-        }
-        stats.bytesSent += packet.length;
-        stats.messagesSent++;
-        peer.send(packet);
-    };
-    // Serialize large RPC sends so chunked messages don't interleave
-    let rpcSendQueue = Promise.resolve();
-    // Helper to send RPC messages - routes large messages through raw bytes streaming
-    // with automatic chunking to stay within transport single-message limits.
-    const sendRPCData = (encoded) => {
-        if (encoded.length <= LARGE_MESSAGE_THRESHOLD) {
-            // Small message: send directly via PROTOCOL_RPC (no chunking needed)
-            const withProtocol = new Uint8Array(1 + encoded.length);
-            withProtocol[0] = PROTOCOL_RPC;
-            withProtocol.set(encoded, 1);
-            stats.bytesSent += withProtocol.length;
-            stats.messagesSent++;
-            peer.send(withProtocol);
-            return Promise.resolve();
-        }
-        if (encoded.length <= RPC_CHUNK_SIZE) {
-            // Fits in one raw bytes message: send with SINGLE flag
-            const msg = new Uint8Array(1 + encoded.length);
-            msg[0] = RPC_FLAG_SINGLE;
-            msg.set(encoded, 1);
-            return sendRawBytesImpl(RPC_STREAM_ID, msg);
-        }
-        // Large message: chunk it. Serialize through queue to prevent interleaving.
-        const sendChunked = async () => {
-            // First chunk: [FLAG_START][4 bytes totalSize][chunk data]
-            const firstChunkDataSize = Math.min(RPC_CHUNK_SIZE - 5, encoded.length); // 5 = 1 flag + 4 size
-            const firstMsg = new Uint8Array(5 + firstChunkDataSize);
-            firstMsg[0] = RPC_FLAG_START;
-            const view = new DataView(firstMsg.buffer, firstMsg.byteOffset, firstMsg.byteLength);
-            view.setUint32(1, encoded.length, false);
-            firstMsg.set(encoded.subarray(0, firstChunkDataSize), 5);
-            await sendRawBytesImpl(RPC_STREAM_ID, firstMsg);
-            // Continuation chunks: [FLAG_CONT][chunk data]
-            let offset = firstChunkDataSize;
-            while (offset < encoded.length) {
-                const end = Math.min(offset + RPC_CHUNK_SIZE - 1, encoded.length); // 1 = flag byte
-                const contMsg = new Uint8Array(1 + (end - offset));
-                contMsg[0] = RPC_FLAG_CONT;
-                contMsg.set(encoded.subarray(offset, end), 1);
-                await sendRawBytesImpl(RPC_STREAM_ID, contMsg);
-                offset = end;
-            }
-        };
-        rpcSendQueue = rpcSendQueue.then(sendChunked, sendChunked);
-        return rpcSendQueue;
-    };
-    // Reassembly state for chunked __rpc messages
-    let rpcReassemblyBuffer = null;
-    let rpcReassemblyOffset = 0;
-    let rpcReassemblyTimer;
-    function clearRpcReassembly() {
-        if (rpcReassemblyTimer) {
-            clearTimeout(rpcReassemblyTimer);
-            rpcReassemblyTimer = undefined;
-        }
-        rpcReassemblyBuffer = null;
-        rpcReassemblyOffset = 0;
-    }
-    function closeForProtocolViolation(reason) {
-        if (isClosed) {
-            return;
-        }
-        console.warn(`Closing ${protocol} peer after binary protocol violation: ${reason}`);
-        isClosed = true;
-        clearRpcReassembly();
-        socket.connected = false;
-        peer.destroy();
-    }
-    // Handle incoming data
-    peer.on("data", async (data) => {
-        try {
-            const bytes = new Uint8Array(data);
-            stats.bytesReceived += bytes.length;
-            stats.messagesReceived++;
-            if (bytes.length === 0)
-                return;
-            const protocolType = bytes[0];
-            // Handle raw bytes stream
-            if (protocolType === PROTOCOL_RAW_BYTES) {
-                if (bytes.length < 3)
-                    return;
-                const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-                const streamIdLength = view.getUint16(1, false);
-                if (bytes.length < 3 + streamIdLength)
-                    return;
-                const streamIdBytes = bytes.subarray(3, 3 + streamIdLength);
-                const streamId = decodeStreamId(streamIdBytes);
-                const payload = bytes.subarray(3 + streamIdLength);
-                if (payload.length > receiveLimits.maxStreamMessageBytes) {
-                    closeForProtocolViolation("raw stream frame exceeds the message-size limit");
-                    return;
-                }
-                // Check if this is an RPC message sent via raw bytes (for large payloads)
-                if (streamId === RPC_STREAM_ID) {
-                    if (payload.length === 0)
-                        return;
-                    const flag = payload[0];
-                    if (flag === RPC_FLAG_SINGLE) {
-                        // Complete message in one raw bytes send
-                        if (payload.length - 1 > receiveLimits.maxRpcMessageBytes) {
-                            closeForProtocolViolation("complete RPC exceeds the message-size limit");
-                            return;
-                        }
-                        handleRPCMessage(payload.subarray(1), handlers, callbacks, sendRPCData);
-                    }
-                    else if (flag === RPC_FLAG_START) {
-                        // First chunk of a multi-part message
-                        if (payload.length < 5)
-                            return; // flag + 4 bytes size minimum
-                        const totalSize = new DataView(payload.buffer, payload.byteOffset + 1, 4).getUint32(0, false);
-                        const chunkData = payload.subarray(5);
-                        if (totalSize === 0 ||
-                            totalSize > receiveLimits.maxRpcMessageBytes ||
-                            chunkData.length > totalSize ||
-                            rpcReassemblyBuffer) {
-                            closeForProtocolViolation("invalid, duplicate, or oversized RPC start frame");
-                            return;
-                        }
-                        rpcReassemblyBuffer = new Uint8Array(totalSize);
-                        rpcReassemblyOffset = 0;
-                        rpcReassemblyBuffer.set(chunkData, 0);
-                        rpcReassemblyOffset = chunkData.length;
-                        rpcReassemblyTimer = setTimeout(() => closeForProtocolViolation("RPC reassembly timed out"), receiveLimits.reassemblyTimeoutMs);
-                        rpcReassemblyTimer.unref?.();
-                        // Check if this single START chunk completes the message (unlikely but safe)
-                        if (rpcReassemblyOffset === totalSize) {
-                            handleRPCMessage(rpcReassemblyBuffer, handlers, callbacks, sendRPCData);
-                            clearRpcReassembly();
-                        }
-                    }
-                    else if (flag === RPC_FLAG_CONT) {
-                        // Continuation chunk
-                        if (!rpcReassemblyBuffer)
-                            return; // no START received, discard
-                        const chunkData = payload.subarray(1);
-                        if (chunkData.length > rpcReassemblyBuffer.length - rpcReassemblyOffset) {
-                            closeForProtocolViolation("RPC continuation exceeds declared size");
-                            return;
-                        }
-                        rpcReassemblyBuffer.set(chunkData, rpcReassemblyOffset);
-                        rpcReassemblyOffset += chunkData.length;
-                        if (rpcReassemblyOffset === rpcReassemblyBuffer.length) {
-                            handleRPCMessage(rpcReassemblyBuffer, handlers, callbacks, sendRPCData);
-                            clearRpcReassembly();
-                        }
-                    }
-                    else {
-                        // Legacy/unknown: treat entire payload as a complete RPC message
-                        // (backwards compat with code before chunking was added)
-                        if (payload.length > receiveLimits.maxRpcMessageBytes) {
-                            closeForProtocolViolation("legacy RPC exceeds the message-size limit");
-                            return;
-                        }
-                        handleRPCMessage(payload, handlers, callbacks, sendRPCData);
-                    }
-                    return;
-                }
-                const handler = rawBytesHandlers[streamId];
-                if (handler)
-                    handler(payload);
-                return;
-            }
-            // Handle RPC messages
-            if (protocolType === PROTOCOL_RPC) {
-                const rpcBytes = bytes.subarray(1);
-                if (rpcBytes.length > receiveLimits.maxRpcMessageBytes) {
-                    closeForProtocolViolation("complete RPC exceeds the message-size limit");
-                    return;
-                }
-                handleRPCMessage(rpcBytes, handlers, callbacks, sendRPCData);
-                return;
-            }
-            // Legacy format (no discriminator) for backwards compatibility
-            if (bytes.length > receiveLimits.maxRpcMessageBytes) {
-                closeForProtocolViolation("legacy RPC exceeds the message-size limit");
-                return;
-            }
-            handleRPCMessage(bytes, handlers, callbacks, sendRPCData);
-        }
-        catch (err) {
-            console.error(`Error parsing ${protocol} message:`, err);
-        }
-    });
-    // Handle closure
-    peer.on("close", () => {
-        if (isClosed)
-            return;
-        isClosed = true;
-        clearRpcReassembly();
-        socket.connected = false;
-    });
-    const socket = {
-        id: connectionId,
-        connected: true,
-        handlesOwnEncoding: true,
-        transportType,
-        stats,
-        emit(eventName, args, callback) {
-            const callbackId = (0, utils_1.newid)();
-            callbacks[callbackId] = callback;
-            const message = { type: "call", eventName, args, callbackId };
-            const encoded = encodeMessage(message);
-            sendRPCData(encoded);
-        },
-        on(eventName, handler) {
-            handlers[eventName] = handler;
-        },
-        removeAllListeners(eventName) {
-            if (eventName) {
-                delete handlers[eventName];
-            }
-            else {
-                for (const key of Object.keys(handlers)) {
-                    delete handlers[key];
-                }
-            }
-        },
-        disconnect() {
-            peer.destroy();
-        },
-        sendRawBytes: sendRawBytesImpl,
-        onRawBytes(streamId, handler) {
-            rawBytesHandlers[streamId] = handler;
-        },
-        removeRawBytesHandler(streamId) {
-            delete rawBytesHandlers[streamId];
-        },
-    };
-    return socket;
-}
-// Helper to handle RPC message parsing
-// sendRPCData automatically routes large messages through raw bytes streaming
-function handleRPCMessage(bytes, handlers, callbacks, sendRPCData) {
-    const message = decodeMessage(bytes);
-    if (message.type === "callback") {
-        const callback = callbacks[message.callbackId];
-        if (callback) {
-            delete callbacks[message.callbackId];
-            callback(message.error, message.result);
-        }
-        return;
-    }
-    if (message.type === "call") {
-        const eventName = message.eventName;
-        const handler = eventName ? handlers[eventName] : undefined;
-        if (!handler) {
-            console.warn(eventName ? `No handler for event: ${eventName}` : "RPC call did not include an event name");
-            return;
-        }
-        try {
-            const callback = (err, result) => {
-                const responseMessage = {
-                    type: "callback",
-                    callbackId: message.callbackId,
-                };
-                if (err)
-                    responseMessage.error = err;
-                else
-                    responseMessage.result = result;
-                const encoded = encodeMessage(responseMessage);
-                // Use sendRPCData which auto-routes large responses through raw bytes
-                sendRPCData(encoded);
-            };
-            handler(message.args, callback);
-        }
-        catch (error) {
-            console.error("Error in handler", { eventName: message.eventName, error });
-            const errorMessage = {
-                type: "callback",
-                callbackId: message.callbackId,
-                error: error.message,
-            };
-            const encoded = encodeMessage(errorMessage);
-            sendRPCData(encoded);
-        }
-    }
-}
-/**
- * Wraps a binary peer (WebRTC or WebSocket) into a Connection.
- * This is the main implementation that handles all binary protocols.
- */
-function wrapBinaryPeer(connectionId, peer, localDevice, initiator, options, getTrustLevel) {
-    const { protocol, markTransportSecure, receiveLimits } = options;
-    // Create the socket wrapper using shared implementation
-    const socket = createBinaryPeerSocket(connectionId, peer, protocol, receiveLimits);
-    const serverAddress = `${protocol}://${connectionId}`;
-    const localServerAddresses = initiator ? undefined : [serverAddress];
-    if (process.env.NODE_ENV !== "test") {
-        getTrustLevel ??= (0, get_trust_level_fn_1.getTrustLevelFn)(localDevice, serverAddress);
-    }
-    const connection = new connection_1.Connection(socket, localDevice, localServerAddresses, getTrustLevel);
-    // Mark transport as secure if applicable (WebRTC DTLS-SRTP, wss)
-    if (markTransportSecure) {
-        connection.secureLocal = true;
-        connection.secureRemote = true;
-    }
-    return connection;
-}
-/**
- * Wraps a WebRTC peer into a Connection.
- * Backwards-compatible wrapper around wrapBinaryPeer.
- * WebRTC is encrypted at the transport layer (DTLS-SRTP), so we skip application-level encryption.
- */
-function wrapWrtc(connectionId, peer, localDevice, initiator, getTrustLevel, receiveLimits) {
-    return wrapBinaryPeer(connectionId, peer, localDevice, initiator, { protocol: "wrtc", markTransportSecure: true, receiveLimits }, getTrustLevel);
-}

package/dist/device/streamed-socket.d.ts

@@ -1,23 +0,0 @@
-import { type ISocket, type ISocketStats, type RPCCallback } from "./socket.type";
-/** Creates a new stats object for tracking socket throughput */
-export declare function createSocketStats(): ISocketStats;
-export declare class StreamedSocket implements ISocket {
-    readonly socket: ISocket;
-    maxChunkSize: number;
-    readonly safeSocketChunkEventName = "__streamed-socket-chunk";
-    readonly safeSocketResponseEventName = "__streamed-socket-response";
-    readonly stats: ISocketStats;
-    constructor(socket: ISocket, maxChunkSize?: number);
-    get id(): string | undefined;
-    get connected(): boolean | undefined;
-    disconnect(close?: boolean): void;
-    private readonly callbacks;
-    emit(eventName: string, args: any, callback: RPCCallback): void;
-    private handlers;
-    on(eventName: string, handler: (...args: any[]) => void): void;
-    removeAllListeners(eventName: string): void;
-    private readonly chunkBuffers;
-    private handleChunk;
-    private processChunks;
-    private handleResponse;
-}