smartproxy/readme.md

# @push.rocks/smartproxy

A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the central API to handle all your proxy needs:

- **Unified Route-Based Configuration**: Match/action pattern for clean, consistent traffic routing
- **SSL/TLS Support**: Automatic HTTPS with Let's Encrypt certificate provisioning
- **Flexible Matching Patterns**: Route by port, domain, path, client IP, and TLS version
- **Advanced SNI Handling**: Smart TCP/SNI-based forwarding with IP filtering
- **Multiple Action Types**: Forward traffic or handle with custom socket handlers
- **Dynamic Port Management**: Add or remove listening ports at runtime without restart
- **Security Features**: Route-specific IP allowlists, blocklists, connection limits, and authentication
- **NFTables Integration**: High-performance kernel-level packet forwarding with Linux NFTables
- **Socket Handlers**: Custom socket handling for specialized protocols and use cases
- **Multiple Targets**: Load balancing and failover with support for multiple upstream targets

## Project Architecture Overview

SmartProxy has been restructured using a modern, modular architecture with a unified route-based configuration system:

```
/ts
├── /core                     # Core functionality
│   ├── /models               # Data models and interfaces
│   ├── /utils                # Shared utilities (IP validation, logging, etc.)
│   └── /events               # Common event definitions
├── /forwarding               # Forwarding system
│   ├── /handlers             # Various forwarding handlers
│   │   ├── base-handler.ts   # Abstract base handler
│   │   ├── http-handler.ts   # HTTP-only handler
│   │   └── ...               # Other handlers
│   ├── /config               # Configuration models
│   └── /factory              # Factory for creating handlers
├── /proxies                  # Different proxy implementations
│   ├── /smart-proxy          # SmartProxy implementation
│   │   ├── /models           # SmartProxy-specific interfaces
│   │   │   ├── route-types.ts # Route-based configuration types
│   │   │   └── interfaces.ts  # SmartProxy interfaces
│   │   ├── certificate-manager.ts # SmartCertManager
│   │   ├── cert-store.ts     # Certificate file storage
│   │   ├── route-helpers.ts  # Helper functions for creating routes
│   │   ├── route-manager.ts  # Route management system
│   │   ├── smart-proxy.ts    # Main SmartProxy class
│   │   └── ...               # Supporting classes
│   ├── /http-proxy           # HttpProxy implementation (HTTP/HTTPS handling)
│   └── /nftables-proxy       # NfTablesProxy implementation
├── /tls                      # TLS-specific functionality
│   ├── /sni                  # SNI handling components
│   └── /alerts               # TLS alerts system
└── /routing                  # Routing functionality
    └── /router               # HTTP routing system
```

## Main Components

### Primary API (Recommended)

- **SmartProxy** (`ts/proxies/smart-proxy/smart-proxy.ts`)
  The central unified API for all proxy needs, featuring:
  - Route-based configuration with match/action pattern
  - Flexible matching criteria (ports, domains, paths, client IPs)
  - Multiple action types (forward, redirect, block, socket-handler)
  - Automatic certificate management
  - Advanced security controls
  - Custom socket handling capabilities
  - Load balancing with multiple targets

### Helper Functions

- **createHttpRoute**, **createHttpsTerminateRoute**, **createHttpsPassthroughRoute**
  Helper functions to create different route configurations with clean syntax
- **createHttpToHttpsRedirect**
  Helper function for HTTP to HTTPS redirects using socket handlers
- **createLoadBalancerRoute**, **createCompleteHttpsServer**
  Helper functions for complex configurations
- **createSocketHandlerRoute**, **SocketHandlers**
  Helper functions for custom socket handling
- **createNfTablesRoute**, **createNfTablesTerminateRoute**, **createCompleteNfTablesHttpsServer**
  Helper functions for NFTables-based high-performance kernel-level routing
- **createPortMappingRoute**, **createOffsetPortMappingRoute**, **createDynamicRoute**, **createSmartLoadBalancer**
  Helper functions for dynamic routing and port mapping
