serve.zone/dcrouter
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5de33449054b159de746f444f22ca80dec7eaba3
dcrouter/readme.md

30 KiB
Raw Blame History

@serve.zone/dcrouter

dcrouter: A powerful traffic router designed to be the gateway for your datacenter. 🚀

A comprehensive traffic routing solution that provides unified gateway capabilities for HTTP/HTTPS, TCP/SNI, email (SMTP), DNS protocols, and RADIUS authentication. Designed for enterprises requiring robust traffic management, automatic certificate provisioning, and enterprise-grade email infrastructure.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Table of Contents

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 four processing modes (forward, process, deliver, reject)
  • DKIM, SPF, DMARC authentication and verification
  • Enterprise deliverability with IP warmup and reputation management
  • Bounce handling with suppression lists

📡 RADIUS Server

  • MAC Authentication Bypass (MAB) for network device authentication
  • VLAN assignment based on MAC address or OUI patterns
  • RADIUS accounting for session tracking and billing
  • OpsServer API integration for real-time management

⚡ High Performance

  • Connection pooling and efficient resource management
  • Load balancing with automatic failover
  • Rate limiting at multiple levels
  • Real-time metrics and monitoring

💾 Flexible Storage System

  • Multiple storage backends: filesystem, custom functions, or memory
  • Unified storage interface for all components
  • Automatic data migration between backends
  • Persistent configuration for domains, routes, and security data

🖥️ OpsServer Dashboard

  • Web-based management interface for real-time monitoring
  • JWT authentication with secure admin access
  • Live statistics for connections, email, DNS, and RADIUS
  • Configuration management via TypedRequest API

Installation

npm install @serve.zone/dcrouter --save
# or
pnpm add @serve.zone/dcrouter

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',
          targets: [{ 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',
    routes: [
      {
        name: 'local-mail',
        match: { recipients: '*@example.com' },
        action: {
          type: 'process',
          process: {
            scan: true,
            dkim: true,
            queue: 'normal'
          }
        }
      }
    ],
    tls: {
      keyPath: './certs/key.pem',
      certPath: './certs/cert.pem'
    }
  }
});

await router.start();

With OpsServer Dashboard

import { DcRouter } from '@serve.zone/dcrouter';

const router = new DcRouter({
  // Enable OpsServer for web dashboard
  opsServerConfig: {
    port: 3000,
    admin: {
      username: 'admin',
      password: 'your-secure-password'
    }
  },

  // Your routing configuration...
  smartProxyConfig: { /* ... */ },
  emailConfig: { /* ... */ }
});

await router.start();
// Dashboard available at http://localhost:3000

Architecture

System Overview

graph TB
    subgraph "External Traffic"
        HTTP[HTTP/HTTPS Clients]
        SMTP[SMTP Clients]
        TCP[TCP Clients]
        DNS[DNS Queries]
        RADIUS[RADIUS Clients]
    end

    subgraph "DcRouter Core"
        DcRouter[DcRouter Orchestrator]
        SmartProxy[SmartProxy Engine]
        EmailServer[Unified Email Server]
        DnsServer[DNS Server]
        RadiusServer[RADIUS Server]
        CertManager[Certificate Manager]
        OpsServer[OpsServer Dashboard]
    end

    subgraph "Backend Services"
        WebServices[Web Services]
        MailServers[Mail Servers]
        Databases[Databases]
        APIs[Internal APIs]
    end

    HTTP --> SmartProxy
    TCP --> SmartProxy
    SMTP --> EmailServer
    DNS --> DnsServer
    RADIUS --> RadiusServer

    DcRouter --> SmartProxy
    DcRouter --> EmailServer
    DcRouter --> DnsServer
    DcRouter --> RadiusServer
    DcRouter --> CertManager
    DcRouter --> OpsServer

    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
  • Four processing modes (forward, process, deliver, reject)
  • Complete authentication stack (DKIM, SPF, DMARC)

DNS Server

Authoritative DNS server with:

  • Dynamic record management
  • DNS-over-HTTPS (DoH) support
  • ACME DNS-01 challenge handling

