Networking

GUN provides multiple networking transports to enable peer-to-peer connectivity across different environments. The mesh networking layer automatically handles peer discovery, message routing, and failover.

Transport Protocols

WebSocket

WebSocket is the default transport for GUN relay peers. It provides bidirectional, real-time communication between peers.

const gun = Gun({
  peers: ['http://localhost:8765/gun']
});

The relay peer automatically upgrades HTTP connections to WebSocket when available.

Server Configuration

const Gun = require('gun');
const server = require('http').createServer();

const gun = Gun({
  web: server.listen(8765),
  peers: [] // Connect to other peers
});

console.log('Relay peer started on port 8765');

Source: ~/workspace/source/examples/http.js:28-32

WebRTC

WebRTC enables direct peer-to-peer connections between browsers without requiring a relay server. GUN includes built-in WebRTC support through the gun/lib/webrtc.js module.

const gun = Gun({
  rtc: {
    iceServers: [
      {urls: 'stun:stun.l.google.com:19302'},
      {urls: 'stun:stun.cloudflare.com:3478'}
    ],
    dataChannel: {
      ordered: false,
      maxRetransmits: 2
    },
    max: 55, // Maximum number of WebRTC connections
    room: 'my-app-room' // Room for peer discovery
  }
});

Source: ~/workspace/source/lib/webrtc.js:22-36

How WebRTC Works in GUN

Peer Discovery: Peers announce themselves to a room using GUN’s graph sync
Offer/Answer Exchange: SDP offers and answers are exchanged via GUN messages
ICE Candidates: Connection candidates are shared for NAT traversal
Data Channel: Once connected, messages flow through the WebRTC data channel

// Disable WebRTC if needed
const gun = Gun({
  RTCPeerConnection: false
});

Source: ~/workspace/source/lib/webrtc.js:8

Media Streams

GUN’s WebRTC implementation supports media streams for video/audio:

navigator.mediaDevices.getUserMedia({video: true, audio: true})
  .then(stream => {
    gun.opt().mesh.wire(stream);
  });

Source: ~/workspace/source/lib/webrtc.js:52-62

Multicast

Multicast enables UDP-based local network discovery in Node.js environments. This is perfect for IoT devices or local-first applications.

const gun = Gun({
  multicast: {
    address: '233.255.255.255',
    port: 8765,
    pack: 50000 // Max UDP packet size (65KB limit)
  }
});

Source: ~/workspace/source/lib/multicast.js:10-13

Disabling Multicast

# Environment variable
export MULTICAST=false

# Or in code
const gun = Gun({ multicast: false });

Source: ~/workspace/source/lib/multicast.js:7

Peer Discovery

Static Peers

Manually specify peer URLs:

const gun = Gun({
  peers: [
    'http://peer1.example.com/gun',
    'http://peer2.example.com/gun',
    'http://peer3.example.com/gun'
  ]
});

Dynamic Peer Discovery

GUN automatically discovers peers through:

WebRTC Room Announcements: Peers join rooms and discover each other
Multicast Broadcasting: Local network peers announce themselves via UDP
Peer Gossip: Connected peers share information about other peers

AXE Relay Protocol

AXE (Advanced eXchange Engine) is GUN’s intelligent routing protocol that optimizes message delivery across the mesh network.

# Enable AXE (enabled by default)
export AXE=true

# Disable AXE
export AXE=false

Source: ~/workspace/source/lib/axe.js:12 AXE features:

Smart routing: Messages are routed to subscribed peers only
Subscription tracking: Peers track which data other peers are interested in
Load balancing: GET requests are distributed across multiple peers
Deduplication: Prevents duplicate messages using hash checking

Mesh Architecture

GUN’s mesh networking layer (src/mesh.js) handles all peer communication:

Message Flow

hear(): Receive messages from peers
say(): Send messages to peers
Batching: Messages are batched for efficient network utilization
Deduplication: Duplicate messages are filtered using message IDs

Source: ~/workspace/source/src/mesh.js:24-194

Peer States

gun.on('hi', peer => {
  console.log('Peer connected:', peer.id);
});

gun.on('bye', peer => {
  console.log('Peer disconnected:', peer.id);
});

Source: ~/workspace/source/src/mesh.js:266-294

Message Limits

