suaveplan/docs/old-network-planning/PHASE_3.md

Phase 3: Message Routing

Overview

Phase 3 focuses on implementing the message routing system, which is responsible for directing messages through the network hierarchy. This system must efficiently route messages based on priorities, optimize paths, and handle various routing scenarios. Building on the core framework and transport layer from previous phases, the message routing system forms a crucial part of the network's communication capabilities.

Key Components

1. MessageRouter Implementation (src/router/router.ts)

The MessageRouter class is responsible for determining how messages should travel through the network. It should:

• Allow registration of route handlers for specific message types
• Determine the appropriate routing strategy based on message properties
• Support various routing modes (upward, downward, hierarchical, etc.)
• Optimize paths for message delivery

Core Features

• Route Registration: Register handlers for specific message patterns
• Route Unregistration: Remove previously registered handlers
• Message Routing: Route messages based on recipient and routing config
• Path Calculation: Determine the optimal path for a message

Implementation Requirements

• Support pattern-based routing (exact matches, wildcards, regex)
• Support route prioritization
• Implement various routing strategies
• Provide default catch-all handler for unmatched messages

Edge Cases

• Handle undeliverable messages
• Prevent routing loops
• Handle timeouts for message routing
• Support message cancellation

2. PriorityMessageQueue Implementation (src/router/priority-queue.ts)

The PriorityMessageQueue manages message ordering based on priority. It should:

• Queue messages according to their priority level
• Process higher priority messages before lower priority ones
• Support batched processing for efficiency
• Implement rate limiting and backpressure mechanisms

Core Features

• Priority-Based Queueing: Insert messages in priority order
• Batch Processing: Process messages in batches for efficiency
• Rate Limiting: Control message processing rate
• Queue Management: Handle queue growth and cleanup

Implementation Requirements

• Support multiple priority levels
• Provide configurable batch sizes
• Implement pause/resume functionality
• Track queue statistics for monitoring

Edge Cases

• Handle queue overflow
• Prevent starvation of low-priority messages
• Manage memory usage for large queues
• Handle queue persistence during reconnection

3. MessageBatcher Implementation (src/router/message-batcher.ts)

The MessageBatcher groups related messages together for more efficient processing. It should:

• Batch messages of similar types
• Apply batching strategies based on message properties
• Flush batches based on triggers (time, size, priority)
• Support custom batching logic

Core Features

• Message Buffering: Group messages by type or other criteria
• Batch Flushing: Send batches based on triggers
• Buffer Management: Manage buffer sizes and timeouts
• Batch Optimization: Optimize batch sizes for network conditions

Implementation Requirements

• Support configurable batch sizes
• Implement various flushing strategies
• Provide manual and automatic flushing
• Track batch statistics

Edge Cases

• Handle partial batch delivery failures
• Manage priority within batches
• Handle timeouts for incomplete batches
• Support batch cancellation

Message Routing Strategies

1. Upward-Only Routing

Messages travel only up the hierarchy:

• Node → Parent → Parent's parent, etc.
• Useful for client-to-server communication
• Simplest routing strategy

2. Downward-Only Routing

Messages travel only down the hierarchy:

• Node → Children → Children's children, etc.
• Useful for server-to-client broadcasts
• Requires knowledge of the target's position in the hierarchy

3. Hierarchical Routing

Messages travel up, then down the hierarchy:

• Source → Parent → ... → Common ancestor → ... → Recipient
• Standard routing approach for most messages
• Requires finding the lowest common ancestor

4. Multi-Level Routing

Messages can take shortcuts through the hierarchy:

• May skip levels for efficiency
• Can use sibling connections to avoid going through parents
• More complex but more efficient for specific scenarios

5. Broadcast Routing

Messages are sent to multiple recipients:

• Can be targeted to specific levels or the entire network
• Uses a combination of other strategies for delivery
• Must handle duplicates and loops

Priority-Based Routing

The system should implement priority-based routing:

1. Critical Messages (Priority 0)

• Take the most direct path possible, potentially skipping levels
• Bypass queues where possible
• May use multiple redundant paths for reliability

2. High Priority Messages (Priority 1)

• Use optimized routing that may skip levels
• Processed before lower priority messages
• Delivered with high reliability guarantees

3. Medium Priority Messages (Priority 2)

• Use standard hierarchical routing
• May be delayed by higher priority messages
• Balance between efficiency and resource usage

4. Low Priority Messages (Priority 3)

• Use resource-efficient routing, even if slower
• May be batched aggressively
• Can be dropped during network congestion

Routing Configuration

The routing system should be highly configurable:

// Example configuration interface
interface MessageRoutingConfig {
  routingMode: RoutingMode;
  maxRoutingDistance: number;
  priorityRoutingRules: {
    [priority: number]: {
      routingMode: RoutingMode;
      maxRoutingDistance: number;
    }
  };
  
