Ring Network - Two Ring Topology with WebRTC

A decentralized peer-to-peer network implementation using WebRTC for communication in a double ring topology with optional Oracle nodes for enhanced network services.

🌟 Features

Core Network Features

• Double Ring Topology: Inner and outer rings for redundancy and efficient routing
• WebRTC Peer-to-Peer: Direct browser-to-browser/node-to-node communication
• Automatic Discovery: Nodes can discover and connect to each other
• Message Routing: Efficient message propagation through ring structures
• Network Resilience: Automatic adaptation to node connections/disconnections

Oracle Node Capabilities

• Network Analysis: Topology analysis and health monitoring
• Distributed Data Storage: Replicated data storage across Oracle nodes
• Consensus Mechanisms: Distributed decision making
• Advanced Routing: Sophisticated routing strategies
• Health Monitoring: Continuous network health assessment
• Metrics Collection: Network performance and usage statistics

🏗️ Architecture

     Inner Ring: A → B → C → A
    Outer Ring: A ← B ← C ← A
    
    Where:
    - A, B, C are network nodes
    - → indicates message flow direction
    - Each node maintains connections to its neighbors in both rings

Node Types

1. Regular Nodes: Basic network participants that route messages
2. Oracle Nodes: Enhanced nodes providing additional services

🚀 Quick Start

Installation

# Clone or create the project directory
cd ringnet

# Install dependencies
npm install

Running the Network

1. Start the first node (Oracle) as bootstrap:

npm run start:oracle -- --port 8080

2. Start additional nodes:

# Regular node
npm run start:node -- --port 8081 --bootstrap localhost:8080

# Another Oracle node
npm run start:oracle -- --port 8082 --bootstrap localhost:8080

3. Start more nodes:

npm run start:node -- --port 8083 --bootstrap localhost:8080

📖 Usage

Command Line Options

--port <port>          # Port to listen on (default: random)
--id <id>              # Node ID (default: auto-generated UUID)
--bootstrap <addr>     # Bootstrap node address (host:port)
--position <pos>       # Initial ring position (default: 0)
--ice-servers <json>   # ICE servers configuration (JSON array)
--config <file>        # Load configuration from JSON file
--help                 # Show help message

WebRTC ICE Servers Configuration

The Ring Network uses WebRTC for peer-to-peer connections. You can configure custom ICE servers (STUN/TURN) for better connectivity:

Using Command Line

# With custom STUN servers
node node.js --ice-servers '[{"urls":"stun:your-stun-server.com:19302"}]'

# With TURN server for NAT traversal
node node.js --ice-servers '[{"urls":"stun:stun.l.google.com:19302"},{"urls":"turn:your-turn-server.com:3478","username":"user","credential":"pass"}]'

Using Configuration Files

# Load from config file
node node.js --config config/ice-servers-with-turn.json

# For Oracle nodes
node oracle.js --config config/ice-servers-public-turn.json

Available Configuration Examples

• config/ice-servers-default.json - Default Google STUN servers
• config/ice-servers-with-turn.json - Template with TURN server
• config/ice-servers-public-turn.json - Public TURN servers for testing

ICE Server Configuration Format

{
  "iceServers": [
    {
      "urls": "stun:stun.l.google.com:19302"
    },
    {
      "urls": "turn:turnserver.example.com:3478",
      "username": "your_username",
      "credential": "your_password"
    }
  ]
}

--help # Show help message

### Interactive Commands

Once a node is running, you can use these commands:

#### Regular Node Commands
- `send <message>` - Send a message through the ring
- `info` - Show network information
- `peers` - List connected peers
- `connections` - Show persistent connection status
- `help` - Show available commands
- `quit` - Exit the node

#### Oracle Node Commands (additional)
- `health` - Perform network health check
- `metrics` - Show network metrics
- `analyze` - Analyze network topology
- `store <key> <value>` - Store data in distributed storage
- `get <key>` - Retrieve data from storage
- `propose <text>` - Create a consensus proposal
- `vote <id> <yes|no>` - Vote on a proposal

## 🔮 Oracle Services

Oracle nodes provide enhanced services to the network:

### 1. Network Analysis (`network-analysis`)
- Topology mapping and analysis
- Network health assessment
- Performance recommendations

### 2. Data Storage (`data-storage`)
- Distributed key-value storage
- Automatic replication across Oracles
- TTL (Time-To-Live) support

