feat(readme): document HTTP/3 QUIC support and configuration options

2026-03-19 19:10:33 +00:00
parent 6d447f0086
commit cd3f08d55f
5 changed files with 139 additions and 4 deletions
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,12 @@
 # Changelog

+## 2026-03-19 - 11.7.0 - feat(readme)
+document HTTP/3 QUIC support and configuration options
+
+- Add a dedicated README section explaining default HTTP/3 route augmentation, qualification rules, and opt-out behavior.
+- Document the new global `http3` configuration shape and re-exported `IHttp3Config` type.
+- Update TypeScript module documentation to include the built-in HTTP/3 augmentation module and exports.
+
 ## 2026-03-19 - 11.6.0 - feat(http3)
 add automatic HTTP/3 route augmentation for qualifying HTTPS routes

--- a/readme.md
+++ b/readme.md
@@ -18,6 +18,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - [Architecture](#architecture)
 - [Configuration Reference](#configuration-reference)
 - [HTTP/HTTPS & TCP/SNI Routing](#httphttps--tcpsni-routing)
+- [HTTP/3 (QUIC) Support](#http3-quic-support)
 - [Email System](#email-system)
 - [DNS Server](#dns-server)
 - [RADIUS Server](#radius-server)
@@ -37,6 +38,7 @@ 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
+- **HTTP/3 (QUIC) enabled by default** — qualifying HTTPS routes automatically get QUIC/H3 support with zero configuration
 - **TCP/SNI proxy** for any protocol with TLS termination or passthrough
 - **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)
@@ -425,6 +427,27 @@ interface IDcRouterOptions {
    };
  };

+  // ── HTTP/3 (QUIC) ────────────────────────────────────────────
+  /** HTTP/3 config — enabled by default on qualifying HTTPS routes */
+  http3?: {
+    enabled?: boolean;                   // default: true
+    quicSettings?: {
+      maxIdleTimeout?: number;           // default: 30000ms
+      maxConcurrentBidiStreams?: number;  // default: 100
+      maxConcurrentUniStreams?: number;   // default: 100
+      initialCongestionWindow?: number;
+    };
+    altSvc?: {
+      port?: number;                     // default: listening port
+      maxAge?: number;                   // default: 86400s
+    };
+    udpSettings?: {
+      sessionTimeout?: number;           // default: 60000ms
+      maxSessionsPerIP?: number;         // default: 1000
+      maxDatagramSize?: number;          // default: 65535
+    };
+  };
+
  // ── OpsServer ────────────────────────────────────────────────
  /** Port for the OpsServer web dashboard (default: 3000) */
  opsServerPort?: number;
@@ -516,6 +539,102 @@ DcRouter uses [SmartProxy](https://code.foss.global/push.rocks/smartproxy) for a
 }
 ```

+## HTTP/3 (QUIC) Support
+
+DcRouter ships with **HTTP/3 enabled by default** 🚀. All qualifying HTTPS routes on port 443 are automatically augmented with QUIC/H3 configuration — no extra setup needed. Under the hood, SmartProxy's native HTTP/3 support (via `IRouteQuic`) handles QUIC transport, Alt-Svc advertisement, and HTTP/3 negotiation.
+
+### How It Works
+
+When DcRouter assembles routes in `setupSmartProxy()`, it automatically augments qualifying routes with:
+- `match.transport: 'all'` — listen on both TCP (HTTP/1.1 + HTTP/2) and UDP (QUIC/HTTP/3) on the same port
+- `action.udp.quic` — QUIC configuration with `enableHttp3: true` and `altSvcMaxAge: 86400`
+
+Browsers that support HTTP/3 will discover it via the `Alt-Svc` header on initial TCP responses, then upgrade to QUIC for subsequent requests.
+
+### What Gets Augmented
+
+A route qualifies for HTTP/3 augmentation when **all** of these are true:
+- Port includes **443** (single number, array, or range)
+- Action type is **`forward`** (not `socket-handler`)
+- **TLS is enabled** (passthrough, terminate, or terminate-and-reencrypt)
+- Route is **not** an email route (ports 25/587/465)
+- Route doesn't already have `transport: 'all'` or existing `udp.quic` config
+
+### Zero-Config (Default Behavior)
+
+```typescript
+// HTTP/3 is ON by default — this route automatically gets QUIC/H3:
+const router = new DcRouter({
+  smartProxyConfig: {
+    routes: [{
+      name: 'web-app',
+      match: { domains: ['example.com'], ports: [443] },
+      action: {
+        type: 'forward',
+        targets: [{ host: '192.168.1.10', port: 8080 }],
+        tls: { mode: 'terminate', certificate: 'auto' }
+      }
+    }]
+  }
+});
+```
+
+### Per-Route Opt-Out
+
+Disable HTTP/3 on a specific route using `action.options.http3`:
+
+```typescript
+{
+  name: 'legacy-app',
+  match: { domains: ['legacy.example.com'], ports: [443] },
+  action: {
+    type: 'forward',
+    targets: [{ host: '192.168.1.50', port: 8080 }],
+    tls: { mode: 'terminate', certificate: 'auto' },
+    options: { http3: false }  // ← This route stays TCP-only
+  }
+}
+```
+
+### Global Opt-Out
+
+Disable HTTP/3 across all routes:
+
+```typescript
+const router = new DcRouter({
+  http3: { enabled: false },
+  smartProxyConfig: { routes: [/* ... */] }
+});
+```
+
+### Custom QUIC Settings
+
+Fine-tune QUIC parameters globally:
+
+```typescript
+const router = new DcRouter({
+  http3: {
+    quicSettings: {
+      maxIdleTimeout: 60000,          // 60s idle timeout
+      maxConcurrentBidiStreams: 200,   // More parallel streams
+      maxConcurrentUniStreams: 50,
+    },
+    altSvc: {
+      maxAge: 3600,                   // 1 hour Alt-Svc cache
+    },
+    udpSettings: {
+      sessionTimeout: 120000,         // 2 min UDP session timeout
+      maxSessionsPerIP: 500,
+    }
+  },
+  smartProxyConfig: { routes: [/* ... */] }
+});
+```
+
+### Programmatic Routes
+
+Routes added at runtime via the Route Management API also get HTTP/3 augmentation automatically — the `RouteConfigManager` applies the same augmentation logic when merging programmatic routes.
+
 ## Email System

 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.
@@ -1221,7 +1340,7 @@ const router = new DcRouter(options: IDcRouterOptions);

 ### Re-exported Types

-DcRouter re-exports key types from smartmta for convenience:
+DcRouter re-exports key types for convenience:

 ```typescript
 import {
@@ -1231,6 +1350,7 @@ import {
  type IUnifiedEmailServerOptions,
  type IEmailRoute,
  type IEmailDomainConfig,
+  type IHttp3Config,
 } from '@serve.zone/dcrouter';
 ```

@@ -1277,9 +1397,10 @@ tstest test/test.opsserver-api.ts --verbose --timeout 60
 | `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.http3-augmentation.ts` | HTTP/3 route augmentation, qualification, opt-in/out, QUIC settings | 20 |
 | `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.opsserver-api.ts` | Health, statistics, configuration, log APIs | 8 |
 | `test.protected-endpoint.ts` | Admin auth, identity verification, public endpoints | 8 |
 | `test.storagemanager.ts` | Memory, filesystem, custom backends, concurrency | 8 |

--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/dcrouter',
-  version: '11.6.0',
+  version: '11.7.0',
  description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }
--- a/ts/readme.md
+++ b/ts/readme.md
@@ -60,6 +60,9 @@ ts/
 │   └── documents/                  # Cached document models
 ├── config/                         # Configuration utilities
 ├── errors/                         # Error classes and retry logic
+├── http3/                          # HTTP/3 (QUIC) route augmentation
+│   ├── index.ts                    # Barrel export
+│   └── http3-route-augmentation.ts # Pure utility: augmentRoutesWithHttp3(), IHttp3Config
 ├── monitoring/                     # MetricsManager (SmartMetrics integration)
 ├── opsserver/                      # OpsServer dashboard + API handlers
 │   ├── classes.opsserver.ts        # HTTP server + TypedRouter setup
@@ -99,6 +102,9 @@ export { RadiusServer, IRadiusServerConfig } from './radius/index.js';

 // Remote Ingress
 export { RemoteIngressManager, TunnelManager } from './remoteingress/index.js';
+
+// HTTP/3
+export type { IHttp3Config } from './http3/index.js';
 ```

 ## Key Classes
@@ -115,6 +121,7 @@ The central orchestrator. Accepts `IDcRouterOptions` and manages the lifecycle o
 | `radiusConfig` | RadiusServer (auth + accounting) | `@push.rocks/smartradius` |
 | `remoteIngressConfig` | RemoteIngressManager + TunnelManager | `@serve.zone/remoteingress` |
 | `tls` + `dnsChallenge` | SmartAcme (ACME cert provisioning) | `@push.rocks/smartacme` |
+| `http3` | HTTP/3 route augmentation (enabled by default) | built-in |
 | `cacheConfig` | CacheDb (embedded MongoDB) | `@push.rocks/smartdata` |
 | *(always)* | OpsServer (dashboard + API) | `@api.global/typedserver` |
 | *(always)* | MetricsManager | `@push.rocks/smartmetrics` |
--- a/ts_web/00_commitinfo_data.ts
+++ b/ts_web/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/dcrouter',
-  version: '11.6.0',
+  version: '11.7.0',
  description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }