@eden_labs/branch

Servidor de sinalizacao para redes P2P mesh. Gerencia descoberta de peers, sinalizacao para NAT hole punching e entrega de mensagens entre peers online.

Instalacao

npm install @eden_labs/branch

Uso rapido

import { WebSocketServer } from 'ws'
import { createSignalingServer } from '@eden_labs/branch'

const wss = new WebSocketServer({ port: 8080 })
await createSignalingServer({ wss })

Opcoes

await createSignalingServer({
  wss,                        // WebSocketServer (obrigatorio)
  storage: fileStorage,       // implementacao de persistencia (default: fileStorage)
  maxPeers: 50,               // max peers retornados no joined (default: 50)
  cleanupTTL: 7 * 24 * 3600000, // tempo (ms) sem contato antes de remover peer
  cleanupInterval: 3600000,   // intervalo (ms) entre limpezas periodicas
})

Retorno

const server = await createSignalingServer({ wss })

server.getOnline()    // Map<peerId, { ws, endpoint }> — peers conectados agora
server.getKnown()     // Map<peerId, { publicKey, lastSeen }> — todos os peers persistidos
server.cleanup()      // executa limpeza manual de peers expirados
server.stopCleanup()  // para o timer de limpeza periodica

Protocolo

Descoberta de peers

cliente -> servidor:  { type: "join", peerId, publicKey }
servidor -> cliente:  { type: "joined", peers: [{ peerId, publicKey }] }
servidor -> broadcast: { type: "peer_connected", peerId, publicKey }
servidor -> broadcast: { type: "peer_disconnected", peerId }

Sinalizacao P2P

cliente -> servidor:  { type: "register", peerId, endpoint: { host, port } }
servidor -> cliente:  { type: "registered" }

cliente -> servidor:  { type: "request_connect", myId, targetId }
servidor -> cliente:  { type: "peer_endpoint", peerId, endpoint, publicKey }
                   ou { type: "error", reason: "peer_not_found" }

Mensagens entre peers

cliente -> servidor:  { type: "send", targetPeerId, payload }
servidor -> target:   { type: "message", fromPeerId, payload }

fromPeerId e derivado do WebSocket (quem mandou), nao declarado na mensagem. Mensagens para peers offline sao descartadas silenciosamente.

Storage customizado

O fileStorage padrao grava em data/known-peers.json. Para usar outro backend (Redis, SQLite, etc.), passe um objeto com a mesma interface:

const customStorage = {
  async load() {
    // retorna Map<peerId, { publicKey, lastSeen }>
  },
  async save(peers) {
    // recebe Map<peerId, { publicKey, lastSeen }>
  }
}

await createSignalingServer({ wss, storage: customStorage })

Testes

npm test

Licenca

MIT