serve.zone/dcrouter
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): refresh package readmes with clearer runtime, API client, interfaces, migrations, and dashboard guidance

Browse Source
This commit is contained in:
Jürgen Kunz
2026-04-17 13:43:13 +00:00
parent 1f25ca4095
commit c5ca95b6f5
9 changed files with 321 additions and 430 deletions
Download Patch File Download Diff File Expand all files Collapse all files

276
readme.md
View File

@@ -2,33 +2,31 @@
![dcrouter banner](https://code.foss.global/serve.zone/docs/raw/branch/main/dcrouter.png)
`dcrouter` is a TypeScript control plane for running a serious multi-protocol edge or datacenter gateway from one process. It orchestrates HTTP/HTTPS and TCP routing through SmartProxy, email through smartmta, authoritative DNS and DNS-over-HTTPS, RADIUS, remote ingress tunnels, VPN access control, a typed Ops API, and a web dashboard.
`dcrouter` is a TypeScript control plane for running a serious multi-protocol edge or datacenter gateway from one process. It wires together SmartProxy for HTTP/HTTPS/TCP routing, smartmta for email, smartdns for authoritative DNS and DNS-over-HTTPS, smartradius, smartvpn, remote ingress tunnels, a TypedRequest API, and the Ops dashboard.
It is built for operators who want one place to define routes, expose services, manage certificates, register domains and DNS providers, control VPN-only access, and inspect what is going on in production.
Use it when you want one place to define routes, manage domains and certificates, protect internal services, automate changes over an API, and operate the whole stack from a browser.
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.
## Why dcrouter
## Why It Works
- 🌐 Run HTTP/HTTPS, TCP/SNI, email, DNS, RADIUS, VPN, and remote ingress from one orchestrated service.
- 🔐 Keep certificates, routes, tokens, domains, and reusable route references in one management plane.
- 🧠 Use system-managed routes for config-, email-, and DNS-derived traffic, plus API-managed routes for dynamic additions.
- 📊 Get an Ops UI and TypedRequest API for monitoring, automation, and day-2 operations.
- ⚡ Lean on Rust-backed data planes where it matters: proxying, DNS, email delivery, remote ingress, and VPN.
- 🌐 One runtime for HTTP/HTTPS/TCP, SMTP, authoritative DNS + DoH, RADIUS, VPN, and remote ingress.
- 🧠 Constructor config becomes system-managed routes, while API-created routes stay editable and clearly separated.
- 🔐 Certificates, DNS providers, domains, records, API tokens, access profiles, and protected routes live in one management plane.
- 🖥️ The OpsServer UI and TypedRequest API are first-class parts of the package, not an afterthought.
- ⚡ Qualifying HTTPS forward routes on port `443` get HTTP/3 augmentation by default unless you opt out.
## What It Covers
## What You Get
| Area | What dcrouter does |
| --- | --- |
| HTTP / HTTPS / TCP | SmartProxy-based routing, TLS termination or passthrough, path/domain matching, optional HTTP/3 augmentation |
| Email | smartmta-based SMTP ingress and delivery, route-based email handling, DKIM-aware domain support |
| DNS | Authoritative DNS, DNS-over-HTTPS bootstrap routes, provider-backed and dcrouter-hosted domains and records |
| Certificates | ACME-aware certificate management with dashboard and API support |
| Access control | Source profiles, network targets, VPN-gated routes, API tokens, admin auth |
| Network edge | Remote ingress hub for edge nodes tunneling traffic into the router |
| Operations | Web dashboard, TypedRequest API, logs, metrics, health, route and token management |
| HTTP / HTTPS / TCP | SmartProxy-based reverse proxying, TLS termination or passthrough, path/domain/port matching, TCP/SNI forwarding |
| Email | SMTP ingress and delivery via `UnifiedEmailServer`, route-based mail actions, email-domain management, queue and resend operations |
| DNS | Authoritative zones, nameserver bootstrap records, DNS-over-HTTPS routes on `/dns-query` and `/resolve`, provider-backed domain management |
| Access and Edge | VPN-gated routes, RADIUS auth/accounting, remote ingress edge registrations and tunnel hub support |
| Operations | Browser dashboard, TypedRequest API, route management, tokens, certificates, logs, metrics, and health views |
## Installation
@@ -38,7 +36,7 @@ pnpm add @serve.zone/dcrouter
## Quick Start
This is the smallest realistic setup: one HTTP route, embedded database enabled, and the Ops dashboard on port `3000`.
This example stays on unprivileged ports so you can run it locally without root.
```typescript
import { DcRouter } from '@serve.zone/dcrouter';
@@ -47,10 +45,10 @@ const router = new DcRouter({
smartProxyConfig: {
routes: [
{
name: 'app',
name: 'local-app',
match: {
domains: ['app.example.com'],
ports: [80],
domains: ['localhost'],
ports: [18080],
},
action: {
type: 'forward',
@@ -68,114 +66,61 @@ const router = new DcRouter({
await router.start();
```
Once the router is running, you can:
After startup:
- open the Ops dashboard on `http://localhost:3000`
- inspect the route in the System Routes view
- add API-managed routes through the dashboard or API client
- enable DNS, email, VPN, remote ingress, or RADIUS by adding the corresponding config blocks
- open the dashboard at `http://localhost:3000`
- log in with the current built-in credentials `admin` / `admin`
- send proxied traffic to `http://localhost:18080`
- stop gracefully with `await router.stop()`
## Mental Model
## Route Ownership Model
`dcrouter` is not a toy reverse proxy with a few side features. It is an orchestrator that wires multiple specialized services into one management plane.
dcrouter keeps route ownership explicit so automation does not accidentally stomp on system-generated traffic.
| Layer | Responsibility |
| --- | --- |
| `DcRouter` | Startup order, shutdown, service wiring, configuration assembly, route hydration |
| SmartProxy | HTTP/HTTPS, TCP/SNI, TLS, HTTP/3-capable route execution |
| smartmta | SMTP ingress, queueing, DKIM-aware email processing and delivery |
| SmartDNS | Authoritative DNS and DoH request handling |
| smartradius | Network authentication, VLAN assignment, accounting |
| remoteingress | Edge tunnel registrations and runtime forwarding into the hub |
| smartvpn | VPN server and client access mediation for protected routes |
| OpsServer + dashboard | Typed API and browser UI for operations |
| smartdata-backed DB | Persistent routes, tokens, domains, records, profiles, cert metadata, caches |
## Route Model
Routes fall into two ownership classes:
| Route kind | Origin | Ownership | What users can do |
| --- | --- | --- | --- |
| System routes | `config`, `email`, `dns` | Derived from config or runtime-managed subsystems | View and toggle only |
| API routes | `api` | Created through route-management API | Create, edit, delete, toggle |
| Route origin | Where it comes from | What you can do |
| --- | --- | --- |
| `config` | Constructor `smartProxyConfig.routes` and related seed config | View and toggle |
| `email` | Email listener and mail-routing derived routes | View and toggle |
| `dns` | Generated DoH and DNS-related routes | View and toggle |
| `api` | Created through the Ops UI or API client | Full CRUD |
Important details:
- system routes are persisted with a stable `systemKey`
- config-, email-, and DNS-derived routes show up in the System Routes view
- DoH routes are persisted as system-route templates and get their live socket handlers attached at apply time
- system routes are managed by the system, not edited directly by operators
- system routes are persisted with stable `systemKey` values
- DNS-over-HTTPS routes are persisted and then hydrated with live socket handlers at runtime
- editing and deletion are reserved for `api` routes; system routes are toggle-only by design
## Core Features
## Configuration Cheat Sheet
### Traffic Routing
- Domain-, port-, and path-based SmartProxy routes
- HTTP/HTTPS reverse proxying and generic TCP/SNI forwarding
- Optional HTTP/3 augmentation for qualifying HTTPS routes
- Reusable source profiles and network targets for route composition
- Remote ingress aware routing for edge-delivered traffic
### Email
- smartmta-based inbound email handling
- Route-based mail actions such as forward, process, deliver, reject
- DKIM-aware domain handling and DNS record generation support
- Email-domain management through the Ops API and UI
- Queue, resend, failure, and delivery inspection through the dashboard and API
### DNS
- Authoritative scopes via `dnsScopes`
- Bootstrap nameserver domains via `dnsNsDomains`
- DNS-over-HTTPS endpoints for `/dns-query` and `/resolve`
- Managed domains, managed records, and provider-backed DNS integrations
- Internal email DNS record generation for `internal-dns` email domains
### Certificates and ACME
- Certificate overview and operations through OpsServer
- Import, export, delete, and reprovision flows
- DB-backed ACME configuration management
- Integration with managed DNS for certificate provisioning flows
- Routes can declare `certificate: 'auto'`, but actual automated issuance depends on ACME being configured in the management plane
### VPN, RADIUS, and Remote Ingress
- VPN-gated routes with target-profile-based access matching
- WireGuard-oriented VPN management with dcrouter-side client lifecycle support
- RADIUS MAB, VLAN assignment, and accounting
- Remote ingress hub for edge nodes tunneling traffic into central routes
### Operations Plane
- Web dashboard with overview, network, routes, access, security, domains, certificates, logs, and email views
- TypedRequest API for automation and external control
- API tokens with scoped access
- Metrics, health, logs, and per-feature operational views
## Configuration Overview
The main entry point is `IDcRouterOptions`.
The main entrypoint is `IDcRouterOptions`.
| Option | Purpose |
| --- | --- |
| `smartProxyConfig` | Main HTTP/HTTPS and TCP/SNI routing configuration |
| `emailConfig` | smartmta server config and email routes |
| `emailPortConfig` | External-to-internal email port mapping and email storage path tuning |
| `dnsNsDomains` | Nameserver hostnames used for NS bootstrap and DoH routes |
| `dnsScopes` | Authoritative DNS zones managed by dcrouter |
| `dnsRecords` | Static constructor-defined records |
| `publicIp` / `proxyIps` | DNS A-record exposure strategy |
| `dbConfig` | Embedded or external Mongo-backed persistence and seeding |
| `radiusConfig` | RADIUS authentication, VLAN, and accounting setup |
| `remoteIngressConfig` | Edge tunnel hub setup |
| `vpnConfig` | VPN server and client access configuration |
| `http3` | Global HTTP/3 behavior for qualifying routes |
| `opsServerPort` | Dashboard and TypedRequest API port |
| `smartProxyConfig` | Main HTTP/HTTPS and TCP/SNI routing config |
| `emailConfig` | Email hostname, ports, domains, and mail routing rules |
| `emailPortConfig` | External-to-internal email port remapping and received-email storage path |
| `tls` | ACME contact and static certificate paths |
| `dnsNsDomains` | Nameserver hostnames used for NS bootstrap and DoH route generation |
| `dnsScopes` | Domains served authoritatively by the embedded DNS server |
| `dnsRecords` | Static constructor-defined DNS records |
| `publicIp` / `proxyIps` | How A records are exposed for nameserver and service records |
| `dbConfig` | Embedded LocalSmartDb or external MongoDB-backed persistence |
| `radiusConfig` | RADIUS auth, VLAN assignment, and accounting |
| `remoteIngressConfig` | Remote ingress hub and edge tunnel setup |
| `vpnConfig` | VPN server and client definitions for protected route access |
| `http3` | Global HTTP/3 behavior for qualifying HTTPS routes |
| `opsServerPort` | Ops dashboard and TypedRequest API port |
## Example: Enabling DNS, Email, and VPN
## Important Behavior
- `dbConfig.enabled` defaults to `true`. If you do not provide `mongoDbUrl`, dcrouter starts an embedded local database automatically.
- If you disable the DB, constructor-driven traffic can still run, but DB-backed features such as persistent routes, tokens, ACME config, and managed domains do not start.
- Qualifying HTTPS forward routes on port `443` get HTTP/3 by default unless `http3.enabled === false` or the route opts out.
- DNS-over-HTTPS endpoints are generated on the first entry of `dnsNsDomains` at `/dns-query` and `/resolve`.
- Email listener ports are internally remapped by default, so common external ports such as `25`, `587`, and `465` end up on internal ports like `10025`, `10587`, and `10465`.
- Provider-backed domains can be managed in the Ops plane without being served by the embedded authoritative DNS server.
## Bigger Example
```typescript
import { DcRouter } from '@serve.zone/dcrouter';
@@ -195,6 +140,19 @@ const router = new DcRouter({
tls: { mode: 'terminate', certificate: 'auto' },
},
},
{
name: 'internal-admin',
match: {
domains: ['internal.example.com'],
ports: [443],
},
action: {
type: 'forward',
targets: [{ host: '127.0.0.1', port: 9090 }],
tls: { mode: 'terminate', certificate: 'auto' },
},
vpnOnly: true,
},
],
},
emailConfig: {
@@ -233,93 +191,103 @@ const router = new DcRouter({
dbConfig: {
enabled: true,
},
opsServerPort: 3000,
});
await router.start();
```
## Operations API and Dashboard
## Automation
With the database enabled, dcrouter exposes a management plane for:
dcrouter gives you three good integration layers:
- routes and route toggles
- API tokens
- source profiles and network targets
- DNS providers, domains, and records
- ACME configuration and certificate lifecycle
- email domains and email operations
- VPN clients, remote ingress edges, and RADIUS data
- the browser dashboard served by `OpsServer`
- raw TypedRequest contracts via `@serve.zone/dcrouter/interfaces`
- a higher-level OO API client via `@serve.zone/dcrouter/apiclient` or `@serve.zone/dcrouter-apiclient`
The browser dashboard is built from the `ts_web` package and is served by OpsServer. The same backend is accessible programmatically via TypedRequest or the dedicated API client package.
## Programmatic API Client
Use the API client when you want automation or integration code instead of clicking through the dashboard.
### OO API Client Example
```bash
pnpm add @serve.zone/dcrouter-apiclient
```
```typescript
import { DcRouterApiClient } from '@serve.zone/dcrouter/apiclient';
import { DcRouterApiClient } from '@serve.zone/dcrouter-apiclient';
const client = new DcRouterApiClient({
baseUrl: 'https://dcrouter.example.com',
});
await client.login('admin', 'password');
await client.login('admin', 'admin');
const { routes } = await client.routes.list();
const systemRoutes = routes.filter((route) => route.origin !== 'api');
if (systemRoutes[0]) {
await systemRoutes[0].toggle(false);
}
await client.routes.build()
.setName('api-gateway')
.setMatch({ ports: 443, domains: ['api.example.com'] })
.setAction({ type: 'forward', targets: [{ host: '127.0.0.1', port: 8081 }] })
.save();
if (routes[0] && routes[0].origin !== 'api') {
await routes[0].toggle(false);
}
```
See `./ts_apiclient/readme.md` for the dedicated API-client package docs.
See `./ts_apiclient/readme.md` for the dedicated client package and `./ts_interfaces/readme.md` for the raw contracts.
## OCI / Container Bootstrap
The package also includes an environment-driven bootstrap used by `runCli()` when `DCROUTER_MODE=OCI_CONTAINER`.
```typescript
import { runCli } from '@serve.zone/dcrouter';
await runCli();
```
Useful environment variables include:
- `DCROUTER_CONFIG_PATH`
- `DCROUTER_BASE_DIR`
- `DCROUTER_TLS_EMAIL`
- `DCROUTER_TLS_DOMAIN`
- `DCROUTER_PUBLIC_IP`
- `DCROUTER_PROXY_IPS`
- `DCROUTER_DNS_NS_DOMAINS`
- `DCROUTER_DNS_SCOPES`
- `DCROUTER_EMAIL_HOSTNAME`
- `DCROUTER_EMAIL_PORTS`
## Published Modules
This repository publishes multiple modules from the same codebase.
This repository ships several module boundaries from one codebase.
| Module | Purpose | Docs |
| --- | --- | --- |
| `@serve.zone/dcrouter` | Main orchestrator and server package | `./readme.md` |
| `@serve.zone/dcrouter-interfaces` | Shared TypedRequest request and data interfaces | `./ts_interfaces/readme.md` |
| `@serve.zone/dcrouter-migrations` | Startup migration runner for dcrouter data | `./ts_migrations/readme.md` |
| `@serve.zone/dcrouter-web` | Web dashboard entry and UI components | `./ts_web/readme.md` |
| `@serve.zone/dcrouter-apiclient` | Typed OO API client | `./ts_apiclient/readme.md` |
| `@serve.zone/dcrouter` | Main runtime and orchestrator | `./readme.md` |
| `@serve.zone/dcrouter/interfaces` | Shared request and data contracts as a subpath export | `./ts_interfaces/readme.md` |
| `@serve.zone/dcrouter/apiclient` | OO API client as a subpath export | `./ts_apiclient/readme.md` |
| `@serve.zone/dcrouter-interfaces` | Standalone interfaces package | `./ts_interfaces/readme.md` |
| `@serve.zone/dcrouter-apiclient` | Standalone OO API client package | `./ts_apiclient/readme.md` |
| `@serve.zone/dcrouter-migrations` | Standalone migration runner package | `./ts_migrations/readme.md` |
| `@serve.zone/dcrouter-web` | Standalone web dashboard package boundary | `./ts_web/readme.md` |
## Development and Testing
## Development
```bash
pnpm run build
pnpm test
```
Target a single test file while working on one area:
Target a single test while working on one area:
```bash
tstest test/test.dns-runtime-routes.node.ts --verbose
tstest test/test.apiclient.ts --verbose
```
## Notes for Operators
- Database-backed management features depend on `dbConfig.enabled !== false`.
- If you disable the DB, constructor-configured services still run, but persistent management features are limited.
- Nameserver domains are still required for DNS bootstrap and DoH route generation.
- HTTP/3 is enabled by default for qualifying HTTPS routes unless disabled globally or per route.
## 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.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./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.