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:

1. Starts its own SMTP server instance
2. Runs comprehensive test scenarios
3. Cleans up all resources
4. 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