  // Optional additional properties
  timeToLive?: number;          // Max hops before message expires
  duplicateDetection?: boolean; // Enable duplicate detection
  acknowledgement?: boolean;    // Require acknowledgment
  retryAttempts?: number;       // Number of delivery attempts
  retryDelay?: number;          // Delay between retries
}

Implementation Details

Message Router

The MessageRouter should use pattern matching for route registration:

// Example patterns
router.registerRoute('chat.message', chatMessageHandler);
router.registerRoute('system.*', systemMessageHandler);
router.registerRoute(/^analytics\./, analyticsHandler);

The routing logic should:

1. Find the appropriate handler for the message type
2. Determine the routing strategy based on message priority
3. Calculate the path to the recipient
4. Forward the message along that path

Priority Queue

The PriorityMessageQueue should implement:

1. Multiple internal queues, one per priority level
2. A processing loop that always takes from the highest priority non-empty queue
3. Batching to process multiple messages of the same priority
4. Rate limiting to prevent overwhelming the network

Message Batcher

The MessageBatcher should:

1. Group messages by type and/or recipient
2. Apply configurable criteria for when to flush batches:
   • Maximum batch size reached
   • Maximum wait time elapsed
   • High priority message forces a flush
   • Manual flush triggered
3. Optimize batch size based on network conditions

Testing Strategy

MessageRouter Tests

1. Route Registration Tests:

   • Test exact match routing
   • Test wildcard pattern routing
   • Test regex pattern routing
   • Test route priority

2. Routing Strategy Tests:

   • Test upward routing
   • Test downward routing
   • Test hierarchical routing
   • Test multi-level routing
   • Test broadcast routing

3. Edge Case Tests:

   • Test routing with missing recipients
   • Test routing when path is blocked
   • Test routing during network changes
   • Test handling of undeliverable messages

PriorityMessageQueue Tests

1. Priority Ordering Tests:

   • Test messages are processed in priority order
   • Test same-priority messages are processed in FIFO order
   • Test priority changes affect processing order

2. Batch Processing Tests:

   • Test batch size configuration
   • Test processing rate limits
   • Test batch composition across priorities

3. Resource Management Tests:

   • Test queue size limits
   • Test memory usage patterns
   • Test queue persistence during disconnection

MessageBatcher Tests

1. Batching Logic Tests:

   • Test message grouping by type
   • Test batch size limits
   • Test time-based flushing
   • Test priority-based flushing

2. Performance Tests:

   • Test throughput with batching vs. without
   • Test latency impact of batching
   • Test optimization based on network conditions

3. Reliability Tests:

   • Test handling batch delivery failures
   • Test batch retries
   • Test partial batch processing

Edge Cases and Considerations

1. Network Topology Changes

Consider how routing adapts to network changes:

• What happens to in-flight messages when topology changes?
• How are routing tables updated when nodes join/leave?
• How quickly do routing changes propagate?

2. Message Expiration

Implement time-to-live for messages:

• Messages should not circulate indefinitely
• Expired messages should be dropped with notifications
• TTL should be configurable per message type or priority

3. Routing Loops

Prevent messages from circulating indefinitely:

• Implement loop detection mechanisms
• Track message path history where needed
• Set maximum hop counts

4. Partial Network Failure

Handle partial network failures gracefully:

• Detect and route around failed nodes
• Queue messages for unreachable destinations
• Provide delivery status feedback

5. Backpressure

Implement backpressure mechanisms:

• Detect when downstream nodes are overwhelmed
• Slow down message production
• Prioritize essential messages during congestion

6. Large Messages

Handle large messages appropriately:

• Fragment large messages if needed
• Prioritize differently based on size
• Consider separate queues for large messages

Integration Points

The message routing system should integrate with:

1. NetworkNode: Via the MessageRouter interface
2. Transport Layer: For actual message delivery
3. Plugin System: For custom routing strategies
4. Monitoring: For performance metrics and debugging

Performance Optimization

Consider these optimizations:

1. Route Caching: Cache frequently used routing paths
2. Eager Path Calculation: Pre-calculate paths for known recipients
3. Adaptive Batching: Adjust batch sizes based on network conditions
4. Priority Tuning: Adjust priorities based on message patterns

Success Criteria

This phase is complete when:

1. The MessageRouter correctly routes messages using all routing strategies
2. The PriorityMessageQueue processes messages in the correct order
3. The MessageBatcher efficiently groups and sends related messages
4. All routing configurations work as expected
5. Messages reach their destinations efficiently
6. Edge cases are properly handled
7. All tests pass with 100% code coverage

The message routing system is a critical component of the network library as it directly impacts the efficiency, reliability, and scalability of communication within the network. A well-implemented routing system will ensure messages flow optimally through the network even as it scales and evolves.