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 `action.targets[0]`
- [ ] 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)
```typescript
// 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)
```typescript
// 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
```typescript
{
  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