322 líneas
8.6 KiB
Markdown
322 líneas
8.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Clone or create the project directory
|
|
cd ringnet
|
|
|
|
# Install dependencies
|
|
npm install
|
|
```
|
|
|
|
### Running the Network
|
|
|
|
1. **Start the first node (Oracle) as bootstrap:**
|
|
```bash
|
|
npm run start:oracle -- --port 8080
|
|
```
|
|
|
|
2. **Start additional nodes:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
npm run start:node -- --port 8083 --bootstrap localhost:8080
|
|
```
|
|
|
|
## 📖 Usage
|
|
|
|
### Command Line Options
|
|
|
|
```bash
|
|
--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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```json
|
|
{
|
|
"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
|
|
- `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
|
|
|
|
```javascript
|
|
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
|
|
|
|
```javascript
|
|
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:
|
|
```bash
|
|
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](https://webrtc.org/) - Real-time communication
|
|
- [Node.js WebRTC](https://github.com/node-webrtc/node-webrtc) - WebRTC for Node.js
|
|
- [Chord DHT](https://en.wikipedia.org/wiki/Chord_(peer-to-peer)) - Distributed hash table
|
|
- [Kademlia](https://en.wikipedia.org/wiki/Kademlia) - Distributed hash table protocol
|
|
|
|
## 📚 Further Reading
|
|
|
|
- [Peer-to-Peer Networks](https://en.wikipedia.org/wiki/Peer-to-peer)
|
|
- [Distributed Systems](https://en.wikipedia.org/wiki/Distributed_computing)
|
|
- [WebRTC Documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API)
|
|
- [Consensus Algorithms](https://en.wikipedia.org/wiki/Consensus_(computer_science))
|