RADIUS Server

Network authentication server with:

  • MAC Authentication Bypass (MAB)
  • VLAN assignment
  • Accounting support

Certificate Manager

Automatic TLS certificate provisioning via ACME with DNS-01 challenges.

OpsServer Dashboard

Web-based management interface with:

  • JWT-secured API
  • Real-time statistics
  • Configuration management

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;
    domains?: IEmailDomainConfig[];  // Domain infrastructure setup
    routes: IEmailRoute[];           // Route-based email handling
    auth?: IAuthConfig;
    tls?: ITlsConfig;
    maxMessageSize?: number;
    rateLimits?: IRateLimitConfig;
    useSocketHandler?: boolean;      // Enable socket-handler mode (no port binding)
    defaults?: {                     // Global defaults for all domains
      dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
      dkim?: IDkimConfig;
      rateLimits?: IRateLimitConfig;
    };
  };

  // DNS server configuration
  dnsServerConfig?: {
    port?: number;
    authoritative?: boolean;
    records?: IDnsRecord[];
  };

  // DNS domain for automatic DNS-over-HTTPS setup
  dnsDomain?: string;               // e.g., 'dns.example.com'

  // DNS nameserver domains (enables authoritative DNS)
  dnsNsDomains?: string[];          // e.g., ['ns1.example.com', 'ns2.example.com']

  // RADIUS server configuration
  radiusConfig?: {
    port?: number;
    secret: string;
    clients?: IRadiusClient[];
    macAuth?: IMacAuthConfig;
    vlanAssignment?: IVlanAssignment[];
  };

  // OpsServer configuration
  opsServerConfig?: {
    port?: number;
    admin: {
      username: string;
      password: string;
    };
  };

  // TLS and certificate configuration
  tls?: {
    contactEmail: string;
    domain: string;
  };

  // DNS challenge configuration
  dnsChallenge?: {
    cloudflareApiKey: string;
  };

  // Storage configuration
  storage?: {
    fsPath?: string;                  // Filesystem storage path
    readFunction?: (key: string) => Promise<string>;    // Custom read function
    writeFunction?: (key: string, value: string) => Promise<void>;  // Custom write function
  };
}

Route Configuration

interface IRouteConfig {
  name: string;
  priority?: number;
  match: {
    domains?: string[];
    ports?: number | number[] | { from: number; to: number }[];
  };
  action: {
    type: 'forward' | 'redirect' | 'serve';
    targets?: Array<{
      host: string;
      port: number | 'preserve' | ((context: any) => number);
    }>;
    tls?: {
      mode: 'terminate' | 'passthrough';
      certificate?: 'auto' | string;
    };
    security?: {
      ipAllowList?: string[];
      ipBlockList?: string[];
    };
  };
}

Socket-Handler Mode

DcRouter supports an advanced socket-handler mode that eliminates internal port binding for both DNS and email services. Instead of services listening on internal ports, SmartProxy passes sockets directly to the services.

DNS Socket-Handler

When dnsDomain is configured, DcRouter automatically:

  • Sets up DNS server for UDP on port 53
  • Creates SmartProxy routes for DNS-over-HTTPS (DoH) on the specified domain
  • Uses socket-handler for HTTPS/DoH traffic (no HTTPS port binding)
const router = new DcRouter({
  dnsDomain: 'dns.example.com',    // Enables DNS with DoH
  smartProxyConfig: {
    // DNS routes are automatically created
  }
});

This creates:

  • UDP DNS service on port 53 (standard DNS queries)
  • HTTPS routes for dns.example.com/dns-query and dns.example.com/resolve
  • Automatic TLS certificates via Let's Encrypt

Email Socket-Handler

When useSocketHandler is enabled in email config:

  • Email server doesn't bind to any ports
  • SmartProxy passes sockets directly to email handlers
  • Reduces latency and resource usage
const router = new DcRouter({
  emailConfig: {
    ports: [25, 587, 465],
    hostname: 'mail.example.com',
    useSocketHandler: true,         // Enable socket-handler mode
    routes: [/* email routes */]
  }
});

