356 lines
12 KiB
Markdown
356 lines
12 KiB
Markdown
# 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.
|