428 lines
11 KiB
Markdown
428 lines
11 KiB
Markdown
# 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)
|
|
```typescript
|
|
// 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)
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
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
|
|
```typescript
|
|
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
|
|
```typescript
|
|
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
|
|
|
|
1. **Full SmartProxy Power**: All SmartProxy features remain available
|
|
2. **Automatic Email Integration**: Email ports are automatically routed through SmartProxy
|
|
3. **Unified TLS Management**: SmartProxy handles all TLS termination and certificates
|
|
4. **Flexible Configuration**: Mix custom SmartProxy routes with automatic email routes
|
|
5. **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 |