Benefits of Socket-Handler Mode

  1. Performance: Eliminates internal port forwarding overhead
  2. Security: No exposed internal ports
  3. Resource Efficiency: Fewer open ports and listeners
  4. Simplified Networking: Direct socket passing
  5. Automatic Configuration: Routes created automatically

Traditional vs Socket-Handler Mode

Traditional Mode (default):

External Port → SmartProxy → Internal Port → Service
    25             →           10025          → Email

Socket-Handler Mode:

External Port → SmartProxy → Socket Handler → Service
    25             →         (direct socket)  → Email

Email System

Email Domain Configuration

DcRouter separates email infrastructure (which domains to handle) from routing logic (how to handle emails):

DNS Modes

Forward Mode - Simple mail forwarding without local DNS:

{
  domain: 'forwarded.com',
  dnsMode: 'forward',
  dns: {
    forward: {
      skipDnsValidation: true,
      targetDomain: 'mail.target.com'
    }
  }
}

Internal DNS Mode - Use built-in DNS server (requires dnsDomain in DcRouter config):

{
  domain: 'mail.example.com',
  dnsMode: 'internal-dns',
  dns: {
    internal: {
      mxPriority: 10,
      ttl: 3600
    }
  },
  dkim: {
    selector: 'mail2024',
    keySize: 2048,
    rotateKeys: true,
    rotationInterval: 90
  }
}

External DNS Mode - Use existing DNS infrastructure:

{
  domain: 'mail.external.com',
  dnsMode: 'external-dns',
  dns: {
    external: {
      requiredRecords: ['MX', 'SPF', 'DKIM', 'DMARC']
    }
  },
  rateLimits: {
    inbound: {
      messagesPerMinute: 100,
      connectionsPerIp: 10
    }
  }
}

DKIM Management

DKIM is always enabled for all domains. Keys are automatically:

  • Generated on first use
  • Stored persistently via StorageManager
  • Rotated based on configuration
  • Cleaned up after grace period

Email Route Actions

Forward Action

Routes emails to external SMTP servers.

{
  name: 'forward-to-internal',
  match: { recipients: '*@company.com' },
  action: {
    type: 'forward',
    forward: {
      host: 'internal-mail.company.com',
      port: 25,
      auth: {
        username: 'relay-user',
        password: 'relay-pass'
      },
      addHeaders: {
        'X-Forwarded-By': 'dcrouter'
      }
    }
  }
}

Process Action

Full Mail Transfer Agent functionality with scanning and delivery queues.

{
  name: 'process-notifications',
  match: { recipients: '*@notifications.company.com' },
  action: {
    type: 'process',
    process: {
      scan: true,
      dkim: true,
      queue: 'priority'
    }
  }
}

Deliver Action

Local delivery for mailbox storage.

{
  name: 'deliver-local',
  match: { recipients: '*@marketing.company.com' },
  action: {
    type: 'deliver'
  }
}

Reject Action

Reject emails with custom SMTP responses.

{
  name: 'reject-spam',
  match: {
    senders: '*@spam-domain.com',
    sizeRange: { min: 1000000 } // > 1MB
  },
  action: {
    type: 'reject',
    reject: {
      code: 550,
      message: 'Message rejected due to policy'
    }
  }
}

Common Email Routing Patterns

IP-Based Relay

Allow internal networks to relay through the server:

{
  name: 'office-relay',
  priority: 100,
  match: { clientIp: ['192.168.0.0/16', '10.0.0.0/8'] },
  action: {
    type: 'forward',
    forward: { host: 'internal-mail.company.com', port: 25 }
  }
}

Domain-Based Routing

Route different domains to different servers:

{
  name: 'partner-domain',
  match: { recipients: '*@partner.com' },
  action: {
    type: 'forward',
    forward: { host: 'partner-mail.com', port: 587 }
  }
}

Authentication-Based Processing

Different handling for authenticated vs unauthenticated senders:

