WebRTC-based peer-to-peer mesh networking with intelligent routing, encrypted storage, and media streaming.
PeerPigeon is a production-ready library for building decentralized applications with true mesh networking, encrypted distributed storage, and selective media streaming. It handles peer discovery, connection management, and message routing automatically.
β οΈ IMPORTANT: Local Testing Requirement
When testing onlocalhost, WebRTC connections require media permissions (microphone/camera) due to browser security.
Solution: Click the "Media" tab in the browser example and grant permissions, or see docs/LOCAL_TESTING.md for details.
This is NOT required for production HTTPS deployments.
- πΈοΈ True Mesh Networking - Gossip protocol + XOR distance routing (Kademlia-inspired)
- π Network Namespaces - Isolated peer networks with automatic global fallback
- ποΈ Distributed Storage - Encrypted, CRDT-enabled storage across the mesh
- π₯ Selective Streaming - Efficient audio/video streaming with bandwidth management
- π¦ Binary Messages - Native support for efficient binary data transfer (Uint8Array/ArrayBuffer)
- οΏ½ Stream API - Transfer large files with ReadableStream/WritableStream (memory-efficient, backpressure handling)
- οΏ½π’ Hub System - Connect multiple signaling servers for global peer discovery
- π End-to-End Encryption - Built-in crypto for secure communication
- π° Cost Optimized - Smart routing reduces server costs by ~95%
- π± Multi-Platform - Browser, Node.js, NativeScript support
npm install peerpigeonimport { PeerPigeonMesh } from 'peerpigeon';
// Create and connect
const mesh = new PeerPigeonMesh({ enableWebDHT: true, enableCrypto: true });
await mesh.init();
await mesh.connect('ws://localhost:3000');
// Send messages
mesh.sendMessage('Hello, mesh!');
// Listen for messages
mesh.on('messageReceived', ({ from, content }) => {
console.log(`${from}: ${content}`);
});# Start both hub and HTTP server for testing
npm run dev
# Or run them separately:
npm run dev:hub # Just the signaling hub
npm run dev:http # Just the HTTP server
# Custom port
PORT=8080 npm run hubFor localhost testing, you need to grant media permissions:
- Open browser example:
http://localhost:8080/ - Go to Media tab
- Click Start Media button
- Allow microphone/camera access
See docs/LOCAL_TESTING.md for full details.
// Send a file using streams (memory-efficient for large files)
const file = fileInput.files[0];
await mesh.sendFile(targetPeerId, file);
// Receive files
mesh.on('streamReceived', async (event) => {
const { stream, metadata } = event;
console.log(`Receiving ${metadata.filename} (${metadata.totalSize} bytes)`);
// Read stream and create blob
const chunks = [];
const reader = stream.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
chunks.push(value);
}
const blob = new Blob(chunks, { type: metadata.mimeType });
// Download file
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = metadata.filename;
a.click();
});// Send binary data to specific peer
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
await mesh.sendBinaryData(targetPeerId, binaryData);
// Broadcast binary to all peers
const count = await mesh.broadcastBinaryData(binaryData);
// Receive binary messages
mesh.on('binaryMessageReceived', ({ from, data, size }) => {
console.log(`Received ${size} bytes from ${from}`);
// data is Uint8Array
});
// Send files
const file = fileInput.files[0];
const buffer = await file.arrayBuffer();
await mesh.sendBinaryData(peerId, new Uint8Array(buffer));// Store encrypted data across the mesh
await mesh.storage.put('myKey', { data: 'value' });
// Retrieve from any peer
const value = await mesh.storage.get('myKey');
// Storage spaces for organization
const chatSpace = mesh.storage.getSpace('chat');
await chatSpace.put('message1', { text: 'Hello!' });// Get local media
const stream = await navigator.mediaDevices.getUserMedia({
video: true,
audio: true
});
// Selective streaming to specific peers
mesh.media.addLocalStream(stream, 'camera');
mesh.media.streamToPeer('peer-id-1', 'camera', { video: true, audio: true });
mesh.media.streamToPeer('peer-id-2', 'camera', { video: false, audio: true }); // Audio only
// Receive streams
mesh.media.on('remoteStreamAdded', ({ peerId, stream, label }) => {
videoElement.srcObject = stream;
});// Create isolated networks
const gameMesh = new PeerPigeonMesh({ networkName: 'game-lobby-1' });
const chatMesh = new PeerPigeonMesh({ networkName: 'chat-room-5' });
// Peers in different networks won't see each other
await gameMesh.connect('ws://localhost:3000');
await chatMesh.connect('ws://localhost:3000');// Server 1 (bootstrap hub on port 3000)
const hub1 = new PeerPigeonServer({
port: 3000,
isHub: true
});
await hub1.start();
// Server 2 connects to hub1
const hub2 = new PeerPigeonServer({
port: 3001,
isHub: true,
bootstrapHubs: ['ws://localhost:3000']
});
await hub2.start();
// Peers on hub2 can discover peers on hub1!- API Documentation - Complete API reference
- CLI Guide - Command-line interface
- Binary Messages - Efficient binary data transfer
- Streaming API - Large file transfers with ReadableStream/WritableStream
- Network Namespaces - Isolated peer networks
- Selective Streaming - Media streaming optimization
- Hub System Overview - Multi-server mesh architecture
- Hub Quick Reference - Quick start guide for hubs
- Hub Scripts - Hub automation scripts
- Bootstrap Hubs - Hub discovery and connection
- Browser Examples - Web applications
- Binary Message Demo - Interactive binary transfer demo
- Stream File Transfer Demo - Large file transfer with progress
- Node.js Examples - Server-side usage
- NativeScript Examples - Mobile apps
PeerPigeon uses a modular architecture with smart routing:
βββββββββββββββββββββββββββββββββββββββββββββββ
β PeerPigeonMesh (Core) β
βββββββββββββββββββββββββββββββββββββββββββββββ€
β β’ SignalingClient β’ PeerDiscovery β
β β’ ConnectionManager β’ EvictionManager β
β β’ GossipManager β’ MeshOptimizer β
β β’ StorageManager β’ MediaManager β
βββββββββββββββββββββββββββββββββββββββββββββββ
β β
βΌ βΌ
ββββββββββββββββ ββββββββββββββββ
β WebSocket β β WebRTC β
β Signaling β β DataChannel β
ββββββββββββββββ ββββββββββββββββ
Key Components:
- XOR Distance Routing - Kademlia-inspired peer selection
- Gossip Protocol - Reliable message propagation
- Smart Eviction - Automatically optimizes mesh topology
- CRDT Storage - Conflict-free distributed data structures
const mesh = new PeerPigeonMesh({
// Core options
peerId: 'custom-peer-id', // Custom peer ID (40-char hex)
networkName: 'my-network', // Network namespace (default: 'global')
allowGlobalFallback: true, // Allow fallback to global network
// Features (all enabled by default)
enableWebDHT: true, // Distributed hash table
enableCrypto: true, // Encryption & key management
// Connection settings
maxPeers: 3, // Max concurrent connections
minPeers: 2, // Min connections to maintain
autoConnect: true, // Auto-connect on join
autoDiscovery: true, // Auto-discover peers
// Topology optimization
evictionStrategy: true, // Smart peer eviction
xorRouting: true // XOR distance-based routing
});# Run all tests
npm test
# Browser integration tests
npm run test:browser
npm run test:browser:visual # With visible browser
# Video streaming tests
npm run test:video
npm run test:video:visual # With visible browserContributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.
MIT Β© Daniel Raeder
- GitHub: github.com/PeerPigeon/PeerPigeon
- npm: npmjs.com/package/peerpigeon
- Issues: github.com/PeerPigeon/PeerPigeon/issues
Built with β€οΈ for the decentralized web