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, pattern matching functions, and multiple dispatch targets.

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
• Multiple dispatch targets per route

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)

Dispatch Configurations

The router supports two types of targets:

1. Instructions - Standard action instructions with parameters
2. Dispatch Configs - Adapter-based dispatch configurations

Dispatch configs can be specified in two formats:

1. Single adapter: {adapter, opts}
2. Multiple adapters: [{adapter1, opts1}, {adapter2, opts2}]

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}},

  # Single dispatch target
  {"metrics.collected", {MetricsAdapter, [type: :counter]}},

  # Multiple dispatch targets
  {"system.error", [
    {MetricsAdapter, [type: :error]},
    {AlertAdapter, [priority: :high]},
    {LogAdapter, [level: :error]}
  ]}
])

Dynamic route management:

# Add routes
{:ok, router} = Router.add(router, [
  {"metrics.**", {MetricsAdapter, [type: :gauge]}}
])

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

Signal routing:

# Route to instruction
{:ok, [%Instruction{action: HandleUserCreated}]} = Router.route(router, %Signal{
  type: "user.created",
  data: %{id: "123"}
})

# Route to multiple dispatch targets
{:ok, [
  {MetricsAdapter, [type: :error]},
  {AlertAdapter, [priority: :high]},
  {LogAdapter, [level: :error]}
]} = Router.route(router, %Signal{
  type: "system.error",
  data: %{message: "Critical error"}
})

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. Dispatch Configuration

   • Use single dispatch for simple routing
   • Use multiple dispatch for cross-cutting concerns
   • Keep adapter options minimal and focused
   • Document adapter requirements

5. 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
• Invalid dispatch configurations

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
• Jido.Signal.Dispatch - Dispatch adapter interface