Platform Service - SmartProxy Architecture Update Plan

Command to reread CLAUDE.md: cat /home/philkunz/.claude/CLAUDE.md

Overview

SmartProxy has undergone a major architectural update, moving from a direct port-to-port proxy configuration to a flexible route-based system. This plan outlines the necessary updates to integrate these changes into the platformservice while retaining all SmartProxy functionality.

New SmartProxy Architecture

Previous Architecture (Legacy)

// Old configuration style
{
  fromPort: 443,
  toPort: 8080,
  targetIP: 'backend.server.com',
  sniEnabled: true,
  domainConfigs: [
    {
      domain: 'example.com',
      target: 'backend1.server.com',
      port: 8081
    }
  ]
}

New Architecture (Route-Based)

// New configuration style - FULL SmartProxy functionality
{
  routes: [
    {
      name: 'https-traffic',
      match: {
        ports: 443,
        domains: ['example.com', '*.example.com']
      },
      action: {
        type: 'forward',
        target: {
          host: 'backend.server.com',
          port: 8080
        }
      },
      tls: {
        mode: 'terminate',
        certificate: 'auto'
      }
    }
  ],
  defaults: {
    target: {
      host: 'fallback.server.com',
      port: 8080
    },
    security: {
      ipAllowList: ['192.168.1.0/24'],
      maxConnections: 1000
    }
  }
}

Integration Approach

1. Direct SmartProxy Configuration

The DcRouter will expose the full SmartProxy configuration directly, with additional email integration that automatically adds email routes to SmartProxy:

export interface IDcRouterOptions {
  /**
   * Full SmartProxy configuration - ALL SmartProxy features available
   * This handles HTTP/HTTPS and general TCP/SNI traffic
   */
  smartProxyConfig?: plugins.smartproxy.ISmartProxyOptions;
  
  /**
   * Email configuration - automatically creates SmartProxy routes for email ports
   */
  emailConfig?: IEmailConfig;
  
  /**
   * Additional configuration options
   */
  tls?: {
    contactEmail: string;
    domain?: string;
    certPath?: string;
    keyPath?: string;
  };
  
  /**
   * DNS server configuration
   */
  dnsServerConfig?: plugins.smartdns.IDnsServerOptions;
}

2. Email Route Auto-Generation

When email configuration is provided, DcRouter will automatically generate SmartProxy routes for email traffic:

private async setupSmartProxy() {
  let routes: plugins.smartproxy.IRouteConfig[] = [];
  let acmeConfig: plugins.smartproxy.IAcmeOptions | undefined;
  
  // If user provides full SmartProxy config, use it directly
  if (this.options.smartProxyConfig) {
    routes = this.options.smartProxyConfig.routes || [];
    acmeConfig = this.options.smartProxyConfig.acme;
  }
  
  // If email config exists, automatically add email routes
  if (this.options.emailConfig) {
    const emailRoutes = this.generateEmailRoutes(this.options.emailConfig);
    routes = [...routes, ...emailRoutes];
  }
  
  // Merge TLS/ACME configuration if provided at root level
  if (this.options.tls && !acmeConfig) {
    acmeConfig = {
      accountEmail: this.options.tls.contactEmail,
      enabled: true,
      useProduction: true,
      autoRenew: true,
      renewThresholdDays: 30
    };
  }
  
  // Initialize SmartProxy with combined configuration
  this.smartProxy = new plugins.smartproxy.SmartProxy({
    ...this.options.smartProxyConfig,
    routes,
    acme: acmeConfig
  });
  
  await this.smartProxy.start();
  logger.info('SmartProxy started with route-based configuration');
}

private generateEmailRoutes(emailConfig: IEmailConfig): plugins.smartproxy.IRouteConfig[] {
  const emailRoutes: plugins.smartproxy.IRouteConfig[] = [];
  
  // Create routes for each email port
  for (const port of emailConfig.ports) {
    // Handle different email ports differently
    switch (port) {
      case 25: // SMTP
        emailRoutes.push({
          name: 'smtp-route',
          match: {
            ports: [25]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost', // Forward to internal email server
              port: 10025 // Internal email server port
            }
          },
          // No TLS termination for port 25 (STARTTLS handled by email server)
          tls: {
            mode: 'passthrough'
          }
        });
        break;
        
      case 587: // Submission
        emailRoutes.push({
          name: 'submission-route',
          match: {
            ports: [587]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost',
              port: 10587
            }
          },
          tls: {
            mode: 'passthrough' // STARTTLS handled by email server
          }
        });
        break;
        
      case 465: // SMTPS
        emailRoutes.push({
          name: 'smtps-route',
          match: {
            ports: [465]
          },
          action: {
            type: 'forward',
            target: {
              host: 'localhost',
              port: 10465
            }
          },
          tls: {
            mode: 'terminate', // Terminate TLS and re-encrypt to email server
            certificate: 'auto'
          }
        });
        break;
    }
  }
  
  // Add domain-specific email routes if configured
  if (emailConfig.domainRules) {
    for (const rule of emailConfig.domainRules) {
      // Extract domain from pattern (e.g., "*@example.com" -> "example.com")
      const domain = rule.pattern.split('@')[1];
      
      if (domain && rule.mode === 'forward' && rule.target) {
        emailRoutes.push({
          name: `email-forward-${domain}`,
          match: {
            ports: emailConfig.ports,
            domains: [domain]
          },
          action: {
            type: 'forward',
            target: {
              host: rule.target.server,
              port: rule.target.port || 25
            }
          },
          tls: {
            mode: rule.target.useTls ? 'terminate-and-reencrypt' : 'passthrough'
          }
        });
      }
    }
  }
  
  return emailRoutes;
}