### 3. Consensus (`consensus`)
- Proposal creation and voting
- Majority-based decision making
- Distributed agreement protocols

### 4. Routing (`routing`)
- Advanced routing strategies
- Shortest path calculation
- Multi-path routing options

### 5. Health Monitoring (`health-check`)
- Continuous network monitoring
- Failure detection and reporting
- Recovery recommendations

### 6. Network Metrics (`network-metrics`)
- Performance statistics
- Usage analytics
- Historical data tracking

## 🧪 Testing

Run the test suite to verify network functionality:

```bash
npm test

The test suite covers:

• Node initialization
• Peer connections
• Ring topology formation
• Oracle services
• Message routing
• Network resilience

📝 API Reference

RingNode Class

import { RingNode } from './src/ring-node.js';

const node = new RingNode({
    id: 'optional-id',
    port: 8080,
    ringPosition: 0,
    isOracle: false
});

// Events
node.on('peerConnected', (peerId) => { });
node.on('peerDisconnected', (peerId) => { });
node.on('ringMessage', ({ from, payload }) => { });
node.on('networkUpdate', ({ from, payload }) => { });

// Methods
node.sendRingMessage(payload, ring);
node.joinRing(bootstrapNode);
node.getNetworkInfo();
node.destroy();

OracleNode Class

import { OracleNode } from './src/oracle-node.js';

const oracle = new OracleNode({
    id: 'oracle-1',
    port: 8080
});

// Oracle-specific methods
oracle.analyzeNetwork();
oracle.handleDataStorage({ operation: 'set', key: 'test', value: 'data' });
oracle.handleConsensus({ proposalId: 'prop1', proposal: 'Upgrade network' });
oracle.performHealthCheck();
oracle.getNetworkMetrics();

🔧 Configuration

WebRTC Configuration

The nodes use public STUN servers by default:

• stun:stun.l.google.com:19302
• stun:stun1.l.google.com:19302

For production use, consider setting up your own TURN servers.

Network Parameters

• Message History Size: 1000 messages (prevents loops)
• Data TTL: 1 hour default (configurable)
• Health Check Interval: 30 seconds
• Metrics Collection: 10 seconds
• Cleanup Interval: 5 minutes

🛡️ Security Considerations

• Message Integrity: All messages should be signed in production
• Node Authentication: Implement proper node authentication
• Data Encryption: Encrypt sensitive data in storage
• Rate Limiting: Implement rate limiting for message propagation
• Access Control: Restrict Oracle services to authorized nodes

🐛 Troubleshooting

Common Issues

1. Connection Failures

   • Check firewall settings
   • Verify port availability
   • Ensure WebRTC support

2. Bootstrap Node Unreachable

   • Verify bootstrap node is running
   • Check network connectivity
   • Confirm port and address

3. Ring Formation Issues

   • Allow time for topology stabilization
   • Check node discovery process
   • Verify peer connections

Debug Mode

Enable debug logging by setting environment variable:

DEBUG=ringnet:* npm start

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• WebRTC - Real-time communication
• Node.js WebRTC - WebRTC for Node.js
• Chord DHT - Distributed hash table
• Kademlia - Distributed hash table protocol

📚 Further Reading

• Peer-to-Peer Networks
• Distributed Systems
• WebRTC Documentation
• Consensus Algorithms

Connection Persistence

The Ring Network now includes connection persistence features:

Persistent Connection Management

• Automatic Connection Maintenance: Nodes automatically maintain persistent WebRTC connections with other nodes
• Heartbeat System: Regular heartbeat messages keep connections alive and detect failures
• Connection Monitoring: Built-in monitoring of connection health and status
• Automatic Reconnection: Failed connections are automatically retried with exponential backoff

Connection Status

Use the connections command to view:

• Total active connections
• Persistent connection count
• Connection health status
• Last seen timestamps for each peer
• Reconnection attempt counts

Bootstrap Connections

When joining via a bootstrap node:

• Initial WebSocket connection for joining the network
• Automatic establishment of persistent WebRTC connection
• Bootstrap node maintains connection with new nodes
• Connection health monitoring and automatic recovery

Features

• ✅ Heartbeat Messages: 30-second intervals to maintain connections
• ✅ Connection Health Checks: Monitor connection state every 30 seconds
• ✅ Automatic Reconnection: Up to 3 attempts before giving up
• ✅ Connection Status Monitoring: Real-time connection status display
• ✅ Graceful Shutdown: Proper cleanup of connections and intervals