dcrouter/readme.md

# 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](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Email System](#email-system)
- [SmartProxy Routing](#smartproxy-routing)
- [Security Features](#security-features)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Troubleshooting](#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

```bash
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

```typescript
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

```typescript
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

```mermaid
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

```typescript
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

```typescript
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.

```typescript
{
  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.

```typescript
{
  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.

```typescript
{
  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**
```typescript
// 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**
```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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
```typescript
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>`
```typescript
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`
```typescript
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

```typescript
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

```typescript
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
```bash
# 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
```bash
# 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
```bash
# Test DNS server
dig @your-server.com your-domain.com

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

### Logging and Monitoring

```typescript
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

```typescript
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

```bash
# 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](https://docs.serve.zone/dcrouter)
- Issues: [https://github.com/serve-zone/dcrouter/issues](https://github.com/serve-zone/dcrouter/issues)
- Community: [https://community.serve.zone](https://community.serve.zone)