3. Email Server Integration

The email server will run on internal ports and receive traffic from SmartProxy:

private async setupUnifiedEmailHandling() {
  if (!this.options.emailConfig) {
    logger.info('No email configuration provided');
    return;
  }

  const emailConfig = this.options.emailConfig;
  
  // Map external ports to internal ports
  const portMapping = {
    25: 10025,   // SMTP
    587: 10587,  // Submission
    465: 10465   // SMTPS
  };
  
  // Create internal email server configuration
  const internalEmailConfig: IEmailConfig = {
    ...emailConfig,
    ports: emailConfig.ports.map(port => portMapping[port] || port + 10000),
    hostname: 'localhost' // Listen on localhost for SmartProxy forwarding
  };
  
  // Initialize email components with internal configuration
  this.domainRouter = new DomainRouter({
    domainRules: emailConfig.domainRules,
    defaultMode: emailConfig.defaultMode,
    defaultServer: emailConfig.defaultServer,
    defaultPort: emailConfig.defaultPort,
    defaultTls: emailConfig.defaultTls
  });
  
  this.unifiedEmailServer = new UnifiedEmailServer({
    ...internalEmailConfig,
    domainRouter: this.domainRouter
  });
  
  await this.unifiedEmailServer.start();
  logger.info('Unified email server started on internal ports');
}

Usage Examples

Example 1: Combined HTTP and Email Configuration

const dcRouter = new DcRouter({
  // Full SmartProxy configuration for HTTP/HTTPS
  smartProxyConfig: {
    routes: [
      {
        name: 'web-traffic',
        match: {
          ports: [80, 443],
          domains: ['www.example.com']
        },
        action: {
          type: 'forward',
          target: {
            host: 'web-backend.example.com',
            port: 8080
          }
        },
        tls: {
          mode: 'terminate',
          certificate: 'auto'
        }
      }
    ],
    acme: {
      accountEmail: 'admin@example.com',
      enabled: true,
      useProduction: true
    }
  },
  
  // Email configuration - automatically creates SmartProxy routes
  emailConfig: {
    ports: [25, 587, 465],
    hostname: 'mail.example.com',
    domainRules: [
      {
        pattern: '*@example.com',
        mode: 'mta',
        mtaOptions: {
          dkimSign: true,
          dkimOptions: {
            domainName: 'example.com',
            keySelector: 'mail',
            privateKey: '...'
          }
        }
      }
    ],
    defaultMode: 'forward',
    defaultServer: 'backup-mail.example.com'
  }
});

Example 2: Advanced SmartProxy Features with Email

const dcRouter = new DcRouter({
  smartProxyConfig: {
    routes: [
      // Custom API route with authentication
      {
        name: 'api-route',
        match: {
          ports: 443,
          domains: 'api.example.com',
          path: '/v1/*'
        },
        action: {
          type: 'forward',
          target: {
            host: (context) => {
              // Dynamic host selection based on context
              return context.headers['x-api-version'] === 'v2' 
                ? 'api-v2.backend.com' 
                : 'api-v1.backend.com';
            },
            port: 9090
          }
        },
        security: {
          authentication: {
            type: 'jwt',
            jwtSecret: process.env.JWT_SECRET
          },
          rateLimit: {
            maxRequestsPerMinute: 100,
            maxRequestsPerSecond: 10
          }
        }
      }
    ],
    // Advanced SmartProxy options
    preserveSourceIP: true,
    enableDetailedLogging: true,
    maxConnectionsPerIP: 50,
    connectionRateLimitPerMinute: 1000
  },
  
  // Email automatically integrates with SmartProxy
  emailConfig: {
    ports: [25, 587, 465],
    hostname: 'mail.example.com',
    domainRules: []
  }
});

Key Benefits

Full SmartProxy Power: All SmartProxy features remain available
Automatic Email Integration: Email ports are automatically routed through SmartProxy
Unified TLS Management: SmartProxy handles all TLS termination and certificates
Flexible Configuration: Mix custom SmartProxy routes with automatic email routes
Performance: SmartProxy's efficient routing benefits email traffic too

Implementation Tasks

Update DcRouter to preserve full SmartProxy configuration
Implement automatic email route generation
Configure email server to run on internal ports
Test integration between SmartProxy and email server
Update documentation with full SmartProxy examples
Create migration guide showing how to use new features
Test advanced SmartProxy features with email routing
Verify TLS handling for different email ports
Test domain-specific email routing through SmartProxy

Notes

SmartProxy acts as the single entry point for all traffic (HTTP, HTTPS, and email)
Email server runs on internal ports and receives forwarded traffic from SmartProxy
TLS termination is handled by SmartProxy where appropriate
STARTTLS for email is handled by the email server itself
All SmartProxy features (rate limiting, authentication, dynamic routing) are available

11 KiB Raw Blame History