serve.zone/dcrouter
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-21 00:12:49 +00:00
parent 5c85188183
commit b1890f59ee
27 changed files with 2096 additions and 705 deletions
Download Patch File Download Diff File Expand all files Collapse all files

428
readme.plan.md
View File

@ -1,428 +0,0 @@
# 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