- **createApiGatewayRoute**, **addRateLimiting**, **addBasicAuth**, **addJwtAuth**
  Helper functions for API gateway features and authentication

### Specialized Components

- **HttpProxy** (`ts/proxies/http-proxy/http-proxy.ts`)
  HTTP/HTTPS reverse proxy with TLS termination and WebSocket support
- **NfTablesProxy** (`ts/proxies/nftables-proxy/nftables-proxy.ts`)
  Low-level port forwarding using nftables NAT rules
- **SniHandler** (`ts/tls/sni/sni-handler.ts`)
  Utilities for SNI extraction from TLS handshakes

### Core Utilities

- **ValidationUtils** (`ts/core/utils/validation-utils.ts`)
  Domain, port, and configuration validation
- **IpUtils** (`ts/core/utils/ip-utils.ts`)
  IP address validation and filtering with glob patterns

### Interfaces and Types

- `IRouteConfig`, `IRouteMatch`, `IRouteAction` (`ts/proxies/smart-proxy/models/route-types.ts`)
- `IRoutedSmartProxyOptions` (`ts/proxies/smart-proxy/models/route-types.ts`)
- `IHttpProxyOptions` (`ts/proxies/http-proxy/models/types.ts`)
- `INfTableProxySettings` (`ts/proxies/nftables-proxy/models/interfaces.ts`)

## Installation
Install via npm:
```bash
npm install @push.rocks/smartproxy
```

## Quick Start with SmartProxy

SmartProxy v20.0.0 provides a unified route-based configuration system with enhanced certificate management, NFTables integration for high-performance kernel-level routing, custom socket handling, and improved helper functions for common proxy setups.

**⚠️ Breaking Change in v20.0.0**: The route action configuration has changed from single `target` to `targets` array to support multiple upstream targets for load balancing and failover.