{
  name: 'authenticated-users',
  match: { authenticated: true },
  action: {
    type: 'process',
    process: { scan: false, dkim: true, queue: 'priority' }
  }
},
{
  name: 'unauthenticated-reject',
  match: { authenticated: false },
  action: {
    type: 'reject',
    reject: { code: 550, message: 'Authentication required' }
  }
}

Email Security Features

Route Matching Patterns

Glob Pattern Matching

// Email address patterns
match: { recipients: '*@example.com' }        // All addresses at domain
match: { recipients: 'admin@*' }             // Admin at any domain
match: { senders: ['*@trusted.com', '*@partner.com'] } // Multiple patterns

// CIDR IP matching
match: { clientIp: '192.168.0.0/16' }        // Private subnet
match: { clientIp: ['10.0.0.0/8', '172.16.0.0/12'] } // Multiple ranges

// Header matching
match: {
  headers: {
    'X-Priority': 'high',
    'Subject': /urgent|emergency/i
  }
}

// Size and content matching
match: {
  sizeRange: { min: 1000, max: 5000000 },    // 1KB to 5MB
  hasAttachments: true,
  subject: /invoice|receipt/i
}

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',
      targets: [{ host: '192.168.1.20', port: 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',
      targets: [{ 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',
      targets: [{ host: '192.168.1.40', port: 8443 }],
      tls: {
        mode: 'passthrough'
      }
    }
  }
];

RADIUS Server

DcRouter includes a RADIUS server for network access control:

Basic RADIUS Configuration

const router = new DcRouter({
  radiusConfig: {
    port: 1812,
    secret: 'your-radius-secret',
    clients: [
      {
        name: 'switch-1',
        ip: '192.168.1.1',
        secret: 'client-secret'
      }
    ]
  }
});

MAC Authentication Bypass (MAB)

const router = new DcRouter({
  radiusConfig: {
    port: 1812,
    secret: 'radius-secret',
    macAuth: {
      enabled: true,
      allowedMacs: [
        'aa:bb:cc:dd:ee:ff',
        'aa:bb:cc:*'  // Wildcard for OUI matching
      ],
      defaultVlan: 100,
      guestVlan: 999
    }
  }
});

VLAN Assignment

const router = new DcRouter({
  radiusConfig: {
    secret: 'radius-secret',
    vlanAssignment: [
      {
        match: { mac: 'aa:bb:cc:*' },  // Vendor OUI match
        vlan: 100
      },
      {
        match: { mac: 'dd:ee:ff:*' },
        vlan: 200
      },
      {
        match: { default: true },
        vlan: 999  // Guest VLAN
      }
    ]
  }
});

Storage System

StorageManager

DcRouter includes a flexible storage system that supports multiple backends:

Filesystem Storage

const router = new DcRouter({
  storage: {
    fsPath: '/var/lib/dcrouter/data'
  }
});

Custom Storage Backend

const router = new DcRouter({
  storage: {
    readFunction: async (key) => {
      // Read from Redis, S3, etc.
      return await myDatabase.get(key);
    },
    writeFunction: async (key, value) => {
      // Write to Redis, S3, etc.
      await myDatabase.set(key, value);
    }
  }
});

Memory Storage (Development)

const router = new DcRouter({
  // No storage config = memory storage with warning
});

Storage Usage

The storage system is used for:

  • DKIM Keys: /email/dkim/{domain}/private.key, /email/dkim/{domain}/public.key
  • Email Routes: /email/routes/{routeId}.json
  • Bounce Lists: /email/bounces/suppression.json
  • IP Reputation: /security/ip-reputation/{ip}.json
  • Domain Configs: /email/domains/{domain}.json

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}`);
}

Rate Limiting

const router = new DcRouter({
  emailConfig: {
    rateLimits: {
      inbound: {
        messagesPerMinute: 100,
        connectionsPerIp: 10,
        recipientsPerMessage: 50
      },
      outbound: {
        messagesPerHour: 1000,
        messagesPerDay: 10000
      }
    }
  }
});

OpsServer Dashboard

The OpsServer provides a web-based management interface:

Features

  • Real-time Statistics: View connections, email throughput, DNS queries, RADIUS sessions
  • Configuration Management: Update routes and settings via API
  • Log Viewer: Access system logs with filtering
  • Security Dashboard: Monitor threats and blocked connections

API Endpoints

The OpsServer exposes TypedRequest endpoints:

// Health check
POST /typedrequest { method: 'getHealthStatus' }

// Server statistics
POST /typedrequest { method: 'getServerStatistics' }

// Configuration
POST /typedrequest { method: 'getConfiguration' }
POST /typedrequest { method: 'updateConfiguration', data: { ... } }

// Logs
POST /typedrequest { method: 'getLogs', data: { level: 'info', limit: 100 } }

// RADIUS
POST /typedrequest { method: 'getRadiusSessions' }
POST /typedrequest { method: 'getRadiusClients' }

API Reference

DcRouter Class

Constructor

constructor(options: IDcRouterOptions)

Methods

start(): Promise<void>

Starts all configured services (SmartProxy, email server, DNS server, RADIUS server, OpsServer).

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'

Examples

Complete Enterprise Setup

import { DcRouter } from '@serve.zone/dcrouter';

const router = new DcRouter({
  // OpsServer dashboard
  opsServerConfig: {
    port: 3000,
    admin: {
      username: 'admin',
      password: process.env.ADMIN_PASSWORD
    }
  },

  // HTTP/HTTPS routing
  smartProxyConfig: {
    routes: [
      // Main website
      {
        name: 'website',
        priority: 100,
        match: { domains: ['example.com', 'www.example.com'], ports: [443] },
        action: {
          type: 'forward',
          targets: [{ 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',
          targets: [{ host: '192.168.1.20', port: 8080 }],
          tls: { mode: 'terminate', certificate: 'auto' }
        }
      }
    ],

    // 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',

    // Domain configuration
    domains: [
      {
        domain: 'example.com',
        dnsMode: 'external-dns',
        dkim: {
          selector: 'mail',
          rotateKeys: true
        }
      }
    ],

    // Email routing rules
    routes: [
      // Relay from office network
      {
        name: 'office-relay',
        priority: 100,
        match: { clientIp: '192.168.0.0/16' },
        action: {
          type: 'forward',
          forward: { host: 'internal-mail.example.com', port: 25 }
        }
      },

      // Process transactional emails
      {
        name: 'notifications',
        priority: 50,
        match: { recipients: '*@notifications.example.com' },
        action: {
          type: 'process',
          process: { scan: true, dkim: true, queue: 'priority' }
        }
      },

      // Default reject
      {
        name: 'default-reject',
        match: { recipients: '*' },
        action: {
          type: 'reject',
          reject: { code: 550, message: 'Relay denied' }
        }
      }
    ]
  },

  // RADIUS for network devices
  radiusConfig: {
    port: 1812,
    secret: process.env.RADIUS_SECRET,
    macAuth: {
      enabled: true,
      defaultVlan: 100,
      guestVlan: 999
    }
  },

  // DNS server for ACME challenges
  dnsServerConfig: {
    port: 53,
    authoritative: true
  },

  // Cloudflare DNS challenges
  dnsChallenge: {
    cloudflareApiKey: process.env.CLOUDFLARE_API_KEY
  },

  // Persistent storage
  storage: {
    fsPath: '/var/lib/dcrouter/data'
  }
});

// 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);

Testing

Comprehensive Test Suite

DcRouter includes a comprehensive test suite with 195 test files 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/smtpserver_commands/test.cmd-01.ehlo-command.ts

# Run with verbose output
tstest test/test.integration.ts --verbose

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

Email Routing Issues

Route Not Matching

  • Check route priority order (higher priority = evaluated first)
  • Verify glob patterns: *@example.com matches domain, admin@* matches user
  • Test CIDR notation: 192.168.0.0/16 includes all 192.168.x.x addresses
  • Confirm authentication state matches your expectations

DNS Issues

# Test DNS server
dig @your-server.com your-domain.com

# Check DNS propagation
dig your-domain.com @8.8.8.8

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 and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

Reference in New Issue View Git Blame Copy Permalink