The Router module implements a high-performance, trie-based signal routing system designed specifically for agent-based architectures. It provides sophisticated message routing capabilities with support for exact matches, wildcards, and pattern matching functions.

Core Concepts

The Router organizes signal handlers into an efficient trie (prefix tree) structure that enables:

• Fast path-based routing using dot-notation (e.g., "user.created.verified")
• Priority-based handler execution (-100 to 100)
• Complexity-based ordering for wildcard resolution
• Dynamic route management (add/remove at runtime)
• Pattern matching through custom functions

Path Patterns

Routes use a dot-notation pattern system supporting:

• Exact matches: "user.created"
• Single wildcards: "user.*.updated" (matches one segment)
• Multi-level wildcards: "audit.**" (matches zero or more segments)

Pattern rules:

• Paths must match: ^[a-zA-Z0-9.*_-]+(.[a-zA-Z0-9.*_-]+)*$
• Cannot contain consecutive dots (..)
• Cannot contain consecutive multi-wildcards (**...**)

Handler Priority

Handlers execute in order based on:

1. Path complexity (more specific paths execute first)
2. Priority (-100 to 100, higher executes first)
3. Registration order (for equal priority/complexity)

Usage Examples

Basic route creation:

{:ok, router} = Router.new([
  # Simple route with default priority
  {"user.created", %Instruction{action: HandleUserCreated}},

  # High-priority audit logging
  {"audit.**", %Instruction{action: AuditLogger}, 100},

  # Pattern matching for large payments
  {"payment.processed",
    fn signal -> signal.data.amount > 1000 end,
    %Instruction{action: HandleLargePayment}}
])

Dynamic route management:

# Add routes
{:ok, router} = Router.add(router, [
  {"metrics.**", %Instruction{action: CollectMetrics}}
])

# Remove routes
{:ok, router} = Router.remove(router, "metrics.**")

Signal routing:

{:ok, instructions} = Router.route(router, %Signal{
  type: "payment.processed",
  data: %{amount: 2000}
})

Path Complexity Scoring

The router uses a sophisticated scoring system to determine handler execution order:

1. Base score from segment count (length * 2000)
2. Exact match bonuses (3000 per segment, weighted by position)
3. Wildcard penalties:
   • Single wildcard (): 1000 - position_index 100
   • Multi-wildcard (*): 2000 - position_index 200

This ensures more specific routes take precedence over wildcards, while maintaining predictable execution order.

Best Practices

1. Route Design

   • Use consistent, hierarchical path patterns
   • Prefer exact matches over wildcards when possible
   • Keep path segments meaningful and well-structured
   • Document your path hierarchy

2. Priority Management

   • Reserve high priorities (75-100) for critical handlers
   • Use default priority (0) for standard business logic
   • Reserve low priorities (-100 to -75) for metrics/logging
   • Document priority ranges for your application

3. Pattern Matching

   • Keep match functions simple and fast
   • Handle nil/missing data gracefully
   • Avoid side effects in match functions
   • Test edge cases thoroughly

4. Performance Considerations

   • Monitor route count in production
   • Use pattern matching sparingly
   • Consider complexity scores when designing paths
   • Profile routing performance under load

Error Handling

The router provides detailed error feedback for:

• Invalid path patterns
• Priority out of bounds
• Invalid match functions
• Missing handlers
• Malformed signals

Implementation Details

The router uses several specialized structs:

• Route - Defines a single routing rule
• TrieNode - Internal trie structure node
• HandlerInfo - Stores handler metadata
• PatternMatch - Encapsulates pattern matching rules

See the corresponding typespecs for detailed field information.

See Also

• Jido.Signal - Signal structure and validation
• Jido.Instruction - Handler instruction format
• Jido.Error - Error types and handling