```typescript
import {
  SmartProxy,
  createHttpRoute,
  createHttpsTerminateRoute,
  createHttpsPassthroughRoute,
  createHttpToHttpsRedirect,
  createCompleteHttpsServer,
  createLoadBalancerRoute,
  createApiRoute,
  createWebSocketRoute,
  createSocketHandlerRoute,
  createNfTablesRoute,
  createNfTablesTerminateRoute,
  createCompleteNfTablesHttpsServer,
  createPortMappingRoute,
  createOffsetPortMappingRoute,
  createDynamicRoute,
  createSmartLoadBalancer,
  createApiGatewayRoute,
  addRateLimiting,
  addBasicAuth,
  addJwtAuth,
  SocketHandlers
} from '@push.rocks/smartproxy';

// Create a new SmartProxy instance with route-based configuration
const proxy = new SmartProxy({
  // Global ACME settings for all routes with certificate: 'auto'
  acme: {
    email: 'ssl@example.com',       // Required for Let's Encrypt
    useProduction: false,           // Use staging by default
    renewThresholdDays: 30,         // Renew 30 days before expiry
    port: 80,                       // Port for HTTP-01 challenges (use 8080 for non-privileged)
    autoRenew: true,               // Enable automatic renewal
    renewCheckIntervalHours: 24    // Check for renewals daily
  },
  
  // Define all your routing rules in a single array
  routes: [
    // Basic HTTP route - forward traffic from port 80 to internal service
    createHttpRoute('api.example.com', { host: 'localhost', port: 3000 }),

    // HTTPS route with TLS termination and automatic certificates
    createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
      certificate: 'auto'  // Uses global ACME settings
    }),

    // HTTPS passthrough for legacy systems
    createHttpsPassthroughRoute('legacy.example.com', { host: '192.168.1.10', port: 443 }),

    // Redirect HTTP to HTTPS for all domains and subdomains
    createHttpToHttpsRedirect(['example.com', '*.example.com']),

    // Complete HTTPS server (creates both HTTPS route and HTTP redirect)
    ...createCompleteHttpsServer('complete.example.com', { host: 'localhost', port: 3000 }, {
      certificate: 'auto'
    }),

    // API route with CORS headers
    createApiRoute('api.service.com', '/v1', { host: 'api-backend', port: 8081 }, {
      useTls: true,
      certificate: 'auto',
      addCorsHeaders: true
    }),

    // WebSocket route for real-time communication
    createWebSocketRoute('ws.example.com', '/socket', { host: 'socket-server', port: 8082 }, {
      useTls: true,
      certificate: 'auto',
      pingInterval: 30000
    }),


    // Load balancer with multiple backend servers
    createLoadBalancerRoute(
      'app.example.com',
      ['192.168.1.10', '192.168.1.11', '192.168.1.12'],
      8080,
      {
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        }
      }
    ),

    // Custom socket handler for specialized protocols
    createSocketHandlerRoute('telnet.example.com', 23, SocketHandlers.lineProtocol((line, socket) => {
      console.log('Received:', line);
      socket.write(`Echo: ${line}\n`);
    })),

    // High-performance NFTables route (requires root/sudo)
    createNfTablesRoute('fast.example.com', { host: 'backend-server', port: 8080 }, {
      ports: 80,
      protocol: 'tcp',
      preserveSourceIP: true,
      ipAllowList: ['10.0.0.*']
    }),

    // NFTables HTTPS termination for ultra-fast TLS handling
    createNfTablesTerminateRoute('secure-fast.example.com', { host: 'backend-ssl', port: 443 }, {
      ports: 443,
      certificate: 'auto',
      maxRate: '100mbps'
    }),

    // Route with security configuration
    {
      name: 'secure-admin',
      match: {
        ports: 443,
        domains: 'admin.example.com'
      },
      action: {
        type: 'forward',
        targets: [{ host: 'localhost', port: 8080 }],  // Note: targets is an array
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        }
      },
      security: {
        ipAllowList: ['10.0.0.*', '192.168.1.*'],
        ipBlockList: ['192.168.1.100'],
        maxConnections: 100
      }
    }
  ]
});

// Start the proxy
await proxy.start();

// Dynamically add new routes later
await proxy.updateRoutes([
  ...proxy.settings.routes,
  createHttpsTerminateRoute('new-domain.com', { host: 'localhost', port: 9000 }, {
    certificate: 'auto'
  })
]);

// Dynamically add or remove port listeners
await proxy.addListeningPort(8081);
await proxy.removeListeningPort(8081);
console.log('Currently listening on ports:', proxy.getListeningPorts());

// Later, gracefully shut down
await proxy.stop();
```

## Route-Based Configuration System

SmartProxy uses a unified route configuration system based on the `IRouteConfig` interface. This system follows a match/action pattern that makes routing more powerful, flexible, and declarative.

### IRouteConfig Interface

The `IRouteConfig` interface is the core building block of SmartProxy's configuration system. Each route definition consists of match criteria and an action to perform on matched traffic:

```typescript
interface IRouteConfig {
  // What traffic to match (required)
  match: IRouteMatch;

  // What to do with matched traffic (required)
  action: IRouteAction;

  // Security configuration (optional)
  security?: IRouteSecurity;

  // Metadata (all optional)
  name?: string;             // Human-readable name for this route
  description?: string;      // Description of the route's purpose
  priority?: number;         // Controls matching order (higher = matched first)
  tags?: string[];           // Arbitrary tags for categorization
  enabled?: boolean;         // Whether the route is active (default: true)
}
```

#### Match Criteria (IRouteMatch)

The `match` property defines criteria for identifying which incoming traffic should be handled by this route:

