ringnet/README.md

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.

🌐 Live Demo: https://ringnet.cloud
📂 Repository: https://git.manalejandro.com/ale/ringnet
📝 Documentation: https://pad.manalejandro.com/p/2ringsnet

🌟 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 the repository
git clone https://git.manalejandro.com/ale/ringnet.git
cd ringnet

# Install dependencies
npm install

Running the Network

1. Start the Dashboard (Optional):

npm run start:dashboard

Dashboard available at: http://localhost:3000

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

npm run start:oracle -- --port 8080 --dashboard http://localhost:3000

3. Start additional nodes:

# Regular node
npm run start:node -- --port 8081 --bootstrap localhost:8080 --dashboard http://localhost:3000

# Another Oracle node
npm run start:oracle -- --port 8082 --bootstrap localhost:8080 --dashboard http://localhost:3000

4. Start more nodes:

npm run start:node -- --port 8083 --bootstrap localhost:8080 --dashboard http://localhost:3000

📖 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)
--dashboard <url>      # Dashboard server URL (default: http://localhost:3000)
--ice-servers <json>   # ICE servers configuration (JSON array)
--config <file>        # Load configuration from JSON file
--help                 # Show help message

Note: Ring positions are now assigned automatically for optimal network topology. The system calculates the best position for each node to ensure even distribution around the ring.

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
- `topology` - Show ring topology and node positions
- `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
- `topology` - Show ring topology and node positions

## 🔮 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

## 🎯 Automatic Ring Positioning

The Ring Network now features **automatic node positioning** that optimizes network topology without manual configuration:

### Key Features
- **Optimal Placement**: New nodes are automatically positioned in the largest gap between existing nodes
- **Even Distribution**: Nodes are distributed evenly around the virtual ring for balanced load
- **Dynamic Rebalancing**: Network topology adjusts automatically when nodes join or leave
- **No Manual Configuration**: Eliminates the need to manually specify ring positions

### How It Works
1. **Virtual Ring**: The network uses a virtual ring of 1000 positions
2. **Gap Analysis**: When a new node joins, the system finds the largest gap between existing nodes
3. **Optimal Insertion**: The new node is placed in the middle of the largest gap
4. **Topology Update**: All nodes update their neighbor connections based on the new topology
5. **Automatic Rebalancing**: The system can redistribute nodes evenly when needed

### Benefits
- **Simplified Setup**: No need to calculate or specify positions manually
- **Better Performance**: Optimal positioning improves routing efficiency
- **Self-Healing**: Network automatically adapts to node changes
- **Scalability**: Easy to add new nodes without topology planning

Use the `topology` command in any node to view the current ring structure and positions.

## 📊 Dashboard & Monitoring

The RingNet includes a web-based dashboard for real-time network monitoring:

### Features
- **Real-time Network Statistics**: Total nodes, connections, Oracle nodes
- **Interactive Ring Topology**: Visual representation of the ring structure
- **Node Status Monitoring**: Active/inactive status, connection health
- **REST API**: Programmatic access to network data

### Quick Start
```bash
# Start the dashboard server
npm run start:dashboard

# Dashboard available at: http://localhost:3000

API Endpoints

• GET /api/nodes - List all nodes
• GET /api/network/stats - Network statistics
• GET /api/network/topology - Ring topology data
• GET /api/nodes/:nodeId - Node details

See server/README.md for complete API documentation.

🧪 Testing

Run the test suite to verify network functionality:

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