|
|
|
|
@@ -34,10 +34,10 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
|
|
|
|
|
### 🌐 Universal Traffic Router
|
|
|
|
|
- **HTTP/HTTPS routing** with domain matching, path-based forwarding, and automatic TLS
|
|
|
|
|
- **TCP/SNI proxy** for any protocol with TLS termination or passthrough
|
|
|
|
|
- **DNS server** with authoritative zones, dynamic record management, and DNS-over-HTTPS
|
|
|
|
|
- **DNS server** (Rust-powered via [SmartDNS](https://code.foss.global/push.rocks/smartdns)) with authoritative zones, dynamic record management, and DNS-over-HTTPS
|
|
|
|
|
- **Multi-protocol support** on the same infrastructure via [SmartProxy](https://code.foss.global/push.rocks/smartproxy)
|
|
|
|
|
|
|
|
|
|
### 📧 Complete Email Infrastructure
|
|
|
|
|
### 📧 Complete Email Infrastructure (powered by [smartmta](https://code.foss.global/push.rocks/smartmta))
|
|
|
|
|
- **Multi-domain SMTP server** on standard ports (25, 587, 465)
|
|
|
|
|
- **Pattern-based email routing** with four action types: forward, process, deliver, reject
|
|
|
|
|
- **DKIM signing & verification**, SPF, DMARC authentication stack
|
|
|
|
|
@@ -59,14 +59,16 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
|
|
|
|
|
|
|
|
|
|
### ⚡ High Performance
|
|
|
|
|
- **Rust-powered proxy engine** via SmartProxy for maximum throughput
|
|
|
|
|
- **Rust-powered MTA engine** via smartmta (TypeScript + Rust hybrid) for reliable email delivery
|
|
|
|
|
- **Rust-powered DNS engine** via SmartDNS for high-performance UDP and DNS-over-HTTPS
|
|
|
|
|
- **Connection pooling** for outbound SMTP and backend services
|
|
|
|
|
- **Socket-handler mode** — direct socket passing eliminates internal port hops
|
|
|
|
|
- **Real-time metrics** via SmartMetrics (CPU, memory, connections, throughput)
|
|
|
|
|
|
|
|
|
|
### 💾 Persistent Storage & Caching
|
|
|
|
|
- **Multiple storage backends**: filesystem, custom functions, or in-memory
|
|
|
|
|
- **Embedded cache database** via smartdata + TsmDb (MongoDB-compatible)
|
|
|
|
|
- **Automatic TTL-based cleanup** for cached emails, IP reputation, DKIM keys, and more
|
|
|
|
|
- **Embedded cache database** via smartdata + LocalTsmDb (MongoDB-compatible)
|
|
|
|
|
- **Automatic TTL-based cleanup** for cached emails and IP reputation data
|
|
|
|
|
|
|
|
|
|
### 🖥️ OpsServer Dashboard
|
|
|
|
|
- **Web-based management interface** with real-time monitoring
|
|
|
|
|
@@ -84,7 +86,7 @@ npm install @serve.zone/dcrouter
|
|
|
|
|
|
|
|
|
|
### Prerequisites
|
|
|
|
|
|
|
|
|
|
- **Node.js 18+** with ES module support
|
|
|
|
|
- **Node.js 20+** with ES module support
|
|
|
|
|
- Valid domain with DNS control (for ACME certificate automation)
|
|
|
|
|
- Cloudflare API token (for DNS-01 challenges) — optional
|
|
|
|
|
|
|
|
|
|
@@ -172,7 +174,7 @@ const router = new DcRouter({
|
|
|
|
|
acme: { email: 'ssl@example.com', enabled: true, useProduction: true }
|
|
|
|
|
},
|
|
|
|
|
|
|
|
|
|
// Email system
|
|
|
|
|
// Email system (powered by smartmta)
|
|
|
|
|
emailConfig: {
|
|
|
|
|
ports: [25, 587, 465],
|
|
|
|
|
hostname: 'mail.example.com',
|
|
|
|
|
@@ -244,10 +246,10 @@ graph TB
|
|
|
|
|
|
|
|
|
|
subgraph "DcRouter Core"
|
|
|
|
|
DC[DcRouter Orchestrator]
|
|
|
|
|
SP[SmartProxy Engine]
|
|
|
|
|
ES[Unified Email Server]
|
|
|
|
|
DS[DNS Server]
|
|
|
|
|
RS[RADIUS Server]
|
|
|
|
|
SP[SmartProxy Engine<br/><i>Rust-powered</i>]
|
|
|
|
|
ES[smartmta Email Server<br/><i>TypeScript + Rust</i>]
|
|
|
|
|
DS[SmartDNS Server<br/><i>Rust-powered</i>]
|
|
|
|
|
RS[SmartRadius Server]
|
|
|
|
|
CM[Certificate Manager]
|
|
|
|
|
OS[OpsServer Dashboard]
|
|
|
|
|
MM[Metrics Manager]
|
|
|
|
|
@@ -289,17 +291,36 @@ graph TB
|
|
|
|
|
|
|
|
|
|
### Core Components
|
|
|
|
|
|
|
|
|
|
| Component | Description |
|
|
|
|
|
|-----------|-------------|
|
|
|
|
|
| **DcRouter** | Central orchestrator — starts, stops, and coordinates all services |
|
|
|
|
|
| **SmartProxy** | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config |
|
|
|
|
|
| **UnifiedEmailServer** | Full SMTP server with pattern-based routing, DKIM, queue management |
|
|
|
|
|
| **DNS Server** | Authoritative DNS with dynamic records, DKIM TXT auto-generation |
|
|
|
|
|
| **RADIUS Server** | Network authentication with MAB, VLAN assignment, and accounting |
|
|
|
|
|
| **OpsServer** | Web dashboard + TypedRequest API for monitoring and management |
|
|
|
|
|
| **MetricsManager** | Real-time metrics collection (CPU, memory, email, DNS, security) |
|
|
|
|
|
| **StorageManager** | Pluggable key-value storage (filesystem, custom, or in-memory) |
|
|
|
|
|
| **CacheDb** | Embedded MongoDB-compatible database for persistent caching |
|
|
|
|
|
| Component | Package | Description |
|
|
|
|
|
|-----------|---------|-------------|
|
|
|
|
|
| **DcRouter** | `@serve.zone/dcrouter` | Central orchestrator — starts, stops, and coordinates all services |
|
|
|
|
|
| **SmartProxy** | `@push.rocks/smartproxy` | High-performance HTTP/HTTPS and TCP/SNI proxy with route-based config (Rust engine) |
|
|
|
|
|
| **UnifiedEmailServer** | `@push.rocks/smartmta` | Full SMTP server with pattern-based routing, DKIM, queue management (TypeScript + Rust) |
|
|
|
|
|
| **DNS Server** | `@push.rocks/smartdns` | Authoritative DNS with dynamic records and DKIM TXT auto-generation (Rust engine) |
|
|
|
|
|
| **RADIUS Server** | `@push.rocks/smartradius` | Network authentication with MAB, VLAN assignment, and accounting |
|
|
|
|
|
| **OpsServer** | `@api.global/typedserver` | Web dashboard + TypedRequest API for monitoring and management |
|
|
|
|
|
| **MetricsManager** | `@push.rocks/smartmetrics` | Real-time metrics collection (CPU, memory, email, DNS, security) |
|
|
|
|
|
| **StorageManager** | built-in | Pluggable key-value storage (filesystem, custom, or in-memory) |
|
|
|
|
|
| **CacheDb** | `@push.rocks/smartdata` | Embedded MongoDB-compatible database (LocalTsmDb) for persistent caching |
|
|
|
|
|
|
|
|
|
|
### How It Works
|
|
|
|
|
|
|
|
|
|
DcRouter acts purely as an **orchestrator** — it doesn't implement protocols itself. Instead, it wires together best-in-class packages for each protocol:
|
|
|
|
|
|
|
|
|
|
1. **On `start()`**: DcRouter initializes OpsServer (port 3000), then spins up SmartProxy, smartmta, SmartDNS, and SmartRadius based on which configs are provided.
|
|
|
|
|
2. **During operation**: Each service handles its own protocol independently. SmartProxy uses a Rust-powered engine for maximum throughput. smartmta uses a hybrid TypeScript + Rust architecture for reliable email delivery.
|
|
|
|
|
3. **On `stop()`**: All services are gracefully shut down in reverse order.
|
|
|
|
|
|
|
|
|
|
### Rust-Powered Architecture
|
|
|
|
|
|
|
|
|
|
DcRouter itself is a pure TypeScript orchestrator, but three of its core sub-components ship with **compiled Rust binaries** for performance-critical paths. At runtime each package detects the platform, unpacks the correct binary, and communicates with TypeScript over IPC/FFI — so you get the ergonomics of TypeScript with the throughput of native code.
|
|
|
|
|
|
|
|
|
|
| Component | Rust Binary | What It Handles |
|
|
|
|
|
|-----------|-------------|-----------------|
|
|
|
|
|
| **SmartProxy** | `smartproxy-bin` | All TCP/TLS/HTTP proxy networking, NFTables integration, connection metrics |
|
|
|
|
|
| **smartmta** | `mailer-bin` | SMTP server + client, DKIM/SPF/DMARC, content scanning, IP reputation |
|
|
|
|
|
| **SmartDNS** | `smartdns-bin` | DNS server (UDP + DNS-over-HTTPS), DNSSEC, DNS client resolution |
|
|
|
|
|
| **SmartRadius** | — | Pure TypeScript (no Rust component) |
|
|
|
|
|
|
|
|
|
|
## Configuration Reference
|
|
|
|
|
|
|
|
|
|
@@ -312,22 +333,8 @@ interface IDcRouterOptions {
|
|
|
|
|
smartProxyConfig?: ISmartProxyOptions;
|
|
|
|
|
|
|
|
|
|
// ── Email ──────────────────────────────────────────────────────
|
|
|
|
|
/** Unified email server configuration */
|
|
|
|
|
emailConfig?: {
|
|
|
|
|
ports: number[]; // e.g. [25, 587, 465]
|
|
|
|
|
hostname: string; // e.g. 'mail.example.com'
|
|
|
|
|
domains: IEmailDomainConfig[]; // Domain infrastructure
|
|
|
|
|
routes: IEmailRoute[]; // Routing rules
|
|
|
|
|
useSocketHandler?: boolean; // Direct socket passing (no port binding)
|
|
|
|
|
auth?: { required?: boolean; methods?: ('PLAIN'|'LOGIN'|'OAUTH2')[]; users?: Array<{username: string; password: string}> };
|
|
|
|
|
tls?: { certPath?: string; keyPath?: string; caPath?: string };
|
|
|
|
|
maxMessageSize?: number;
|
|
|
|
|
defaults?: {
|
|
|
|
|
dnsMode?: 'forward' | 'internal-dns' | 'external-dns';
|
|
|
|
|
dkim?: IEmailDomainConfig['dkim'];
|
|
|
|
|
rateLimits?: IEmailDomainConfig['rateLimits'];
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
/** Unified email server configuration (smartmta) */
|
|
|
|
|
emailConfig?: IUnifiedEmailServerOptions;
|
|
|
|
|
|
|
|
|
|
/** Custom email port mapping overrides */
|
|
|
|
|
emailPortConfig?: {
|
|
|
|
|
@@ -338,9 +345,9 @@ interface IDcRouterOptions {
|
|
|
|
|
|
|
|
|
|
// ── DNS ────────────────────────────────────────────────────────
|
|
|
|
|
/** Nameserver domains — get A records automatically */
|
|
|
|
|
dnsNsDomains?: string[]; // e.g. ['ns1.example.com', 'ns2.example.com']
|
|
|
|
|
dnsNsDomains?: string[];
|
|
|
|
|
/** Domains this server is authoritative for */
|
|
|
|
|
dnsScopes?: string[]; // e.g. ['example.com']
|
|
|
|
|
dnsScopes?: string[];
|
|
|
|
|
/** Public IP for NS A records */
|
|
|
|
|
publicIp?: string;
|
|
|
|
|
/** Ingress proxy IPs (hides real server IP) */
|
|
|
|
|
@@ -453,7 +460,7 @@ DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for a
|
|
|
|
|
|
|
|
|
|
## Email System
|
|
|
|
|
|
|
|
|
|
The email system is built around the **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing in a single unified component.
|
|
|
|
|
The email system is powered by [`@push.rocks/smartmta`](https://code.foss.global/push.rocks/smartmta), a TypeScript + Rust hybrid MTA. DcRouter configures and orchestrates smartmta's **UnifiedEmailServer**, which handles SMTP sessions, route matching, delivery queuing, DKIM signing, and all email processing.
|
|
|
|
|
|
|
|
|
|
### Email Domain Configuration
|
|
|
|
|
|
|
|
|
|
@@ -722,7 +729,7 @@ Used for: DKIM keys, email routes, bounce/suppression lists, IP reputation data,
|
|
|
|
|
|
|
|
|
|
### Cache Database
|
|
|
|
|
|
|
|
|
|
An embedded MongoDB-compatible database (via smartdata + TsmDb) for persistent caching with automatic TTL cleanup:
|
|
|
|
|
An embedded MongoDB-compatible database (via smartdata + LocalTsmDb) for persistent caching with automatic TTL cleanup:
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
cacheConfig: {
|
|
|
|
|
@@ -740,7 +747,7 @@ cacheConfig: {
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Cached document types: `CachedEmail`, `CachedIPReputation`, `CachedBounce`, `CachedSuppression`, `CachedDKIMKey`.
|
|
|
|
|
Cached document types: `CachedEmail`, `CachedIPReputation`.
|
|
|
|
|
|
|
|
|
|
## Security Features
|
|
|
|
|
|
|
|
|
|
@@ -814,31 +821,39 @@ All management is done via TypedRequest over HTTP POST to `/typedrequest`:
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
// Authentication
|
|
|
|
|
{ method: 'adminLogin', data: { username, password } }
|
|
|
|
|
{ method: 'verifyIdentity', data: { identity } }
|
|
|
|
|
'adminLoginWithUsernameAndPassword' // Login with credentials → returns JWT identity
|
|
|
|
|
'verifyIdentity' // Verify JWT token validity
|
|
|
|
|
'adminLogout' // End admin session
|
|
|
|
|
|
|
|
|
|
// Statistics
|
|
|
|
|
{ method: 'getServerStatistics', data: { identity } }
|
|
|
|
|
{ method: 'getCombinedMetrics', data: { identity } }
|
|
|
|
|
{ method: 'getHealthStatus', data: { identity } }
|
|
|
|
|
// Statistics & Health
|
|
|
|
|
'getServerStatistics' // Uptime, CPU, memory, connections
|
|
|
|
|
'getHealthStatus' // System health check
|
|
|
|
|
'getCombinedMetrics' // All metrics in one call
|
|
|
|
|
|
|
|
|
|
// Email Operations
|
|
|
|
|
{ method: 'getQueuedEmails', data: { identity } }
|
|
|
|
|
{ method: 'getSentEmails', data: { identity } }
|
|
|
|
|
{ method: 'getFailedEmails', data: { identity } }
|
|
|
|
|
{ method: 'resendEmail', data: { identity, emailId } }
|
|
|
|
|
{ method: 'getBounceRecords', data: { identity } }
|
|
|
|
|
'getQueuedEmails' // Emails pending delivery
|
|
|
|
|
'getSentEmails' // Successfully delivered emails
|
|
|
|
|
'getFailedEmails' // Failed emails
|
|
|
|
|
'resendEmail' // Re-queue a failed email
|
|
|
|
|
'getBounceRecords' // Bounce records
|
|
|
|
|
'removeFromSuppressionList' // Unsuppress an address
|
|
|
|
|
|
|
|
|
|
// Configuration (read-only)
|
|
|
|
|
{ method: 'getConfiguration', data: { identity } }
|
|
|
|
|
'getConfiguration' // Current system config
|
|
|
|
|
|
|
|
|
|
// Logs
|
|
|
|
|
{ method: 'getLogs', data: { identity, level, limit } }
|
|
|
|
|
'getLogs' // Retrieve system logs
|
|
|
|
|
|
|
|
|
|
// RADIUS
|
|
|
|
|
{ method: 'getRadiusSessions', data: { identity } }
|
|
|
|
|
{ method: 'getRadiusClients', data: { identity } }
|
|
|
|
|
{ method: 'getRadiusStatistics', data: { identity } }
|
|
|
|
|
'getRadiusSessions' // Active RADIUS sessions
|
|
|
|
|
'getRadiusClients' // List NAS clients
|
|
|
|
|
'getRadiusStatistics' // RADIUS stats
|
|
|
|
|
'setRadiusClient' // Add/update NAS client
|
|
|
|
|
'removeRadiusClient' // Remove NAS client
|
|
|
|
|
'getVlanMappings' // List VLAN mappings
|
|
|
|
|
'setVlanMapping' // Add/update VLAN mapping
|
|
|
|
|
'removeVlanMapping' // Remove VLAN mapping
|
|
|
|
|
'testVlanAssignment' // Test what VLAN a MAC gets
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## API Reference
|
|
|
|
|
@@ -869,7 +884,7 @@ const router = new DcRouter(options: IDcRouterOptions);
|
|
|
|
|
|----------|------|-------------|
|
|
|
|
|
| `options` | `IDcRouterOptions` | Current configuration |
|
|
|
|
|
| `smartProxy` | `SmartProxy` | SmartProxy instance |
|
|
|
|
|
| `emailServer` | `UnifiedEmailServer` | Email server instance |
|
|
|
|
|
| `emailServer` | `UnifiedEmailServer` | Email server instance (from smartmta) |
|
|
|
|
|
| `dnsServer` | `DnsServer` | DNS server instance |
|
|
|
|
|
| `radiusServer` | `RadiusServer` | RADIUS server instance |
|
|
|
|
|
| `storageManager` | `StorageManager` | Storage backend |
|
|
|
|
|
@@ -877,6 +892,21 @@ const router = new DcRouter(options: IDcRouterOptions);
|
|
|
|
|
| `metricsManager` | `MetricsManager` | Metrics collector |
|
|
|
|
|
| `cacheDb` | `CacheDb` | Cache database instance |
|
|
|
|
|
|
|
|
|
|
### Re-exported Types
|
|
|
|
|
|
|
|
|
|
DcRouter re-exports key types from smartmta for convenience:
|
|
|
|
|
|
|
|
|
|
```typescript
|
|
|
|
|
import {
|
|
|
|
|
DcRouter,
|
|
|
|
|
IDcRouterOptions,
|
|
|
|
|
UnifiedEmailServer,
|
|
|
|
|
type IUnifiedEmailServerOptions,
|
|
|
|
|
type IEmailRoute,
|
|
|
|
|
type IEmailDomainConfig,
|
|
|
|
|
} from '@serve.zone/dcrouter';
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Sub-Modules
|
|
|
|
|
|
|
|
|
|
DcRouter is published as a monorepo with separately-installable interface and web packages:
|
|
|
|
|
@@ -895,31 +925,34 @@ import { data, requests } from '@serve.zone/dcrouter/interfaces';
|
|
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
|
|
|
|
|
DcRouter includes a comprehensive test suite with **198 test files** covering all system components:
|
|
|
|
|
|
|
|
|
|
- **SMTP Protocol** — EHLO, MAIL FROM, RCPT TO, DATA, STARTTLS, AUTH, pipelining
|
|
|
|
|
- **Email Routing** — Pattern matching, route priorities, all action types
|
|
|
|
|
- **Email Security** — DKIM, SPF, DMARC, content scanning, rate limiting
|
|
|
|
|
- **DNS** — Record management, socket handler, validation, mode switching
|
|
|
|
|
- **RADIUS** — Authentication, VLAN assignment, accounting
|
|
|
|
|
- **Deliverability** — IP warmup, reputation monitoring, bounce management
|
|
|
|
|
- **Storage & Cache** — All backends, TTL cleanup, persistence
|
|
|
|
|
- **OpsServer** — API authentication, protected endpoints, statistics
|
|
|
|
|
- **Integration** — Full end-to-end workflows
|
|
|
|
|
|
|
|
|
|
### Running Tests
|
|
|
|
|
DcRouter includes a comprehensive test suite covering all system components:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# Run all tests
|
|
|
|
|
# Run all tests (10 files, 73 tests)
|
|
|
|
|
pnpm test
|
|
|
|
|
|
|
|
|
|
# Run a specific test file
|
|
|
|
|
tstest test/test.email.router.ts --verbose
|
|
|
|
|
tstest test/test.jwt-auth.ts --verbose
|
|
|
|
|
|
|
|
|
|
# Run SMTP protocol suite
|
|
|
|
|
tstest test/suite/smtpserver_commands/test.cmd-01.ehlo-command.ts --verbose
|
|
|
|
|
# Run with extended timeout
|
|
|
|
|
tstest test/test.opsserver-api.ts --verbose --timeout 60
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Test Coverage
|
|
|
|
|
|
|
|
|
|
| Test File | Area | Tests |
|
|
|
|
|
|-----------|------|-------|
|
|
|
|
|
| `test.contentscanner.ts` | Content scanning (spam, phishing, malware, attachments) | 13 |
|
|
|
|
|
| `test.dcrouter.email.ts` | Email config, domain and route setup | 4 |
|
|
|
|
|
| `test.dns-server-config.ts` | DNS record parsing, grouping, extraction | 5 |
|
|
|
|
|
| `test.dns-socket-handler.ts` | DNS socket handler and route generation | 6 |
|
|
|
|
|
| `test.errors.ts` | Error classes, handler, retry utilities | 5 |
|
|
|
|
|
| `test.ipreputationchecker.ts` | IP reputation, DNSBL, caching, risk classification | 10 |
|
|
|
|
|
| `test.jwt-auth.ts` | JWT login, verification, logout, invalid credentials | 8 |
|
|
|
|
|
| `test.opsserver-api.ts` | Health, statistics, configuration, log APIs | 6 |
|
|
|
|
|
| `test.protected-endpoint.ts` | Admin auth, identity verification, public endpoints | 8 |
|
|
|
|
|
| `test.storagemanager.ts` | Memory, filesystem, custom backends, concurrency | 8 |
|
|
|
|
|
|
|
|
|
|
## 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](./LICENSE) file.
|
|
|
|
|
|
