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.

## 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)