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.

Support

• Documentation: https://docs.serve.zone/dcrouter
• Issues: https://github.com/serve-zone/dcrouter/issues
• Community: https://community.serve.zone