Initial Commit
This commit is contained in:
355
docs/old-network-planning/PHASE_1.md
Normal file
355
docs/old-network-planning/PHASE_1.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# Phase 1: Core Framework and Types
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 1 establishes the foundation of the network library by implementing core types and the base building blocks: `NetworkNode` and `NetworkSystem`. This phase is critical as it defines the data structures and relationships that the entire system depends on.
|
||||
|
||||
## Core Architecture Class Diagram
|
||||
|
||||
The following class diagram illustrates the key components and their relationships that should be implemented in this phase:
|
||||
|
||||
```typescript
|
||||
classDiagram
|
||||
class NetworkNode {
|
||||
-id: string
|
||||
-level: number
|
||||
-parent: NetworkNode
|
||||
-children: Map~string, NetworkNode~
|
||||
-siblings: Map~string, NetworkNode~
|
||||
-capabilities: NodeCapabilities
|
||||
-performance: NodePerformance
|
||||
-levelConfig: LevelConfig
|
||||
-transport: NetworkTransport
|
||||
+addChild(node: NetworkNode)
|
||||
+removeChild(nodeId: string)
|
||||
+addSibling(node: NetworkNode)
|
||||
+removeSibling(nodeId: string)
|
||||
+sendMessage(message: NetworkMessage)
|
||||
+tryPromote()
|
||||
+demote()
|
||||
+canAcceptChildren()
|
||||
}
|
||||
|
||||
class LevelConfig {
|
||||
+level: number
|
||||
+name: string
|
||||
+maxChildren: number
|
||||
+maxSiblings: number
|
||||
+minPromotionScore: number
|
||||
+demotionThreshold: number
|
||||
+messageRoutingConfig: MessageRoutingConfig
|
||||
}
|
||||
|
||||
class NetworkSystem {
|
||||
-nodes: Map~string, NetworkNode~
|
||||
-config: NetworkSystemConfig
|
||||
+createNode(id, transport, capabilities)
|
||||
+removeNode(id)
|
||||
+findBestParent(node)
|
||||
+placeNodeInHierarchy(node)
|
||||
}
|
||||
|
||||
class NetworkTransport {
|
||||
<<interface>>
|
||||
+sendTo(nodeId, message)
|
||||
+on(event, handler)
|
||||
+off(event, handler)
|
||||
}
|
||||
|
||||
class VotingManager {
|
||||
-node: NetworkNode
|
||||
-config: VotingConfig
|
||||
+startVote(trigger)
|
||||
+castVote(vote)
|
||||
}
|
||||
|
||||
NetworkNode "1" --> "0..1" NetworkNode : parent
|
||||
NetworkNode "1" --> "*" NetworkNode : children
|
||||
NetworkNode "1" --> "*" NetworkNode : siblings
|
||||
NetworkNode "1" --> "1" LevelConfig
|
||||
NetworkNode "1" --> "0..1" VotingManager
|
||||
NetworkNode "1" --> "1" NetworkTransport
|
||||
NetworkSystem "1" --> "*" NetworkNode
|
||||
```
|
||||
|
||||
This diagram illustrates the unified node architecture where all network participants use the same `NetworkNode` class with behavior determined by their level in the hierarchy. The relationships between nodes (parent-child and sibling) form the network structure, with each node configured based on its level.
|
||||
|
||||
## Key Components
|
||||
|
||||
### 1. Core Types and Interfaces (`src/types.ts`)
|
||||
|
||||
This file serves as the centralized location for all shared types used throughout the system. It should include:
|
||||
|
||||
- **Connection States and Message Types**: Define enums for connection states, message priorities, and routing modes
|
||||
- **Node Configuration**: Define interfaces for node capabilities, performance metrics, and connection quality
|
||||
- **Level Configuration**: Define interfaces for level configurations, system configuration, and routing rules
|
||||
- **Voting System Types**: Define interfaces for votes, vote tallies, and voting configuration
|
||||
- **Tier Management Types**: Define interfaces for tier statistics and configuration
|
||||
- **Plugin Interface**: Define the base plugin interface
|
||||
|
||||
### 2. Node-Specific Types (`src/node/types.ts`)
|
||||
|
||||
This file defines interfaces specific to the NetworkNode component to avoid circular dependencies:
|
||||
|
||||
- **INetworkNodeIdentity**: A lightweight interface representing node identity
|
||||
- **Component Interfaces**: Define interfaces for VotingManager, MessageRouter, and NetworkStats
|
||||
|
||||
### 3. NetworkNode Implementation (`src/node/node.ts`)
|
||||
|
||||
The NetworkNode class is the fundamental building block of the system. It should:
|
||||
|
||||
- Maintain parent-child relationships in the hierarchy
|
||||
- Track siblings at the same level
|
||||
- Support dynamic level changes (promotion/demotion)
|
||||
- Provide message routing capabilities
|
||||
- Configure behavior based on level
|
||||
- Support plugin registration and management
|
||||
|
||||
#### Key Methods to Implement
|
||||
|
||||
- **Parent-Child Management**:
|
||||
- `addChild`: Add a child node to this node
|
||||
- `removeChild`: Remove a child node
|
||||
- `canAcceptChildren`: Check if this node can accept more children
|
||||
|
||||
- **Sibling Management**:
|
||||
- `addSibling`: Add a sibling node
|
||||
- `removeSibling`: Remove a sibling relationship
|
||||
|
||||
- **Messaging**:
|
||||
- `sendMessage`: Send a message to another node
|
||||
- Process incoming messages
|
||||
|
||||
- **Level Management**:
|
||||
- `tryPromote`: Attempt to promote this node to the next level
|
||||
- `demote`: Demote this node to a lower level
|
||||
|
||||
- **Plugin Management**:
|
||||
- `registerPlugin`: Register a plugin with this node
|
||||
- `removePlugin`: Remove a plugin
|
||||
- `getPlugin`: Get a plugin by ID
|
||||
|
||||
#### Edge Cases to Handle
|
||||
|
||||
- **Level Changes**: When a node changes level, children must be redistributed
|
||||
- **Parent Disconnection**: When a parent disconnects, child nodes must find new parents
|
||||
- **Circular References**: Avoid circular parent-child relationships
|
||||
- **Level Configuration**: Apply the correct configuration based on the node's level
|
||||
- **Message Routing**: Ensure messages are routed correctly based on the hierarchy
|
||||
|
||||
### 4. NetworkSystem Implementation (`src/network/network.ts`)
|
||||
|
||||
The NetworkSystem class manages the entire network of nodes. It should:
|
||||
|
||||
- Create and remove nodes
|
||||
- Place nodes in the hierarchy
|
||||
- Find appropriate parents for nodes
|
||||
- Manage the tier structure
|
||||
- Handle node disconnections and reconnections
|
||||
|
||||
#### Key Methods to Implement
|
||||
|
||||
- **Node Management**:
|
||||
- `createNode`: Create a new node with the specified properties
|
||||
- `removeNode`: Remove a node from the system
|
||||
- `getNode`: Get a node by ID
|
||||
- `getAllNodes`: Get all nodes in the system
|
||||
|
||||
- **Hierarchy Management**:
|
||||
- `findBestParent`: Find the most suitable parent for a node
|
||||
- `placeNodeInHierarchy`: Place a node in the hierarchy
|
||||
- `getNodesByLevel`: Get all nodes at a specific level
|
||||
|
||||
- **Event Handling**:
|
||||
- `handleNodeDisconnection`: Handle a node disconnecting
|
||||
- `handleNodeReconnection`: Handle a node reconnecting
|
||||
|
||||
#### Edge Cases to Handle
|
||||
|
||||
- **Empty Levels**: Handle situations where an entire level becomes empty
|
||||
- **Disconnection Cascades**: Prevent cascading disconnections from destabilizing the system
|
||||
- **Reconnection Loops**: Prevent infinite reconnection attempts
|
||||
- **Configuration Inconsistencies**: Validate level configurations to ensure they're consistent
|
||||
|
||||
## Implementation Requirements
|
||||
|
||||
### Node Relationships
|
||||
|
||||
Node relationships should be flexible but controlled:
|
||||
|
||||
1. **Parent-Child Relationships**:
|
||||
- A node can have only one parent
|
||||
- A node's level must be one less than its parent's level
|
||||
- A node cannot be its own ancestor (no cycles in the hierarchy)
|
||||
- Level 0 nodes (clients) cannot have children
|
||||
|
||||
2. **Sibling Relationships**:
|
||||
- Siblings must be at the same level
|
||||
- Sibling relationships should be bidirectional
|
||||
- The number of siblings should not exceed the level's maxSiblings parameter
|
||||
|
||||
### Level Configuration
|
||||
|
||||
Each level needs specific configuration:
|
||||
|
||||
1. **Level 0 (Client)**:
|
||||
- Cannot have children
|
||||
- No hosting responsibilities
|
||||
- May have unlimited siblings
|
||||
|
||||
2. **Level 1 (Host)**:
|
||||
- Limited number of children (typically 20)
|
||||
- Limited number of siblings (typically 10)
|
||||
- Handles message routing for its children
|
||||
|
||||
3. **Level 2+ (Tier Host, Region Host, etc.)**:
|
||||
- Each higher level has fewer hosts but more responsibilities
|
||||
- Higher levels need higher performance thresholds
|
||||
- Higher levels may route messages differently
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
Nodes need to track and report performance metrics:
|
||||
|
||||
1. **System Metrics**:
|
||||
- CPU load
|
||||
- Memory usage
|
||||
- Network usage
|
||||
- Battery level (for mobile devices)
|
||||
|
||||
2. **Connection Metrics**:
|
||||
- Latency/ping times to connected nodes
|
||||
- Packet loss
|
||||
- Bandwidth
|
||||
- Jitter
|
||||
- Connection stability
|
||||
|
||||
### Message Handling
|
||||
|
||||
The basic message flow implementation should support:
|
||||
|
||||
1. **Message Types**:
|
||||
- Direct messages (node to node)
|
||||
- Broadcasts (to all or a subset of nodes)
|
||||
- System messages (for internal coordination)
|
||||
|
||||
2. **Message Priorities**:
|
||||
- Critical messages (highest priority)
|
||||
- High priority messages
|
||||
- Medium priority messages
|
||||
- Low priority messages (lowest priority)
|
||||
|
||||
3. **Message Routing**:
|
||||
- Upward routing (to parent)
|
||||
- Downward routing (to children)
|
||||
- Hierarchical routing (up then down)
|
||||
- Multi-level routing (optimized path)
|
||||
- Broadcast routing (to all connected nodes)
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### NetworkNode Tests
|
||||
|
||||
1. **Relationship Tests**:
|
||||
- Test adding/removing children
|
||||
- Test handling parent changes
|
||||
- Test sibling relationships
|
||||
|
||||
2. **Level Management Tests**:
|
||||
- Test promotion criteria
|
||||
- Test demotion criteria
|
||||
- Test level-specific behavior
|
||||
|
||||
3. **Message Routing Tests**:
|
||||
- Test sending messages to parent
|
||||
- Test sending messages to children
|
||||
- Test handling unknown recipients
|
||||
|
||||
### NetworkSystem Tests
|
||||
|
||||
1. **Node Management Tests**:
|
||||
- Test creating nodes with different capabilities
|
||||
- Test removing nodes
|
||||
- Test retrieving nodes
|
||||
|
||||
2. **Hierarchy Tests**:
|
||||
- Test placement algorithms
|
||||
- Test finding best parent
|
||||
- Test handling disconnections
|
||||
|
||||
3. **Configuration Tests**:
|
||||
- Test level configuration application
|
||||
- Test system configuration validation
|
||||
|
||||
## Edge Cases and Considerations
|
||||
|
||||
### 1. Memory Management
|
||||
|
||||
Be careful with bidirectional references to avoid memory leaks:
|
||||
|
||||
- Use weak references where appropriate
|
||||
- Clean up event listeners when nodes are removed
|
||||
- Ensure circular references are properly handled
|
||||
|
||||
### 2. Event Propagation
|
||||
|
||||
Consider how events propagate through the hierarchy:
|
||||
|
||||
- Should events bubble up to parents?
|
||||
- Should parents broadcast events to children?
|
||||
- How are events handled when the hierarchy changes?
|
||||
|
||||
### 3. Concurrency
|
||||
|
||||
Consider concurrent operations on the node hierarchy:
|
||||
|
||||
- What happens if a node is added while the hierarchy is being reorganized?
|
||||
- How are race conditions handled when multiple nodes disconnect simultaneously?
|
||||
- How is message ordering maintained during hierarchy changes?
|
||||
|
||||
### 4. Error Handling
|
||||
|
||||
Implement robust error handling:
|
||||
|
||||
- Handle transport failures gracefully
|
||||
- Validate all inputs, especially network messages
|
||||
- Provide meaningful error messages for debugging
|
||||
|
||||
### 5. Configuration Validation
|
||||
|
||||
Validate system configuration to prevent issues:
|
||||
|
||||
- Ensure level configurations are consistent
|
||||
- Validate routing configurations
|
||||
- Check for missing required configuration fields
|
||||
|
||||
## Integration Points
|
||||
|
||||
The core components should be designed with clear integration points for future phases:
|
||||
|
||||
1. **Transport Integration**: NetworkNode should use the ITransport interface
|
||||
2. **Voting Integration**: NetworkNode should prepare for VotingManager integration
|
||||
3. **Plugin System**: NetworkNode should support plugin registration
|
||||
4. **Tier Management**: NetworkSystem should prepare for TierManager integration
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
Even in this foundational phase, consider performance:
|
||||
|
||||
1. **Message Handling**: Optimize message routing algorithm
|
||||
2. **Node Storage**: Use efficient data structures for node lookups
|
||||
3. **Event Handling**: Avoid unnecessary event emissions
|
||||
|
||||
## Success Criteria
|
||||
|
||||
This phase is complete when:
|
||||
|
||||
1. All core types and interfaces are defined
|
||||
2. NetworkNode fully implements parent-child relationships
|
||||
3. NetworkNode correctly adapts behavior based on level
|
||||
4. NetworkSystem can create, place, and manage nodes
|
||||
5. Basic message routing works correctly
|
||||
6. All tests pass with 100% code coverage
|
||||
7. Edge cases are properly handled and tested
|
||||
|
||||
The foundation laid in this phase will support all subsequent development, so it's critical to ensure it's robust, well-tested, and extensible.
|
||||
Reference in New Issue
Block a user