```typescript
interface IRouteMatch {
  // Port(s) to match
  ports: number | number[] | string;    // Single port, array, or range like '8000-8999'
  
  // Domain matching (optional - if not specified, matches all domains)
  domains?: string | string[];          // Exact domains or patterns with wildcards
  
  // Path matching (optional)
  path?: string;                        // URL path pattern (supports wildcards)
  
  // Client IP matching (optional)
  clientIp?: string | string[];         // IP addresses or CIDR ranges
  
  // Protocol matching (optional)
  protocol?: 'tcp' | 'udp' | 'http' | 'https' | 'ws' | 'wss';
  
  // TLS version matching (optional)
  tlsVersion?: string | string[];       // e.g., ['TLSv1.2', 'TLSv1.3']
  
  // Custom matcher function (optional)
  customMatcher?: (context: IRouteContext) => boolean | Promise<boolean>;
}
```

**Domain Matching Patterns:**
- Exact match: `example.com`
- Wildcard subdomain: `*.example.com`
- Multiple domains: `['example.com', '*.example.com', 'example.org']`
- All domains: omit the `domains` field

**Path Matching Patterns:**
- Exact path: `/api/users`
- Path prefix with wildcard: `/api/*`
- Path with parameter: `/api/users/:id`
- Multiple path segments: `/api/*/details`

#### Action Types (IRouteAction)

The `action` property defines what to do with matched traffic:

```typescript
interface IRouteAction {
  // Action type (required)
  type: 'forward' | 'redirect' | 'block' | 'socket-handler';
  
  // For 'forward' type - array of upstream targets
  targets?: IRouteTarget[];
  
  // For 'redirect' type
  redirectUrl?: string;               // URL template with placeholders
  redirectCode?: number;              // HTTP status code (301, 302, etc.)
  
  // For 'socket-handler' type
  socketHandler?: (socket: net.Socket, context: IRouteContext) => void | Promise<void>;
  
  // TLS configuration (optional)
  tls?: IRouteTls;
  
  // WebSocket configuration (optional)
  websocket?: {
    enabled: boolean;
    pingInterval?: number;            // Milliseconds between pings
    pingTimeout?: number;             // Milliseconds to wait for pong
  };
  
  // Headers manipulation (optional)
  headers?: {
    request?: Record<string, string>;   // Headers to add to requests
    response?: Record<string, string>;  // Headers to add to responses
  };
}
```

**Forward Action with Multiple Targets:**
```typescript
{
  type: 'forward',
  targets: [
    { host: 'backend1.example.com', port: 8080 },
    { host: 'backend2.example.com', port: 8080 },
    { host: 'backend3.example.com', port: 8080 }
  ]
}
```

**Redirect Action:**
```typescript
{
  type: 'redirect',
  redirectUrl: 'https://{domain}/{path}',  // Placeholders: {domain}, {path}, {clientIp}
  redirectCode: 301
}
```

**Socket Handler Action:**
```typescript
{
  type: 'socket-handler',
  socketHandler: (socket, context) => {
    // Custom logic for handling the socket
    socket.write('Hello from custom handler\n');
    socket.end();
  }
}
```

### Route Examples

#### Basic HTTP Forwarding
```typescript
{
  match: {
    ports: 80,
    domains: 'api.example.com'
  },
  action: {
    type: 'forward',
    targets: [{ host: 'localhost', port: 3000 }]
  }
}
```

#### HTTPS with TLS Termination and Load Balancing
```typescript
{
  match: {
    ports: 443,
    domains: ['secure.example.com', '*.secure.example.com']
  },
  action: {
    type: 'forward',
    targets: [
      { host: '10.0.0.10', port: 8080 },
      { host: '10.0.0.11', port: 8080 },
      { host: '10.0.0.12', port: 8080 }
    ],
    tls: {
      mode: 'terminate',
      certificate: 'auto'  // Automatic Let's Encrypt certificate
    }
  }
}
```

#### WebSocket Route
```typescript
{
  match: {
    ports: 443,
    domains: 'ws.example.com',
    path: '/socket/*'
  },
  action: {
    type: 'forward',
    targets: [{ host: 'websocket-server', port: 8080 }],
    tls: {
      mode: 'terminate',
      certificate: 'auto'
    },
    websocket: {
      enabled: true,
      pingInterval: 30000,
      pingTimeout: 5000
    }
  }
}
```