const gun = Gun({
  gap: 0,        // Delay between batched messages (ms)
  max: 300000000 * 0.3, // Max message size (~90MB)
  pack: 3000,    // Batch packet size
  puff: 9        // Messages processed per tick
});

Source: ~/workspace/source/src/mesh.js:14-17

Network Optimization

Connection Pooling

GUN maintains a pool of peer connections and automatically reconnects on failure.

Backpressure Handling

Messages are queued when peers are temporarily unavailable:

// Queued messages are sent when peer reconnects
peer.queue = peer.queue || [];
peer.queue.push(message);

Source: ~/workspace/source/src/mesh.js:262

Message Batching

Messages are automatically batched into JSON arrays to reduce network overhead:

// Multiple messages sent as: [{msg1}, {msg2}, {msg3}]

Source: ~/workspace/source/src/mesh.js:178-192

Security Considerations

HTTPS/WSS

For production deployments, always use encrypted connections:

const fs = require('fs');
const Gun = require('gun');

const server = require('https').createServer({
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem')
}, Gun.serve(__dirname));

const gun = Gun({web: server.listen(443)});

Source: ~/workspace/source/examples/http.js:18-22

Peer Authentication

Use GUN’s SEA (Security, Encryption, Authorization) for peer authentication:

const Gun = require('gun');
require('gun/sea');

const gun = Gun();
const user = gun.user();

user.create('alice', 'password', ack => {
  user.auth('alice', 'password');
});

Debugging Network Issues

Enable Statistics

console.STAT = {};

// Access stats
setInterval(() => {
  console.log('Connected peers:', console.STAT.peers);
}, 1000);

Source: ~/workspace/source/src/mesh.js:328

Message Tracking

Enable debug logging to track message flow:

Gun.log = console.log;

const gun = Gun({
  log: console.log
});

Best Practices

Use relay peers for production: Browser-to-browser WebRTC should be supplemented with relay peers for reliability
Configure STUN/TURN servers: Required for WebRTC NAT traversal
Set reasonable connection limits: Default WebRTC max is 55 connections
Enable multicast for local networks: Great for offline-first IoT applications
Monitor peer connections: Track hi/bye events to understand network topology
Use AXE for large meshes: Improves routing efficiency with many peers
Batch writes: Group multiple puts to reduce network messages

Next Steps

Learn about Conflict Resolution in distributed networks
Optimize Performance for your use case
Understand CAP Theorem tradeoffs
Deploy to Production

Get Started

Core Concepts

API Reference

Security (SEA)

Storage Adapters

Advanced

Integration Guides

Networking

Transport Protocols

WebSocket

Server Configuration

WebRTC

How WebRTC Works in GUN

Media Streams

Multicast

Disabling Multicast

Peer Discovery

Static Peers

Dynamic Peer Discovery

AXE Relay Protocol

Mesh Architecture

Message Flow

Peer States

Message Limits

Network Optimization

Connection Pooling

Backpressure Handling

Message Batching

Security Considerations

HTTPS/WSS

Peer Authentication

Debugging Network Issues

Enable Statistics

Message Tracking

Best Practices

Next Steps

​Transport Protocols

​WebSocket

​Server Configuration

​WebRTC

​How WebRTC Works in GUN

​Media Streams

​Multicast

​Disabling Multicast

​Peer Discovery

​Static Peers

​Dynamic Peer Discovery

​AXE Relay Protocol

​Mesh Architecture

​Message Flow

​Peer States

​Message Limits

​Network Optimization

​Connection Pooling

​Backpressure Handling

​Message Batching

​Security Considerations

​HTTPS/WSS

​Peer Authentication

​Debugging Network Issues

​Enable Statistics

​Message Tracking

​Best Practices

​Next Steps

Transport Protocols

WebSocket

Server Configuration

WebRTC

How WebRTC Works in GUN

Media Streams

Multicast

Disabling Multicast

Peer Discovery

Static Peers

Dynamic Peer Discovery

AXE Relay Protocol

Mesh Architecture

Message Flow

Peer States

Message Limits

Network Optimization

Connection Pooling

Backpressure Handling

Message Batching

Security Considerations

HTTPS/WSS

Peer Authentication

Debugging Network Issues

Enable Statistics

Message Tracking

Best Practices

Next Steps