- Add core interfaces (IEmailRoute, IEmailMatch, IEmailAction, IEmailContext) - Create EmailRouter class with comprehensive matching capabilities - Support for recipient/sender patterns, IP/CIDR matching, auth checks - Add content matching (headers, size, subject, attachments) - Implement pattern caching for performance - Update plan with completed steps
dcrouter
dcrouter: a traffic router intended to be gating your datacenter.
A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), and DNS protocols. Designed for enterprises requiring robust traffic management, automatic certificate provisioning, and enterprise-grade email infrastructure.
Table of Contents
- Features
- Installation
- Quick Start
- Architecture
- Configuration
- Email System
- SmartProxy Routing
- Security Features
- API Reference
- Examples
- Troubleshooting
Features
🌐 Universal Traffic Router
- HTTP/HTTPS routing with pattern matching and virtual hosts
- TCP/SNI proxy for any protocol with TLS termination/passthrough
- DNS server with authoritative and dynamic record management
- Multi-protocol support on the same infrastructure
🔒 Enterprise Security
- Automatic TLS certificates via ACME with DNS-01 challenges
- IP reputation checking and real-time threat detection
- Content scanning for spam, viruses, and malicious content
- Comprehensive security logging with correlation tracking
📧 Complete Email Infrastructure
- Multi-domain SMTP server on standard ports (25, 587, 465)
- Pattern-based email routing with three processing modes
- DKIM, SPF, DMARC authentication and verification
- Enterprise deliverability with IP warmup and reputation management
⚡ High Performance
- Connection pooling and efficient resource management
- Load balancing with automatic failover
- Rate limiting at multiple levels
- Real-time metrics and monitoring
Installation
npm install @serve.zone/dcrouter --save
Prerequisites
- Node.js 18+ with ES modules support
- Valid domain with DNS control (for ACME certificates)
- Cloudflare API token (for DNS challenges)
Quick Start
Basic HTTP/HTTPS Router
import { DcRouter } from '@serve.zone/dcrouter';
const router = new DcRouter({
smartProxyConfig: {
routes: [
{
name: 'web-service',
match: { domains: ['example.com'], ports: [443] },
action: {
type: 'forward',
target: { host: '192.168.1.10', port: 8080 },
tls: { mode: 'terminate', certificate: 'auto' }
}
}
],
acme: {
email: 'admin@example.com',
enabled: true,
useProduction: true
}
}
});
await router.start();
console.log('DcRouter started successfully');
Basic Email Router
import { DcRouter } from '@serve.zone/dcrouter';
const router = new DcRouter({
emailConfig: {
ports: [25, 587, 465],
hostname: 'mail.example.com',
domainRules: [
{
pattern: '*@example.com',
mode: 'mta',
mtaOptions: {
domain: 'example.com',
dkimSign: true
}
}
],
tls: {
keyPath: './certs/key.pem',
certPath: './certs/cert.pem'
}
}
});
await router.start();
Architecture
System Overview
graph TB
subgraph "External Traffic"
HTTP[HTTP/HTTPS Clients]
SMTP[SMTP Clients]
TCP[TCP Clients]
DNS[DNS Queries]
end
subgraph "DcRouter Core"
DcRouter[DcRouter Orchestrator]
SmartProxy[SmartProxy Engine]
EmailServer[Unified Email Server]
DnsServer[DNS Server]
CertManager[Certificate Manager]
end
subgraph "Backend Services"
WebServices[Web Services]
MailServers[Mail Servers]
Databases[Databases]
APIs[Internal APIs]
end
HTTP --> SmartProxy
TCP --> SmartProxy
SMTP --> EmailServer
DNS --> DnsServer
DcRouter --> SmartProxy
DcRouter --> EmailServer
DcRouter --> DnsServer
DcRouter --> CertManager
SmartProxy --> WebServices
SmartProxy --> APIs
EmailServer --> MailServers
EmailServer --> Databases
CertManager -.-> SmartProxy
CertManager -.-> EmailServer
Core Components
DcRouter Orchestrator
Central coordination engine that manages all services and provides unified configuration.
SmartProxy Engine
High-performance HTTP/HTTPS and TCP/SNI proxy with:
- Pattern-based routing
- TLS termination/passthrough
- Load balancing
- Connection pooling
Unified Email Server
Enterprise-grade SMTP server with:
- Multi-domain support
- Pattern-based routing
- Three processing modes
- Complete authentication stack
Certificate Manager
Automatic TLS certificate provisioning via ACME with DNS-01 challenges.
Configuration
Complete Configuration Interface
interface IDcRouterOptions {
// SmartProxy configuration for HTTP/HTTPS/TCP routing
smartProxyConfig?: {
routes: IRouteConfig[];
acme?: IAcmeConfig;
allowSessionTicket?: boolean;
};
// Email system configuration
emailConfig?: {
ports: number[];
hostname: string;
domainRules: IDomainRule[];
defaultMode: EmailProcessingMode;
auth?: IAuthConfig;
tls?: ITlsConfig;
};
// DNS server configuration
dnsServerConfig?: {
port?: number;
authoritative?: boolean;
records?: IDnsRecord[];
};
// TLS and certificate configuration
tls?: {
contactEmail: string;
domain: string;
};
// DNS challenge configuration
dnsChallenge?: {
cloudflareApiKey: string;
};
}
Route Configuration
interface IRouteConfig {
name: string;
priority?: number;
match: {
domains?: string[];
ports?: number | number[] | { from: number; to: number }[];
};
action: {
type: 'forward' | 'redirect' | 'serve';
target?: {
host: string;
port: number | 'preserve' | ((context: any) => number);
};
tls?: {
mode: 'terminate' | 'passthrough';
certificate?: 'auto' | string;
};
security?: {
ipAllowList?: string[];
ipBlockList?: string[];
};
};
}
Email System
Email Processing Modes
Forward Mode
Routes emails to external SMTP servers with optional authentication and TLS.
{
pattern: '*@company.com',
mode: 'forward',
target: {
server: 'internal-mail.company.com',
port: 25,
useTls: true,
auth: {
username: 'relay-user',
password: 'relay-pass'
}
}
}
MTA Mode
Full Mail Transfer Agent functionality with DKIM signing and delivery queues.
{
pattern: '*@notifications.company.com',
mode: 'mta',
mtaOptions: {
domain: 'notifications.company.com',
dkimSign: true,
dkimOptions: {
domainName: 'notifications.company.com',
keySelector: 'mail',
privateKey: fs.readFileSync('./dkim-private.key', 'utf8')
},
queueConfig: {
maxRetries: 3,
retryDelay: 300000
}
}
}
Process Mode
Store-and-forward with content scanning and transformations.
{
pattern: '*@marketing.company.com',
mode: 'process',
contentScanning: true,
scanners: [
{
type: 'spam',
threshold: 5.0,
action: 'tag'
},
{
type: 'virus',
action: 'reject'
}
],
transformations: [
{
type: 'addHeader',
header: 'X-Marketing-Campaign',
value: 'auto-processed'
}
]
}
Email Security Features
DKIM, SPF, DMARC
// Automatic DKIM signing
const dkimOptions = {
domainName: 'example.com',
keySelector: 'mail',
privateKey: dkimPrivateKey,
algorithm: 'rsa-sha256'
};
// SPF record validation
const spfPolicy = 'v=spf1 include:_spf.google.com ~all';
// DMARC policy enforcement
const dmarcPolicy = {
policy: 'quarantine',
alignment: {
spf: 'relaxed',
dkim: 'strict'
}
};
Content Scanning
const scanners = [
{
type: 'spam',
threshold: 5.0,
action: 'tag',
headers: ['X-Spam-Score', 'X-Spam-Status']
},
{
type: 'virus',
action: 'reject',
quarantine: true
},
{
type: 'attachment',
blockedExtensions: ['.exe', '.bat', '.scr'],
maxSize: 25 * 1024 * 1024 // 25MB
}
];
SmartProxy Routing
HTTP/HTTPS Routing
const routes = [
// API routing with path-based forwarding
{
name: 'api-gateway',
match: {
domains: ['api.example.com'],
ports: [443]
},
action: {
type: 'forward',
target: {
host: '192.168.1.20',
port: (context) => {
// Route based on path
if (context.path.startsWith('/v1/')) return 8080;
if (context.path.startsWith('/v2/')) return 8081;
return 8080;
}
},
tls: {
mode: 'terminate',
certificate: 'auto'
}
}
},
// Static file serving
{
name: 'static-assets',
match: {
domains: ['cdn.example.com'],
ports: [443]
},
action: {
type: 'serve',
root: '/var/www/static',
tls: {
mode: 'terminate',
certificate: 'auto'
}
}
}
];
TCP/SNI Routing
const tcpRoutes = [
// Database connection routing
{
name: 'database-cluster',
match: {
ports: [{ from: 5432, to: 5439 }]
},
action: {
type: 'forward',
target: {
host: '192.168.1.30',
port: 'preserve'
},
security: {
ipAllowList: ['192.168.1.0/24']
}
}
},
// SNI-based routing for TLS services
{
name: 'secure-service',
match: {
domains: ['secure.example.com'],
ports: [8443]
},
action: {
type: 'forward',
target: {
host: '192.168.1.40',
port: 8443
},
tls: {
mode: 'passthrough'
}
}
}
];
Security Features
IP Reputation Checking
import { IpReputationChecker } from '@serve.zone/dcrouter';
const ipChecker = new IpReputationChecker({
providers: ['spamhaus', 'barracuda', 'surbl'],
cacheTimeout: 3600000, // 1 hour
threshold: 0.7
});
// Check IP reputation
const result = await ipChecker.checkIp('192.0.2.1');
if (result.isBlocked) {
console.log(`IP blocked: ${result.reason}`);
}
Content Security Scanner
import { ContentScanner } from '@serve.zone/dcrouter';
const scanner = new ContentScanner({
spamThreshold: 5.0,
virusScanning: true,
attachmentFiltering: {
maxSize: 25 * 1024 * 1024,
blockedTypes: ['.exe', '.bat', '.scr']
}
});
const scanResult = await scanner.scanEmail(email);
API Reference
DcRouter Class
Constructor
constructor(options: IDcRouterOptions)
Methods
start(): Promise<void>
Starts all configured services (SmartProxy, email server, DNS server).
stop(): Promise<void>
Gracefully stops all services.
updateRoutes(routes: IRouteConfig[]): Promise<void>
Updates SmartProxy routes dynamically.
updateDomainRules(rules: IDomainRule[]): Promise<void>
Updates email domain routing rules.
getStats(): IStatsResponse
Returns real-time statistics for all services.
Email Service API
sendEmail(options: IEmailOptions): Promise<string>
const emailId = await router.emailService.sendEmail({
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Test Email',
html: '<p>Hello World</p>',
attachments: []
});
getEmailStatus(emailId: string): IEmailStatus
const status = router.emailService.getEmailStatus(emailId);
console.log(status.status); // 'pending', 'sent', 'delivered', 'bounced'
getDeliveryReport(emailId: string): IDeliveryReport
Detailed delivery information including bounce reasons and tracking data.
Examples
Complete Enterprise Setup
import { DcRouter } from '@serve.zone/dcrouter';
const router = new DcRouter({
// HTTP/HTTPS routing
smartProxyConfig: {
routes: [
// Main website
{
name: 'website',
priority: 100,
match: { domains: ['example.com', 'www.example.com'], ports: [443] },
action: {
type: 'forward',
target: { host: '192.168.1.10', port: 80 },
tls: { mode: 'terminate', certificate: 'auto' }
}
},
// API services
{
name: 'api',
priority: 110,
match: { domains: ['api.example.com'], ports: [443] },
action: {
type: 'forward',
target: { host: '192.168.1.20', port: 8080 },
tls: { mode: 'terminate', certificate: 'auto' }
}
},
// Internal services
{
name: 'internal',
match: { ports: [{ from: 8000, to: 8999 }] },
action: {
type: 'forward',
target: { host: '192.168.1.30', port: 'preserve' },
security: { ipAllowList: ['192.168.0.0/16'] }
}
}
],
// ACME certificate automation
acme: {
email: 'ssl@example.com',
enabled: true,
useProduction: true,
autoRenew: true
}
},
// Enterprise email system
emailConfig: {
ports: [25, 587, 465],
hostname: 'mail.example.com',
// Authentication configuration
auth: {
required: true,
methods: ['PLAIN', 'LOGIN']
},
// TLS configuration
tls: {
keyPath: './certs/mail-key.pem',
certPath: './certs/mail-cert.pem'
},
// Domain routing rules
domainRules: [
// Transactional emails via MTA
{
pattern: '*@notifications.example.com',
mode: 'mta',
mtaOptions: {
domain: 'notifications.example.com',
dkimSign: true,
dkimOptions: {
domainName: 'notifications.example.com',
keySelector: 'mail',
privateKey: dkimKey
}
}
},
// Internal emails forwarded to Exchange
{
pattern: '*@example.com',
mode: 'forward',
target: {
server: 'exchange.internal.example.com',
port: 25,
useTls: true
}
},
// Marketing emails with content scanning
{
pattern: '*@marketing.example.com',
mode: 'process',
contentScanning: true,
scanners: [
{ type: 'spam', threshold: 5.0, action: 'tag' },
{ type: 'virus', action: 'reject' }
]
}
],
// Default fallback
defaultMode: 'forward',
defaultServer: 'backup-mail.example.com',
defaultPort: 25
},
// DNS server for ACME challenges
dnsServerConfig: {
port: 53,
authoritative: true
},
// Cloudflare DNS challenges
dnsChallenge: {
cloudflareApiKey: process.env.CLOUDFLARE_API_KEY
}
});
// Start the router
await router.start();
console.log('Enterprise DcRouter started');
// Monitor statistics
setInterval(() => {
const stats = router.getStats();
console.log('Active connections:', stats.activeConnections);
console.log('Emails processed:', stats.emailsProcessed);
}, 60000);
Email Template System
import { EmailService, TemplateManager } from '@serve.zone/dcrouter';
// Setup email templates
const templateManager = new TemplateManager();
templateManager.addTemplate('welcome', {
subject: 'Welcome to {{company}}!',
html: `
<h1>Welcome {{name}}!</h1>
<p>Thank you for joining {{company}}.</p>
<p>Your account: {{email}}</p>
`,
text: 'Welcome {{name}}! Thank you for joining {{company}}.'
});
// Send templated email
const emailService = new EmailService(router);
await emailService.sendTemplatedEmail('welcome', {
to: 'user@example.com',
templateData: {
name: 'John Doe',
company: 'Example Corp',
email: 'user@example.com'
}
});
Troubleshooting
Common Issues
Certificate Issues
# Check certificate status
curl -I https://your-domain.com
# Verify ACME challenge accessibility
curl http://your-domain.com/.well-known/acme-challenge/test
Email Delivery Issues
# Test SMTP connectivity
telnet your-server.com 25
# Check DKIM record
dig TXT mail._domainkey.your-domain.com
# Verify SPF record
dig TXT your-domain.com
DNS Issues
# Test DNS server
dig @your-server.com your-domain.com
# Check DNS propagation
dig your-domain.com @8.8.8.8
Logging and Monitoring
import { SmartLog } from '@push.rocks/smartlog';
// Configure logging
const logger = new SmartLog({
level: 'info',
transport: 'console'
});
// Monitor email events
router.emailServer.on('emailReceived', (email) => {
logger.log('info', `Email received: ${email.from} -> ${email.to}`);
});
router.emailServer.on('emailSent', (result) => {
logger.log('info', `Email sent: ${result.messageId} (${result.status})`);
});
// Monitor proxy events
router.smartProxy.on('connectionEstablished', (connection) => {
logger.log('info', `Connection: ${connection.clientIp} -> ${connection.target}`);
});
Performance Tuning
const performanceConfig = {
// Connection limits
maxConnections: 1000,
connectionTimeout: 30000,
// Email queue settings
emailQueue: {
concurrency: 10,
maxRetries: 3,
retryDelay: 300000
},
// Cache settings
cache: {
ipReputation: { ttl: 3600000 }, // 1 hour
dns: { ttl: 300000 }, // 5 minutes
certificates: { ttl: 86400000 } // 24 hours
}
};
License
MIT License - see LICENSE file for details.
Testing
Comprehensive Test Suite
DcRouter includes a comprehensive test suite covering all aspects of the system:
SMTP Protocol Tests
- Commands: EHLO, HELO, MAIL FROM, RCPT TO, DATA, RSET, NOOP, QUIT, VRFY, EXPN, HELP
- Extensions: SIZE, PIPELINING, STARTTLS
- Connection Management: TLS/plain connections, timeouts, limits, rejection handling
- Error Handling: Syntax errors, invalid sequences, temporary/permanent failures
- Email Processing: Basic sending, multiple recipients, large emails, invalid addresses
- Security: Authentication, rate limiting
- Performance: Throughput testing
- Edge Cases: Very large emails, special characters
Running Tests
# Run all tests
pnpm test
# Run specific test categories
tsx test/suite/commands/test.ehlo-command.ts
tsx test/suite/connection/test.tls-connection.ts
tsx test/suite/email-processing/test.basic-email.ts
# Run with verbose output
tstest test/suite/security/test.authentication.ts --verbose
Test Infrastructure
The test suite uses a self-contained pattern where each test:
- Starts its own SMTP server instance
- Runs comprehensive test scenarios
- Cleans up all resources
- Provides detailed logging for debugging
This ensures tests are isolated, reliable, and can run in parallel.
Support
- Documentation: https://docs.serve.zone/dcrouter
- Issues: https://github.com/serve-zone/dcrouter/issues
- Community: https://community.serve.zone