#### API Gateway with Security
```typescript
{
  match: {
    ports: 443,
    domains: 'api.example.com',
    path: '/v1/*'
  },
  action: {
    type: 'forward',
    targets: [{ host: 'api-backend', port: 8080 }],
    tls: {
      mode: 'terminate',
      certificate: 'auto'
    },
    headers: {
      request: {
        'X-API-Version': 'v1',
        'X-Real-IP': '{clientIp}'
      },
      response: {
        'Access-Control-Allow-Origin': '*',
        'X-Powered-By': 'SmartProxy'
      }
    }
  },
  security: {
    ipAllowList: ['10.0.0.0/8', '172.16.0.0/12'],
    rateLimit: {
      maxRequests: 100,
      windowMs: 60000
    },
    authentication: {
      type: 'basic',
      realm: 'API Access',
      users: {
        'apiuser': 'hashedpassword'
      }
    }
  }
}
```

## NFTables Integration

SmartProxy includes high-performance kernel-level packet forwarding using Linux NFTables. This provides ultra-low latency forwarding by operating at the kernel level.

### Requirements
- Linux kernel with NFTables support
- Root/sudo privileges
- `nft` command-line tool installed

### NFTables Route Example
```typescript
// Basic NFTables forwarding
createNfTablesRoute('fast.example.com', { host: 'backend', port: 8080 }, {
  ports: 80,
  protocol: 'tcp',
  preserveSourceIP: true
})

// NFTables with TLS termination
createNfTablesTerminateRoute('secure-fast.example.com', { host: 'backend', port: 8080 }, {
  ports: 443,
  certificate: 'auto',
  maxRate: '100mbps'
})
```

## Socket Handlers

SmartProxy supports custom socket handlers for implementing specialized protocols or custom logic:

### Pre-built Socket Handlers

```typescript
// Echo server
createSocketHandlerRoute('echo.example.com', 7, SocketHandlers.echo)

// HTTP redirect
createHttpToHttpsRedirect('example.com')

// Line-based protocol
createSocketHandlerRoute('telnet.example.com', 23, SocketHandlers.lineProtocol((line, socket) => {
  socket.write(`You said: ${line}\n`);
}))

// HTTP server for custom logic
createSocketHandlerRoute('custom.example.com', 8080, SocketHandlers.httpServer((req, res) => {
  if (req.url === '/health') {
    res.status(200);
    res.send('OK');
  } else {
    res.status(404);
    res.send('Not Found');
  }
  res.end();
}))

// Block connections
createSocketHandlerRoute('blocked.example.com', 443, SocketHandlers.block('Access Denied'))

// TCP proxy
createSocketHandlerRoute('proxy.example.com', 8080, SocketHandlers.proxy('internal-server', 3000))
```

### Custom Socket Handler

```typescript
{
  match: {
    ports: 9999,
    domains: 'custom.example.com'
  },
  action: {
    type: 'socket-handler',
    socketHandler: async (socket, context) => {
      console.log(`New connection from ${context.clientIp} to ${context.domain}`);
      
      socket.write('Welcome to the custom protocol server\n');
      
      socket.on('data', (data) => {
        // Process incoming data
        const command = data.toString().trim();
        
        if (command === 'QUIT') {
          socket.end('Goodbye\n');
        } else {
          socket.write(`Unknown command: ${command}\n`);
        }
      });
      
      socket.on('error', (err) => {
        console.error('Socket error:', err);
      });
    }
  }
}
```

## Dynamic Port Management

SmartProxy allows you to dynamically add or remove listening ports without restarting:

```typescript
// Add a new listening port
await proxy.addListeningPort(8443);

// Remove a listening port
await proxy.removeListeningPort(8080);

// Get all currently listening ports
const ports = proxy.getListeningPorts(); // [80, 443, 8443]
```

