smartproxy/readme.plan.md

SmartProxy Enhanced Routing Plan

Goal

Implement enhanced routing structure with multiple targets per route, sub-matching capabilities, and target-specific overrides to enable more elegant and DRY configurations.

Key Changes

1. Update Route Target Interface

• Add match property to IRouteTarget for sub-matching within routes
• Add target-specific override properties (tls, websocket, loadBalancing, etc.)
• Add priority field for controlling match order

2. Update Route Action Interface

• Remove singular target property
• Use only targets array (single target = array with one element)
• Maintain backwards compatibility during migration

3. Implementation Steps

Phase 1: Type Updates

• Update IRouteTarget interface in route-types.ts
  • Add match?: ITargetMatch property
  • Add override properties (tls, websocket, etc.)
  • Add priority?: number field
• Create ITargetMatch interface for sub-matching criteria
• Update IRouteAction to use only targets: IRouteTarget[]

Phase 2: Route Resolution Logic

• Update route matching logic to handle multiple targets
• Implement target sub-matching algorithm:
  1. Sort targets by priority (highest first)
  2. For each target with a match property, check if request matches
  3. Use first matching target, or fallback to target without match
• Ensure target-specific settings override route-level settings

Phase 3: Code Migration

• Find all occurrences of action.target and update to use action.targets
• Update route helpers and utilities
• Update certificate manager to handle multiple targets
• Update connection handlers

Phase 4: Testing

• Update existing tests to use new format
• Add tests for multi-target scenarios
• Add tests for sub-matching logic
• Add tests for setting overrides

Phase 5: Documentation

• Update type documentation
• Add examples of new routing patterns
• Document migration path for existing configs

Example Configurations

Before (Current)

// Need separate routes for different ports/paths
[
  {
    match: { domains: ['api.example.com'], ports: [80] },
    action: {
      type: 'forward',
      target: { host: 'backend', port: 8080 },
      tls: { mode: 'terminate' }
    }
  },
  {
    match: { domains: ['api.example.com'], ports: [443] },
    action: {
      type: 'forward',
      target: { host: 'backend', port: 8081 },
      tls: { mode: 'passthrough' }
    }
  }
]

After (Enhanced)

// Single route with multiple targets
{
  match: { domains: ['api.example.com'], ports: [80, 443] },
  action: {
    type: 'forward',
    targets: [
      {
        match: { ports: [80] },
        host: 'backend',
        port: 8080,
        tls: { mode: 'terminate' }
      },
      {
        match: { ports: [443] },
        host: 'backend',
        port: 8081,
        tls: { mode: 'passthrough' }
      }
    ]
  }
}

Advanced Example

{
  match: { domains: ['app.example.com'], ports: [443] },
  action: {
    type: 'forward',
    tls: { mode: 'terminate', certificate: 'auto' }, // Route-level default
    websocket: { enabled: true }, // Route-level default
    targets: [
      {
        match: { path: '/api/v2/*' },
        host: 'api-v2',
        port: 8082,
        priority: 10
      },
      {
        match: { path: '/api/*', headers: { 'X-Version': 'v1' } },
        host: 'api-v1',
        port: 8081,
        priority: 5
      },
      {
        match: { path: '/ws/*' },
        host: 'websocket-server',
        port: 8090,
        websocket: { 
          enabled: true,
          rewritePath: '/'  // Strip /ws prefix
        }
      },
      {
        // Default target (no match property)
        host: 'web-backend',
        port: 8080
      }
    ]
  }
}

Benefits

1. DRY Configuration: No need to duplicate common settings across routes
2. Flexibility: Different backends for different ports/paths within same domain
3. Clarity: All routing for a domain in one place
4. Performance: Single route lookup instead of multiple
5. Backwards Compatible: Can migrate gradually

Migration Strategy

1. Keep support for target temporarily with deprecation warning
2. Auto-convert target to targets: [target] internally
3. Update documentation with migration examples
4. Remove target support in next major version