## Certificate Management

SmartProxy includes automatic certificate management with Let's Encrypt support:

### Automatic Certificates (Let's Encrypt)
```typescript
{
  action: {
    tls: {
      mode: 'terminate',
      certificate: 'auto'  // Automatic Let's Encrypt certificate
    }
  }
}
```

### Manual Certificates
```typescript
{
  action: {
    tls: {
      mode: 'terminate',
      certificate: {
        key: fs.readFileSync('./certs/private.key', 'utf8'),
        cert: fs.readFileSync('./certs/certificate.crt', 'utf8')
      }
    }
  }
}
```

### Certificate Store
Certificates are automatically stored and managed:
- Auto certificates: `./certificates/{domain}/`
- Manual certificates: In-memory only

## Security Features

### IP-Based Access Control
```typescript
{
  security: {
    ipAllowList: ['10.0.0.0/8', '192.168.*', '::1'],
    ipBlockList: ['192.168.1.100', '10.0.0.0/24']
  }
}
```

### Connection Limits
```typescript
{
  security: {
    maxConnections: 1000,              // Total connections
    maxConnectionsPerIp: 10            // Per IP address
  }
}
```

### Rate Limiting
```typescript
{
  security: {
    rateLimit: {
      maxRequests: 100,                // Maximum requests
      windowMs: 60000                  // Time window (1 minute)
    }
  }
}
```

### Authentication
```typescript
// Basic Authentication
{
  security: {
    authentication: {
      type: 'basic',
      realm: 'Protected Area',
      users: {
        'admin': 'hashedpassword'
      }
    }
  }
}

// JWT Authentication
{
  security: {
    authentication: {
      type: 'jwt',
      secret: 'your-secret-key',
      algorithms: ['HS256']
    }
  }
}
```

## Advanced Features

### Custom Route Matching
```typescript
{
  match: {
    ports: 443,
    customMatcher: async (context) => {
      // Custom logic to determine if route should match
      const hour = new Date().getHours();
      return hour >= 9 && hour < 17; // Only match during business hours
    }
  }
}
```

### Header Manipulation
```typescript
{
  action: {
    headers: {
      request: {
        'X-Real-IP': '{clientIp}',
        'X-Forwarded-For': '{clientIp}',
        'X-Custom-Header': 'value'
      },
      response: {
        'X-Powered-By': 'SmartProxy',
        'Strict-Transport-Security': 'max-age=31536000'
      }
    }
  }
}
```

### Dynamic Target Selection
```typescript
{
  action: {
    type: 'forward',
    targets: [
      {
        host: ['backend1.example.com', 'backend2.example.com'],  // Round-robin
        port: (context) => {
          // Dynamic port based on path
          return context.path.startsWith('/api/v1') ? 8081 : 8080;
        }
      }
    ]
  }
}
```

## Complete Examples

### Multi-Domain HTTPS Server with Redirects
```typescript
const proxy = new SmartProxy({
  acme: {
    email: 'admin@example.com',
    useProduction: true
  },
  routes: [
    // HTTPS routes
    ...['example.com', 'app.example.com', 'api.example.com'].map(domain =>
      createHttpsTerminateRoute(domain, { host: 'localhost', port: 3000 }, {
        certificate: 'auto'
      })
    ),
    
    // HTTP to HTTPS redirects
    createHttpToHttpsRedirect(['example.com', '*.example.com'])
  ]
});
```

### API Gateway with Multiple Services
```typescript
const proxy = new SmartProxy({
  routes: [
    // User service
    createApiRoute('api.example.com', '/users', { host: 'user-service', port: 8081 }),
    
    // Product service
    createApiRoute('api.example.com', '/products', { host: 'product-service', port: 8082 }),
    
    // Order service with authentication
    {
      match: {
        ports: 443,
        domains: 'api.example.com',
        path: '/orders/*'
      },
      action: {
        type: 'forward',
        targets: [{ host: 'order-service', port: 8083 }],
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        }
      },
      security: {
        authentication: {
          type: 'jwt',
          secret: process.env.JWT_SECRET
        }
      }
    }
  ]
});
```

### WebSocket Server with Load Balancing
```typescript
const proxy = new SmartProxy({
  routes: [
    {
      match: {
        ports: 443,
        domains: 'ws.example.com'
      },
      action: {
        type: 'forward',
        targets: [
          { host: 'ws-server-1', port: 8080 },
          { host: 'ws-server-2', port: 8080 },
          { host: 'ws-server-3', port: 8080 }
        ],
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        },
        websocket: {
          enabled: true,
          pingInterval: 30000
        }
      }
    }
  ]
});
```

## Troubleshooting

### Common Issues

#### Certificate Provisioning
- Ensure domains are publicly accessible
- Check firewall rules for port 80 (ACME challenges)
- Verify DNS resolution
- Check ACME email configuration

#### Connection Issues
- Verify route matching criteria
- Check security rules (IP lists, authentication)
- Ensure target servers are accessible
- Check for port conflicts

#### Performance Issues
- Consider using NFTables for high-traffic routes
- Adjust connection pool sizes
- Enable connection keep-alive
- Monitor resource usage

### Debug Mode
Enable detailed logging:
```typescript
const proxy = new SmartProxy({
  debug: true,
  routes: [...]
});
```

### Route Testing
Test route matching:
```typescript
const matchedRoute = proxy.findMatchingRoute({
  port: 443,
  domain: 'example.com',
  path: '/api/users',
  clientIp: '192.168.1.100'
});

console.log('Matched route:', matchedRoute?.name);
```

## Migration Guide

### From v19.x to v20.x

The main breaking change is the route action configuration:

**Before (v19.x):**
```typescript
{
  action: {
    type: 'forward',
    target: { host: 'localhost', port: 8080 }  // Single target
  }
}
```

**After (v20.x):**
```typescript
{
  action: {
    type: 'forward',
    targets: [{ host: 'localhost', port: 8080 }]  // Array of targets
  }
}
```

Helper functions have been updated to use the new format automatically.

## Best Practices

1. **Use Helper Functions**: They provide sensible defaults and reduce configuration errors
2. **Set Route Priorities**: Higher priority routes are matched first
3. **Use Specific Matches**: More specific routes should have higher priorities
4. **Enable Security Features**: Always use IP filtering and rate limiting for public services
5. **Monitor Performance**: Use debug logging and metrics to identify bottlenecks
6. **Regular Certificate Checks**: Monitor certificate expiration and renewal
7. **Graceful Shutdown**: Always call `proxy.stop()` for clean shutdown

## API Reference

### SmartProxy Class

```typescript
class SmartProxy {
  constructor(options: IRoutedSmartProxyOptions);
  
  // Lifecycle methods
  start(): Promise<void>;
  stop(): Promise<void>;
  
  // Route management
  updateRoutes(routes: IRouteConfig[]): Promise<void>;
  addRoute(route: IRouteConfig): Promise<void>;
  removeRoute(routeName: string): Promise<void>;
  findMatchingRoute(context: Partial<IRouteContext>): IRouteConfig | null;
  
  // Port management
  addListeningPort(port: number): Promise<void>;
  removeListeningPort(port: number): Promise<void>;
  getListeningPorts(): number[];
  
  // Certificate management
  getCertificateInfo(domain: string): ICertificateInfo | null;
  renewCertificate(domain: string): Promise<void>;
  
  // Status and monitoring
  getStatus(): IProxyStatus;
  getMetrics(): IProxyMetrics;
}
```

### Route Configuration Types

See the TypeScript definitions in:
- `ts/proxies/smart-proxy/models/route-types.ts`
- `ts/proxies/smart-proxy/models/interfaces.ts`

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.