v26.0.0

changelog.md

@@ -1,5 +1,258 @@
 # Changelog
 
+## 2026-03-21 - 26.0.0 - BREAKING CHANGE(ts-api,rustproxy)
+remove deprecated TypeScript protocol and utility exports while hardening QUIC, HTTP/3, WebSocket, and rate limiter cleanup paths
+
+- Removes large parts of the public TypeScript surface including detection, TLS, router, websocket, proxy/common protocol, and multiple core utility exports and files.
+- Adds parent-child cancellation handling for HTTP/3 and QUIC stream forwarding to stop orphaned tasks and close idle or overlong streams.
+- Improves cleanup reliability with RAII guards for WebSocket upstream tracking and QUIC connection metrics, plus periodic cleanup for rate limiter and proxy address maps.
+- Cleans backend metrics state when active backend connections drop to zero and tracks passthrough backend sockets for shutdown cleanup.
+
+## 2026-03-20 - 25.17.10 - fix(rustproxy-http)
+reuse the shared HTTP proxy service for HTTP/3 request handling
+
+- Refactors H3ProxyService to delegate requests to the shared HttpProxyService instead of maintaining separate routing and backend forwarding logic.
+- Aligns HTTP/3 with the TCP/HTTP path for route matching, connection pooling, and ALPN-based upstream protocol detection.
+- Generalizes request handling and filters to accept boxed/generic HTTP bodies so both HTTP/3 and existing HTTP paths share the same proxy pipeline.
+- Updates the HTTP/3 integration route matcher to allow transport matching across shared HTTP and QUIC handling.
+
+## 2026-03-20 - 25.17.9 - fix(rustproxy-http)
+correct HTTP/3 host extraction and avoid protocol filtering during UDP route lookup
+
+- Use the URI host or strip the port from the Host header so HTTP/3 requests match routes consistently with TCP/HTTP handling.
+- Remove protocol filtering from HTTP/3 route lookup because QUIC transport already constrains routing to UDP and protocol validation happens earlier.
+
+## 2026-03-20 - 25.17.8 - fix(rustproxy)
+use SNI-based certificate resolution for QUIC TLS connections
+
+- Replaces static first-certificate selection with the shared CertResolver used by the TCP/TLS path.
+- Ensures QUIC connections can present the correct certificate per requested domain.
+- Keeps HTTP/3 ALPN configuration while improving multi-domain TLS handling.
+
+## 2026-03-20 - 25.17.7 - fix(readme)
+document QUIC and HTTP/3 compatibility caveats
+
+- Add notes explaining that GREASE frames are disabled on both server and client HTTP/3 paths to avoid interoperability issues
+- Document that the current HTTP/3 stack depends on pre-1.0 h3 ecosystem components and may still have rough edges
+
+## 2026-03-20 - 25.17.6 - fix(rustproxy-http)
+disable HTTP/3 GREASE for client and server connections
+
+- Switch the HTTP/3 server connection setup to use the builder API with send_grease(false)
+- Switch the HTTP/3 client handshake to use the builder API with send_grease(false) to improve compatibility
+
+## 2026-03-20 - 25.17.5 - fix(rustproxy)
+add HTTP/3 integration test for QUIC response stream FIN handling
+
+- adds an integration test covering HTTP/3 proxying over QUIC with TLS termination
+- verifies response bodies fully arrive and the client receives stream termination instead of hanging
+- adds test-only dependencies for quinn, h3, h3-quinn, rustls, bytes, and http
+
+## 2026-03-20 - 25.17.4 - fix(rustproxy-http)
+prevent HTTP/3 response body streaming from hanging on backend completion
+
+- extract and track Content-Length before consuming the response body
+- stop the HTTP/3 body loop when the stream reports end-of-stream or the expected byte count has been sent
+- add a per-frame idle timeout to avoid indefinite waits on stalled or close-delimited backend bodies
+
+## 2026-03-20 - 25.17.3 - fix(repository)
+no changes detected
+
+
+## 2026-03-20 - 25.17.2 - fix(rustproxy-http)
+enable TLS connections for HTTP/3 upstream requests when backend re-encryption or TLS is configured
+
+- Pass backend TLS client configuration into the HTTP/3 request handler.
+- Detect TLS-required upstream targets using route and target TLS settings before connecting.
+- Build backend request URIs with the correct http or https scheme to match the upstream connection.
+
+## 2026-03-20 - 25.17.1 - fix(rustproxy-routing)
+allow QUIC UDP TLS connections without SNI to match domain-restricted routes
+
+- Exempts UDP transport from the no-SNI rejection logic because QUIC encrypts the TLS ClientHello and SNI is unavailable at accept time
+- Adds regression tests to confirm QUIC route matching succeeds without SNI while TCP TLS without SNI remains rejected
+
+## 2026-03-19 - 25.17.0 - feat(rustproxy-passthrough)
+add PROXY protocol v2 client IP handling for UDP and QUIC listeners
+
+- propagate trusted proxy IP configuration into UDP and QUIC listener managers
+- extract and preserve real client addresses from PROXY protocol v2 headers for HTTP/3 and QUIC stream handling
+- apply rate limiting, session limits, routing, and metrics using the resolved client IP while preserving correct proxy return-path routing
+
+## 2026-03-19 - 25.16.3 - fix(rustproxy)
+upgrade fallback UDP listeners to QUIC when TLS certificates become available
+
+- Rebuild and apply QUIC TLS configuration during route and certificate updates instead of only when adding new UDP ports.
+- Add logic to drain UDP sessions, stop raw fallback listeners, and start QUIC endpoints on existing ports once TLS is available.
+- Retry QUIC endpoint creation during upgrade and fall back to rebinding raw UDP if the upgrade cannot complete.
+
+## 2026-03-19 - 25.16.2 - fix(rustproxy-http)
+cache backend Alt-Svc only from original upstream responses during protocol auto-detection
+
+- Moves Alt-Svc discovery into streaming response construction so it reads backend headers before response filters inject client-facing Alt-Svc values
+- Stores the protocol cache key in connection activity during auto-detect mode and clears it after HTTP/3 connection failure to avoid re-caching failed H3 routes
+- Prevents fallback requests from reintroducing stale or self-injected Alt-Svc entries that could cause repeated H3 retry loops
+
+## 2026-03-19 - 25.16.1 - fix(http-proxy)
+avoid repeated HTTP/3 recaching after QUIC fallback and document backend protocol selection
+
+- Suppress Alt-Svc HTTP/3 recaching after a failed QUIC backend connection to prevent repeated H3 timeout fallback loops
+- Force an ALPN probe on TCP fallback so auto detection correctly reselects HTTP/2 or HTTP/1.1 after H3 connection failure
+- Add README documentation for best-effort backendProtocol selection and supported protocol modes
+
+## 2026-03-19 - 25.16.0 - feat(quic,http3)
+add HTTP/3 proxy handling and hot-reload QUIC TLS configuration
+
+- initialize and wire H3ProxyService into QUIC listeners so HTTP/3 requests are handled instead of being kept as placeholder connections
+- add backend HTTP/3 support with protocol caching that stores Alt-Svc advertised H3 ports for auto-detection
+- hot-swap TLS certificates across active QUIC endpoints and require terminating TLS for QUIC route validation
+- document QUIC route setup with required TLS and ACME configuration
+
+## 2026-03-19 - 25.15.0 - feat(readme)
+document UDP, QUIC, and HTTP/3 support in the README
+
+- Adds README examples for UDP datagram handlers, QUIC/HTTP3 forwarding, and dual-stack TCP/UDP routes
+- Expands configuration and API reference sections to cover transport matching, UDP/QUIC options, backend transport selection, and UDP metrics
+- Updates architecture and feature descriptions to reflect UDP, QUIC, HTTP/3, and datagram handler capabilities
+
+## 2026-03-19 - 25.14.1 - fix(deps)
+update build and runtime dependencies and align route validation test expectations
+
+- split the test preparation step into a dedicated test:before script while keeping test execution separate
+- bump development tooling and runtime package versions in package.json
+- adjust the route validation test to match the current generic handler error message
+
+## 2026-03-19 - 25.14.0 - feat(udp,http3)
+add UDP datagram handler relay support and stream HTTP/3 request bodies to backends
+
+- establish a persistent Unix socket relay for UDP datagram handlers and process handler replies back to clients
+- update route validation and smart proxy route reload logic to support datagramHandler routes
+- record UDP, QUIC, and HTTP/3 byte metrics more accurately, including request bytes in and UDP session cleanup connection tracking
+- add integration tests for UDP forwarding, datagram handlers, and UDP metrics
+
+## 2026-03-19 - 25.13.0 - feat(smart-proxy)
+add UDP transport support with QUIC/HTTP3 routing and datagram handler relay
+
+- adds UDP listener and session tracking infrastructure in the Rust proxy, including UDP metrics and hot-reload support for transport-specific ports
+- introduces QUIC and HTTP/3 support in routing and HTTP handling, including Alt-Svc advertisement and QUIC TLS configuration
+- extends route configuration types in Rust and TypeScript with transport, UDP, QUIC, backend transport, and mixed port range support
+- adds a TypeScript datagram handler relay server and bridge command so UDP socket-handler routes can dispatch datagrams to application callbacks
+- updates nftables rule generation so protocol=all creates both TCP and UDP rules
+
+## 2026-03-19 - 25.12.0 - feat(proxy-protocol)
+add PROXY protocol v2 support to the Rust passthrough listener and streamline TypeScript proxy protocol exports
+
+- detect and parse PROXY protocol v2 headers in the Rust TCP listener, including TCP and UDP address families
+- add Rust v2 header generation, incomplete-header handling, and broader parser test coverage
+- remove deprecated TypeScript proxy protocol parser exports and tests, leaving shared type definitions only
+
+## 2026-03-17 - 25.11.24 - fix(rustproxy-http)
+improve async static file serving, websocket handshake buffering, and shared metric metadata handling
+
+- convert static file serving to async filesystem operations and await directory/file checks
+- preserve and forward bytes read past the WebSocket handshake header terminator to avoid dropping buffered upstream data
+- reuse Arc<str> values for route and source identifiers across counting bodies and metric reporting
+- standardize backend key propagation across H1/H2 forwarding, retry, and fallback paths for consistent logging and metrics
+
+## 2026-03-17 - 25.11.23 - fix(rustproxy-http,rustproxy-metrics)
+reduce per-frame metrics overhead by batching body byte accounting
+
+- Buffer HTTP body byte counts and flush them every 64 KB, at end of stream, and on drop to keep totals accurate while preserving throughput sampling.
+- Skip zero-value counter updates in metrics collection to avoid unnecessary atomic and DashMap operations for the unused direction.
+
+## 2026-03-17 - 25.11.22 - fix(rustproxy-http)
+reuse healthy HTTP/2 upstream connections after requests with bodies
+
+- Registers successful HTTP/2 connections in the pool regardless of whether the proxied request included a body
+- Continues to avoid pooling upstream connections that returned 502 Bad Gateway responses
+
+## 2026-03-17 - 25.11.21 - fix(rustproxy-http)
+reuse pooled HTTP/2 connections for requests with and without bodies
+
+- remove the bodyless-request restriction from HTTP/2 pool checkout
+- always return successful HTTP/2 senders to the connection pool after requests
+
+## 2026-03-17 - 25.11.20 - fix(rustproxy-http)
+avoid downgrading cached backend protocol on H2 stream errors
+
+- Treat HTTP/2 stream-level failures as retryable request errors instead of evidence that the backend only supports HTTP/1.1
+- Keep protocol cache entries unchanged after successful H2 handshakes so future requests continue using HTTP/2
+- Lower log severity for this fallback path from warning to debug while still recording backend H2 failure metrics
+
+## 2026-03-16 - 25.11.19 - fix(rustproxy-http)
+avoid reusing pooled HTTP/2 connections for requests with bodies to prevent upload flow-control stalls
+
+- Limit HTTP/2 pool checkout to bodyless requests such as GET, HEAD, and DELETE
+- Skip re-registering HTTP/2 connections in the pool after requests that send a body
+- Prevent stalled uploads caused by depleted connection-level flow control windows on reused HTTP/2 connections
+
+## 2026-03-16 - 25.11.18 - fix(repo)
+no changes to commit
+
+
+## 2026-03-16 - 25.11.17 - fix(rustproxy-http)
+prevent stale HTTP/2 connection drivers from evicting newer pooled connections
+
+- add generation IDs to pooled HTTP/2 senders so pool removal only affects the matching connection
+- update HTTP/2 proxy and retry paths to register generation-tagged connections and skip eviction before registration completes
+
+## 2026-03-16 - 25.11.16 - fix(repo)
+no changes to commit
+
+
+## 2026-03-16 - 25.11.15 - fix(rustproxy-http)
+implement vectored write support for backend streams
+
+- Add poll_write_vectored forwarding for both plain and TLS backend stream variants
+- Expose is_write_vectored so the proxy can correctly report vectored write capability
+
+## 2026-03-16 - 25.11.14 - fix(rustproxy-http)
+forward vectored write support in ShutdownOnDrop AsyncWrite wrapper
+
+- Implements poll_write_vectored by delegating to the wrapped writer
+- Exposes is_write_vectored so the wrapper preserves underlying AsyncWrite capabilities
+
+## 2026-03-16 - 25.11.13 - fix(rustproxy-http)
+remove hot-path debug logging from HTTP/1 connection pool hits
+
+- Stops emitting debug logs when reusing HTTP/1 idle connections in the connection pool.
+- Keeps pool hit behavior unchanged while reducing overhead on a frequently executed path.
+
+## 2026-03-16 - 25.11.12 - fix(rustproxy-http)
+remove connection pool hit logging and keep logging limited to actual failures
+
+- Removes debug and warning logs for HTTP/2 connection pool hits and age checks.
+- Keeps pool behavior unchanged while reducing noisy per-request logging in the Rust HTTP proxy layer.
+
+## 2026-03-16 - 25.11.11 - fix(rustproxy-http)
+improve HTTP/2 proxy error logging with warning-level connection failures and debug error details
+
+- Adds debug-formatted error fields to HTTP/2 handshake, retry, fallback, and request failure logs
+- Promotes upstream HTTP/2 connection error logs from debug to warn to improve operational visibility
+
+## 2026-03-16 - 25.11.10 - fix(rustproxy-http)
+validate pooled HTTP/2 connections asynchronously before reuse and evict stale senders
+
+- Add an async ready() check with a 500ms timeout before reusing pooled HTTP/2 senders to catch GOAWAY/RST states before forwarding requests
+- Return connection age from the HTTP/2 pool checkout path and log warnings for older pooled connections
+- Evict pooled HTTP/2 senders when they are closed, exceed max age, fail readiness validation, or time out during readiness checks
+
+## 2026-03-16 - 25.11.9 - fix(rustproxy-routing)
+reduce hot-path allocations in routing, metrics, and proxy protocol handling
+
+- skip HTTP header map construction unless a route on the current port uses header matching
+- reuse computed client IP strings during HTTP route matching to avoid redundant allocations
+- optimize per-route and per-IP metric updates with get-first lookups to avoid unnecessary String creation on existing entries
+- replace heap-allocated PROXY protocol peek and discard buffers with stack-allocated buffers in the TCP listener
+- improve domain matcher case-insensitive wildcard checks while preserving glob fallback behavior
+
+## 2026-03-16 - 25.11.8 - fix(rustproxy-http)
+prevent premature idle timeouts during streamed HTTP responses and ensure TLS close_notify is sent on dropped connections
+
+- track active streaming response bodies so the HTTP idle watchdog does not close connections mid-transfer
+- add a ShutdownOnDrop wrapper for TLS-terminated HTTP connections to send shutdown on drop and avoid improperly terminated TLS sessions
+- apply the shutdown wrapper in passthrough TLS terminate and terminate+reencrypt HTTP handling
+
 ## 2026-03-16 - 25.11.7 - fix(rustproxy)
 prevent TLS route reload certificate mismatches and tighten passthrough connection handling
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "25.11.7",
+  "version": "26.0.0",
   "private": false,
   "description": "A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.",
   "main": "dist_ts/index.js",
@@ -9,27 +9,28 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tsrust) && (tstest test/**/test*.ts --verbose --timeout 60 --logfile)",
+    "test:before": "(tsrust)",
+    "test": "(tstest test/**/test*.ts --verbose --timeout 60 --logfile)",
     "build": "(tsbuild tsfolders --allowimplicitany) && (tsrust)",
     "format": "(gitzone format)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsbuild": "^4.3.0",
     "@git.zone/tsrun": "^2.0.1",
     "@git.zone/tsrust": "^1.3.0",
-    "@git.zone/tstest": "^3.1.8",
+    "@git.zone/tstest": "^3.5.0",
     "@push.rocks/smartserve": "^2.0.1",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.5.0",
     "typescript": "^5.9.3",
     "why-is-node-running": "^3.2.2"
   },
   "dependencies": {
     "@push.rocks/smartcrypto": "^2.0.4",
-    "@push.rocks/smartlog": "^3.1.10",
-    "@push.rocks/smartrust": "^1.2.1",
-    "@tsclass/tsclass": "^9.3.0",
-    "minimatch": "^10.2.0"
+    "@push.rocks/smartlog": "^3.2.1",
+    "@push.rocks/smartrust": "^1.3.2",
+    "@tsclass/tsclass": "^9.5.0",
+    "minimatch": "^10.2.4"
   },
   "files": [
     "ts/**/*",

readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartproxy 🚀
 
-**A high-performance, Rust-powered proxy toolkit for Node.js** — unified route-based configuration for SSL/TLS termination, HTTP/HTTPS reverse proxying, WebSocket support, load balancing, custom protocol handlers, and kernel-level NFTables forwarding.
+**A high-performance, Rust-powered proxy toolkit for Node.js** — unified route-based configuration for SSL/TLS termination, HTTP/HTTPS reverse proxying, WebSocket support, UDP/QUIC/HTTP3, load balancing, custom protocol handlers, and kernel-level NFTables forwarding.
 
 ## 📦 Installation
 
@@ -16,9 +16,9 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ## 🎯 What is SmartProxy?
 
-SmartProxy is a production-ready proxy solution that takes the complexity out of traffic management. Under the hood, all networking — TCP, TLS, HTTP reverse proxy, connection tracking, security enforcement, and NFTables — is handled by a **Rust engine** for maximum performance, while you configure everything through a clean TypeScript API with full type safety.
+SmartProxy is a production-ready proxy solution that takes the complexity out of traffic management. Under the hood, all networking — TCP, UDP, TLS, HTTP reverse proxy, QUIC/HTTP3, connection tracking, security enforcement, and NFTables — is handled by a **Rust engine** for maximum performance, while you configure everything through a clean TypeScript API with full type safety.
 
-Whether you're building microservices, deploying edge infrastructure, or need a battle-tested reverse proxy with automatic Let's Encrypt certificates, SmartProxy has you covered.
+Whether you're building microservices, deploying edge infrastructure, proxying UDP-based protocols, or need a battle-tested reverse proxy with automatic Let's Encrypt certificates, SmartProxy has you covered.
 
 ### ⚡ Key Features
 
@@ -29,11 +29,12 @@ Whether you're building microservices, deploying edge infrastructure, or need a
 | 🔒 **Automatic SSL/TLS** | Zero-config HTTPS with Let's Encrypt ACME integration |
 | 🎯 **Flexible Matching** | Route by port, domain, path, protocol, client IP, TLS version, headers, or custom logic |
 | 🚄 **High-Performance** | Choose between user-space or kernel-level (NFTables) forwarding |
+| 📡 **UDP & QUIC/HTTP3** | First-class UDP transport, datagram handlers, QUIC tunneling, and HTTP/3 support |
 | ⚖️ **Load Balancing** | Round-robin, least-connections, IP-hash with health checks |
 | 🛡️ **Enterprise Security** | IP filtering, rate limiting, basic auth, JWT auth, connection limits |
 | 🔌 **WebSocket Support** | First-class WebSocket proxying with ping/pong keep-alive |
-| 🎮 **Custom Protocols** | Socket handlers for implementing any protocol in TypeScript |
-| 📊 **Live Metrics** | Real-time throughput, connection counts, and performance data |
+| 🎮 **Custom Protocols** | Socket and datagram handlers for implementing any protocol in TypeScript |
+| 📊 **Live Metrics** | Real-time throughput, connection counts, UDP sessions, and performance data |
 | 🔧 **Dynamic Management** | Add/remove ports and routes at runtime without restarts |
 | 🔄 **PROXY Protocol** | Full PROXY protocol v1/v2 support for preserving client information |
 | 💾 **Consumer Cert Storage** | Bring your own persistence — SmartProxy never writes certs to disk |
@@ -89,7 +90,7 @@ SmartProxy uses a powerful **match/action** pattern that makes routing predictab
 ```
 
 Every route consists of:
-- **Match** — What traffic to capture (ports, domains, paths, protocol, IPs, headers)
+- **Match** — What traffic to capture (ports, domains, paths, transport, protocol, IPs, headers)
 - **Action** — What to do with it (`forward` or `socket-handler`)
 - **Security** (optional) — IP allow/block lists, rate limits, authentication
 - **Headers** (optional) — Request/response header manipulation with template variables
@@ -197,7 +198,7 @@ apiRoute = addRateLimiting(apiRoute, {
 const proxy = new SmartProxy({ routes: [apiRoute] });
 ```
 
-### 🎮 Custom Protocol Handler
+### 🎮 Custom Protocol Handler (TCP)
 
 SmartProxy lets you implement any protocol with full socket control. Routes with JavaScript socket handlers are automatically relayed from the Rust engine back to your TypeScript code:
 
@@ -247,6 +248,140 @@ const proxy = new SmartProxy({ routes: [echoRoute, customRoute] });
 | `SocketHandlers.httpBlock(status, message)` | HTTP block response |
 | `SocketHandlers.block(message)` | Block with optional message |
 
+### 📡 UDP Datagram Handler
+
+Handle raw UDP datagrams with custom TypeScript logic — perfect for DNS, game servers, IoT protocols, or any UDP-based service:
+
+```typescript
+import { SmartProxy } from '@push.rocks/smartproxy';
+import type { IRouteConfig, TDatagramHandler, IDatagramInfo } from '@push.rocks/smartproxy';
+
+// Custom UDP echo handler
+const udpHandler: TDatagramHandler = (datagram, info, reply) => {
+  console.log(`UDP from ${info.sourceIp}:${info.sourcePort} on port ${info.destPort}`);
+  reply(datagram); // Echo it back
+};
+
+const proxy = new SmartProxy({
+  routes: [{
+    name: 'udp-echo',
+    match: {
+      ports: 5353,
+      transport: 'udp'        // 👈 Listen for UDP datagrams
+    },
+    action: {
+      type: 'socket-handler',
+      datagramHandler: udpHandler,  // 👈 Process each datagram
+      udp: {
+        sessionTimeout: 60000,     // Session idle timeout (ms)
+        maxSessionsPerIP: 100,
+        maxDatagramSize: 65535
+      }
+    }
+  }]
+});
+
+await proxy.start();
+```
+
+### 📡 QUIC / HTTP3 Forwarding
+
+Forward QUIC traffic to backends with optional protocol translation (e.g., receive QUIC, forward as TCP/HTTP1):
+
+```typescript
+import { SmartProxy } from '@push.rocks/smartproxy';
+import type { IRouteConfig } from '@push.rocks/smartproxy';
+
+const quicRoute: IRouteConfig = {
+  name: 'quic-to-backend',
+  match: {
+    ports: 443,
+    transport: 'udp',
+    protocol: 'quic'           // 👈 Match QUIC protocol
+  },
+  action: {
+    type: 'forward',
+    targets: [{
+      host: 'backend-server',
+      port: 8443,
+      backendTransport: 'tcp'  // 👈 Translate QUIC → TCP for backend
+    }],
+    tls: {
+      mode: 'terminate',
+      certificate: 'auto'     // 👈 QUIC requires TLS 1.3
+    },
+    udp: {
+      quic: {
+        enableHttp3: true,
+        maxIdleTimeout: 30000,
+        maxConcurrentBidiStreams: 100,
+        altSvcPort: 443,       // Advertise in Alt-Svc header
+        altSvcMaxAge: 86400
+      }
+    }
+  }
+};
+
+const proxy = new SmartProxy({
+  acme: { email: 'ssl@example.com' },
+  routes: [quicRoute]
+});
+```
+
+### 🚄 Best-Effort Backend Protocol (H3 > H2 > H1)
+
+SmartProxy automatically uses the **highest protocol your backend supports** for HTTP requests. The backend protocol is independent of the client protocol — a client using HTTP/1.1 can be forwarded over HTTP/3 to the backend, and vice versa.
+
+```typescript
+const route: IRouteConfig = {
+  name: 'auto-protocol',
+  match: { ports: 443, domains: 'app.example.com' },
+  action: {
+    type: 'forward',
+    targets: [{ host: 'backend', port: 8443 }],
+    tls: { mode: 'terminate', certificate: 'auto' },
+    options: {
+      backendProtocol: 'auto'  // 👈 Default — best-effort selection
+    }
+  }
+};
+```
+
+**How protocol discovery works (browser model):**
+
+1. First request → TLS ALPN probe detects H2 or H1
+2. Backend response inspected for `Alt-Svc: h3=":port"` header
+3. If H3 advertised → cached and used for subsequent requests via QUIC
+4. Graceful fallback: H3 failure → H2 → H1 with automatic cache invalidation
+
+| `backendProtocol` | Behavior |
+|---|---|
+| `'auto'` (default) | Best-effort: H3 > H2 > H1 with Alt-Svc discovery |
+| `'http1'` | Always HTTP/1.1 |
+| `'http2'` | Always HTTP/2 (hard-fail if unsupported) |
+| `'http3'` | Always HTTP/3 via QUIC (hard-fail if unsupported) |
+
+> **Note:** WebSocket upgrades always use HTTP/1.1 to the backend regardless of `backendProtocol`, since there's no performance benefit from H2/H3 Extended CONNECT for tunneled connections, and backend support is rare.
+
+### 🔁 Dual-Stack TCP + UDP Route
+
+Listen on both TCP and UDP with a single route — handle each transport with its own handler:
+
+```typescript
+const dualStackRoute: IRouteConfig = {
+  name: 'dual-stack-dns',
+  match: {
+    ports: 53,
+    transport: 'all'  // 👈 Listen on both TCP and UDP
+  },
+  action: {
+    type: 'socket-handler',
+    socketHandler: handleTcpDns,      // 👈 TCP connections
+    datagramHandler: handleUdpDns,    // 👈 UDP datagrams
+  }
+};
+```
+
 ### ⚡ High-Performance NFTables Forwarding
 
 For ultra-low latency on Linux, use kernel-level forwarding (requires root):
@@ -419,6 +554,10 @@ console.log(`Bytes in: ${metrics.totals.bytesIn()}`);
 console.log(`Requests/sec: ${metrics.requests.perSecond()}`);
 console.log(`Throughput in: ${metrics.throughput.instant().in} bytes/sec`);
 
+// UDP metrics
+console.log(`UDP sessions: ${metrics.udp.activeSessions()}`);
+console.log(`Datagrams in: ${metrics.udp.datagramsIn()}`);
+
 // Get detailed statistics from the Rust engine
 const stats = await proxy.getStatistics();
 
@@ -545,7 +684,7 @@ SmartProxy uses a hybrid **Rust + TypeScript** architecture:
 ```
 ┌─────────────────────────────────────────────────────┐
 │                  Your Application                    │
-│     (TypeScript — routes, config, socket handlers)   │
+│     (TypeScript — routes, config, handlers)          │
 └──────────────────┬──────────────────────────────────┘
                    │  IPC (JSON over stdin/stdout)
 ┌──────────────────▼──────────────────────────────────┐
@@ -556,22 +695,23 @@ SmartProxy uses a hybrid **Rust + TypeScript** architecture:
 │  │         │ │  Proxy   │ │         │ │          │  │
 │  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
 │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
-│  │ Security│ │ Metrics  │ │ Connec- │ │ NFTables │  │
-│  │ Enforce │ │ Collect  │ │  tion   │ │  Mgr     │  │
-│  │         │ │          │ │ Tracker │ │          │  │
+│  │   UDP   │ │ Security│ │ Metrics  │ │ NFTables │  │
+│  │  QUIC   │ │ Enforce │ │ Collect  │ │  Mgr     │  │
+│  │  HTTP/3 │ │         │ │          │ │          │  │
 │  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
 └──────────────────┬──────────────────────────────────┘
                    │  Unix Socket Relay
 ┌──────────────────▼──────────────────────────────────┐
-│       TypeScript Socket Handler Server               │
-│  (for JS-defined socket handlers & dynamic routes)   │
+│   TypeScript Socket & Datagram Handler Servers       │
+│  (for JS socket handlers, datagram handlers,         │
+│   and dynamic routes)                                │
 └─────────────────────────────────────────────────────┘
 ```
 
-- **Rust Engine** handles all networking, TLS, HTTP proxying, connection management, security, and metrics
-- **TypeScript** provides the npm API, configuration types, route helpers, validation, and socket handler callbacks
+- **Rust Engine** handles all networking: TCP, UDP, TLS, QUIC, HTTP proxying, connection management, security, and metrics
+- **TypeScript** provides the npm API, configuration types, route helpers, validation, and handler callbacks
 - **IPC** — The TypeScript wrapper uses JSON commands/events over stdin/stdout to communicate with the Rust binary
-- **Socket Relay** — A Unix domain socket server for routes requiring TypeScript-side handling (socket handlers, dynamic host/port functions)
+- **Socket/Datagram Relay** — Unix domain socket servers for routes requiring TypeScript-side handling (socket handlers, datagram handlers, dynamic host/port functions)
 
 ## 🎯 Route Configuration Reference
 
@@ -579,22 +719,26 @@ SmartProxy uses a hybrid **Rust + TypeScript** architecture:
 
 ```typescript
 interface IRouteMatch {
-  ports: number | number[] | Array<{ from: number; to: number }>;  // Required — port(s) to listen on
-  domains?: string | string[];         // 'example.com', '*.example.com'
-  path?: string;                       // '/api/*', '/users/:id'
-  clientIp?: string[];                 // ['10.0.0.0/8', '192.168.*']
-  tlsVersion?: string[];               // ['TLSv1.2', 'TLSv1.3']
+  ports: TPortRange;                     // Required — port(s) to listen on
+  transport?: 'tcp' | 'udp' | 'all';    // Transport protocol (default: 'tcp')
+  domains?: string | string[];           // 'example.com', '*.example.com'
+  path?: string;                         // '/api/*', '/users/:id'
+  clientIp?: string[];                   // ['10.0.0.0/8', '192.168.*']
+  tlsVersion?: string[];                 // ['TLSv1.2', 'TLSv1.3']
   headers?: Record<string, string | RegExp>;  // Match by HTTP headers
-  protocol?: 'http' | 'tcp';          // Match specific protocol ('http' includes h2 + WebSocket upgrades)
+  protocol?: 'http' | 'tcp' | 'udp' | 'quic' | 'http3';  // Application-layer protocol
 }
+
+// Port range supports single numbers, arrays, and ranges
+type TPortRange = number | Array<number | { from: number; to: number }>;
 ```
 
 ### Action Types
 
 | Type | Description |
 |------|-------------|
-| `forward` | Proxy to one or more backend targets (with optional TLS, WebSocket, load balancing) |
-| `socket-handler` | Custom socket handling function in TypeScript |
+| `forward` | Proxy to one or more backend targets (with optional TLS, WebSocket, load balancing, UDP/QUIC) |
+| `socket-handler` | Custom socket/datagram handling function in TypeScript |
 
 ### Target Options
 
@@ -602,14 +746,15 @@ interface IRouteMatch {
 interface IRouteTarget {
   host: string | string[] | ((context: IRouteContext) => string | string[]);
   port: number | 'preserve' | ((context: IRouteContext) => number);
-  tls?: IRouteTls;           // Per-target TLS override
-  priority?: number;          // Target priority
-  match?: ITargetMatch;       // Sub-match within a route (by port, path, headers, method)
+  tls?: IRouteTls;                  // Per-target TLS override
+  priority?: number;                // Target priority
+  match?: ITargetMatch;             // Sub-match within a route (by port, path, headers, method)
   websocket?: IRouteWebSocket;
   loadBalancing?: IRouteLoadBalancing;
   sendProxyProtocol?: boolean;
   headers?: IRouteHeaders;
   advanced?: IRouteAdvanced;
+  backendTransport?: 'tcp' | 'udp'; // Backend transport (e.g., receive QUIC, forward as TCP)
 }
 ```
 
@@ -666,6 +811,49 @@ interface IRouteLoadBalancing {
 }
 ```
 
+### Backend Protocol Options
+
+```typescript
+// Set on action.options
+{
+  action: {
+    type: 'forward',
+    targets: [...],
+    options: {
+      backendProtocol: 'auto' | 'http1' | 'http2' | 'http3'
+    }
+  }
+}
+```
+
+| Value | Backend Behavior |
+|-------|-----------------|
+| `'auto'` | Best-effort: discovers H3 via Alt-Svc, probes H2 via ALPN, falls back to H1 |
+| `'http1'` | Always HTTP/1.1 (no ALPN probe) |
+| `'http2'` | Always HTTP/2 (hard-fail if handshake fails) |
+| `'http3'` | Always HTTP/3 over QUIC (3s connect timeout, hard-fail if unreachable) |
+
+### UDP & QUIC Options
+
+```typescript
+interface IRouteUdp {
+  sessionTimeout?: number;       // Idle timeout per UDP session (ms, default: 60000)
+  maxSessionsPerIP?: number;     // Max concurrent sessions per IP (default: 1000)
+  maxDatagramSize?: number;      // Max datagram size in bytes (default: 65535)
+  quic?: IRouteQuic;
+}
+
+interface IRouteQuic {
+  maxIdleTimeout?: number;                // QUIC idle timeout (ms, default: 30000)
+  maxConcurrentBidiStreams?: number;       // Max bidi streams (default: 100)
+  maxConcurrentUniStreams?: number;        // Max uni streams (default: 100)
+  enableHttp3?: boolean;                  // Enable HTTP/3 (default: false)
+  altSvcPort?: number;                    // Port for Alt-Svc header
+  altSvcMaxAge?: number;                  // Alt-Svc max age in seconds (default: 86400)
+  initialCongestionWindow?: number;       // Initial congestion window (bytes)
+}
+```
+
 ## 🛠️ Helper Functions Reference
 
 All helpers are fully typed and return `IRouteConfig` or `IRouteConfig[]`:
@@ -689,7 +877,7 @@ import {
   createWebSocketRoute,            // WebSocket-enabled route
 
   // Custom Protocols
-  createSocketHandlerRoute,        // Custom socket handler
+  createSocketHandlerRoute,        // Custom TCP socket handler
   SocketHandlers,                  // Pre-built handlers (echo, proxy, block, etc.)
 
   // NFTables (Linux, requires root)
@@ -718,6 +906,8 @@ import {
 } from '@push.rocks/smartproxy';
 ```
 
+> **Tip:** For UDP datagram handler routes or QUIC/HTTP3 routes, construct `IRouteConfig` objects directly — there are no helper functions for these yet. See the [UDP Datagram Handler](#-udp-datagram-handler) and [QUIC / HTTP3 Forwarding](#-quic--http3-forwarding) examples above.
+
 ## 📖 API Documentation
 
 ### SmartProxy Class
@@ -753,6 +943,8 @@ class SmartProxy extends EventEmitter {
 
   // Events
   on(event: 'error', handler: (err: Error) => void): this;
+  on(event: 'certificate-issued', handler: (ev: ICertificateIssuedEvent) => void): this;
+  on(event: 'certificate-failed', handler: (ev: ICertificateFailedEvent) => void): this;
 }
 ```
 
@@ -775,6 +967,8 @@ interface ISmartProxyOptions {
   // Custom certificate provisioning
   certProvisionFunction?: (domain: string) => Promise<ICert | 'http01'>;
   certProvisionFallbackToAcme?: boolean;    // Fall back to ACME on failure (default: true)
+  certProvisionTimeout?: number;            // Timeout per provision call (ms)
+  certProvisionConcurrency?: number;        // Max concurrent provisions
 
   // Consumer-managed certificate persistence (see "Consumer-Managed Certificate Storage")
   certStore?: ISmartProxyCertStore;
@@ -782,6 +976,9 @@ interface ISmartProxyOptions {
   // Self-signed fallback
   disableDefaultCert?: boolean;             // Disable '*' self-signed fallback (default: false)
 
+  // Rust binary path override
+  rustBinaryPath?: string;                  // Custom path to the Rust proxy binary
+
   // Global defaults
   defaults?: {
     target?: { host: string; port: number };
@@ -868,11 +1065,22 @@ metrics.requests.perSecond();              // Requests per second
 metrics.requests.perMinute();              // Requests per minute
 metrics.requests.total();                  // Total requests
 
+// UDP metrics
+metrics.udp.activeSessions();              // Current active UDP sessions
+metrics.udp.totalSessions();              // Total UDP sessions since start
+metrics.udp.datagramsIn();                // Datagrams received
+metrics.udp.datagramsOut();               // Datagrams sent
+
 // Cumulative totals
 metrics.totals.bytesIn();                  // Total bytes received
 metrics.totals.bytesOut();                 // Total bytes sent
 metrics.totals.connections();              // Total connections
 
+// Backend metrics
+metrics.backends.byBackend();              // Map<backend, IBackendMetrics>
+metrics.backends.protocols();              // Map<backend, protocol>
+metrics.backends.topByErrors(10);          // Top N error-prone backends
+
 // Percentiles
 metrics.percentiles.connectionDuration();  // { p50, p95, p99 }
 metrics.percentiles.bytesTransferred();    // { in: { p50, p95, p99 }, out: { p50, p95, p99 } }
@@ -896,11 +1104,16 @@ metrics.percentiles.bytesTransferred();    // { in: { p50, p95, p99 }, out: { p5
 ### Rust Binary Not Found
 
 SmartProxy searches for the Rust binary in this order:
-1. `SMARTPROXY_RUST_BINARY` environment variable
-2. Platform-specific npm package (`@push.rocks/smartproxy-linux-x64`, etc.)
-3. `dist_rust/rustproxy` relative to the package root (built by `tsrust`)
-4. Local dev build (`./rust/target/release/rustproxy`)
-5. System PATH (`rustproxy`)
+1. `rustBinaryPath` option in `ISmartProxyOptions`
+2. `SMARTPROXY_RUST_BINARY` environment variable
+3. Platform-specific npm package (`@push.rocks/smartproxy-linux-x64`, etc.)
+4. `dist_rust/rustproxy` relative to the package root (built by `tsrust`)
+5. Local dev build (`./rust/target/release/rustproxy`)
+6. System PATH (`rustproxy`)
+
+### QUIC / HTTP3 Caveats
+- **GREASE frames are disabled.** The underlying h3 crate sends [GREASE frames](https://www.rfc-editor.org/rfc/rfc9114.html#frame-reserved) by default to test protocol extensibility. However, some HTTP/3 clients and servers don't properly ignore unknown frame types, causing 400/500 errors or stream hangs ([h3#206](https://github.com/hyperium/h3/issues/206)). SmartProxy disables GREASE on both the server side (for incoming H3 requests) and the client side (for H3 backend connections) to maximize compatibility.
+- **HTTP/3 is pre-release.** The h3 ecosystem (h3 0.0.8, h3-quinn 0.0.10, quinn 0.11) is still pre-1.0. Expect rough edges.
 
 ### Performance Tuning
 - ✅ Use NFTables forwarding for high-traffic routes (Linux only)

rust/Cargo.lock

@@ -157,12 +157,24 @@ dependencies = [
  "shlex",
 ]
 
+[[package]]
+name = "cesu8"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c"
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
 [[package]]
 name = "clap"
 version = "4.5.57"
@@ -218,6 +230,16 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
 
+[[package]]
+name = "combine"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
@@ -285,6 +307,24 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "fastbloom"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7f34442dbe69c60fe8eaf58a8cafff81a1f278816d8ab4db255b3bef4ac3c4"
+dependencies = [
+ "getrandom 0.3.4",
+ "libm",
+ "rand",
+ "siphasher",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -303,6 +343,21 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
 
+[[package]]
+name = "futures"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65bc07b1a8bc7c85c5f2e110c476c7389b4554ba72af57d8445ea63a576b0876"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
 [[package]]
 name = "futures-channel"
 version = "0.3.31"
@@ -310,6 +365,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2dff15bf788c671c1934e366d07e30c1814a8ef514e1af724a602e8a2fbe1b10"
 dependencies = [
  "futures-core",
+ "futures-sink",
 ]
 
 [[package]]
@@ -318,6 +374,34 @@ version = "0.3.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "05f29059c0c2090612e8d742178b0580d2dc940c837851ad723096f87af6663e"
 
+[[package]]
+name = "futures-executor"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e28d1d997f585e54aebc3f97d39e72338912123a67330d723fdbb564d646c9f"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "162ee34ebcb7c64a8abebc059ce0fee27c2262618d7b60ed8faf72fef13c3650"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "futures-sink"
 version = "0.3.31"
@@ -336,10 +420,16 @@ version = "0.3.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9fa08315bb612088cc391249efdc3bc77536f16c91f6cf495e6fbe85b20a4a81"
 dependencies = [
+ "futures-channel",
  "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
  "futures-task",
+ "memchr",
  "pin-project-lite",
  "pin-utils",
+ "slab",
 ]
 
 [[package]]
@@ -362,9 +452,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
  "cfg-if",
+ "js-sys",
  "libc",
  "r-efi",
  "wasip2",
+ "wasm-bindgen",
 ]
 
 [[package]]
@@ -392,6 +484,34 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "h3"
+version = "0.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10872b55cfb02a821b69dc7cf8dc6a71d6af25eb9a79662bec4a9d016056b3be"
+dependencies = [
+ "bytes",
+ "fastrand",
+ "futures-util",
+ "http",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "h3-quinn"
+version = "0.0.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2e732c8d91a74731663ac8479ab505042fbf547b9a207213ab7fbcbfc4f8b4"
+dependencies = [
+ "bytes",
+ "futures",
+ "h3",
+ "quinn",
+ "tokio",
+ "tokio-util",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.14.5"
@@ -565,6 +685,28 @@ version = "1.0.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
 
+[[package]]
+name = "jni"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a87aa2bb7d2af34197c04845522473242e1aa17c12f4935d5856491a7fb8c97"
+dependencies = [
+ "cesu8",
+ "cfg-if",
+ "combine",
+ "jni-sys",
+ "log",
+ "thiserror 1.0.69",
+ "walkdir",
+ "windows-sys 0.45.0",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8eaf4bc02d17cbdd7ff4c7438cafcdf7fb9a4613313ad11b4f8fefe7d3fa0130"
+
 [[package]]
 name = "jobserver"
 version = "0.1.34"
@@ -612,6 +754,12 @@ version = "0.2.180"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bcc35a38544a891a5f7c865aca548a982ccb3b8650a5b06d0fd33a10283c56fc"
 
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
 [[package]]
 name = "libmimalloc-sys"
 version = "0.1.44"
@@ -637,6 +785,12 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "lru-slab"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+
 [[package]]
 name = "matchers"
 version = "0.2.0"
@@ -784,6 +938,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
 
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.106"
@@ -793,6 +956,64 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "quinn"
+version = "0.11.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e20a958963c291dc322d98411f541009df2ced7b5a4f2bd52337638cfccf20"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "futures-io",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2 0.6.2",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "434b42fec591c96ef50e21e886936e66d3cc3f737104fdb9b737c40ffb94c098"
+dependencies = [
+ "bytes",
+ "fastbloom",
+ "getrandom 0.3.4",
+ "lru-slab",
+ "rand",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
+ "slab",
+ "thiserror 2.0.18",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "addec6a0dcad8a8d96a771f815f0eaf55f9d1805756410b39f5fa81332574cbd"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2 0.6.2",
+ "tracing",
+ "windows-sys 0.60.2",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.44"
@@ -808,6 +1029,35 @@ version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
+[[package]]
+name = "rand"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
 [[package]]
 name = "rcgen"
 version = "0.13.2"
@@ -873,6 +1123,12 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rustc-hash"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
+
 [[package]]
 name = "rustls"
 version = "0.23.36"
@@ -916,9 +1172,37 @@ version = "1.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
 dependencies = [
+ "web-time",
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d99feebc72bae7ab76ba994bb5e121b8d83d910ca40b36e0921f53becc41784"
+dependencies = [
+ "core-foundation",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
+
 [[package]]
 name = "rustls-webpki"
 version = "0.103.9"
@@ -940,12 +1224,17 @@ dependencies = [
  "bytes",
  "clap",
  "dashmap",
+ "h3",
+ "h3-quinn",
+ "http",
  "http-body-util",
  "hyper",
  "hyper-util",
  "mimalloc",
+ "quinn",
  "rcgen",
  "rustls",
+ "rustls-pemfile",
  "rustproxy-config",
  "rustproxy-http",
  "rustproxy-metrics",
@@ -981,10 +1270,13 @@ dependencies = [
  "arc-swap",
  "bytes",
  "dashmap",
+ "h3",
+ "h3-quinn",
  "http-body",
  "http-body-util",
  "hyper",
  "hyper-util",
+ "quinn",
  "regex",
  "rustls",
  "rustproxy-config",
@@ -1031,7 +1323,10 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "arc-swap",
+ "base64",
  "dashmap",
+ "quinn",
+ "rcgen",
  "rustls",
  "rustls-pemfile",
  "rustproxy-config",
@@ -1096,6 +1391,15 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
 [[package]]
 name = "schannel"
 version = "0.1.28"
@@ -1214,6 +1518,12 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "siphasher"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2aa850e253778c88a04c3d7323b043aeda9d3e30d5971937c1855769763678e"
+
 [[package]]
 name = "slab"
 version = "0.4.12"
@@ -1349,6 +1659,21 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tinyvec"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e61e67053d25a4e82c844e8424039d9745781b3fc4f32b8d55ed50f5f667ef3"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
 [[package]]
 name = "tokio"
 version = "1.49.0"
@@ -1412,6 +1737,7 @@ version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
+ "log",
  "pin-project-lite",
  "tracing-attributes",
  "tracing-core",
@@ -1497,6 +1823,16 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
 [[package]]
 name = "want"
 version = "0.3.1"
@@ -1566,12 +1902,49 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-root-certs"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "804f18a4ac2676ffb4e8b5b5fa9ae38af06df08162314f96a68d2a363e21a8ca"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 
+[[package]]
+name = "windows-sys"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+dependencies = [
+ "windows-targets 0.42.2",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.52.0"
@@ -1599,6 +1972,21 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-targets"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071"
+dependencies = [
+ "windows_aarch64_gnullvm 0.42.2",
+ "windows_aarch64_msvc 0.42.2",
+ "windows_i686_gnu 0.42.2",
+ "windows_i686_msvc 0.42.2",
+ "windows_x86_64_gnu 0.42.2",
+ "windows_x86_64_gnullvm 0.42.2",
+ "windows_x86_64_msvc 0.42.2",
+]
+
 [[package]]
 name = "windows-targets"
 version = "0.52.6"
@@ -1632,6 +2020,12 @@ dependencies = [
  "windows_x86_64_msvc 0.53.1",
 ]
 
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8"
+
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.52.6"
@@ -1644,6 +2038,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
 
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43"
+
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.52.6"
@@ -1656,6 +2056,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
 
+[[package]]
+name = "windows_i686_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f"
+
 [[package]]
 name = "windows_i686_gnu"
 version = "0.52.6"
@@ -1680,6 +2086,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
 
+[[package]]
+name = "windows_i686_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060"
+
 [[package]]
 name = "windows_i686_msvc"
 version = "0.52.6"
@@ -1692,6 +2104,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
 
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36"
+
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.52.6"
@@ -1704,6 +2122,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
 
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3"
+
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.52.6"
@@ -1716,6 +2140,12 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
 
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0"
+
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.52.6"
@@ -1743,6 +2173,26 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "zerocopy"
+version = "0.8.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2578b716f8a7a858b7f02d5bd870c14bf4ddbbcf3a4c05414ba6503640505e3"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e6cc098ea4d3bd6246687de65af3f920c430e236bee1e3bf2e441463f08a02f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "zeroize"
 version = "1.8.2"

rust/Cargo.toml

@@ -91,6 +91,13 @@ libc = "0.2"
 # Socket-level options (keepalive, etc.)
 socket2 = { version = "0.5", features = ["all"] }
 
+# QUIC transport
+quinn = "0.11"
+
+# HTTP/3 protocol
+h3 = "0.0.8"
+h3-quinn = "0.0.10"
+
 # mimalloc allocator (prevents glibc fragmentation / slow RSS growth)
 mimalloc = "0.1"
 

rust/crates/rustproxy-config/src/helpers.rs

@@ -15,6 +15,7 @@ pub fn create_http_route(
             domains: Some(domains.into()),
             path: None,
             client_ip: None,
+            transport: None,
             tls_version: None,
             headers: None,
             protocol: None,
@@ -31,6 +32,7 @@ pub fn create_http_route(
                 send_proxy_protocol: None,
                 headers: None,
                 advanced: None,
+                backend_transport: None,
                 priority: None,
             }]),
             tls: None,
@@ -41,6 +43,7 @@ pub fn create_http_route(
             forwarding_engine: None,
             nftables: None,
             send_proxy_protocol: None,
+            udp: None,
         },
         headers: None,
         security: None,
@@ -107,6 +110,7 @@ pub fn create_http_to_https_redirect(
             domains: Some(domains),
             path: None,
             client_ip: None,
+            transport: None,
             tls_version: None,
             headers: None,
             protocol: None,
@@ -137,6 +141,7 @@ pub fn create_http_to_https_redirect(
             forwarding_engine: None,
             nftables: None,
             send_proxy_protocol: None,
+            udp: None,
         },
         headers: None,
         security: None,
@@ -187,6 +192,7 @@ pub fn create_load_balancer_route(
             send_proxy_protocol: None,
             headers: None,
             advanced: None,
+            backend_transport: None,
             priority: None,
         })
         .collect();
@@ -200,6 +206,7 @@ pub fn create_load_balancer_route(
             domains: Some(domains.into()),
             path: None,
             client_ip: None,
+            transport: None,
             tls_version: None,
             headers: None,
             protocol: None,
@@ -218,6 +225,7 @@ pub fn create_load_balancer_route(
             forwarding_engine: None,
             nftables: None,
             send_proxy_protocol: None,
+            udp: None,
         },
         headers: None,
         security: None,

rust/crates/rustproxy-config/src/route_types.rs

@@ -7,16 +7,24 @@ use crate::security_types::RouteSecurity;
 // ─── Port Range ──────────────────────────────────────────────────────
 
 /// Port range specification format.
-/// Matches TypeScript: `type TPortRange = number | number[] | Array<{ from: number; to: number }>`
+/// Matches TypeScript: `type TPortRange = number | Array<number | { from: number; to: number }>`
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum PortRange {
     /// Single port number
     Single(u16),
-    /// Array of port numbers
-    List(Vec<u16>),
-    /// Array of port ranges
-    Ranges(Vec<PortRangeSpec>),
+    /// Array of port numbers, ranges, or mixed
+    List(Vec<PortRangeItem>),
+}
+
+/// A single item in a port range array: either a number or a from-to range.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PortRangeItem {
+    /// Single port number
+    Port(u16),
+    /// A from-to port range
+    Range(PortRangeSpec),
 }
 
 impl PortRange {
@@ -24,9 +32,11 @@ impl PortRange {
     pub fn to_ports(&self) -> Vec<u16> {
         match self {
             PortRange::Single(p) => vec![*p],
-            PortRange::List(ports) => ports.clone(),
-            PortRange::Ranges(ranges) => {
-                ranges.iter().flat_map(|r| r.from..=r.to).collect()
+            PortRange::List(items) => {
+                items.iter().flat_map(|item| match item {
+                    PortRangeItem::Port(p) => vec![*p],
+                    PortRangeItem::Range(r) => (r.from..=r.to).collect(),
+                }).collect()
             }
         }
     }
@@ -95,6 +105,10 @@ pub struct RouteMatch {
     /// Listen on these ports (required)
     pub ports: PortRange,
 
+    /// Transport protocol: tcp (default), udp, or all (both TCP and UDP)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transport: Option<TransportProtocol>,
+
     /// Optional domain patterns to match (default: all domains)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub domains: Option<DomainSpec>,
@@ -115,7 +129,7 @@ pub struct RouteMatch {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub headers: Option<HashMap<String, String>>,
 
-    /// Match specific protocol: "http" (includes h2 + websocket) or "tcp"
+    /// Match specific protocol: "http", "tcp", "udp", "quic", "http3"
     #[serde(skip_serializing_if = "Option::is_none")]
     pub protocol: Option<String>,
 }
@@ -367,9 +381,19 @@ pub struct NfTablesOptions {
 pub enum BackendProtocol {
     Http1,
     Http2,
+    Http3,
     Auto,
 }
 
+/// Transport protocol for route matching.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum TransportProtocol {
+    Tcp,
+    Udp,
+    All,
+}
+
 /// Action options.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -470,6 +494,10 @@ pub struct RouteTarget {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub advanced: Option<RouteAdvanced>,
 
+    /// Override transport for backend connection (e.g., receive QUIC but forward as TCP)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend_transport: Option<TransportProtocol>,
+
     /// Priority for matching (higher values checked first, default: 0)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub priority: Option<i32>,
@@ -524,6 +552,68 @@ pub struct RouteAction {
     /// PROXY protocol support (default for all targets)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub send_proxy_protocol: Option<bool>,
+
+    /// UDP-specific settings (session tracking, datagram limits, QUIC config)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub udp: Option<RouteUdp>,
+}
+
+// ─── UDP & QUIC Config ──────────────────────────────────────────────
+
+/// UDP-specific settings for route actions.
+/// Matches TypeScript: `IRouteUdp`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteUdp {
+    /// Idle timeout for a UDP session/flow in ms. Default: 60000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub session_timeout: Option<u64>,
+
+    /// Max concurrent UDP sessions per source IP. Default: 1000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_sessions_per_ip: Option<u32>,
+
+    /// Max accepted datagram size in bytes. Default: 65535
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_datagram_size: Option<u32>,
+
+    /// QUIC-specific configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub quic: Option<RouteQuic>,
+}
+
+/// QUIC and HTTP/3 settings.
+/// Matches TypeScript: `IRouteQuic`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteQuic {
+    /// QUIC connection idle timeout in ms. Default: 30000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_idle_timeout: Option<u64>,
+
+    /// Max concurrent bidirectional streams per QUIC connection. Default: 100
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_concurrent_bidi_streams: Option<u32>,
+
+    /// Max concurrent unidirectional streams per QUIC connection. Default: 100
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_concurrent_uni_streams: Option<u32>,
+
+    /// Enable HTTP/3 over this QUIC endpoint. Default: false
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_http3: Option<bool>,
+
+    /// Port to advertise in Alt-Svc header on TCP HTTP responses
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub alt_svc_port: Option<u16>,
+
+    /// Max age for Alt-Svc advertisement in seconds. Default: 86400
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub alt_svc_max_age: Option<u64>,
+
+    /// Initial congestion window size in bytes
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub initial_congestion_window: Option<u32>,
 }
 
 // ─── Route Config ────────────────────────────────────────────────────

rust/crates/rustproxy-http/Cargo.toml

@@ -27,3 +27,6 @@ arc-swap = { workspace = true }
 dashmap = { workspace = true }
 tokio-util = { workspace = true }
 socket2 = { workspace = true }
+quinn = { workspace = true }
+h3 = { workspace = true }
+h3-quinn = { workspace = true }

rust/crates/rustproxy-http/src/connection_pool.rs

@@ -1,16 +1,16 @@
-//! Backend connection pool for HTTP/1.1 and HTTP/2.
+//! Backend connection pool for HTTP/1.1, HTTP/2, and HTTP/3 (QUIC).
 //!
 //! Reuses idle keep-alive connections to avoid per-request TCP+TLS handshakes.
-//! HTTP/2 connections are multiplexed (clone the sender for each request).
+//! HTTP/2 and HTTP/3 connections are multiplexed (clone the sender / share the connection).
 
 use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
 use std::time::{Duration, Instant};
 
 use bytes::Bytes;
 use dashmap::DashMap;
 use http_body_util::combinators::BoxBody;
 use hyper::client::conn::{http1, http2};
-use tracing::debug;
 
 /// Maximum idle connections per backend key.
 const MAX_IDLE_PER_KEY: usize = 16;
@@ -19,9 +19,17 @@ const IDLE_TIMEOUT: Duration = Duration::from_secs(90);
 /// Background eviction interval.
 const EVICTION_INTERVAL: Duration = Duration::from_secs(30);
 /// Maximum age for pooled HTTP/2 connections before proactive eviction.
-/// Prevents staleness from backends that close idle connections (e.g. nginx GOAWAY).
-/// 120s is well within typical server GOAWAY windows (nginx: ~60s idle, envoy: ~60s).
 const MAX_H2_AGE: Duration = Duration::from_secs(120);
+/// Maximum age for pooled QUIC/HTTP/3 connections.
+const MAX_H3_AGE: Duration = Duration::from_secs(120);
+
+/// Protocol for pool key discrimination.
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub enum PoolProtocol {
+    H1,
+    H2,
+    H3,
+}
 
 /// Identifies a unique backend endpoint.
 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
@@ -29,7 +37,7 @@ pub struct PoolKey {
     pub host: String,
     pub port: u16,
     pub use_tls: bool,
-    pub h2: bool,
+    pub protocol: PoolProtocol,
 }
 
 /// An idle HTTP/1.1 sender with a timestamp for eviction.
@@ -38,10 +46,20 @@ struct IdleH1 {
     idle_since: Instant,
 }
 
-/// A pooled HTTP/2 sender (multiplexed, Clone-able).
+/// A pooled HTTP/2 sender (multiplexed, Clone-able) with a generation tag.
 struct PooledH2 {
     sender: http2::SendRequest<BoxBody<Bytes, hyper::Error>>,
     created_at: Instant,
+    /// Unique generation ID. Connection drivers use this to only remove their OWN
+    /// entry, preventing phantom eviction when multiple connections share the same key.
+    generation: u64,
+}
+
+/// A pooled QUIC/HTTP/3 connection (multiplexed like H2).
+pub struct PooledH3 {
+    pub connection: quinn::Connection,
+    pub created_at: Instant,
+    pub generation: u64,
 }
 
 /// Backend connection pool.
@@ -50,6 +68,10 @@ pub struct ConnectionPool {
     h1_pool: Arc<DashMap<PoolKey, Vec<IdleH1>>>,
     /// HTTP/2 multiplexed connections indexed by backend key.
     h2_pool: Arc<DashMap<PoolKey, PooledH2>>,
+    /// HTTP/3 (QUIC) connections indexed by backend key.
+    h3_pool: Arc<DashMap<PoolKey, PooledH3>>,
+    /// Monotonic generation counter for H2/H3 pool entries.
+    h2_generation: AtomicU64,
     /// Handle for the background eviction task.
     eviction_handle: Option<tokio::task::JoinHandle<()>>,
 }
@@ -59,16 +81,20 @@ impl ConnectionPool {
     pub fn new() -> Self {
         let h1_pool: Arc<DashMap<PoolKey, Vec<IdleH1>>> = Arc::new(DashMap::new());
         let h2_pool: Arc<DashMap<PoolKey, PooledH2>> = Arc::new(DashMap::new());
+        let h3_pool: Arc<DashMap<PoolKey, PooledH3>> = Arc::new(DashMap::new());
 
         let h1_clone = Arc::clone(&h1_pool);
         let h2_clone = Arc::clone(&h2_pool);
+        let h3_clone = Arc::clone(&h3_pool);
         let eviction_handle = tokio::spawn(async move {
-            Self::eviction_loop(h1_clone, h2_clone).await;
+            Self::eviction_loop(h1_clone, h2_clone, h3_clone).await;
         });
 
         Self {
             h1_pool,
             h2_pool,
+            h3_pool,
+            h2_generation: AtomicU64::new(0),
             eviction_handle: Some(eviction_handle),
         }
     }
@@ -82,7 +108,7 @@ impl ConnectionPool {
         while let Some(idle) = idles.pop() {
             // Check if the connection is still alive and ready
             if idle.idle_since.elapsed() < IDLE_TIMEOUT && idle.sender.is_ready() && !idle.sender.is_closed() {
-                debug!("Pool hit (h1): {}:{}", key.host, key.port);
+                // H1 pool hit — no logging on hot path
                 return Some(idle.sender);
             }
             // Stale or closed — drop it
@@ -115,46 +141,109 @@ impl ConnectionPool {
 
     /// Try to get a cloned HTTP/2 sender for the given key.
     /// HTTP/2 senders are Clone-able (multiplexed), so we clone rather than remove.
-    pub fn checkout_h2(&self, key: &PoolKey) -> Option<http2::SendRequest<BoxBody<Bytes, hyper::Error>>> {
+    pub fn checkout_h2(&self, key: &PoolKey) -> Option<(http2::SendRequest<BoxBody<Bytes, hyper::Error>>, Duration)> {
         let entry = self.h2_pool.get(key)?;
         let pooled = entry.value();
+        let age = pooled.created_at.elapsed();
 
-        // Check if the h2 connection is still alive and not too old
-        if pooled.sender.is_closed() || pooled.created_at.elapsed() >= MAX_H2_AGE {
+        if pooled.sender.is_closed() || age >= MAX_H2_AGE {
             drop(entry);
             self.h2_pool.remove(key);
             return None;
         }
 
         if pooled.sender.is_ready() {
-            debug!("Pool hit (h2): {}:{}", key.host, key.port);
-            return Some(pooled.sender.clone());
+            return Some((pooled.sender.clone(), age));
         }
         None
     }
 
-    /// Remove a dead HTTP/2 sender from the pool.
+    /// Remove a dead HTTP/2 sender from the pool (unconditional).
     /// Called when `send_request` fails to prevent subsequent requests from reusing the stale sender.
     pub fn remove_h2(&self, key: &PoolKey) {
         self.h2_pool.remove(key);
     }
 
-    /// Register an HTTP/2 sender in the pool. Since h2 is multiplexed,
-    /// only one sender per key is stored (it's Clone-able).
-    pub fn register_h2(&self, key: PoolKey, sender: http2::SendRequest<BoxBody<Bytes, hyper::Error>>) {
+    /// Remove an HTTP/2 sender ONLY if the current entry has the expected generation.
+    /// This prevents phantom eviction: when multiple connections share the same key,
+    /// an old connection's driver won't accidentally remove a newer connection's entry.
+    pub fn remove_h2_if_generation(&self, key: &PoolKey, expected_gen: u64) {
+        if let Some(entry) = self.h2_pool.get(key) {
+            if entry.value().generation == expected_gen {
+                drop(entry); // release DashMap ref before remove
+                self.h2_pool.remove(key);
+            }
+            // else: a newer connection replaced ours — don't touch it
+        }
+    }
+
+    /// Register an HTTP/2 sender in the pool. Returns the generation ID for this entry.
+    /// The caller should pass this generation to the connection driver so it can use
+    /// `remove_h2_if_generation` instead of `remove_h2` to avoid phantom eviction.
+    pub fn register_h2(&self, key: PoolKey, sender: http2::SendRequest<BoxBody<Bytes, hyper::Error>>) -> u64 {
+        let gen = self.h2_generation.fetch_add(1, Ordering::Relaxed);
         if sender.is_closed() {
-            return;
+            return gen;
         }
         self.h2_pool.insert(key, PooledH2 {
             sender,
             created_at: Instant::now(),
+            generation: gen,
         });
+        gen
+    }
+
+    // ── HTTP/3 (QUIC) pool methods ──
+
+    /// Try to get a pooled QUIC connection for the given key.
+    /// QUIC connections are multiplexed — the connection is shared, not removed.
+    pub fn checkout_h3(&self, key: &PoolKey) -> Option<(quinn::Connection, Duration)> {
+        let entry = self.h3_pool.get(key)?;
+        let pooled = entry.value();
+        let age = pooled.created_at.elapsed();
+
+        if age >= MAX_H3_AGE {
+            drop(entry);
+            self.h3_pool.remove(key);
+            return None;
+        }
+
+        // Check if QUIC connection is still alive
+        if pooled.connection.close_reason().is_some() {
+            drop(entry);
+            self.h3_pool.remove(key);
+            return None;
+        }
+
+        Some((pooled.connection.clone(), age))
+    }
+
+    /// Register a QUIC connection in the pool. Returns the generation ID.
+    pub fn register_h3(&self, key: PoolKey, connection: quinn::Connection) -> u64 {
+        let gen = self.h2_generation.fetch_add(1, Ordering::Relaxed);
+        self.h3_pool.insert(key, PooledH3 {
+            connection,
+            created_at: Instant::now(),
+            generation: gen,
+        });
+        gen
+    }
+
+    /// Remove a QUIC connection only if generation matches.
+    pub fn remove_h3_if_generation(&self, key: &PoolKey, expected_gen: u64) {
+        if let Some(entry) = self.h3_pool.get(key) {
+            if entry.value().generation == expected_gen {
+                drop(entry);
+                self.h3_pool.remove(key);
+            }
+        }
     }
 
     /// Background eviction loop — runs every EVICTION_INTERVAL to remove stale connections.
     async fn eviction_loop(
         h1_pool: Arc<DashMap<PoolKey, Vec<IdleH1>>>,
         h2_pool: Arc<DashMap<PoolKey, PooledH2>>,
+        h3_pool: Arc<DashMap<PoolKey, PooledH3>>,
     ) {
         let mut interval = tokio::time::interval(EVICTION_INTERVAL);
         loop {
@@ -184,6 +273,19 @@ impl ConnectionPool {
             for key in dead_h2 {
                 h2_pool.remove(&key);
             }
+
+            // Evict dead or aged-out H3 (QUIC) connections
+            let mut dead_h3 = Vec::new();
+            for entry in h3_pool.iter() {
+                if entry.value().connection.close_reason().is_some()
+                    || entry.value().created_at.elapsed() >= MAX_H3_AGE
+                {
+                    dead_h3.push(entry.key().clone());
+                }
+            }
+            for key in dead_h3 {
+                h3_pool.remove(&key);
+            }
         }
     }
 }

rust/crates/rustproxy-http/src/counting_body.rs

@@ -9,24 +9,37 @@ use bytes::Bytes;
 use http_body::Frame;
 use rustproxy_metrics::MetricsCollector;
 
+/// Flush accumulated bytes to the metrics collector every 64 KB.
+/// This reduces per-frame DashMap shard-locked reads from ~15 to ~1 per 4 frames
+/// (assuming typical 16 KB upload frames).  The 1 Hz throughput sampler still sees
+/// data within one sampling period even at low transfer rates.
+const BYTE_FLUSH_THRESHOLD: u64 = 65_536;
+
 /// Wraps any `http_body::Body` and counts data bytes passing through.
 ///
-/// Each chunk is reported to the `MetricsCollector` immediately so that
-/// the throughput tracker (sampled at 1 Hz) reflects real-time data flow.
+/// Bytes are accumulated and flushed to the `MetricsCollector` every
+/// [`BYTE_FLUSH_THRESHOLD`] bytes (and on Drop) so the throughput tracker
+/// (sampled at 1 Hz) reflects real-time data flow without per-frame overhead.
 ///
 /// The inner body is pinned on the heap to support `!Unpin` types like `hyper::body::Incoming`.
 pub struct CountingBody<B> {
     inner: Pin<Box<B>>,
     metrics: Arc<MetricsCollector>,
-    route_id: Option<String>,
-    source_ip: Option<String>,
+    route_id: Option<Arc<str>>,
+    source_ip: Option<Arc<str>>,
     /// Whether we count bytes as "in" (request body) or "out" (response body).
     direction: Direction,
+    /// Accumulated bytes not yet flushed to the metrics collector.
+    pending_bytes: u64,
     /// Optional connection-level activity tracker. When set, poll_frame updates this
     /// to keep the idle watchdog alive during active body streaming (uploads/downloads).
     connection_activity: Option<Arc<AtomicU64>>,
     /// Start instant for computing elapsed ms for connection_activity.
     activity_start: Option<std::time::Instant>,
+    /// Optional active-request counter. When set, CountingBody increments on creation
+    /// and decrements on Drop, keeping the HTTP idle watchdog aware that a response
+    /// body is still streaming (even after the request handler has returned).
+    active_requests: Option<Arc<AtomicU64>>,
 }
 
 /// Which direction the bytes flow.
@@ -43,8 +56,8 @@ impl<B> CountingBody<B> {
     pub fn new(
         inner: B,
         metrics: Arc<MetricsCollector>,
-        route_id: Option<String>,
-        source_ip: Option<String>,
+        route_id: Option<Arc<str>>,
+        source_ip: Option<Arc<str>>,
         direction: Direction,
     ) -> Self {
         Self {
@@ -53,8 +66,10 @@ impl<B> CountingBody<B> {
             route_id,
             source_ip,
             direction,
+            pending_bytes: 0,
             connection_activity: None,
             activity_start: None,
+            active_requests: None,
         }
     }
 
@@ -67,14 +82,28 @@ impl<B> CountingBody<B> {
         self
     }
 
-    /// Report a chunk of bytes immediately to the metrics collector.
+    /// Set the active-request counter for the HTTP idle watchdog.
+    /// CountingBody increments on creation and decrements on Drop, ensuring the
+    /// idle watchdog sees an "active request" while the response body streams.
+    pub fn with_active_requests(mut self, counter: Arc<AtomicU64>) -> Self {
+        counter.fetch_add(1, Ordering::Relaxed);
+        self.active_requests = Some(counter);
+        self
+    }
+
+    /// Flush accumulated bytes to the metrics collector.
     #[inline]
-    fn report_chunk(&self, len: u64) {
+    fn flush_pending(&mut self) {
+        if self.pending_bytes == 0 {
+            return;
+        }
+        let bytes = self.pending_bytes;
+        self.pending_bytes = 0;
         let route_id = self.route_id.as_deref();
         let source_ip = self.source_ip.as_deref();
         match self.direction {
-            Direction::In => self.metrics.record_bytes(len, 0, route_id, source_ip),
-            Direction::Out => self.metrics.record_bytes(0, len, route_id, source_ip),
+            Direction::In => self.metrics.record_bytes(bytes, 0, route_id, source_ip),
+            Direction::Out => self.metrics.record_bytes(0, bytes, route_id, source_ip),
         }
     }
 }
@@ -99,9 +128,12 @@ where
             Poll::Ready(Some(Ok(frame))) => {
                 if let Some(data) = frame.data_ref() {
                     let len = data.len() as u64;
-                    // Report bytes immediately so the 1 Hz throughput sampler sees them
-                    this.report_chunk(len);
-                    // Keep the connection-level idle watchdog alive during body streaming
+                    this.pending_bytes += len;
+                    if this.pending_bytes >= BYTE_FLUSH_THRESHOLD {
+                        this.flush_pending();
+                    }
+                    // Keep the connection-level idle watchdog alive on every frame
+                    // (this is just one atomic store — cheap enough per-frame)
                     if let (Some(activity), Some(start)) = (&this.connection_activity, &this.activity_start) {
                         activity.store(start.elapsed().as_millis() as u64, Ordering::Relaxed);
                     }
@@ -109,7 +141,11 @@ where
                 Poll::Ready(Some(Ok(frame)))
             }
             Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))),
-            Poll::Ready(None) => Poll::Ready(None),
+            Poll::Ready(None) => {
+                // End of stream — flush any remaining bytes
+                this.flush_pending();
+                Poll::Ready(None)
+            }
             Poll::Pending => Poll::Pending,
         }
     }
@@ -122,3 +158,15 @@ where
         self.inner.size_hint()
     }
 }
+
+impl<B> Drop for CountingBody<B> {
+    fn drop(&mut self) {
+        // Flush any remaining accumulated bytes so totals stay accurate
+        self.flush_pending();
+        // Decrement the active-request counter so the HTTP idle watchdog
+        // knows this response body is no longer streaming.
+        if let Some(ref counter) = self.active_requests {
+            counter.fetch_sub(1, Ordering::Relaxed);
+        }
+    }
+}

rust/crates/rustproxy-http/src/h3_service.rs

@@ -0,0 +1,223 @@
+//! HTTP/3 proxy service.
+//!
+//! Accepts QUIC connections via quinn, runs h3 server to handle HTTP/3 requests,
+//! and delegates backend forwarding to the shared `HttpProxyService` — same
+//! route matching, connection pool, and protocol auto-detection as TCP/HTTP.
+
+use std::net::SocketAddr;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+
+use bytes::{Buf, Bytes};
+use http_body::Frame;
+use http_body_util::BodyExt;
+use http_body_util::combinators::BoxBody;
+use tracing::{debug, warn};
+
+use rustproxy_config::RouteConfig;
+use tokio_util::sync::CancellationToken;
+
+use crate::proxy_service::{ConnActivity, HttpProxyService};
+
+/// HTTP/3 proxy service.
+///
+/// Accepts QUIC connections, parses HTTP/3 requests, and delegates backend
+/// forwarding to the shared `HttpProxyService`.
+pub struct H3ProxyService {
+    http_proxy: Arc<HttpProxyService>,
+}
+
+impl H3ProxyService {
+    pub fn new(http_proxy: Arc<HttpProxyService>) -> Self {
+        Self { http_proxy }
+    }
+
+    /// Handle an accepted QUIC connection as HTTP/3.
+    ///
+    /// If `real_client_addr` is provided (from PROXY protocol), it overrides
+    /// `connection.remote_address()` for client IP attribution.
+    pub async fn handle_connection(
+        &self,
+        connection: quinn::Connection,
+        _fallback_route: &RouteConfig,
+        port: u16,
+        real_client_addr: Option<SocketAddr>,
+        parent_cancel: &CancellationToken,
+    ) -> anyhow::Result<()> {
+        let remote_addr = real_client_addr.unwrap_or_else(|| connection.remote_address());
+        debug!("HTTP/3 connection from {} on port {}", remote_addr, port);
+
+        let mut h3_conn: h3::server::Connection<h3_quinn::Connection, Bytes> =
+            h3::server::builder()
+                .send_grease(false)
+                .build(h3_quinn::Connection::new(connection))
+                .await
+                .map_err(|e| anyhow::anyhow!("H3 connection setup failed: {}", e))?;
+
+        loop {
+            let resolver = tokio::select! {
+                _ = parent_cancel.cancelled() => {
+                    debug!("HTTP/3 connection from {} cancelled by parent", remote_addr);
+                    break;
+                }
+                result = h3_conn.accept() => {
+                    match result {
+                        Ok(Some(resolver)) => resolver,
+                        Ok(None) => {
+                            debug!("HTTP/3 connection from {} closed", remote_addr);
+                            break;
+                        }
+                        Err(e) => {
+                            debug!("HTTP/3 accept error from {}: {}", remote_addr, e);
+                            break;
+                        }
+                    }
+                }
+            };
+
+            let (request, stream) = match resolver.resolve_request().await {
+                Ok(pair) => pair,
+                Err(e) => {
+                    debug!("HTTP/3 request resolve error: {}", e);
+                    continue;
+                }
+            };
+
+            let http_proxy = Arc::clone(&self.http_proxy);
+            let request_cancel = parent_cancel.child_token();
+
+            tokio::spawn(async move {
+                if let Err(e) = handle_h3_request(
+                    request, stream, port, remote_addr, &http_proxy, request_cancel,
+                ).await {
+                    debug!("HTTP/3 request error from {}: {}", remote_addr, e);
+                }
+            });
+        }
+
+        Ok(())
+    }
+}
+
+/// Handle a single HTTP/3 request by delegating to HttpProxyService.
+///
+/// 1. Read the H3 request body via an mpsc channel (streaming, not buffered)
+/// 2. Build a `hyper::Request<BoxBody>` that HttpProxyService can handle
+/// 3. Call `HttpProxyService::handle_request` — same route matching, connection
+///    pool, ALPN protocol detection (H1/H2/H3) as the TCP/HTTP path
+/// 4. Stream the response back over the H3 stream
+async fn handle_h3_request(
+    request: hyper::Request<()>,
+    mut stream: h3::server::RequestStream<h3_quinn::BidiStream<Bytes>, Bytes>,
+    port: u16,
+    peer_addr: SocketAddr,
+    http_proxy: &HttpProxyService,
+    cancel: CancellationToken,
+) -> anyhow::Result<()> {
+    // Stream request body from H3 client via an mpsc channel.
+    let (body_tx, body_rx) = tokio::sync::mpsc::channel::<Bytes>(4);
+
+    // Spawn the H3 body reader task with cancellation
+    let body_cancel = cancel.clone();
+    let body_reader = tokio::spawn(async move {
+        loop {
+            let chunk = tokio::select! {
+                _ = body_cancel.cancelled() => break,
+                result = stream.recv_data() => {
+                    match result {
+                        Ok(Some(chunk)) => chunk,
+                        _ => break,
+                    }
+                }
+            };
+            let mut chunk = chunk;
+            let data = Bytes::copy_from_slice(chunk.chunk());
+            chunk.advance(chunk.remaining());
+            if body_tx.send(data).await.is_err() {
+                break;
+            }
+        }
+        stream
+    });
+
+    // Build a hyper::Request<BoxBody> from the H3 request + streaming body.
+    // The URI already has scheme + authority + path set by the h3 crate.
+    let body = H3RequestBody { receiver: body_rx };
+    let (parts, _) = request.into_parts();
+    let boxed_body: BoxBody<Bytes, hyper::Error> = BoxBody::new(body);
+    let req = hyper::Request::from_parts(parts, boxed_body);
+
+    // Delegate to HttpProxyService — same backend path as TCP/HTTP:
+    // route matching, ALPN protocol detection, connection pool, H1/H2/H3 auto.
+    let conn_activity = ConnActivity::new_standalone();
+    let response = http_proxy.handle_request(req, peer_addr, port, cancel, conn_activity).await
+        .map_err(|e| anyhow::anyhow!("Backend request failed: {}", e))?;
+
+    // Await the body reader to get the H3 stream back
+    let mut stream = body_reader.await
+        .map_err(|e| anyhow::anyhow!("Body reader task failed: {}", e))?;
+
+    // Send response headers over H3 (skip hop-by-hop headers)
+    let (resp_parts, resp_body) = response.into_parts();
+    let mut h3_response = hyper::Response::builder().status(resp_parts.status);
+    for (name, value) in &resp_parts.headers {
+        let n = name.as_str();
+        if n == "transfer-encoding" || n == "connection" || n == "keep-alive" || n == "upgrade" {
+            continue;
+        }
+        h3_response = h3_response.header(name, value);
+    }
+    let h3_response = h3_response.body(())
+        .map_err(|e| anyhow::anyhow!("Failed to build H3 response: {}", e))?;
+
+    stream.send_response(h3_response).await
+        .map_err(|e| anyhow::anyhow!("Failed to send H3 response: {}", e))?;
+
+    // Stream response body back over H3
+    let mut resp_body = resp_body;
+    while let Some(frame) = resp_body.frame().await {
+        match frame {
+            Ok(frame) => {
+                if let Some(data) = frame.data_ref() {
+                    stream.send_data(Bytes::copy_from_slice(data)).await
+                        .map_err(|e| anyhow::anyhow!("Failed to send H3 data: {}", e))?;
+                }
+            }
+            Err(e) => {
+                warn!("Response body read error: {}", e);
+                break;
+            }
+        }
+    }
+
+    // Finish the H3 stream (send QUIC FIN)
+    stream.finish().await
+        .map_err(|e| anyhow::anyhow!("Failed to finish H3 stream: {}", e))?;
+
+    Ok(())
+}
+
+/// A streaming request body backed by an mpsc channel receiver.
+///
+/// Implements `http_body::Body` so hyper can poll chunks as they arrive
+/// from the H3 client, avoiding buffering the entire request body in memory.
+struct H3RequestBody {
+    receiver: tokio::sync::mpsc::Receiver<Bytes>,
+}
+
+impl http_body::Body for H3RequestBody {
+    type Data = Bytes;
+    type Error = hyper::Error;
+
+    fn poll_frame(
+        mut self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
+        match self.receiver.poll_recv(cx) {
+            Poll::Ready(Some(data)) => Poll::Ready(Some(Ok(Frame::data(data)))),
+            Poll::Ready(None) => Poll::Ready(None),
+            Poll::Pending => Poll::Pending,
+        }
+    }
+}

rust/crates/rustproxy-http/src/lib.rs

@@ -9,8 +9,10 @@ pub mod protocol_cache;
 pub mod proxy_service;
 pub mod request_filter;
 pub mod response_filter;
+pub mod shutdown_on_drop;
 pub mod template;
 pub mod upstream_selector;
+pub mod h3_service;
 
 pub use connection_pool::*;
 pub use counting_body::*;

rust/crates/rustproxy-http/src/protocol_cache.rs

@@ -1,8 +1,11 @@
-//! Bounded, TTL-based protocol detection cache for HTTP/2 auto-detection.
+//! Bounded, TTL-based protocol detection cache for backend protocol auto-detection.
 //!
-//! Caches the ALPN-negotiated protocol (H1 or H2) per backend endpoint and requested
+//! Caches the detected protocol (H1, H2, or H3) per backend endpoint and requested
 //! domain (host:port + requested_host). This prevents cache oscillation when multiple
-//! frontend domains share the same backend but differ in HTTP/2 support.
+//! frontend domains share the same backend but differ in protocol support.
+//!
+//! H3 detection uses the browser model: Alt-Svc headers from H1/H2 responses are
+//! parsed and cached, including the advertised H3 port (which may differ from TCP).
 
 use std::sync::Arc;
 use std::time::{Duration, Instant};
@@ -26,6 +29,15 @@ const PROTOCOL_CACHE_CLEANUP_INTERVAL: Duration = Duration::from_secs(60);
 pub enum DetectedProtocol {
     H1,
     H2,
+    H3,
+}
+
+/// Result of a protocol cache lookup.
+#[derive(Debug, Clone, Copy)]
+pub struct CachedProtocol {
+    pub protocol: DetectedProtocol,
+    /// For H3: the port advertised by Alt-Svc (may differ from TCP port).
+    pub h3_port: Option<u16>,
 }
 
 /// Key for the protocol cache: (host, port, requested_host).
@@ -42,6 +54,8 @@ pub struct ProtocolCacheKey {
 struct CachedEntry {
     protocol: DetectedProtocol,
     detected_at: Instant,
+    /// For H3: the port advertised by Alt-Svc (may differ from TCP port).
+    h3_port: Option<u16>,
 }
 
 /// Bounded, TTL-based protocol detection cache.
@@ -74,11 +88,14 @@ impl ProtocolCache {
 
     /// Look up the cached protocol for a backend endpoint.
     /// Returns `None` if not cached or expired (caller should probe via ALPN).
-    pub fn get(&self, key: &ProtocolCacheKey) -> Option<DetectedProtocol> {
+    pub fn get(&self, key: &ProtocolCacheKey) -> Option<CachedProtocol> {
         let entry = self.cache.get(key)?;
         if entry.detected_at.elapsed() < PROTOCOL_CACHE_TTL {
             debug!("Protocol cache hit: {:?} for {}:{} (requested: {:?})", entry.protocol, key.host, key.port, key.requested_host);
-            Some(entry.protocol)
+            Some(CachedProtocol {
+                protocol: entry.protocol,
+                h3_port: entry.h3_port,
+            })
         } else {
             // Expired — remove and return None to trigger re-probe
             drop(entry); // release DashMap ref before remove
@@ -90,6 +107,16 @@ impl ProtocolCache {
     /// Insert a detected protocol into the cache.
     /// If the cache is at capacity, evict the oldest entry first.
     pub fn insert(&self, key: ProtocolCacheKey, protocol: DetectedProtocol) {
+        self.insert_with_h3_port(key, protocol, None);
+    }
+
+    /// Insert an H3 detection result with the Alt-Svc advertised port.
+    pub fn insert_h3(&self, key: ProtocolCacheKey, h3_port: u16) {
+        self.insert_with_h3_port(key, DetectedProtocol::H3, Some(h3_port));
+    }
+
+    /// Insert a protocol detection result with an optional H3 port.
+    fn insert_with_h3_port(&self, key: ProtocolCacheKey, protocol: DetectedProtocol, h3_port: Option<u16>) {
         if self.cache.len() >= PROTOCOL_CACHE_MAX_ENTRIES && !self.cache.contains_key(&key) {
             // Evict the oldest entry to stay within bounds
             let oldest = self.cache.iter()
@@ -102,6 +129,7 @@ impl ProtocolCache {
         self.cache.insert(key, CachedEntry {
             protocol,
             detected_at: Instant::now(),
+            h3_port,
         });
     }
 

rust/crates/rustproxy-http/src/request_filter.rs

@@ -6,7 +6,6 @@ use std::sync::Arc;
 use bytes::Bytes;
 use http_body_util::Full;
 use http_body_util::BodyExt;
-use hyper::body::Incoming;
 use hyper::{Request, Response, StatusCode};
 use http_body_util::combinators::BoxBody;
 
@@ -19,7 +18,7 @@ impl RequestFilter {
     /// Apply security filters. Returns Some(response) if the request should be blocked.
     pub fn apply(
         security: &RouteSecurity,
-        req: &Request<Incoming>,
+        req: &Request<impl hyper::body::Body>,
         peer_addr: &SocketAddr,
     ) -> Option<Response<BoxBody<Bytes, hyper::Error>>> {
         Self::apply_with_rate_limiter(security, req, peer_addr, None)
@@ -29,7 +28,7 @@ impl RequestFilter {
     /// Returns Some(response) if the request should be blocked.
     pub fn apply_with_rate_limiter(
         security: &RouteSecurity,
-        req: &Request<Incoming>,
+        req: &Request<impl hyper::body::Body>,
         peer_addr: &SocketAddr,
         rate_limiter: Option<&Arc<RateLimiter>>,
     ) -> Option<Response<BoxBody<Bytes, hyper::Error>>> {
@@ -182,7 +181,7 @@ impl RequestFilter {
     /// Determine the rate limit key based on configuration.
     fn rate_limit_key(
         config: &rustproxy_config::RouteRateLimit,
-        req: &Request<Incoming>,
+        req: &Request<impl hyper::body::Body>,
         peer_addr: &SocketAddr,
     ) -> String {
         use rustproxy_config::RateLimitKeyBy;
@@ -220,7 +219,7 @@ impl RequestFilter {
     /// Handle CORS preflight (OPTIONS) requests.
     /// Returns Some(response) if this is a CORS preflight that should be handled.
     pub fn handle_cors_preflight(
-        req: &Request<Incoming>,
+        req: &Request<impl hyper::body::Body>,
     ) -> Option<Response<BoxBody<Bytes, hyper::Error>>> {
         if req.method() != hyper::Method::OPTIONS {
             return None;

rust/crates/rustproxy-http/src/response_filter.rs

@@ -10,7 +10,23 @@ pub struct ResponseFilter;
 impl ResponseFilter {
     /// Apply response headers from route config and CORS settings.
     /// If a `RequestContext` is provided, template variables in header values will be expanded.
+    /// Also injects Alt-Svc header for routes with HTTP/3 enabled.
     pub fn apply_headers(route: &RouteConfig, headers: &mut HeaderMap, req_ctx: Option<&RequestContext>) {
+        // Inject Alt-Svc for HTTP/3 advertisement if QUIC/HTTP3 is enabled on this route
+        if let Some(ref udp) = route.action.udp {
+            if let Some(ref quic) = udp.quic {
+                if quic.enable_http3.unwrap_or(false) {
+                    let port = quic.alt_svc_port
+                        .or_else(|| req_ctx.map(|c| c.port))
+                        .unwrap_or(443);
+                    let max_age = quic.alt_svc_max_age.unwrap_or(86400);
+                    let alt_svc = format!("h3=\":{}\"; ma={}", port, max_age);
+                    if let Ok(val) = HeaderValue::from_str(&alt_svc) {
+                        headers.insert("alt-svc", val);
+                    }
+                }
+            }
+        }
         // Apply custom response headers from route config
         if let Some(ref route_headers) = route.headers {
             if let Some(ref response_headers) = route_headers.response {

rust/crates/rustproxy-http/src/shutdown_on_drop.rs

@@ -0,0 +1,102 @@
+//! Wrapper that ensures TLS close_notify is sent when the stream is dropped.
+//!
+//! When hyper drops an HTTP connection (backend error, timeout, normal H2 close),
+//! the underlying TLS stream is dropped WITHOUT `shutdown()`. tokio-rustls cannot
+//! send `close_notify` in Drop (requires async). This wrapper tracks whether
+//! `poll_shutdown` was called and, if not, spawns a background task to send it.
+
+use std::io;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+
+use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
+
+/// Wraps an AsyncRead+AsyncWrite stream and ensures `shutdown()` is called when
+/// dropped, even if the caller (e.g. hyper) doesn't explicitly shut down.
+///
+/// This guarantees TLS `close_notify` is sent for TLS-wrapped streams, preventing
+/// "GnuTLS recv error (-110): The TLS connection was non-properly terminated" errors.
+pub struct ShutdownOnDrop<S: AsyncRead + AsyncWrite + Unpin + Send + 'static> {
+    inner: Option<S>,
+    shutdown_called: bool,
+}
+
+impl<S: AsyncRead + AsyncWrite + Unpin + Send + 'static> ShutdownOnDrop<S> {
+    /// Create a new wrapper around the given stream.
+    pub fn new(stream: S) -> Self {
+        Self {
+            inner: Some(stream),
+            shutdown_called: false,
+        }
+    }
+}
+
+impl<S: AsyncRead + AsyncWrite + Unpin + Send + 'static> AsyncRead for ShutdownOnDrop<S> {
+    fn poll_read(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &mut ReadBuf<'_>,
+    ) -> Poll<io::Result<()>> {
+        Pin::new(self.get_mut().inner.as_mut().unwrap()).poll_read(cx, buf)
+    }
+}
+
+impl<S: AsyncRead + AsyncWrite + Unpin + Send + 'static> AsyncWrite for ShutdownOnDrop<S> {
+    fn poll_write(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        buf: &[u8],
+    ) -> Poll<io::Result<usize>> {
+        Pin::new(self.get_mut().inner.as_mut().unwrap()).poll_write(cx, buf)
+    }
+
+    fn poll_write_vectored(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+        bufs: &[io::IoSlice<'_>],
+    ) -> Poll<io::Result<usize>> {
+        Pin::new(self.get_mut().inner.as_mut().unwrap()).poll_write_vectored(cx, bufs)
+    }
+
+    fn is_write_vectored(&self) -> bool {
+        self.inner.as_ref().unwrap().is_write_vectored()
+    }
+
+    fn poll_flush(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<io::Result<()>> {
+        Pin::new(self.get_mut().inner.as_mut().unwrap()).poll_flush(cx)
+    }
+
+    fn poll_shutdown(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<io::Result<()>> {
+        let this = self.get_mut();
+        let result = Pin::new(this.inner.as_mut().unwrap()).poll_shutdown(cx);
+        if result.is_ready() {
+            this.shutdown_called = true;
+        }
+        result
+    }
+}
+
+impl<S: AsyncRead + AsyncWrite + Unpin + Send + 'static> Drop for ShutdownOnDrop<S> {
+    fn drop(&mut self) {
+        // If shutdown was already called (hyper closed properly), nothing to do.
+        // If not (hyper dropped without shutdown — e.g. H2 close, error, timeout),
+        // spawn a background task to send close_notify / TCP FIN.
+        if !self.shutdown_called {
+            if let Some(mut stream) = self.inner.take() {
+                tokio::spawn(async move {
+                    let _ = tokio::time::timeout(
+                        std::time::Duration::from_secs(2),
+                        tokio::io::AsyncWriteExt::shutdown(&mut stream),
+                    ).await;
+                    // stream is dropped here — all resources freed
+                });
+            }
+        }
+    }
+}

rust/crates/rustproxy-http/src/upstream_selector.rs

@@ -184,6 +184,7 @@ mod tests {
             send_proxy_protocol: None,
             headers: None,
             advanced: None,
+            backend_transport: None,
             priority: None,
         }
     }

rust/crates/rustproxy-metrics/src/collector.rs

@@ -26,6 +26,11 @@ pub struct Metrics {
     pub total_http_requests: u64,
     pub http_requests_per_sec: u64,
     pub http_requests_per_sec_recent: u64,
+    // UDP metrics
+    pub active_udp_sessions: u64,
+    pub total_udp_sessions: u64,
+    pub total_datagrams_in: u64,
+    pub total_datagrams_out: u64,
 }
 
 /// Per-route metrics.
@@ -136,6 +141,12 @@ pub struct MetricsCollector {
     pending_http_requests: AtomicU64,
     http_request_throughput: Mutex<ThroughputTracker>,
 
+    // ── UDP metrics ──
+    active_udp_sessions: AtomicU64,
+    total_udp_sessions: AtomicU64,
+    total_datagrams_in: AtomicU64,
+    total_datagrams_out: AtomicU64,
+
     // ── Lock-free pending throughput counters (hot path) ──
     global_pending_tp_in: AtomicU64,
     global_pending_tp_out: AtomicU64,
@@ -180,6 +191,10 @@ impl MetricsCollector {
             backend_pool_hits: DashMap::new(),
             backend_pool_misses: DashMap::new(),
             backend_h2_failures: DashMap::new(),
+            active_udp_sessions: AtomicU64::new(0),
+            total_udp_sessions: AtomicU64::new(0),
+            total_datagrams_in: AtomicU64::new(0),
+            total_datagrams_out: AtomicU64::new(0),
             total_http_requests: AtomicU64::new(0),
             pending_http_requests: AtomicU64::new(0),
             http_request_throughput: Mutex::new(ThroughputTracker::new(retention_seconds)),
@@ -259,51 +274,87 @@ impl MetricsCollector {
     /// Called per-chunk in the TCP copy loop. Only touches AtomicU64 counters —
     /// no Mutex is taken. The throughput trackers are fed during `sample_all()`.
     pub fn record_bytes(&self, bytes_in: u64, bytes_out: u64, route_id: Option<&str>, source_ip: Option<&str>) {
-        self.total_bytes_in.fetch_add(bytes_in, Ordering::Relaxed);
-        self.total_bytes_out.fetch_add(bytes_out, Ordering::Relaxed);
-
-        // Accumulate into lock-free pending throughput counters
-        self.global_pending_tp_in.fetch_add(bytes_in, Ordering::Relaxed);
-        self.global_pending_tp_out.fetch_add(bytes_out, Ordering::Relaxed);
-
-        if let Some(route_id) = route_id {
-            self.route_bytes_in
-                .entry(route_id.to_string())
-                .or_insert_with(|| AtomicU64::new(0))
-                .fetch_add(bytes_in, Ordering::Relaxed);
-            self.route_bytes_out
-                .entry(route_id.to_string())
-                .or_insert_with(|| AtomicU64::new(0))
-                .fetch_add(bytes_out, Ordering::Relaxed);
-
-            // Accumulate into per-route pending throughput counters (lock-free)
-            let entry = self.route_pending_tp
-                .entry(route_id.to_string())
-                .or_insert_with(|| (AtomicU64::new(0), AtomicU64::new(0)));
-            entry.0.fetch_add(bytes_in, Ordering::Relaxed);
-            entry.1.fetch_add(bytes_out, Ordering::Relaxed);
+        // Short-circuit: only touch counters for the direction that has data.
+        // CountingBody always calls with one direction zero — skipping the zero
+        // direction avoids ~50% of DashMap shard-locked reads per call.
+        if bytes_in > 0 {
+            self.total_bytes_in.fetch_add(bytes_in, Ordering::Relaxed);
+            self.global_pending_tp_in.fetch_add(bytes_in, Ordering::Relaxed);
+        }
+        if bytes_out > 0 {
+            self.total_bytes_out.fetch_add(bytes_out, Ordering::Relaxed);
+            self.global_pending_tp_out.fetch_add(bytes_out, Ordering::Relaxed);
         }
 
+        // Per-route tracking: use get() first (zero-alloc fast path for existing entries),
+        // fall back to entry() with to_string() only on the rare first-chunk miss.
+        if let Some(route_id) = route_id {
+            if bytes_in > 0 {
+                if let Some(counter) = self.route_bytes_in.get(route_id) {
+                    counter.fetch_add(bytes_in, Ordering::Relaxed);
+                } else {
+                    self.route_bytes_in.entry(route_id.to_string())
+                        .or_insert_with(|| AtomicU64::new(0))
+                        .fetch_add(bytes_in, Ordering::Relaxed);
+                }
+            }
+            if bytes_out > 0 {
+                if let Some(counter) = self.route_bytes_out.get(route_id) {
+                    counter.fetch_add(bytes_out, Ordering::Relaxed);
+                } else {
+                    self.route_bytes_out.entry(route_id.to_string())
+                        .or_insert_with(|| AtomicU64::new(0))
+                        .fetch_add(bytes_out, Ordering::Relaxed);
+                }
+            }
+
+            // Accumulate into per-route pending throughput counters (lock-free)
+            if let Some(entry) = self.route_pending_tp.get(route_id) {
+                if bytes_in > 0 { entry.0.fetch_add(bytes_in, Ordering::Relaxed); }
+                if bytes_out > 0 { entry.1.fetch_add(bytes_out, Ordering::Relaxed); }
+            } else {
+                let entry = self.route_pending_tp.entry(route_id.to_string())
+                    .or_insert_with(|| (AtomicU64::new(0), AtomicU64::new(0)));
+                if bytes_in > 0 { entry.0.fetch_add(bytes_in, Ordering::Relaxed); }
+                if bytes_out > 0 { entry.1.fetch_add(bytes_out, Ordering::Relaxed); }
+            }
+        }
+
+        // Per-IP tracking: same get()-first pattern to avoid String allocation on hot path.
         if let Some(ip) = source_ip {
             // Only record per-IP stats if the IP still has active connections.
             // This prevents orphaned entries when record_bytes races with
             // connection_closed (which evicts all per-IP data on last close).
             if self.ip_connections.contains_key(ip) {
-                self.ip_bytes_in
-                    .entry(ip.to_string())
-                    .or_insert_with(|| AtomicU64::new(0))
-                    .fetch_add(bytes_in, Ordering::Relaxed);
-                self.ip_bytes_out
-                    .entry(ip.to_string())
-                    .or_insert_with(|| AtomicU64::new(0))
-                    .fetch_add(bytes_out, Ordering::Relaxed);
+                if bytes_in > 0 {
+                    if let Some(counter) = self.ip_bytes_in.get(ip) {
+                        counter.fetch_add(bytes_in, Ordering::Relaxed);
+                    } else {
+                        self.ip_bytes_in.entry(ip.to_string())
+                            .or_insert_with(|| AtomicU64::new(0))
+                            .fetch_add(bytes_in, Ordering::Relaxed);
+                    }
+                }
+                if bytes_out > 0 {
+                    if let Some(counter) = self.ip_bytes_out.get(ip) {
+                        counter.fetch_add(bytes_out, Ordering::Relaxed);
+                    } else {
+                        self.ip_bytes_out.entry(ip.to_string())
+                            .or_insert_with(|| AtomicU64::new(0))
+                            .fetch_add(bytes_out, Ordering::Relaxed);
+                    }
+                }
 
                 // Accumulate into per-IP pending throughput counters (lock-free)
-                let entry = self.ip_pending_tp
-                    .entry(ip.to_string())
-                    .or_insert_with(|| (AtomicU64::new(0), AtomicU64::new(0)));
-                entry.0.fetch_add(bytes_in, Ordering::Relaxed);
-                entry.1.fetch_add(bytes_out, Ordering::Relaxed);
+                if let Some(entry) = self.ip_pending_tp.get(ip) {
+                    if bytes_in > 0 { entry.0.fetch_add(bytes_in, Ordering::Relaxed); }
+                    if bytes_out > 0 { entry.1.fetch_add(bytes_out, Ordering::Relaxed); }
+                } else {
+                    let entry = self.ip_pending_tp.entry(ip.to_string())
+                        .or_insert_with(|| (AtomicU64::new(0), AtomicU64::new(0)));
+                    if bytes_in > 0 { entry.0.fetch_add(bytes_in, Ordering::Relaxed); }
+                    if bytes_out > 0 { entry.1.fetch_add(bytes_out, Ordering::Relaxed); }
+                }
             }
         }
     }
@@ -314,6 +365,29 @@ impl MetricsCollector {
         self.pending_http_requests.fetch_add(1, Ordering::Relaxed);
     }
 
+    // ── UDP session recording methods ──
+
+    /// Record a new UDP session opened.
+    pub fn udp_session_opened(&self) {
+        self.active_udp_sessions.fetch_add(1, Ordering::Relaxed);
+        self.total_udp_sessions.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Record a UDP session closed.
+    pub fn udp_session_closed(&self) {
+        self.active_udp_sessions.fetch_sub(1, Ordering::Relaxed);
+    }
+
+    /// Record a UDP datagram (inbound or outbound).
+    pub fn record_datagram_in(&self) {
+        self.total_datagrams_in.fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Record an outbound UDP datagram.
+    pub fn record_datagram_out(&self) {
+        self.total_datagrams_out.fetch_add(1, Ordering::Relaxed);
+    }
+
     // ── Per-backend recording methods ──
 
     /// Record a successful backend connection with its connect duration.
@@ -337,11 +411,24 @@ impl MetricsCollector {
     }
 
     /// Record a backend connection closing.
+    /// Removes all per-backend tracking entries when the active count reaches 0.
     pub fn backend_connection_closed(&self, key: &str) {
         if let Some(counter) = self.backend_active.get(key) {
-            let val = counter.load(Ordering::Relaxed);
-            if val > 0 {
-                counter.fetch_sub(1, Ordering::Relaxed);
+            let prev = counter.fetch_sub(1, Ordering::Relaxed);
+            if prev <= 1 {
+                // Active count reached 0 — clean up all per-backend maps
+                drop(counter); // release DashMap ref before remove
+                self.backend_active.remove(key);
+                self.backend_total.remove(key);
+                self.backend_protocol.remove(key);
+                self.backend_connect_errors.remove(key);
+                self.backend_handshake_errors.remove(key);
+                self.backend_request_errors.remove(key);
+                self.backend_connect_time_us.remove(key);
+                self.backend_connect_count.remove(key);
+                self.backend_pool_hits.remove(key);
+                self.backend_pool_misses.remove(key);
+                self.backend_h2_failures.remove(key);
             }
         }
     }
@@ -733,6 +820,10 @@ impl MetricsCollector {
             total_http_requests: self.total_http_requests.load(Ordering::Relaxed),
             http_requests_per_sec: http_rps,
             http_requests_per_sec_recent: http_rps_recent,
+            active_udp_sessions: self.active_udp_sessions.load(Ordering::Relaxed),
+            total_udp_sessions: self.total_udp_sessions.load(Ordering::Relaxed),
+            total_datagrams_in: self.total_datagrams_in.load(Ordering::Relaxed),
+            total_datagrams_out: self.total_datagrams_out.load(Ordering::Relaxed),
         }
     }
 }
@@ -1135,10 +1226,13 @@ mod tests {
         // No entry created
         assert!(collector.backend_active.get(key).is_none());
 
-        // Open one, close two — should saturate at 0
+        // Open one, close — entries are removed when active count reaches 0
         collector.backend_connection_opened(key, Duration::from_millis(1));
         collector.backend_connection_closed(key);
+        // Entry should be cleaned up (active reached 0)
+        assert!(collector.backend_active.get(key).is_none());
+        // Second close on missing entry is a no-op
         collector.backend_connection_closed(key);
-        assert_eq!(collector.backend_active.get(key).unwrap().load(Ordering::Relaxed), 0);
+        assert!(collector.backend_active.get(key).is_none());
     }
 }

rust/crates/rustproxy-nftables/src/rule_builder.rs

@@ -9,34 +9,36 @@ pub fn build_dnat_rule(
     target_port: u16,
     options: &NfTablesOptions,
 ) -> Vec<String> {
-    let protocol = match options.protocol.as_ref().unwrap_or(&NfTablesProtocol::Tcp) {
-        NfTablesProtocol::Tcp => "tcp",
-        NfTablesProtocol::Udp => "udp",
-        NfTablesProtocol::All => "tcp", // TODO: handle "all"
+    let protocols: Vec<&str> = match options.protocol.as_ref().unwrap_or(&NfTablesProtocol::Tcp) {
+        NfTablesProtocol::Tcp => vec!["tcp"],
+        NfTablesProtocol::Udp => vec!["udp"],
+        NfTablesProtocol::All => vec!["tcp", "udp"],
     };
 
     let mut rules = Vec::new();
 
-    // DNAT rule
-    rules.push(format!(
-        "nft add rule ip {} {} {} dport {} dnat to {}:{}",
-        table_name, chain_name, protocol, source_port, target_host, target_port,
-    ));
-
-    // SNAT rule if preserving source IP is not enabled
-    if !options.preserve_source_ip.unwrap_or(false) {
+    for protocol in &protocols {
+        // DNAT rule
         rules.push(format!(
-            "nft add rule ip {} postrouting {} dport {} masquerade",
-            table_name, protocol, target_port,
+            "nft add rule ip {} {} {} dport {} dnat to {}:{}",
+            table_name, chain_name, protocol, source_port, target_host, target_port,
         ));
-    }
 
-    // Rate limiting
-    if let Some(max_rate) = &options.max_rate {
-        rules.push(format!(
-            "nft add rule ip {} {} {} dport {} limit rate {} accept",
-            table_name, chain_name, protocol, source_port, max_rate,
-        ));
+        // SNAT rule if preserving source IP is not enabled
+        if !options.preserve_source_ip.unwrap_or(false) {
+            rules.push(format!(
+                "nft add rule ip {} postrouting {} dport {} masquerade",
+                table_name, protocol, target_port,
+            ));
+        }
+
+        // Rate limiting
+        if let Some(max_rate) = &options.max_rate {
+            rules.push(format!(
+                "nft add rule ip {} {} {} dport {} limit rate {} accept",
+                table_name, chain_name, protocol, source_port, max_rate,
+            ));
+        }
     }
 
     rules
@@ -120,4 +122,25 @@ mod tests {
         assert_eq!(commands.len(), 1);
         assert!(commands[0].contains("delete table ip rustproxy"));
     }
+
+    #[test]
+    fn test_protocol_all_generates_tcp_and_udp_rules() {
+        let mut options = make_options();
+        options.protocol = Some(NfTablesProtocol::All);
+        let rules = build_dnat_rule("rustproxy", "prerouting", 53, "10.0.0.53", 53, &options);
+        // Should have TCP DNAT + masquerade + UDP DNAT + masquerade = 4 rules
+        assert_eq!(rules.len(), 4);
+        assert!(rules.iter().any(|r| r.contains("tcp dport 53 dnat")));
+        assert!(rules.iter().any(|r| r.contains("udp dport 53 dnat")));
+        assert!(rules.iter().filter(|r| r.contains("masquerade")).count() == 2);
+    }
+
+    #[test]
+    fn test_protocol_udp() {
+        let mut options = make_options();
+        options.protocol = Some(NfTablesProtocol::Udp);
+        let rules = build_dnat_rule("rustproxy", "prerouting", 53, "10.0.0.53", 53, &options);
+        assert!(rules.iter().all(|r| !r.contains("tcp")));
+        assert!(rules.iter().any(|r| r.contains("udp dport 53 dnat")));
+    }
 }

rust/crates/rustproxy-passthrough/Cargo.toml

@@ -24,3 +24,6 @@ tokio-util = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 socket2 = { workspace = true }
+quinn = { workspace = true }
+rcgen = { workspace = true }
+base64 = { workspace = true }

rust/crates/rustproxy-passthrough/src/lib.rs

@@ -1,7 +1,8 @@
 //! # rustproxy-passthrough
 //!
-//! Raw TCP/SNI passthrough engine for RustProxy.
-//! Handles TCP listening, TLS ClientHello SNI extraction, and bidirectional forwarding.
+//! Raw TCP/SNI passthrough engine and UDP listener for RustProxy.
+//! Handles TCP listening, TLS ClientHello SNI extraction, bidirectional forwarding,
+//! and UDP datagram session tracking with forwarding.
 
 pub mod tcp_listener;
 pub mod sni_parser;
@@ -11,6 +12,9 @@ pub mod tls_handler;
 pub mod connection_tracker;
 pub mod socket_relay;
 pub mod socket_opts;
+pub mod udp_session;
+pub mod udp_listener;
+pub mod quic_handler;
 
 pub use tcp_listener::*;
 pub use sni_parser::*;
@@ -20,3 +24,6 @@ pub use tls_handler::*;
 pub use connection_tracker::*;
 pub use socket_relay::*;
 pub use socket_opts::*;
+pub use udp_session::*;
+pub use udp_listener::*;
+pub use quic_handler::*;

rust/crates/rustproxy-passthrough/src/proxy_protocol.rs

@@ -1,4 +1,4 @@
-use std::net::SocketAddr;
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
 use thiserror::Error;
 
 #[derive(Debug, Error)]
@@ -9,9 +9,11 @@ pub enum ProxyProtocolError {
     UnsupportedVersion,
     #[error("Parse error: {0}")]
     Parse(String),
+    #[error("Incomplete header: need {0} bytes, got {1}")]
+    Incomplete(usize, usize),
 }
 
-/// Parsed PROXY protocol v1 header.
+/// Parsed PROXY protocol header (v1 or v2).
 #[derive(Debug, Clone)]
 pub struct ProxyProtocolHeader {
     pub source_addr: SocketAddr,
@@ -24,14 +26,29 @@ pub struct ProxyProtocolHeader {
 pub enum ProxyProtocol {
     Tcp4,
     Tcp6,
+    Udp4,
+    Udp6,
     Unknown,
 }
 
+/// Transport type for PROXY v2 header generation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProxyV2Transport {
+    Stream,   // TCP
+    Datagram, // UDP
+}
+
+/// PROXY protocol v2 signature (12 bytes).
+const PROXY_V2_SIGNATURE: [u8; 12] = [
+    0x0D, 0x0A, 0x0D, 0x0A, 0x00, 0x0D, 0x0A, 0x51, 0x55, 0x49, 0x54, 0x0A,
+];
+
+// ===== v1 (text format) =====
+
 /// Parse a PROXY protocol v1 header from data.
 ///
 /// Format: `PROXY TCP4 <src_ip> <dst_ip> <src_port> <dst_port>\r\n`
 pub fn parse_v1(data: &[u8]) -> Result<(ProxyProtocolHeader, usize), ProxyProtocolError> {
-    // Find the end of the header line
     let line_end = data
         .windows(2)
         .position(|w| w == b"\r\n")
@@ -56,10 +73,10 @@ pub fn parse_v1(data: &[u8]) -> Result<(ProxyProtocolHeader, usize), ProxyProtoc
         _ => return Err(ProxyProtocolError::UnsupportedVersion),
     };
 
-    let src_ip: std::net::IpAddr = parts[2]
+    let src_ip: IpAddr = parts[2]
         .parse()
         .map_err(|_| ProxyProtocolError::Parse("Invalid source IP".to_string()))?;
-    let dst_ip: std::net::IpAddr = parts[3]
+    let dst_ip: IpAddr = parts[3]
         .parse()
         .map_err(|_| ProxyProtocolError::Parse("Invalid destination IP".to_string()))?;
     let src_port: u16 = parts[4]
@@ -75,7 +92,6 @@ pub fn parse_v1(data: &[u8]) -> Result<(ProxyProtocolHeader, usize), ProxyProtoc
         protocol,
     };
 
-    // Consumed bytes = line + \r\n
     Ok((header, line_end + 2))
 }
 
@@ -97,10 +113,219 @@ pub fn is_proxy_protocol_v1(data: &[u8]) -> bool {
     data.starts_with(b"PROXY ")
 }
 
+// ===== v2 (binary format) =====
+
+/// Check if data starts with a PROXY protocol v2 header.
+pub fn is_proxy_protocol_v2(data: &[u8]) -> bool {
+    data.len() >= 12 && data[..12] == PROXY_V2_SIGNATURE
+}
+
+/// Parse a PROXY protocol v2 binary header.
+///
+/// Binary format:
+/// - [0..12]  signature (12 bytes)
+/// - [12]     version (high nibble) + command (low nibble)
+/// - [13]     address family (high nibble) + transport (low nibble)
+/// - [14..16] address block length (big-endian u16)
+/// - [16..]   address block (variable, depends on family)
+pub fn parse_v2(data: &[u8]) -> Result<(ProxyProtocolHeader, usize), ProxyProtocolError> {
+    if data.len() < 16 {
+        return Err(ProxyProtocolError::Incomplete(16, data.len()));
+    }
+
+    // Validate signature
+    if data[..12] != PROXY_V2_SIGNATURE {
+        return Err(ProxyProtocolError::InvalidHeader);
+    }
+
+    // Version (high nibble of byte 12) must be 0x2
+    let version = (data[12] >> 4) & 0x0F;
+    if version != 2 {
+        return Err(ProxyProtocolError::UnsupportedVersion);
+    }
+
+    // Command (low nibble of byte 12)
+    let command = data[12] & 0x0F;
+    // 0x0 = LOCAL, 0x1 = PROXY
+    if command > 1 {
+        return Err(ProxyProtocolError::Parse(format!("Unknown command: {}", command)));
+    }
+
+    // Address family (high nibble) + transport (low nibble) of byte 13
+    let family = (data[13] >> 4) & 0x0F;
+    let transport = data[13] & 0x0F;
+
+    // Address block length
+    let addr_len = u16::from_be_bytes([data[14], data[15]]) as usize;
+    let total_len = 16 + addr_len;
+
+    if data.len() < total_len {
+        return Err(ProxyProtocolError::Incomplete(total_len, data.len()));
+    }
+
+    // LOCAL command: no real addresses, return unspecified
+    if command == 0 {
+        return Ok((
+            ProxyProtocolHeader {
+                source_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
+                dest_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
+                protocol: ProxyProtocol::Unknown,
+            },
+            total_len,
+        ));
+    }
+
+    // PROXY command: parse addresses based on family + transport
+    let addr_block = &data[16..16 + addr_len];
+
+    match (family, transport) {
+        // AF_INET (0x1) + STREAM (0x1) = TCP4
+        (0x1, 0x1) => {
+            if addr_len < 12 {
+                return Err(ProxyProtocolError::Parse("IPv4 address block too short".to_string()));
+            }
+            let src_ip = Ipv4Addr::new(addr_block[0], addr_block[1], addr_block[2], addr_block[3]);
+            let dst_ip = Ipv4Addr::new(addr_block[4], addr_block[5], addr_block[6], addr_block[7]);
+            let src_port = u16::from_be_bytes([addr_block[8], addr_block[9]]);
+            let dst_port = u16::from_be_bytes([addr_block[10], addr_block[11]]);
+            Ok((
+                ProxyProtocolHeader {
+                    source_addr: SocketAddr::new(IpAddr::V4(src_ip), src_port),
+                    dest_addr: SocketAddr::new(IpAddr::V4(dst_ip), dst_port),
+                    protocol: ProxyProtocol::Tcp4,
+                },
+                total_len,
+            ))
+        }
+        // AF_INET (0x1) + DGRAM (0x2) = UDP4
+        (0x1, 0x2) => {
+            if addr_len < 12 {
+                return Err(ProxyProtocolError::Parse("IPv4 address block too short".to_string()));
+            }
+            let src_ip = Ipv4Addr::new(addr_block[0], addr_block[1], addr_block[2], addr_block[3]);
+            let dst_ip = Ipv4Addr::new(addr_block[4], addr_block[5], addr_block[6], addr_block[7]);
+            let src_port = u16::from_be_bytes([addr_block[8], addr_block[9]]);
+            let dst_port = u16::from_be_bytes([addr_block[10], addr_block[11]]);
+            Ok((
+                ProxyProtocolHeader {
+                    source_addr: SocketAddr::new(IpAddr::V4(src_ip), src_port),
+                    dest_addr: SocketAddr::new(IpAddr::V4(dst_ip), dst_port),
+                    protocol: ProxyProtocol::Udp4,
+                },
+                total_len,
+            ))
+        }
+        // AF_INET6 (0x2) + STREAM (0x1) = TCP6
+        (0x2, 0x1) => {
+            if addr_len < 36 {
+                return Err(ProxyProtocolError::Parse("IPv6 address block too short".to_string()));
+            }
+            let src_ip = Ipv6Addr::from(<[u8; 16]>::try_from(&addr_block[0..16]).unwrap());
+            let dst_ip = Ipv6Addr::from(<[u8; 16]>::try_from(&addr_block[16..32]).unwrap());
+            let src_port = u16::from_be_bytes([addr_block[32], addr_block[33]]);
+            let dst_port = u16::from_be_bytes([addr_block[34], addr_block[35]]);
+            Ok((
+                ProxyProtocolHeader {
+                    source_addr: SocketAddr::new(IpAddr::V6(src_ip), src_port),
+                    dest_addr: SocketAddr::new(IpAddr::V6(dst_ip), dst_port),
+                    protocol: ProxyProtocol::Tcp6,
+                },
+                total_len,
+            ))
+        }
+        // AF_INET6 (0x2) + DGRAM (0x2) = UDP6
+        (0x2, 0x2) => {
+            if addr_len < 36 {
+                return Err(ProxyProtocolError::Parse("IPv6 address block too short".to_string()));
+            }
+            let src_ip = Ipv6Addr::from(<[u8; 16]>::try_from(&addr_block[0..16]).unwrap());
+            let dst_ip = Ipv6Addr::from(<[u8; 16]>::try_from(&addr_block[16..32]).unwrap());
+            let src_port = u16::from_be_bytes([addr_block[32], addr_block[33]]);
+            let dst_port = u16::from_be_bytes([addr_block[34], addr_block[35]]);
+            Ok((
+                ProxyProtocolHeader {
+                    source_addr: SocketAddr::new(IpAddr::V6(src_ip), src_port),
+                    dest_addr: SocketAddr::new(IpAddr::V6(dst_ip), dst_port),
+                    protocol: ProxyProtocol::Udp6,
+                },
+                total_len,
+            ))
+        }
+        // AF_UNSPEC or unknown
+        (0x0, _) => Ok((
+            ProxyProtocolHeader {
+                source_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
+                dest_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
+                protocol: ProxyProtocol::Unknown,
+            },
+            total_len,
+        )),
+        _ => Err(ProxyProtocolError::Parse(format!(
+            "Unsupported family/transport: 0x{:X}{:X}",
+            family, transport
+        ))),
+    }
+}
+
+/// Generate a PROXY protocol v2 binary header.
+pub fn generate_v2(
+    source: &SocketAddr,
+    dest: &SocketAddr,
+    transport: ProxyV2Transport,
+) -> Vec<u8> {
+    let transport_nibble: u8 = match transport {
+        ProxyV2Transport::Stream => 0x1,
+        ProxyV2Transport::Datagram => 0x2,
+    };
+
+    match (source.ip(), dest.ip()) {
+        (IpAddr::V4(src_ip), IpAddr::V4(dst_ip)) => {
+            let mut buf = Vec::with_capacity(28);
+            buf.extend_from_slice(&PROXY_V2_SIGNATURE);
+            buf.push(0x21); // version 2, PROXY command
+            buf.push(0x10 | transport_nibble); // AF_INET + transport
+            buf.extend_from_slice(&12u16.to_be_bytes()); // addr block length
+            buf.extend_from_slice(&src_ip.octets());
+            buf.extend_from_slice(&dst_ip.octets());
+            buf.extend_from_slice(&source.port().to_be_bytes());
+            buf.extend_from_slice(&dest.port().to_be_bytes());
+            buf
+        }
+        (IpAddr::V6(src_ip), IpAddr::V6(dst_ip)) => {
+            let mut buf = Vec::with_capacity(52);
+            buf.extend_from_slice(&PROXY_V2_SIGNATURE);
+            buf.push(0x21); // version 2, PROXY command
+            buf.push(0x20 | transport_nibble); // AF_INET6 + transport
+            buf.extend_from_slice(&36u16.to_be_bytes()); // addr block length
+            buf.extend_from_slice(&src_ip.octets());
+            buf.extend_from_slice(&dst_ip.octets());
+            buf.extend_from_slice(&source.port().to_be_bytes());
+            buf.extend_from_slice(&dest.port().to_be_bytes());
+            buf
+        }
+        // Mixed IPv4/IPv6: map IPv4 to IPv6-mapped address
+        _ => {
+            let src_v6 = match source.ip() {
+                IpAddr::V4(v4) => v4.to_ipv6_mapped(),
+                IpAddr::V6(v6) => v6,
+            };
+            let dst_v6 = match dest.ip() {
+                IpAddr::V4(v4) => v4.to_ipv6_mapped(),
+                IpAddr::V6(v6) => v6,
+            };
+            let src6 = SocketAddr::new(IpAddr::V6(src_v6), source.port());
+            let dst6 = SocketAddr::new(IpAddr::V6(dst_v6), dest.port());
+            generate_v2(&src6, &dst6, transport)
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    // ===== v1 tests =====
+
     #[test]
     fn test_parse_v1_tcp4() {
         let header = b"PROXY TCP4 192.168.1.100 10.0.0.1 12345 443\r\n";
@@ -126,4 +351,130 @@ mod tests {
         assert!(is_proxy_protocol_v1(b"PROXY TCP4 ..."));
         assert!(!is_proxy_protocol_v1(b"GET / HTTP/1.1"));
     }
+
+    // ===== v2 tests =====
+
+    #[test]
+    fn test_is_proxy_protocol_v2() {
+        assert!(is_proxy_protocol_v2(&PROXY_V2_SIGNATURE));
+        assert!(!is_proxy_protocol_v2(b"PROXY TCP4 ..."));
+        assert!(!is_proxy_protocol_v2(b"short"));
+    }
+
+    #[test]
+    fn test_parse_v2_tcp4() {
+        let source: SocketAddr = "198.51.100.10:54321".parse().unwrap();
+        let dest: SocketAddr = "203.0.113.25:8443".parse().unwrap();
+        let header = generate_v2(&source, &dest, ProxyV2Transport::Stream);
+
+        assert_eq!(header.len(), 28);
+        let (parsed, consumed) = parse_v2(&header).unwrap();
+        assert_eq!(consumed, 28);
+        assert_eq!(parsed.protocol, ProxyProtocol::Tcp4);
+        assert_eq!(parsed.source_addr, source);
+        assert_eq!(parsed.dest_addr, dest);
+    }
+
+    #[test]
+    fn test_parse_v2_udp4() {
+        let source: SocketAddr = "10.0.0.1:12345".parse().unwrap();
+        let dest: SocketAddr = "10.0.0.2:53".parse().unwrap();
+        let header = generate_v2(&source, &dest, ProxyV2Transport::Datagram);
+
+        assert_eq!(header.len(), 28);
+        assert_eq!(header[13], 0x12); // AF_INET + DGRAM
+
+        let (parsed, consumed) = parse_v2(&header).unwrap();
+        assert_eq!(consumed, 28);
+        assert_eq!(parsed.protocol, ProxyProtocol::Udp4);
+        assert_eq!(parsed.source_addr, source);
+        assert_eq!(parsed.dest_addr, dest);
+    }
+
+    #[test]
+    fn test_parse_v2_tcp6() {
+        let source: SocketAddr = "[2001:db8::1]:54321".parse().unwrap();
+        let dest: SocketAddr = "[2001:db8::2]:443".parse().unwrap();
+        let header = generate_v2(&source, &dest, ProxyV2Transport::Stream);
+
+        assert_eq!(header.len(), 52);
+        assert_eq!(header[13], 0x21); // AF_INET6 + STREAM
+
+        let (parsed, consumed) = parse_v2(&header).unwrap();
+        assert_eq!(consumed, 52);
+        assert_eq!(parsed.protocol, ProxyProtocol::Tcp6);
+        assert_eq!(parsed.source_addr, source);
+        assert_eq!(parsed.dest_addr, dest);
+    }
+
+    #[test]
+    fn test_generate_v2_tcp4_byte_layout() {
+        let source: SocketAddr = "1.2.3.4:1000".parse().unwrap();
+        let dest: SocketAddr = "5.6.7.8:443".parse().unwrap();
+        let header = generate_v2(&source, &dest, ProxyV2Transport::Stream);
+
+        assert_eq!(&header[0..12], &PROXY_V2_SIGNATURE);
+        assert_eq!(header[12], 0x21); // v2, PROXY
+        assert_eq!(header[13], 0x11); // AF_INET, STREAM
+        assert_eq!(u16::from_be_bytes([header[14], header[15]]), 12); // addr len
+        assert_eq!(&header[16..20], &[1, 2, 3, 4]); // src ip
+        assert_eq!(&header[20..24], &[5, 6, 7, 8]); // dst ip
+        assert_eq!(u16::from_be_bytes([header[24], header[25]]), 1000); // src port
+        assert_eq!(u16::from_be_bytes([header[26], header[27]]), 443); // dst port
+    }
+
+    #[test]
+    fn test_generate_v2_udp4_byte_layout() {
+        let source: SocketAddr = "10.0.0.1:5000".parse().unwrap();
+        let dest: SocketAddr = "10.0.0.2:53".parse().unwrap();
+        let header = generate_v2(&source, &dest, ProxyV2Transport::Datagram);
+
+        assert_eq!(header[12], 0x21); // v2, PROXY
+        assert_eq!(header[13], 0x12); // AF_INET, DGRAM (UDP)
+    }
+
+    #[test]
+    fn test_parse_v2_local_command() {
+        // Build a LOCAL command header (no addresses)
+        let mut header = Vec::new();
+        header.extend_from_slice(&PROXY_V2_SIGNATURE);
+        header.push(0x20); // v2, LOCAL
+        header.push(0x00); // AF_UNSPEC
+        header.extend_from_slice(&0u16.to_be_bytes()); // 0-length address block
+
+        let (parsed, consumed) = parse_v2(&header).unwrap();
+        assert_eq!(consumed, 16);
+        assert_eq!(parsed.protocol, ProxyProtocol::Unknown);
+        assert_eq!(parsed.source_addr.port(), 0);
+    }
+
+    #[test]
+    fn test_parse_v2_incomplete() {
+        let data = &PROXY_V2_SIGNATURE[..8]; // only 8 bytes
+        assert!(parse_v2(data).is_err());
+    }
+
+    #[test]
+    fn test_parse_v2_wrong_version() {
+        let mut header = Vec::new();
+        header.extend_from_slice(&PROXY_V2_SIGNATURE);
+        header.push(0x11); // version 1, not 2
+        header.push(0x11);
+        header.extend_from_slice(&12u16.to_be_bytes());
+        header.extend_from_slice(&[0u8; 12]);
+        assert!(matches!(parse_v2(&header), Err(ProxyProtocolError::UnsupportedVersion)));
+    }
+
+    #[test]
+    fn test_v2_roundtrip_with_trailing_data() {
+        let source: SocketAddr = "192.168.1.1:8080".parse().unwrap();
+        let dest: SocketAddr = "10.0.0.1:443".parse().unwrap();
+        let mut data = generate_v2(&source, &dest, ProxyV2Transport::Stream);
+        data.extend_from_slice(b"GET / HTTP/1.1\r\n"); // trailing app data
+
+        let (parsed, consumed) = parse_v2(&data).unwrap();
+        assert_eq!(consumed, 28);
+        assert_eq!(parsed.source_addr, source);
+        assert_eq!(&data[consumed..], b"GET / HTTP/1.1\r\n");
+    }
 }

rust/crates/rustproxy-passthrough/src/quic_handler.rs

@@ -0,0 +1,700 @@
+//! QUIC connection handling.
+//!
+//! Manages QUIC endpoints (via quinn), accepts connections, and either:
+//! - Forwards streams bidirectionally to TCP backends (QUIC termination)
+//! - Dispatches to H3ProxyService for HTTP/3 handling (Phase 5)
+//!
+//! When `proxy_ips` is configured, a UDP relay layer intercepts PROXY protocol v2
+//! headers before they reach quinn, extracting real client IPs for attribution.
+
+use std::net::{IpAddr, SocketAddr};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::UdpSocket;
+use tokio::task::JoinHandle;
+
+use arc_swap::ArcSwap;
+use dashmap::DashMap;
+use quinn::{Endpoint, ServerConfig as QuinnServerConfig};
+use rustls::ServerConfig as RustlsServerConfig;
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, info, warn};
+
+use rustproxy_config::{RouteConfig, TransportProtocol};
+use rustproxy_metrics::MetricsCollector;
+use rustproxy_routing::{MatchContext, RouteManager};
+
+use rustproxy_http::h3_service::H3ProxyService;
+
+use crate::connection_tracker::ConnectionTracker;
+
+/// Create a QUIC server endpoint on the given port with the provided TLS config.
+///
+/// The TLS config must have ALPN protocols set (e.g., `h3` for HTTP/3).
+pub fn create_quic_endpoint(
+    port: u16,
+    tls_config: Arc<RustlsServerConfig>,
+) -> anyhow::Result<Endpoint> {
+    let quic_crypto = quinn::crypto::rustls::QuicServerConfig::try_from(tls_config)
+        .map_err(|e| anyhow::anyhow!("Failed to create QUIC crypto config: {}", e))?;
+    let server_config = QuinnServerConfig::with_crypto(Arc::new(quic_crypto));
+
+    let socket = std::net::UdpSocket::bind(SocketAddr::from(([0, 0, 0, 0], port)))?;
+    let endpoint = Endpoint::new(
+        quinn::EndpointConfig::default(),
+        Some(server_config),
+        socket,
+        quinn::default_runtime()
+            .ok_or_else(|| anyhow::anyhow!("No async runtime for quinn"))?,
+    )?;
+
+    info!("QUIC endpoint listening on port {}", port);
+    Ok(endpoint)
+}
+
+// ===== PROXY protocol relay for QUIC =====
+
+/// Result of creating a QUIC endpoint with a PROXY protocol relay layer.
+pub struct QuicProxyRelay {
+    /// The quinn endpoint (bound to 127.0.0.1:ephemeral).
+    pub endpoint: Endpoint,
+    /// The relay recv loop task handle.
+    pub relay_task: JoinHandle<()>,
+    /// Maps relay socket local addr → real client SocketAddr (from PROXY v2).
+    /// Consulted by `quic_accept_loop` to resolve real client IPs.
+    pub real_client_map: Arc<DashMap<SocketAddr, SocketAddr>>,
+}
+
+/// A single relay session for forwarding datagrams between an external source
+/// and the internal quinn endpoint.
+struct RelaySession {
+    socket: Arc<UdpSocket>,
+    last_activity: AtomicU64,
+    return_task: JoinHandle<()>,
+    cancel: CancellationToken,
+}
+
+/// Create a QUIC endpoint with a PROXY protocol v2 relay layer.
+///
+/// Instead of giving the external socket to quinn, we:
+/// 1. Bind a raw UDP socket on 0.0.0.0:port (external)
+/// 2. Bind quinn on 127.0.0.1:0 (internal, ephemeral)
+/// 3. Run a relay loop that filters PROXY v2 headers and forwards datagrams
+///
+/// Only used when `proxy_ips` is non-empty.
+pub fn create_quic_endpoint_with_proxy_relay(
+    port: u16,
+    tls_config: Arc<RustlsServerConfig>,
+    proxy_ips: Arc<Vec<IpAddr>>,
+    cancel: CancellationToken,
+) -> anyhow::Result<QuicProxyRelay> {
+    // Bind external socket on the real port
+    let external_socket = std::net::UdpSocket::bind(SocketAddr::from(([0, 0, 0, 0], port)))?;
+    external_socket.set_nonblocking(true)?;
+    let external_socket = Arc::new(
+        UdpSocket::from_std(external_socket)
+            .map_err(|e| anyhow::anyhow!("Failed to wrap external socket: {}", e))?,
+    );
+
+    // Bind quinn on localhost ephemeral port
+    let internal_socket = std::net::UdpSocket::bind("127.0.0.1:0")?;
+    let quinn_internal_addr = internal_socket.local_addr()?;
+
+    let quic_crypto = quinn::crypto::rustls::QuicServerConfig::try_from(tls_config)
+        .map_err(|e| anyhow::anyhow!("Failed to create QUIC crypto config: {}", e))?;
+    let server_config = QuinnServerConfig::with_crypto(Arc::new(quic_crypto));
+
+    let endpoint = Endpoint::new(
+        quinn::EndpointConfig::default(),
+        Some(server_config),
+        internal_socket,
+        quinn::default_runtime()
+            .ok_or_else(|| anyhow::anyhow!("No async runtime for quinn"))?,
+    )?;
+
+    let real_client_map = Arc::new(DashMap::new());
+
+    let relay_task = tokio::spawn(quic_proxy_relay_loop(
+        external_socket,
+        quinn_internal_addr,
+        proxy_ips,
+        Arc::clone(&real_client_map),
+        cancel,
+    ));
+
+    info!("QUIC endpoint with PROXY relay on port {} (quinn internal: {})", port, quinn_internal_addr);
+    Ok(QuicProxyRelay { endpoint, relay_task, real_client_map })
+}
+
+/// Main relay loop: reads datagrams from the external socket, filters PROXY v2
+/// headers from trusted proxy IPs, and forwards everything else to quinn via
+/// per-session relay sockets.
+async fn quic_proxy_relay_loop(
+    external_socket: Arc<UdpSocket>,
+    quinn_internal_addr: SocketAddr,
+    proxy_ips: Arc<Vec<IpAddr>>,
+    real_client_map: Arc<DashMap<SocketAddr, SocketAddr>>,
+    cancel: CancellationToken,
+) {
+    // Maps external source addr → real client addr (from PROXY v2 headers)
+    let proxy_addr_map: DashMap<SocketAddr, SocketAddr> = DashMap::new();
+    // Maps external source addr → relay session
+    let relay_sessions: DashMap<SocketAddr, Arc<RelaySession>> = DashMap::new();
+    let epoch = Instant::now();
+    let mut buf = vec![0u8; 65535];
+
+    // Inline cleanup: periodically scan relay_sessions for stale entries
+    let mut last_cleanup = Instant::now();
+    let cleanup_interval = std::time::Duration::from_secs(30);
+    let session_timeout_ms: u64 = 120_000;
+
+    loop {
+        let (len, src_addr) = tokio::select! {
+            _ = cancel.cancelled() => {
+                debug!("QUIC proxy relay loop cancelled");
+                break;
+            }
+            result = external_socket.recv_from(&mut buf) => {
+                match result {
+                    Ok(r) => r,
+                    Err(e) => {
+                        warn!("QUIC proxy relay recv error: {}", e);
+                        continue;
+                    }
+                }
+            }
+        };
+
+        let datagram = &buf[..len];
+
+        // PROXY v2 handling: only on first datagram from a trusted proxy IP
+        // (before a relay session exists for this source)
+        if proxy_ips.contains(&src_addr.ip()) && relay_sessions.get(&src_addr).is_none() {
+            if crate::proxy_protocol::is_proxy_protocol_v2(datagram) {
+                match crate::proxy_protocol::parse_v2(datagram) {
+                    Ok((header, _consumed)) => {
+                        debug!("QUIC PROXY v2 from {}: real client {}", src_addr, header.source_addr);
+                        proxy_addr_map.insert(src_addr, header.source_addr);
+                        continue; // consume the PROXY v2 datagram
+                    }
+                    Err(e) => {
+                        debug!("QUIC proxy relay: failed to parse PROXY v2 from {}: {}", src_addr, e);
+                    }
+                }
+            }
+        }
+
+        // Determine real client address
+        let real_client = proxy_addr_map.get(&src_addr)
+            .map(|r| *r)
+            .unwrap_or(src_addr);
+
+        // Get or create relay session for this external source
+        let session = match relay_sessions.get(&src_addr) {
+            Some(s) => {
+                s.last_activity.store(epoch.elapsed().as_millis() as u64, Ordering::Relaxed);
+                Arc::clone(s.value())
+            }
+            None => {
+                // Create new relay socket connected to quinn's internal address
+                let relay_socket = match UdpSocket::bind("127.0.0.1:0").await {
+                    Ok(s) => s,
+                    Err(e) => {
+                        warn!("QUIC relay: failed to bind relay socket: {}", e);
+                        continue;
+                    }
+                };
+                if let Err(e) = relay_socket.connect(quinn_internal_addr).await {
+                    warn!("QUIC relay: failed to connect relay socket to {}: {}", quinn_internal_addr, e);
+                    continue;
+                }
+                let relay_local_addr = match relay_socket.local_addr() {
+                    Ok(a) => a,
+                    Err(e) => {
+                        warn!("QUIC relay: failed to get relay socket local addr: {}", e);
+                        continue;
+                    }
+                };
+                let relay_socket = Arc::new(relay_socket);
+
+                // Store the real client mapping for the QUIC accept loop
+                real_client_map.insert(relay_local_addr, real_client);
+
+                // Spawn return-path relay: quinn -> external socket -> original source
+                let session_cancel = cancel.child_token();
+                let return_task = tokio::spawn(relay_return_path(
+                    Arc::clone(&relay_socket),
+                    Arc::clone(&external_socket),
+                    src_addr,
+                    session_cancel.child_token(),
+                ));
+
+                let session = Arc::new(RelaySession {
+                    socket: relay_socket,
+                    last_activity: AtomicU64::new(epoch.elapsed().as_millis() as u64),
+                    return_task,
+                    cancel: session_cancel,
+                });
+
+                relay_sessions.insert(src_addr, Arc::clone(&session));
+                debug!("QUIC relay: new session for {} (relay {}), real client {}",
+                    src_addr, relay_local_addr, real_client);
+
+                session
+            }
+        };
+
+        // Forward datagram to quinn via the relay socket
+        if let Err(e) = session.socket.send(datagram).await {
+            debug!("QUIC relay: forward error to quinn for {}: {}", src_addr, e);
+        }
+
+        // Periodic cleanup of stale relay sessions
+        if last_cleanup.elapsed() >= cleanup_interval {
+            last_cleanup = Instant::now();
+            let now_ms = epoch.elapsed().as_millis() as u64;
+            let stale_keys: Vec<SocketAddr> = relay_sessions.iter()
+                .filter(|entry| {
+                    let age = now_ms.saturating_sub(entry.value().last_activity.load(Ordering::Relaxed));
+                    age > session_timeout_ms
+                })
+                .map(|entry| *entry.key())
+                .collect();
+
+            for key in stale_keys {
+                if let Some((_, session)) = relay_sessions.remove(&key) {
+                    session.cancel.cancel();
+                    session.return_task.abort();
+                    // Clean up real_client_map entry
+                    if let Ok(addr) = session.socket.local_addr() {
+                        real_client_map.remove(&addr);
+                    }
+                    proxy_addr_map.remove(&key);
+                    debug!("QUIC relay: cleaned up stale session for {}", key);
+                }
+            }
+
+            // Also clean orphaned proxy_addr_map entries (PROXY header received
+            // but no relay session was ever created, e.g. client never sent data)
+            let orphaned: Vec<SocketAddr> = proxy_addr_map.iter()
+                .filter(|entry| relay_sessions.get(entry.key()).is_none())
+                .map(|entry| *entry.key())
+                .collect();
+            for key in orphaned {
+                proxy_addr_map.remove(&key);
+                debug!("QUIC relay: cleaned up orphaned proxy_addr_map entry for {}", key);
+            }
+        }
+    }
+
+    // Shutdown: cancel all relay sessions
+    for entry in relay_sessions.iter() {
+        entry.value().cancel.cancel();
+        entry.value().return_task.abort();
+    }
+}
+
+/// Return-path relay: receives datagrams from quinn (via the relay socket)
+/// and forwards them back to the external client through the external socket.
+async fn relay_return_path(
+    relay_socket: Arc<UdpSocket>,
+    external_socket: Arc<UdpSocket>,
+    external_src_addr: SocketAddr,
+    cancel: CancellationToken,
+) {
+    let mut buf = vec![0u8; 65535];
+    loop {
+        let len = tokio::select! {
+            _ = cancel.cancelled() => break,
+            result = relay_socket.recv(&mut buf) => {
+                match result {
+                    Ok(len) => len,
+                    Err(e) => {
+                        debug!("QUIC relay return recv error for {}: {}", external_src_addr, e);
+                        break;
+                    }
+                }
+            }
+        };
+
+        if let Err(e) = external_socket.send_to(&buf[..len], external_src_addr).await {
+            debug!("QUIC relay return send error to {}: {}", external_src_addr, e);
+            break;
+        }
+    }
+}
+
+// ===== QUIC accept loop =====
+
+/// Run the QUIC accept loop for a single endpoint.
+///
+/// Accepts incoming QUIC connections and spawns a task per connection.
+/// When `real_client_map` is provided, it is consulted to resolve real client
+/// IPs from PROXY protocol v2 headers (relay socket addr → real client addr).
+pub async fn quic_accept_loop(
+    endpoint: Endpoint,
+    port: u16,
+    route_manager: Arc<ArcSwap<RouteManager>>,
+    metrics: Arc<MetricsCollector>,
+    conn_tracker: Arc<ConnectionTracker>,
+    cancel: CancellationToken,
+    h3_service: Option<Arc<H3ProxyService>>,
+    real_client_map: Option<Arc<DashMap<SocketAddr, SocketAddr>>>,
+) {
+    loop {
+        let incoming = tokio::select! {
+            _ = cancel.cancelled() => {
+                debug!("QUIC accept loop on port {} cancelled", port);
+                break;
+            }
+            incoming = endpoint.accept() => {
+                match incoming {
+                    Some(conn) => conn,
+                    None => {
+                        debug!("QUIC endpoint on port {} closed", port);
+                        break;
+                    }
+                }
+            }
+        };
+
+        let remote_addr = incoming.remote_address();
+
+        // Resolve real client IP from PROXY protocol map if available
+        let real_addr = real_client_map.as_ref()
+            .and_then(|map| map.get(&remote_addr).map(|r| *r))
+            .unwrap_or(remote_addr);
+        let ip = real_addr.ip();
+
+        // Per-IP rate limiting
+        if !conn_tracker.try_accept(&ip) {
+            debug!("QUIC connection rejected from {} (rate limit)", real_addr);
+            // Drop `incoming` to refuse the connection
+            continue;
+        }
+
+        // Route matching (port + client IP, no domain yet — QUIC Initial is encrypted)
+        let rm = route_manager.load();
+        let ip_str = ip.to_string();
+        let ctx = MatchContext {
+            port,
+            domain: None,
+            path: None,
+            client_ip: Some(&ip_str),
+            tls_version: None,
+            headers: None,
+            is_tls: true,
+            protocol: Some("quic"),
+            transport: Some(TransportProtocol::Udp),
+        };
+
+        let route = match rm.find_route(&ctx) {
+            Some(m) => m.route.clone(),
+            None => {
+                debug!("No QUIC route matched for port {} from {}", port, real_addr);
+                continue;
+            }
+        };
+
+        conn_tracker.connection_opened(&ip);
+        let route_id = route.name.clone().or(route.id.clone());
+        metrics.connection_opened(route_id.as_deref(), Some(&ip_str));
+
+        let metrics = Arc::clone(&metrics);
+        let conn_tracker = Arc::clone(&conn_tracker);
+        let cancel = cancel.child_token();
+        let h3_svc = h3_service.clone();
+        let real_client_addr = if real_addr != remote_addr { Some(real_addr) } else { None };
+
+        tokio::spawn(async move {
+            // RAII guard: ensures metrics/tracker cleanup even on panic
+            struct QuicConnGuard {
+                tracker: Arc<ConnectionTracker>,
+                metrics: Arc<MetricsCollector>,
+                ip: std::net::IpAddr,
+                ip_str: String,
+                route_id: Option<String>,
+            }
+            impl Drop for QuicConnGuard {
+                fn drop(&mut self) {
+                    self.tracker.connection_closed(&self.ip);
+                    self.metrics.connection_closed(self.route_id.as_deref(), Some(&self.ip_str));
+                }
+            }
+            let _guard = QuicConnGuard {
+                tracker: conn_tracker,
+                metrics: Arc::clone(&metrics),
+                ip,
+                ip_str,
+                route_id,
+            };
+
+            match handle_quic_connection(incoming, route, port, Arc::clone(&metrics), &cancel, h3_svc, real_client_addr).await {
+                Ok(()) => debug!("QUIC connection from {} completed", real_addr),
+                Err(e) => debug!("QUIC connection from {} error: {}", real_addr, e),
+            }
+        });
+    }
+
+    // Graceful shutdown: close endpoint and wait for in-flight connections
+    endpoint.close(quinn::VarInt::from_u32(0), b"server shutting down");
+    endpoint.wait_idle().await;
+    info!("QUIC endpoint on port {} shut down", port);
+}
+
+/// Handle a single accepted QUIC connection.
+async fn handle_quic_connection(
+    incoming: quinn::Incoming,
+    route: RouteConfig,
+    port: u16,
+    metrics: Arc<MetricsCollector>,
+    cancel: &CancellationToken,
+    h3_service: Option<Arc<H3ProxyService>>,
+    real_client_addr: Option<SocketAddr>,
+) -> anyhow::Result<()> {
+    let connection = incoming.await?;
+    let effective_addr = real_client_addr.unwrap_or_else(|| connection.remote_address());
+    debug!("QUIC connection established from {}", effective_addr);
+
+    // Check if this route has HTTP/3 enabled
+    let enable_http3 = route.action.udp.as_ref()
+        .and_then(|u| u.quic.as_ref())
+        .and_then(|q| q.enable_http3)
+        .unwrap_or(false);
+
+    if enable_http3 {
+        if let Some(ref h3_svc) = h3_service {
+            debug!("HTTP/3 enabled for route {:?}, dispatching to H3ProxyService", route.name);
+            h3_svc.handle_connection(connection, &route, port, real_client_addr, cancel).await
+        } else {
+            warn!("HTTP/3 enabled for route {:?} but H3ProxyService not initialized", route.name);
+            // Keep connection alive until cancelled
+            tokio::select! {
+                _ = cancel.cancelled() => {}
+                reason = connection.closed() => {
+                    debug!("HTTP/3 connection closed (no service): {}", reason);
+                }
+            }
+            Ok(())
+        }
+    } else {
+        // Non-HTTP3 QUIC: bidirectional stream forwarding to TCP backend
+        handle_quic_stream_forwarding(connection, route, port, metrics, cancel, real_client_addr).await
+    }
+}
+
+/// Forward QUIC streams bidirectionally to a TCP backend.
+///
+/// For each accepted bidirectional QUIC stream, connects to the backend
+/// via TCP and forwards data in both directions. Quinn's RecvStream/SendStream
+/// implement AsyncRead/AsyncWrite, enabling reuse of existing forwarder patterns.
+async fn handle_quic_stream_forwarding(
+    connection: quinn::Connection,
+    route: RouteConfig,
+    port: u16,
+    metrics: Arc<MetricsCollector>,
+    cancel: &CancellationToken,
+    real_client_addr: Option<SocketAddr>,
+) -> anyhow::Result<()> {
+    let effective_addr = real_client_addr.unwrap_or_else(|| connection.remote_address());
+    let route_id = route.name.as_deref().or(route.id.as_deref());
+    let metrics_arc = metrics;
+
+    // Resolve backend target
+    let target = route.action.targets.as_ref()
+        .and_then(|t| t.first())
+        .ok_or_else(|| anyhow::anyhow!("No target for QUIC route"))?;
+    let backend_host = target.host.first();
+    let backend_port = target.port.resolve(port);
+    let backend_addr = format!("{}:{}", backend_host, backend_port);
+
+    loop {
+        let (send_stream, recv_stream) = tokio::select! {
+            _ = cancel.cancelled() => break,
+            result = connection.accept_bi() => {
+                match result {
+                    Ok(streams) => streams,
+                    Err(quinn::ConnectionError::ApplicationClosed(_)) => break,
+                    Err(quinn::ConnectionError::LocallyClosed) => break,
+                    Err(e) => {
+                        debug!("QUIC stream accept error from {}: {}", effective_addr, e);
+                        break;
+                    }
+                }
+            }
+        };
+
+        let backend_addr = backend_addr.clone();
+        let ip_str = effective_addr.ip().to_string();
+        let stream_metrics = Arc::clone(&metrics_arc);
+        let stream_route_id = route_id.map(|s| s.to_string());
+        let stream_cancel = cancel.child_token();
+
+        // Spawn a task for each QUIC stream → TCP bidirectional forwarding
+        tokio::spawn(async move {
+            match forward_quic_stream_to_tcp(
+                send_stream,
+                recv_stream,
+                &backend_addr,
+                stream_cancel,
+            ).await {
+                Ok((bytes_in, bytes_out)) => {
+                    stream_metrics.record_bytes(
+                        bytes_in, bytes_out,
+                        stream_route_id.as_deref(),
+                        Some(&ip_str),
+                    );
+                    debug!("QUIC stream forwarded: {}B in, {}B out", bytes_in, bytes_out);
+                }
+                Err(e) => {
+                    debug!("QUIC stream forwarding error: {}", e);
+                }
+            }
+        });
+    }
+
+    Ok(())
+}
+
+/// Forward a single QUIC bidirectional stream to a TCP backend connection.
+///
+/// Includes inactivity timeout (60s), max lifetime (10min), and cancellation
+/// to prevent leaked stream tasks when the parent connection closes.
+async fn forward_quic_stream_to_tcp(
+    mut quic_send: quinn::SendStream,
+    mut quic_recv: quinn::RecvStream,
+    backend_addr: &str,
+    cancel: CancellationToken,
+) -> anyhow::Result<(u64, u64)> {
+    let inactivity_timeout = std::time::Duration::from_secs(60);
+    let max_lifetime = std::time::Duration::from_secs(600);
+
+    // Connect to backend TCP
+    let tcp_stream = tokio::net::TcpStream::connect(backend_addr).await?;
+    let (mut tcp_read, mut tcp_write) = tcp_stream.into_split();
+
+    let last_activity = Arc::new(AtomicU64::new(0));
+    let start = std::time::Instant::now();
+    let conn_cancel = CancellationToken::new();
+
+    let la1 = Arc::clone(&last_activity);
+    let cc1 = conn_cancel.clone();
+    let c2b = tokio::spawn(async move {
+        let mut buf = vec![0u8; 65536];
+        let mut total = 0u64;
+        loop {
+            let n = tokio::select! {
+                result = quic_recv.read(&mut buf) => match result {
+                    Ok(Some(0)) | Ok(None) | Err(_) => break,
+                    Ok(Some(n)) => n,
+                },
+                _ = cc1.cancelled() => break,
+            };
+            if tcp_write.write_all(&buf[..n]).await.is_err() {
+                break;
+            }
+            total += n as u64;
+            la1.store(start.elapsed().as_millis() as u64, Ordering::Relaxed);
+        }
+        let _ = tokio::time::timeout(
+            std::time::Duration::from_secs(2),
+            tcp_write.shutdown(),
+        ).await;
+        total
+    });
+
+    let la2 = Arc::clone(&last_activity);
+    let cc2 = conn_cancel.clone();
+    let b2c = tokio::spawn(async move {
+        let mut buf = vec![0u8; 65536];
+        let mut total = 0u64;
+        loop {
+            let n = tokio::select! {
+                result = tcp_read.read(&mut buf) => match result {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => n,
+                },
+                _ = cc2.cancelled() => break,
+            };
+            // quinn SendStream implements AsyncWrite
+            if quic_send.write_all(&buf[..n]).await.is_err() {
+                break;
+            }
+            total += n as u64;
+            la2.store(start.elapsed().as_millis() as u64, Ordering::Relaxed);
+        }
+        let _ = quic_send.finish();
+        total
+    });
+
+    // Watchdog: inactivity, max lifetime, and cancellation
+    let la_watch = Arc::clone(&last_activity);
+    let c2b_abort = c2b.abort_handle();
+    let b2c_abort = b2c.abort_handle();
+    tokio::spawn(async move {
+        let check_interval = std::time::Duration::from_secs(5);
+        let mut last_seen = 0u64;
+        loop {
+            tokio::select! {
+                _ = cancel.cancelled() => break,
+                _ = tokio::time::sleep(check_interval) => {
+                    if start.elapsed() >= max_lifetime {
+                        debug!("QUIC stream exceeded max lifetime, closing");
+                        break;
+                    }
+                    let current = la_watch.load(Ordering::Relaxed);
+                    if current == last_seen {
+                        let elapsed = start.elapsed().as_millis() as u64 - current;
+                        if elapsed >= inactivity_timeout.as_millis() as u64 {
+                            debug!("QUIC stream inactive for {}ms, closing", elapsed);
+                            break;
+                        }
+                    }
+                    last_seen = current;
+                }
+            }
+        }
+        conn_cancel.cancel();
+        tokio::time::sleep(std::time::Duration::from_secs(4)).await;
+        c2b_abort.abort();
+        b2c_abort.abort();
+    });
+
+    let bytes_in = c2b.await.unwrap_or(0);
+    let bytes_out = b2c.await.unwrap_or(0);
+
+    Ok((bytes_in, bytes_out))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_quic_endpoint_requires_tls_config() {
+        // Install the ring crypto provider for tests
+        let _ = rustls::crypto::ring::default_provider().install_default();
+
+        // Generate a single self-signed cert and use its key pair
+        let self_signed = rcgen::generate_simple_self_signed(vec!["localhost".to_string()])
+            .unwrap();
+        let cert_der = self_signed.cert.der().clone();
+        let key_der = self_signed.key_pair.serialize_der();
+
+        let mut tls_config = RustlsServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(
+                vec![cert_der.into()],
+                rustls::pki_types::PrivateKeyDer::try_from(key_der).unwrap(),
+            )
+            .unwrap();
+        tls_config.alpn_protocols = vec![b"h3".to_vec()];
+
+        // Port 0 = OS assigns a free port
+        let result = create_quic_endpoint(0, Arc::new(tls_config));
+        assert!(result.is_ok(), "QUIC endpoint creation failed: {:?}", result.err());
+    }
+}

rust/crates/rustproxy-passthrough/src/tcp_listener.rs

@@ -428,6 +428,11 @@ impl TcpListenerManager {
         self.http_proxy.prune_stale_routes(active_route_ids);
     }
 
+    /// Get a reference to the HTTP proxy service (shared with H3).
+    pub fn http_proxy(&self) -> &Arc<HttpProxyService> {
+        &self.http_proxy
+    }
+
     /// Get a reference to the connection tracker.
     pub fn conn_tracker(&self) -> &Arc<ConnectionTracker> {
         &self.conn_tracker
@@ -561,8 +566,9 @@ impl TcpListenerManager {
         // Non-proxy connections skip the peek entirely (no latency cost).
         let mut effective_peer_addr = peer_addr;
         if !conn_config.proxy_ips.is_empty() && conn_config.proxy_ips.contains(&peer_addr.ip()) {
-            // Trusted proxy IP — peek for PROXY protocol header
-            let mut proxy_peek = vec![0u8; 256];
+            // Trusted proxy IP — peek for PROXY protocol header.
+            // Use stack-allocated buffers (PROXY v1 headers are max ~108 bytes).
+            let mut proxy_peek = [0u8; 256];
             let pn = match tokio::time::timeout(
                 std::time::Duration::from_millis(conn_config.initial_data_timeout_ms),
                 stream.peek(&mut proxy_peek),
@@ -572,18 +578,30 @@ impl TcpListenerManager {
                 Err(_) => return Err("Initial data timeout (proxy protocol peek)".into()),
             };
 
-            if pn > 0 && crate::proxy_protocol::is_proxy_protocol_v1(&proxy_peek[..pn]) {
-                match crate::proxy_protocol::parse_v1(&proxy_peek[..pn]) {
-                    Ok((header, consumed)) => {
-                        debug!("PROXY protocol: real client {} -> {}", header.source_addr, header.dest_addr);
-                        effective_peer_addr = header.source_addr;
-                        // Consume the proxy protocol header bytes
-                        let mut discard = vec![0u8; consumed];
-                        stream.read_exact(&mut discard).await?;
+            if pn > 0 {
+                if crate::proxy_protocol::is_proxy_protocol_v1(&proxy_peek[..pn]) {
+                    match crate::proxy_protocol::parse_v1(&proxy_peek[..pn]) {
+                        Ok((header, consumed)) => {
+                            debug!("PROXY v1: real client {} -> {}", header.source_addr, header.dest_addr);
+                            effective_peer_addr = header.source_addr;
+                            let mut discard = [0u8; 128];
+                            stream.read_exact(&mut discard[..consumed]).await?;
+                        }
+                        Err(e) => {
+                            debug!("Failed to parse PROXY v1 header: {}", e);
+                        }
                     }
-                    Err(e) => {
-                        debug!("Failed to parse PROXY protocol header: {}", e);
-                        // Not a PROXY protocol header, continue normally
+                } else if crate::proxy_protocol::is_proxy_protocol_v2(&proxy_peek[..pn]) {
+                    match crate::proxy_protocol::parse_v2(&proxy_peek[..pn]) {
+                        Ok((header, consumed)) => {
+                            debug!("PROXY v2: real client {} -> {} ({:?})", header.source_addr, header.dest_addr, header.protocol);
+                            effective_peer_addr = header.source_addr;
+                            let mut discard = [0u8; 256];
+                            stream.read_exact(&mut discard[..consumed]).await?;
+                        }
+                        Err(e) => {
+                            debug!("Failed to parse PROXY v2 header: {}", e);
+                        }
                     }
                 }
             }
@@ -612,6 +630,7 @@ impl TcpListenerManager {
                 headers: None,
                 is_tls: false,
                 protocol: None,
+                transport: None,
             };
 
             if let Some(quick_match) = route_manager.find_route(&quick_ctx) {
@@ -801,6 +820,7 @@ impl TcpListenerManager {
             is_tls,
             // For TLS connections, protocol is unknown until after termination
             protocol: if is_http { Some("http") } else if !is_tls { Some("tcp") } else { None },
+            transport: None,
         };
 
         let route_match = route_manager.find_route(&ctx);
@@ -1014,7 +1034,11 @@ impl TcpListenerManager {
                         "TLS Terminate + HTTP: {} -> {}:{} (domain: {:?})",
                         peer_addr, target_host, target_port, domain
                     );
-                    http_proxy.handle_io(buf_stream, peer_addr, port, cancel.clone()).await;
+                    // Wrap in ShutdownOnDrop to ensure TLS close_notify is sent
+                    // even if hyper drops the connection without calling shutdown
+                    // (e.g. H2 close, backend error, idle timeout drain).
+                    let wrapped = rustproxy_http::shutdown_on_drop::ShutdownOnDrop::new(buf_stream);
+                    http_proxy.handle_io(wrapped, peer_addr, port, cancel.clone()).await;
                 } else {
                     debug!(
                         "TLS Terminate + TCP: {} -> {}:{} (domain: {:?})",
@@ -1096,7 +1120,10 @@ impl TcpListenerManager {
                         "TLS Terminate+Reencrypt + HTTP: {} (domain: {:?})",
                         peer_addr, domain
                     );
-                    http_proxy.handle_io(buf_stream, peer_addr, port, cancel.clone()).await;
+                    // Wrap in ShutdownOnDrop to ensure TLS close_notify is sent
+                    // even if hyper drops the connection without calling shutdown.
+                    let wrapped = rustproxy_http::shutdown_on_drop::ShutdownOnDrop::new(buf_stream);
+                    http_proxy.handle_io(wrapped, peer_addr, port, cancel.clone()).await;
                 } else {
                     // Non-HTTP: TLS-to-TLS tunnel (existing behavior for raw TCP protocols)
                     debug!(

rust/crates/rustproxy-passthrough/src/udp_listener.rs

@@ -0,0 +1,907 @@
+//! UDP listener manager.
+//!
+//! Binds UDP sockets on configured ports, receives datagrams, matches routes,
+//! tracks sessions (flows), and forwards datagrams to backend UDP sockets.
+//!
+//! Supports PROXY protocol v2 on both raw UDP and QUIC paths when `proxy_ips`
+//! is configured. For QUIC, a relay layer intercepts datagrams before they
+//! reach the quinn endpoint.
+
+use std::collections::HashMap;
+use std::net::{IpAddr, SocketAddr};
+use std::sync::atomic::Ordering;
+use std::sync::Arc;
+
+use dashmap::DashMap;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+use arc_swap::ArcSwap;
+use tokio::net::UdpSocket;
+use tokio::task::JoinHandle;
+use tokio::sync::{Mutex, RwLock};
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, error, info, warn};
+
+use rustproxy_config::{RouteActionType, TransportProtocol};
+use rustproxy_metrics::MetricsCollector;
+use rustproxy_routing::{MatchContext, RouteManager};
+
+use rustproxy_http::h3_service::H3ProxyService;
+
+use crate::connection_tracker::ConnectionTracker;
+use crate::udp_session::{SessionKey, UdpSession, UdpSessionConfig, UdpSessionTable};
+
+/// Manages UDP listeners across all configured ports.
+pub struct UdpListenerManager {
+    /// Port → (recv loop task handle, optional QUIC endpoint for TLS updates)
+    listeners: HashMap<u16, (JoinHandle<()>, Option<quinn::Endpoint>)>,
+    /// Hot-reloadable route table
+    route_manager: Arc<ArcSwap<RouteManager>>,
+    /// Shared metrics collector
+    metrics: Arc<MetricsCollector>,
+    /// Per-IP session/rate limiting (shared with TCP)
+    conn_tracker: Arc<ConnectionTracker>,
+    /// Shared session table across all ports
+    session_table: Arc<UdpSessionTable>,
+    /// Cancellation for graceful shutdown
+    cancel_token: CancellationToken,
+    /// Unix socket path for datagram handler relay
+    datagram_handler_relay: Arc<RwLock<Option<String>>>,
+    /// Persistent write half of the relay connection
+    relay_writer: Arc<Mutex<Option<tokio::net::unix::OwnedWriteHalf>>>,
+    /// Cancel token for the current relay reply reader task
+    relay_reader_cancel: Option<CancellationToken>,
+    /// H3 proxy service for HTTP/3 request handling
+    h3_service: Option<Arc<H3ProxyService>>,
+    /// Trusted proxy IPs that may send PROXY protocol v2 headers.
+    /// When non-empty, PROXY v2 detection is enabled on both raw UDP and QUIC paths.
+    proxy_ips: Arc<Vec<IpAddr>>,
+}
+
+impl Drop for UdpListenerManager {
+    fn drop(&mut self) {
+        self.cancel_token.cancel();
+        for (_, (handle, endpoint)) in self.listeners.drain() {
+            handle.abort();
+            if let Some(ep) = endpoint {
+                ep.close(quinn::VarInt::from_u32(0), b"shutdown");
+            }
+        }
+    }
+}
+
+impl UdpListenerManager {
+    pub fn new(
+        route_manager: Arc<RouteManager>,
+        metrics: Arc<MetricsCollector>,
+        conn_tracker: Arc<ConnectionTracker>,
+        cancel_token: CancellationToken,
+    ) -> Self {
+        Self {
+            listeners: HashMap::new(),
+            route_manager: Arc::new(ArcSwap::from(route_manager)),
+            metrics,
+            conn_tracker,
+            session_table: Arc::new(UdpSessionTable::new()),
+            cancel_token,
+            datagram_handler_relay: Arc::new(RwLock::new(None)),
+            relay_writer: Arc::new(Mutex::new(None)),
+            relay_reader_cancel: None,
+            h3_service: None,
+            proxy_ips: Arc::new(Vec::new()),
+        }
+    }
+
+    /// Set the trusted proxy IPs for PROXY protocol v2 detection.
+    pub fn set_proxy_ips(&mut self, ips: Vec<IpAddr>) {
+        if !ips.is_empty() {
+            info!("UDP/QUIC PROXY protocol v2 enabled for {} trusted IPs", ips.len());
+        }
+        self.proxy_ips = Arc::new(ips);
+    }
+
+    /// Set the H3 proxy service for HTTP/3 request handling.
+    pub fn set_h3_service(&mut self, svc: Arc<H3ProxyService>) {
+        self.h3_service = Some(svc);
+    }
+
+    /// Update the route manager (for hot-reload).
+    pub fn update_routes(&self, route_manager: Arc<RouteManager>) {
+        self.route_manager.store(route_manager);
+    }
+
+    /// Start listening on a UDP port.
+    ///
+    /// If any route on this port has QUIC config (`action.udp.quic`), a quinn
+    /// endpoint is created instead of a raw UDP socket.
+    pub async fn add_port(&mut self, port: u16) -> anyhow::Result<()> {
+        self.add_port_with_tls(port, None).await
+    }
+
+    /// Start listening on a UDP port with optional TLS config for QUIC.
+    pub async fn add_port_with_tls(
+        &mut self,
+        port: u16,
+        tls_config: Option<std::sync::Arc<rustls::ServerConfig>>,
+    ) -> anyhow::Result<()> {
+        if self.listeners.contains_key(&port) {
+            debug!("UDP port {} already listening", port);
+            return Ok(());
+        }
+
+        // Check if any route on this port uses QUIC
+        let rm = self.route_manager.load();
+        let has_quic = rm.routes_for_port(port).iter().any(|r| {
+            r.action.udp.as_ref()
+                .and_then(|u| u.quic.as_ref())
+                .is_some()
+        });
+
+        if has_quic {
+            if let Some(tls) = tls_config {
+                if self.proxy_ips.is_empty() {
+                    // Direct path: quinn owns the external socket (zero overhead)
+                    let endpoint = crate::quic_handler::create_quic_endpoint(port, tls)?;
+                    let endpoint_for_updates = endpoint.clone();
+                    let handle = tokio::spawn(crate::quic_handler::quic_accept_loop(
+                        endpoint,
+                        port,
+                        Arc::clone(&self.route_manager),
+                        Arc::clone(&self.metrics),
+                        Arc::clone(&self.conn_tracker),
+                        self.cancel_token.child_token(),
+                        self.h3_service.clone(),
+                        None,
+                    ));
+                    self.listeners.insert(port, (handle, Some(endpoint_for_updates)));
+                    info!("QUIC endpoint started on port {}", port);
+                } else {
+                    // Proxy relay path: we own external socket, quinn on localhost
+                    let relay = crate::quic_handler::create_quic_endpoint_with_proxy_relay(
+                        port,
+                        tls,
+                        Arc::clone(&self.proxy_ips),
+                        self.cancel_token.child_token(),
+                    )?;
+                    let endpoint_for_updates = relay.endpoint.clone();
+                    let handle = tokio::spawn(crate::quic_handler::quic_accept_loop(
+                        relay.endpoint,
+                        port,
+                        Arc::clone(&self.route_manager),
+                        Arc::clone(&self.metrics),
+                        Arc::clone(&self.conn_tracker),
+                        self.cancel_token.child_token(),
+                        self.h3_service.clone(),
+                        Some(relay.real_client_map),
+                    ));
+                    self.listeners.insert(port, (handle, Some(endpoint_for_updates)));
+                    info!("QUIC endpoint with PROXY relay started on port {}", port);
+                }
+                return Ok(());
+            } else {
+                warn!("QUIC routes on port {} but no TLS config provided, falling back to raw UDP", port);
+            }
+        }
+
+        // Raw UDP listener
+        let addr: SocketAddr = ([0, 0, 0, 0], port).into();
+        let socket = UdpSocket::bind(addr).await?;
+        let socket = Arc::new(socket);
+        info!("UDP listener bound on port {}", port);
+
+        let handle = tokio::spawn(Self::recv_loop(
+            socket,
+            port,
+            Arc::clone(&self.route_manager),
+            Arc::clone(&self.metrics),
+            Arc::clone(&self.conn_tracker),
+            Arc::clone(&self.session_table),
+            Arc::clone(&self.datagram_handler_relay),
+            Arc::clone(&self.relay_writer),
+            self.cancel_token.child_token(),
+            Arc::clone(&self.proxy_ips),
+        ));
+
+        self.listeners.insert(port, (handle, None));
+
+        // Start the session cleanup task if this is the first port
+        if self.listeners.len() == 1 {
+            self.start_cleanup_task();
+        }
+
+        Ok(())
+    }
+
+    /// Stop listening on a UDP port.
+    pub fn remove_port(&mut self, port: u16) {
+        if let Some((handle, endpoint)) = self.listeners.remove(&port) {
+            handle.abort();
+            if let Some(ep) = endpoint {
+                ep.close(quinn::VarInt::from_u32(0), b"port removed");
+            }
+            info!("UDP listener removed from port {}", port);
+        }
+    }
+
+    /// Get all listening UDP ports.
+    pub fn listening_ports(&self) -> Vec<u16> {
+        let mut ports: Vec<u16> = self.listeners.keys().copied().collect();
+        ports.sort();
+        ports
+    }
+
+    /// Stop all listeners and clean up.
+    pub async fn stop(&mut self) {
+        self.cancel_token.cancel();
+        for (port, (handle, endpoint)) in self.listeners.drain() {
+            handle.abort();
+            if let Some(ep) = endpoint {
+                ep.close(quinn::VarInt::from_u32(0), b"shutdown");
+            }
+            debug!("UDP listener stopped on port {}", port);
+        }
+        info!("All UDP listeners stopped, {} sessions remaining",
+            self.session_table.session_count());
+    }
+
+    /// Update TLS config on all active QUIC endpoints (cert refresh).
+    /// Only affects new incoming connections — existing connections are undisturbed.
+    /// Uses quinn's Endpoint::set_server_config() for zero-downtime hot-swap.
+    pub fn update_quic_tls(&self, tls_config: Arc<rustls::ServerConfig>) {
+        for (port, (_handle, endpoint)) in &self.listeners {
+            if let Some(ep) = endpoint {
+                match quinn::crypto::rustls::QuicServerConfig::try_from(Arc::clone(&tls_config)) {
+                    Ok(quic_crypto) => {
+                        let server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_crypto));
+                        ep.set_server_config(Some(server_config));
+                        info!("Updated QUIC TLS config on port {}", port);
+                    }
+                    Err(e) => {
+                        warn!("Failed to update QUIC TLS config on port {}: {}", port, e);
+                    }
+                }
+            }
+        }
+    }
+
+    /// Upgrade raw UDP fallback listeners to QUIC endpoints.
+    ///
+    /// At startup, if no TLS certs are available, QUIC routes fall back to raw UDP.
+    /// When certs become available later (via loadCertificate IPC or ACME), this method
+    /// stops the raw UDP listener, drains sessions, and creates a proper QUIC endpoint.
+    ///
+    /// This is idempotent — ports that already have QUIC endpoints are skipped.
+    pub async fn upgrade_raw_to_quic(&mut self, tls_config: Arc<rustls::ServerConfig>) {
+        // Find ports that are raw UDP fallback (endpoint=None) but have QUIC routes
+        let rm = self.route_manager.load();
+        let upgrade_ports: Vec<u16> = self.listeners.iter()
+            .filter(|(_, (_, endpoint))| endpoint.is_none())
+            .filter(|(port, _)| {
+                rm.routes_for_port(**port).iter().any(|r| {
+                    r.action.udp.as_ref()
+                        .and_then(|u| u.quic.as_ref())
+                        .is_some()
+                })
+            })
+            .map(|(port, _)| *port)
+            .collect();
+
+        for port in upgrade_ports {
+            info!("Upgrading raw UDP listener on port {} to QUIC endpoint", port);
+
+            // Stop the raw UDP listener task and drain sessions to release the socket
+            if let Some((handle, _)) = self.listeners.remove(&port) {
+                handle.abort();
+            }
+            let drained = self.session_table.drain_port(
+                port, &self.metrics, &self.conn_tracker,
+            );
+            if drained > 0 {
+                debug!("Drained {} UDP sessions on port {} for QUIC upgrade", drained, port);
+            }
+
+            // Brief yield to let aborted tasks drop their socket references
+            tokio::task::yield_now().await;
+
+            // Create QUIC endpoint on the now-free port
+            let create_result = if self.proxy_ips.is_empty() {
+                self.create_quic_direct(port, Arc::clone(&tls_config))
+            } else {
+                self.create_quic_with_relay(port, Arc::clone(&tls_config))
+            };
+
+            match create_result {
+                Ok(()) => {
+                    info!("QUIC endpoint started on port {} (upgraded from raw UDP)", port);
+                }
+                Err(e) => {
+                    // Port may still be held — retry once after a brief delay
+                    warn!("QUIC endpoint creation failed on port {}, retrying: {}", port, e);
+                    tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+
+                    let retry_result = if self.proxy_ips.is_empty() {
+                        self.create_quic_direct(port, Arc::clone(&tls_config))
+                    } else {
+                        self.create_quic_with_relay(port, Arc::clone(&tls_config))
+                    };
+
+                    match retry_result {
+                        Ok(()) => {
+                            info!("QUIC endpoint started on port {} (upgraded from raw UDP, retry)", port);
+                        }
+                        Err(e2) => {
+                            error!("Failed to upgrade port {} to QUIC after retry: {}. \
+                                   Rebinding as raw UDP.", port, e2);
+                            // Fallback: rebind as raw UDP so the port isn't dead
+                            if let Ok(()) = self.rebind_raw_udp(port).await {
+                                warn!("Port {} rebound as raw UDP (QUIC upgrade failed)", port);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    /// Create a direct QUIC endpoint (quinn owns the socket).
+    fn create_quic_direct(&mut self, port: u16, tls_config: Arc<rustls::ServerConfig>) -> anyhow::Result<()> {
+        let endpoint = crate::quic_handler::create_quic_endpoint(port, tls_config)?;
+        let endpoint_for_updates = endpoint.clone();
+        let handle = tokio::spawn(crate::quic_handler::quic_accept_loop(
+            endpoint,
+            port,
+            Arc::clone(&self.route_manager),
+            Arc::clone(&self.metrics),
+            Arc::clone(&self.conn_tracker),
+            self.cancel_token.child_token(),
+            self.h3_service.clone(),
+            None,
+        ));
+        self.listeners.insert(port, (handle, Some(endpoint_for_updates)));
+        Ok(())
+    }
+
+    /// Create a QUIC endpoint with PROXY protocol relay.
+    fn create_quic_with_relay(&mut self, port: u16, tls_config: Arc<rustls::ServerConfig>) -> anyhow::Result<()> {
+        let relay = crate::quic_handler::create_quic_endpoint_with_proxy_relay(
+            port,
+            tls_config,
+            Arc::clone(&self.proxy_ips),
+            self.cancel_token.child_token(),
+        )?;
+        let endpoint_for_updates = relay.endpoint.clone();
+        let handle = tokio::spawn(crate::quic_handler::quic_accept_loop(
+            relay.endpoint,
+            port,
+            Arc::clone(&self.route_manager),
+            Arc::clone(&self.metrics),
+            Arc::clone(&self.conn_tracker),
+            self.cancel_token.child_token(),
+            self.h3_service.clone(),
+            Some(relay.real_client_map),
+        ));
+        self.listeners.insert(port, (handle, Some(endpoint_for_updates)));
+        Ok(())
+    }
+
+    /// Rebind a port as a raw UDP listener (fallback when QUIC upgrade fails).
+    async fn rebind_raw_udp(&mut self, port: u16) -> anyhow::Result<()> {
+        let addr: std::net::SocketAddr = ([0, 0, 0, 0], port).into();
+        let socket = UdpSocket::bind(addr).await?;
+        let socket = Arc::new(socket);
+
+        let handle = tokio::spawn(Self::recv_loop(
+            socket,
+            port,
+            Arc::clone(&self.route_manager),
+            Arc::clone(&self.metrics),
+            Arc::clone(&self.conn_tracker),
+            Arc::clone(&self.session_table),
+            Arc::clone(&self.datagram_handler_relay),
+            Arc::clone(&self.relay_writer),
+            self.cancel_token.child_token(),
+            Arc::clone(&self.proxy_ips),
+        ));
+
+        self.listeners.insert(port, (handle, None));
+        Ok(())
+    }
+
+    /// Set the datagram handler relay socket path and establish connection.
+    pub async fn set_datagram_handler_relay(&mut self, path: String) {
+        // Cancel previous relay reader task if any
+        if let Some(old_cancel) = self.relay_reader_cancel.take() {
+            old_cancel.cancel();
+        }
+
+        // Store the path
+        {
+            let mut relay = self.datagram_handler_relay.write().await;
+            *relay = Some(path.clone());
+        }
+
+        // Connect to the Unix socket
+        match tokio::net::UnixStream::connect(&path).await {
+            Ok(stream) => {
+                let (read_half, write_half) = stream.into_split();
+
+                // Store write half for sending datagrams
+                {
+                    let mut writer = self.relay_writer.lock().await;
+                    *writer = Some(write_half);
+                }
+
+                // Spawn reply reader — reads length-prefixed JSON replies from TS
+                // and sends them back to clients via the listener sockets
+                let cancel = self.cancel_token.child_token();
+                self.relay_reader_cancel = Some(cancel.clone());
+                tokio::spawn(Self::relay_reply_reader(read_half, cancel));
+
+                info!("Datagram handler relay connected to {}", path);
+            }
+            Err(e) => {
+                error!("Failed to connect datagram handler relay to {}: {}", path, e);
+            }
+        }
+    }
+
+    /// Start periodic session cleanup task.
+    fn start_cleanup_task(&self) {
+        let session_table = Arc::clone(&self.session_table);
+        let metrics = Arc::clone(&self.metrics);
+        let conn_tracker = Arc::clone(&self.conn_tracker);
+        let cancel = self.cancel_token.child_token();
+        let route_manager = Arc::clone(&self.route_manager);
+
+        tokio::spawn(async move {
+            let mut interval = tokio::time::interval(std::time::Duration::from_secs(10));
+            loop {
+                tokio::select! {
+                    _ = cancel.cancelled() => break,
+                    _ = interval.tick() => {
+                        // Determine the timeout from routes (use the minimum configured timeout,
+                        // or default 60s if none configured)
+                        let rm = route_manager.load();
+                        let timeout_ms = Self::get_min_session_timeout(&rm);
+                        let removed = session_table.cleanup_idle(timeout_ms, &metrics, &conn_tracker);
+                        if removed > 0 {
+                            debug!("UDP session cleanup: removed {} idle sessions, {} remaining",
+                                removed, session_table.session_count());
+                        }
+                    }
+                }
+            }
+        });
+    }
+
+    /// Get the minimum session timeout across all UDP routes.
+    fn get_min_session_timeout(_rm: &RouteManager) -> u64 {
+        // Default to 60 seconds; actual per-route timeouts checked during cleanup
+        60_000
+    }
+
+    /// Main receive loop for a UDP port.
+    ///
+    /// When `proxy_ips` is non-empty, the first datagram from a trusted proxy IP
+    /// is checked for PROXY protocol v2. If found, the real client IP is extracted
+    /// and used for all subsequent session handling for that source address.
+    async fn recv_loop(
+        socket: Arc<UdpSocket>,
+        port: u16,
+        route_manager: Arc<ArcSwap<RouteManager>>,
+        metrics: Arc<MetricsCollector>,
+        conn_tracker: Arc<ConnectionTracker>,
+        session_table: Arc<UdpSessionTable>,
+        _datagram_handler_relay: Arc<RwLock<Option<String>>>,
+        relay_writer: Arc<Mutex<Option<tokio::net::unix::OwnedWriteHalf>>>,
+        cancel: CancellationToken,
+        proxy_ips: Arc<Vec<IpAddr>>,
+    ) {
+        // Use a reasonably large buffer; actual max is per-route but we need a single buffer
+        let mut buf = vec![0u8; 65535];
+
+        // Maps proxy source addr → real client addr (from PROXY v2 headers).
+        // Only populated when proxy_ips is non-empty.
+        let proxy_addr_map: DashMap<SocketAddr, SocketAddr> = DashMap::new();
+
+        // Periodic cleanup for proxy_addr_map to prevent unbounded growth
+        let mut last_proxy_cleanup = tokio::time::Instant::now();
+        let proxy_cleanup_interval = std::time::Duration::from_secs(60);
+
+        loop {
+            // Periodic cleanup: remove proxy_addr_map entries with no active session
+            if !proxy_addr_map.is_empty() && last_proxy_cleanup.elapsed() >= proxy_cleanup_interval {
+                last_proxy_cleanup = tokio::time::Instant::now();
+                let stale: Vec<SocketAddr> = proxy_addr_map.iter()
+                    .filter(|entry| {
+                        let key: SessionKey = (*entry.key(), port);
+                        session_table.get(&key).is_none()
+                    })
+                    .map(|entry| *entry.key())
+                    .collect();
+                if !stale.is_empty() {
+                    debug!("UDP proxy_addr_map cleanup: removing {} stale entries on port {}", stale.len(), port);
+                    for addr in stale {
+                        proxy_addr_map.remove(&addr);
+                    }
+                }
+            }
+
+            let (len, client_addr) = tokio::select! {
+                _ = cancel.cancelled() => {
+                    debug!("UDP recv loop on port {} cancelled", port);
+                    break;
+                }
+                result = socket.recv_from(&mut buf) => {
+                    match result {
+                        Ok(r) => r,
+                        Err(e) => {
+                            warn!("UDP recv error on port {}: {}", port, e);
+                            continue;
+                        }
+                    }
+                }
+            };
+
+            let datagram = &buf[..len];
+
+            // PROXY protocol v2 detection for datagrams from trusted proxy IPs
+            let effective_client_ip = if !proxy_ips.is_empty() && proxy_ips.contains(&client_addr.ip()) {
+                let session_key: SessionKey = (client_addr, port);
+                if session_table.get(&session_key).is_none() && !proxy_addr_map.contains_key(&client_addr) {
+                    // No session and no prior PROXY header — check for PROXY v2
+                    if crate::proxy_protocol::is_proxy_protocol_v2(datagram) {
+                        match crate::proxy_protocol::parse_v2(datagram) {
+                            Ok((header, _consumed)) => {
+                                debug!("UDP PROXY v2 from {}: real client {}", client_addr, header.source_addr);
+                                proxy_addr_map.insert(client_addr, header.source_addr);
+                                continue; // discard the PROXY v2 datagram
+                            }
+                            Err(e) => {
+                                debug!("UDP PROXY v2 parse error from {}: {}", client_addr, e);
+                                client_addr.ip()
+                            }
+                        }
+                    } else {
+                        client_addr.ip()
+                    }
+                } else {
+                    // Use real client IP if we've previously seen a PROXY v2 header
+                    proxy_addr_map.get(&client_addr)
+                        .map(|r| r.ip())
+                        .unwrap_or_else(|| client_addr.ip())
+                }
+            } else {
+                client_addr.ip()
+            };
+
+            // Route matching — use effective (real) client IP
+            let rm = route_manager.load();
+            let ip_str = effective_client_ip.to_string();
+            let ctx = MatchContext {
+                port,
+                domain: None,
+                path: None,
+                client_ip: Some(&ip_str),
+                tls_version: None,
+                headers: None,
+                is_tls: false,
+                protocol: Some("udp"),
+                transport: Some(TransportProtocol::Udp),
+            };
+
+            let route_match = match rm.find_route(&ctx) {
+                Some(m) => m,
+                None => {
+                    debug!("No UDP route matched for port {} from {}", port, client_addr);
+                    continue;
+                }
+            };
+
+            let route = route_match.route;
+            let route_id = route.name.as_deref().or(route.id.as_deref());
+
+            // Socket handler routes → relay datagram to TS via persistent Unix socket
+            if route.action.action_type == RouteActionType::SocketHandler {
+                if let Err(e) = Self::relay_datagram_via_writer(
+                    &relay_writer,
+                    route_id.unwrap_or("unknown"),
+                    &client_addr,
+                    port,
+                    datagram,
+                ).await {
+                    debug!("Failed to relay UDP datagram to TS: {}", e);
+                }
+                continue;
+            }
+
+            // Get UDP config from route
+            let udp_config = UdpSessionConfig::from_route_udp(route.action.udp.as_ref());
+
+            // Check datagram size
+            if len as u32 > udp_config.max_datagram_size {
+                debug!("UDP datagram too large ({} > {}) from {}, dropping",
+                    len, udp_config.max_datagram_size, client_addr);
+                continue;
+            }
+
+            // Session lookup or create
+            // Session key uses the proxy's source addr for correct return-path routing
+            let session_key: SessionKey = (client_addr, port);
+            let session = match session_table.get(&session_key) {
+                Some(s) => s,
+                None => {
+                    // New session — check per-IP limits using the real client IP
+                    if !conn_tracker.try_accept(&effective_client_ip) {
+                        debug!("UDP session rejected for {} (rate limit)", effective_client_ip);
+                        continue;
+                    }
+                    if !session_table.can_create_session(
+                        &effective_client_ip,
+                        udp_config.max_sessions_per_ip,
+                    ) {
+                        debug!("UDP session rejected for {} (per-IP session limit)", effective_client_ip);
+                        continue;
+                    }
+
+                    // Resolve target
+                    let target = match route_match.target.or_else(|| {
+                        route.action.targets.as_ref().and_then(|t| t.first())
+                    }) {
+                        Some(t) => t,
+                        None => {
+                            warn!("No target for UDP route {:?}", route_id);
+                            continue;
+                        }
+                    };
+
+                    let backend_host = target.host.first();
+                    let backend_port = target.port.resolve(port);
+                    let backend_addr = format!("{}:{}", backend_host, backend_port);
+
+                    // Create backend socket
+                    let backend_socket = match UdpSocket::bind("0.0.0.0:0").await {
+                        Ok(s) => s,
+                        Err(e) => {
+                            error!("Failed to bind backend UDP socket: {}", e);
+                            continue;
+                        }
+                    };
+                    if let Err(e) = backend_socket.connect(&backend_addr).await {
+                        error!("Failed to connect backend UDP socket to {}: {}", backend_addr, e);
+                        continue;
+                    }
+                    let backend_socket = Arc::new(backend_socket);
+
+                    debug!("New UDP session: {} -> {} (via port {}, real client {})",
+                        client_addr, backend_addr, port, effective_client_ip);
+
+                    // Spawn return-path relay task
+                    let session_cancel = CancellationToken::new();
+                    let return_task = tokio::spawn(Self::return_relay(
+                        Arc::clone(&backend_socket),
+                        Arc::clone(&socket),
+                        client_addr,
+                        Arc::clone(&session_table),
+                        session_key,
+                        Arc::clone(&metrics),
+                        route_id.map(|s| s.to_string()),
+                        session_cancel.child_token(),
+                    ));
+
+                    let session = Arc::new(UdpSession {
+                        backend_socket,
+                        last_activity: std::sync::atomic::AtomicU64::new(session_table.elapsed_ms()),
+                        created_at: std::time::Instant::now(),
+                        route_id: route_id.map(|s| s.to_string()),
+                        source_ip: effective_client_ip,
+                        client_addr,
+                        return_task,
+                        cancel: session_cancel,
+                    });
+
+                    if !session_table.insert(session_key, Arc::clone(&session), udp_config.max_sessions_per_ip) {
+                        warn!("Failed to insert UDP session (race condition)");
+                        continue;
+                    }
+
+                    // Track in metrics using the real client IP
+                    conn_tracker.connection_opened(&effective_client_ip);
+                    metrics.connection_opened(route_id, Some(&ip_str));
+                    metrics.udp_session_opened();
+
+                    session
+                }
+            };
+
+            // Forward datagram to backend
+            match session.backend_socket.send(datagram).await {
+                Ok(_) => {
+                    session.last_activity.store(session_table.elapsed_ms(), Ordering::Relaxed);
+                    metrics.record_bytes(len as u64, 0, route_id, Some(&ip_str));
+                    metrics.record_datagram_in();
+                }
+                Err(e) => {
+                    debug!("Failed to send UDP datagram to backend: {}", e);
+                }
+            }
+        }
+    }
+
+    /// Return-path relay: backend → client.
+    async fn return_relay(
+        backend_socket: Arc<UdpSocket>,
+        listener_socket: Arc<UdpSocket>,
+        client_addr: SocketAddr,
+        session_table: Arc<UdpSessionTable>,
+        session_key: SessionKey,
+        metrics: Arc<MetricsCollector>,
+        route_id: Option<String>,
+        cancel: CancellationToken,
+    ) {
+        let mut buf = vec![0u8; 65535];
+        let ip_str = client_addr.ip().to_string();
+
+        loop {
+            let len = tokio::select! {
+                _ = cancel.cancelled() => break,
+                result = backend_socket.recv(&mut buf) => {
+                    match result {
+                        Ok(len) => len,
+                        Err(e) => {
+                            debug!("UDP backend recv error for {}: {}", client_addr, e);
+                            break;
+                        }
+                    }
+                }
+            };
+
+            // Send reply back to client
+            match listener_socket.send_to(&buf[..len], client_addr).await {
+                Ok(_) => {
+                    // Update session activity
+                    if let Some(session) = session_table.get(&session_key) {
+                        session.last_activity.store(session_table.elapsed_ms(), Ordering::Relaxed);
+                    }
+                    metrics.record_bytes(0, len as u64, route_id.as_deref(), Some(&ip_str));
+                    metrics.record_datagram_out();
+                }
+                Err(e) => {
+                    debug!("Failed to send UDP reply to {}: {}", client_addr, e);
+                    break;
+                }
+            }
+        }
+    }
+
+    /// Send a datagram to TS via the persistent relay writer.
+    async fn relay_datagram_via_writer(
+        writer: &Mutex<Option<tokio::net::unix::OwnedWriteHalf>>,
+        route_key: &str,
+        client_addr: &SocketAddr,
+        dest_port: u16,
+        datagram: &[u8],
+    ) -> anyhow::Result<()> {
+        use base64::Engine;
+
+        let payload_b64 = base64::engine::general_purpose::STANDARD.encode(datagram);
+        let msg = serde_json::json!({
+            "type": "datagram",
+            "routeKey": route_key,
+            "sourceIp": client_addr.ip().to_string(),
+            "sourcePort": client_addr.port(),
+            "destPort": dest_port,
+            "payloadBase64": payload_b64,
+        });
+        let json = serde_json::to_vec(&msg)?;
+
+        let mut guard = writer.lock().await;
+        let stream = guard.as_mut()
+            .ok_or_else(|| anyhow::anyhow!("Datagram relay not connected"))?;
+
+        // Length-prefixed frame
+        let len_bytes = (json.len() as u32).to_be_bytes();
+        stream.write_all(&len_bytes).await?;
+        stream.write_all(&json).await?;
+        stream.flush().await?;
+
+        Ok(())
+    }
+
+    /// Background task reading reply frames from the TS datagram handler.
+    /// Parses replies and sends them back to the original client via UDP.
+    async fn relay_reply_reader(
+        mut reader: tokio::net::unix::OwnedReadHalf,
+        cancel: CancellationToken,
+    ) {
+        use base64::Engine;
+
+        let mut len_buf = [0u8; 4];
+        loop {
+            // Read length prefix
+            let read_result = tokio::select! {
+                _ = cancel.cancelled() => break,
+                result = reader.read_exact(&mut len_buf) => result,
+            };
+
+            match read_result {
+                Ok(_) => {}
+                Err(e) => {
+                    debug!("Datagram relay reader closed: {}", e);
+                    break;
+                }
+            }
+
+            let frame_len = u32::from_be_bytes(len_buf) as usize;
+            if frame_len > 10 * 1024 * 1024 {
+                error!("Datagram relay frame too large: {} bytes", frame_len);
+                break;
+            }
+
+            let mut frame_buf = vec![0u8; frame_len];
+            match reader.read_exact(&mut frame_buf).await {
+                Ok(_) => {}
+                Err(e) => {
+                    debug!("Datagram relay reader frame error: {}", e);
+                    break;
+                }
+            }
+
+            // Parse the reply JSON
+            let reply: serde_json::Value = match serde_json::from_slice(&frame_buf) {
+                Ok(v) => v,
+                Err(e) => {
+                    debug!("Datagram relay reply parse error: {}", e);
+                    continue;
+                }
+            };
+
+            if reply.get("type").and_then(|v| v.as_str()) != Some("reply") {
+                continue;
+            }
+
+            let source_ip = reply.get("sourceIp").and_then(|v| v.as_str()).unwrap_or("");
+            let source_port = reply.get("sourcePort").and_then(|v| v.as_u64()).unwrap_or(0) as u16;
+            let dest_port = reply.get("destPort").and_then(|v| v.as_u64()).unwrap_or(0) as u16;
+            let payload_b64 = reply.get("payloadBase64").and_then(|v| v.as_str()).unwrap_or("");
+
+            let payload = match base64::engine::general_purpose::STANDARD.decode(payload_b64) {
+                Ok(p) => p,
+                Err(e) => {
+                    debug!("Datagram relay reply base64 decode error: {}", e);
+                    continue;
+                }
+            };
+
+            let client_addr: SocketAddr = match format!("{}:{}", source_ip, source_port).parse() {
+                Ok(a) => a,
+                Err(e) => {
+                    debug!("Datagram relay reply address parse error: {}", e);
+                    continue;
+                }
+            };
+
+            // Send the reply back to the client via a temporary UDP socket bound to the dest_port
+            // We need the listener socket for this port. For simplicity, use a fresh socket.
+            let reply_socket = match UdpSocket::bind(format!("0.0.0.0:{}", dest_port)).await {
+                Ok(s) => s,
+                Err(_) => {
+                    // Port already bound by the listener — use unbound socket
+                    match UdpSocket::bind("0.0.0.0:0").await {
+                        Ok(s) => s,
+                        Err(e) => {
+                            debug!("Failed to create reply socket: {}", e);
+                            continue;
+                        }
+                    }
+                }
+            };
+
+            if let Err(e) = reply_socket.send_to(&payload, client_addr).await {
+                debug!("Failed to send datagram reply to {}: {}", client_addr, e);
+            }
+        }
+
+        debug!("Datagram relay reply reader stopped");
+    }
+}

rust/crates/rustproxy-passthrough/src/udp_session.rs

@@ -0,0 +1,354 @@
+//! UDP session (flow) tracking.
+//!
+//! A UDP "session" is a flow identified by (client_addr, listening_port).
+//! Each session maintains a backend socket bound to an ephemeral port and
+//! connected to the backend target, plus a background task that relays
+//! return datagrams from the backend back to the client.
+
+use std::net::{IpAddr, SocketAddr};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+
+use dashmap::DashMap;
+use tokio::net::UdpSocket;
+use tokio::task::JoinHandle;
+use tokio_util::sync::CancellationToken;
+use tracing::debug;
+
+use rustproxy_metrics::MetricsCollector;
+
+use crate::connection_tracker::ConnectionTracker;
+
+/// A single UDP session (flow).
+pub struct UdpSession {
+    /// Socket bound to ephemeral port, connected to backend
+    pub backend_socket: Arc<UdpSocket>,
+    /// Milliseconds since the session table's epoch
+    pub last_activity: AtomicU64,
+    /// When the session was created
+    pub created_at: Instant,
+    /// Route ID for metrics
+    pub route_id: Option<String>,
+    /// Source IP for metrics/tracking
+    pub source_ip: IpAddr,
+    /// Client address (for return path)
+    pub client_addr: SocketAddr,
+    /// Handle for the return-path relay task
+    pub return_task: JoinHandle<()>,
+    /// Per-session cancellation
+    pub cancel: CancellationToken,
+}
+
+impl Drop for UdpSession {
+    fn drop(&mut self) {
+        self.cancel.cancel();
+        self.return_task.abort();
+    }
+}
+
+/// Configuration for UDP session behavior.
+#[derive(Debug, Clone)]
+pub struct UdpSessionConfig {
+    /// Idle timeout in milliseconds. Default: 60000.
+    pub session_timeout_ms: u64,
+    /// Max concurrent sessions per source IP. Default: 1000.
+    pub max_sessions_per_ip: u32,
+    /// Max accepted datagram size in bytes. Default: 65535.
+    pub max_datagram_size: u32,
+}
+
+impl Default for UdpSessionConfig {
+    fn default() -> Self {
+        Self {
+            session_timeout_ms: 60_000,
+            max_sessions_per_ip: 1_000,
+            max_datagram_size: 65_535,
+        }
+    }
+}
+
+impl UdpSessionConfig {
+    /// Build from route's UDP config, falling back to defaults.
+    pub fn from_route_udp(udp: Option<&rustproxy_config::RouteUdp>) -> Self {
+        match udp {
+            Some(u) => Self {
+                session_timeout_ms: u.session_timeout.unwrap_or(60_000),
+                max_sessions_per_ip: u.max_sessions_per_ip.unwrap_or(1_000),
+                max_datagram_size: u.max_datagram_size.unwrap_or(65_535),
+            },
+            None => Self::default(),
+        }
+    }
+}
+
+/// Session key: (client address, listening port).
+pub type SessionKey = (SocketAddr, u16);
+
+/// Tracks all active UDP sessions across all ports.
+pub struct UdpSessionTable {
+    /// Active sessions keyed by (client_addr, listen_port)
+    sessions: DashMap<SessionKey, Arc<UdpSession>>,
+    /// Per-IP session counts for enforcing limits
+    ip_session_counts: DashMap<IpAddr, u32>,
+    /// Time reference for last_activity
+    epoch: Instant,
+}
+
+impl UdpSessionTable {
+    pub fn new() -> Self {
+        Self {
+            sessions: DashMap::new(),
+            ip_session_counts: DashMap::new(),
+            epoch: Instant::now(),
+        }
+    }
+
+    /// Get elapsed milliseconds since epoch (for last_activity tracking).
+    pub fn elapsed_ms(&self) -> u64 {
+        self.epoch.elapsed().as_millis() as u64
+    }
+
+    /// Look up an existing session.
+    pub fn get(&self, key: &SessionKey) -> Option<Arc<UdpSession>> {
+        self.sessions.get(key).map(|entry| Arc::clone(entry.value()))
+    }
+
+    /// Check if we can create a new session for this IP (under the per-IP limit).
+    pub fn can_create_session(&self, ip: &IpAddr, max_per_ip: u32) -> bool {
+        let count = self.ip_session_counts
+            .get(ip)
+            .map(|c| *c.value())
+            .unwrap_or(0);
+        count < max_per_ip
+    }
+
+    /// Insert a new session. Returns false if per-IP limit exceeded.
+    pub fn insert(
+        &self,
+        key: SessionKey,
+        session: Arc<UdpSession>,
+        max_per_ip: u32,
+    ) -> bool {
+        let ip = session.source_ip;
+
+        // Atomically check and increment per-IP count
+        let mut count_entry = self.ip_session_counts.entry(ip).or_insert(0);
+        if *count_entry.value() >= max_per_ip {
+            return false;
+        }
+        *count_entry.value_mut() += 1;
+        drop(count_entry);
+
+        self.sessions.insert(key, session);
+        true
+    }
+
+    /// Remove a session and decrement per-IP count.
+    pub fn remove(&self, key: &SessionKey) -> Option<Arc<UdpSession>> {
+        if let Some((_, session)) = self.sessions.remove(key) {
+            let ip = session.source_ip;
+            if let Some(mut count) = self.ip_session_counts.get_mut(&ip) {
+                *count.value_mut() = count.value().saturating_sub(1);
+                if *count.value() == 0 {
+                    drop(count);
+                    self.ip_session_counts.remove(&ip);
+                }
+            }
+            Some(session)
+        } else {
+            None
+        }
+    }
+
+    /// Clean up idle sessions past the given timeout.
+    /// Returns the number of sessions removed.
+    pub fn cleanup_idle(
+        &self,
+        timeout_ms: u64,
+        metrics: &MetricsCollector,
+        conn_tracker: &ConnectionTracker,
+    ) -> usize {
+        let now_ms = self.elapsed_ms();
+        let mut removed = 0;
+
+        // Collect keys to remove (avoid holding DashMap refs during removal)
+        let stale_keys: Vec<SessionKey> = self.sessions.iter()
+            .filter(|entry| {
+                let last = entry.value().last_activity.load(Ordering::Relaxed);
+                now_ms.saturating_sub(last) >= timeout_ms
+            })
+            .map(|entry| *entry.key())
+            .collect();
+
+        for key in stale_keys {
+            if let Some(session) = self.remove(&key) {
+                debug!(
+                    "UDP session expired: {} -> port {} (idle {}ms)",
+                    session.client_addr, key.1,
+                    now_ms.saturating_sub(session.last_activity.load(Ordering::Relaxed))
+                );
+                conn_tracker.connection_closed(&session.source_ip);
+                metrics.connection_closed(
+                    session.route_id.as_deref(),
+                    Some(&session.source_ip.to_string()),
+                );
+                metrics.udp_session_closed();
+                removed += 1;
+            }
+        }
+
+        removed
+    }
+
+    /// Drain all sessions on a given listening port, releasing socket references.
+    /// Used when upgrading a raw UDP listener to QUIC — the raw UDP socket's
+    /// Arc refcount must drop to zero so the port can be rebound.
+    pub fn drain_port(
+        &self,
+        port: u16,
+        metrics: &MetricsCollector,
+        conn_tracker: &ConnectionTracker,
+    ) -> usize {
+        let keys: Vec<SessionKey> = self.sessions.iter()
+            .filter(|entry| entry.key().1 == port)
+            .map(|entry| *entry.key())
+            .collect();
+
+        let mut removed = 0;
+        for key in keys {
+            if let Some(session) = self.remove(&key) {
+                session.cancel.cancel();
+                conn_tracker.connection_closed(&session.source_ip);
+                metrics.connection_closed(
+                    session.route_id.as_deref(),
+                    Some(&session.source_ip.to_string()),
+                );
+                metrics.udp_session_closed();
+                removed += 1;
+            }
+        }
+        removed
+    }
+
+    /// Total number of active sessions.
+    pub fn session_count(&self) -> usize {
+        self.sessions.len()
+    }
+
+    /// Number of tracked IPs with active sessions.
+    pub fn tracked_ips(&self) -> usize {
+        self.ip_session_counts.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{Ipv4Addr, SocketAddrV4};
+
+    fn make_addr(port: u16) -> SocketAddr {
+        SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(10, 0, 0, 1), port))
+    }
+
+    fn make_session(client_addr: SocketAddr, cancel: CancellationToken) -> Arc<UdpSession> {
+        // Create a dummy backend socket for testing
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let backend_socket = rt.block_on(async {
+            Arc::new(UdpSocket::bind("127.0.0.1:0").await.unwrap())
+        });
+
+        let child_cancel = cancel.child_token();
+        let return_task = rt.spawn(async move {
+            child_cancel.cancelled().await;
+        });
+
+        Arc::new(UdpSession {
+            backend_socket,
+            last_activity: AtomicU64::new(0),
+            created_at: Instant::now(),
+            route_id: None,
+            source_ip: client_addr.ip(),
+            client_addr,
+            return_task,
+            cancel,
+        })
+    }
+
+    #[test]
+    fn test_session_table_insert_and_get() {
+        let table = UdpSessionTable::new();
+        let cancel = CancellationToken::new();
+        let addr = make_addr(12345);
+        let key: SessionKey = (addr, 53);
+        let session = make_session(addr, cancel);
+
+        assert!(table.insert(key, session, 1000));
+        assert!(table.get(&key).is_some());
+        assert_eq!(table.session_count(), 1);
+    }
+
+    #[test]
+    fn test_session_table_per_ip_limit() {
+        let table = UdpSessionTable::new();
+        let ip = Ipv4Addr::new(10, 0, 0, 1);
+
+        // Insert 2 sessions from same IP, limit is 2
+        for port in [12345u16, 12346] {
+            let addr = SocketAddr::V4(SocketAddrV4::new(ip, port));
+            let cancel = CancellationToken::new();
+            let session = make_session(addr, cancel);
+            assert!(table.insert((addr, 53), session, 2));
+        }
+
+        // Third should be rejected
+        let addr3 = SocketAddr::V4(SocketAddrV4::new(ip, 12347));
+        let cancel3 = CancellationToken::new();
+        let session3 = make_session(addr3, cancel3);
+        assert!(!table.insert((addr3, 53), session3, 2));
+
+        assert_eq!(table.session_count(), 2);
+    }
+
+    #[test]
+    fn test_session_table_remove() {
+        let table = UdpSessionTable::new();
+        let cancel = CancellationToken::new();
+        let addr = make_addr(12345);
+        let key: SessionKey = (addr, 53);
+        let session = make_session(addr, cancel);
+
+        table.insert(key, session, 1000);
+        assert_eq!(table.session_count(), 1);
+        assert_eq!(table.tracked_ips(), 1);
+
+        table.remove(&key);
+        assert_eq!(table.session_count(), 0);
+        assert_eq!(table.tracked_ips(), 0);
+    }
+
+    #[test]
+    fn test_session_config_defaults() {
+        let config = UdpSessionConfig::default();
+        assert_eq!(config.session_timeout_ms, 60_000);
+        assert_eq!(config.max_sessions_per_ip, 1_000);
+        assert_eq!(config.max_datagram_size, 65_535);
+    }
+
+    #[test]
+    fn test_session_config_from_route() {
+        let route_udp = rustproxy_config::RouteUdp {
+            session_timeout: Some(10_000),
+            max_sessions_per_ip: Some(500),
+            max_datagram_size: Some(1400),
+            quic: None,
+        };
+        let config = UdpSessionConfig::from_route_udp(Some(&route_udp));
+        assert_eq!(config.session_timeout_ms, 10_000);
+        assert_eq!(config.max_sessions_per_ip, 500);
+        assert_eq!(config.max_datagram_size, 1400);
+    }
+}

rust/crates/rustproxy-routing/src/matchers/domain.rs

@@ -6,25 +6,28 @@
 /// - `example.com` exact match
 /// - `**.example.com` matches any depth of subdomain
 pub fn domain_matches(pattern: &str, domain: &str) -> bool {
-    let pattern = pattern.trim().to_lowercase();
-    let domain = domain.trim().to_lowercase();
+    let pattern = pattern.trim();
+    let domain = domain.trim();
 
     if pattern == "*" {
         return true;
     }
 
-    if pattern == domain {
+    if pattern.eq_ignore_ascii_case(domain) {
         return true;
     }
 
     // Wildcard patterns
-    if pattern.starts_with("*.") {
+    if pattern.starts_with("*.") || pattern.starts_with("*.") {
         let suffix = &pattern[2..]; // e.g., "example.com"
         // Match exact parent or any single-level subdomain
-        if domain == suffix {
+        if domain.eq_ignore_ascii_case(suffix) {
             return true;
         }
-        if domain.ends_with(&format!(".{}", suffix)) {
+        if domain.len() > suffix.len() + 1
+            && domain.as_bytes()[domain.len() - suffix.len() - 1] == b'.'
+            && domain[domain.len() - suffix.len()..].eq_ignore_ascii_case(suffix)
+        {
             // Check it's a single level subdomain for `*.`
             let prefix = &domain[..domain.len() - suffix.len() - 1];
             return !prefix.contains('.');
@@ -35,11 +38,22 @@ pub fn domain_matches(pattern: &str, domain: &str) -> bool {
     if pattern.starts_with("**.") {
         let suffix = &pattern[3..];
         // Match exact parent or any depth of subdomain
-        return domain == suffix || domain.ends_with(&format!(".{}", suffix));
+        if domain.eq_ignore_ascii_case(suffix) {
+            return true;
+        }
+        if domain.len() > suffix.len() + 1
+            && domain.as_bytes()[domain.len() - suffix.len() - 1] == b'.'
+            && domain[domain.len() - suffix.len()..].eq_ignore_ascii_case(suffix)
+        {
+            return true;
+        }
+        return false;
     }
 
-    // Use glob-match for more complex patterns
-    glob_match::glob_match(&pattern, &domain)
+    // Use glob-match for more complex patterns (case-insensitive via lowercasing)
+    let pattern_lower = pattern.to_lowercase();
+    let domain_lower = domain.to_lowercase();
+    glob_match::glob_match(&pattern_lower, &domain_lower)
 }
 
 /// Check if a domain matches any of the given patterns.

rust/crates/rustproxy-routing/src/route_manager.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use rustproxy_config::{RouteConfig, RouteTarget, TlsMode};
+use rustproxy_config::{RouteConfig, RouteTarget, TransportProtocol, TlsMode};
 use crate::matchers;
 
 /// Context for route matching (subset of connection info).
@@ -12,8 +12,10 @@ pub struct MatchContext<'a> {
     pub tls_version: Option<&'a str>,
     pub headers: Option<&'a HashMap<String, String>>,
     pub is_tls: bool,
-    /// Detected protocol: "http" or "tcp". None when unknown (e.g. pre-TLS-termination).
+    /// Detected protocol: "http", "tcp", "udp", "quic". None when unknown.
     pub protocol: Option<&'a str>,
+    /// Transport protocol of the listener: None = TCP (backward compat), Some(Udp), Some(All).
+    pub transport: Option<TransportProtocol>,
 }
 
 /// Result of a route match.
@@ -60,6 +62,16 @@ impl RouteManager {
         manager
     }
 
+    /// Check if any route on the given port uses header matching.
+    /// Used to skip expensive header HashMap construction when no route needs it.
+    pub fn any_route_has_headers(&self, port: u16) -> bool {
+        if let Some(indices) = self.port_index.get(&port) {
+            indices.iter().any(|&idx| self.routes[idx].route_match.headers.is_some())
+        } else {
+            false
+        }
+    }
+
     /// Find the best matching route for the given context.
     pub fn find_route<'a>(&'a self, ctx: &MatchContext<'_>) -> Option<RouteMatchResult<'a>> {
         // Get routes for this port
@@ -82,6 +94,22 @@ impl RouteManager {
     fn matches_route(&self, route: &RouteConfig, ctx: &MatchContext<'_>) -> bool {
         let rm = &route.route_match;
 
+        // Transport filtering: ensure route transport matches context transport
+        let route_transport = rm.transport.as_ref();
+        let ctx_transport = ctx.transport.as_ref();
+        match (route_transport, ctx_transport) {
+            // Route requires UDP only — reject non-UDP contexts
+            (Some(TransportProtocol::Udp), None) |
+            (Some(TransportProtocol::Udp), Some(TransportProtocol::Tcp)) => return false,
+            // Route requires TCP only — reject UDP contexts
+            (Some(TransportProtocol::Tcp), Some(TransportProtocol::Udp)) => return false,
+            // Route has no transport (default = TCP) — reject UDP contexts
+            (None, Some(TransportProtocol::Udp)) => return false,
+            // All other combinations match: All matches everything, same transport matches,
+            // None + None/Tcp matches (backward compat)
+            _ => {}
+        }
+
         // Domain matching
         if let Some(ref domains) = rm.domains {
             if let Some(domain) = ctx.domain {
@@ -94,10 +122,16 @@ impl RouteManager {
                 // This prevents session-ticket resumption from misrouting when clients
                 // omit SNI (RFC 8446 recommends but doesn't mandate SNI on resumption).
                 // Wildcard-only routes (domains: ["*"]) still match since they accept all.
-                let patterns = domains.to_vec();
-                let is_wildcard_only = patterns.iter().all(|d| *d == "*");
-                if !is_wildcard_only {
-                    return false;
+                //
+                // Exception: QUIC (UDP transport) encrypts the TLS ClientHello, so SNI
+                // is unavailable at accept time. Domain verification happens per-request
+                // in H3ProxyService via the :authority header.
+                if ctx.transport != Some(TransportProtocol::Udp) {
+                    let patterns = domains.to_vec();
+                    let is_wildcard_only = patterns.iter().all(|d| *d == "*");
+                    if !is_wildcard_only {
+                        return false;
+                    }
                 }
             }
         }
@@ -293,6 +327,7 @@ mod tests {
             id: None,
             route_match: RouteMatch {
                 ports: PortRange::Single(port),
+                transport: None,
                 domains: domain.map(|d| DomainSpec::Single(d.to_string())),
                 path: None,
                 client_ip: None,
@@ -312,6 +347,7 @@ mod tests {
                     send_proxy_protocol: None,
                     headers: None,
                     advanced: None,
+                    backend_transport: None,
                     priority: None,
                 }]),
                 tls: None,
@@ -322,6 +358,7 @@ mod tests {
                 forwarding_engine: None,
                 nftables: None,
                 send_proxy_protocol: None,
+                udp: None,
             },
             headers: None,
             security: None,
@@ -350,6 +387,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         let result = manager.find_route(&ctx);
@@ -373,6 +411,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         let result = manager.find_route(&ctx).unwrap();
@@ -397,6 +436,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_none());
@@ -483,6 +523,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_some());
@@ -503,6 +544,7 @@ mod tests {
             headers: None,
             is_tls: true,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_none());
@@ -523,6 +565,7 @@ mod tests {
             headers: None,
             is_tls: true,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_none());
@@ -543,6 +586,7 @@ mod tests {
             headers: None,
             is_tls: true,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_some());
@@ -567,6 +611,7 @@ mod tests {
             headers: None,
             is_tls: true,
             protocol: None,
+            transport: None,
         };
 
         let result = manager.find_route(&ctx);
@@ -592,6 +637,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_some());
@@ -611,6 +657,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
 
         assert!(manager.find_route(&ctx).is_some());
@@ -635,6 +682,7 @@ mod tests {
                 send_proxy_protocol: None,
                 headers: None,
                 advanced: None,
+                backend_transport: None,
                 priority: Some(10),
             },
             RouteTarget {
@@ -647,6 +695,7 @@ mod tests {
                 send_proxy_protocol: None,
                 headers: None,
                 advanced: None,
+                backend_transport: None,
                 priority: None,
             },
         ]);
@@ -662,6 +711,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
         let result = manager.find_route(&ctx).unwrap();
         assert_eq!(result.target.unwrap().host.first(), "api-backend");
@@ -676,6 +726,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: None,
+            transport: None,
         };
         let result = manager.find_route(&ctx).unwrap();
         assert_eq!(result.target.unwrap().host.first(), "default-backend");
@@ -701,6 +752,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: Some("http"),
+            transport: None,
         };
         assert!(manager.find_route(&ctx).is_some());
     }
@@ -719,6 +771,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: Some("tcp"),
+            transport: None,
         };
         assert!(manager.find_route(&ctx).is_none());
     }
@@ -738,6 +791,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: Some("http"),
+            transport: None,
         };
         assert!(manager.find_route(&ctx_http).is_some());
 
@@ -750,6 +804,7 @@ mod tests {
             headers: None,
             is_tls: false,
             protocol: Some("tcp"),
+            transport: None,
         };
         assert!(manager.find_route(&ctx_tcp).is_some());
     }
@@ -770,7 +825,230 @@ mod tests {
             headers: None,
             is_tls: true,
             protocol: None,
+            transport: None,
         };
         assert!(manager.find_route(&ctx).is_some());
     }
+
+    // ===== Transport filtering tests =====
+
+    fn make_route_with_transport(port: u16, transport: Option<TransportProtocol>) -> RouteConfig {
+        let mut route = make_route(port, None, 0);
+        route.route_match.transport = transport;
+        route
+    }
+
+    #[test]
+    fn test_transport_udp_route_matches_udp_context() {
+        let routes = vec![make_route_with_transport(53, Some(TransportProtocol::Udp))];
+        let manager = RouteManager::new(routes);
+
+        let ctx = MatchContext {
+            port: 53,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: Some("udp"),
+            transport: Some(TransportProtocol::Udp),
+        };
+        assert!(manager.find_route(&ctx).is_some());
+    }
+
+    #[test]
+    fn test_transport_udp_route_rejects_tcp_context() {
+        let routes = vec![make_route_with_transport(53, Some(TransportProtocol::Udp))];
+        let manager = RouteManager::new(routes);
+
+        // TCP context (transport: None = TCP)
+        let ctx = MatchContext {
+            port: 53,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: None,
+            transport: None,
+        };
+        assert!(manager.find_route(&ctx).is_none());
+    }
+
+    #[test]
+    fn test_transport_tcp_route_rejects_udp_context() {
+        let routes = vec![make_route_with_transport(80, Some(TransportProtocol::Tcp))];
+        let manager = RouteManager::new(routes);
+
+        let ctx = MatchContext {
+            port: 80,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: Some("udp"),
+            transport: Some(TransportProtocol::Udp),
+        };
+        assert!(manager.find_route(&ctx).is_none());
+    }
+
+    #[test]
+    fn test_transport_all_matches_both() {
+        let routes = vec![make_route_with_transport(443, Some(TransportProtocol::All))];
+        let manager = RouteManager::new(routes);
+
+        // TCP context
+        let tcp_ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: None,
+            transport: None,
+        };
+        assert!(manager.find_route(&tcp_ctx).is_some());
+
+        // UDP context
+        let udp_ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: Some("udp"),
+            transport: Some(TransportProtocol::Udp),
+        };
+        assert!(manager.find_route(&udp_ctx).is_some());
+    }
+
+    #[test]
+    fn test_transport_none_default_matches_tcp_only() {
+        // Route with no transport field = TCP only (backward compat)
+        let routes = vec![make_route_with_transport(80, None)];
+        let manager = RouteManager::new(routes);
+
+        // TCP context should match
+        let tcp_ctx = MatchContext {
+            port: 80,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: None,
+            transport: None,
+        };
+        assert!(manager.find_route(&tcp_ctx).is_some());
+
+        // UDP context should NOT match
+        let udp_ctx = MatchContext {
+            port: 80,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: Some("udp"),
+            transport: Some(TransportProtocol::Udp),
+        };
+        assert!(manager.find_route(&udp_ctx).is_none());
+    }
+
+    #[test]
+    fn test_transport_mixed_routes_same_port() {
+        // TCP and UDP routes on the same port — each matches only its transport
+        let mut tcp_route = make_route_with_transport(443, Some(TransportProtocol::Tcp));
+        tcp_route.name = Some("tcp-route".to_string());
+        let mut udp_route = make_route_with_transport(443, Some(TransportProtocol::Udp));
+        udp_route.name = Some("udp-route".to_string());
+
+        let manager = RouteManager::new(vec![tcp_route, udp_route]);
+
+        let tcp_ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: None,
+            transport: None,
+        };
+        let result = manager.find_route(&tcp_ctx).unwrap();
+        assert_eq!(result.route.name.as_deref(), Some("tcp-route"));
+
+        let udp_ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: false,
+            protocol: Some("udp"),
+            transport: Some(TransportProtocol::Udp),
+        };
+        let result = manager.find_route(&udp_ctx).unwrap();
+        assert_eq!(result.route.name.as_deref(), Some("udp-route"));
+    }
+
+    #[test]
+    fn test_quic_tls_no_sni_matches_domain_restricted_route() {
+        // QUIC accept-level matching: is_tls=true, domain=None, transport=Udp.
+        // Should match because QUIC encrypts the ClientHello — SNI is unavailable
+        // at accept time but verified per-request in H3ProxyService.
+        let mut route = make_route(443, Some("example.com"), 0);
+        route.route_match.transport = Some(TransportProtocol::Udp);
+        let routes = vec![route];
+        let manager = RouteManager::new(routes);
+
+        let ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: true,
+            protocol: Some("quic"),
+            transport: Some(TransportProtocol::Udp),
+        };
+
+        assert!(manager.find_route(&ctx).is_some(),
+            "QUIC (UDP) with is_tls=true and domain=None should match domain-restricted routes");
+    }
+
+    #[test]
+    fn test_tcp_tls_no_sni_still_rejects_domain_restricted_route() {
+        // TCP TLS without SNI must still be rejected (no QUIC exemption).
+        let routes = vec![make_route(443, Some("example.com"), 0)];
+        let manager = RouteManager::new(routes);
+
+        let ctx = MatchContext {
+            port: 443,
+            domain: None,
+            path: None,
+            client_ip: None,
+            tls_version: None,
+            headers: None,
+            is_tls: true,
+            protocol: None,
+            transport: None, // TCP (default)
+        };
+
+        assert!(manager.find_route(&ctx).is_none(),
+            "TCP TLS without SNI should NOT match domain-restricted routes");
+    }
 }

rust/crates/rustproxy/Cargo.toml

@@ -32,6 +32,7 @@ arc-swap = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 rustls = { workspace = true }
+rustls-pemfile = { workspace = true }
 tokio-rustls = { workspace = true }
 tokio-util = { workspace = true }
 dashmap = { workspace = true }
@@ -43,3 +44,9 @@ mimalloc = { workspace = true }
 
 [dev-dependencies]
 rcgen = { workspace = true }
+quinn = { workspace = true }
+h3 = { workspace = true }
+h3-quinn = { workspace = true }
+bytes = { workspace = true }
+rustls = { workspace = true }
+http = "1"

rust/crates/rustproxy/src/lib.rs

@@ -47,7 +47,7 @@ pub use rustproxy_security;
 
 use rustproxy_config::{RouteConfig, RustProxyOptions, TlsMode, CertificateSpec, ForwardingEngine};
 use rustproxy_routing::RouteManager;
-use rustproxy_passthrough::{TcpListenerManager, TlsCertConfig, ConnectionConfig};
+use rustproxy_passthrough::{TcpListenerManager, UdpListenerManager, TlsCertConfig, ConnectionConfig};
 use rustproxy_metrics::{MetricsCollector, Metrics, Statistics};
 use rustproxy_tls::{CertManager, CertStore, CertBundle, CertMetadata, CertSource};
 use rustproxy_nftables::{NftManager, rule_builder};
@@ -68,6 +68,7 @@ pub struct RustProxy {
     options: RustProxyOptions,
     route_table: ArcSwap<RouteManager>,
     listener_manager: Option<TcpListenerManager>,
+    udp_listener_manager: Option<UdpListenerManager>,
     metrics: Arc<MetricsCollector>,
     cert_manager: Option<Arc<tokio::sync::Mutex<CertManager>>>,
     challenge_server: Option<challenge_server::ChallengeServer>,
@@ -114,6 +115,7 @@ impl RustProxy {
             options,
             route_table: ArcSwap::from(Arc::new(route_manager)),
             listener_manager: None,
+            udp_listener_manager: None,
             metrics: Arc::new(MetricsCollector::with_retention(retention)),
             cert_manager,
             challenge_server: None,
@@ -153,6 +155,7 @@ impl RustProxy {
                             send_proxy_protocol: None,
                             headers: None,
                             advanced: None,
+                            backend_transport: None,
                             priority: None,
                         }
                     ]);
@@ -261,6 +264,8 @@ impl RustProxy {
             conn_config.socket_timeout_ms,
             conn_config.max_connection_lifetime_ms,
         );
+        // Clone proxy_ips before conn_config is moved into the TCP listener
+        let udp_proxy_ips = conn_config.proxy_ips.clone();
         listener.set_connection_config(conn_config);
 
         // Share the socket-handler relay path with the listener
@@ -289,17 +294,69 @@ impl RustProxy {
             }
         }
 
+        // Build QUIC TLS config before set_tls_configs consumes the map
+        let quic_tls_config = Self::build_quic_tls_config(&tls_configs);
+
         if !tls_configs.is_empty() {
             debug!("Loaded TLS certificates for {} domains", tls_configs.len());
             listener.set_tls_configs(tls_configs);
         }
 
-        // Bind all ports
-        for port in &ports {
+        // Determine which ports need TCP vs UDP based on route transport config
+        let mut tcp_ports = std::collections::HashSet::new();
+        let mut udp_ports = std::collections::HashSet::new();
+        for route in &self.options.routes {
+            if !route.is_enabled() { continue; }
+            let transport = route.route_match.transport.as_ref();
+            let route_ports = route.route_match.ports.to_ports();
+            for port in route_ports {
+                match transport {
+                    Some(rustproxy_config::TransportProtocol::Udp) => {
+                        udp_ports.insert(port);
+                    }
+                    Some(rustproxy_config::TransportProtocol::All) => {
+                        tcp_ports.insert(port);
+                        udp_ports.insert(port);
+                    }
+                    Some(rustproxy_config::TransportProtocol::Tcp) | None => {
+                        tcp_ports.insert(port);
+                    }
+                }
+            }
+        }
+
+        // Bind TCP ports
+        for port in &tcp_ports {
             listener.add_port(*port).await?;
         }
 
         self.listener_manager = Some(listener);
+
+        // Bind UDP ports (if any)
+        if !udp_ports.is_empty() {
+            let conn_tracker = self.listener_manager.as_ref().unwrap().conn_tracker().clone();
+            let mut udp_mgr = UdpListenerManager::new(
+                Arc::clone(&*self.route_table.load()),
+                Arc::clone(&self.metrics),
+                conn_tracker,
+                self.cancel_token.clone(),
+            );
+            udp_mgr.set_proxy_ips(udp_proxy_ips.clone());
+
+            // Share HttpProxyService with H3 — same route matching, connection
+            // pool, and ALPN protocol detection as the TCP/HTTP path.
+            let http_proxy = self.listener_manager.as_ref().unwrap().http_proxy().clone();
+            let h3_svc = rustproxy_http::h3_service::H3ProxyService::new(http_proxy);
+            udp_mgr.set_h3_service(Arc::new(h3_svc));
+
+            for port in &udp_ports {
+                udp_mgr.add_port_with_tls(*port, quic_tls_config.clone()).await?;
+            }
+            info!("UDP listeners started on {} ports: {:?}",
+                udp_ports.len(), udp_mgr.listening_ports());
+            self.udp_listener_manager = Some(udp_mgr);
+        }
+
         self.started = true;
         self.started_at = Some(Instant::now());
 
@@ -567,6 +624,13 @@ impl RustProxy {
             listener.graceful_stop().await;
         }
         self.listener_manager = None;
+
+        // Stop UDP listeners
+        if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+            udp_mgr.stop().await;
+        }
+        self.udp_listener_manager = None;
+
         self.started = false;
         // Reset cancel token so proxy can be restarted
         self.cancel_token = CancellationToken::new();
@@ -681,6 +745,82 @@ impl RustProxy {
             }
         }
 
+        // Reconcile UDP ports
+        {
+            let mut new_udp_ports = HashSet::new();
+            for route in &routes {
+                if !route.is_enabled() { continue; }
+                let transport = route.route_match.transport.as_ref();
+                match transport {
+                    Some(rustproxy_config::TransportProtocol::Udp) |
+                    Some(rustproxy_config::TransportProtocol::All) => {
+                        for port in route.route_match.ports.to_ports() {
+                            new_udp_ports.insert(port);
+                        }
+                    }
+                    _ => {}
+                }
+            }
+
+            let old_udp_ports: HashSet<u16> = self.udp_listener_manager
+                .as_ref()
+                .map(|u| u.listening_ports().into_iter().collect())
+                .unwrap_or_default();
+
+            if !new_udp_ports.is_empty() {
+                // Ensure UDP manager exists
+                if self.udp_listener_manager.is_none() {
+                    if let Some(ref listener) = self.listener_manager {
+                        let conn_tracker = listener.conn_tracker().clone();
+                        let conn_config = Self::build_connection_config(&self.options);
+                        let mut udp_mgr = UdpListenerManager::new(
+                            Arc::clone(&new_manager),
+                            Arc::clone(&self.metrics),
+                            conn_tracker,
+                            self.cancel_token.clone(),
+                        );
+                        udp_mgr.set_proxy_ips(conn_config.proxy_ips);
+                        self.udp_listener_manager = Some(udp_mgr);
+                    }
+                }
+
+                // Build TLS config for QUIC (needed for new ports and upgrading existing raw UDP)
+                let quic_tls = {
+                    let tls_configs = self.current_tls_configs().await;
+                    Self::build_quic_tls_config(&tls_configs)
+                };
+
+                if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+                    udp_mgr.update_routes(Arc::clone(&new_manager));
+
+                    // Add new UDP ports (with TLS for QUIC)
+                    for port in &new_udp_ports {
+                        if !old_udp_ports.contains(port) {
+                            udp_mgr.add_port_with_tls(*port, quic_tls.clone()).await?;
+                        }
+                    }
+                    // Remove old UDP ports
+                    for port in &old_udp_ports {
+                        if !new_udp_ports.contains(port) {
+                            udp_mgr.remove_port(*port);
+                        }
+                    }
+
+                    // Upgrade existing raw UDP fallback listeners to QUIC if TLS is now available
+                    if let Some(ref quic_config) = quic_tls {
+                        udp_mgr.update_quic_tls(Arc::clone(quic_config));
+                        udp_mgr.upgrade_raw_to_quic(Arc::clone(quic_config)).await;
+                    }
+                }
+            } else if self.udp_listener_manager.is_some() {
+                // All UDP routes removed — shut down UDP manager
+                if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+                    udp_mgr.stop().await;
+                }
+                self.udp_listener_manager = None;
+            }
+        }
+
         // Update NFTables rules: remove old, apply new
         self.update_nftables_rules(&routes).await;
 
@@ -727,12 +867,12 @@ impl RustProxy {
             .map_err(|e| anyhow::anyhow!("ACME provisioning failed: {}", e))?;
 
         // Hot-swap into TLS configs
-        if let Some(ref mut listener) = self.listener_manager {
-            let mut tls_configs = Self::extract_tls_configs(&self.options.routes);
-            tls_configs.insert(domain.clone(), TlsCertConfig {
-                cert_pem: bundle.cert_pem.clone(),
-                key_pem: bundle.key_pem.clone(),
-            });
+        let mut tls_configs = Self::extract_tls_configs(&self.options.routes);
+        tls_configs.insert(domain.clone(), TlsCertConfig {
+            cert_pem: bundle.cert_pem.clone(),
+            key_pem: bundle.key_pem.clone(),
+        });
+        {
             let cm = cm_arc.lock().await;
             for (d, b) in cm.store().iter() {
                 if !tls_configs.contains_key(d) {
@@ -742,9 +882,22 @@ impl RustProxy {
                     });
                 }
             }
+        }
+
+        let quic_tls = Self::build_quic_tls_config(&tls_configs);
+
+        if let Some(ref listener) = self.listener_manager {
             listener.set_tls_configs(tls_configs);
         }
 
+        // Update existing QUIC endpoints and upgrade raw UDP fallback listeners
+        if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+            if let Some(ref quic_config) = quic_tls {
+                udp_mgr.update_quic_tls(Arc::clone(quic_config));
+                udp_mgr.upgrade_raw_to_quic(Arc::clone(quic_config)).await;
+            }
+        }
+
         info!("Certificate provisioned and loaded for route '{}'", route_name);
         Ok(())
     }
@@ -840,6 +993,73 @@ impl RustProxy {
         self.socket_handler_relay.read().unwrap().clone()
     }
 
+    /// Build a rustls ServerConfig suitable for QUIC (TLS 1.3 only, h3 ALPN).
+    /// Uses the first available cert from tls_configs, or returns None if no certs available.
+    fn build_quic_tls_config(
+        tls_configs: &HashMap<String, TlsCertConfig>,
+    ) -> Option<Arc<rustls::ServerConfig>> {
+        if tls_configs.is_empty() {
+            return None;
+        }
+
+        // Reuse CertResolver for SNI-based cert selection (same as TCP/TLS path).
+        // This ensures QUIC connections get the correct certificate for each domain
+        // instead of a single static cert.
+        let resolver = match rustproxy_passthrough::tls_handler::CertResolver::new(tls_configs) {
+            Ok(r) => r,
+            Err(e) => {
+                warn!("Failed to build QUIC cert resolver: {}", e);
+                return None;
+            }
+        };
+
+        let mut tls_config = rustls::ServerConfig::builder()
+            .with_no_client_auth()
+            .with_cert_resolver(Arc::new(resolver));
+
+        // QUIC requires h3 ALPN
+        tls_config.alpn_protocols = vec![b"h3".to_vec()];
+
+        Some(Arc::new(tls_config))
+    }
+
+    /// Build the current full TLS config map from all sources (route configs, loaded certs, cert manager).
+    async fn current_tls_configs(&self) -> HashMap<String, TlsCertConfig> {
+        let mut configs = Self::extract_tls_configs(&self.options.routes);
+
+        // Merge dynamically loaded certs (from loadCertificate IPC)
+        for (d, c) in &self.loaded_certs {
+            if !configs.contains_key(d) {
+                configs.insert(d.clone(), c.clone());
+            }
+        }
+
+        // Merge certs from cert manager store
+        if let Some(ref cm_arc) = self.cert_manager {
+            let cm = cm_arc.lock().await;
+            for (d, b) in cm.store().iter() {
+                if !configs.contains_key(d) {
+                    configs.insert(d.clone(), TlsCertConfig {
+                        cert_pem: b.cert_pem.clone(),
+                        key_pem: b.key_pem.clone(),
+                    });
+                }
+            }
+        }
+
+        configs
+    }
+
+    /// Set the Unix domain socket path for relaying UDP datagrams to TypeScript datagramHandler callbacks.
+    pub async fn set_datagram_handler_relay_path(&mut self, path: Option<String>) {
+        info!("Datagram handler relay path set to: {:?}", path);
+        if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+            if let Some(ref p) = path {
+                udp_mgr.set_datagram_handler_relay(p.clone()).await;
+            }
+        }
+    }
+
     /// Load a certificate for a domain and hot-swap the TLS configuration.
     pub async fn load_certificate(
         &mut self,
@@ -880,39 +1100,24 @@ impl RustProxy {
             key_pem: key_pem.clone(),
         });
 
-        // Hot-swap TLS config on the listener
-        if let Some(ref mut listener) = self.listener_manager {
-            let mut tls_configs = Self::extract_tls_configs(&self.options.routes);
+        // Hot-swap TLS config on TCP and QUIC listeners
+        let tls_configs = self.current_tls_configs().await;
 
-            // Add the new cert
-            tls_configs.insert(domain.to_string(), TlsCertConfig {
-                cert_pem: cert_pem.clone(),
-                key_pem: key_pem.clone(),
-            });
-
-            // Also include all existing certs from cert manager
-            if let Some(ref cm_arc) = self.cert_manager {
-                let cm = cm_arc.lock().await;
-                for (d, b) in cm.store().iter() {
-                    if !tls_configs.contains_key(d) {
-                        tls_configs.insert(d.clone(), TlsCertConfig {
-                            cert_pem: b.cert_pem.clone(),
-                            key_pem: b.key_pem.clone(),
-                        });
-                    }
-                }
-            }
-
-            // Merge dynamically loaded certs from previous loadCertificate calls
-            for (d, c) in &self.loaded_certs {
-                if !tls_configs.contains_key(d) {
-                    tls_configs.insert(d.clone(), c.clone());
-                }
-            }
+        // Build QUIC TLS config before TCP consumes the map
+        let quic_tls = Self::build_quic_tls_config(&tls_configs);
 
+        if let Some(ref listener) = self.listener_manager {
             listener.set_tls_configs(tls_configs);
         }
 
+        // Update existing QUIC endpoints and upgrade raw UDP fallback listeners
+        if let Some(ref mut udp_mgr) = self.udp_listener_manager {
+            if let Some(ref quic_config) = quic_tls {
+                udp_mgr.update_quic_tls(Arc::clone(quic_config));
+                udp_mgr.upgrade_raw_to_quic(Arc::clone(quic_config)).await;
+            }
+        }
+
         info!("Certificate loaded and TLS config updated for {}", domain);
         Ok(())
     }

rust/crates/rustproxy/src/management.rs

@@ -149,6 +149,7 @@ async fn handle_request(
         "getListeningPorts" => handle_get_listening_ports(&id, proxy),
         "getNftablesStatus" => handle_get_nftables_status(&id, proxy).await,
         "setSocketHandlerRelay" => handle_set_socket_handler_relay(&id, &request.params, proxy).await,
+        "setDatagramHandlerRelay" => handle_set_datagram_handler_relay(&id, &request.params, proxy).await,
         "addListeningPort" => handle_add_listening_port(&id, &request.params, proxy).await,
         "removeListeningPort" => handle_remove_listening_port(&id, &request.params, proxy).await,
         "loadCertificate" => handle_load_certificate(&id, &request.params, proxy).await,
@@ -391,6 +392,26 @@ async fn handle_set_socket_handler_relay(
     ManagementResponse::ok(id.to_string(), serde_json::json!({}))
 }
 
+async fn handle_set_datagram_handler_relay(
+    id: &str,
+    params: &serde_json::Value,
+    proxy: &mut Option<RustProxy>,
+) -> ManagementResponse {
+    let p = match proxy.as_mut() {
+        Some(p) => p,
+        None => return ManagementResponse::err(id.to_string(), "Proxy is not running".to_string()),
+    };
+
+    let socket_path = params.get("socketPath")
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+
+    info!("setDatagramHandlerRelay: socket_path={:?}", socket_path);
+    p.set_datagram_handler_relay_path(socket_path).await;
+
+    ManagementResponse::ok(id.to_string(), serde_json::json!({}))
+}
+
 async fn handle_add_listening_port(
     id: &str,
     params: &serde_json::Value,

rust/crates/rustproxy/tests/common/mod.rs

@@ -269,6 +269,7 @@ pub fn make_test_route(
         id: None,
         route_match: rustproxy_config::RouteMatch {
             ports: rustproxy_config::PortRange::Single(port),
+            transport: None,
             domains: domain.map(|d| rustproxy_config::DomainSpec::Single(d.to_string())),
             path: None,
             client_ip: None,
@@ -288,6 +289,7 @@ pub fn make_test_route(
                 send_proxy_protocol: None,
                 headers: None,
                 advanced: None,
+                backend_transport: None,
                 priority: None,
             }]),
             tls: None,
@@ -298,6 +300,7 @@ pub fn make_test_route(
             forwarding_engine: None,
             nftables: None,
             send_proxy_protocol: None,
+            udp: None,
         },
         headers: None,
         security: None,

rust/crates/rustproxy/tests/integration_h3_proxy.rs

@@ -0,0 +1,195 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::{RustProxyOptions, TransportProtocol, RouteUdp, RouteQuic};
+use bytes::Buf;
+use std::sync::Arc;
+
+/// Build a route that listens on UDP with HTTP/3 enabled and TLS terminate.
+fn make_h3_route(
+    port: u16,
+    target_host: &str,
+    target_port: u16,
+    cert_pem: &str,
+    key_pem: &str,
+) -> rustproxy_config::RouteConfig {
+    let mut route = make_tls_terminate_route(port, "localhost", target_host, target_port, cert_pem, key_pem);
+    route.route_match.transport = Some(TransportProtocol::All);
+    // Keep domain="localhost" from make_tls_terminate_route — needed for TLS cert extraction
+    route.action.udp = Some(RouteUdp {
+        session_timeout: None,
+        max_sessions_per_ip: None,
+        max_datagram_size: None,
+        quic: Some(RouteQuic {
+            max_idle_timeout: Some(30000),
+            max_concurrent_bidi_streams: None,
+            max_concurrent_uni_streams: None,
+            enable_http3: Some(true),
+            alt_svc_port: None,
+            alt_svc_max_age: None,
+            initial_congestion_window: None,
+        }),
+    });
+    route
+}
+
+/// Build a quinn client endpoint with insecure TLS for testing.
+fn make_h3_client_endpoint() -> quinn::Endpoint {
+    let mut tls_config = rustls::ClientConfig::builder()
+        .dangerous()
+        .with_custom_certificate_verifier(Arc::new(InsecureVerifier))
+        .with_no_client_auth();
+    tls_config.alpn_protocols = vec![b"h3".to_vec()];
+
+    let quic_client_config = quinn::crypto::rustls::QuicClientConfig::try_from(tls_config)
+        .expect("Failed to build QUIC client config");
+    let client_config = quinn::ClientConfig::new(Arc::new(quic_client_config));
+
+    let mut endpoint = quinn::Endpoint::client("0.0.0.0:0".parse().unwrap())
+        .expect("Failed to create QUIC client endpoint");
+    endpoint.set_default_client_config(client_config);
+    endpoint
+}
+
+/// Test that HTTP/3 response streams properly finish (FIN is received by client).
+///
+/// This is the critical regression test for the FIN bug: the proxy must send
+/// a QUIC stream FIN after the response body so the client's `recv_data()`
+/// returns `None` instead of hanging forever.
+#[tokio::test]
+async fn test_h3_response_stream_finishes() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let body_text = "Hello from HTTP/3 backend! This body has a known length for testing.";
+
+    // 1. Start plain HTTP backend with known body + content-length
+    let _backend = start_http_server(backend_port, 200, body_text).await;
+
+    // 2. Generate self-signed cert and configure H3 route
+    let (cert_pem, key_pem) = generate_self_signed_cert("localhost");
+    let route = make_h3_route(proxy_port, "127.0.0.1", backend_port, &cert_pem, &key_pem);
+
+    let options = RustProxyOptions {
+        routes: vec![route],
+        ..Default::default()
+    };
+
+    // 3. Start proxy and wait for UDP bind
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+
+    // 4. Connect QUIC/H3 client
+    let endpoint = make_h3_client_endpoint();
+    let addr: std::net::SocketAddr = format!("127.0.0.1:{}", proxy_port).parse().unwrap();
+    let connection = endpoint
+        .connect(addr, "localhost")
+        .expect("Failed to initiate QUIC connection")
+        .await
+        .expect("QUIC handshake failed");
+
+    let (mut driver, mut send_request) = h3::client::new(
+        h3_quinn::Connection::new(connection),
+    )
+    .await
+    .expect("H3 connection setup failed");
+
+    // Drive the H3 connection in background
+    tokio::spawn(async move {
+        let _ = driver.wait_idle().await;
+    });
+
+    // 5. Send GET request
+    let req = http::Request::builder()
+        .method("GET")
+        .uri("https://localhost/")
+        .header("host", "localhost")
+        .body(())
+        .unwrap();
+
+    let mut stream = send_request.send_request(req).await
+        .expect("Failed to send H3 request");
+    stream.finish().await
+        .expect("Failed to finish sending H3 request body");
+
+    // 6. Read response headers
+    let resp = stream.recv_response().await
+        .expect("Failed to receive H3 response");
+    assert_eq!(resp.status(), http::StatusCode::OK,
+        "Expected 200 OK, got {}", resp.status());
+
+    // 7. Read body and verify stream ends (FIN received)
+    //    This is the critical assertion: recv_data() must return None (stream ended)
+    //    within the timeout, NOT hang forever waiting for a FIN that never arrives.
+    let result = with_timeout(async {
+        let mut total = 0usize;
+        while let Some(chunk) = stream.recv_data().await.expect("H3 data receive error") {
+            total += chunk.remaining();
+        }
+        // recv_data() returned None => stream ended (FIN received)
+        total
+    }, 10)
+    .await;
+
+    let bytes_received = result.expect(
+        "TIMEOUT: H3 stream never ended (FIN not received by client). \
+         The proxy sent all response data but failed to send the QUIC stream FIN."
+    );
+    assert_eq!(
+        bytes_received,
+        body_text.len(),
+        "Expected {} bytes, got {}",
+        body_text.len(),
+        bytes_received
+    );
+
+    // 8. Cleanup
+    endpoint.close(quinn::VarInt::from_u32(0), b"test done");
+    proxy.stop().await.unwrap();
+}
+
+/// Insecure TLS verifier that accepts any certificate (for tests only).
+#[derive(Debug)]
+struct InsecureVerifier;
+
+impl rustls::client::danger::ServerCertVerifier for InsecureVerifier {
+    fn verify_server_cert(
+        &self,
+        _end_entity: &rustls::pki_types::CertificateDer<'_>,
+        _intermediates: &[rustls::pki_types::CertificateDer<'_>],
+        _server_name: &rustls::pki_types::ServerName<'_>,
+        _ocsp_response: &[u8],
+        _now: rustls::pki_types::UnixTime,
+    ) -> Result<rustls::client::danger::ServerCertVerified, rustls::Error> {
+        Ok(rustls::client::danger::ServerCertVerified::assertion())
+    }
+
+    fn verify_tls12_signature(
+        &self,
+        _message: &[u8],
+        _cert: &rustls::pki_types::CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn verify_tls13_signature(
+        &self,
+        _message: &[u8],
+        _cert: &rustls::pki_types::CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn supported_verify_schemes(&self) -> Vec<rustls::SignatureScheme> {
+        vec![
+            rustls::SignatureScheme::RSA_PKCS1_SHA256,
+            rustls::SignatureScheme::ECDSA_NISTP256_SHA256,
+            rustls::SignatureScheme::ECDSA_NISTP384_SHA384,
+            rustls::SignatureScheme::ED25519,
+            rustls::SignatureScheme::RSA_PSS_SHA256,
+        ]
+    }
+}

test/core/utils/test.async-utils.ts

@@ -1,200 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { 
-  delay, 
-  retryWithBackoff, 
-  withTimeout, 
-  parallelLimit,
-  debounceAsync,
-  AsyncMutex,
-  CircuitBreaker
-} from '../../../ts/core/utils/async-utils.js';
-
-tap.test('delay should pause execution for specified milliseconds', async () => {
-  const startTime = Date.now();
-  await delay(100);
-  const elapsed = Date.now() - startTime;
-  
-  // Allow some tolerance for timing
-  expect(elapsed).toBeGreaterThan(90);
-  expect(elapsed).toBeLessThan(150);
-});
-
-tap.test('retryWithBackoff should retry failed operations', async () => {
-  let attempts = 0;
-  const operation = async () => {
-    attempts++;
-    if (attempts < 3) {
-      throw new Error('Test error');
-    }
-    return 'success';
-  };
-  
-  const result = await retryWithBackoff(operation, {
-    maxAttempts: 3,
-    initialDelay: 10
-  });
-  
-  expect(result).toEqual('success');
-  expect(attempts).toEqual(3);
-});
-
-tap.test('retryWithBackoff should throw after max attempts', async () => {
-  let attempts = 0;
-  const operation = async () => {
-    attempts++;
-    throw new Error('Always fails');
-  };
-  
-  let error: Error | null = null;
-  try {
-    await retryWithBackoff(operation, {
-      maxAttempts: 2,
-      initialDelay: 10
-    });
-  } catch (e: any) {
-    error = e;
-  }
-  
-  expect(error).not.toBeNull();
-  expect(error?.message).toEqual('Always fails');
-  expect(attempts).toEqual(2);
-});
-
-tap.test('withTimeout should complete operations within timeout', async () => {
-  const operation = async () => {
-    await delay(50);
-    return 'completed';
-  };
-  
-  const result = await withTimeout(operation, 100);
-  expect(result).toEqual('completed');
-});
-
-tap.test('withTimeout should throw on timeout', async () => {
-  const operation = async () => {
-    await delay(200);
-    return 'never happens';
-  };
-  
-  let error: Error | null = null;
-  try {
-    await withTimeout(operation, 50);
-  } catch (e: any) {
-    error = e;
-  }
-  
-  expect(error).not.toBeNull();
-  expect(error?.message).toContain('timed out');
-});
-
-tap.test('parallelLimit should respect concurrency limit', async () => {
-  let concurrent = 0;
-  let maxConcurrent = 0;
-  
-  const items = [1, 2, 3, 4, 5, 6];
-  const operation = async (item: number) => {
-    concurrent++;
-    maxConcurrent = Math.max(maxConcurrent, concurrent);
-    await delay(50);
-    concurrent--;
-    return item * 2;
-  };
-  
-  const results = await parallelLimit(items, operation, 2);
-  
-  expect(results).toEqual([2, 4, 6, 8, 10, 12]);
-  expect(maxConcurrent).toBeLessThan(3);
-  expect(maxConcurrent).toBeGreaterThan(0);
-});
-
-tap.test('debounceAsync should debounce function calls', async () => {
-  let callCount = 0;
-  const fn = async (value: string) => {
-    callCount++;
-    return value;
-  };
-  
-  const debounced = debounceAsync(fn, 50);
-  
-  // Make multiple calls quickly
-  debounced('a');
-  debounced('b');
-  debounced('c');
-  const result = await debounced('d');
-  
-  // Wait a bit to ensure no more calls
-  await delay(100);
-  
-  expect(result).toEqual('d');
-  expect(callCount).toEqual(1); // Only the last call should execute
-});
-
-tap.test('AsyncMutex should ensure exclusive access', async () => {
-  const mutex = new AsyncMutex();
-  const results: number[] = [];
-  
-  const operation = async (value: number) => {
-    await mutex.runExclusive(async () => {
-      results.push(value);
-      await delay(10);
-      results.push(value * 10);
-    });
-  };
-  
-  // Run operations concurrently
-  await Promise.all([
-    operation(1),
-    operation(2),
-    operation(3)
-  ]);
-  
-  // Results should show sequential execution
-  expect(results).toEqual([1, 10, 2, 20, 3, 30]);
-});
-
-tap.test('CircuitBreaker should open after failures', async () => {
-  const breaker = new CircuitBreaker({
-    failureThreshold: 2,
-    resetTimeout: 100
-  });
-  
-  let attempt = 0;
-  const failingOperation = async () => {
-    attempt++;
-    throw new Error('Test failure');
-  };
-  
-  // First two failures
-  for (let i = 0; i < 2; i++) {
-    try {
-      await breaker.execute(failingOperation);
-    } catch (e) {
-      // Expected
-    }
-  }
-  
-  expect(breaker.isOpen()).toBeTrue();
-  
-  // Next attempt should fail immediately
-  let error: Error | null = null;
-  try {
-    await breaker.execute(failingOperation);
-  } catch (e: any) {
-    error = e;
-  }
-  
-  expect(error?.message).toEqual('Circuit breaker is open');
-  expect(attempt).toEqual(2); // Operation not called when circuit is open
-  
-  // Wait for reset timeout
-  await delay(150);
-  
-  // Circuit should be half-open now, allowing one attempt
-  const successOperation = async () => 'success';
-  const result = await breaker.execute(successOperation);
-  
-  expect(result).toEqual('success');
-  expect(breaker.getState()).toEqual('closed');
-});
-
-tap.start();

test/core/utils/test.binary-heap.ts

@@ -1,206 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { BinaryHeap } from '../../../ts/core/utils/binary-heap.js';
-
-interface TestItem {
-  id: string;
-  priority: number;
-  value: string;
-}
-
-tap.test('should create empty heap', async () => {
-  const heap = new BinaryHeap<number>((a, b) => a - b);
-  
-  expect(heap.size).toEqual(0);
-  expect(heap.isEmpty()).toBeTrue();
-  expect(heap.peek()).toBeUndefined();
-});
-
-tap.test('should insert and extract in correct order', async () => {
-  const heap = new BinaryHeap<number>((a, b) => a - b);
-  
-  heap.insert(5);
-  heap.insert(3);
-  heap.insert(7);
-  heap.insert(1);
-  heap.insert(9);
-  heap.insert(4);
-  
-  expect(heap.size).toEqual(6);
-  
-  // Extract in ascending order
-  expect(heap.extract()).toEqual(1);
-  expect(heap.extract()).toEqual(3);
-  expect(heap.extract()).toEqual(4);
-  expect(heap.extract()).toEqual(5);
-  expect(heap.extract()).toEqual(7);
-  expect(heap.extract()).toEqual(9);
-  expect(heap.extract()).toBeUndefined();
-});
-
-tap.test('should work with custom objects and comparator', async () => {
-  const heap = new BinaryHeap<TestItem>(
-    (a, b) => a.priority - b.priority,
-    (item) => item.id
-  );
-  
-  heap.insert({ id: 'a', priority: 5, value: 'five' });
-  heap.insert({ id: 'b', priority: 2, value: 'two' });
-  heap.insert({ id: 'c', priority: 8, value: 'eight' });
-  heap.insert({ id: 'd', priority: 1, value: 'one' });
-  
-  const first = heap.extract();
-  expect(first?.priority).toEqual(1);
-  expect(first?.value).toEqual('one');
-  
-  const second = heap.extract();
-  expect(second?.priority).toEqual(2);
-  expect(second?.value).toEqual('two');
-});
-
-tap.test('should support reverse order (max heap)', async () => {
-  const heap = new BinaryHeap<number>((a, b) => b - a);
-  
-  heap.insert(5);
-  heap.insert(3);
-  heap.insert(7);
-  heap.insert(1);
-  heap.insert(9);
-  
-  // Extract in descending order
-  expect(heap.extract()).toEqual(9);
-  expect(heap.extract()).toEqual(7);
-  expect(heap.extract()).toEqual(5);
-});
-
-tap.test('should extract by predicate', async () => {
-  const heap = new BinaryHeap<TestItem>((a, b) => a.priority - b.priority);
-  
-  heap.insert({ id: 'a', priority: 5, value: 'five' });
-  heap.insert({ id: 'b', priority: 2, value: 'two' });
-  heap.insert({ id: 'c', priority: 8, value: 'eight' });
-  
-  const extracted = heap.extractIf(item => item.id === 'b');
-  expect(extracted?.id).toEqual('b');
-  expect(heap.size).toEqual(2);
-  
-  // Should not find it again
-  const notFound = heap.extractIf(item => item.id === 'b');
-  expect(notFound).toBeUndefined();
-});
-
-tap.test('should extract by key', async () => {
-  const heap = new BinaryHeap<TestItem>(
-    (a, b) => a.priority - b.priority,
-    (item) => item.id
-  );
-  
-  heap.insert({ id: 'a', priority: 5, value: 'five' });
-  heap.insert({ id: 'b', priority: 2, value: 'two' });
-  heap.insert({ id: 'c', priority: 8, value: 'eight' });
-  
-  expect(heap.hasKey('b')).toBeTrue();
-  
-  const extracted = heap.extractByKey('b');
-  expect(extracted?.id).toEqual('b');
-  expect(heap.size).toEqual(2);
-  expect(heap.hasKey('b')).toBeFalse();
-  
-  // Should not find it again
-  const notFound = heap.extractByKey('b');
-  expect(notFound).toBeUndefined();
-});
-
-tap.test('should throw when using key operations without extractKey', async () => {
-  const heap = new BinaryHeap<TestItem>((a, b) => a.priority - b.priority);
-  
-  heap.insert({ id: 'a', priority: 5, value: 'five' });
-  
-  let error: Error | null = null;
-  try {
-    heap.extractByKey('a');
-  } catch (e: any) {
-    error = e;
-  }
-  
-  expect(error).not.toBeNull();
-  expect(error?.message).toContain('extractKey function must be provided');
-});
-
-tap.test('should handle duplicates correctly', async () => {
-  const heap = new BinaryHeap<number>((a, b) => a - b);
-  
-  heap.insert(5);
-  heap.insert(5);
-  heap.insert(5);
-  heap.insert(3);
-  heap.insert(7);
-  
-  expect(heap.size).toEqual(5);
-  expect(heap.extract()).toEqual(3);
-  expect(heap.extract()).toEqual(5);
-  expect(heap.extract()).toEqual(5);
-  expect(heap.extract()).toEqual(5);
-  expect(heap.extract()).toEqual(7);
-});
-
-tap.test('should convert to array without modifying heap', async () => {
-  const heap = new BinaryHeap<number>((a, b) => a - b);
-  
-  heap.insert(5);
-  heap.insert(3);
-  heap.insert(7);
-  
-  const array = heap.toArray();
-  expect(array).toContain(3);
-  expect(array).toContain(5);
-  expect(array).toContain(7);
-  expect(array.length).toEqual(3);
-  
-  // Heap should still be intact
-  expect(heap.size).toEqual(3);
-  expect(heap.extract()).toEqual(3);
-});
-
-tap.test('should clear the heap', async () => {
-  const heap = new BinaryHeap<TestItem>(
-    (a, b) => a.priority - b.priority,
-    (item) => item.id
-  );
-  
-  heap.insert({ id: 'a', priority: 5, value: 'five' });
-  heap.insert({ id: 'b', priority: 2, value: 'two' });
-  
-  expect(heap.size).toEqual(2);
-  expect(heap.hasKey('a')).toBeTrue();
-  
-  heap.clear();
-  
-  expect(heap.size).toEqual(0);
-  expect(heap.isEmpty()).toBeTrue();
-  expect(heap.hasKey('a')).toBeFalse();
-});
-
-tap.test('should handle complex extraction patterns', async () => {
-  const heap = new BinaryHeap<number>((a, b) => a - b);
-  
-  // Insert numbers 1-10 in random order
-  [8, 3, 5, 9, 1, 7, 4, 10, 2, 6].forEach(n => heap.insert(n));
-  
-  // Extract some in order
-  expect(heap.extract()).toEqual(1);
-  expect(heap.extract()).toEqual(2);
-  
-  // Insert more
-  heap.insert(0);
-  heap.insert(1.5);
-  
-  // Continue extracting
-  expect(heap.extract()).toEqual(0);
-  expect(heap.extract()).toEqual(1.5);
-  expect(heap.extract()).toEqual(3);
-  
-  // Verify remaining size (10 - 2 extracted + 2 inserted - 3 extracted = 7)
-  expect(heap.size).toEqual(7);
-});
-
-tap.start();

test/core/utils/test.fs-utils.ts

@@ -1,185 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import * as path from 'path';
-import { AsyncFileSystem } from '../../../ts/core/utils/fs-utils.js';
-
-// Use a temporary directory for tests
-const testDir = path.join(process.cwd(), '.nogit', 'test-fs-utils');
-const testFile = path.join(testDir, 'test.txt');
-const testJsonFile = path.join(testDir, 'test.json');
-
-tap.test('should create and check directory existence', async () => {
-  // Ensure directory
-  await AsyncFileSystem.ensureDir(testDir);
-  
-  // Check it exists
-  const exists = await AsyncFileSystem.exists(testDir);
-  expect(exists).toBeTrue();
-  
-  // Check it's a directory
-  const isDir = await AsyncFileSystem.isDirectory(testDir);
-  expect(isDir).toBeTrue();
-});
-
-tap.test('should write and read text files', async () => {
-  const testContent = 'Hello, async filesystem!';
-  
-  // Write file
-  await AsyncFileSystem.writeFile(testFile, testContent);
-  
-  // Check file exists
-  const exists = await AsyncFileSystem.exists(testFile);
-  expect(exists).toBeTrue();
-  
-  // Read file
-  const content = await AsyncFileSystem.readFile(testFile);
-  expect(content).toEqual(testContent);
-  
-  // Check it's a file
-  const isFile = await AsyncFileSystem.isFile(testFile);
-  expect(isFile).toBeTrue();
-});
-
-tap.test('should write and read JSON files', async () => {
-  const testData = {
-    name: 'Test',
-    value: 42,
-    nested: {
-      array: [1, 2, 3]
-    }
-  };
-  
-  // Write JSON
-  await AsyncFileSystem.writeJSON(testJsonFile, testData);
-  
-  // Read JSON
-  const readData = await AsyncFileSystem.readJSON(testJsonFile);
-  expect(readData).toEqual(testData);
-});
-
-tap.test('should copy files', async () => {
-  const copyFile = path.join(testDir, 'copy.txt');
-  
-  // Copy file
-  await AsyncFileSystem.copyFile(testFile, copyFile);
-  
-  // Check copy exists
-  const exists = await AsyncFileSystem.exists(copyFile);
-  expect(exists).toBeTrue();
-  
-  // Check content matches
-  const content = await AsyncFileSystem.readFile(copyFile);
-  const originalContent = await AsyncFileSystem.readFile(testFile);
-  expect(content).toEqual(originalContent);
-});
-
-tap.test('should move files', async () => {
-  const moveFile = path.join(testDir, 'moved.txt');
-  const copyFile = path.join(testDir, 'copy.txt');
-  
-  // Move file
-  await AsyncFileSystem.moveFile(copyFile, moveFile);
-  
-  // Check moved file exists
-  const movedExists = await AsyncFileSystem.exists(moveFile);
-  expect(movedExists).toBeTrue();
-  
-  // Check original doesn't exist
-  const originalExists = await AsyncFileSystem.exists(copyFile);
-  expect(originalExists).toBeFalse();
-});
-
-tap.test('should list files in directory', async () => {
-  const files = await AsyncFileSystem.listFiles(testDir);
-  
-  expect(files).toContain('test.txt');
-  expect(files).toContain('test.json');
-  expect(files).toContain('moved.txt');
-});
-
-tap.test('should list files with full paths', async () => {
-  const files = await AsyncFileSystem.listFilesFullPath(testDir);
-  
-  const fileNames = files.map(f => path.basename(f));
-  expect(fileNames).toContain('test.txt');
-  expect(fileNames).toContain('test.json');
-  
-  // All paths should be absolute
-  files.forEach(file => {
-    expect(path.isAbsolute(file)).toBeTrue();
-  });
-});
-
-tap.test('should get file stats', async () => {
-  const stats = await AsyncFileSystem.getStats(testFile);
-  
-  expect(stats).not.toBeNull();
-  expect(stats?.isFile()).toBeTrue();
-  expect(stats?.size).toBeGreaterThan(0);
-});
-
-tap.test('should handle non-existent files gracefully', async () => {
-  const nonExistent = path.join(testDir, 'does-not-exist.txt');
-  
-  // Check existence
-  const exists = await AsyncFileSystem.exists(nonExistent);
-  expect(exists).toBeFalse();
-  
-  // Get stats should return null
-  const stats = await AsyncFileSystem.getStats(nonExistent);
-  expect(stats).toBeNull();
-  
-  // Remove should not throw
-  await AsyncFileSystem.remove(nonExistent);
-});
-
-tap.test('should remove files', async () => {
-  // Remove a file
-  await AsyncFileSystem.remove(testFile);
-  
-  // Check it's gone
-  const exists = await AsyncFileSystem.exists(testFile);
-  expect(exists).toBeFalse();
-});
-
-tap.test('should ensure file exists', async () => {
-  const ensureFile = path.join(testDir, 'ensure.txt');
-  
-  // Ensure file
-  await AsyncFileSystem.ensureFile(ensureFile);
-  
-  // Check it exists
-  const exists = await AsyncFileSystem.exists(ensureFile);
-  expect(exists).toBeTrue();
-  
-  // Check it's empty
-  const content = await AsyncFileSystem.readFile(ensureFile);
-  expect(content).toEqual('');
-});
-
-tap.test('should recursively list files', async () => {
-  // Create subdirectory with file
-  const subDir = path.join(testDir, 'subdir');
-  const subFile = path.join(subDir, 'nested.txt');
-  
-  await AsyncFileSystem.ensureDir(subDir);
-  await AsyncFileSystem.writeFile(subFile, 'nested content');
-  
-  // List recursively
-  const files = await AsyncFileSystem.listFilesRecursive(testDir);
-  
-  // Should include files from subdirectory
-  const fileNames = files.map(f => path.relative(testDir, f));
-  expect(fileNames).toContain('test.json');
-  expect(fileNames).toContain(path.join('subdir', 'nested.txt'));
-});
-
-tap.test('should clean up test directory', async () => {
-  // Remove entire test directory
-  await AsyncFileSystem.removeDir(testDir);
-  
-  // Check it's gone
-  const exists = await AsyncFileSystem.exists(testDir);
-  expect(exists).toBeFalse();
-});
-
-tap.start();

test/core/utils/test.ip-utils.ts

@@ -1,156 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { IpUtils } from '../../../ts/core/utils/ip-utils.js';
-
-tap.test('ip-utils - normalizeIP', async () => {
-  // IPv4 normalization
-  const ipv4Variants = IpUtils.normalizeIP('127.0.0.1');
-  expect(ipv4Variants).toEqual(['127.0.0.1', '::ffff:127.0.0.1']);
-  
-  // IPv6-mapped IPv4 normalization
-  const ipv6MappedVariants = IpUtils.normalizeIP('::ffff:127.0.0.1');
-  expect(ipv6MappedVariants).toEqual(['::ffff:127.0.0.1', '127.0.0.1']);
-  
-  // IPv6 normalization
-  const ipv6Variants = IpUtils.normalizeIP('::1');
-  expect(ipv6Variants).toEqual(['::1']);
-  
-  // Invalid/empty input handling
-  expect(IpUtils.normalizeIP('')).toEqual([]);
-  expect(IpUtils.normalizeIP(null as any)).toEqual([]);
-  expect(IpUtils.normalizeIP(undefined as any)).toEqual([]);
-});
-
-tap.test('ip-utils - isGlobIPMatch', async () => {
-  // Direct matches
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['127.0.0.1'])).toEqual(true);
-  expect(IpUtils.isGlobIPMatch('::1', ['::1'])).toEqual(true);
-  
-  // Wildcard matches
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['127.0.0.*'])).toEqual(true);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['127.0.*.*'])).toEqual(true);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['127.*.*.*'])).toEqual(true);
-  
-  // IPv4-mapped IPv6 handling
-  expect(IpUtils.isGlobIPMatch('::ffff:127.0.0.1', ['127.0.0.1'])).toEqual(true);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['::ffff:127.0.0.1'])).toEqual(true);
-  
-  // Match multiple patterns
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['10.0.0.1', '127.0.0.1', '192.168.1.1'])).toEqual(true);
-  
-  // Non-matching patterns
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['10.0.0.1'])).toEqual(false);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['128.0.0.1'])).toEqual(false);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', ['127.0.0.2'])).toEqual(false);
-  
-  // Edge cases
-  expect(IpUtils.isGlobIPMatch('', ['127.0.0.1'])).toEqual(false);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', [])).toEqual(false);
-  expect(IpUtils.isGlobIPMatch('127.0.0.1', null as any)).toEqual(false);
-  expect(IpUtils.isGlobIPMatch(null as any, ['127.0.0.1'])).toEqual(false);
-});
-
-tap.test('ip-utils - isIPAuthorized', async () => {
-  // Basic tests to check the core functionality works
-  // No restrictions - all IPs allowed
-  expect(IpUtils.isIPAuthorized('127.0.0.1')).toEqual(true);
-
-  // Basic blocked IP test
-  const blockedIP = '8.8.8.8';
-  const blockedIPs = [blockedIP];
-  expect(IpUtils.isIPAuthorized(blockedIP, [], blockedIPs)).toEqual(false);
-
-  // Basic allowed IP test
-  const allowedIP = '10.0.0.1';
-  const allowedIPs = [allowedIP];
-  expect(IpUtils.isIPAuthorized(allowedIP, allowedIPs)).toEqual(true);
-  expect(IpUtils.isIPAuthorized('192.168.1.1', allowedIPs)).toEqual(false);
-});
-
-tap.test('ip-utils - isPrivateIP', async () => {
-  // Private IPv4 ranges
-  expect(IpUtils.isPrivateIP('10.0.0.1')).toEqual(true);
-  expect(IpUtils.isPrivateIP('172.16.0.1')).toEqual(true);
-  expect(IpUtils.isPrivateIP('172.31.255.255')).toEqual(true);
-  expect(IpUtils.isPrivateIP('192.168.0.1')).toEqual(true);
-  expect(IpUtils.isPrivateIP('127.0.0.1')).toEqual(true);
-  
-  // Public IPv4 addresses
-  expect(IpUtils.isPrivateIP('8.8.8.8')).toEqual(false);
-  expect(IpUtils.isPrivateIP('203.0.113.1')).toEqual(false);
-  
-  // IPv4-mapped IPv6 handling
-  expect(IpUtils.isPrivateIP('::ffff:10.0.0.1')).toEqual(true);
-  expect(IpUtils.isPrivateIP('::ffff:8.8.8.8')).toEqual(false);
-  
-  // Private IPv6 addresses
-  expect(IpUtils.isPrivateIP('::1')).toEqual(true);
-  expect(IpUtils.isPrivateIP('fd00::')).toEqual(true);
-  expect(IpUtils.isPrivateIP('fe80::1')).toEqual(true);
-  
-  // Public IPv6 addresses
-  expect(IpUtils.isPrivateIP('2001:db8::1')).toEqual(false);
-  
-  // Edge cases
-  expect(IpUtils.isPrivateIP('')).toEqual(false);
-  expect(IpUtils.isPrivateIP(null as any)).toEqual(false);
-  expect(IpUtils.isPrivateIP(undefined as any)).toEqual(false);
-});
-
-tap.test('ip-utils - isPublicIP', async () => {
-  // Public IPv4 addresses
-  expect(IpUtils.isPublicIP('8.8.8.8')).toEqual(true);
-  expect(IpUtils.isPublicIP('203.0.113.1')).toEqual(true);
-  
-  // Private IPv4 ranges
-  expect(IpUtils.isPublicIP('10.0.0.1')).toEqual(false);
-  expect(IpUtils.isPublicIP('172.16.0.1')).toEqual(false);
-  expect(IpUtils.isPublicIP('192.168.0.1')).toEqual(false);
-  expect(IpUtils.isPublicIP('127.0.0.1')).toEqual(false);
-  
-  // Public IPv6 addresses
-  expect(IpUtils.isPublicIP('2001:db8::1')).toEqual(true);
-  
-  // Private IPv6 addresses
-  expect(IpUtils.isPublicIP('::1')).toEqual(false);
-  expect(IpUtils.isPublicIP('fd00::')).toEqual(false);
-  expect(IpUtils.isPublicIP('fe80::1')).toEqual(false);
-  
-  // Edge cases - the implementation treats these as non-private, which is technically correct but might not be what users expect
-  const emptyResult = IpUtils.isPublicIP('');
-  expect(emptyResult).toEqual(true);
-
-  const nullResult = IpUtils.isPublicIP(null as any);
-  expect(nullResult).toEqual(true);
-
-  const undefinedResult = IpUtils.isPublicIP(undefined as any);
-  expect(undefinedResult).toEqual(true);
-});
-
-tap.test('ip-utils - cidrToGlobPatterns', async () => {
-  // Class C network
-  const classC = IpUtils.cidrToGlobPatterns('192.168.1.0/24');
-  expect(classC).toEqual(['192.168.1.*']);
-  
-  // Class B network
-  const classB = IpUtils.cidrToGlobPatterns('172.16.0.0/16');
-  expect(classB).toEqual(['172.16.*.*']);
-  
-  // Class A network
-  const classA = IpUtils.cidrToGlobPatterns('10.0.0.0/8');
-  expect(classA).toEqual(['10.*.*.*']);
-  
-  // Small subnet (/28 = 16 addresses)
-  const smallSubnet = IpUtils.cidrToGlobPatterns('192.168.1.0/28');
-  expect(smallSubnet.length).toEqual(16);
-  expect(smallSubnet).toContain('192.168.1.0');
-  expect(smallSubnet).toContain('192.168.1.15');
-  
-  // Invalid inputs
-  expect(IpUtils.cidrToGlobPatterns('')).toEqual([]);
-  expect(IpUtils.cidrToGlobPatterns('192.168.1.0')).toEqual([]);
-  expect(IpUtils.cidrToGlobPatterns('192.168.1.0/')).toEqual([]);
-  expect(IpUtils.cidrToGlobPatterns('192.168.1.0/33')).toEqual([]);
-  expect(IpUtils.cidrToGlobPatterns('invalid/24')).toEqual([]);
-});
-
-export default tap.start();

test/core/utils/test.lifecycle-component.ts

@@ -1,252 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { LifecycleComponent } from '../../../ts/core/utils/lifecycle-component.js';
-import { EventEmitter } from 'events';
-
-// Test implementation of LifecycleComponent
-class TestComponent extends LifecycleComponent {
-  public timerCallCount = 0;
-  public intervalCallCount = 0;
-  public cleanupCalled = false;
-  public testEmitter = new EventEmitter();
-  public listenerCallCount = 0;
-
-  constructor() {
-    super();
-    this.setupTimers();
-    this.setupListeners();
-  }
-
-  private setupTimers() {
-    // Set up a timeout
-    this.setTimeout(() => {
-      this.timerCallCount++;
-    }, 100);
-
-    // Set up an interval
-    this.setInterval(() => {
-      this.intervalCallCount++;
-    }, 50);
-  }
-
-  private setupListeners() {
-    this.addEventListener(this.testEmitter, 'test-event', () => {
-      this.listenerCallCount++;
-    });
-  }
-
-  protected async onCleanup(): Promise<void> {
-    this.cleanupCalled = true;
-  }
-
-  // Expose protected methods for testing
-  public testSetTimeout(handler: Function, timeout: number): NodeJS.Timeout {
-    return this.setTimeout(handler, timeout);
-  }
-
-  public testSetInterval(handler: Function, interval: number): NodeJS.Timeout {
-    return this.setInterval(handler, interval);
-  }
-
-  public testClearTimeout(timer: NodeJS.Timeout): void {
-    return this.clearTimeout(timer);
-  }
-
-  public testClearInterval(timer: NodeJS.Timeout): void {
-    return this.clearInterval(timer);
-  }
-
-  public testAddEventListener(target: any, event: string, handler: Function, options?: { once?: boolean }): void {
-    return this.addEventListener(target, event, handler, options);
-  }
-
-  public testIsShuttingDown(): boolean {
-    return this.isShuttingDownState();
-  }
-}
-
-tap.test('should manage timers properly', async () => {
-  const component = new TestComponent();
-  
-  // Wait for timers to fire
-  await new Promise(resolve => setTimeout(resolve, 200));
-  
-  expect(component.timerCallCount).toEqual(1);
-  expect(component.intervalCallCount).toBeGreaterThan(2);
-  
-  await component.cleanup();
-});
-
-tap.test('should manage event listeners properly', async () => {
-  const component = new TestComponent();
-  
-  // Emit events
-  component.testEmitter.emit('test-event');
-  component.testEmitter.emit('test-event');
-  
-  expect(component.listenerCallCount).toEqual(2);
-  
-  // Cleanup and verify listeners are removed
-  await component.cleanup();
-  
-  component.testEmitter.emit('test-event');
-  expect(component.listenerCallCount).toEqual(2); // Should not increase
-});
-
-tap.test('should prevent timer execution after cleanup', async () => {
-  const component = new TestComponent();
-  
-  let laterCallCount = 0;
-  component.testSetTimeout(() => {
-    laterCallCount++;
-  }, 100);
-  
-  // Cleanup immediately
-  await component.cleanup();
-  
-  // Wait for timer that would have fired
-  await new Promise(resolve => setTimeout(resolve, 150));
-  
-  expect(laterCallCount).toEqual(0);
-});
-
-tap.test('should handle child components', async () => {
-  class ParentComponent extends LifecycleComponent {
-    public child: TestComponent;
-    
-    constructor() {
-      super();
-      this.child = new TestComponent();
-      this.registerChildComponent(this.child);
-    }
-  }
-  
-  const parent = new ParentComponent();
-  
-  // Wait for child timers
-  await new Promise(resolve => setTimeout(resolve, 100));
-  
-  expect(parent.child.timerCallCount).toEqual(1);
-  
-  // Cleanup parent should cleanup child
-  await parent.cleanup();
-  
-  expect(parent.child.cleanupCalled).toBeTrue();
-  expect(parent.child.testIsShuttingDown()).toBeTrue();
-});
-
-tap.test('should handle multiple cleanup calls gracefully', async () => {
-  const component = new TestComponent();
-  
-  // Call cleanup multiple times
-  const promises = [
-    component.cleanup(),
-    component.cleanup(),
-    component.cleanup()
-  ];
-  
-  await Promise.all(promises);
-  
-  // Should only clean up once
-  expect(component.cleanupCalled).toBeTrue();
-});
-
-tap.test('should clear specific timers', async () => {
-  const component = new TestComponent();
-  
-  let callCount = 0;
-  const timer = component.testSetTimeout(() => {
-    callCount++;
-  }, 100);
-  
-  // Clear the timer
-  component.testClearTimeout(timer);
-  
-  // Wait and verify it didn't fire
-  await new Promise(resolve => setTimeout(resolve, 150));
-  
-  expect(callCount).toEqual(0);
-  
-  await component.cleanup();
-});
-
-tap.test('should clear specific intervals', async () => {
-  const component = new TestComponent();
-  
-  let callCount = 0;
-  const interval = component.testSetInterval(() => {
-    callCount++;
-  }, 50);
-  
-  // Let it run a bit
-  await new Promise(resolve => setTimeout(resolve, 120));
-  
-  const countBeforeClear = callCount;
-  expect(countBeforeClear).toBeGreaterThan(1);
-  
-  // Clear the interval
-  component.testClearInterval(interval);
-  
-  // Wait and verify it stopped
-  await new Promise(resolve => setTimeout(resolve, 100));
-  
-  expect(callCount).toEqual(countBeforeClear);
-  
-  await component.cleanup();
-});
-
-tap.test('should handle once event listeners', async () => {
-  const component = new TestComponent();
-  const emitter = new EventEmitter();
-  
-  let callCount = 0;
-  const handler = () => {
-    callCount++;
-  };
-  
-  component.testAddEventListener(emitter, 'once-event', handler, { once: true });
-  
-  // Check listener count before emit
-  const beforeCount = emitter.listenerCount('once-event');
-  expect(beforeCount).toEqual(1);
-  
-  // Emit once - the listener should fire and auto-remove
-  emitter.emit('once-event');
-  expect(callCount).toEqual(1);
-  
-  // Check listener was auto-removed
-  const afterCount = emitter.listenerCount('once-event');
-  expect(afterCount).toEqual(0);
-  
-  // Emit again - should not increase count
-  emitter.emit('once-event');
-  expect(callCount).toEqual(1);
-  
-  await component.cleanup();
-});
-
-tap.test('should not create timers when shutting down', async () => {
-  const component = new TestComponent();
-  
-  // Start cleanup
-  const cleanupPromise = component.cleanup();
-  
-  // Try to create timers during shutdown
-  let timerFired = false;
-  let intervalFired = false;
-  
-  component.testSetTimeout(() => {
-    timerFired = true;
-  }, 10);
-  
-  component.testSetInterval(() => {
-    intervalFired = true;
-  }, 10);
-  
-  await cleanupPromise;
-  await new Promise(resolve => setTimeout(resolve, 50));
-  
-  expect(timerFired).toBeFalse();
-  expect(intervalFired).toBeFalse();
-});
-
-export default tap.start();

test/core/utils/test.shared-security-manager.ts

@@ -1,158 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { SharedSecurityManager } from '../../../ts/core/utils/shared-security-manager.js';
-import type { IRouteConfig, IRouteContext } from '../../../ts/proxies/smart-proxy/models/route-types.js';
-
-// Test security manager
-tap.test('Shared Security Manager', async () => {
-  let securityManager: SharedSecurityManager;
-
-  // Set up a new security manager for each test
-  securityManager = new SharedSecurityManager({
-    maxConnectionsPerIP: 5,
-    connectionRateLimitPerMinute: 10
-  });
-
-  tap.test('should validate IPs correctly', async () => {
-    // Should allow IPs under connection limit
-    expect(securityManager.validateIP('192.168.1.1').allowed).toBeTrue();
-    
-    // Track multiple connections
-    for (let i = 0; i < 4; i++) {
-      securityManager.trackConnectionByIP('192.168.1.1', `conn_${i}`);
-    }
-    
-    // Should still allow IPs under connection limit
-    expect(securityManager.validateIP('192.168.1.1').allowed).toBeTrue();
-    
-    // Add one more to reach the limit
-    securityManager.trackConnectionByIP('192.168.1.1', 'conn_4');
-    
-    // Should now block IPs over connection limit
-    expect(securityManager.validateIP('192.168.1.1').allowed).toBeFalse();
-    
-    // Remove a connection
-    securityManager.removeConnectionByIP('192.168.1.1', 'conn_0');
-    
-    // Should allow again after connection is removed
-    expect(securityManager.validateIP('192.168.1.1').allowed).toBeTrue();
-  });
-  
-  tap.test('should authorize IPs based on allow/block lists', async () => {
-    // Test with allow list only
-    expect(securityManager.isIPAuthorized('192.168.1.1', ['192.168.1.*'])).toBeTrue();
-    expect(securityManager.isIPAuthorized('192.168.2.1', ['192.168.1.*'])).toBeFalse();
-    
-    // Test with block list
-    expect(securityManager.isIPAuthorized('192.168.1.5', ['*'], ['192.168.1.5'])).toBeFalse();
-    expect(securityManager.isIPAuthorized('192.168.1.1', ['*'], ['192.168.1.5'])).toBeTrue();
-    
-    // Test with both allow and block lists
-    expect(securityManager.isIPAuthorized('192.168.1.1', ['192.168.1.*'], ['192.168.1.5'])).toBeTrue();
-    expect(securityManager.isIPAuthorized('192.168.1.5', ['192.168.1.*'], ['192.168.1.5'])).toBeFalse();
-  });
-
-  tap.test('should validate route access', async () => {
-    const route: IRouteConfig = {
-      match: {
-        ports: [8080]
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'target.com', port: 443 }]
-      },
-      security: {
-        ipAllowList: ['10.0.0.*', '192.168.1.*'],
-        ipBlockList: ['192.168.1.100'],
-        maxConnections: 3
-      }
-    };
-
-    const allowedContext: IRouteContext = {
-      clientIp: '192.168.1.1',
-      port: 8080,
-      serverIp: '127.0.0.1',
-      isTls: false,
-      timestamp: Date.now(),
-      connectionId: 'test_conn_1'
-    };
-
-    const blockedByIPContext: IRouteContext = {
-      ...allowedContext,
-      clientIp: '192.168.1.100'
-    };
-
-    const blockedByRangeContext: IRouteContext = {
-      ...allowedContext,
-      clientIp: '172.16.0.1'
-    };
-
-    const blockedByMaxConnectionsContext: IRouteContext = {
-      ...allowedContext,
-      connectionId: 'test_conn_4'
-    };
-
-    expect(securityManager.isAllowed(route, allowedContext)).toBeTrue();
-    expect(securityManager.isAllowed(route, blockedByIPContext)).toBeFalse();
-    expect(securityManager.isAllowed(route, blockedByRangeContext)).toBeFalse();
-    
-    // Test max connections for route - assuming implementation has been updated
-    if ((securityManager as any).trackConnectionByRoute) {
-      (securityManager as any).trackConnectionByRoute(route, 'conn_1');
-      (securityManager as any).trackConnectionByRoute(route, 'conn_2');
-      (securityManager as any).trackConnectionByRoute(route, 'conn_3');
-      
-      // Should now block due to max connections
-      expect(securityManager.isAllowed(route, blockedByMaxConnectionsContext)).toBeFalse();
-    }
-  });
-
-  tap.test('should clean up expired entries', async () => {
-    const route: IRouteConfig = {
-      match: {
-        ports: [8080]
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'target.com', port: 443 }]
-      },
-      security: {
-        rateLimit: {
-          enabled: true,
-          maxRequests: 5,
-          window: 60 // 60 seconds
-        }
-      }
-    };
-
-    const context: IRouteContext = {
-      clientIp: '192.168.1.1',
-      port: 8080,
-      serverIp: '127.0.0.1',
-      isTls: false,
-      timestamp: Date.now(),
-      connectionId: 'test_conn_1'
-    };
-
-    // Test rate limiting if method exists
-    if ((securityManager as any).checkRateLimit) {
-      // Add 5 attempts (max allowed)
-      for (let i = 0; i < 5; i++) {
-        expect((securityManager as any).checkRateLimit(route, context)).toBeTrue();
-      }
-
-      // Should now be blocked
-      expect((securityManager as any).checkRateLimit(route, context)).toBeFalse();
-
-      // Force cleanup (normally runs periodically)
-      if ((securityManager as any).cleanup) {
-        (securityManager as any).cleanup();
-      }
-
-      // Should still be blocked since entries are not expired yet
-      expect((securityManager as any).checkRateLimit(route, context)).toBeFalse();
-    }
-  });
-});
-
-// Export test runner
-export default tap.start();

test/core/utils/test.validation-utils.ts

@@ -1,302 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { ValidationUtils } from '../../../ts/core/utils/validation-utils.js';
-import type { IDomainOptions, IAcmeOptions } from '../../../ts/core/models/common-types.js';
-
-tap.test('validation-utils - isValidPort', async () => {
-  // Valid port values
-  expect(ValidationUtils.isValidPort(1)).toEqual(true);
-  expect(ValidationUtils.isValidPort(80)).toEqual(true);
-  expect(ValidationUtils.isValidPort(443)).toEqual(true);
-  expect(ValidationUtils.isValidPort(8080)).toEqual(true);
-  expect(ValidationUtils.isValidPort(65535)).toEqual(true);
-  
-  // Invalid port values
-  expect(ValidationUtils.isValidPort(0)).toEqual(false);
-  expect(ValidationUtils.isValidPort(-1)).toEqual(false);
-  expect(ValidationUtils.isValidPort(65536)).toEqual(false);
-  expect(ValidationUtils.isValidPort(80.5)).toEqual(false);
-  expect(ValidationUtils.isValidPort(NaN)).toEqual(false);
-  expect(ValidationUtils.isValidPort(null as any)).toEqual(false);
-  expect(ValidationUtils.isValidPort(undefined as any)).toEqual(false);
-});
-
-tap.test('validation-utils - isValidDomainName', async () => {
-  // Valid domain names
-  expect(ValidationUtils.isValidDomainName('example.com')).toEqual(true);
-  expect(ValidationUtils.isValidDomainName('sub.example.com')).toEqual(true);
-  expect(ValidationUtils.isValidDomainName('*.example.com')).toEqual(true);
-  expect(ValidationUtils.isValidDomainName('a-hyphenated-domain.example.com')).toEqual(true);
-  expect(ValidationUtils.isValidDomainName('example123.com')).toEqual(true);
-  
-  // Invalid domain names
-  expect(ValidationUtils.isValidDomainName('')).toEqual(false);
-  expect(ValidationUtils.isValidDomainName(null as any)).toEqual(false);
-  expect(ValidationUtils.isValidDomainName(undefined as any)).toEqual(false);
-  expect(ValidationUtils.isValidDomainName('-invalid.com')).toEqual(false);
-  expect(ValidationUtils.isValidDomainName('invalid-.com')).toEqual(false);
-  expect(ValidationUtils.isValidDomainName('inv@lid.com')).toEqual(false);
-  expect(ValidationUtils.isValidDomainName('example')).toEqual(false);
-  expect(ValidationUtils.isValidDomainName('example.')).toEqual(false);
-});
-
-tap.test('validation-utils - isValidEmail', async () => {
-  // Valid email addresses
-  expect(ValidationUtils.isValidEmail('user@example.com')).toEqual(true);
-  expect(ValidationUtils.isValidEmail('admin@sub.example.com')).toEqual(true);
-  expect(ValidationUtils.isValidEmail('first.last@example.com')).toEqual(true);
-  expect(ValidationUtils.isValidEmail('user+tag@example.com')).toEqual(true);
-  
-  // Invalid email addresses
-  expect(ValidationUtils.isValidEmail('')).toEqual(false);
-  expect(ValidationUtils.isValidEmail(null as any)).toEqual(false);
-  expect(ValidationUtils.isValidEmail(undefined as any)).toEqual(false);
-  expect(ValidationUtils.isValidEmail('user')).toEqual(false);
-  expect(ValidationUtils.isValidEmail('user@')).toEqual(false);
-  expect(ValidationUtils.isValidEmail('@example.com')).toEqual(false);
-  expect(ValidationUtils.isValidEmail('user example.com')).toEqual(false);
-});
-
-tap.test('validation-utils - isValidCertificate', async () => {
-  // Valid certificate format
-  const validCert = `-----BEGIN CERTIFICATE-----
-MIIDazCCAlOgAwIBAgIUJlq+zz9CO2E91rlD4vhx0CX1Z/kwDQYJKoZIhvcNAQEL
-BQAwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgMClNvbWUtU3RhdGUxITAfBgNVBAoM
-GEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDAeFw0yMzAxMDEwMDAwMDBaFw0yNDAx
-MDEwMDAwMDBaMEUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIDApTb21lLVN0YXRlMSEw
-HwYDVQQKDBhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwggEiMA0GCSqGSIb3DQEB
-AQUAA4IBDwAwggEKAoIBAQC0aQeHIV9vQpZ4UVwW/xhx9zl01UbppLXdoqe3NP9x
-KfXTCB1YbtJ4GgKIlQqHGLGsLI5ZOE7KxmJeGEwK7ueP4f3WkUlM5C5yTbZ5hSUo
-R+OFnszFRJJiBXJlw57YAW9+zqKQHYxwve64O64dlgw6pekDYJhXtrUUZ78Lz0GX
-veJvCrci1M4Xk6/7/p1Ii9PNmbPKqHafdmkFLf6TXiWPuRDhPuHW7cXyE8xD5ahr
-NsDuwJyRUk+GS4/oJg0TqLSiD0IPxDH50V5MSfUIB82i+lc1t+OAGwLhjUDuQmJi
-Pv1+9Zvv+HA5PXBCsGXnSADrOOUO6t9q5R9PXbSvAgMBAAGjUzBRMB0GA1UdDgQW
-BBQEtdtBhH/z1XyIf+y+5O9ErDGCVjAfBgNVHSMEGDAWgBQEtdtBhH/z1XyIf+y+
-5O9ErDGCVjAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBmJyQ0
-r0pBJkYJJVDJ6i3WMoEEFTD8MEUkWxASHRnuMzm7XlZ8WS1HvbEWF0+WfJPCYHnk
-tGbvUFGaZ4qUxZ4Ip2mvKXoeYTJCZRxxhHeSVWnZZu0KS3X7xVAFwQYQNhdLOqP8
-XOHyLhHV/1/kcFd3GvKKjXxE79jUUZ/RXHZ/IY50KvxGzWc/5ZOFYrPEW1/rNlRo
-7ixXo1hNnBQsG1YoFAxTBGegdTFJeTYHYjZZ5XlRvY2aBq6QveRbJGJLcPm1UQMd
-HQYxacbWSVAQf3ltYwSH+y3a97C5OsJJiQXpRRJlQKL3txklzcpg3E5swhr63bM2
-jUoNXr5G5Q5h3GD5
------END CERTIFICATE-----`;
-
-  expect(ValidationUtils.isValidCertificate(validCert)).toEqual(true);
-  
-  // Invalid certificate format
-  expect(ValidationUtils.isValidCertificate('')).toEqual(false);
-  expect(ValidationUtils.isValidCertificate(null as any)).toEqual(false);
-  expect(ValidationUtils.isValidCertificate(undefined as any)).toEqual(false);
-  expect(ValidationUtils.isValidCertificate('invalid certificate')).toEqual(false);
-  expect(ValidationUtils.isValidCertificate('-----BEGIN CERTIFICATE-----')).toEqual(false);
-});
-
-tap.test('validation-utils - isValidPrivateKey', async () => {
-  // Valid private key format
-  const validKey = `-----BEGIN PRIVATE KEY-----
-MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC0aQeHIV9vQpZ4
-UVwW/xhx9zl01UbppLXdoqe3NP9xKfXTCB1YbtJ4GgKIlQqHGLGsLI5ZOE7KxmJe
-GEwK7ueP4f3WkUlM5C5yTbZ5hSUoR+OFnszFRJJiBXJlw57YAW9+zqKQHYxwve64
-O64dlgw6pekDYJhXtrUUZ78Lz0GXveJvCrci1M4Xk6/7/p1Ii9PNmbPKqHafdmkF
-Lf6TXiWPuRDhPuHW7cXyE8xD5ahrNsDuwJyRUk+GS4/oJg0TqLSiD0IPxDH50V5M
-SfUIB82i+lc1t+OAGwLhjUDuQmJiPv1+9Zvv+HA5PXBCsGXnSADrOOUO6t9q5R9P
-XbSvAgMBAAECggEADw8Xx9iEv3FvS8hYIRn2ZWM8ObRgbHkFN92NJ/5RvUwgyV03
-gG8GwVN+7IsVLnIQRyIYEGGJ0ZLZFIq7//Jy0jYUgEGLmXxknuZQn1cQEqqYVyBr
-G9JrfKkXaDEoP/bZBMvZ0KEO2C9Vq6mY8M0h0GxDT2y6UQnQYjH3+H6Rvhbhh+Ld
-n8lCJqWoW1t9GOUZ4xLsZ5jEDibcMJJzLBWYRxgHWyECK31/VtEQDKFiUcymrJ3I
-/zoDEDGbp1gdJHvlCxfSLJ2za7ErtRKRXYFRhZ9QkNSXl1pVFMqRQkedXIcA1/Cs
-VpUxiIE2JA3hSrv2csjmXoGJKDLVCvZ3CFxKL3u/AQKBgQDf6MxHXN3IDuJNrJP7
-0gyRbO5d6vcvP/8qiYjtEt2xB2MNt5jDz9Bxl6aKEdNW2+UE0rvXXT6KAMZv9LiF
-hxr5qiJmmSB8OeGfr0W4FCixGN4BkRNwfT1gUqZgQOrfMOLHNXOksc1CJwHJfROV
-h6AH+gjtF2BCXnVEHcqtRklk4QKBgQDOOYnLJn1CwgFAyRUYK8LQYKnrLp2cGn7N
-YH0SLf+VnCu7RCeNr3dm9FoHBCynjkx+qv9kGvCaJuZqEJ7+7IimNUZfDjwXTOJ+
-pzs8kEPN5EQOcbkmYCTQyOA0YeBuEXcv5xIZRZUYQvKg1xXOe/JhAQ4siVIMhgQL
-2XR3QwzRDwKBgB7rjZs2VYnuVExGr74lUUAGoZ71WCgt9Du9aYGJfNUriDtTEWAd
-VT5sKgVqpRwkY/zXujdxGr+K8DZu4vSdHBLcDLQsEBvRZIILTzjwXBRPGMnVe95v
-Q90+vytbmHshlkbMaVRNQxCjdbf7LbQbLecgRt+5BKxHVwL4u3BZNIqhAoGAas4f
-PoPOdFfKAMKZL7FLGMhEXLyFsg1JcGRfmByxTNgOJKXpYv5Hl7JLYOvfaiUOUYKI
-5Dnh5yLdFOaOjnB3iP0KEiSVEwZK0/Vna5JkzFTqImK9QD3SQCtQLXHJLD52EPFR
-9gRa8N5k68+mIzGDEzPBoC1AajbXFGPxNOwaQQ0CgYEAq0dPYK0TTv3Yez27LzVy
-RbHkwpE+df4+KhpHbCzUKzfQYo4WTahlR6IzhpOyVQKIptkjuTDyQzkmt0tXEGw3
-/M3yHa1FcY9IzPrHXHJoOeU1r9ay0GOQUi4FxKkYYWxUCtjOi5xlUxI0ABD8vGGR
-QbKMrQXRgLd/84nDnY2cYzA=
------END PRIVATE KEY-----`;
-
-  expect(ValidationUtils.isValidPrivateKey(validKey)).toEqual(true);
-  
-  // Invalid private key format
-  expect(ValidationUtils.isValidPrivateKey('')).toEqual(false);
-  expect(ValidationUtils.isValidPrivateKey(null as any)).toEqual(false);
-  expect(ValidationUtils.isValidPrivateKey(undefined as any)).toEqual(false);
-  expect(ValidationUtils.isValidPrivateKey('invalid key')).toEqual(false);
-  expect(ValidationUtils.isValidPrivateKey('-----BEGIN PRIVATE KEY-----')).toEqual(false);
-});
-
-tap.test('validation-utils - validateDomainOptions', async () => {
-  // Valid domain options
-  const validDomainOptions: IDomainOptions = {
-    domainName: 'example.com',
-    sslRedirect: true,
-    acmeMaintenance: true
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(validDomainOptions).isValid).toEqual(true);
-  
-  // Valid domain options with forward
-  const validDomainOptionsWithForward: IDomainOptions = {
-    domainName: 'example.com',
-    sslRedirect: true,
-    acmeMaintenance: true,
-    forward: {
-      ip: '127.0.0.1',
-      port: 8080
-    }
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(validDomainOptionsWithForward).isValid).toEqual(true);
-  
-  // Invalid domain options - no domain name
-  const invalidDomainOptions1: IDomainOptions = {
-    domainName: '',
-    sslRedirect: true,
-    acmeMaintenance: true
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(invalidDomainOptions1).isValid).toEqual(false);
-  
-  // Invalid domain options - invalid domain name
-  const invalidDomainOptions2: IDomainOptions = {
-    domainName: 'inv@lid.com',
-    sslRedirect: true,
-    acmeMaintenance: true
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(invalidDomainOptions2).isValid).toEqual(false);
-  
-  // Invalid domain options - forward missing ip
-  const invalidDomainOptions3: IDomainOptions = {
-    domainName: 'example.com',
-    sslRedirect: true,
-    acmeMaintenance: true,
-    forward: {
-      ip: '',
-      port: 8080
-    }
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(invalidDomainOptions3).isValid).toEqual(false);
-  
-  // Invalid domain options - forward missing port
-  const invalidDomainOptions4: IDomainOptions = {
-    domainName: 'example.com',
-    sslRedirect: true,
-    acmeMaintenance: true,
-    forward: {
-      ip: '127.0.0.1',
-      port: null as any
-    }
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(invalidDomainOptions4).isValid).toEqual(false);
-  
-  // Invalid domain options - invalid forward port
-  const invalidDomainOptions5: IDomainOptions = {
-    domainName: 'example.com',
-    sslRedirect: true,
-    acmeMaintenance: true,
-    forward: {
-      ip: '127.0.0.1',
-      port: 99999
-    }
-  };
-  
-  expect(ValidationUtils.validateDomainOptions(invalidDomainOptions5).isValid).toEqual(false);
-});
-
-tap.test('validation-utils - validateAcmeOptions', async () => {
-  // Valid ACME options
-  const validAcmeOptions: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'admin@example.com',
-    port: 80,
-    httpsRedirectPort: 443,
-    useProduction: false,
-    renewThresholdDays: 30,
-    renewCheckIntervalHours: 24,
-    certificateStore: './certs'
-  };
-  
-  expect(ValidationUtils.validateAcmeOptions(validAcmeOptions).isValid).toEqual(true);
-  
-  // ACME disabled - should be valid regardless of other options
-  const disabledAcmeOptions: IAcmeOptions = {
-    enabled: false
-  };
-
-  // Don't need to verify other fields when ACME is disabled
-  const disabledResult = ValidationUtils.validateAcmeOptions(disabledAcmeOptions);
-  expect(disabledResult.isValid).toEqual(true);
-  
-  // Invalid ACME options - missing email
-  const invalidAcmeOptions1: IAcmeOptions = {
-    enabled: true,
-    accountEmail: '',
-    port: 80
-  };
-  
-  expect(ValidationUtils.validateAcmeOptions(invalidAcmeOptions1).isValid).toEqual(false);
-  
-  // Invalid ACME options - invalid email
-  const invalidAcmeOptions2: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'invalid-email',
-    port: 80
-  };
-  
-  expect(ValidationUtils.validateAcmeOptions(invalidAcmeOptions2).isValid).toEqual(false);
-  
-  // Invalid ACME options - invalid port
-  const invalidAcmeOptions3: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'admin@example.com',
-    port: 99999
-  };
-  
-  expect(ValidationUtils.validateAcmeOptions(invalidAcmeOptions3).isValid).toEqual(false);
-  
-  // Invalid ACME options - invalid HTTPS redirect port
-  const invalidAcmeOptions4: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'admin@example.com',
-    port: 80,
-    httpsRedirectPort: -1
-  };
-  
-  expect(ValidationUtils.validateAcmeOptions(invalidAcmeOptions4).isValid).toEqual(false);
-  
-  // Invalid ACME options - invalid renew threshold days
-  const invalidAcmeOptions5: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'admin@example.com',
-    port: 80,
-    renewThresholdDays: 0
-  };
-
-  // The implementation allows renewThresholdDays of 0, even though the docstring suggests otherwise
-  const validationResult5 = ValidationUtils.validateAcmeOptions(invalidAcmeOptions5);
-  expect(validationResult5.isValid).toEqual(true);
-  
-  // Invalid ACME options - invalid renew check interval hours
-  const invalidAcmeOptions6: IAcmeOptions = {
-    enabled: true,
-    accountEmail: 'admin@example.com',
-    port: 80,
-    renewCheckIntervalHours: 0
-  };
-
-  // The implementation should validate this, but let's check the actual result
-  const checkIntervalResult = ValidationUtils.validateAcmeOptions(invalidAcmeOptions6);
-  // Adjust test to match actual implementation behavior
-  expect(checkIntervalResult.isValid !== false ? true : false).toEqual(true);
-});
-
-export default tap.start();

test/test.datagram-handler.ts

@@ -0,0 +1,125 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as dgram from 'dgram';
+import { SmartProxy } from '../ts/index.js';
+import type { TDatagramHandler, IDatagramInfo } from '../ts/index.js';
+import { findFreePorts, assertPortsFree } from './helpers/port-allocator.js';
+
+let smartProxy: SmartProxy;
+let PROXY_PORT: number;
+
+// Helper: send a single UDP datagram and wait for a response
+function sendDatagram(port: number, msg: string, timeoutMs = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const client = dgram.createSocket('udp4');
+    const timeout = setTimeout(() => {
+      client.close();
+      reject(new Error(`UDP response timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    client.send(Buffer.from(msg), port, '127.0.0.1');
+    client.on('message', (data) => {
+      clearTimeout(timeout);
+      client.close();
+      resolve(data.toString());
+    });
+    client.on('error', (err) => {
+      clearTimeout(timeout);
+      client.close();
+      reject(err);
+    });
+  });
+}
+
+tap.test('setup: start SmartProxy with datagramHandler', async () => {
+  [PROXY_PORT] = await findFreePorts(1);
+
+  const handler: TDatagramHandler = (datagram, info, reply) => {
+    reply(Buffer.from(`Handled: ${datagram.toString()}`));
+  };
+
+  smartProxy = new SmartProxy({
+    routes: [
+      {
+        name: 'dgram-handler-test',
+        match: {
+          ports: PROXY_PORT,
+          transport: 'udp' as const,
+        },
+        action: {
+          type: 'socket-handler',
+          datagramHandler: handler,
+        },
+      },
+    ],
+    defaults: {
+      security: {
+        ipAllowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+      },
+    },
+  });
+
+  await smartProxy.start();
+});
+
+tap.test('datagram handler: receives and replies to datagram', async () => {
+  const response = await sendDatagram(PROXY_PORT, 'Hello Handler');
+  expect(response).toEqual('Handled: Hello Handler');
+});
+
+tap.test('datagram handler: async handler works', async () => {
+  // Stop and restart with async handler
+  await smartProxy.stop();
+
+  [PROXY_PORT] = await findFreePorts(1);
+
+  const asyncHandler: TDatagramHandler = async (datagram, info, reply) => {
+    // Simulate async work
+    await new Promise<void>((resolve) => setTimeout(resolve, 10));
+    reply(Buffer.from(`Async: ${datagram.toString()}`));
+  };
+
+  smartProxy = new SmartProxy({
+    routes: [
+      {
+        name: 'dgram-async-handler',
+        match: {
+          ports: PROXY_PORT,
+          transport: 'udp' as const,
+        },
+        action: {
+          type: 'socket-handler',
+          datagramHandler: asyncHandler,
+        },
+      },
+    ],
+    defaults: {
+      security: {
+        ipAllowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+      },
+    },
+  });
+
+  await smartProxy.start();
+
+  const response = await sendDatagram(PROXY_PORT, 'Test Async');
+  expect(response).toEqual('Async: Test Async');
+});
+
+tap.test('datagram handler: multiple rapid datagrams', async () => {
+  const promises: Promise<string>[] = [];
+  for (let i = 0; i < 5; i++) {
+    promises.push(sendDatagram(PROXY_PORT, `msg-${i}`));
+  }
+
+  const responses = await Promise.all(promises);
+
+  for (let i = 0; i < 5; i++) {
+    expect(responses).toContain(`Async: msg-${i}`);
+  }
+});
+
+tap.test('cleanup: stop SmartProxy', async () => {
+  await smartProxy.stop();
+  await assertPortsFree([PROXY_PORT]);
+});
+
+export default tap.start();

test/test.detection.ts

@@ -1,146 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as smartproxy from '../ts/index.js';
-
-tap.test('Protocol Detection - TLS Detection', async () => {
-  // Test TLS handshake detection
-  const tlsHandshake = Buffer.from([
-    0x16, // Handshake record type
-    0x03, 0x01, // TLS 1.0
-    0x00, 0x05, // Length: 5 bytes
-    0x01, // ClientHello
-    0x00, 0x00, 0x01, 0x00 // Handshake length and data
-  ]);
-  
-  const detector = new smartproxy.detection.TlsDetector();
-  expect(detector.canHandle(tlsHandshake)).toEqual(true);
-  
-  const result = detector.detect(tlsHandshake);
-  expect(result).toBeDefined();
-  expect(result?.protocol).toEqual('tls');
-  expect(result?.connectionInfo.tlsVersion).toEqual('TLSv1.0');
-});
-
-tap.test('Protocol Detection - HTTP Detection', async () => {
-  // Test HTTP request detection
-  const httpRequest = Buffer.from(
-    'GET /test HTTP/1.1\r\n' +
-    'Host: example.com\r\n' +
-    'User-Agent: TestClient/1.0\r\n' +
-    '\r\n'
-  );
-  
-  const detector = new smartproxy.detection.HttpDetector();
-  expect(detector.canHandle(httpRequest)).toEqual(true);
-  
-  const result = detector.detect(httpRequest);
-  expect(result).toBeDefined();
-  expect(result?.protocol).toEqual('http');
-  expect(result?.connectionInfo.method).toEqual('GET');
-  expect(result?.connectionInfo.path).toEqual('/test');
-  expect(result?.connectionInfo.domain).toEqual('example.com');
-});
-
-tap.test('Protocol Detection - Main Detector TLS', async () => {
-  const tlsHandshake = Buffer.from([
-    0x16, // Handshake record type
-    0x03, 0x03, // TLS 1.2
-    0x00, 0x05, // Length: 5 bytes
-    0x01, // ClientHello
-    0x00, 0x00, 0x01, 0x00 // Handshake length and data
-  ]);
-  
-  const result = await smartproxy.detection.ProtocolDetector.detect(tlsHandshake);
-  expect(result.protocol).toEqual('tls');
-  expect(result.connectionInfo.tlsVersion).toEqual('TLSv1.2');
-});
-
-tap.test('Protocol Detection - Main Detector HTTP', async () => {
-  const httpRequest = Buffer.from(
-    'POST /api/test HTTP/1.1\r\n' +
-    'Host: api.example.com\r\n' +
-    'Content-Type: application/json\r\n' +
-    'Content-Length: 2\r\n' +
-    '\r\n' +
-    '{}'
-  );
-  
-  const result = await smartproxy.detection.ProtocolDetector.detect(httpRequest);
-  expect(result.protocol).toEqual('http');
-  expect(result.connectionInfo.method).toEqual('POST');
-  expect(result.connectionInfo.path).toEqual('/api/test');
-  expect(result.connectionInfo.domain).toEqual('api.example.com');
-});
-
-tap.test('Protocol Detection - Unknown Protocol', async () => {
-  const unknownData = Buffer.from('UNKNOWN PROTOCOL DATA\r\n');
-  
-  const result = await smartproxy.detection.ProtocolDetector.detect(unknownData);
-  expect(result.protocol).toEqual('unknown');
-  expect(result.isComplete).toEqual(true);
-});
-
-tap.test('Protocol Detection - Fragmented HTTP', async () => {
-  // Create connection context
-  const context = smartproxy.detection.ProtocolDetector.createConnectionContext({
-    sourceIp: '127.0.0.1',
-    sourcePort: 12345,
-    destIp: '127.0.0.1',
-    destPort: 80,
-    socketId: 'test-connection-1'
-  });
-  
-  // First fragment
-  const fragment1 = Buffer.from('GET /test HT');
-  let result = await smartproxy.detection.ProtocolDetector.detectWithContext(
-    fragment1,
-    context
-  );
-  expect(result.protocol).toEqual('http');
-  expect(result.isComplete).toEqual(false);
-  
-  // Second fragment
-  const fragment2 = Buffer.from('TP/1.1\r\nHost: example.com\r\n\r\n');
-  result = await smartproxy.detection.ProtocolDetector.detectWithContext(
-    fragment2,
-    context
-  );
-  expect(result.protocol).toEqual('http');
-  expect(result.isComplete).toEqual(true);
-  expect(result.connectionInfo.method).toEqual('GET');
-  expect(result.connectionInfo.path).toEqual('/test');
-  expect(result.connectionInfo.domain).toEqual('example.com');
-  
-  // Clean up fragments
-  smartproxy.detection.ProtocolDetector.cleanupConnection(context);
-});
-
-tap.test('Protocol Detection - HTTP Methods', async () => {
-  const methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
-  
-  for (const method of methods) {
-    const request = Buffer.from(
-      `${method} /test HTTP/1.1\r\n` +
-      'Host: example.com\r\n' +
-      '\r\n'
-    );
-    
-    const detector = new smartproxy.detection.HttpDetector();
-    const result = detector.detect(request);
-    expect(result?.connectionInfo.method).toEqual(method);
-  }
-});
-
-tap.test('Protocol Detection - Invalid Data', async () => {
-  // Binary data that's not a valid protocol
-  const binaryData = Buffer.from([0xFF, 0xFE, 0xFD, 0xFC, 0xFB]);
-  
-  const result = await smartproxy.detection.ProtocolDetector.detect(binaryData);
-  expect(result.protocol).toEqual('unknown');
-});
-
-tap.test('cleanup detection', async () => {
-  // Clean up the protocol detector instance
-  smartproxy.detection.ProtocolDetector.destroy();
-});
-
-export default tap.start();

test/test.ip-validation.ts

@@ -1,128 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as smartproxy from '../ts/index.js';
-import { RouteValidator } from '../ts/proxies/smart-proxy/utils/route-validator.js';
-import { IpUtils } from '../ts/core/utils/ip-utils.js';
-
-tap.test('IP Validation - Shorthand patterns', async () => {
-  
-  // Test shorthand patterns are now accepted
-  const testPatterns = [
-    { pattern: '192.168.*', shouldPass: true },
-    { pattern: '192.168.*.*', shouldPass: true },
-    { pattern: '10.*', shouldPass: true },
-    { pattern: '10.*.*.*', shouldPass: true },
-    { pattern: '172.16.*', shouldPass: true },
-    { pattern: '10.0.0.0/8', shouldPass: true },
-    { pattern: '192.168.0.0/16', shouldPass: true },
-    { pattern: '192.168.1.100', shouldPass: true },
-    { pattern: '*', shouldPass: true },
-    { pattern: '192.168.1.1-192.168.1.100', shouldPass: true },
-  ];
-
-  for (const { pattern, shouldPass } of testPatterns) {
-    const route = {
-      name: 'test',
-      match: { ports: 80 },
-      action: { type: 'forward' as const, targets: [{ host: 'localhost', port: 8080 }] },
-      security: { ipAllowList: [pattern] }
-    };
-    
-    const result = RouteValidator.validateRoute(route);
-    
-    if (shouldPass) {
-      expect(result.valid).toEqual(true);
-      console.log(`✅ Pattern '${pattern}' correctly accepted`);
-    } else {
-      expect(result.valid).toEqual(false);
-      console.log(`✅ Pattern '${pattern}' correctly rejected`);
-    }
-  }
-});
-
-tap.test('IP Matching - Runtime shorthand pattern matching', async () => {
-  
-  // Test runtime matching with shorthand patterns
-  const testCases = [
-    { ip: '192.168.1.100', patterns: ['192.168.*'], expected: true },
-    { ip: '192.168.1.100', patterns: ['192.168.1.*'], expected: true },
-    { ip: '192.168.1.100', patterns: ['192.168.2.*'], expected: false },
-    { ip: '10.0.0.1', patterns: ['10.*'], expected: true },
-    { ip: '10.1.2.3', patterns: ['10.*'], expected: true },
-    { ip: '172.16.0.1', patterns: ['10.*'], expected: false },
-    { ip: '192.168.1.1', patterns: ['192.168.*.*'], expected: true },
-  ];
-
-  for (const { ip, patterns, expected } of testCases) {
-    const result = IpUtils.isGlobIPMatch(ip, patterns);
-    expect(result).toEqual(expected);
-    console.log(`✅ IP ${ip} with pattern ${patterns[0]} = ${result} (expected ${expected})`);
-  }
-});
-
-tap.test('IP Matching - CIDR notation', async () => {
-  
-  // Test CIDR notation matching
-  const cidrTests = [
-    { ip: '10.0.0.1', cidr: '10.0.0.0/8', expected: true },
-    { ip: '10.255.255.255', cidr: '10.0.0.0/8', expected: true },
-    { ip: '11.0.0.1', cidr: '10.0.0.0/8', expected: false },
-    { ip: '192.168.1.1', cidr: '192.168.0.0/16', expected: true },
-    { ip: '192.168.255.255', cidr: '192.168.0.0/16', expected: true },
-    { ip: '192.169.0.1', cidr: '192.168.0.0/16', expected: false },
-    { ip: '192.168.1.100', cidr: '192.168.1.0/24', expected: true },
-    { ip: '192.168.2.100', cidr: '192.168.1.0/24', expected: false },
-  ];
-
-  for (const { ip, cidr, expected } of cidrTests) {
-    const result = IpUtils.isGlobIPMatch(ip, [cidr]);
-    expect(result).toEqual(expected);
-    console.log(`✅ IP ${ip} in CIDR ${cidr} = ${result} (expected ${expected})`);
-  }
-});
-
-tap.test('IP Matching - Range notation', async () => {
-  
-  // Test range notation matching
-  const rangeTests = [
-    { ip: '192.168.1.1', range: '192.168.1.1-192.168.1.100', expected: true },
-    { ip: '192.168.1.50', range: '192.168.1.1-192.168.1.100', expected: true },
-    { ip: '192.168.1.100', range: '192.168.1.1-192.168.1.100', expected: true },
-    { ip: '192.168.1.101', range: '192.168.1.1-192.168.1.100', expected: false },
-    { ip: '192.168.2.50', range: '192.168.1.1-192.168.1.100', expected: false },
-  ];
-
-  for (const { ip, range, expected } of rangeTests) {
-    const result = IpUtils.isGlobIPMatch(ip, [range]);
-    expect(result).toEqual(expected);
-    console.log(`✅ IP ${ip} in range ${range} = ${result} (expected ${expected})`);
-  }
-});
-
-tap.test('IP Matching - Mixed patterns', async () => {
-  
-  // Test with mixed pattern types
-  const allowList = [
-    '10.0.0.0/8',      // CIDR
-    '192.168.*',       // Shorthand glob
-    '172.16.1.*',      // Specific subnet glob
-    '8.8.8.8',         // Single IP
-    '1.1.1.1-1.1.1.10' // Range
-  ];
-  
-  const tests = [
-    { ip: '10.1.2.3', expected: true },      // Matches CIDR
-    { ip: '192.168.100.1', expected: true }, // Matches shorthand glob
-    { ip: '172.16.1.5', expected: true },    // Matches specific glob
-    { ip: '8.8.8.8', expected: true },       // Matches single IP
-    { ip: '1.1.1.5', expected: true },       // Matches range
-    { ip: '9.9.9.9', expected: false },      // Doesn't match any
-  ];
-  
-  for (const { ip, expected } of tests) {
-    const result = IpUtils.isGlobIPMatch(ip, allowList);
-    expect(result).toEqual(expected);
-    console.log(`✅ IP ${ip} in mixed patterns = ${result} (expected ${expected})`);
-  }
-});
-
-export default tap.start();

test/test.log-deduplication.node.ts

@@ -1,112 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { LogDeduplicator } from '../ts/core/utils/log-deduplicator.js';
-
-let deduplicator: LogDeduplicator;
-
-tap.test('Setup log deduplicator', async () => {
-  deduplicator = new LogDeduplicator(1000); // 1 second flush interval for testing
-});
-
-tap.test('Connection rejection deduplication', async (tools) => {
-  // Simulate multiple connection rejections
-  for (let i = 0; i < 10; i++) {
-    deduplicator.log(
-      'connection-rejected',
-      'warn',
-      'Connection rejected',
-      { reason: 'global-limit', component: 'test' },
-      'global-limit'
-    );
-  }
-  
-  for (let i = 0; i < 5; i++) {
-    deduplicator.log(
-      'connection-rejected',
-      'warn',
-      'Connection rejected',
-      { reason: 'route-limit', component: 'test' },
-      'route-limit'
-    );
-  }
-  
-  // Force flush
-  deduplicator.flush('connection-rejected');
-  
-  // The logs should have been aggregated
-  // (Can't easily test the actual log output, but we can verify the mechanism works)
-  expect(deduplicator).toBeInstanceOf(LogDeduplicator);
-});
-
-tap.test('IP rejection deduplication', async (tools) => {
-  // Simulate rejections from multiple IPs
-  const ips = ['192.168.1.100', '192.168.1.101', '192.168.1.100', '10.0.0.1'];
-  const reasons = ['per-ip-limit', 'rate-limit', 'per-ip-limit', 'global-limit'];
-  
-  for (let i = 0; i < ips.length; i++) {
-    deduplicator.log(
-      'ip-rejected',
-      'warn',
-      `Connection rejected from ${ips[i]}`,
-      { remoteIP: ips[i], reason: reasons[i] },
-      ips[i]
-    );
-  }
-  
-  // Add more rejections from the same IP
-  for (let i = 0; i < 20; i++) {
-    deduplicator.log(
-      'ip-rejected',
-      'warn',
-      'Connection rejected from 192.168.1.100',
-      { remoteIP: '192.168.1.100', reason: 'rate-limit' },
-      '192.168.1.100'
-    );
-  }
-  
-  // Force flush
-  deduplicator.flush('ip-rejected');
-  
-  // Verify the deduplicator exists and works
-  expect(deduplicator).toBeInstanceOf(LogDeduplicator);
-});
-
-tap.test('Connection cleanup deduplication', async (tools) => {
-  // Simulate various cleanup events
-  const reasons = ['normal', 'timeout', 'error', 'normal', 'zombie'];
-  
-  for (const reason of reasons) {
-    for (let i = 0; i < 5; i++) {
-      deduplicator.log(
-        'connection-cleanup',
-        'info',
-        `Connection cleanup: ${reason}`,
-        { connectionId: `conn-${i}`, reason },
-        reason
-      );
-    }
-  }
-  
-  // Wait for automatic flush
-  await tools.delayFor(1500);
-  
-  // Verify deduplicator is working
-  expect(deduplicator).toBeInstanceOf(LogDeduplicator);
-});
-
-tap.test('Automatic periodic flush', async (tools) => {
-  // Add some events
-  deduplicator.log('test-event', 'info', 'Test message', {}, 'test');
-  
-  // Wait for automatic flush (should happen within 2x flush interval = 2 seconds)
-  await tools.delayFor(2500);
-  
-  // Events should have been flushed automatically
-  expect(deduplicator).toBeInstanceOf(LogDeduplicator);
-});
-
-tap.test('Cleanup deduplicator', async () => {
-  deduplicator.cleanup();
-  expect(deduplicator).toBeInstanceOf(LogDeduplicator);
-});
-
-export default tap.start();

test/test.proxy-protocol.ts

@@ -1,133 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as smartproxy from '../ts/index.js';
-import { ProxyProtocolParser } from '../ts/core/utils/proxy-protocol.js';
-
-tap.test('PROXY protocol v1 parser - valid headers', async () => {
-  // Test TCP4 format
-  const tcp4Header = Buffer.from('PROXY TCP4 192.168.1.1 10.0.0.1 56324 443\r\n', 'ascii');
-  const tcp4Result = ProxyProtocolParser.parse(tcp4Header);
-  
-  expect(tcp4Result.proxyInfo).property('protocol').toEqual('TCP4');
-  expect(tcp4Result.proxyInfo).property('sourceIP').toEqual('192.168.1.1');
-  expect(tcp4Result.proxyInfo).property('sourcePort').toEqual(56324);
-  expect(tcp4Result.proxyInfo).property('destinationIP').toEqual('10.0.0.1');
-  expect(tcp4Result.proxyInfo).property('destinationPort').toEqual(443);
-  expect(tcp4Result.remainingData.length).toEqual(0);
-  
-  // Test TCP6 format
-  const tcp6Header = Buffer.from('PROXY TCP6 2001:db8::1 2001:db8::2 56324 443\r\n', 'ascii');
-  const tcp6Result = ProxyProtocolParser.parse(tcp6Header);
-  
-  expect(tcp6Result.proxyInfo).property('protocol').toEqual('TCP6');
-  expect(tcp6Result.proxyInfo).property('sourceIP').toEqual('2001:db8::1');
-  expect(tcp6Result.proxyInfo).property('sourcePort').toEqual(56324);
-  expect(tcp6Result.proxyInfo).property('destinationIP').toEqual('2001:db8::2');
-  expect(tcp6Result.proxyInfo).property('destinationPort').toEqual(443);
-  
-  // Test UNKNOWN protocol
-  const unknownHeader = Buffer.from('PROXY UNKNOWN\r\n', 'ascii');
-  const unknownResult = ProxyProtocolParser.parse(unknownHeader);
-  
-  expect(unknownResult.proxyInfo).property('protocol').toEqual('UNKNOWN');
-  expect(unknownResult.proxyInfo).property('sourceIP').toEqual('');
-  expect(unknownResult.proxyInfo).property('sourcePort').toEqual(0);
-});
-
-tap.test('PROXY protocol v1 parser - with remaining data', async () => {
-  const headerWithData = Buffer.concat([
-    Buffer.from('PROXY TCP4 192.168.1.1 10.0.0.1 56324 443\r\n', 'ascii'),
-    Buffer.from('GET / HTTP/1.1\r\n', 'ascii')
-  ]);
-  
-  const result = ProxyProtocolParser.parse(headerWithData);
-  
-  expect(result.proxyInfo).property('protocol').toEqual('TCP4');
-  expect(result.proxyInfo).property('sourceIP').toEqual('192.168.1.1');
-  expect(result.remainingData.toString()).toEqual('GET / HTTP/1.1\r\n');
-});
-
-tap.test('PROXY protocol v1 parser - invalid headers', async () => {
-  // Not a PROXY protocol header
-  const notProxy = Buffer.from('GET / HTTP/1.1\r\n', 'ascii');
-  const notProxyResult = ProxyProtocolParser.parse(notProxy);
-  expect(notProxyResult.proxyInfo).toBeNull();
-  expect(notProxyResult.remainingData).toEqual(notProxy);
-  
-  // Invalid protocol
-  expect(() => {
-    ProxyProtocolParser.parse(Buffer.from('PROXY INVALID 1.1.1.1 2.2.2.2 80 443\r\n', 'ascii'));
-  }).toThrow();
-  
-  // Wrong number of fields
-  expect(() => {
-    ProxyProtocolParser.parse(Buffer.from('PROXY TCP4 192.168.1.1 10.0.0.1 56324\r\n', 'ascii'));
-  }).toThrow();
-  
-  // Invalid port
-  expect(() => {
-    ProxyProtocolParser.parse(Buffer.from('PROXY TCP4 192.168.1.1 10.0.0.1 99999 443\r\n', 'ascii'));
-  }).toThrow();
-  
-  // Invalid IP for protocol
-  expect(() => {
-    ProxyProtocolParser.parse(Buffer.from('PROXY TCP4 2001:db8::1 10.0.0.1 56324 443\r\n', 'ascii'));
-  }).toThrow();
-});
-
-tap.test('PROXY protocol v1 parser - incomplete headers', async () => {
-  // Header without terminator
-  const incomplete = Buffer.from('PROXY TCP4 192.168.1.1 10.0.0.1 56324 443', 'ascii');
-  const result = ProxyProtocolParser.parse(incomplete);
-  
-  expect(result.proxyInfo).toBeNull();
-  expect(result.remainingData).toEqual(incomplete);
-  
-  // Header exceeding max length - create a buffer that actually starts with PROXY
-  const longHeader = Buffer.from('PROXY TCP4 ' + '1'.repeat(100), 'ascii');
-  expect(() => {
-    ProxyProtocolParser.parse(longHeader);
-  }).toThrow();
-});
-
-tap.test('PROXY protocol v1 generator', async () => {
-  // Generate TCP4 header
-  const tcp4Info = {
-    protocol: 'TCP4' as const,
-    sourceIP: '192.168.1.1',
-    sourcePort: 56324,
-    destinationIP: '10.0.0.1',
-    destinationPort: 443
-  };
-  
-  const tcp4Header = ProxyProtocolParser.generate(tcp4Info);
-  expect(tcp4Header.toString('ascii')).toEqual('PROXY TCP4 192.168.1.1 10.0.0.1 56324 443\r\n');
-  
-  // Generate TCP6 header
-  const tcp6Info = {
-    protocol: 'TCP6' as const,
-    sourceIP: '2001:db8::1',
-    sourcePort: 56324,
-    destinationIP: '2001:db8::2',
-    destinationPort: 443
-  };
-  
-  const tcp6Header = ProxyProtocolParser.generate(tcp6Info);
-  expect(tcp6Header.toString('ascii')).toEqual('PROXY TCP6 2001:db8::1 2001:db8::2 56324 443\r\n');
-  
-  // Generate UNKNOWN header
-  const unknownInfo = {
-    protocol: 'UNKNOWN' as const,
-    sourceIP: '',
-    sourcePort: 0,
-    destinationIP: '',
-    destinationPort: 0
-  };
-  
-  const unknownHeader = ProxyProtocolParser.generate(unknownInfo);
-  expect(unknownHeader.toString('ascii')).toEqual('PROXY UNKNOWN\r\n');
-});
-
-// Skipping integration tests for now - focus on unit tests
-// Integration tests would require more complex setup and teardown
-
-export default tap.start();

test/test.route-utils.ts

@@ -174,7 +174,7 @@ tap.test('Route Validation - validateRouteAction', async () => {
   const invalidSocketResult = validateRouteAction(invalidSocketAction);
   expect(invalidSocketResult.valid).toBeFalse();
   expect(invalidSocketResult.errors.length).toBeGreaterThan(0);
-  expect(invalidSocketResult.errors[0]).toInclude('Socket handler function is required');
+  expect(invalidSocketResult.errors[0]).toInclude('handler function is required');
 });
 
 tap.test('Route Validation - validateRouteConfig', async () => {

test/test.router.ts

@@ -1,403 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as http from 'http';
-import { HttpRouter, type RouterResult } from '../ts/routing/router/http-router.js';
-import type { IRouteConfig } from '../ts/proxies/smart-proxy/models/route-types.js';
-
-// Test proxies and configurations
-let router: HttpRouter;
-
-// Sample hostname for testing
-const TEST_DOMAIN = 'example.com';
-const TEST_SUBDOMAIN = 'api.example.com';
-const TEST_WILDCARD = '*.example.com';
-
-// Helper: Creates a mock HTTP request for testing
-function createMockRequest(host: string, url: string = '/'): http.IncomingMessage {
-  const req = {
-    headers: { host },
-    url,
-    socket: {
-      remoteAddress: '127.0.0.1'
-    }
-  } as any;
-  return req;
-}
-
-// Helper: Creates a test route configuration
-function createRouteConfig(
-  hostname: string, 
-  destinationIp: string = '10.0.0.1',
-  destinationPort: number = 8080
-): IRouteConfig {
-  return {
-    name: `route-${hostname}`,
-    match: {
-      domains: [hostname],
-      ports: 443
-    },
-    action: {
-      type: 'forward',
-      targets: [{
-        host: destinationIp,
-        port: destinationPort
-      }]
-    }
-  };
-}
-
-// SETUP: Create an HttpRouter instance
-tap.test('setup http router test environment', async () => {
-  router = new HttpRouter();
-  
-  // Initialize with empty config
-  router.setRoutes([]);
-});
-
-// Test basic routing by hostname
-tap.test('should route requests by hostname', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  router.setRoutes([config]);
-  
-  const req = createMockRequest(TEST_DOMAIN);
-  const result = router.routeReq(req);
-  
-  expect(result).toBeTruthy();
-  expect(result).toEqual(config);
-});
-
-// Test handling of hostname with port number
-tap.test('should handle hostname with port number', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  router.setRoutes([config]);
-  
-  const req = createMockRequest(`${TEST_DOMAIN}:443`);
-  const result = router.routeReq(req);
-  
-  expect(result).toBeTruthy();
-  expect(result).toEqual(config);
-});
-
-// Test case-insensitive hostname matching
-tap.test('should perform case-insensitive hostname matching', async () => {
-  const config = createRouteConfig(TEST_DOMAIN.toLowerCase());
-  router.setRoutes([config]);
-  
-  const req = createMockRequest(TEST_DOMAIN.toUpperCase());
-  const result = router.routeReq(req);
-  
-  expect(result).toBeTruthy();
-  expect(result).toEqual(config);
-});
-
-// Test handling of unmatched hostnames
-tap.test('should return undefined for unmatched hostnames', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  router.setRoutes([config]);
-  
-  const req = createMockRequest('unknown.domain.com');
-  const result = router.routeReq(req);
-  
-  expect(result).toBeUndefined();
-});
-
-// Test adding path patterns
-tap.test('should match requests using path patterns', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  config.match.path = '/api/users';
-  router.setRoutes([config]);
-  
-  // Test that path matches
-  const req1 = createMockRequest(TEST_DOMAIN, '/api/users');
-  const result1 = router.routeReqWithDetails(req1);
-  
-  expect(result1).toBeTruthy();
-  expect(result1.route).toEqual(config);
-  expect(result1.pathMatch).toEqual('/api/users');
-  
-  // Test that non-matching path doesn't match
-  const req2 = createMockRequest(TEST_DOMAIN, '/web/users');
-  const result2 = router.routeReqWithDetails(req2);
-  
-  expect(result2).toBeUndefined();
-});
-
-// Test handling wildcard patterns
-tap.test('should support wildcard path patterns', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  config.match.path = '/api/*';
-  router.setRoutes([config]);
-  
-  // Test with path that matches the wildcard pattern
-  const req = createMockRequest(TEST_DOMAIN, '/api/users/123');
-  const result = router.routeReqWithDetails(req);
-  
-  expect(result).toBeTruthy();
-  expect(result.route).toEqual(config);
-  expect(result.pathMatch).toEqual('/api');
-  
-  // Print the actual value to diagnose issues
-  console.log('Path remainder value:', result.pathRemainder);
-  expect(result.pathRemainder).toBeTruthy();
-  expect(result.pathRemainder).toEqual('/users/123');
-});
-
-// Test extracting path parameters
-tap.test('should extract path parameters from URL', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  config.match.path = '/users/:id/profile';
-  router.setRoutes([config]);
-  
-  const req = createMockRequest(TEST_DOMAIN, '/users/123/profile');
-  const result = router.routeReqWithDetails(req);
-  
-  expect(result).toBeTruthy();
-  expect(result.route).toEqual(config);
-  expect(result.pathParams).toBeTruthy();
-  expect(result.pathParams.id).toEqual('123');
-});
-
-// Test multiple configs for same hostname with different paths
-tap.test('should support multiple configs for same hostname with different paths', async () => {
-  const apiConfig = createRouteConfig(TEST_DOMAIN, '10.0.0.1', 8001);
-  apiConfig.match.path = '/api/*';
-  apiConfig.name = 'api-route';
-  
-  const webConfig = createRouteConfig(TEST_DOMAIN, '10.0.0.2', 8002);
-  webConfig.match.path = '/web/*';
-  webConfig.name = 'web-route';
-  
-  // Add both configs
-  router.setRoutes([apiConfig, webConfig]);
-  
-  // Test API path routes to API config
-  const apiReq = createMockRequest(TEST_DOMAIN, '/api/users');
-  const apiResult = router.routeReq(apiReq);
-  
-  expect(apiResult).toEqual(apiConfig);
-  
-  // Test web path routes to web config
-  const webReq = createMockRequest(TEST_DOMAIN, '/web/dashboard');
-  const webResult = router.routeReq(webReq);
-  
-  expect(webResult).toEqual(webConfig);
-  
-  // Test unknown path returns undefined
-  const unknownReq = createMockRequest(TEST_DOMAIN, '/unknown');
-  const unknownResult = router.routeReq(unknownReq);
-  
-  expect(unknownResult).toBeUndefined();
-});
-
-// Test wildcard subdomains
-tap.test('should match wildcard subdomains', async () => {
-  const wildcardConfig = createRouteConfig(TEST_WILDCARD);
-  router.setRoutes([wildcardConfig]);
-  
-  // Test that subdomain.example.com matches *.example.com
-  const req = createMockRequest('subdomain.example.com');
-  const result = router.routeReq(req);
-  
-  expect(result).toBeTruthy();
-  expect(result).toEqual(wildcardConfig);
-});
-
-// Test TLD wildcards (example.*)
-tap.test('should match TLD wildcards', async () => {
-  const tldWildcardConfig = createRouteConfig('example.*');
-  router.setRoutes([tldWildcardConfig]);
-  
-  // Test that example.com matches example.*
-  const req1 = createMockRequest('example.com');
-  const result1 = router.routeReq(req1);
-  expect(result1).toBeTruthy();
-  expect(result1).toEqual(tldWildcardConfig);
-  
-  // Test that example.org matches example.*
-  const req2 = createMockRequest('example.org');
-  const result2 = router.routeReq(req2);
-  expect(result2).toBeTruthy();
-  expect(result2).toEqual(tldWildcardConfig);
-  
-  // Test that subdomain.example.com doesn't match example.*
-  const req3 = createMockRequest('subdomain.example.com');
-  const result3 = router.routeReq(req3);
-  expect(result3).toBeUndefined();
-});
-
-// Test complex pattern matching (*.lossless*)
-tap.test('should match complex wildcard patterns', async () => {
-  const complexWildcardConfig = createRouteConfig('*.lossless*');
-  router.setRoutes([complexWildcardConfig]);
-  
-  // Test that sub.lossless.com matches *.lossless*
-  const req1 = createMockRequest('sub.lossless.com');
-  const result1 = router.routeReq(req1);
-  expect(result1).toBeTruthy();
-  expect(result1).toEqual(complexWildcardConfig);
-  
-  // Test that api.lossless.org matches *.lossless*
-  const req2 = createMockRequest('api.lossless.org');
-  const result2 = router.routeReq(req2);
-  expect(result2).toBeTruthy();
-  expect(result2).toEqual(complexWildcardConfig);
-  
-  // Test that losslessapi.com matches *.lossless*
-  const req3 = createMockRequest('losslessapi.com');
-  const result3 = router.routeReq(req3);
-  expect(result3).toBeUndefined(); // Should not match as it doesn't have a subdomain
-});
-
-// Test default configuration fallback
-tap.test('should fall back to default configuration', async () => {
-  const defaultConfig = createRouteConfig('*');
-  const specificConfig = createRouteConfig(TEST_DOMAIN);
-  
-  router.setRoutes([specificConfig, defaultConfig]);
-  
-  // Test specific domain routes to specific config
-  const specificReq = createMockRequest(TEST_DOMAIN);
-  const specificResult = router.routeReq(specificReq);
-  
-  expect(specificResult).toEqual(specificConfig);
-  
-  // Test unknown domain falls back to default config
-  const unknownReq = createMockRequest('unknown.com');
-  const unknownResult = router.routeReq(unknownReq);
-  
-  expect(unknownResult).toEqual(defaultConfig);
-});
-
-// Test priority between exact and wildcard matches
-tap.test('should prioritize exact hostname over wildcard', async () => {
-  const wildcardConfig = createRouteConfig(TEST_WILDCARD);
-  const exactConfig = createRouteConfig(TEST_SUBDOMAIN);
-  
-  router.setRoutes([exactConfig, wildcardConfig]);
-  
-  // Test that exact match takes priority
-  const req = createMockRequest(TEST_SUBDOMAIN);
-  const result = router.routeReq(req);
-  
-  expect(result).toEqual(exactConfig);
-});
-
-// Test adding and removing configurations
-tap.test('should manage configurations correctly', async () => {
-  router.setRoutes([]);
-  
-  // Add a config
-  const config = createRouteConfig(TEST_DOMAIN);
-  router.setRoutes([config]);
-  
-  // Verify routing works
-  const req = createMockRequest(TEST_DOMAIN);
-  let result = router.routeReq(req);
-  
-  expect(result).toEqual(config);
-  
-  // Remove the config and verify it no longer routes
-  router.setRoutes([]);
-  
-  result = router.routeReq(req);
-  expect(result).toBeUndefined();
-});
-
-// Test path pattern specificity
-tap.test('should prioritize more specific path patterns', async () => {
-  const genericConfig = createRouteConfig(TEST_DOMAIN, '10.0.0.1', 8001);
-  genericConfig.match.path = '/api/*';
-  genericConfig.name = 'generic-api';
-  
-  const specificConfig = createRouteConfig(TEST_DOMAIN, '10.0.0.2', 8002);
-  specificConfig.match.path = '/api/users';
-  specificConfig.name = 'specific-api';
-  specificConfig.priority = 10; // Higher priority
-  
-  router.setRoutes([genericConfig, specificConfig]);
-  
-  // The more specific '/api/users' should match before the '/api/*' wildcard
-  const req = createMockRequest(TEST_DOMAIN, '/api/users');
-  const result = router.routeReq(req);
-  
-  expect(result).toEqual(specificConfig);
-});
-
-// Test multiple hostnames
-tap.test('should handle multiple configured hostnames', async () => {
-  const routes = [
-    createRouteConfig(TEST_DOMAIN),
-    createRouteConfig(TEST_SUBDOMAIN)
-  ];
-  router.setRoutes(routes);
-  
-  // Test first domain routes correctly
-  const req1 = createMockRequest(TEST_DOMAIN);
-  const result1 = router.routeReq(req1);
-  expect(result1).toEqual(routes[0]);
-  
-  // Test second domain routes correctly
-  const req2 = createMockRequest(TEST_SUBDOMAIN);
-  const result2 = router.routeReq(req2);
-  expect(result2).toEqual(routes[1]);
-});
-
-// Test handling missing host header
-tap.test('should handle missing host header', async () => {
-  const defaultConfig = createRouteConfig('*');
-  router.setRoutes([defaultConfig]);
-  
-  const req = createMockRequest('');
-  req.headers.host = undefined;
-  
-  const result = router.routeReq(req);
-  
-  expect(result).toEqual(defaultConfig);
-});
-
-// Test complex path parameters
-tap.test('should handle complex path parameters', async () => {
-  const config = createRouteConfig(TEST_DOMAIN);
-  config.match.path = '/api/:version/users/:userId/posts/:postId';
-  router.setRoutes([config]);
-  
-  const req = createMockRequest(TEST_DOMAIN, '/api/v1/users/123/posts/456');
-  const result = router.routeReqWithDetails(req);
-  
-  expect(result).toBeTruthy();
-  expect(result.route).toEqual(config);
-  expect(result.pathParams).toBeTruthy();
-  expect(result.pathParams.version).toEqual('v1');
-  expect(result.pathParams.userId).toEqual('123');
-  expect(result.pathParams.postId).toEqual('456');
-});
-
-// Performance test
-tap.test('should handle many configurations efficiently', async () => {
-  const configs = [];
-  
-  // Create many configs with different hostnames
-  for (let i = 0; i < 100; i++) {
-    configs.push(createRouteConfig(`host-${i}.example.com`));
-  }
-  
-  router.setRoutes(configs);
-  
-  // Test middle of the list to avoid best/worst case
-  const req = createMockRequest('host-50.example.com');
-  const result = router.routeReq(req);
-  
-  expect(result).toEqual(configs[50]);
-});
-
-// Test cleanup
-tap.test('cleanup proxy router test environment', async () => {
-  // Clear all configurations
-  router.setRoutes([]);
-  
-  // Verify empty state by testing that no routes match
-  const req = createMockRequest(TEST_DOMAIN);
-  const result = router.routeReq(req);
-  expect(result).toBeUndefined();
-});
-
-export default tap.start();

test/test.shared-security-manager-limits.node.ts

@@ -1,157 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { SharedSecurityManager } from '../ts/core/utils/shared-security-manager.js';
-import type { IRouteConfig, IRouteContext } from '../ts/proxies/smart-proxy/models/route-types.js';
-
-let securityManager: SharedSecurityManager;
-
-tap.test('Setup SharedSecurityManager', async () => {
-  securityManager = new SharedSecurityManager({
-    maxConnectionsPerIP: 5,
-    connectionRateLimitPerMinute: 10,
-    cleanupIntervalMs: 1000 // 1 second for faster testing
-  });
-});
-
-tap.test('IP connection tracking', async () => {
-  const testIP = '192.168.1.100';
-  
-  // Track multiple connections
-  securityManager.trackConnectionByIP(testIP, 'conn1');
-  securityManager.trackConnectionByIP(testIP, 'conn2');
-  securityManager.trackConnectionByIP(testIP, 'conn3');
-  
-  // Verify connection count
-  expect(securityManager.getConnectionCountByIP(testIP)).toEqual(3);
-  
-  // Remove a connection
-  securityManager.removeConnectionByIP(testIP, 'conn2');
-  expect(securityManager.getConnectionCountByIP(testIP)).toEqual(2);
-  
-  // Remove remaining connections
-  securityManager.removeConnectionByIP(testIP, 'conn1');
-  securityManager.removeConnectionByIP(testIP, 'conn3');
-  expect(securityManager.getConnectionCountByIP(testIP)).toEqual(0);
-});
-
-tap.test('Per-IP connection limits validation', async () => {
-  const testIP = '192.168.1.101';
-  
-  // Track connections up to limit
-  for (let i = 1; i <= 5; i++) {
-    // Validate BEFORE tracking the connection (checking if we can add a new connection)
-    const result = securityManager.validateIP(testIP);
-    expect(result.allowed).toBeTrue();
-    // Now track the connection
-    securityManager.trackConnectionByIP(testIP, `conn${i}`);
-  }
-  
-  // Verify we're at the limit
-  expect(securityManager.getConnectionCountByIP(testIP)).toEqual(5);
-  
-  // Next connection should be rejected (we're already at 5)
-  const result = securityManager.validateIP(testIP);
-  expect(result.allowed).toBeFalse();
-  expect(result.reason).toInclude('Maximum connections per IP');
-  
-  // Clean up
-  for (let i = 1; i <= 5; i++) {
-    securityManager.removeConnectionByIP(testIP, `conn${i}`);
-  }
-});
-
-tap.test('Connection rate limiting', async () => {
-  const testIP = '192.168.1.102';
-  
-  // Make connections at the rate limit
-  // Note: validateIP() already tracks timestamps internally for rate limiting
-  for (let i = 0; i < 10; i++) {
-    const result = securityManager.validateIP(testIP);
-    expect(result.allowed).toBeTrue();
-  }
-  
-  // Next connection should exceed rate limit
-  const result = securityManager.validateIP(testIP);
-  expect(result.allowed).toBeFalse();
-  expect(result.reason).toInclude('Connection rate limit');
-});
-
-tap.test('Route-level connection limits', async () => {
-  const route: IRouteConfig = {
-    name: 'test-route',
-    match: { ports: 443 },
-    action: { type: 'forward', targets: [{ host: 'localhost', port: 8080 }] },
-    security: {
-      maxConnections: 3
-    }
-  };
-  
-  const context: IRouteContext = {
-    port: 443,
-    clientIp: '192.168.1.103',
-    serverIp: '0.0.0.0',
-    timestamp: Date.now(),
-    connectionId: 'test-conn',
-    isTls: true
-  };
-  
-  // Test with connection counts below limit
-  expect(securityManager.isAllowed(route, context, 0)).toBeTrue();
-  expect(securityManager.isAllowed(route, context, 2)).toBeTrue();
-  
-  // Test at limit
-  expect(securityManager.isAllowed(route, context, 3)).toBeFalse();
-  
-  // Test above limit
-  expect(securityManager.isAllowed(route, context, 5)).toBeFalse();
-});
-
-tap.test('IPv4/IPv6 normalization', async () => {
-  const ipv4 = '127.0.0.1';
-  const ipv4Mapped = '::ffff:127.0.0.1';
-  
-  // Track connection with IPv4
-  securityManager.trackConnectionByIP(ipv4, 'conn1');
-  
-  // Both representations should show the same connection
-  expect(securityManager.getConnectionCountByIP(ipv4)).toEqual(1);
-  expect(securityManager.getConnectionCountByIP(ipv4Mapped)).toEqual(1);
-  
-  // Track another connection with IPv6 representation
-  securityManager.trackConnectionByIP(ipv4Mapped, 'conn2');
-  
-  // Both should show 2 connections
-  expect(securityManager.getConnectionCountByIP(ipv4)).toEqual(2);
-  expect(securityManager.getConnectionCountByIP(ipv4Mapped)).toEqual(2);
-  
-  // Clean up
-  securityManager.removeConnectionByIP(ipv4, 'conn1');
-  securityManager.removeConnectionByIP(ipv4Mapped, 'conn2');
-});
-
-tap.test('Automatic cleanup of expired data', async (tools) => {
-  const testIP = '192.168.1.104';
-  
-  // Track a connection and then remove it
-  securityManager.trackConnectionByIP(testIP, 'temp-conn');
-  securityManager.removeConnectionByIP(testIP, 'temp-conn');
-  
-  // Add some rate limit entries (they expire after 1 minute)
-  for (let i = 0; i < 5; i++) {
-    securityManager.validateIP(testIP);
-  }
-  
-  // Wait for cleanup interval (set to 1 second in our test)
-  await tools.delayFor(1500);
-  
-  // The IP should be cleaned up since it has no connections
-  // Note: We can't directly check the internal map, but we can verify
-  // that a new connection is allowed (fresh rate limit)
-  const result = securityManager.validateIP(testIP);
-  expect(result.allowed).toBeTrue();
-});
-
-tap.test('Cleanup SharedSecurityManager', async () => {
-  securityManager.clearIPTracking();
-});
-
-export default tap.start();

test/test.udp-forwarding.ts

@@ -0,0 +1,142 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as dgram from 'dgram';
+import { SmartProxy } from '../ts/index.js';
+import { findFreePorts, assertPortsFree } from './helpers/port-allocator.js';
+
+let smartProxy: SmartProxy;
+let backendServer: dgram.Socket;
+let PROXY_PORT: number;
+let BACKEND_PORT: number;
+
+// Helper: send a single UDP datagram and wait for a response
+function sendDatagram(port: number, msg: string, timeoutMs = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const client = dgram.createSocket('udp4');
+    const timeout = setTimeout(() => {
+      client.close();
+      reject(new Error(`UDP response timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    client.send(Buffer.from(msg), port, '127.0.0.1');
+    client.on('message', (data) => {
+      clearTimeout(timeout);
+      client.close();
+      resolve(data.toString());
+    });
+    client.on('error', (err) => {
+      clearTimeout(timeout);
+      client.close();
+      reject(err);
+    });
+  });
+}
+
+// Helper: create a UDP echo server
+function createUdpEchoServer(port: number): Promise<dgram.Socket> {
+  return new Promise((resolve) => {
+    const server = dgram.createSocket('udp4');
+    server.on('message', (msg, rinfo) => {
+      server.send(Buffer.from(`Echo: ${msg.toString()}`), rinfo.port, rinfo.address);
+    });
+    server.bind(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+tap.test('setup: start UDP echo server and SmartProxy', async () => {
+  [PROXY_PORT, BACKEND_PORT] = await findFreePorts(2);
+
+  // Start backend UDP echo server
+  backendServer = await createUdpEchoServer(BACKEND_PORT);
+
+  // Start SmartProxy with a UDP forwarding route
+  smartProxy = new SmartProxy({
+    routes: [
+      {
+        name: 'udp-forward-test',
+        match: {
+          ports: PROXY_PORT,
+          transport: 'udp' as const,
+        },
+        action: {
+          type: 'forward',
+          targets: [{ host: '127.0.0.1', port: BACKEND_PORT }],
+          udp: {
+            sessionTimeout: 5000,
+          },
+        },
+      },
+    ],
+    defaults: {
+      security: {
+        ipAllowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+      },
+    },
+  });
+
+  await smartProxy.start();
+});
+
+tap.test('UDP forwarding: basic datagram round-trip', async () => {
+  const response = await sendDatagram(PROXY_PORT, 'Hello UDP');
+  expect(response).toEqual('Echo: Hello UDP');
+});
+
+tap.test('UDP forwarding: multiple datagrams same session', async () => {
+  // Use a single client socket for session reuse
+  const client = dgram.createSocket('udp4');
+  const responses: string[] = [];
+
+  const done = new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      client.close();
+      reject(new Error('Timeout waiting for 3 responses'));
+    }, 5000);
+
+    client.on('message', (data) => {
+      responses.push(data.toString());
+      if (responses.length === 3) {
+        clearTimeout(timeout);
+        client.close();
+        resolve();
+      }
+    });
+    client.on('error', (err) => {
+      clearTimeout(timeout);
+      client.close();
+      reject(err);
+    });
+  });
+
+  client.send(Buffer.from('msg1'), PROXY_PORT, '127.0.0.1');
+  client.send(Buffer.from('msg2'), PROXY_PORT, '127.0.0.1');
+  client.send(Buffer.from('msg3'), PROXY_PORT, '127.0.0.1');
+
+  await done;
+
+  expect(responses).toContain('Echo: msg1');
+  expect(responses).toContain('Echo: msg2');
+  expect(responses).toContain('Echo: msg3');
+});
+
+tap.test('UDP forwarding: multiple clients', async () => {
+  const [resp1, resp2] = await Promise.all([
+    sendDatagram(PROXY_PORT, 'client1'),
+    sendDatagram(PROXY_PORT, 'client2'),
+  ]);
+
+  expect(resp1).toEqual('Echo: client1');
+  expect(resp2).toEqual('Echo: client2');
+});
+
+tap.test('UDP forwarding: large datagram (1400 bytes)', async () => {
+  const payload = 'X'.repeat(1400);
+  const response = await sendDatagram(PROXY_PORT, payload);
+  expect(response).toEqual(`Echo: ${payload}`);
+});
+
+tap.test('cleanup: stop SmartProxy and backend', async () => {
+  await smartProxy.stop();
+  await new Promise<void>((resolve) => backendServer.close(() => resolve()));
+  await assertPortsFree([PROXY_PORT, BACKEND_PORT]);
+});
+
+export default tap.start();

test/test.udp-metrics.ts

@@ -0,0 +1,114 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as dgram from 'dgram';
+import { SmartProxy } from '../ts/index.js';
+import { findFreePorts, assertPortsFree } from './helpers/port-allocator.js';
+
+let smartProxy: SmartProxy;
+let backendServer: dgram.Socket;
+let PROXY_PORT: number;
+let BACKEND_PORT: number;
+
+// Helper: send a single UDP datagram and wait for a response
+function sendDatagram(port: number, msg: string, timeoutMs = 5000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const client = dgram.createSocket('udp4');
+    const timeout = setTimeout(() => {
+      client.close();
+      reject(new Error(`UDP response timeout after ${timeoutMs}ms`));
+    }, timeoutMs);
+    client.send(Buffer.from(msg), port, '127.0.0.1');
+    client.on('message', (data) => {
+      clearTimeout(timeout);
+      client.close();
+      resolve(data.toString());
+    });
+    client.on('error', (err) => {
+      clearTimeout(timeout);
+      client.close();
+      reject(err);
+    });
+  });
+}
+
+// Helper: create a UDP echo server
+function createUdpEchoServer(port: number): Promise<dgram.Socket> {
+  return new Promise((resolve) => {
+    const server = dgram.createSocket('udp4');
+    server.on('message', (msg, rinfo) => {
+      server.send(Buffer.from(`Echo: ${msg.toString()}`), rinfo.port, rinfo.address);
+    });
+    server.bind(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+tap.test('setup: start UDP echo server and SmartProxy with metrics', async () => {
+  [PROXY_PORT, BACKEND_PORT] = await findFreePorts(2);
+
+  backendServer = await createUdpEchoServer(BACKEND_PORT);
+
+  smartProxy = new SmartProxy({
+    routes: [
+      {
+        name: 'udp-metrics-test',
+        match: {
+          ports: PROXY_PORT,
+          transport: 'udp' as const,
+        },
+        action: {
+          type: 'forward',
+          targets: [{ host: '127.0.0.1', port: BACKEND_PORT }],
+          udp: {
+            sessionTimeout: 10000,
+          },
+        },
+      },
+    ],
+    defaults: {
+      security: {
+        ipAllowList: ['127.0.0.1', '::1', '::ffff:127.0.0.1'],
+      },
+    },
+    metrics: {
+      enabled: true,
+      sampleIntervalMs: 1000,
+      retentionSeconds: 60,
+    },
+  });
+
+  await smartProxy.start();
+});
+
+tap.test('UDP metrics: counters increase after traffic', async () => {
+  // Send a few datagrams
+  const resp1 = await sendDatagram(PROXY_PORT, 'metrics-test-1');
+  expect(resp1).toEqual('Echo: metrics-test-1');
+
+  const resp2 = await sendDatagram(PROXY_PORT, 'metrics-test-2');
+  expect(resp2).toEqual('Echo: metrics-test-2');
+
+  // Wait for metrics to propagate and cache to refresh
+  await new Promise<void>((resolve) => setTimeout(resolve, 2000));
+
+  // Get metrics (returns the adapter, need to ensure cache is fresh)
+  const metrics = smartProxy.getMetrics();
+
+  // The udp property reads from the Rust JSON snapshot
+  expect(metrics.udp).toBeDefined();
+  const totalSessions = metrics.udp.totalSessions();
+  const datagramsIn = metrics.udp.datagramsIn();
+  const datagramsOut = metrics.udp.datagramsOut();
+
+  console.log(`UDP metrics: sessions=${totalSessions}, in=${datagramsIn}, out=${datagramsOut}`);
+
+  expect(totalSessions).toBeGreaterThan(0);
+  expect(datagramsIn).toBeGreaterThan(0);
+  expect(datagramsOut).toBeGreaterThan(0);
+});
+
+tap.test('cleanup: stop SmartProxy and backend', async () => {
+  await smartProxy.stop();
+  await new Promise<void>((resolve) => backendServer.close(() => resolve()));
+  await assertPortsFree([PROXY_PORT, BACKEND_PORT]);
+});
+
+export default tap.start();

test/test.wrapped-socket.ts

@@ -1,315 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import * as plugins from '../ts/plugins.js';
-import { WrappedSocket } from '../ts/core/models/wrapped-socket.js';
-import * as net from 'net';
-
-tap.test('WrappedSocket - should wrap a regular socket', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  
-  // Wrap the socket
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Test initial state - should use underlying socket values
-  expect(wrappedSocket.remoteAddress).toEqual(clientSocket.remoteAddress);
-  expect(wrappedSocket.remotePort).toEqual(clientSocket.remotePort);
-  expect(wrappedSocket.localAddress).toEqual(clientSocket.localAddress);
-  expect(wrappedSocket.localPort).toEqual(clientSocket.localPort);
-  expect(wrappedSocket.isFromTrustedProxy).toBeFalse();
-  
-  // Clean up
-  clientSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should provide real client info when set', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  
-  // Wrap the socket with initial proxy info
-  const wrappedSocket = new WrappedSocket(clientSocket, '192.168.1.100', 54321);
-  
-  // Test that real client info is returned
-  expect(wrappedSocket.remoteAddress).toEqual('192.168.1.100');
-  expect(wrappedSocket.remotePort).toEqual(54321);
-  expect(wrappedSocket.isFromTrustedProxy).toBeTrue();
-  
-  // Local info should still come from underlying socket
-  expect(wrappedSocket.localAddress).toEqual(clientSocket.localAddress);
-  expect(wrappedSocket.localPort).toEqual(clientSocket.localPort);
-  
-  // Clean up
-  clientSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should update proxy info via setProxyInfo', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  
-  // Wrap the socket without initial proxy info
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Initially should use underlying socket
-  expect(wrappedSocket.isFromTrustedProxy).toBeFalse();
-  expect(wrappedSocket.remoteAddress).toEqual(clientSocket.remoteAddress);
-  
-  // Update proxy info
-  wrappedSocket.setProxyInfo('10.0.0.5', 12345);
-  
-  // Now should return proxy info
-  expect(wrappedSocket.remoteAddress).toEqual('10.0.0.5');
-  expect(wrappedSocket.remotePort).toEqual(12345);
-  expect(wrappedSocket.isFromTrustedProxy).toBeTrue();
-  
-  // Clean up
-  clientSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should correctly determine IP family', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  
-  // Test IPv4
-  const wrappedSocketIPv4 = new WrappedSocket(clientSocket, '192.168.1.1', 80);
-  expect(wrappedSocketIPv4.remoteFamily).toEqual('IPv4');
-  
-  // Test IPv6
-  const wrappedSocketIPv6 = new WrappedSocket(clientSocket, '2001:0db8:85a3:0000:0000:8a2e:0370:7334', 443);
-  expect(wrappedSocketIPv6.remoteFamily).toEqual('IPv6');
-  
-  // Test fallback to underlying socket
-  const wrappedSocketNoProxy = new WrappedSocket(clientSocket);
-  expect(wrappedSocketNoProxy.remoteFamily).toEqual(clientSocket.remoteFamily);
-  
-  // Clean up
-  clientSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should forward events correctly', async () => {
-  // Create a simple echo server
-  let serverConnection: net.Socket;
-  const server = net.createServer((socket) => {
-    serverConnection = socket;
-    socket.on('data', (data) => {
-      socket.write(data); // Echo back
-    });
-  });
-  
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  
-  // Wrap the socket
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Set up event tracking
-  let connectReceived = false;
-  let dataReceived = false;
-  let endReceived = false;
-  let closeReceived = false;
-  
-  wrappedSocket.on('connect', () => {
-    connectReceived = true;
-  });
-  
-  wrappedSocket.on('data', (chunk) => {
-    dataReceived = true;
-    expect(chunk.toString()).toEqual('test data');
-  });
-  
-  wrappedSocket.on('end', () => {
-    endReceived = true;
-  });
-  
-  wrappedSocket.on('close', () => {
-    closeReceived = true;
-  });
-  
-  // Wait for connection
-  await new Promise<void>((resolve) => {
-    if (clientSocket.readyState === 'open') {
-      resolve();
-    } else {
-      clientSocket.once('connect', () => resolve());
-    }
-  });
-  
-  // Send data
-  wrappedSocket.write('test data');
-  
-  // Wait for echo
-  await new Promise(resolve => setTimeout(resolve, 100));
-  
-  // Close the connection
-  serverConnection.end();
-  
-  // Wait for events
-  await new Promise(resolve => setTimeout(resolve, 100));
-  
-  // Verify all events were received
-  expect(dataReceived).toBeTrue();
-  expect(endReceived).toBeTrue();
-  expect(closeReceived).toBeTrue();
-  
-  // Clean up
-  server.close();
-});
-
-tap.test('WrappedSocket - should pass through socket methods', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  await new Promise<void>((resolve) => {
-    clientSocket.once('connect', () => resolve());
-  });
-  
-  // Wrap the socket
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Test various pass-through methods
-  expect(wrappedSocket.readable).toEqual(clientSocket.readable);
-  expect(wrappedSocket.writable).toEqual(clientSocket.writable);
-  expect(wrappedSocket.destroyed).toEqual(clientSocket.destroyed);
-  expect(wrappedSocket.bytesRead).toEqual(clientSocket.bytesRead);
-  expect(wrappedSocket.bytesWritten).toEqual(clientSocket.bytesWritten);
-  
-  // Test method calls
-  wrappedSocket.pause();
-  expect(clientSocket.isPaused()).toBeTrue();
-  
-  wrappedSocket.resume();
-  expect(clientSocket.isPaused()).toBeFalse();
-  
-  // Test setTimeout
-  let timeoutCalled = false;
-  wrappedSocket.setTimeout(100, () => {
-    timeoutCalled = true;
-  });
-  await new Promise(resolve => setTimeout(resolve, 150));
-  expect(timeoutCalled).toBeTrue();
-  
-  // Clean up
-  wrappedSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should handle write and pipe operations', async () => {
-  // Create a simple echo server
-  const server = net.createServer((socket) => {
-    socket.pipe(socket); // Echo everything back
-  });
-  
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  await new Promise<void>((resolve) => {
-    clientSocket.once('connect', () => resolve());
-  });
-  
-  // Wrap the socket
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Test write with callback
-  const writeResult = wrappedSocket.write('test', 'utf8', () => {
-    // Write completed
-  });
-  expect(typeof writeResult).toEqual('boolean');
-  
-  // Test pipe
-  const { PassThrough } = await import('stream');
-  const passThrough = new PassThrough();
-  const piped = wrappedSocket.pipe(passThrough);
-  expect(piped).toEqual(passThrough);
-  
-  // Clean up
-  wrappedSocket.destroy();
-  server.close();
-});
-
-tap.test('WrappedSocket - should handle encoding and address methods', async () => {
-  // Create a simple test server
-  const server = net.createServer();
-  await new Promise<void>((resolve) => {
-    server.listen(0, 'localhost', () => resolve());
-  });
-  
-  const serverPort = (server.address() as net.AddressInfo).port;
-  
-  // Create a client connection
-  const clientSocket = net.connect(serverPort, 'localhost');
-  await new Promise<void>((resolve) => {
-    clientSocket.once('connect', () => resolve());
-  });
-  
-  // Wrap the socket
-  const wrappedSocket = new WrappedSocket(clientSocket);
-  
-  // Test setEncoding
-  wrappedSocket.setEncoding('utf8');
-  
-  // Test address method
-  const addr = wrappedSocket.address();
-  expect(addr).toEqual(clientSocket.address());
-  
-  // Test cork/uncork (if available)
-  wrappedSocket.cork();
-  wrappedSocket.uncork();
-  
-  // Clean up
-  wrappedSocket.destroy();
-  server.close();
-});
-
-export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '25.11.7',
+  version: '26.0.0',
   description: 'A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.'
 }

ts/core/events/index.ts

@@ -1,3 +0,0 @@
-/**
- * Common event definitions
- */

ts/core/index.ts

@@ -5,4 +5,3 @@
 // Export submodules
 export * from './models/index.js';
 export * from './utils/index.js';
-export * from './events/index.js';

ts/core/models/index.ts

@@ -3,7 +3,6 @@
  */
 
 export * from './common-types.js';
-export * from './socket-augmentation.js';
 export * from './route-context.js';
 export * from './wrapped-socket.js';
 export * from './socket-types.js';

ts/core/models/socket-augmentation.ts

@@ -1,38 +0,0 @@
-import * as plugins from '../../plugins.js';
-
-// Augment the Node.js Socket type to include TLS-related properties
-// This helps TypeScript understand properties that are dynamically added by Node.js
-declare module 'net' {
-  interface Socket {
-    // TLS-related properties
-    encrypted?: boolean;    // Indicates if the socket is encrypted (TLS/SSL)
-    authorizationError?: Error; // Authentication error if TLS handshake failed
-    
-    // TLS-related methods
-    getTLSVersion?(): string;  // Returns the TLS version (e.g., 'TLSv1.2', 'TLSv1.3')
-    getPeerCertificate?(detailed?: boolean): any;  // Returns the peer's certificate
-    getSession?(): Buffer;   // Returns the TLS session data
-    
-    // Connection tracking properties (used by HttpProxy)
-    _connectionId?: string;   // Unique identifier for the connection
-    _remoteIP?: string;       // Remote IP address
-    _realRemoteIP?: string;   // Real remote IP (when proxied)
-  }
-}
-
-// Export a utility function to check if a socket is a TLS socket
-export function isTLSSocket(socket: plugins.net.Socket): boolean {
-  return 'encrypted' in socket && !!socket.encrypted;
-}
-
-// Export a utility function to safely get the TLS version
-export function getTLSVersion(socket: plugins.net.Socket): string | null {
-  if (socket.getTLSVersion) {
-    try {
-      return socket.getTLSVersion();
-    } catch (e) {
-      return null;
-    }
-  }
-  return null;
-}

ts/core/utils/async-utils.ts

@@ -1,275 +0,0 @@
-/**
- * Async utility functions for SmartProxy
- * Provides non-blocking alternatives to synchronous operations
- */
-
-/**
- * Delays execution for the specified number of milliseconds
- * Non-blocking alternative to busy wait loops
- * @param ms - Number of milliseconds to delay
- * @returns Promise that resolves after the delay
- */
-export async function delay(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-/**
- * Retry an async operation with exponential backoff
- * @param fn - The async function to retry
- * @param options - Retry options
- * @returns The result of the function or throws the last error
- */
-export async function retryWithBackoff<T>(
-  fn: () => Promise<T>,
-  options: {
-    maxAttempts?: number;
-    initialDelay?: number;
-    maxDelay?: number;
-    factor?: number;
-    onRetry?: (attempt: number, error: Error) => void;
-  } = {}
-): Promise<T> {
-  const {
-    maxAttempts = 3,
-    initialDelay = 100,
-    maxDelay = 10000,
-    factor = 2,
-    onRetry
-  } = options;
-
-  let lastError: Error | null = null;
-  let currentDelay = initialDelay;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn();
-    } catch (error: any) {
-      lastError = error;
-      
-      if (attempt === maxAttempts) {
-        throw error;
-      }
-
-      if (onRetry) {
-        onRetry(attempt, error);
-      }
-
-      await delay(currentDelay);
-      currentDelay = Math.min(currentDelay * factor, maxDelay);
-    }
-  }
-
-  throw lastError || new Error('Retry failed');
-}
-
-/**
- * Execute an async operation with a timeout
- * @param fn - The async function to execute
- * @param timeoutMs - Timeout in milliseconds
- * @param timeoutError - Optional custom timeout error
- * @returns The result of the function or throws timeout error
- */
-export async function withTimeout<T>(
-  fn: () => Promise<T>,
-  timeoutMs: number,
-  timeoutError?: Error
-): Promise<T> {
-  const timeoutPromise = new Promise<never>((_, reject) => {
-    setTimeout(() => {
-      reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
-    }, timeoutMs);
-  });
-
-  return Promise.race([fn(), timeoutPromise]);
-}
-
-/**
- * Run multiple async operations in parallel with a concurrency limit
- * @param items - Array of items to process
- * @param fn - Async function to run for each item
- * @param concurrency - Maximum number of concurrent operations
- * @returns Array of results in the same order as input
- */
-export async function parallelLimit<T, R>(
-  items: T[],
-  fn: (item: T, index: number) => Promise<R>,
-  concurrency: number
-): Promise<R[]> {
-  const results: R[] = new Array(items.length);
-  const executing: Set<Promise<void>> = new Set();
-  
-  for (let i = 0; i < items.length; i++) {
-    const promise = fn(items[i], i).then(result => {
-      results[i] = result;
-      executing.delete(promise);
-    });
-    
-    executing.add(promise);
-    
-    if (executing.size >= concurrency) {
-      await Promise.race(executing);
-    }
-  }
-  
-  await Promise.all(executing);
-  return results;
-}
-
-/**
- * Debounce an async function
- * @param fn - The async function to debounce
- * @param delayMs - Delay in milliseconds
- * @returns Debounced function with cancel method
- */
-export function debounceAsync<T extends (...args: any[]) => Promise<any>>(
-  fn: T,
-  delayMs: number
-): T & { cancel: () => void } {
-  let timeoutId: NodeJS.Timeout | null = null;
-  let lastPromise: Promise<any> | null = null;
-
-  const debounced = ((...args: Parameters<T>) => {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-    }
-
-    lastPromise = new Promise((resolve, reject) => {
-      timeoutId = setTimeout(async () => {
-        timeoutId = null;
-        try {
-          const result = await fn(...args);
-          resolve(result);
-        } catch (error) {
-          reject(error);
-        }
-      }, delayMs);
-    });
-
-    return lastPromise;
-  }) as any;
-
-  debounced.cancel = () => {
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-      timeoutId = null;
-    }
-  };
-
-  return debounced as T & { cancel: () => void };
-}
-
-/**
- * Create a mutex for ensuring exclusive access to a resource
- */
-export class AsyncMutex {
-  private queue: Array<() => void> = [];
-  private locked = false;
-
-  async acquire(): Promise<() => void> {
-    if (!this.locked) {
-      this.locked = true;
-      return () => this.release();
-    }
-
-    return new Promise<() => void>(resolve => {
-      this.queue.push(() => {
-        resolve(() => this.release());
-      });
-    });
-  }
-
-  private release(): void {
-    const next = this.queue.shift();
-    if (next) {
-      next();
-    } else {
-      this.locked = false;
-    }
-  }
-
-  async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
-    const release = await this.acquire();
-    try {
-      return await fn();
-    } finally {
-      release();
-    }
-  }
-}
-
-/**
- * Circuit breaker for protecting against cascading failures
- */
-export class CircuitBreaker {
-  private failureCount = 0;
-  private lastFailureTime = 0;
-  private state: 'closed' | 'open' | 'half-open' = 'closed';
-
-  constructor(
-    private options: {
-      failureThreshold: number;
-      resetTimeout: number;
-      onStateChange?: (state: 'closed' | 'open' | 'half-open') => void;
-    }
-  ) {}
-
-  async execute<T>(fn: () => Promise<T>): Promise<T> {
-    if (this.state === 'open') {
-      if (Date.now() - this.lastFailureTime > this.options.resetTimeout) {
-        this.setState('half-open');
-      } else {
-        throw new Error('Circuit breaker is open');
-      }
-    }
-
-    try {
-      const result = await fn();
-      this.onSuccess();
-      return result;
-    } catch (error) {
-      this.onFailure();
-      throw error;
-    }
-  }
-
-  private onSuccess(): void {
-    this.failureCount = 0;
-    if (this.state !== 'closed') {
-      this.setState('closed');
-    }
-  }
-
-  private onFailure(): void {
-    this.failureCount++;
-    this.lastFailureTime = Date.now();
-    
-    if (this.failureCount >= this.options.failureThreshold) {
-      this.setState('open');
-    }
-  }
-
-  private setState(state: 'closed' | 'open' | 'half-open'): void {
-    if (this.state !== state) {
-      this.state = state;
-      if (this.options.onStateChange) {
-        this.options.onStateChange(state);
-      }
-    }
-  }
-
-  isOpen(): boolean {
-    return this.state === 'open';
-  }
-
-  getState(): 'closed' | 'open' | 'half-open' {
-    return this.state;
-  }
-
-  recordSuccess(): void {
-    this.onSuccess();
-  }
-
-  recordFailure(): void {
-    this.onFailure();
-  }
-}

ts/core/utils/binary-heap.ts

@@ -1,225 +0,0 @@
-/**
- * A binary heap implementation for efficient priority queue operations
- * Supports O(log n) insert and extract operations
- */
-export class BinaryHeap<T> {
-  private heap: T[] = [];
-  private keyMap?: Map<string, number>; // For efficient key-based lookups
-
-  constructor(
-    private compareFn: (a: T, b: T) => number,
-    private extractKey?: (item: T) => string
-  ) {
-    if (extractKey) {
-      this.keyMap = new Map();
-    }
-  }
-
-  /**
-   * Get the current size of the heap
-   */
-  public get size(): number {
-    return this.heap.length;
-  }
-
-  /**
-   * Check if the heap is empty
-   */
-  public isEmpty(): boolean {
-    return this.heap.length === 0;
-  }
-
-  /**
-   * Peek at the top element without removing it
-   */
-  public peek(): T | undefined {
-    return this.heap[0];
-  }
-
-  /**
-   * Insert a new item into the heap
-   * O(log n) time complexity
-   */
-  public insert(item: T): void {
-    const index = this.heap.length;
-    this.heap.push(item);
-    
-    if (this.keyMap && this.extractKey) {
-      const key = this.extractKey(item);
-      this.keyMap.set(key, index);
-    }
-    
-    this.bubbleUp(index);
-  }
-
-  /**
-   * Extract the top element from the heap
-   * O(log n) time complexity
-   */
-  public extract(): T | undefined {
-    if (this.heap.length === 0) return undefined;
-    if (this.heap.length === 1) {
-      const item = this.heap.pop()!;
-      if (this.keyMap && this.extractKey) {
-        this.keyMap.delete(this.extractKey(item));
-      }
-      return item;
-    }
-    
-    const result = this.heap[0];
-    const lastItem = this.heap.pop()!;
-    this.heap[0] = lastItem;
-    
-    if (this.keyMap && this.extractKey) {
-      this.keyMap.delete(this.extractKey(result));
-      this.keyMap.set(this.extractKey(lastItem), 0);
-    }
-    
-    this.bubbleDown(0);
-    return result;
-  }
-
-  /**
-   * Extract an element that matches the predicate
-   * O(n) time complexity for search, O(log n) for extraction
-   */
-  public extractIf(predicate: (item: T) => boolean): T | undefined {
-    const index = this.heap.findIndex(predicate);
-    if (index === -1) return undefined;
-    
-    return this.extractAt(index);
-  }
-
-  /**
-   * Extract an element by its key (if extractKey was provided)
-   * O(log n) time complexity
-   */
-  public extractByKey(key: string): T | undefined {
-    if (!this.keyMap || !this.extractKey) {
-      throw new Error('extractKey function must be provided to use key-based extraction');
-    }
-    
-    const index = this.keyMap.get(key);
-    if (index === undefined) return undefined;
-    
-    return this.extractAt(index);
-  }
-
-  /**
-   * Check if a key exists in the heap
-   * O(1) time complexity
-   */
-  public hasKey(key: string): boolean {
-    if (!this.keyMap) return false;
-    return this.keyMap.has(key);
-  }
-
-  /**
-   * Get all elements as an array (does not modify heap)
-   * O(n) time complexity
-   */
-  public toArray(): T[] {
-    return [...this.heap];
-  }
-
-  /**
-   * Clear the heap
-   */
-  public clear(): void {
-    this.heap = [];
-    if (this.keyMap) {
-      this.keyMap.clear();
-    }
-  }
-
-  /**
-   * Extract element at specific index
-   */
-  private extractAt(index: number): T {
-    const item = this.heap[index];
-    
-    if (this.keyMap && this.extractKey) {
-      this.keyMap.delete(this.extractKey(item));
-    }
-    
-    if (index === this.heap.length - 1) {
-      this.heap.pop();
-      return item;
-    }
-    
-    const lastItem = this.heap.pop()!;
-    this.heap[index] = lastItem;
-    
-    if (this.keyMap && this.extractKey) {
-      this.keyMap.set(this.extractKey(lastItem), index);
-    }
-    
-    // Try bubbling up first
-    const parentIndex = Math.floor((index - 1) / 2);
-    if (parentIndex >= 0 && this.compareFn(this.heap[index], this.heap[parentIndex]) < 0) {
-      this.bubbleUp(index);
-    } else {
-      this.bubbleDown(index);
-    }
-    
-    return item;
-  }
-
-  /**
-   * Bubble up element at given index to maintain heap property
-   */
-  private bubbleUp(index: number): void {
-    while (index > 0) {
-      const parentIndex = Math.floor((index - 1) / 2);
-      
-      if (this.compareFn(this.heap[index], this.heap[parentIndex]) >= 0) {
-        break;
-      }
-      
-      this.swap(index, parentIndex);
-      index = parentIndex;
-    }
-  }
-
-  /**
-   * Bubble down element at given index to maintain heap property
-   */
-  private bubbleDown(index: number): void {
-    const length = this.heap.length;
-    
-    while (true) {
-      const leftChild = 2 * index + 1;
-      const rightChild = 2 * index + 2;
-      let smallest = index;
-      
-      if (leftChild < length && 
-          this.compareFn(this.heap[leftChild], this.heap[smallest]) < 0) {
-        smallest = leftChild;
-      }
-      
-      if (rightChild < length && 
-          this.compareFn(this.heap[rightChild], this.heap[smallest]) < 0) {
-        smallest = rightChild;
-      }
-      
-      if (smallest === index) break;
-      
-      this.swap(index, smallest);
-      index = smallest;
-    }
-  }
-
-  /**
-   * Swap two elements in the heap
-   */
-  private swap(i: number, j: number): void {
-    const temp = this.heap[i];
-    this.heap[i] = this.heap[j];
-    this.heap[j] = temp;
-    
-    if (this.keyMap && this.extractKey) {
-      this.keyMap.set(this.extractKey(this.heap[i]), i);
-      this.keyMap.set(this.extractKey(this.heap[j]), j);
-    }
-  }
-}

ts/core/utils/enhanced-connection-pool.ts

@@ -1,425 +0,0 @@
-import { LifecycleComponent } from './lifecycle-component.js';
-import { BinaryHeap } from './binary-heap.js';
-import { AsyncMutex } from './async-utils.js';
-import { EventEmitter } from 'node:events';
-
-/**
- * Interface for pooled connection
- */
-export interface IPooledConnection<T> {
-  id: string;
-  connection: T;
-  createdAt: number;
-  lastUsedAt: number;
-  useCount: number;
-  inUse: boolean;
-  metadata?: any;
-}
-
-/**
- * Configuration options for the connection pool
- */
-export interface IConnectionPoolOptions<T> {
-  minSize?: number;
-  maxSize?: number;
-  acquireTimeout?: number;
-  idleTimeout?: number;
-  maxUseCount?: number;
-  validateOnAcquire?: boolean;
-  validateOnReturn?: boolean;
-  queueTimeout?: number;
-  connectionFactory: () => Promise<T>;
-  connectionValidator?: (connection: T) => Promise<boolean>;
-  connectionDestroyer?: (connection: T) => Promise<void>;
-  onConnectionError?: (error: Error, connection?: T) => void;
-}
-
-/**
- * Interface for queued acquire request
- */
-interface IAcquireRequest<T> {
-  id: string;
-  priority: number;
-  timestamp: number;
-  resolve: (connection: IPooledConnection<T>) => void;
-  reject: (error: Error) => void;
-  timeoutHandle?: NodeJS.Timeout;
-}
-
-/**
- * Enhanced connection pool with priority queue, backpressure, and lifecycle management
- */
-export class EnhancedConnectionPool<T> extends LifecycleComponent {
-  private readonly options: Required<Omit<IConnectionPoolOptions<T>, 'connectionValidator' | 'connectionDestroyer' | 'onConnectionError'>> & Pick<IConnectionPoolOptions<T>, 'connectionValidator' | 'connectionDestroyer' | 'onConnectionError'>;
-  private readonly availableConnections: IPooledConnection<T>[] = [];
-  private readonly activeConnections: Map<string, IPooledConnection<T>> = new Map();
-  private readonly waitQueue: BinaryHeap<IAcquireRequest<T>>;
-  private readonly mutex = new AsyncMutex();
-  private readonly eventEmitter = new EventEmitter();
-  
-  private connectionIdCounter = 0;
-  private requestIdCounter = 0;
-  private isClosing = false;
-  
-  // Metrics
-  private metrics = {
-    connectionsCreated: 0,
-    connectionsDestroyed: 0,
-    connectionsAcquired: 0,
-    connectionsReleased: 0,
-    acquireTimeouts: 0,
-    validationFailures: 0,
-    queueHighWaterMark: 0,
-  };
-
-  constructor(options: IConnectionPoolOptions<T>) {
-    super();
-    
-    this.options = {
-      minSize: 0,
-      maxSize: 10,
-      acquireTimeout: 30000,
-      idleTimeout: 300000, // 5 minutes
-      maxUseCount: Infinity,
-      validateOnAcquire: true,
-      validateOnReturn: false,
-      queueTimeout: 60000,
-      ...options,
-    };
-    
-    // Initialize priority queue (higher priority = extracted first)
-    this.waitQueue = new BinaryHeap<IAcquireRequest<T>>(
-      (a, b) => b.priority - a.priority || a.timestamp - b.timestamp,
-      (item) => item.id
-    );
-    
-    // Start maintenance cycle
-    this.startMaintenance();
-    
-    // Initialize minimum connections
-    this.initializeMinConnections();
-  }
-
-  /**
-   * Initialize minimum number of connections
-   */
-  private async initializeMinConnections(): Promise<void> {
-    const promises: Promise<void>[] = [];
-    
-    for (let i = 0; i < this.options.minSize; i++) {
-      promises.push(
-        this.createConnection()
-          .then(conn => {
-            this.availableConnections.push(conn);
-          })
-          .catch(err => {
-            if (this.options.onConnectionError) {
-              this.options.onConnectionError(err);
-            }
-          })
-      );
-    }
-    
-    await Promise.all(promises);
-  }
-
-  /**
-   * Start maintenance timer for idle connection cleanup
-   */
-  private startMaintenance(): void {
-    this.setInterval(() => {
-      this.performMaintenance();
-    }, 30000); // Every 30 seconds
-  }
-
-  /**
-   * Perform maintenance tasks
-   */
-  private async performMaintenance(): Promise<void> {
-    await this.mutex.runExclusive(async () => {
-      const now = Date.now();
-      const toRemove: IPooledConnection<T>[] = [];
-      
-      // Check for idle connections beyond minimum size
-      for (let i = this.availableConnections.length - 1; i >= 0; i--) {
-        const conn = this.availableConnections[i];
-        
-        // Keep minimum connections
-        if (this.availableConnections.length <= this.options.minSize) {
-          break;
-        }
-        
-        // Remove idle connections
-        if (now - conn.lastUsedAt > this.options.idleTimeout) {
-          toRemove.push(conn);
-          this.availableConnections.splice(i, 1);
-        }
-      }
-      
-      // Destroy idle connections
-      for (const conn of toRemove) {
-        await this.destroyConnection(conn);
-      }
-    });
-  }
-
-  /**
-   * Acquire a connection from the pool
-   */
-  public async acquire(priority: number = 0, timeout?: number): Promise<IPooledConnection<T>> {
-    if (this.isClosing) {
-      throw new Error('Connection pool is closing');
-    }
-    
-    return this.mutex.runExclusive(async () => {
-      // Try to get an available connection
-      const connection = await this.tryAcquireConnection();
-      if (connection) {
-        return connection;
-      }
-      
-      // Check if we can create a new connection
-      const totalConnections = this.availableConnections.length + this.activeConnections.size;
-      if (totalConnections < this.options.maxSize) {
-        try {
-          const newConnection = await this.createConnection();
-          return this.checkoutConnection(newConnection);
-        } catch (err) {
-          // Fall through to queue if creation fails
-        }
-      }
-      
-      // Add to wait queue
-      return this.queueAcquireRequest(priority, timeout);
-    });
-  }
-
-  /**
-   * Try to acquire an available connection
-   */
-  private async tryAcquireConnection(): Promise<IPooledConnection<T> | null> {
-    while (this.availableConnections.length > 0) {
-      const connection = this.availableConnections.shift()!;
-      
-      // Check if connection exceeded max use count
-      if (connection.useCount >= this.options.maxUseCount) {
-        await this.destroyConnection(connection);
-        continue;
-      }
-      
-      // Validate connection if required
-      if (this.options.validateOnAcquire && this.options.connectionValidator) {
-        try {
-          const isValid = await this.options.connectionValidator(connection.connection);
-          if (!isValid) {
-            this.metrics.validationFailures++;
-            await this.destroyConnection(connection);
-            continue;
-          }
-        } catch (err) {
-          this.metrics.validationFailures++;
-          await this.destroyConnection(connection);
-          continue;
-        }
-      }
-      
-      return this.checkoutConnection(connection);
-    }
-    
-    return null;
-  }
-
-  /**
-   * Checkout a connection for use
-   */
-  private checkoutConnection(connection: IPooledConnection<T>): IPooledConnection<T> {
-    connection.inUse = true;
-    connection.lastUsedAt = Date.now();
-    connection.useCount++;
-    
-    this.activeConnections.set(connection.id, connection);
-    this.metrics.connectionsAcquired++;
-    
-    this.eventEmitter.emit('acquire', connection);
-    return connection;
-  }
-
-  /**
-   * Queue an acquire request
-   */
-  private queueAcquireRequest(priority: number, timeout?: number): Promise<IPooledConnection<T>> {
-    return new Promise<IPooledConnection<T>>((resolve, reject) => {
-      const request: IAcquireRequest<T> = {
-        id: `req-${this.requestIdCounter++}`,
-        priority,
-        timestamp: Date.now(),
-        resolve,
-        reject,
-      };
-      
-      // Set timeout
-      const timeoutMs = timeout || this.options.queueTimeout;
-      request.timeoutHandle = this.setTimeout(() => {
-        if (this.waitQueue.extractByKey(request.id)) {
-          this.metrics.acquireTimeouts++;
-          reject(new Error(`Connection acquire timeout after ${timeoutMs}ms`));
-        }
-      }, timeoutMs);
-      
-      this.waitQueue.insert(request);
-      this.metrics.queueHighWaterMark = Math.max(
-        this.metrics.queueHighWaterMark, 
-        this.waitQueue.size
-      );
-      
-      this.eventEmitter.emit('enqueue', { queueSize: this.waitQueue.size });
-    });
-  }
-
-  /**
-   * Release a connection back to the pool
-   */
-  public async release(connection: IPooledConnection<T>): Promise<void> {
-    return this.mutex.runExclusive(async () => {
-      if (!connection.inUse || !this.activeConnections.has(connection.id)) {
-        throw new Error('Connection is not active');
-      }
-      
-      this.activeConnections.delete(connection.id);
-      connection.inUse = false;
-      connection.lastUsedAt = Date.now();
-      this.metrics.connectionsReleased++;
-      
-      // Check if connection should be destroyed
-      if (connection.useCount >= this.options.maxUseCount) {
-        await this.destroyConnection(connection);
-        return;
-      }
-      
-      // Validate on return if required
-      if (this.options.validateOnReturn && this.options.connectionValidator) {
-        try {
-          const isValid = await this.options.connectionValidator(connection.connection);
-          if (!isValid) {
-            await this.destroyConnection(connection);
-            return;
-          }
-        } catch (err) {
-          await this.destroyConnection(connection);
-          return;
-        }
-      }
-      
-      // Check if there are waiting requests
-      const request = this.waitQueue.extract();
-      if (request) {
-        this.clearTimeout(request.timeoutHandle!);
-        request.resolve(this.checkoutConnection(connection));
-        this.eventEmitter.emit('dequeue', { queueSize: this.waitQueue.size });
-      } else {
-        // Return to available pool
-        this.availableConnections.push(connection);
-        this.eventEmitter.emit('release', connection);
-      }
-    });
-  }
-
-  /**
-   * Create a new connection
-   */
-  private async createConnection(): Promise<IPooledConnection<T>> {
-    const rawConnection = await this.options.connectionFactory();
-    
-    const connection: IPooledConnection<T> = {
-      id: `conn-${this.connectionIdCounter++}`,
-      connection: rawConnection,
-      createdAt: Date.now(),
-      lastUsedAt: Date.now(),
-      useCount: 0,
-      inUse: false,
-    };
-    
-    this.metrics.connectionsCreated++;
-    this.eventEmitter.emit('create', connection);
-    
-    return connection;
-  }
-
-  /**
-   * Destroy a connection
-   */
-  private async destroyConnection(connection: IPooledConnection<T>): Promise<void> {
-    try {
-      if (this.options.connectionDestroyer) {
-        await this.options.connectionDestroyer(connection.connection);
-      }
-      
-      this.metrics.connectionsDestroyed++;
-      this.eventEmitter.emit('destroy', connection);
-    } catch (err) {
-      if (this.options.onConnectionError) {
-        this.options.onConnectionError(err as Error, connection.connection);
-      }
-    }
-  }
-
-  /**
-   * Get current pool statistics
-   */
-  public getStats() {
-    return {
-      available: this.availableConnections.length,
-      active: this.activeConnections.size,
-      waiting: this.waitQueue.size,
-      total: this.availableConnections.length + this.activeConnections.size,
-      ...this.metrics,
-    };
-  }
-
-  /**
-   * Subscribe to pool events
-   */
-  public on(event: string, listener: Function): void {
-    this.addEventListener(this.eventEmitter, event, listener);
-  }
-
-  /**
-   * Close the pool and cleanup resources
-   */
-  protected async onCleanup(): Promise<void> {
-    this.isClosing = true;
-    
-    // Clear the wait queue
-    while (!this.waitQueue.isEmpty()) {
-      const request = this.waitQueue.extract();
-      if (request) {
-        this.clearTimeout(request.timeoutHandle!);
-        request.reject(new Error('Connection pool is closing'));
-      }
-    }
-    
-    // Wait for active connections to be released (with timeout)
-    const timeout = 30000;
-    const startTime = Date.now();
-    
-    while (this.activeConnections.size > 0 && Date.now() - startTime < timeout) {
-      await new Promise(resolve => {
-        const timer = setTimeout(resolve, 100);
-        if (typeof timer.unref === 'function') {
-          timer.unref();
-        }
-      });
-    }
-    
-    // Destroy all connections
-    const allConnections = [
-      ...this.availableConnections,
-      ...this.activeConnections.values(),
-    ];
-    
-    await Promise.all(allConnections.map(conn => this.destroyConnection(conn)));
-    
-    this.availableConnections.length = 0;
-    this.activeConnections.clear();
-  }
-}

ts/core/utils/fs-utils.ts

@@ -1,270 +0,0 @@
-/**
- * Async filesystem utilities for SmartProxy
- * Provides non-blocking alternatives to synchronous filesystem operations
- */
-
-import * as plugins from '../../plugins.js';
-
-export class AsyncFileSystem {
-  /**
-   * Check if a file or directory exists
-   * @param path - Path to check
-   * @returns Promise resolving to true if exists, false otherwise
-   */
-  static async exists(path: string): Promise<boolean> {
-    try {
-      await plugins.fs.promises.access(path);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Ensure a directory exists, creating it if necessary
-   * @param dirPath - Directory path to ensure
-   * @returns Promise that resolves when directory is ensured
-   */
-  static async ensureDir(dirPath: string): Promise<void> {
-    await plugins.fs.promises.mkdir(dirPath, { recursive: true });
-  }
-
-  /**
-   * Read a file as string
-   * @param filePath - Path to the file
-   * @param encoding - File encoding (default: utf8)
-   * @returns Promise resolving to file contents
-   */
-  static async readFile(filePath: string, encoding: BufferEncoding = 'utf8'): Promise<string> {
-    return plugins.fs.promises.readFile(filePath, encoding);
-  }
-
-  /**
-   * Read a file as buffer
-   * @param filePath - Path to the file
-   * @returns Promise resolving to file buffer
-   */
-  static async readFileBuffer(filePath: string): Promise<Buffer> {
-    return plugins.fs.promises.readFile(filePath);
-  }
-
-  /**
-   * Write string data to a file
-   * @param filePath - Path to the file
-   * @param data - String data to write
-   * @param encoding - File encoding (default: utf8)
-   * @returns Promise that resolves when file is written
-   */
-  static async writeFile(filePath: string, data: string, encoding: BufferEncoding = 'utf8'): Promise<void> {
-    // Ensure directory exists
-    const dir = plugins.path.dirname(filePath);
-    await this.ensureDir(dir);
-    await plugins.fs.promises.writeFile(filePath, data, encoding);
-  }
-
-  /**
-   * Write buffer data to a file
-   * @param filePath - Path to the file
-   * @param data - Buffer data to write
-   * @returns Promise that resolves when file is written
-   */
-  static async writeFileBuffer(filePath: string, data: Buffer): Promise<void> {
-    const dir = plugins.path.dirname(filePath);
-    await this.ensureDir(dir);
-    await plugins.fs.promises.writeFile(filePath, data);
-  }
-
-  /**
-   * Remove a file
-   * @param filePath - Path to the file
-   * @returns Promise that resolves when file is removed
-   */
-  static async remove(filePath: string): Promise<void> {
-    try {
-      await plugins.fs.promises.unlink(filePath);
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
-      // File doesn't exist, which is fine
-    }
-  }
-
-  /**
-   * Remove a directory and all its contents
-   * @param dirPath - Path to the directory
-   * @returns Promise that resolves when directory is removed
-   */
-  static async removeDir(dirPath: string): Promise<void> {
-    try {
-      await plugins.fs.promises.rm(dirPath, { recursive: true, force: true });
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
-    }
-  }
-
-  /**
-   * Read JSON from a file
-   * @param filePath - Path to the JSON file
-   * @returns Promise resolving to parsed JSON
-   */
-  static async readJSON<T = any>(filePath: string): Promise<T> {
-    const content = await this.readFile(filePath);
-    return JSON.parse(content);
-  }
-
-  /**
-   * Write JSON to a file
-   * @param filePath - Path to the file
-   * @param data - Data to write as JSON
-   * @param pretty - Whether to pretty-print JSON (default: true)
-   * @returns Promise that resolves when file is written
-   */
-  static async writeJSON(filePath: string, data: any, pretty = true): Promise<void> {
-    const jsonString = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
-    await this.writeFile(filePath, jsonString);
-  }
-
-  /**
-   * Copy a file from source to destination
-   * @param source - Source file path
-   * @param destination - Destination file path
-   * @returns Promise that resolves when file is copied
-   */
-  static async copyFile(source: string, destination: string): Promise<void> {
-    const destDir = plugins.path.dirname(destination);
-    await this.ensureDir(destDir);
-    await plugins.fs.promises.copyFile(source, destination);
-  }
-
-  /**
-   * Move/rename a file
-   * @param source - Source file path
-   * @param destination - Destination file path
-   * @returns Promise that resolves when file is moved
-   */
-  static async moveFile(source: string, destination: string): Promise<void> {
-    const destDir = plugins.path.dirname(destination);
-    await this.ensureDir(destDir);
-    await plugins.fs.promises.rename(source, destination);
-  }
-
-  /**
-   * Get file stats
-   * @param filePath - Path to the file
-   * @returns Promise resolving to file stats or null if doesn't exist
-   */
-  static async getStats(filePath: string): Promise<plugins.fs.Stats | null> {
-    try {
-      return await plugins.fs.promises.stat(filePath);
-    } catch (error: any) {
-      if (error.code === 'ENOENT') {
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * List files in a directory
-   * @param dirPath - Directory path
-   * @returns Promise resolving to array of filenames
-   */
-  static async listFiles(dirPath: string): Promise<string[]> {
-    try {
-      return await plugins.fs.promises.readdir(dirPath);
-    } catch (error: any) {
-      if (error.code === 'ENOENT') {
-        return [];
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * List files in a directory with full paths
-   * @param dirPath - Directory path
-   * @returns Promise resolving to array of full file paths
-   */
-  static async listFilesFullPath(dirPath: string): Promise<string[]> {
-    const files = await this.listFiles(dirPath);
-    return files.map(file => plugins.path.join(dirPath, file));
-  }
-
-  /**
-   * Recursively list all files in a directory
-   * @param dirPath - Directory path
-   * @param fileList - Accumulator for file list (used internally)
-   * @returns Promise resolving to array of all file paths
-   */
-  static async listFilesRecursive(dirPath: string, fileList: string[] = []): Promise<string[]> {
-    const files = await this.listFiles(dirPath);
-    
-    for (const file of files) {
-      const filePath = plugins.path.join(dirPath, file);
-      const stats = await this.getStats(filePath);
-      
-      if (stats?.isDirectory()) {
-        await this.listFilesRecursive(filePath, fileList);
-      } else if (stats?.isFile()) {
-        fileList.push(filePath);
-      }
-    }
-    
-    return fileList;
-  }
-
-  /**
-   * Create a read stream for a file
-   * @param filePath - Path to the file
-   * @param options - Stream options
-   * @returns Read stream
-   */
-  static createReadStream(filePath: string, options?: Parameters<typeof plugins.fs.createReadStream>[1]): plugins.fs.ReadStream {
-    return plugins.fs.createReadStream(filePath, options);
-  }
-
-  /**
-   * Create a write stream for a file
-   * @param filePath - Path to the file
-   * @param options - Stream options
-   * @returns Write stream
-   */
-  static createWriteStream(filePath: string, options?: Parameters<typeof plugins.fs.createWriteStream>[1]): plugins.fs.WriteStream {
-    return plugins.fs.createWriteStream(filePath, options);
-  }
-
-  /**
-   * Ensure a file exists, creating an empty file if necessary
-   * @param filePath - Path to the file
-   * @returns Promise that resolves when file is ensured
-   */
-  static async ensureFile(filePath: string): Promise<void> {
-    const exists = await this.exists(filePath);
-    if (!exists) {
-      await this.writeFile(filePath, '');
-    }
-  }
-
-  /**
-   * Check if a path is a directory
-   * @param path - Path to check
-   * @returns Promise resolving to true if directory, false otherwise
-   */
-  static async isDirectory(path: string): Promise<boolean> {
-    const stats = await this.getStats(path);
-    return stats?.isDirectory() ?? false;
-  }
-
-  /**
-   * Check if a path is a file
-   * @param path - Path to check
-   * @returns Promise resolving to true if file, false otherwise
-   */
-  static async isFile(path: string): Promise<boolean> {
-    const stats = await this.getStats(path);
-    return stats?.isFile() ?? false;
-  }
-}

ts/core/utils/index.ts

@@ -2,17 +2,4 @@
  * Core utility functions
  */
 
-export * from './validation-utils.js';
-export * from './ip-utils.js';
-export * from './template-utils.js';
-export * from './security-utils.js';
-export * from './shared-security-manager.js';
-export * from './websocket-utils.js';
 export * from './logger.js';
-export * from './async-utils.js';
-export * from './fs-utils.js';
-export * from './lifecycle-component.js';
-export * from './binary-heap.js';
-export * from './enhanced-connection-pool.js';
-export * from './socket-utils.js';
-export * from './proxy-protocol.js';

ts/core/utils/ip-utils.ts

@@ -1,303 +0,0 @@
-import * as plugins from '../../plugins.js';
-
-/**
- * Utility class for IP address operations
- */
-export class IpUtils {
-  /**
-   * Check if the IP matches any of the glob patterns
-   *
-   * This method checks IP addresses against glob patterns and handles IPv4/IPv6 normalization.
-   * It's used to implement IP filtering based on security configurations.
-   *
-   * @param ip - The IP address to check
-   * @param patterns - Array of glob patterns
-   * @returns true if IP matches any pattern, false otherwise
-   */
-  public static isGlobIPMatch(ip: string, patterns: string[]): boolean {
-    if (!ip || !patterns || patterns.length === 0) return false;
-
-    // Normalize the IP being checked
-    const normalizedIPVariants = this.normalizeIP(ip);
-    if (normalizedIPVariants.length === 0) return false;
-
-    // Check each pattern
-    for (const pattern of patterns) {
-      // Handle CIDR notation
-      if (pattern.includes('/')) {
-        if (this.matchCIDR(ip, pattern)) {
-          return true;
-        }
-        continue;
-      }
-
-      // Handle range notation
-      if (pattern.includes('-') && !pattern.includes('*')) {
-        if (this.matchIPRange(ip, pattern)) {
-          return true;
-        }
-        continue;
-      }
-
-      // Expand shorthand patterns for glob matching
-      let expandedPattern = pattern;
-      if (pattern.includes('*') && !pattern.includes(':')) {
-        const parts = pattern.split('.');
-        while (parts.length < 4) {
-          parts.push('*');
-        }
-        expandedPattern = parts.join('.');
-      }
-
-      // Normalize and check with minimatch
-      const normalizedPatterns = this.normalizeIP(expandedPattern);
-      
-      for (const ipVariant of normalizedIPVariants) {
-        for (const normalizedPattern of normalizedPatterns) {
-          if (plugins.minimatch(ipVariant, normalizedPattern)) {
-            return true;
-          }
-        }
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Normalize IP addresses for consistent comparison
-   * 
-   * @param ip The IP address to normalize
-   * @returns Array of normalized IP forms
-   */
-  public static normalizeIP(ip: string): string[] {
-    if (!ip) return [];
-    
-    // Handle IPv4-mapped IPv6 addresses (::ffff:127.0.0.1)
-    if (ip.startsWith('::ffff:')) {
-      const ipv4 = ip.slice(7);
-      return [ip, ipv4];
-    }
-    
-    // Handle IPv4 addresses by also checking IPv4-mapped form
-    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) {
-      return [ip, `::ffff:${ip}`];
-    }
-    
-    return [ip];
-  }
-
-  /**
-   * Check if an IP is authorized using security rules
-   *
-   * @param ip - The IP address to check
-   * @param allowedIPs - Array of allowed IP patterns
-   * @param blockedIPs - Array of blocked IP patterns
-   * @returns true if IP is authorized, false if blocked
-   */
-  public static isIPAuthorized(ip: string, allowedIPs: string[] = [], blockedIPs: string[] = []): boolean {
-    // Skip IP validation if no rules are defined
-    if (!ip || (allowedIPs.length === 0 && blockedIPs.length === 0)) {
-      return true;
-    }
-
-    // First check if IP is blocked - blocked IPs take precedence
-    if (blockedIPs.length > 0 && this.isGlobIPMatch(ip, blockedIPs)) {
-      return false;
-    }
-
-    // Then check if IP is allowed (if no allowed IPs are specified, all non-blocked IPs are allowed)
-    return allowedIPs.length === 0 || this.isGlobIPMatch(ip, allowedIPs);
-  }
-
-  /**
-   * Check if an IP address is a private network address
-   * 
-   * @param ip The IP address to check
-   * @returns true if the IP is a private network address, false otherwise
-   */
-  public static isPrivateIP(ip: string): boolean {
-    if (!ip) return false;
-
-    // Handle IPv4-mapped IPv6 addresses
-    if (ip.startsWith('::ffff:')) {
-      ip = ip.slice(7);
-    }
-
-    // Check IPv4 private ranges
-    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) {
-      const parts = ip.split('.').map(Number);
-      
-      // Check common private ranges
-      // 10.0.0.0/8
-      if (parts[0] === 10) return true;
-      
-      // 172.16.0.0/12
-      if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
-      
-      // 192.168.0.0/16
-      if (parts[0] === 192 && parts[1] === 168) return true;
-      
-      // 127.0.0.0/8 (localhost)
-      if (parts[0] === 127) return true;
-      
-      return false;
-    }
-    
-    // IPv6 local addresses
-    return ip === '::1' || ip.startsWith('fc00:') || ip.startsWith('fd00:') || ip.startsWith('fe80:');
-  }
-
-  /**
-   * Check if an IP address is a public network address
-   * 
-   * @param ip The IP address to check
-   * @returns true if the IP is a public network address, false otherwise
-   */
-  public static isPublicIP(ip: string): boolean {
-    return !this.isPrivateIP(ip);
-  }
-
-  /**
-   * Check if an IP matches a CIDR notation
-   * 
-   * @param ip The IP address to check
-   * @param cidr The CIDR notation (e.g., "192.168.1.0/24")
-   * @returns true if IP is within the CIDR range
-   */
-  private static matchCIDR(ip: string, cidr: string): boolean {
-    if (!cidr.includes('/')) return false;
-    
-    const [networkAddr, prefixStr] = cidr.split('/');
-    const prefix = parseInt(prefixStr, 10);
-    
-    // Handle IPv4-mapped IPv6 in the IP being checked
-    let checkIP = ip;
-    if (checkIP.startsWith('::ffff:')) {
-      checkIP = checkIP.slice(7);
-    }
-    
-    // Handle IPv6 CIDR
-    if (networkAddr.includes(':')) {
-      // TODO: Implement IPv6 CIDR matching
-      return false;
-    }
-    
-    // IPv4 CIDR matching
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(checkIP)) return false;
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(networkAddr)) return false;
-    if (isNaN(prefix) || prefix < 0 || prefix > 32) return false;
-    
-    const ipParts = checkIP.split('.').map(Number);
-    const netParts = networkAddr.split('.').map(Number);
-    
-    // Validate IP parts
-    for (const part of [...ipParts, ...netParts]) {
-      if (part < 0 || part > 255) return false;
-    }
-    
-    // Convert to 32-bit integers
-    const ipNum = (ipParts[0] << 24) | (ipParts[1] << 16) | (ipParts[2] << 8) | ipParts[3];
-    const netNum = (netParts[0] << 24) | (netParts[1] << 16) | (netParts[2] << 8) | netParts[3];
-    
-    // Create mask
-    const mask = (-1 << (32 - prefix)) >>> 0;
-    
-    // Check if IP is in network range
-    return (ipNum & mask) === (netNum & mask);
-  }
-
-  /**
-   * Check if an IP matches a range notation
-   * 
-   * @param ip The IP address to check
-   * @param range The range notation (e.g., "192.168.1.1-192.168.1.100")
-   * @returns true if IP is within the range
-   */
-  private static matchIPRange(ip: string, range: string): boolean {
-    if (!range.includes('-')) return false;
-    
-    const [startIP, endIP] = range.split('-').map(s => s.trim());
-    
-    // Handle IPv4-mapped IPv6 in the IP being checked
-    let checkIP = ip;
-    if (checkIP.startsWith('::ffff:')) {
-      checkIP = checkIP.slice(7);
-    }
-    
-    // Only handle IPv4 for now
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(checkIP)) return false;
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(startIP)) return false;
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(endIP)) return false;
-    
-    const ipParts = checkIP.split('.').map(Number);
-    const startParts = startIP.split('.').map(Number);
-    const endParts = endIP.split('.').map(Number);
-    
-    // Validate parts
-    for (const part of [...ipParts, ...startParts, ...endParts]) {
-      if (part < 0 || part > 255) return false;
-    }
-    
-    // Convert to 32-bit integers for comparison
-    const ipNum = (ipParts[0] << 24) | (ipParts[1] << 16) | (ipParts[2] << 8) | ipParts[3];
-    const startNum = (startParts[0] << 24) | (startParts[1] << 16) | (startParts[2] << 8) | startParts[3];
-    const endNum = (endParts[0] << 24) | (endParts[1] << 16) | (endParts[2] << 8) | endParts[3];
-    
-    // Convert to unsigned for proper comparison
-    const ipUnsigned = ipNum >>> 0;
-    const startUnsigned = startNum >>> 0;
-    const endUnsigned = endNum >>> 0;
-    
-    return ipUnsigned >= startUnsigned && ipUnsigned <= endUnsigned;
-  }
-
-  /**
-   * Convert a subnet CIDR to an IP range for filtering
-   * 
-   * @param cidr The CIDR notation (e.g., "192.168.1.0/24")
-   * @returns Array of glob patterns that match the CIDR range
-   */
-  public static cidrToGlobPatterns(cidr: string): string[] {
-    if (!cidr || !cidr.includes('/')) return [];
-    
-    const [ipPart, prefixPart] = cidr.split('/');
-    const prefix = parseInt(prefixPart, 10);
-    
-    if (isNaN(prefix) || prefix < 0 || prefix > 32) return [];
-    
-    // For IPv4 only for now
-    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(ipPart)) return [];
-    
-    const ipParts = ipPart.split('.').map(Number);
-    const fullMask = Math.pow(2, 32 - prefix) - 1;
-    
-    // Convert IP to a numeric value
-    const ipNum = (ipParts[0] << 24) | (ipParts[1] << 16) | (ipParts[2] << 8) | ipParts[3];
-    
-    // Calculate network address (IP & ~fullMask)
-    const networkNum = ipNum & ~fullMask;
-    
-    // For large ranges, return wildcard patterns
-    if (prefix <= 8) {
-      return [`${(networkNum >>> 24) & 255}.*.*.*`];
-    } else if (prefix <= 16) {
-      return [`${(networkNum >>> 24) & 255}.${(networkNum >>> 16) & 255}.*.*`];
-    } else if (prefix <= 24) {
-      return [`${(networkNum >>> 24) & 255}.${(networkNum >>> 16) & 255}.${(networkNum >>> 8) & 255}.*`];
-    }
-    
-    // For small ranges, create individual IP patterns
-    const patterns = [];
-    const maxAddresses = Math.min(256, Math.pow(2, 32 - prefix));
-    
-    for (let i = 0; i < maxAddresses; i++) {
-      const currentIpNum = networkNum + i;
-      patterns.push(
-        `${(currentIpNum >>> 24) & 255}.${(currentIpNum >>> 16) & 255}.${(currentIpNum >>> 8) & 255}.${currentIpNum & 255}`
-      );
-    }
-    
-    return patterns;
-  }
-}

ts/core/utils/lifecycle-component.ts

@@ -1,251 +0,0 @@
-/**
- * Base class for components that need proper resource lifecycle management
- * Provides automatic cleanup of timers and event listeners to prevent memory leaks
- */
-export abstract class LifecycleComponent {
-  private timers: Set<NodeJS.Timeout> = new Set();
-  private intervals: Set<NodeJS.Timeout> = new Set();
-  private listeners: Array<{ 
-    target: any; 
-    event: string; 
-    handler: Function;
-    actualHandler?: Function; // The actual handler registered (may be wrapped)
-    once?: boolean;
-  }> = [];
-  private childComponents: Set<LifecycleComponent> = new Set();
-  protected isShuttingDown = false;
-  private cleanupPromise?: Promise<void>;
-
-  /**
-   * Create a managed setTimeout that will be automatically cleaned up
-   */
-  protected setTimeout(handler: Function, timeout: number): NodeJS.Timeout {
-    if (this.isShuttingDown) {
-      // Return a dummy timer if shutting down
-      const dummyTimer = setTimeout(() => {}, 0);
-      if (typeof dummyTimer.unref === 'function') {
-        dummyTimer.unref();
-      }
-      return dummyTimer;
-    }
-
-    const wrappedHandler = () => {
-      this.timers.delete(timer);
-      if (!this.isShuttingDown) {
-        handler();
-      }
-    };
-
-    const timer = setTimeout(wrappedHandler, timeout);
-    this.timers.add(timer);
-    
-    // Allow process to exit even with timer
-    if (typeof timer.unref === 'function') {
-      timer.unref();
-    }
-    
-    return timer;
-  }
-
-  /**
-   * Create a managed setInterval that will be automatically cleaned up
-   */
-  protected setInterval(handler: Function, interval: number): NodeJS.Timeout {
-    if (this.isShuttingDown) {
-      // Return a dummy timer if shutting down
-      const dummyTimer = setInterval(() => {}, interval);
-      if (typeof dummyTimer.unref === 'function') {
-        dummyTimer.unref();
-      }
-      clearInterval(dummyTimer); // Clear immediately since we don't need it
-      return dummyTimer;
-    }
-
-    const wrappedHandler = () => {
-      if (!this.isShuttingDown) {
-        handler();
-      }
-    };
-
-    const timer = setInterval(wrappedHandler, interval);
-    this.intervals.add(timer);
-    
-    // Allow process to exit even with timer
-    if (typeof timer.unref === 'function') {
-      timer.unref();
-    }
-    
-    return timer;
-  }
-
-  /**
-   * Clear a managed timeout
-   */
-  protected clearTimeout(timer: NodeJS.Timeout): void {
-    clearTimeout(timer);
-    this.timers.delete(timer);
-  }
-
-  /**
-   * Clear a managed interval
-   */
-  protected clearInterval(timer: NodeJS.Timeout): void {
-    clearInterval(timer);
-    this.intervals.delete(timer);
-  }
-
-  /**
-   * Add a managed event listener that will be automatically removed on cleanup
-   */
-  protected addEventListener(
-    target: any, 
-    event: string, 
-    handler: Function,
-    options?: { once?: boolean }
-  ): void {
-    if (this.isShuttingDown) {
-      return;
-    }
-
-    // For 'once' listeners, we need to wrap the handler to remove it from our tracking
-    let actualHandler = handler;
-    if (options?.once) {
-      actualHandler = (...args: any[]) => {
-        // Call the original handler
-        handler(...args);
-        
-        // Remove from our internal tracking
-        const index = this.listeners.findIndex(
-          l => l.target === target && l.event === event && l.handler === handler
-        );
-        if (index !== -1) {
-          this.listeners.splice(index, 1);
-        }
-      };
-    }
-
-    // Support both EventEmitter and DOM-style event targets
-    if (typeof target.on === 'function') {
-      if (options?.once) {
-        target.once(event, actualHandler);
-      } else {
-        target.on(event, actualHandler);
-      }
-    } else if (typeof target.addEventListener === 'function') {
-      target.addEventListener(event, actualHandler, options);
-    } else {
-      throw new Error('Target must support on() or addEventListener()');
-    }
-
-    // Store both the original handler and the actual handler registered
-    this.listeners.push({ 
-      target, 
-      event, 
-      handler,
-      actualHandler, // The handler that was actually registered (may be wrapped)
-      once: options?.once 
-    });
-  }
-
-  /**
-   * Remove a specific event listener
-   */
-  protected removeEventListener(target: any, event: string, handler: Function): void {
-    // Remove from target
-    if (typeof target.removeListener === 'function') {
-      target.removeListener(event, handler);
-    } else if (typeof target.removeEventListener === 'function') {
-      target.removeEventListener(event, handler);
-    }
-
-    // Remove from our tracking
-    const index = this.listeners.findIndex(
-      l => l.target === target && l.event === event && l.handler === handler
-    );
-    if (index !== -1) {
-      this.listeners.splice(index, 1);
-    }
-  }
-
-  /**
-   * Register a child component that should be cleaned up when this component is cleaned up
-   */
-  protected registerChildComponent(component: LifecycleComponent): void {
-    this.childComponents.add(component);
-  }
-
-  /**
-   * Unregister a child component
-   */
-  protected unregisterChildComponent(component: LifecycleComponent): void {
-    this.childComponents.delete(component);
-  }
-
-  /**
-   * Override this method to implement component-specific cleanup logic
-   */
-  protected async onCleanup(): Promise<void> {
-    // Override in subclasses
-  }
-
-  /**
-   * Clean up all managed resources
-   */
-  public async cleanup(): Promise<void> {
-    // Return existing cleanup promise if already cleaning up
-    if (this.cleanupPromise) {
-      return this.cleanupPromise;
-    }
-
-    this.cleanupPromise = this.performCleanup();
-    return this.cleanupPromise;
-  }
-
-  private async performCleanup(): Promise<void> {
-    this.isShuttingDown = true;
-    
-    // First, clean up child components
-    const childCleanupPromises: Promise<void>[] = [];
-    for (const child of this.childComponents) {
-      childCleanupPromises.push(child.cleanup());
-    }
-    await Promise.all(childCleanupPromises);
-    this.childComponents.clear();
-
-    // Clear all timers
-    for (const timer of this.timers) {
-      clearTimeout(timer);
-    }
-    this.timers.clear();
-
-    // Clear all intervals
-    for (const timer of this.intervals) {
-      clearInterval(timer);
-    }
-    this.intervals.clear();
-
-    // Remove all event listeners
-    for (const { target, event, handler, actualHandler } of this.listeners) {
-      // Use actualHandler if available (for wrapped handlers), otherwise use the original handler
-      const handlerToRemove = actualHandler || handler;
-      
-      // All listeners need to be removed, including 'once' listeners that might not have fired
-      if (typeof target.removeListener === 'function') {
-        target.removeListener(event, handlerToRemove);
-      } else if (typeof target.removeEventListener === 'function') {
-        target.removeEventListener(event, handlerToRemove);
-      }
-    }
-    this.listeners = [];
-
-    // Call subclass cleanup
-    await this.onCleanup();
-  }
-
-  /**
-   * Check if the component is shutting down
-   */
-  protected isShuttingDownState(): boolean {
-    return this.isShuttingDown;
-  }
-}

ts/core/utils/log-deduplicator.ts

@@ -1,370 +0,0 @@
-import { logger } from './logger.js';
-
-interface ILogEvent {
-  level: 'info' | 'warn' | 'error' | 'debug';
-  message: string;
-  data?: any;
-  count: number;
-  firstSeen: number;
-  lastSeen: number;
-}
-
-interface IAggregatedEvent {
-  key: string;
-  events: Map<string, ILogEvent>;
-  flushTimer?: NodeJS.Timeout;
-}
-
-/**
- * Log deduplication utility to reduce log spam for repetitive events
- */
-export class LogDeduplicator {
-  private globalFlushTimer?: NodeJS.Timeout;
-  private aggregatedEvents: Map<string, IAggregatedEvent> = new Map();
-  private flushInterval: number = 5000; // 5 seconds
-  private maxBatchSize: number = 100;
-  private rapidEventThreshold: number = 50; // Flush early if this many events in 1 second
-  private lastRapidCheck: number = Date.now();
-  
-  constructor(flushInterval?: number) {
-    if (flushInterval) {
-      this.flushInterval = flushInterval;
-    }
-    
-    // Set up global periodic flush to ensure logs are emitted regularly
-    this.globalFlushTimer = setInterval(() => {
-      this.flushAll();
-    }, this.flushInterval * 2); // Flush everything every 2x the normal interval
-    
-    if (this.globalFlushTimer.unref) {
-      this.globalFlushTimer.unref();
-    }
-  }
-  
-  /**
-   * Log a deduplicated event
-   * @param key - Aggregation key (e.g., 'connection-rejected', 'cleanup-batch')
-   * @param level - Log level
-   * @param message - Log message template
-   * @param data - Additional data
-   * @param dedupeKey - Deduplication key within the aggregation (e.g., IP address, reason)
-   */
-  public log(
-    key: string,
-    level: 'info' | 'warn' | 'error' | 'debug',
-    message: string,
-    data?: any,
-    dedupeKey?: string
-  ): void {
-    const eventKey = dedupeKey || message;
-    const now = Date.now();
-    
-    if (!this.aggregatedEvents.has(key)) {
-      this.aggregatedEvents.set(key, {
-        key,
-        events: new Map(),
-        flushTimer: undefined
-      });
-    }
-    
-    const aggregated = this.aggregatedEvents.get(key)!;
-    
-    if (aggregated.events.has(eventKey)) {
-      const event = aggregated.events.get(eventKey)!;
-      event.count++;
-      event.lastSeen = now;
-      if (data) {
-        event.data = { ...event.data, ...data };
-      }
-    } else {
-      aggregated.events.set(eventKey, {
-        level,
-        message,
-        data,
-        count: 1,
-        firstSeen: now,
-        lastSeen: now
-      });
-    }
-    
-    // Check for rapid events (many events in short time)
-    const totalEvents = Array.from(aggregated.events.values()).reduce((sum, e) => sum + e.count, 0);
-    
-    // If we're getting flooded with events, flush more frequently
-    if (now - this.lastRapidCheck < 1000 && totalEvents >= this.rapidEventThreshold) {
-      this.flush(key);
-      this.lastRapidCheck = now;
-    } else if (aggregated.events.size >= this.maxBatchSize) {
-      // Check if we should flush due to size
-      this.flush(key);
-    } else if (!aggregated.flushTimer) {
-      // Schedule flush
-      aggregated.flushTimer = setTimeout(() => {
-        this.flush(key);
-      }, this.flushInterval);
-      
-      if (aggregated.flushTimer.unref) {
-        aggregated.flushTimer.unref();
-      }
-    }
-    
-    // Update rapid check time
-    if (now - this.lastRapidCheck >= 1000) {
-      this.lastRapidCheck = now;
-    }
-  }
-  
-  /**
-   * Flush aggregated events for a specific key
-   */
-  public flush(key: string): void {
-    const aggregated = this.aggregatedEvents.get(key);
-    if (!aggregated || aggregated.events.size === 0) {
-      return;
-    }
-    
-    if (aggregated.flushTimer) {
-      clearTimeout(aggregated.flushTimer);
-      aggregated.flushTimer = undefined;
-    }
-    
-    // Emit aggregated log based on the key
-    switch (key) {
-      case 'connection-rejected':
-        this.flushConnectionRejections(aggregated);
-        break;
-      case 'connection-cleanup':
-        this.flushConnectionCleanups(aggregated);
-        break;
-      case 'connection-terminated':
-        this.flushConnectionTerminations(aggregated);
-        break;
-      case 'ip-rejected':
-        this.flushIPRejections(aggregated);
-        break;
-      default:
-        this.flushGeneric(aggregated);
-    }
-    
-    // Clear events
-    aggregated.events.clear();
-  }
-  
-  /**
-   * Flush all pending events
-   */
-  public flushAll(): void {
-    for (const key of this.aggregatedEvents.keys()) {
-      this.flush(key);
-    }
-  }
-  
-  private flushConnectionRejections(aggregated: IAggregatedEvent): void {
-    const totalCount = Array.from(aggregated.events.values()).reduce((sum, e) => sum + e.count, 0);
-    const byReason = new Map<string, number>();
-    
-    for (const [, event] of aggregated.events) {
-      const reason = event.data?.reason || 'unknown';
-      byReason.set(reason, (byReason.get(reason) || 0) + event.count);
-    }
-    
-    const reasonSummary = Array.from(byReason.entries())
-      .sort((a, b) => b[1] - a[1])
-      .map(([reason, count]) => `${reason}: ${count}`)
-      .join(', ');
-    
-    const duration = Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen));
-    logger.log('warn', `[SUMMARY] Rejected ${totalCount} connections in ${Math.round(duration/1000)}s`, {
-      reasons: reasonSummary,
-      uniqueIPs: aggregated.events.size,
-      component: 'connection-dedup'
-    });
-  }
-  
-  private flushConnectionCleanups(aggregated: IAggregatedEvent): void {
-    const totalCount = Array.from(aggregated.events.values()).reduce((sum, e) => sum + e.count, 0);
-    const byReason = new Map<string, number>();
-    
-    for (const [, event] of aggregated.events) {
-      const reason = event.data?.reason || 'normal';
-      byReason.set(reason, (byReason.get(reason) || 0) + event.count);
-    }
-    
-    const reasonSummary = Array.from(byReason.entries())
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, 5) // Top 5 reasons
-      .map(([reason, count]) => `${reason}: ${count}`)
-      .join(', ');
-    
-    logger.log('info', `Cleaned up ${totalCount} connections`, {
-      reasons: reasonSummary,
-      duration: Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen)),
-      component: 'connection-dedup'
-    });
-  }
-  
-  private flushConnectionTerminations(aggregated: IAggregatedEvent): void {
-    const totalCount = Array.from(aggregated.events.values()).reduce((sum, e) => sum + e.count, 0);
-    const byReason = new Map<string, number>();
-    const byIP = new Map<string, number>();
-    let lastActiveCount = 0;
-    
-    for (const [, event] of aggregated.events) {
-      const reason = event.data?.reason || 'unknown';
-      const ip = event.data?.remoteIP || 'unknown';
-      
-      byReason.set(reason, (byReason.get(reason) || 0) + event.count);
-      
-      // Track by IP
-      if (ip !== 'unknown') {
-        byIP.set(ip, (byIP.get(ip) || 0) + event.count);
-      }
-      
-      // Track the last active connection count
-      if (event.data?.activeConnections !== undefined) {
-        lastActiveCount = event.data.activeConnections;
-      }
-    }
-    
-    const reasonSummary = Array.from(byReason.entries())
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, 5) // Top 5 reasons
-      .map(([reason, count]) => `${reason}: ${count}`)
-      .join(', ');
-    
-    // Show top IPs if there are many different ones
-    let ipInfo = '';
-    if (byIP.size > 3) {
-      const topIPs = Array.from(byIP.entries())
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 3)
-        .map(([ip, count]) => `${ip} (${count})`)
-        .join(', ');
-      ipInfo = `, from ${byIP.size} IPs (top: ${topIPs})`;
-    } else if (byIP.size > 0) {
-      ipInfo = `, IPs: ${Array.from(byIP.keys()).join(', ')}`;
-    }
-    
-    const duration = Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen));
-    
-    // Special handling for localhost connections (HttpProxy)
-    const localhostCount = byIP.get('::ffff:127.0.0.1') || 0;
-    if (localhostCount > 0 && byIP.size === 1) {
-      // All connections are from localhost (HttpProxy)
-      logger.log('info', `[SUMMARY] ${totalCount} HttpProxy connections terminated in ${Math.round(duration/1000)}s`, {
-        reasons: reasonSummary,
-        activeConnections: lastActiveCount,
-        component: 'connection-dedup'
-      });
-    } else {
-      logger.log('info', `[SUMMARY] ${totalCount} connections terminated in ${Math.round(duration/1000)}s`, {
-        reasons: reasonSummary,
-        activeConnections: lastActiveCount,
-        uniqueReasons: byReason.size,
-        ...(ipInfo ? { ips: ipInfo } : {}),
-        component: 'connection-dedup'
-      });
-    }
-  }
-  
-  private flushIPRejections(aggregated: IAggregatedEvent): void {
-    const byIP = new Map<string, { count: number; reasons: Set<string> }>();
-    const allReasons = new Map<string, number>();
-    
-    for (const [ip, event] of aggregated.events) {
-      if (!byIP.has(ip)) {
-        byIP.set(ip, { count: 0, reasons: new Set() });
-      }
-      const ipData = byIP.get(ip)!;
-      ipData.count += event.count;
-      if (event.data?.reason) {
-        ipData.reasons.add(event.data.reason);
-        // Track overall reason counts
-        allReasons.set(event.data.reason, (allReasons.get(event.data.reason) || 0) + event.count);
-      }
-    }
-    
-    // Create reason summary
-    const reasonSummary = Array.from(allReasons.entries())
-      .sort((a, b) => b[1] - a[1])
-      .map(([reason, count]) => `${reason}: ${count}`)
-      .join(', ');
-    
-    // Log top offenders
-    const topOffenders = Array.from(byIP.entries())
-      .sort((a, b) => b[1].count - a[1].count)
-      .slice(0, 10)
-      .map(([ip, data]) => `${ip} (${data.count}x, ${Array.from(data.reasons).join('/')})`)
-      .join(', ');
-    
-    const totalRejections = Array.from(byIP.values()).reduce((sum, data) => sum + data.count, 0);
-    
-    const duration = Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen));
-    logger.log('warn', `[SUMMARY] Rejected ${totalRejections} connections from ${byIP.size} IPs in ${Math.round(duration/1000)}s (${reasonSummary})`, {
-      topOffenders,
-      component: 'ip-dedup'
-    });
-  }
-  
-  private flushGeneric(aggregated: IAggregatedEvent): void {
-    const totalCount = Array.from(aggregated.events.values()).reduce((sum, e) => sum + e.count, 0);
-    const level = aggregated.events.values().next().value?.level || 'info';
-    
-    // Special handling for IP cleanup events
-    if (aggregated.key === 'ip-cleanup') {
-      const totalCleaned = Array.from(aggregated.events.values()).reduce((sum, e) => {
-        return sum + (e.data?.cleanedIPs || 0) + (e.data?.cleanedRateLimits || 0);
-      }, 0);
-      
-      if (totalCleaned > 0) {
-        logger.log(level as any, `IP tracking cleanup: removed ${totalCleaned} entries across ${totalCount} cleanup cycles`, {
-          duration: Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen)),
-          component: 'log-dedup'
-        });
-      }
-    } else {
-      logger.log(level as any, `${aggregated.key}: ${totalCount} events`, {
-        uniqueEvents: aggregated.events.size,
-        duration: Date.now() - Math.min(...Array.from(aggregated.events.values()).map(e => e.firstSeen)),
-        component: 'log-dedup'
-      });
-    }
-  }
-  
-  /**
-   * Cleanup and stop deduplication
-   */
-  public cleanup(): void {
-    this.flushAll();
-    
-    if (this.globalFlushTimer) {
-      clearInterval(this.globalFlushTimer);
-      this.globalFlushTimer = undefined;
-    }
-    
-    for (const aggregated of this.aggregatedEvents.values()) {
-      if (aggregated.flushTimer) {
-        clearTimeout(aggregated.flushTimer);
-      }
-    }
-    this.aggregatedEvents.clear();
-  }
-}
-
-// Global instance for connection-related log deduplication
-export const connectionLogDeduplicator = new LogDeduplicator(5000); // 5 second batches
-
-// Ensure logs are flushed on process exit.
-// Only use beforeExit — do NOT call process.exit() from SIGINT/SIGTERM handlers
-// as that kills the host process's graceful shutdown (e.g., dcrouter connection draining).
-process.on('beforeExit', () => {
-  connectionLogDeduplicator.flushAll();
-});
-
-process.on('SIGINT', () => {
-  connectionLogDeduplicator.cleanup();
-});
-
-process.on('SIGTERM', () => {
-  connectionLogDeduplicator.cleanup();
-});

ts/core/utils/proxy-protocol.ts

@@ -1,129 +0,0 @@
-import * as plugins from '../../plugins.js';
-import { logger } from './logger.js';
-import { ProxyProtocolParser as ProtocolParser, type IProxyInfo, type IProxyParseResult } from '../../protocols/proxy/index.js';
-
-// Re-export types from protocols for backward compatibility
-export type { IProxyInfo, IProxyParseResult } from '../../protocols/proxy/index.js';
-
-/**
- * Parser for PROXY protocol v1 (text format)
- * Spec: https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
- * 
- * This class now delegates to the protocol parser but adds 
- * smartproxy-specific features like socket reading and logging
- */
-export class ProxyProtocolParser {
-  static readonly PROXY_V1_SIGNATURE = ProtocolParser.PROXY_V1_SIGNATURE;
-  static readonly MAX_HEADER_LENGTH = ProtocolParser.MAX_HEADER_LENGTH;
-  static readonly HEADER_TERMINATOR = ProtocolParser.HEADER_TERMINATOR;
-  
-  /**
-   * Parse PROXY protocol v1 header from buffer
-   * Returns proxy info and remaining data after header
-   */
-  static parse(data: Buffer): IProxyParseResult {
-    // Delegate to protocol parser
-    return ProtocolParser.parse(data);
-  }
-  
-  /**
-   * Generate PROXY protocol v1 header
-   */
-  static generate(info: IProxyInfo): Buffer {
-    // Delegate to protocol parser
-    return ProtocolParser.generate(info);
-  }
-  
-  /**
-   * Validate IP address format
-   */
-  private static isValidIP(ip: string, protocol: 'TCP4' | 'TCP6' | 'UNKNOWN'): boolean {
-    return ProtocolParser.isValidIP(ip, protocol);
-  }
-  
-  /**
-   * Attempt to read a complete PROXY protocol header from a socket
-   * Returns null if no PROXY protocol detected or incomplete
-   */
-  static async readFromSocket(socket: plugins.net.Socket, timeout: number = 5000): Promise<IProxyParseResult | null> {
-    return new Promise((resolve) => {
-      let buffer = Buffer.alloc(0);
-      let resolved = false;
-      
-      const cleanup = () => {
-        socket.removeListener('data', onData);
-        socket.removeListener('error', onError);
-        clearTimeout(timer);
-      };
-      
-      const timer = setTimeout(() => {
-        if (!resolved) {
-          resolved = true;
-          cleanup();
-          resolve({
-            proxyInfo: null,
-            remainingData: buffer
-          });
-        }
-      }, timeout);
-      
-      const onData = (chunk: Buffer) => {
-        buffer = Buffer.concat([buffer, chunk]);
-        
-        // Check if we have enough data
-        if (!buffer.toString('ascii', 0, Math.min(6, buffer.length)).startsWith(this.PROXY_V1_SIGNATURE)) {
-          // Not PROXY protocol
-          resolved = true;
-          cleanup();
-          resolve({
-            proxyInfo: null,
-            remainingData: buffer
-          });
-          return;
-        }
-        
-        // Try to parse
-        try {
-          const result = this.parse(buffer);
-          if (result.proxyInfo) {
-            // Successfully parsed
-            resolved = true;
-            cleanup();
-            resolve(result);
-          } else if (buffer.length > this.MAX_HEADER_LENGTH) {
-            // Header too long
-            resolved = true;
-            cleanup();
-            resolve({
-              proxyInfo: null,
-              remainingData: buffer
-            });
-          }
-          // Otherwise continue reading
-        } catch (error) {
-          // Parse error
-          logger.log('error', `PROXY protocol parse error: ${error.message}`);
-          resolved = true;
-          cleanup();
-          resolve({
-            proxyInfo: null,
-            remainingData: buffer
-          });
-        }
-      };
-      
-      const onError = (error: Error) => {
-        logger.log('error', `Socket error while reading PROXY protocol: ${error.message}`);
-        resolved = true;
-        cleanup();
-        resolve({
-          proxyInfo: null,
-          remainingData: buffer
-        });
-      };
-      
-      socket.on('data', onData);
-      socket.on('error', onError);
-    });
-  }
-}

ts/core/utils/security-utils.ts

@@ -1,305 +0,0 @@
-import * as plugins from '../../plugins.js';
-import { IpMatcher } from '../routing/matchers/ip.js';
-
-/**
- * Security utilities for IP validation, rate limiting, 
- * authentication, and other security features
- */
-
-/**
- * Result of IP validation
- */
-export interface IIpValidationResult {
-  allowed: boolean;
-  reason?: string;
-}
-
-/**
- * IP connection tracking information
- */
-export interface IIpConnectionInfo {
-  connections: Set<string>;  // ConnectionIDs
-  timestamps: number[];      // Connection timestamps
-  ipVariants: string[];      // Normalized IP variants (e.g., ::ffff:127.0.0.1 and 127.0.0.1)
-}
-
-/**
- * Rate limit tracking
- */
-export interface IRateLimitInfo {
-  count: number;
-  expiry: number;
-}
-
-/**
- * Logger interface for security utilities
- */
-export interface ISecurityLogger {
-  info: (message: string, ...args: any[]) => void;
-  warn: (message: string, ...args: any[]) => void;
-  error: (message: string, ...args: any[]) => void;
-  debug?: (message: string, ...args: any[]) => void;
-}
-
-/**
- * Normalize IP addresses for comparison
- * Handles IPv4-mapped IPv6 addresses (::ffff:127.0.0.1)
- * 
- * @param ip IP address to normalize
- * @returns Array of equivalent IP representations
- */
-export function normalizeIP(ip: string): string[] {
-  if (!ip) return [];
-  
-  // Handle IPv4-mapped IPv6 addresses (::ffff:127.0.0.1)
-  if (ip.startsWith('::ffff:')) {
-    const ipv4 = ip.slice(7);
-    return [ip, ipv4];
-  }
-  
-  // Handle IPv4 addresses by also checking IPv4-mapped form
-  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) {
-    return [ip, `::ffff:${ip}`];
-  }
-  
-  return [ip];
-}
-
-/**
- * Check if an IP is authorized based on allow and block lists
- *
- * @param ip - The IP address to check
- * @param allowedIPs - Array of allowed IP patterns
- * @param blockedIPs - Array of blocked IP patterns
- * @returns Whether the IP is authorized
- */
-export function isIPAuthorized(
-  ip: string, 
-  allowedIPs: string[] = ['*'], 
-  blockedIPs: string[] = []
-): boolean {
-  // Skip IP validation if no rules
-  if (!ip || (allowedIPs.length === 0 && blockedIPs.length === 0)) {
-    return true;
-  }
-
-  // First check if IP is blocked - blocked IPs take precedence
-  if (blockedIPs.length > 0) {
-    for (const pattern of blockedIPs) {
-      if (IpMatcher.match(pattern, ip)) {
-        return false;
-      }
-    }
-  }
-
-  // If allowed IPs list has wildcard, all non-blocked IPs are allowed
-  if (allowedIPs.includes('*')) {
-    return true;
-  }
-
-  // Then check if IP is allowed in the explicit allow list
-  if (allowedIPs.length > 0) {
-    for (const pattern of allowedIPs) {
-      if (IpMatcher.match(pattern, ip)) {
-        return true;
-      }
-    }
-    // If allowedIPs is specified but no match, deny access
-    return false;
-  }
-
-  // Default allow if no explicit allow list
-  return true;
-}
-
-/**
- * Check if an IP exceeds maximum connections
- *
- * @param ip - The IP address to check
- * @param ipConnectionsMap - Map of IPs to connection info
- * @param maxConnectionsPerIP - Maximum allowed connections per IP
- * @returns Result with allowed status and reason if blocked
- */
-export function checkMaxConnections(
-  ip: string,
-  ipConnectionsMap: Map<string, IIpConnectionInfo>,
-  maxConnectionsPerIP: number
-): IIpValidationResult {
-  if (!ipConnectionsMap.has(ip)) {
-    return { allowed: true };
-  }
-
-  const connectionCount = ipConnectionsMap.get(ip)!.connections.size;
-  
-  if (connectionCount >= maxConnectionsPerIP) {
-    return {
-      allowed: false,
-      reason: `Maximum connections per IP (${maxConnectionsPerIP}) exceeded`
-    };
-  }
-
-  return { allowed: true };
-}
-
-/**
- * Check if an IP exceeds connection rate limit
- *
- * @param ip - The IP address to check
- * @param ipConnectionsMap - Map of IPs to connection info
- * @param rateLimit - Maximum connections per minute
- * @returns Result with allowed status and reason if blocked
- */
-export function checkConnectionRate(
-  ip: string,
-  ipConnectionsMap: Map<string, IIpConnectionInfo>,
-  rateLimit: number
-): IIpValidationResult {
-  const now = Date.now();
-  const minute = 60 * 1000;
-
-  // Get or create connection info
-  if (!ipConnectionsMap.has(ip)) {
-    const info: IIpConnectionInfo = {
-      connections: new Set(),
-      timestamps: [now],
-      ipVariants: normalizeIP(ip)
-    };
-    ipConnectionsMap.set(ip, info);
-    return { allowed: true };
-  }
-
-  // Get timestamps and filter out entries older than 1 minute
-  const info = ipConnectionsMap.get(ip)!;
-  const timestamps = info.timestamps.filter(time => now - time < minute);
-  timestamps.push(now);
-  info.timestamps = timestamps;
-
-  // Check if rate exceeds limit
-  if (timestamps.length > rateLimit) {
-    return {
-      allowed: false,
-      reason: `Connection rate limit (${rateLimit}/min) exceeded`
-    };
-  }
-
-  return { allowed: true };
-}
-
-/**
- * Track a connection for an IP
- *
- * @param ip - The IP address
- * @param connectionId - The connection ID to track
- * @param ipConnectionsMap - Map of IPs to connection info
- */
-export function trackConnection(
-  ip: string,
-  connectionId: string,
-  ipConnectionsMap: Map<string, IIpConnectionInfo>
-): void {
-  if (!ipConnectionsMap.has(ip)) {
-    ipConnectionsMap.set(ip, {
-      connections: new Set([connectionId]),
-      timestamps: [Date.now()],
-      ipVariants: normalizeIP(ip)
-    });
-    return;
-  }
-
-  const info = ipConnectionsMap.get(ip)!;
-  info.connections.add(connectionId);
-}
-
-/**
- * Remove connection tracking for an IP
- *
- * @param ip - The IP address
- * @param connectionId - The connection ID to remove
- * @param ipConnectionsMap - Map of IPs to connection info
- */
-export function removeConnection(
-  ip: string,
-  connectionId: string,
-  ipConnectionsMap: Map<string, IIpConnectionInfo>
-): void {
-  if (!ipConnectionsMap.has(ip)) return;
-
-  const info = ipConnectionsMap.get(ip)!;
-  info.connections.delete(connectionId);
-
-  if (info.connections.size === 0) {
-    ipConnectionsMap.delete(ip);
-  }
-}
-
-/**
- * Clean up expired rate limits
- *
- * @param rateLimits - Map of rate limits to clean up
- * @param logger - Logger for debug messages
- */
-export function cleanupExpiredRateLimits(
-  rateLimits: Map<string, Map<string, IRateLimitInfo>>,
-  logger?: ISecurityLogger
-): void {
-  const now = Date.now();
-  let totalRemoved = 0;
-
-  for (const [routeId, routeLimits] of rateLimits.entries()) {
-    let removed = 0;
-    for (const [key, limit] of routeLimits.entries()) {
-      if (limit.expiry < now) {
-        routeLimits.delete(key);
-        removed++;
-        totalRemoved++;
-      }
-    }
-    
-    if (removed > 0 && logger?.debug) {
-      logger.debug(`Cleaned up ${removed} expired rate limits for route ${routeId}`);
-    }
-  }
-  
-  if (totalRemoved > 0 && logger?.info) {
-    logger.info(`Cleaned up ${totalRemoved} expired rate limits total`);
-  }
-}
-
-/**
- * Generate basic auth header value from username and password
- *
- * @param username - The username
- * @param password - The password
- * @returns Base64 encoded basic auth string
- */
-export function generateBasicAuthHeader(username: string, password: string): string {
-  return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
-}
-
-/**
- * Parse basic auth header
- *
- * @param authHeader - The Authorization header value
- * @returns Username and password, or null if invalid
- */
-export function parseBasicAuthHeader(
-  authHeader: string
-): { username: string; password: string } | null {
-  if (!authHeader || !authHeader.startsWith('Basic ')) {
-    return null;
-  }
-
-  try {
-    const base64 = authHeader.slice(6); // Remove 'Basic '
-    const decoded = Buffer.from(base64, 'base64').toString();
-    const [username, password] = decoded.split(':');
-    
-    if (!username || !password) {
-      return null;
-    }
-
-    return { username, password };
-  } catch (err) {
-    return null;
-  }
-}

ts/core/utils/shared-security-manager.ts

@@ -1,470 +0,0 @@
-import * as plugins from '../../plugins.js';
-import type { IRouteConfig, IRouteContext } from '../../proxies/smart-proxy/models/route-types.js';
-import type {
-  IIpValidationResult,
-  IIpConnectionInfo,
-  ISecurityLogger,
-  IRateLimitInfo
-} from './security-utils.js';
-import {
-  isIPAuthorized,
-  checkMaxConnections,
-  checkConnectionRate,
-  trackConnection,
-  removeConnection,
-  cleanupExpiredRateLimits,
-  parseBasicAuthHeader,
-  normalizeIP
-} from './security-utils.js';
-
-/**
- * Shared SecurityManager for use across proxy components
- * Handles IP tracking, rate limiting, and authentication
- */
-export class SharedSecurityManager {
-  // IP connection tracking
-  private connectionsByIP: Map<string, IIpConnectionInfo> = new Map();
-  
-  // Route-specific rate limiting
-  private rateLimits: Map<string, Map<string, IRateLimitInfo>> = new Map();
-  
-  // Cache IP filtering results to avoid constant regex matching
-  private ipFilterCache: Map<string, Map<string, boolean>> = new Map();
-  
-  // Default limits
-  private maxConnectionsPerIP: number;
-  private connectionRateLimitPerMinute: number;
-  
-  // Cache cleanup interval
-  private cleanupInterval: NodeJS.Timeout | null = null;
-  
-  /**
-   * Create a new SharedSecurityManager
-   * 
-   * @param options - Configuration options
-   * @param logger - Logger instance
-   */
-  constructor(options: {
-    maxConnectionsPerIP?: number;
-    connectionRateLimitPerMinute?: number;
-    cleanupIntervalMs?: number;
-    routes?: IRouteConfig[];
-  }, private logger?: ISecurityLogger) {
-    this.maxConnectionsPerIP = options.maxConnectionsPerIP || 100;
-    this.connectionRateLimitPerMinute = options.connectionRateLimitPerMinute || 300;
-    
-    // Set up logger with defaults if not provided
-    this.logger = logger || {
-      info: console.log,
-      warn: console.warn,
-      error: console.error
-    };
-    
-    // Set up cache cleanup interval
-    const cleanupInterval = options.cleanupIntervalMs || 60000; // Default: 1 minute
-    this.cleanupInterval = setInterval(() => {
-      this.cleanupCaches();
-    }, cleanupInterval);
-    
-    // Don't keep the process alive just for cleanup
-    if (this.cleanupInterval.unref) {
-      this.cleanupInterval.unref();
-    }
-  }
-  
-  /**
-   * Get connections count by IP
-   * 
-   * @param ip - The IP address to check
-   * @returns Number of connections from this IP
-   */
-  public getConnectionCountByIP(ip: string): number {
-    // Check all normalized variants of the IP
-    const variants = normalizeIP(ip);
-    for (const variant of variants) {
-      const info = this.connectionsByIP.get(variant);
-      if (info) {
-        return info.connections.size;
-      }
-    }
-    return 0;
-  }
-  
-  /**
-   * Track connection by IP
-   * 
-   * @param ip - The IP address to track
-   * @param connectionId - The connection ID to associate
-   */
-  public trackConnectionByIP(ip: string, connectionId: string): void {
-    // Check if any variant already exists
-    const variants = normalizeIP(ip);
-    let existingKey: string | null = null;
-    
-    for (const variant of variants) {
-      if (this.connectionsByIP.has(variant)) {
-        existingKey = variant;
-        break;
-      }
-    }
-    
-    // Use existing key or the original IP
-    trackConnection(existingKey || ip, connectionId, this.connectionsByIP);
-  }
-  
-  /**
-   * Remove connection tracking for an IP
-   * 
-   * @param ip - The IP address to update
-   * @param connectionId - The connection ID to remove
-   */
-  public removeConnectionByIP(ip: string, connectionId: string): void {
-    // Check all variants to find where the connection is tracked
-    const variants = normalizeIP(ip);
-    
-    for (const variant of variants) {
-      if (this.connectionsByIP.has(variant)) {
-        removeConnection(variant, connectionId, this.connectionsByIP);
-        break;
-      }
-    }
-  }
-  
-  /**
-   * Check if IP is authorized based on route security settings
-   * 
-   * @param ip - The IP address to check
-   * @param allowedIPs - List of allowed IP patterns
-   * @param blockedIPs - List of blocked IP patterns
-   * @returns Whether the IP is authorized
-   */
-  public isIPAuthorized(
-    ip: string,
-    allowedIPs: string[] = ['*'],
-    blockedIPs: string[] = []
-  ): boolean {
-    return isIPAuthorized(ip, allowedIPs, blockedIPs);
-  }
-  
-  /**
-   * Validate IP against rate limits and connection limits
-   *
-   * @param ip - The IP address to validate
-   * @returns Result with allowed status and reason if blocked
-   */
-  public validateIP(ip: string): IIpValidationResult {
-    // Check connection count limit
-    const connectionResult = checkMaxConnections(
-      ip,
-      this.connectionsByIP,
-      this.maxConnectionsPerIP
-    );
-    if (!connectionResult.allowed) {
-      return connectionResult;
-    }
-
-    // Check connection rate limit
-    const rateResult = checkConnectionRate(
-      ip,
-      this.connectionsByIP,
-      this.connectionRateLimitPerMinute
-    );
-    if (!rateResult.allowed) {
-      return rateResult;
-    }
-
-    return { allowed: true };
-  }
-
-  /**
-   * Atomically validate an IP and track the connection if allowed.
-   * This prevents race conditions where concurrent connections could bypass per-IP limits.
-   *
-   * @param ip - The IP address to validate
-   * @param connectionId - The connection ID to track if validation passes
-   * @returns Object with validation result and reason
-   */
-  public validateAndTrackIP(ip: string, connectionId: string): IIpValidationResult {
-    // Check connection count limit BEFORE tracking
-    const connectionResult = checkMaxConnections(
-      ip,
-      this.connectionsByIP,
-      this.maxConnectionsPerIP
-    );
-    if (!connectionResult.allowed) {
-      return connectionResult;
-    }
-
-    // Check connection rate limit
-    const rateResult = checkConnectionRate(
-      ip,
-      this.connectionsByIP,
-      this.connectionRateLimitPerMinute
-    );
-    if (!rateResult.allowed) {
-      return rateResult;
-    }
-
-    // Validation passed - immediately track to prevent race conditions
-    this.trackConnectionByIP(ip, connectionId);
-
-    return { allowed: true };
-  }
-  
-  /**
-   * Check if a client is allowed to access a specific route
-   * 
-   * @param route - The route to check
-   * @param context - The request context
-   * @param routeConnectionCount - Current connection count for this route (optional)
-   * @returns Whether access is allowed
-   */
-  public isAllowed(route: IRouteConfig, context: IRouteContext, routeConnectionCount?: number): boolean {
-    if (!route.security) {
-      return true; // No security restrictions
-    }
-    
-    // --- IP filtering ---
-    if (!this.isClientIpAllowed(route, context.clientIp)) {
-      this.logger?.debug?.(`IP ${context.clientIp} is blocked for route ${route.name || 'unnamed'}`);
-      return false;
-    }
-    
-    // --- Route-level connection limit ---
-    if (route.security.maxConnections !== undefined && routeConnectionCount !== undefined) {
-      if (routeConnectionCount >= route.security.maxConnections) {
-        this.logger?.debug?.(`Route connection limit (${route.security.maxConnections}) exceeded for route ${route.name || 'unnamed'}`);
-        return false;
-      }
-    }
-    
-    // --- Rate limiting ---
-    if (route.security.rateLimit?.enabled && !this.isWithinRateLimit(route, context)) {
-      this.logger?.debug?.(`Rate limit exceeded for route ${route.name || 'unnamed'}`);
-      return false;
-    }
-    
-    return true;
-  }
-  
-  /**
-   * Check if a client IP is allowed for a route
-   * 
-   * @param route - The route to check
-   * @param clientIp - The client IP
-   * @returns Whether the IP is allowed
-   */
-  private isClientIpAllowed(route: IRouteConfig, clientIp: string): boolean {
-    if (!route.security) {
-      return true; // No security restrictions
-    }
-    
-    const routeId = route.id || route.name || 'unnamed';
-    
-    // Check cache first
-    if (!this.ipFilterCache.has(routeId)) {
-      this.ipFilterCache.set(routeId, new Map());
-    }
-    
-    const routeCache = this.ipFilterCache.get(routeId)!;
-    if (routeCache.has(clientIp)) {
-      return routeCache.get(clientIp)!;
-    }
-    
-    // Check IP against route security settings
-    const ipAllowList = route.security.ipAllowList;
-    const ipBlockList = route.security.ipBlockList;
-    
-    const allowed = this.isIPAuthorized(clientIp, ipAllowList, ipBlockList);
-    
-    // Cache the result
-    routeCache.set(clientIp, allowed);
-    
-    return allowed;
-  }
-  
-  /**
-   * Check if request is within rate limit
-   * 
-   * @param route - The route to check
-   * @param context - The request context
-   * @returns Whether the request is within rate limit
-   */
-  private isWithinRateLimit(route: IRouteConfig, context: IRouteContext): boolean {
-    if (!route.security?.rateLimit?.enabled) {
-      return true;
-    }
-    
-    const rateLimit = route.security.rateLimit;
-    const routeId = route.id || route.name || 'unnamed';
-    
-    // Determine rate limit key (by IP, path, or header)
-    let key = context.clientIp; // Default to IP
-    
-    if (rateLimit.keyBy === 'path' && context.path) {
-      key = `${context.clientIp}:${context.path}`;
-    } else if (rateLimit.keyBy === 'header' && rateLimit.headerName && context.headers) {
-      const headerValue = context.headers[rateLimit.headerName.toLowerCase()];
-      if (headerValue) {
-        key = `${context.clientIp}:${headerValue}`;
-      }
-    }
-    
-    // Get or create rate limit tracking for this route
-    if (!this.rateLimits.has(routeId)) {
-      this.rateLimits.set(routeId, new Map());
-    }
-    
-    const routeLimits = this.rateLimits.get(routeId)!;
-    const now = Date.now();
-    
-    // Get or create rate limit tracking for this key
-    let limit = routeLimits.get(key);
-    if (!limit || limit.expiry < now) {
-      // Create new rate limit or reset expired one
-      limit = {
-        count: 1,
-        expiry: now + (rateLimit.window * 1000)
-      };
-      routeLimits.set(key, limit);
-      return true;
-    }
-    
-    // Increment the counter
-    limit.count++;
-    
-    // Check if rate limit is exceeded
-    return limit.count <= rateLimit.maxRequests;
-  }
-  
-  /**
-   * Validate HTTP Basic Authentication
-   *
-   * @param route - The route to check
-   * @param authHeader - The Authorization header
-   * @returns Whether authentication is valid
-   */
-  public validateBasicAuth(route: IRouteConfig, authHeader?: string): boolean {
-    // Skip if basic auth not enabled for route
-    if (!route.security?.basicAuth?.enabled) {
-      return true;
-    }
-
-    // No auth header means auth failed
-    if (!authHeader) {
-      return false;
-    }
-
-    // Parse auth header
-    const credentials = parseBasicAuthHeader(authHeader);
-    if (!credentials) {
-      return false;
-    }
-
-    // Check credentials against configured users
-    const { username, password } = credentials;
-    const users = route.security.basicAuth.users;
-
-    return users.some(user =>
-      user.username === username && user.password === password
-    );
-  }
-
-  /**
-   * Verify a JWT token against route configuration
-   *
-   * @param route - The route to verify the token for
-   * @param token - The JWT token to verify
-   * @returns True if the token is valid, false otherwise
-   */
-  public verifyJwtToken(route: IRouteConfig, token: string): boolean {
-    if (!route.security?.jwtAuth?.enabled) {
-      return true;
-    }
-
-    try {
-      const jwtAuth = route.security.jwtAuth;
-
-      // Verify structure (header.payload.signature)
-      const parts = token.split('.');
-      if (parts.length !== 3) {
-        return false;
-      }
-
-      // Decode payload
-      const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
-
-      // Check expiration
-      if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
-        return false;
-      }
-
-      // Check issuer
-      if (jwtAuth.issuer && payload.iss !== jwtAuth.issuer) {
-        return false;
-      }
-
-      // Check audience
-      if (jwtAuth.audience && payload.aud !== jwtAuth.audience) {
-        return false;
-      }
-
-      // Note: In a real implementation, you'd also verify the signature
-      // using the secret and algorithm specified in jwtAuth.
-      // This requires a proper JWT library for cryptographic verification.
-
-      return true;
-    } catch (err) {
-      this.logger?.error?.(`Error verifying JWT: ${err}`);
-      return false;
-    }
-  }
-  
-  /**
-   * Clean up caches to prevent memory leaks
-   */
-  private cleanupCaches(): void {
-    // Clean up rate limits
-    cleanupExpiredRateLimits(this.rateLimits, this.logger);
-    
-    // Clean up IP connection tracking
-    let cleanedIPs = 0;
-    for (const [ip, info] of this.connectionsByIP.entries()) {
-      // Remove IPs with no active connections and no recent timestamps
-      if (info.connections.size === 0 && info.timestamps.length === 0) {
-        this.connectionsByIP.delete(ip);
-        cleanedIPs++;
-      }
-    }
-    
-    if (cleanedIPs > 0 && this.logger?.debug) {
-      this.logger.debug(`Cleaned up ${cleanedIPs} IPs with no active connections`);
-    }
-    
-    // IP filter cache doesn't need cleanup (tied to routes)
-  }
-  
-  /**
-   * Clear all IP tracking data (for shutdown)
-   */
-  public clearIPTracking(): void {
-    this.connectionsByIP.clear();
-    this.rateLimits.clear();
-    this.ipFilterCache.clear();
-    
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
-  }
-  
-  /**
-   * Update routes for security checking
-   * 
-   * @param routes - New routes to use
-   */
-  public setRoutes(routes: IRouteConfig[]): void {
-    // Only clear the IP filter cache - route-specific
-    this.ipFilterCache.clear();
-  }
-}

ts/core/utils/socket-utils.ts

@@ -1,322 +0,0 @@
-import * as plugins from '../../plugins.js';
-
-export interface CleanupOptions {
-  immediate?: boolean;      // Force immediate destruction
-  allowDrain?: boolean;     // Allow write buffer to drain
-  gracePeriod?: number;     // Ms to wait before force close
-}
-
-export interface SafeSocketOptions {
-  port: number;
-  host: string;
-  onError?: (error: Error) => void;
-  onConnect?: () => void;
-  timeout?: number;
-}
-
-/**
- * Safely cleanup a socket by removing all listeners and destroying it
- * @param socket The socket to cleanup
- * @param socketName Optional name for logging
- * @param options Cleanup options
- */
-export function cleanupSocket(
-  socket: plugins.net.Socket | plugins.tls.TLSSocket | null, 
-  socketName?: string,
-  options: CleanupOptions = {}
-): Promise<void> {
-  if (!socket || socket.destroyed) return Promise.resolve();
-  
-  return new Promise<void>((resolve) => {
-    const cleanup = () => {
-      try {
-        // Remove all event listeners
-        socket.removeAllListeners();
-        
-        // Destroy if not already destroyed
-        if (!socket.destroyed) {
-          socket.destroy();
-        }
-      } catch (err) {
-        console.error(`Error cleaning up socket${socketName ? ` (${socketName})` : ''}: ${err}`);
-      }
-      resolve();
-    };
-    
-    if (options.immediate) {
-      // Immediate cleanup (old behavior)
-      socket.unpipe();
-      cleanup();
-    } else if (options.allowDrain && socket.writable) {
-      // Allow pending writes to complete
-      socket.end(() => cleanup());
-      
-      // Force cleanup after grace period
-      if (options.gracePeriod) {
-        setTimeout(() => {
-          if (!socket.destroyed) {
-            cleanup();
-          }
-        }, options.gracePeriod);
-      }
-    } else {
-      // Default: immediate cleanup
-      socket.unpipe();
-      cleanup();
-    }
-  });
-}
-
-
-/**
- * Create independent cleanup handlers for paired sockets that support half-open connections
- * @param clientSocket The client socket
- * @param serverSocket The server socket
- * @param onBothClosed Callback when both sockets are closed
- * @returns Independent cleanup functions for each socket
- */
-export function createIndependentSocketHandlers(
-  clientSocket: plugins.net.Socket | plugins.tls.TLSSocket,
-  serverSocket: plugins.net.Socket | plugins.tls.TLSSocket,
-  onBothClosed: (reason: string) => void,
-  options: { enableHalfOpen?: boolean } = {}
-): { cleanupClient: (reason: string) => Promise<void>, cleanupServer: (reason: string) => Promise<void> } {
-  let clientClosed = false;
-  let serverClosed = false;
-  let clientReason = '';
-  let serverReason = '';
-  
-  const checkBothClosed = () => {
-    if (clientClosed && serverClosed) {
-      onBothClosed(`client: ${clientReason}, server: ${serverReason}`);
-    }
-  };
-  
-  const cleanupClient = async (reason: string) => {
-    if (clientClosed) return;
-    clientClosed = true;
-    clientReason = reason;
-    
-    // Default behavior: close both sockets when one closes (required for proxy chains)
-    if (!serverClosed && !options.enableHalfOpen) {
-      serverSocket.destroy();
-    }
-    
-    // Half-open support (opt-in only)
-    if (!serverClosed && serverSocket.writable && options.enableHalfOpen) {
-      // Half-close: stop reading from client, let server finish
-      clientSocket.pause();
-      clientSocket.unpipe(serverSocket);
-      await cleanupSocket(clientSocket, 'client', { allowDrain: true, gracePeriod: 5000 });
-    } else {
-      await cleanupSocket(clientSocket, 'client', { immediate: true });
-    }
-    
-    checkBothClosed();
-  };
-  
-  const cleanupServer = async (reason: string) => {
-    if (serverClosed) return;
-    serverClosed = true;
-    serverReason = reason;
-    
-    // Default behavior: close both sockets when one closes (required for proxy chains)
-    if (!clientClosed && !options.enableHalfOpen) {
-      clientSocket.destroy();
-    }
-    
-    // Half-open support (opt-in only)
-    if (!clientClosed && clientSocket.writable && options.enableHalfOpen) {
-      // Half-close: stop reading from server, let client finish
-      serverSocket.pause();
-      serverSocket.unpipe(clientSocket);
-      await cleanupSocket(serverSocket, 'server', { allowDrain: true, gracePeriod: 5000 });
-    } else {
-      await cleanupSocket(serverSocket, 'server', { immediate: true });
-    }
-    
-    checkBothClosed();
-  };
-  
-  return { cleanupClient, cleanupServer };
-}
-
-/**
- * Setup socket error and close handlers with proper cleanup
- * @param socket The socket to setup handlers for
- * @param handleClose The cleanup function to call
- * @param handleTimeout Optional custom timeout handler
- * @param errorPrefix Optional prefix for error messages
- */
-export function setupSocketHandlers(
-  socket: plugins.net.Socket | plugins.tls.TLSSocket,
-  handleClose: (reason: string) => void,
-  handleTimeout?: (socket: plugins.net.Socket | plugins.tls.TLSSocket) => void,
-  errorPrefix?: string
-): void {
-  socket.on('error', (error) => {
-    const prefix = errorPrefix || 'Socket';
-    handleClose(`${prefix}_error: ${error.message}`);
-  });
-  
-  socket.on('close', () => {
-    const prefix = errorPrefix || 'socket';
-    handleClose(`${prefix}_closed`);
-  });
-  
-  socket.on('timeout', () => {
-    if (handleTimeout) {
-      handleTimeout(socket);  // Custom timeout handling
-    } else {
-      // Default: just log, don't close
-      console.warn(`Socket timeout: ${errorPrefix || 'socket'}`);
-    }
-  });
-}
-
-/**
- * Setup bidirectional data forwarding between two sockets with proper cleanup
- * @param clientSocket The client/incoming socket
- * @param serverSocket The server/outgoing socket
- * @param handlers Object containing optional handlers for data and cleanup
- * @returns Cleanup functions for both sockets
- */
-export function setupBidirectionalForwarding(
-  clientSocket: plugins.net.Socket | plugins.tls.TLSSocket,
-  serverSocket: plugins.net.Socket | plugins.tls.TLSSocket,
-  handlers: {
-    onClientData?: (chunk: Buffer) => void;
-    onServerData?: (chunk: Buffer) => void;
-    onCleanup: (reason: string) => void;
-    enableHalfOpen?: boolean;
-  }
-): { cleanupClient: (reason: string) => Promise<void>, cleanupServer: (reason: string) => Promise<void> } {
-  // Set up cleanup handlers
-  const { cleanupClient, cleanupServer } = createIndependentSocketHandlers(
-    clientSocket,
-    serverSocket,
-    handlers.onCleanup,
-    { enableHalfOpen: handlers.enableHalfOpen }
-  );
-  
-  // Set up error and close handlers
-  setupSocketHandlers(clientSocket, cleanupClient, undefined, 'client');
-  setupSocketHandlers(serverSocket, cleanupServer, undefined, 'server');
-  
-  // Set up data forwarding with backpressure handling
-  clientSocket.on('data', (chunk: Buffer) => {
-    if (handlers.onClientData) {
-      handlers.onClientData(chunk);
-    }
-    
-    if (serverSocket.writable) {
-      const flushed = serverSocket.write(chunk);
-      
-      // Handle backpressure
-      if (!flushed) {
-        clientSocket.pause();
-        serverSocket.once('drain', () => {
-          if (!clientSocket.destroyed) {
-            clientSocket.resume();
-          }
-        });
-      }
-    }
-  });
-  
-  serverSocket.on('data', (chunk: Buffer) => {
-    if (handlers.onServerData) {
-      handlers.onServerData(chunk);
-    }
-    
-    if (clientSocket.writable) {
-      const flushed = clientSocket.write(chunk);
-      
-      // Handle backpressure
-      if (!flushed) {
-        serverSocket.pause();
-        clientSocket.once('drain', () => {
-          if (!serverSocket.destroyed) {
-            serverSocket.resume();
-          }
-        });
-      }
-    }
-  });
-  
-  return { cleanupClient, cleanupServer };
-}
-
-/**
- * Create a socket with immediate error handling to prevent crashes
- * @param options Socket creation options
- * @returns The created socket
- */
-export function createSocketWithErrorHandler(options: SafeSocketOptions): plugins.net.Socket {
-  const { port, host, onError, onConnect, timeout } = options;
-  
-  // Create socket with immediate error handler attachment
-  const socket = new plugins.net.Socket();
-  
-  // Track if connected
-  let connected = false;
-  let connectionTimeout: NodeJS.Timeout | null = null;
-  
-  // Attach error handler BEFORE connecting to catch immediate errors
-  socket.on('error', (error) => {
-    console.error(`Socket connection error to ${host}:${port}: ${error.message}`);
-    // Clear the connection timeout if it exists
-    if (connectionTimeout) {
-      clearTimeout(connectionTimeout);
-      connectionTimeout = null;
-    }
-    if (onError) {
-      onError(error);
-    }
-  });
-  
-  // Attach connect handler
-  const handleConnect = () => {
-    connected = true;
-    // Clear the connection timeout
-    if (connectionTimeout) {
-      clearTimeout(connectionTimeout);
-      connectionTimeout = null;
-    }
-    // Set inactivity timeout if provided (after connection is established)
-    if (timeout) {
-      socket.setTimeout(timeout);
-    }
-    if (onConnect) {
-      onConnect();
-    }
-  };
-  
-  socket.on('connect', handleConnect);
-  
-  // Implement connection establishment timeout
-  if (timeout) {
-    connectionTimeout = setTimeout(() => {
-      if (!connected && !socket.destroyed) {
-        // Connection timed out - destroy the socket
-        const error = new Error(`Connection timeout after ${timeout}ms to ${host}:${port}`);
-        (error as any).code = 'ETIMEDOUT';
-        
-        console.error(`Socket connection timeout to ${host}:${port} after ${timeout}ms`);
-        
-        // Destroy the socket
-        socket.destroy();
-        
-        // Call error handler
-        if (onError) {
-          onError(error);
-        }
-      }
-    }, timeout);
-  }
-  
-  // Now attempt to connect - any immediate errors will be caught
-  socket.connect(port, host);
-  
-  return socket;
-}

ts/core/utils/template-utils.ts

@@ -1,124 +0,0 @@
-import type { IRouteContext } from '../models/route-context.js';
-
-/**
- * Utility class for resolving template variables in strings
- */
-export class TemplateUtils {
-  /**
-   * Resolve template variables in a string using the route context
-   * Supports variables like {domain}, {path}, {clientIp}, etc.
-   * 
-   * @param template The template string with {variables}
-   * @param context The route context with values
-   * @returns The resolved string
-   */
-  public static resolveTemplateVariables(template: string, context: IRouteContext): string {
-    if (!template) {
-      return template;
-    }
-    
-    // Replace variables with values from context
-    return template.replace(/\{([a-zA-Z0-9_\.]+)\}/g, (match, varName) => {
-      // Handle nested properties with dot notation (e.g., {headers.host})
-      if (varName.includes('.')) {
-        const parts = varName.split('.');
-        let current: any = context;
-        
-        // Traverse nested object structure
-        for (const part of parts) {
-          if (current === undefined || current === null) {
-            return match; // Return original if path doesn't exist
-          }
-          current = current[part];
-        }
-        
-        // Return the resolved value if it exists
-        if (current !== undefined && current !== null) {
-          return TemplateUtils.convertToString(current);
-        }
-        
-        return match;
-      }
-
-      // Direct property access
-      const value = context[varName as keyof IRouteContext];
-      if (value === undefined) {
-        return match; // Keep the original {variable} if not found
-      }
-
-      // Convert value to string
-      return TemplateUtils.convertToString(value);
-    });
-  }
-  
-  /**
-   * Safely convert a value to a string
-   * 
-   * @param value Any value to convert to string
-   * @returns String representation or original match for complex objects
-   */
-  private static convertToString(value: any): string {
-    if (value === null || value === undefined) {
-      return '';
-    }
-    
-    if (typeof value === 'string') {
-      return value;
-    }
-    
-    if (typeof value === 'number' || typeof value === 'boolean') {
-      return value.toString();
-    }
-    
-    if (Array.isArray(value)) {
-      return value.join(',');
-    }
-    
-    if (typeof value === 'object') {
-      try {
-        return JSON.stringify(value);
-      } catch (e) {
-        return '[Object]';
-      }
-    }
-    
-    return String(value);
-  }
-  
-  /**
-   * Resolve template variables in header values
-   * 
-   * @param headers Header object with potential template variables
-   * @param context Route context for variable resolution
-   * @returns New header object with resolved values
-   */
-  public static resolveHeaderTemplates(
-    headers: Record<string, string>,
-    context: IRouteContext
-  ): Record<string, string> {
-    const result: Record<string, string> = {};
-    
-    for (const [key, value] of Object.entries(headers)) {
-      // Skip special directive headers (starting with !)
-      if (value.startsWith('!')) {
-        result[key] = value;
-        continue;
-      }
-      
-      // Resolve template variables in the header value
-      result[key] = TemplateUtils.resolveTemplateVariables(value, context);
-    }
-    
-    return result;
-  }
-  
-  /**
-   * Check if a string contains template variables
-   * 
-   * @param str String to check for template variables
-   * @returns True if string contains template variables
-   */
-  public static containsTemplateVariables(str: string): boolean {
-    return !!str && /\{([a-zA-Z0-9_\.]+)\}/g.test(str);
-  }
-}

ts/core/utils/validation-utils.ts

@@ -1,177 +0,0 @@
-import * as plugins from '../../plugins.js';
-import type { IDomainOptions, IAcmeOptions } from '../models/common-types.js';
-
-/**
- * Collection of validation utilities for configuration and domain options
- */
-export class ValidationUtils {
-  /**
-   * Validates domain configuration options
-   * 
-   * @param domainOptions The domain options to validate
-   * @returns An object with validation result and error message if invalid
-   */
-  public static validateDomainOptions(domainOptions: IDomainOptions): { isValid: boolean; error?: string } {
-    if (!domainOptions) {
-      return { isValid: false, error: 'Domain options cannot be null or undefined' };
-    }
-
-    if (!domainOptions.domainName) {
-      return { isValid: false, error: 'Domain name is required' };
-    }
-
-    // Check domain pattern
-    if (!this.isValidDomainName(domainOptions.domainName)) {
-      return { isValid: false, error: `Invalid domain name: ${domainOptions.domainName}` };
-    }
-
-    // Validate forward config if provided
-    if (domainOptions.forward) {
-      if (!domainOptions.forward.ip) {
-        return { isValid: false, error: 'Forward IP is required when forward is specified' };
-      }
-
-      if (!domainOptions.forward.port) {
-        return { isValid: false, error: 'Forward port is required when forward is specified' };
-      }
-
-      if (!this.isValidPort(domainOptions.forward.port)) {
-        return { isValid: false, error: `Invalid forward port: ${domainOptions.forward.port}` };
-      }
-    }
-
-    // Validate ACME forward config if provided
-    if (domainOptions.acmeForward) {
-      if (!domainOptions.acmeForward.ip) {
-        return { isValid: false, error: 'ACME forward IP is required when acmeForward is specified' };
-      }
-
-      if (!domainOptions.acmeForward.port) {
-        return { isValid: false, error: 'ACME forward port is required when acmeForward is specified' };
-      }
-
-      if (!this.isValidPort(domainOptions.acmeForward.port)) {
-        return { isValid: false, error: `Invalid ACME forward port: ${domainOptions.acmeForward.port}` };
-      }
-    }
-
-    return { isValid: true };
-  }
-
-  /**
-   * Validates ACME configuration options
-   * 
-   * @param acmeOptions The ACME options to validate
-   * @returns An object with validation result and error message if invalid
-   */
-  public static validateAcmeOptions(acmeOptions: IAcmeOptions): { isValid: boolean; error?: string } {
-    if (!acmeOptions) {
-      return { isValid: false, error: 'ACME options cannot be null or undefined' };
-    }
-
-    if (acmeOptions.enabled) {
-      if (!acmeOptions.accountEmail) {
-        return { isValid: false, error: 'Account email is required when ACME is enabled' };
-      }
-
-      if (!this.isValidEmail(acmeOptions.accountEmail)) {
-        return { isValid: false, error: `Invalid email: ${acmeOptions.accountEmail}` };
-      }
-
-      if (acmeOptions.port && !this.isValidPort(acmeOptions.port)) {
-        return { isValid: false, error: `Invalid ACME port: ${acmeOptions.port}` };
-      }
-
-      if (acmeOptions.httpsRedirectPort && !this.isValidPort(acmeOptions.httpsRedirectPort)) {
-        return { isValid: false, error: `Invalid HTTPS redirect port: ${acmeOptions.httpsRedirectPort}` };
-      }
-
-      if (acmeOptions.renewThresholdDays && acmeOptions.renewThresholdDays < 1) {
-        return { isValid: false, error: 'Renew threshold days must be greater than 0' };
-      }
-
-      if (acmeOptions.renewCheckIntervalHours && acmeOptions.renewCheckIntervalHours < 1) {
-        return { isValid: false, error: 'Renew check interval hours must be greater than 0' };
-      }
-    }
-
-    return { isValid: true };
-  }
-
-  /**
-   * Validates a port number
-   * 
-   * @param port The port to validate
-   * @returns true if the port is valid, false otherwise
-   */
-  public static isValidPort(port: number): boolean {
-    return typeof port === 'number' && port > 0 && port <= 65535 && Number.isInteger(port);
-  }
-
-  /**
-   * Validates a domain name
-   * 
-   * @param domain The domain name to validate
-   * @returns true if the domain name is valid, false otherwise
-   */
-  public static isValidDomainName(domain: string): boolean {
-    if (!domain || typeof domain !== 'string') {
-      return false;
-    }
-
-    // Wildcard domain check (*.example.com)
-    if (domain.startsWith('*.')) {
-      domain = domain.substring(2);
-    }
-
-    // Simple domain validation pattern
-    const domainPattern = /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
-    return domainPattern.test(domain);
-  }
-
-  /**
-   * Validates an email address
-   * 
-   * @param email The email to validate
-   * @returns true if the email is valid, false otherwise
-   */
-  public static isValidEmail(email: string): boolean {
-    if (!email || typeof email !== 'string') {
-      return false;
-    }
-    
-    // Basic email validation pattern
-    const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-    return emailPattern.test(email);
-  }
-
-  /**
-   * Validates a certificate format (PEM)
-   * 
-   * @param cert The certificate content to validate
-   * @returns true if the certificate appears to be in PEM format, false otherwise
-   */
-  public static isValidCertificate(cert: string): boolean {
-    if (!cert || typeof cert !== 'string') {
-      return false;
-    }
-    
-    return cert.includes('-----BEGIN CERTIFICATE-----') && 
-           cert.includes('-----END CERTIFICATE-----');
-  }
-
-  /**
-   * Validates a private key format (PEM)
-   * 
-   * @param key The private key content to validate
-   * @returns true if the key appears to be in PEM format, false otherwise
-   */
-  public static isValidPrivateKey(key: string): boolean {
-    if (!key || typeof key !== 'string') {
-      return false;
-    }
-    
-    return key.includes('-----BEGIN PRIVATE KEY-----') && 
-           key.includes('-----END PRIVATE KEY-----');
-  }
-}

ts/core/utils/websocket-utils.ts

@@ -1,33 +0,0 @@
-/**
- * WebSocket utility functions
- * 
- * This module provides smartproxy-specific WebSocket utilities
- * and re-exports protocol utilities from the protocols module
- */
-
-// Import and re-export from protocols
-import { getMessageSize as protocolGetMessageSize, toBuffer as protocolToBuffer } from '../../protocols/websocket/index.js';
-export type { RawData } from '../../protocols/websocket/index.js';
-
-/**
- * Get the length of a WebSocket message regardless of its type
- * (handles all possible WebSocket message data types)
- * 
- * @param data - The data message from WebSocket (could be any RawData type)
- * @returns The length of the data in bytes
- */
-export function getMessageSize(data: import('../../protocols/websocket/index.js').RawData): number {
-  // Delegate to protocol implementation
-  return protocolGetMessageSize(data);
-}
-
-/**
- * Convert any raw WebSocket data to Buffer for consistent handling
- * 
- * @param data - The data message from WebSocket (could be any RawData type)
- * @returns A Buffer containing the data
- */
-export function toBuffer(data: import('../../protocols/websocket/index.js').RawData): Buffer {
-  // Delegate to protocol implementation
-  return protocolToBuffer(data);
-}

ts/detection/detectors/http-detector.ts

@@ -1,127 +0,0 @@
-/**
- * HTTP Protocol Detector
- * 
- * Simplified HTTP detection using the new architecture
- */
-
-import type { IProtocolDetector } from '../models/interfaces.js';
-import type { IDetectionResult, IDetectionOptions } from '../models/detection-types.js';
-import type { IProtocolDetectionResult, IConnectionContext } from '../../protocols/common/types.js';
-import type { THttpMethod } from '../../protocols/http/index.js';
-import { QuickProtocolDetector } from './quick-detector.js';
-import { RoutingExtractor } from './routing-extractor.js';
-import { DetectionFragmentManager } from '../utils/fragment-manager.js';
-import { HttpParser } from '../../protocols/http/parser.js';
-
-/**
- * Simplified HTTP detector
- */
-export class HttpDetector implements IProtocolDetector {
-  private quickDetector = new QuickProtocolDetector();
-  private fragmentManager: DetectionFragmentManager;
-  
-  constructor(fragmentManager?: DetectionFragmentManager) {
-    this.fragmentManager = fragmentManager || new DetectionFragmentManager();
-  }
-  
-  /**
-   * Check if buffer can be handled by this detector
-   */
-  canHandle(buffer: Buffer): boolean {
-    const result = this.quickDetector.quickDetect(buffer);
-    return result.protocol === 'http' && result.confidence > 50;
-  }
-  
-  /**
-   * Get minimum bytes needed for detection
-   */
-  getMinimumBytes(): number {
-    return 4; // "GET " minimum
-  }
-  
-  /**
-   * Detect HTTP protocol from buffer
-   */
-  detect(buffer: Buffer, options?: IDetectionOptions): IDetectionResult | null {
-    // Quick detection first
-    const quickResult = this.quickDetector.quickDetect(buffer);
-    
-    if (quickResult.protocol !== 'http' || quickResult.confidence < 50) {
-      return null;
-    }
-    
-    // Check if we have complete headers first
-    const headersEnd = buffer.indexOf('\r\n\r\n');
-    const isComplete = headersEnd !== -1;
-    
-    // Extract routing information
-    const routing = RoutingExtractor.extract(buffer, 'http');
-    
-    // Extract headers if requested and we have complete headers
-    let headers: Record<string, string> | undefined;
-    if (options?.extractFullHeaders && isComplete) {
-      const headerSection = buffer.slice(0, headersEnd).toString();
-      const lines = headerSection.split('\r\n');
-      if (lines.length > 1) {
-        // Skip the request line and parse headers
-        headers = HttpParser.parseHeaders(lines.slice(1));
-      }
-    }
-    
-    // If we don't need full headers and we have complete headers, we can return early
-    if (quickResult.confidence >= 95 && !options?.extractFullHeaders && isComplete) {
-      return {
-        protocol: 'http',
-        connectionInfo: { 
-          protocol: 'http',
-          method: quickResult.metadata?.method as THttpMethod,
-          domain: routing?.domain,
-          path: routing?.path
-        },
-        isComplete: true
-      };
-    }
-    
-    return {
-      protocol: 'http',
-      connectionInfo: {
-        protocol: 'http',
-        domain: routing?.domain,
-        path: routing?.path,
-        method: quickResult.metadata?.method as THttpMethod,
-        headers: headers
-      },
-      isComplete,
-      bytesNeeded: isComplete ? undefined : buffer.length + 512 // Need more for headers
-    };
-  }
-  
-  /**
-   * Handle fragmented detection
-   */
-  detectWithContext(
-    buffer: Buffer,
-    context: IConnectionContext,
-    options?: IDetectionOptions
-  ): IDetectionResult | null {
-    const handler = this.fragmentManager.getHandler('http');
-    const connectionId = DetectionFragmentManager.createConnectionId(context);
-    
-    // Add fragment
-    const result = handler.addFragment(connectionId, buffer);
-    
-    if (result.error) {
-      handler.complete(connectionId);
-      return null;
-    }
-    
-    // Try detection on accumulated buffer
-    const detectResult = this.detect(result.buffer!, options);
-    
-    if (detectResult && detectResult.isComplete) {
-      handler.complete(connectionId);
-    }
-    
-    return detectResult;
-  }
-}

ts/detection/detectors/quick-detector.ts

@@ -1,148 +0,0 @@
-/**
- * Quick Protocol Detector
- * 
- * Lightweight protocol identification based on minimal bytes
- * No parsing, just identification
- */
-
-import type { IProtocolDetector, IProtocolDetectionResult } from '../../protocols/common/types.js';
-import { TlsRecordType } from '../../protocols/tls/index.js';
-import { HttpParser } from '../../protocols/http/index.js';
-
-/**
- * Quick protocol detector for fast identification
- */
-export class QuickProtocolDetector implements IProtocolDetector {
-  /**
-   * Check if this detector can handle the data
-   */
-  canHandle(data: Buffer): boolean {
-    return data.length >= 1;
-  }
-  
-  /**
-   * Perform quick detection based on first few bytes
-   */
-  quickDetect(data: Buffer): IProtocolDetectionResult {
-    if (data.length === 0) {
-      return {
-        protocol: 'unknown',
-        confidence: 0,
-        requiresMoreData: true
-      };
-    }
-    
-    // Check for TLS
-    const tlsResult = this.checkTls(data);
-    if (tlsResult.confidence > 80) {
-      return tlsResult;
-    }
-    
-    // Check for HTTP
-    const httpResult = this.checkHttp(data);
-    if (httpResult.confidence > 80) {
-      return httpResult;
-    }
-    
-    // Need more data or unknown
-    return {
-      protocol: 'unknown',
-      confidence: 0,
-      requiresMoreData: data.length < 20
-    };
-  }
-  
-  /**
-   * Check if data looks like TLS
-   */
-  private checkTls(data: Buffer): IProtocolDetectionResult {
-    if (data.length < 3) {
-      return {
-        protocol: 'tls',
-        confidence: 0,
-        requiresMoreData: true
-      };
-    }
-    
-    const firstByte = data[0];
-    const secondByte = data[1];
-    
-    // Check for valid TLS record type
-    const validRecordTypes = [
-      TlsRecordType.CHANGE_CIPHER_SPEC,
-      TlsRecordType.ALERT,
-      TlsRecordType.HANDSHAKE,
-      TlsRecordType.APPLICATION_DATA,
-      TlsRecordType.HEARTBEAT
-    ];
-    
-    if (!validRecordTypes.includes(firstByte)) {
-      return {
-        protocol: 'tls',
-        confidence: 0
-      };
-    }
-    
-    // Check TLS version byte (0x03 for all TLS/SSL versions)
-    if (secondByte !== 0x03) {
-      return {
-        protocol: 'tls',
-        confidence: 0
-      };
-    }
-    
-    // High confidence it's TLS
-    return {
-      protocol: 'tls',
-      confidence: 95,
-      metadata: {
-        recordType: firstByte
-      }
-    };
-  }
-  
-  /**
-   * Check if data looks like HTTP
-   */
-  private checkHttp(data: Buffer): IProtocolDetectionResult {
-    if (data.length < 3) {
-      return {
-        protocol: 'http',
-        confidence: 0,
-        requiresMoreData: true
-      };
-    }
-    
-    // Quick check for HTTP methods
-    const start = data.subarray(0, Math.min(10, data.length)).toString('ascii');
-    
-    // Check common HTTP methods
-    const httpMethods = ['GET ', 'POST ', 'PUT ', 'DELETE ', 'HEAD ', 'OPTIONS', 'PATCH ', 'CONNECT', 'TRACE '];
-    for (const method of httpMethods) {
-      if (start.startsWith(method)) {
-        return {
-          protocol: 'http',
-          confidence: 95,
-          metadata: {
-            method: method.trim()
-          }
-        };
-      }
-    }
-    
-    // Check if it might be HTTP but need more data
-    if (HttpParser.isPrintableAscii(data, Math.min(20, data.length))) {
-      // Could be HTTP, but not sure
-      return {
-        protocol: 'http',
-        confidence: 30,
-        requiresMoreData: data.length < 20
-      };
-    }
-    
-    return {
-      protocol: 'http',
-      confidence: 0
-    };
-  }
-}

ts/detection/detectors/routing-extractor.ts

@@ -1,147 +0,0 @@
-/**
- * Routing Information Extractor
- * 
- * Extracts minimal routing information from protocols
- * without full parsing
- */
-
-import type { IRoutingInfo, IConnectionContext, TProtocolType } from '../../protocols/common/types.js';
-import { SniExtraction } from '../../protocols/tls/sni/sni-extraction.js';
-import { HttpParser } from '../../protocols/http/index.js';
-
-/**
- * Extracts routing information from protocol data
- */
-export class RoutingExtractor {
-  /**
-   * Extract routing info based on protocol type
-   */
-  static extract(
-    data: Buffer, 
-    protocol: TProtocolType,
-    context?: IConnectionContext
-  ): IRoutingInfo | null {
-    switch (protocol) {
-      case 'tls':
-      case 'https':
-        return this.extractTlsRouting(data, context);
-      
-      case 'http':
-        return this.extractHttpRouting(data);
-      
-      default:
-        return null;
-    }
-  }
-  
-  /**
-   * Extract routing from TLS ClientHello (SNI)
-   */
-  private static extractTlsRouting(
-    data: Buffer,
-    context?: IConnectionContext
-  ): IRoutingInfo | null {
-    try {
-      // Quick SNI extraction without full parsing
-      const sni = SniExtraction.extractSNI(data);
-      
-      if (sni) {
-        return {
-          domain: sni,
-          protocol: 'tls',
-          port: 443  // Default HTTPS port
-        };
-      }
-      
-      return null;
-    } catch (error) {
-      // Extraction failed, return null
-      return null;
-    }
-  }
-  
-  /**
-   * Extract routing from HTTP headers (Host header)
-   */
-  private static extractHttpRouting(data: Buffer): IRoutingInfo | null {
-    try {
-      // Look for first line
-      const firstLineEnd = data.indexOf('\n');
-      if (firstLineEnd === -1) {
-        return null;
-      }
-      
-      // Parse request line
-      const firstLine = data.subarray(0, firstLineEnd).toString('ascii').trim();
-      const requestLine = HttpParser.parseRequestLine(firstLine);
-      
-      if (!requestLine) {
-        return null;
-      }
-      
-      // Look for Host header
-      let pos = firstLineEnd + 1;
-      const maxSearch = Math.min(data.length, 4096); // Don't search too far
-      
-      while (pos < maxSearch) {
-        const lineEnd = data.indexOf('\n', pos);
-        if (lineEnd === -1) break;
-        
-        const line = data.subarray(pos, lineEnd).toString('ascii').trim();
-        
-        // Empty line means end of headers
-        if (line.length === 0) break;
-        
-        // Check for Host header
-        if (line.toLowerCase().startsWith('host:')) {
-          const hostValue = line.substring(5).trim();
-          const domain = HttpParser.extractDomainFromHost(hostValue);
-          
-          return {
-            domain,
-            path: requestLine.path,
-            protocol: 'http',
-            port: 80  // Default HTTP port
-          };
-        }
-        
-        pos = lineEnd + 1;
-      }
-      
-      // No Host header found, but we have the path
-      return {
-        path: requestLine.path,
-        protocol: 'http',
-        port: 80
-      };
-    } catch (error) {
-      // Extraction failed
-      return null;
-    }
-  }
-  
-  /**
-   * Try to extract domain from any protocol
-   */
-  static extractDomain(data: Buffer, hint?: TProtocolType): string | null {
-    // If we have a hint, use it
-    if (hint) {
-      const routing = this.extract(data, hint);
-      return routing?.domain || null;
-    }
-    
-    // Try TLS first (more specific)
-    const tlsRouting = this.extractTlsRouting(data);
-    if (tlsRouting?.domain) {
-      return tlsRouting.domain;
-    }
-    
-    // Try HTTP
-    const httpRouting = this.extractHttpRouting(data);
-    if (httpRouting?.domain) {
-      return httpRouting.domain;
-    }
-    
-    return null;
-  }
-}

ts/detection/detectors/tls-detector.ts

@@ -1,223 +0,0 @@
-/**
- * TLS protocol detector
- */
-
-// TLS detector doesn't need plugins imports
-import type { IProtocolDetector } from '../models/interfaces.js';
-import type { IDetectionResult, IDetectionOptions, IConnectionInfo } from '../models/detection-types.js';
-import { readUInt16BE } from '../utils/buffer-utils.js';
-import { tlsVersionToString } from '../utils/parser-utils.js';
-
-// Import from protocols
-import { TlsRecordType, TlsHandshakeType, TlsExtensionType } from '../../protocols/tls/index.js';
-
-// Import TLS utilities for SNI extraction from protocols
-import { SniExtraction } from '../../protocols/tls/sni/sni-extraction.js';
-import { ClientHelloParser } from '../../protocols/tls/sni/client-hello-parser.js';
-
-/**
- * TLS detector implementation
- */
-export class TlsDetector implements IProtocolDetector {
-  /**
-   * Minimum bytes needed to identify TLS (record header)
-   */
-  private static readonly MIN_TLS_HEADER_SIZE = 5;
-  
-  
-  /**
-   * Detect TLS protocol from buffer
-   */
-  detect(buffer: Buffer, options?: IDetectionOptions): IDetectionResult | null {
-    // Check if buffer is too small
-    if (buffer.length < TlsDetector.MIN_TLS_HEADER_SIZE) {
-      return null;
-    }
-    
-    // Check if this is a TLS record
-    if (!this.isTlsRecord(buffer)) {
-      return null;
-    }
-    
-    // Extract basic TLS info
-    const recordType = buffer[0];
-    const tlsMajor = buffer[1];
-    const tlsMinor = buffer[2];
-    const recordLength = readUInt16BE(buffer, 3);
-    
-    // Initialize connection info
-    const connectionInfo: IConnectionInfo = {
-      protocol: 'tls',
-      tlsVersion: tlsVersionToString(tlsMajor, tlsMinor) || undefined
-    };
-    
-    // If it's a handshake, try to extract more info
-    if (recordType === TlsRecordType.HANDSHAKE && buffer.length >= 6) {
-      const handshakeType = buffer[5];
-      
-      // For ClientHello, extract SNI and other info
-      if (handshakeType === TlsHandshakeType.CLIENT_HELLO) {
-        // Check if we have the complete handshake
-        const totalRecordLength = recordLength + 5; // Including TLS header
-        if (buffer.length >= totalRecordLength) {
-          // Extract SNI using existing logic
-          const sni = SniExtraction.extractSNI(buffer);
-          if (sni) {
-            connectionInfo.domain = sni;
-            connectionInfo.sni = sni;
-          }
-          
-          // Parse ClientHello for additional info
-          const parseResult = ClientHelloParser.parseClientHello(buffer);
-          if (parseResult.isValid) {
-            // Extract ALPN if present
-            const alpnExtension = parseResult.extensions.find(
-              ext => ext.type === TlsExtensionType.APPLICATION_LAYER_PROTOCOL_NEGOTIATION
-            );
-            
-            if (alpnExtension) {
-              connectionInfo.alpn = this.parseAlpnExtension(alpnExtension.data);
-            }
-            
-            // Store cipher suites if needed
-            if (parseResult.cipherSuites && options?.extractFullHeaders) {
-              connectionInfo.cipherSuites = this.parseCipherSuites(parseResult.cipherSuites);
-            }
-          }
-          
-          // Return complete result
-          return {
-            protocol: 'tls',
-            connectionInfo,
-            remainingBuffer: buffer.length > totalRecordLength 
-              ? buffer.subarray(totalRecordLength) 
-              : undefined,
-            isComplete: true
-          };
-        } else {
-          // Incomplete handshake
-          return {
-            protocol: 'tls',
-            connectionInfo,
-            isComplete: false,
-            bytesNeeded: totalRecordLength
-          };
-        }
-      }
-    }
-    
-    // For other TLS record types, just return basic info
-    return {
-      protocol: 'tls',
-      connectionInfo,
-      isComplete: true,
-      remainingBuffer: buffer.length > recordLength + 5 
-        ? buffer.subarray(recordLength + 5) 
-        : undefined
-    };
-  }
-  
-  /**
-   * Check if buffer can be handled by this detector
-   */
-  canHandle(buffer: Buffer): boolean {
-    return buffer.length >= TlsDetector.MIN_TLS_HEADER_SIZE && 
-           this.isTlsRecord(buffer);
-  }
-  
-  /**
-   * Get minimum bytes needed for detection
-   */
-  getMinimumBytes(): number {
-    return TlsDetector.MIN_TLS_HEADER_SIZE;
-  }
-  
-  /**
-   * Check if buffer contains a valid TLS record
-   */
-  private isTlsRecord(buffer: Buffer): boolean {
-    const recordType = buffer[0];
-    
-    // Check for valid record type
-    const validTypes = [
-      TlsRecordType.CHANGE_CIPHER_SPEC,
-      TlsRecordType.ALERT,
-      TlsRecordType.HANDSHAKE,
-      TlsRecordType.APPLICATION_DATA,
-      TlsRecordType.HEARTBEAT
-    ];
-    
-    if (!validTypes.includes(recordType)) {
-      return false;
-    }
-    
-    // Check TLS version bytes (should be 0x03 0x0X)
-    if (buffer[1] !== 0x03) {
-      return false;
-    }
-    
-    // Check record length is reasonable
-    const recordLength = readUInt16BE(buffer, 3);
-    if (recordLength > 16384) { // Max TLS record size
-      return false;
-    }
-    
-    return true;
-  }
-  
-  /**
-   * Parse ALPN extension data
-   */
-  private parseAlpnExtension(data: Buffer): string[] {
-    const protocols: string[] = [];
-    
-    if (data.length < 2) {
-      return protocols;
-    }
-    
-    const listLength = readUInt16BE(data, 0);
-    let offset = 2;
-    
-    while (offset < Math.min(2 + listLength, data.length)) {
-      const protoLength = data[offset];
-      offset++;
-      
-      if (offset + protoLength <= data.length) {
-        const protocol = data.subarray(offset, offset + protoLength).toString('ascii');
-        protocols.push(protocol);
-        offset += protoLength;
-      } else {
-        break;
-      }
-    }
-    
-    return protocols;
-  }
-  
-  /**
-   * Parse cipher suites
-   */
-  private parseCipherSuites(cipherData: Buffer): number[] {
-    const suites: number[] = [];
-    
-    for (let i = 0; i < cipherData.length - 1; i += 2) {
-      const suite = readUInt16BE(cipherData, i);
-      suites.push(suite);
-    }
-    
-    return suites;
-  }
-  
-  /**
-   * Detect with context for fragmented data
-   */
-  detectWithContext(
-    buffer: Buffer,
-    _context: { sourceIp?: string; sourcePort?: number; destIp?: string; destPort?: number },
-    options?: IDetectionOptions
-  ): IDetectionResult | null {
-    // This method is deprecated - TLS detection should use the fragment manager
-    // from the parent detector system, not maintain its own fragments
-    return this.detect(buffer, options);
-  }
-}

ts/detection/index.ts

@@ -1,25 +0,0 @@
-/**
- * Centralized Protocol Detection Module
- * 
- * This module provides unified protocol detection capabilities for
- * both TLS and HTTP protocols, extracting connection information
- * without consuming the data stream.
- */
-
-// Main detector
-export * from './protocol-detector.js';
-
-// Models
-export * from './models/detection-types.js';
-export * from './models/interfaces.js';
-
-// Individual detectors
-export * from './detectors/tls-detector.js';
-export * from './detectors/http-detector.js';
-export * from './detectors/quick-detector.js';
-export * from './detectors/routing-extractor.js';
-
-// Utilities
-export * from './utils/buffer-utils.js';
-export * from './utils/parser-utils.js';
-export * from './utils/fragment-manager.js';

ts/detection/models/detection-types.ts

@@ -1,102 +0,0 @@
-/**
- * Type definitions for protocol detection
- */
-
-/**
- * Supported protocol types that can be detected
- */
-export type TProtocolType = 'tls' | 'http' | 'unknown';
-
-/**
- * HTTP method types
- */
-export type THttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
-
-/**
- * TLS version identifiers
- */
-export type TTlsVersion = 'SSLv3' | 'TLSv1.0' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
-
-/**
- * Connection information extracted from protocol detection
- */
-export interface IConnectionInfo {
-  /**
-   * The detected protocol type
-   */
-  protocol: TProtocolType;
-  
-  /**
-   * Domain/hostname extracted from the connection
-   * - For TLS: from SNI extension
-   * - For HTTP: from Host header
-   */
-  domain?: string;
-  
-  /**
-   * HTTP-specific fields
-   */
-  method?: THttpMethod;
-  path?: string;
-  httpVersion?: string;
-  headers?: Record<string, string>;
-  
-  /**
-   * TLS-specific fields
-   */
-  tlsVersion?: TTlsVersion;
-  sni?: string;
-  alpn?: string[];
-  cipherSuites?: number[];
-}
-
-/**
- * Result of protocol detection
- */
-export interface IDetectionResult {
-  /**
-   * The detected protocol type
-   */
-  protocol: TProtocolType;
-  
-  /**
-   * Extracted connection information
-   */
-  connectionInfo: IConnectionInfo;
-  
-  /**
-   * Any remaining buffer data after detection headers
-   * This can be used to continue processing the stream
-   */
-  remainingBuffer?: Buffer;
-  
-  /**
-   * Whether the detection is complete or needs more data
-   */
-  isComplete: boolean;
-  
-  /**
-   * Minimum bytes needed for complete detection (if incomplete)
-   */
-  bytesNeeded?: number;
-}
-
-/**
- * Options for protocol detection
- */
-export interface IDetectionOptions {
-  /**
-   * Maximum bytes to buffer for detection (default: 8192)
-   */
-  maxBufferSize?: number;
-  
-  /**
-   * Timeout for detection in milliseconds (default: 5000)
-   */
-  timeout?: number;
-  
-  /**
-   * Whether to extract full headers or just essential info
-   */
-  extractFullHeaders?: boolean;
-}

ts/detection/models/interfaces.ts

@@ -1,115 +0,0 @@
-/**
- * Interface definitions for protocol detection components
- */
-
-import type { IDetectionResult, IDetectionOptions } from './detection-types.js';
-
-/**
- * Interface for protocol detectors
- */
-export interface IProtocolDetector {
-  /**
-   * Detect protocol from buffer data
-   * @param buffer The buffer to analyze
-   * @param options Detection options
-   * @returns Detection result or null if protocol cannot be determined
-   */
-  detect(buffer: Buffer, options?: IDetectionOptions): IDetectionResult | null;
-  
-  /**
-   * Check if buffer potentially contains this protocol
-   * @param buffer The buffer to check
-   * @returns True if buffer might contain this protocol
-   */
-  canHandle(buffer: Buffer): boolean;
-  
-  /**
-   * Get the minimum bytes needed for detection
-   */
-  getMinimumBytes(): number;
-}
-
-/**
- * Interface for connection tracking during fragmented detection
- */
-export interface IConnectionTracker {
-  /**
-   * Connection identifier
-   */
-  id: string;
-  
-  /**
-   * Accumulated buffer data
-   */
-  buffer: Buffer;
-  
-  /**
-   * Timestamp of first data
-   */
-  startTime: number;
-  
-  /**
-   * Current detection state
-   */
-  state: 'detecting' | 'complete' | 'failed';
-  
-  /**
-   * Partial detection result (if any)
-   */
-  partialResult?: Partial<IDetectionResult>;
-}
-
-/**
- * Interface for buffer accumulator (handles fragmented data)
- */
-export interface IBufferAccumulator {
-  /**
-   * Add data to accumulator
-   */
-  append(data: Buffer): void;
-  
-  /**
-   * Get accumulated buffer
-   */
-  getBuffer(): Buffer;
-  
-  /**
-   * Get buffer length
-   */
-  length(): number;
-  
-  /**
-   * Clear accumulated data
-   */
-  clear(): void;
-  
-  /**
-   * Check if accumulator has enough data
-   */
-  hasMinimumBytes(minBytes: number): boolean;
-}
-
-/**
- * Detection events
- */
-export interface IDetectionEvents {
-  /**
-   * Emitted when protocol is successfully detected
-   */
-  detected: (result: IDetectionResult) => void;
-  
-  /**
-   * Emitted when detection fails
-   */
-  failed: (error: Error) => void;
-  
-  /**
-   * Emitted when detection times out
-   */
-  timeout: () => void;
-  
-  /**
-   * Emitted when more data is needed
-   */
-  needMoreData: (bytesNeeded: number) => void;
-}

ts/detection/protocol-detector.ts

@@ -1,319 +0,0 @@
-/**
- * Protocol Detector
- * 
- * Simplified protocol detection using the new architecture
- */
-
-import type { IDetectionResult, IDetectionOptions } from './models/detection-types.js';
-import type { IConnectionContext } from '../protocols/common/types.js';
-import { TlsDetector } from './detectors/tls-detector.js';
-import { HttpDetector } from './detectors/http-detector.js';
-import { DetectionFragmentManager } from './utils/fragment-manager.js';
-
-/**
- * Main protocol detector class
- */
-export class ProtocolDetector {
-  private static instance: ProtocolDetector;
-  private fragmentManager: DetectionFragmentManager;
-  private tlsDetector: TlsDetector;
-  private httpDetector: HttpDetector;
-  private connectionProtocols: Map<string, { protocol: 'tls' | 'http'; createdAt: number }> = new Map();
-
-  constructor() {
-    this.fragmentManager = new DetectionFragmentManager();
-    this.tlsDetector = new TlsDetector();
-    this.httpDetector = new HttpDetector(this.fragmentManager);
-  }
-  
-  private static getInstance(): ProtocolDetector {
-    if (!this.instance) {
-      this.instance = new ProtocolDetector();
-    }
-    return this.instance;
-  }
-  
-  /**
-   * Detect protocol from buffer data
-   */
-  static async detect(buffer: Buffer, options?: IDetectionOptions): Promise<IDetectionResult> {
-    return this.getInstance().detectInstance(buffer, options);
-  }
-  
-  private async detectInstance(buffer: Buffer, options?: IDetectionOptions): Promise<IDetectionResult> {
-    // Quick sanity check
-    if (!buffer || buffer.length === 0) {
-      return {
-        protocol: 'unknown',
-        connectionInfo: { protocol: 'unknown' },
-        isComplete: true
-      };
-    }
-    
-    // Try TLS detection first (more specific)
-    if (this.tlsDetector.canHandle(buffer)) {
-      const tlsResult = this.tlsDetector.detect(buffer, options);
-      if (tlsResult) {
-        return tlsResult;
-      }
-    }
-    
-    // Try HTTP detection
-    if (this.httpDetector.canHandle(buffer)) {
-      const httpResult = this.httpDetector.detect(buffer, options);
-      if (httpResult) {
-        return httpResult;
-      }
-    }
-    
-    // Neither TLS nor HTTP
-    return {
-      protocol: 'unknown',
-      connectionInfo: { protocol: 'unknown' },
-      isComplete: true
-    };
-  }
-  
-  /**
-   * Detect protocol with connection tracking for fragmented data
-   * @deprecated Use detectWithContext instead
-   */
-  static async detectWithConnectionTracking(
-    buffer: Buffer,
-    connectionId: string,
-    options?: IDetectionOptions
-  ): Promise<IDetectionResult> {
-    // Convert connection ID to context
-    const context: IConnectionContext = {
-      id: connectionId,
-      sourceIp: 'unknown',
-      sourcePort: 0,
-      destIp: 'unknown',
-      destPort: 0,
-      timestamp: Date.now()
-    };
-    
-    return this.getInstance().detectWithContextInstance(buffer, context, options);
-  }
-  
-  /**
-   * Detect protocol with connection context for fragmented data
-   */
-  static async detectWithContext(
-    buffer: Buffer,
-    context: IConnectionContext,
-    options?: IDetectionOptions
-  ): Promise<IDetectionResult> {
-    return this.getInstance().detectWithContextInstance(buffer, context, options);
-  }
-  
-  private async detectWithContextInstance(
-    buffer: Buffer,
-    context: IConnectionContext,
-    options?: IDetectionOptions
-  ): Promise<IDetectionResult> {
-    // Quick sanity check
-    if (!buffer || buffer.length === 0) {
-      return {
-        protocol: 'unknown',
-        connectionInfo: { protocol: 'unknown' },
-        isComplete: true
-      };
-    }
-    
-    const connectionId = DetectionFragmentManager.createConnectionId(context);
-    
-    // Check if we already know the protocol for this connection
-    const knownEntry = this.connectionProtocols.get(connectionId);
-    const knownProtocol = knownEntry?.protocol;
-
-    if (knownProtocol === 'http') {
-      const result = this.httpDetector.detectWithContext(buffer, context, options);
-      if (result) {
-        if (result.isComplete) {
-          this.connectionProtocols.delete(connectionId);
-        }
-        return result;
-      }
-    } else if (knownProtocol === 'tls') {
-      // Handle TLS with fragment accumulation
-      const handler = this.fragmentManager.getHandler('tls');
-      const fragmentResult = handler.addFragment(connectionId, buffer);
-      
-      if (fragmentResult.error) {
-        handler.complete(connectionId);
-        this.connectionProtocols.delete(connectionId);
-        return {
-          protocol: 'unknown',
-          connectionInfo: { protocol: 'unknown' },
-          isComplete: true
-        };
-      }
-      
-      const result = this.tlsDetector.detect(fragmentResult.buffer!, options);
-      if (result) {
-        if (result.isComplete) {
-          handler.complete(connectionId);
-          this.connectionProtocols.delete(connectionId);
-        }
-        return result;
-      }
-    }
-    
-    // If we don't know the protocol yet, try to detect it
-    if (!knownProtocol) {
-      // First peek to determine protocol type
-      if (this.tlsDetector.canHandle(buffer)) {
-        this.connectionProtocols.set(connectionId, { protocol: 'tls', createdAt: Date.now() });
-        // Handle TLS with fragment accumulation
-        const handler = this.fragmentManager.getHandler('tls');
-        const fragmentResult = handler.addFragment(connectionId, buffer);
-        
-        if (fragmentResult.error) {
-          handler.complete(connectionId);
-          this.connectionProtocols.delete(connectionId);
-          return {
-            protocol: 'unknown',
-            connectionInfo: { protocol: 'unknown' },
-            isComplete: true
-          };
-        }
-        
-        const result = this.tlsDetector.detect(fragmentResult.buffer!, options);
-        if (result) {
-          if (result.isComplete) {
-            handler.complete(connectionId);
-            this.connectionProtocols.delete(connectionId);
-          }
-          return result;
-        }
-      }
-      
-      if (this.httpDetector.canHandle(buffer)) {
-        this.connectionProtocols.set(connectionId, { protocol: 'http', createdAt: Date.now() });
-        const result = this.httpDetector.detectWithContext(buffer, context, options);
-        if (result) {
-          if (result.isComplete) {
-            this.connectionProtocols.delete(connectionId);
-          }
-          return result;
-        }
-      }
-    }
-    
-    // Can't determine protocol
-    return {
-      protocol: 'unknown',
-      connectionInfo: { protocol: 'unknown' },
-      isComplete: false,
-      bytesNeeded: Math.max(
-        this.tlsDetector.getMinimumBytes(),
-        this.httpDetector.getMinimumBytes()
-      )
-    };
-  }
-  
-  /**
-   * Clean up resources
-   */
-  static cleanup(): void {
-    this.getInstance().cleanupInstance();
-  }
-  
-  private cleanupInstance(): void {
-    this.fragmentManager.cleanup();
-    // Remove stale connectionProtocols entries (abandoned handshakes, port scanners)
-    const maxAge = 30_000; // 30 seconds
-    const now = Date.now();
-    for (const [id, entry] of this.connectionProtocols) {
-      if (now - entry.createdAt > maxAge) {
-        this.connectionProtocols.delete(id);
-      }
-    }
-  }
-  
-  /**
-   * Destroy detector instance
-   */
-  static destroy(): void {
-    this.getInstance().destroyInstance();
-    this.instance = null as any;
-  }
-  
-  private destroyInstance(): void {
-    this.fragmentManager.destroy();
-    this.connectionProtocols.clear();
-  }
-  
-  /**
-   * Clean up old connection tracking entries
-   * 
-   * @param _maxAge Maximum age in milliseconds (default: 30 seconds)
-   */
-  static cleanupConnections(_maxAge: number = 30000): void {
-    this.getInstance().cleanupInstance();
-  }
-  
-  /**
-   * Clean up fragments for a specific connection
-   */
-  static cleanupConnection(context: IConnectionContext): void {
-    const instance = this.getInstance();
-    const connectionId = DetectionFragmentManager.createConnectionId(context);
-    
-    // Clean up both TLS and HTTP fragments for this connection
-    instance.fragmentManager.getHandler('tls').complete(connectionId);
-    instance.fragmentManager.getHandler('http').complete(connectionId);
-    
-    // Remove from connection protocols tracking
-    instance.connectionProtocols.delete(connectionId);
-  }
-  
-  /**
-   * Extract domain from connection info
-   */
-  static extractDomain(connectionInfo: any): string | undefined {
-    return connectionInfo.domain || connectionInfo.sni || connectionInfo.host;
-  }
-  
-  /**
-   * Create a connection ID from connection parameters
-   * @deprecated Use createConnectionContext instead
-   */
-  static createConnectionId(params: {
-    sourceIp?: string;
-    sourcePort?: number;
-    destIp?: string;
-    destPort?: number;
-    socketId?: string;
-  }): string {
-    // If socketId is provided, use it
-    if (params.socketId) {
-      return params.socketId;
-    }
-    
-    // Otherwise create from connection tuple
-    const { sourceIp = 'unknown', sourcePort = 0, destIp = 'unknown', destPort = 0 } = params;
-    return `${sourceIp}:${sourcePort}-${destIp}:${destPort}`;
-  }
-  
-  /**
-   * Create a connection context from parameters
-   */
-  static createConnectionContext(params: {
-    sourceIp?: string;
-    sourcePort?: number;
-    destIp?: string;
-    destPort?: number;
-    socketId?: string;
-  }): IConnectionContext {
-    return {
-      id: params.socketId,
-      sourceIp: params.sourceIp || 'unknown',
-      sourcePort: params.sourcePort || 0,
-      destIp: params.destIp || 'unknown',
-      destPort: params.destPort || 0,
-      timestamp: Date.now()
-    };
-  }
-}

ts/detection/utils/buffer-utils.ts

@@ -1,141 +0,0 @@
-/**
- * Buffer manipulation utilities for protocol detection
- */
-
-// Import from protocols
-import { HttpParser } from '../../protocols/http/index.js';
-
-/**
- * BufferAccumulator class for handling fragmented data
- */
-export class BufferAccumulator {
-  private chunks: Buffer[] = [];
-  private totalLength = 0;
-  
-  /**
-   * Append data to the accumulator
-   */
-  append(data: Buffer): void {
-    this.chunks.push(data);
-    this.totalLength += data.length;
-  }
-  
-  /**
-   * Get the accumulated buffer
-   */
-  getBuffer(): Buffer {
-    if (this.chunks.length === 0) {
-      return Buffer.alloc(0);
-    }
-    if (this.chunks.length === 1) {
-      return this.chunks[0];
-    }
-    return Buffer.concat(this.chunks, this.totalLength);
-  }
-  
-  /**
-   * Get current buffer length
-   */
-  length(): number {
-    return this.totalLength;
-  }
-  
-  /**
-   * Clear all accumulated data
-   */
-  clear(): void {
-    this.chunks = [];
-    this.totalLength = 0;
-  }
-  
-  /**
-   * Check if accumulator has minimum bytes
-   */
-  hasMinimumBytes(minBytes: number): boolean {
-    return this.totalLength >= minBytes;
-  }
-}
-
-/**
- * Read a big-endian 16-bit integer from buffer
- */
-export function readUInt16BE(buffer: Buffer, offset: number): number {
-  if (offset + 2 > buffer.length) {
-    throw new Error('Buffer too short for UInt16BE read');
-  }
-  return (buffer[offset] << 8) | buffer[offset + 1];
-}
-
-/**
- * Read a big-endian 24-bit integer from buffer
- */
-export function readUInt24BE(buffer: Buffer, offset: number): number {
-  if (offset + 3 > buffer.length) {
-    throw new Error('Buffer too short for UInt24BE read');
-  }
-  return (buffer[offset] << 16) | (buffer[offset + 1] << 8) | buffer[offset + 2];
-}
-
-/**
- * Find a byte sequence in a buffer
- */
-export function findSequence(buffer: Buffer, sequence: Buffer, startOffset = 0): number {
-  if (sequence.length === 0) {
-    return startOffset;
-  }
-  
-  const searchLength = buffer.length - sequence.length + 1;
-  for (let i = startOffset; i < searchLength; i++) {
-    let found = true;
-    for (let j = 0; j < sequence.length; j++) {
-      if (buffer[i + j] !== sequence[j]) {
-        found = false;
-        break;
-      }
-    }
-    if (found) {
-      return i;
-    }
-  }
-  return -1;
-}
-
-/**
- * Extract a line from buffer (up to CRLF or LF)
- */
-export function extractLine(buffer: Buffer, startOffset = 0): { line: string; nextOffset: number } | null {
-  // Delegate to protocol parser
-  return HttpParser.extractLine(buffer, startOffset);
-}
-
-/**
- * Check if buffer starts with a string (case-insensitive)
- */
-export function startsWithString(buffer: Buffer, str: string, offset = 0): boolean {
-  if (offset + str.length > buffer.length) {
-    return false;
-  }
-  
-  const bufferStr = buffer.slice(offset, offset + str.length).toString('utf8');
-  return bufferStr.toLowerCase() === str.toLowerCase();
-}
-
-/**
- * Safe buffer slice that doesn't throw on out-of-bounds
- */
-export function safeSlice(buffer: Buffer, start: number, end?: number): Buffer {
-  const safeStart = Math.max(0, Math.min(start, buffer.length));
-  const safeEnd = end === undefined 
-    ? buffer.length 
-    : Math.max(safeStart, Math.min(end, buffer.length));
-    
-  return buffer.slice(safeStart, safeEnd);
-}
-
-/**
- * Check if buffer contains printable ASCII
- */
-export function isPrintableAscii(buffer: Buffer, length?: number): boolean {
-  // Delegate to protocol parser
-  return HttpParser.isPrintableAscii(buffer, length);
-}

ts/detection/utils/fragment-manager.ts

@@ -1,64 +0,0 @@
-/**
- * Fragment Manager for Detection Module
- * 
- * Manages fragmented protocol data using the shared fragment handler
- */
-
-import { FragmentHandler, type IFragmentOptions } from '../../protocols/common/fragment-handler.js';
-import type { IConnectionContext } from '../../protocols/common/types.js';
-
-/**
- * Detection-specific fragment manager
- */
-export class DetectionFragmentManager {
-  private tlsFragments: FragmentHandler;
-  private httpFragments: FragmentHandler;
-  
-  constructor() {
-    // Configure fragment handlers with appropriate limits
-    const tlsOptions: IFragmentOptions = {
-      maxBufferSize: 16384,  // TLS record max size
-      timeout: 5000,
-      cleanupInterval: 30000
-    };
-    
-    const httpOptions: IFragmentOptions = {
-      maxBufferSize: 8192,   // HTTP header reasonable limit
-      timeout: 5000,
-      cleanupInterval: 30000
-    };
-    
-    this.tlsFragments = new FragmentHandler(tlsOptions);
-    this.httpFragments = new FragmentHandler(httpOptions);
-  }
-  
-  /**
-   * Get fragment handler for protocol type
-   */
-  getHandler(protocol: 'tls' | 'http'): FragmentHandler {
-    return protocol === 'tls' ? this.tlsFragments : this.httpFragments;
-  }
-  
-  /**
-   * Create connection ID from context
-   */
-  static createConnectionId(context: IConnectionContext): string {
-    return context.id || `${context.sourceIp}:${context.sourcePort}-${context.destIp}:${context.destPort}`;
-  }
-  
-  /**
-   * Clean up all handlers
-   */
-  cleanup(): void {
-    this.tlsFragments.cleanup();
-    this.httpFragments.cleanup();
-  }
-  
-  /**
-   * Destroy all handlers
-   */
-  destroy(): void {
-    this.tlsFragments.destroy();
-    this.httpFragments.destroy();
-  }
-}

ts/detection/utils/parser-utils.ts

@@ -1,77 +0,0 @@
-/**
- * Parser utilities for protocol detection
- * Now delegates to protocol modules for actual parsing
- */
-
-import type { THttpMethod, TTlsVersion } from '../models/detection-types.js';
-import { HttpParser, HTTP_METHODS, HTTP_VERSIONS } from '../../protocols/http/index.js';
-import { tlsVersionToString as protocolTlsVersionToString } from '../../protocols/tls/index.js';
-
-// Re-export constants for backward compatibility
-export { HTTP_METHODS, HTTP_VERSIONS };
-
-/**
- * Parse HTTP request line
- */
-export function parseHttpRequestLine(line: string): {
-  method: THttpMethod;
-  path: string;
-  version: string;
-} | null {
-  // Delegate to protocol parser
-  const result = HttpParser.parseRequestLine(line);
-  return result ? {
-    method: result.method as THttpMethod,
-    path: result.path,
-    version: result.version
-  } : null;
-}
-
-/**
- * Parse HTTP header line
- */
-export function parseHttpHeader(line: string): { name: string; value: string } | null {
-  // Delegate to protocol parser
-  return HttpParser.parseHeaderLine(line);
-}
-
-/**
- * Parse HTTP headers from lines
- */
-export function parseHttpHeaders(lines: string[]): Record<string, string> {
-  // Delegate to protocol parser
-  return HttpParser.parseHeaders(lines);
-}
-
-/**
- * Convert TLS version bytes to version string
- */
-export function tlsVersionToString(major: number, minor: number): TTlsVersion | null {
-  // Delegate to protocol parser
-  return protocolTlsVersionToString(major, minor) as TTlsVersion;
-}
-
-/**
- * Extract domain from Host header value
- */
-export function extractDomainFromHost(hostHeader: string): string {
-  // Delegate to protocol parser
-  return HttpParser.extractDomainFromHost(hostHeader);
-}
-
-/**
- * Validate domain name
- */
-export function isValidDomain(domain: string): boolean {
-  // Delegate to protocol parser
-  return HttpParser.isValidDomain(domain);
-}
-
-/**
- * Check if string is a valid HTTP method
- */
-export function isHttpMethod(str: string): str is THttpMethod {
-  // Delegate to protocol parser
-  return HttpParser.isHttpMethod(str) && (str as THttpMethod) !== undefined;
-}
-

ts/index.ts

@@ -11,18 +11,12 @@ export type { ISmartProxyOptions, IConnectionRecord, IRouteConfig, IRouteMatch,
 export type { TSmartProxyCertProvisionObject, ICertProvisionEventComms, ICertificateIssuedEvent, ICertificateFailedEvent } from './proxies/smart-proxy/models/interfaces.js';
 export * from './proxies/smart-proxy/utils/index.js';
 
-// Original: export * from './smartproxy/classes.pp.snihandler.js'
-// Now we export from the new module
-export { SniHandler } from './tls/sni/sni-handler.js';
-
 // Core types and utilities
 export * from './core/models/common-types.js';
 
 // Export IAcmeOptions from one place only
 export type { IAcmeOptions } from './proxies/smart-proxy/models/interfaces.js';
 
-// Modular exports for new architecture
-export * as tls from './tls/index.js';
+// Modular exports
 export * as routing from './routing/index.js';
-export * as detection from './detection/index.js';
 export * as protocols from './protocols/index.js';

ts/protocols/common/fragment-handler.ts

@@ -1,167 +0,0 @@
-/**
- * Shared Fragment Handler for Protocol Detection
- * 
- * Provides unified fragment buffering and reassembly for protocols
- * that may span multiple TCP packets.
- */
-
-import { Buffer } from 'node:buffer';
-
-/**
- * Fragment tracking information
- */
-export interface IFragmentInfo {
-  buffer: Buffer;
-  timestamp: number;
-  connectionId: string;
-}
-
-/**
- * Options for fragment handling
- */
-export interface IFragmentOptions {
-  maxBufferSize?: number;
-  timeout?: number;
-  cleanupInterval?: number;
-}
-
-/**
- * Result of fragment processing
- */
-export interface IFragmentResult {
-  isComplete: boolean;
-  buffer?: Buffer;
-  needsMoreData: boolean;
-  error?: string;
-}
-
-/**
- * Shared fragment handler for protocol detection
- */
-export class FragmentHandler {
-  private fragments = new Map<string, IFragmentInfo>();
-  private cleanupTimer?: NodeJS.Timeout;
-  
-  constructor(private options: IFragmentOptions = {}) {
-    // Start cleanup timer if not already running
-    if (options.cleanupInterval && !this.cleanupTimer) {
-      this.cleanupTimer = setInterval(
-        () => this.cleanup(),
-        options.cleanupInterval
-      );
-      // Don't let this timer prevent process exit
-      if (this.cleanupTimer.unref) {
-        this.cleanupTimer.unref();
-      }
-    }
-  }
-  
-  /**
-   * Add a fragment for a connection
-   */
-  addFragment(connectionId: string, fragment: Buffer): IFragmentResult {
-    const existing = this.fragments.get(connectionId);
-    
-    if (existing) {
-      // Append to existing buffer
-      const newBuffer = Buffer.concat([existing.buffer, fragment]);
-      
-      // Check size limit
-      const maxSize = this.options.maxBufferSize || 65536;
-      if (newBuffer.length > maxSize) {
-        this.fragments.delete(connectionId);
-        return {
-          isComplete: false,
-          needsMoreData: false,
-          error: 'Buffer size exceeded maximum allowed'
-        };
-      }
-      
-      // Update fragment info
-      this.fragments.set(connectionId, {
-        buffer: newBuffer,
-        timestamp: Date.now(),
-        connectionId
-      });
-      
-      return {
-        isComplete: false,
-        buffer: newBuffer,
-        needsMoreData: true
-      };
-    } else {
-      // New fragment
-      this.fragments.set(connectionId, {
-        buffer: fragment,
-        timestamp: Date.now(),
-        connectionId
-      });
-      
-      return {
-        isComplete: false,
-        buffer: fragment,
-        needsMoreData: true
-      };
-    }
-  }
-  
-  /**
-   * Get the current buffer for a connection
-   */
-  getBuffer(connectionId: string): Buffer | undefined {
-    return this.fragments.get(connectionId)?.buffer;
-  }
-  
-  /**
-   * Mark a connection as complete and clean up
-   */
-  complete(connectionId: string): void {
-    this.fragments.delete(connectionId);
-  }
-  
-  /**
-   * Check if we're tracking a connection
-   */
-  hasConnection(connectionId: string): boolean {
-    return this.fragments.has(connectionId);
-  }
-  
-  /**
-   * Clean up expired fragments
-   */
-  cleanup(): void {
-    const now = Date.now();
-    const timeout = this.options.timeout || 5000;
-    
-    for (const [connectionId, info] of this.fragments.entries()) {
-      if (now - info.timestamp > timeout) {
-        this.fragments.delete(connectionId);
-      }
-    }
-  }
-  
-  /**
-   * Clear all fragments
-   */
-  clear(): void {
-    this.fragments.clear();
-  }
-  
-  /**
-   * Destroy the handler and clean up resources
-   */
-  destroy(): void {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = undefined;
-    }
-    this.clear();
-  }
-  
-  /**
-   * Get the number of tracked connections
-   */
-  get size(): number {
-    return this.fragments.size;
-  }
-}

ts/protocols/common/index.ts

@@ -1,8 +0,0 @@
-/**
- * Common Protocol Infrastructure
- * 
- * Shared utilities and types for protocol handling
- */
-
-export * from './fragment-handler.js';
-export * from './types.js';

ts/protocols/common/types.ts

@@ -1,76 +0,0 @@
-/**
- * Common Protocol Types
- * 
- * Shared types used across different protocol implementations
- */
-
-/**
- * Supported protocol types
- */
-export type TProtocolType = 'tls' | 'http' | 'https' | 'websocket' | 'unknown';
-
-/**
- * Protocol detection result
- */
-export interface IProtocolDetectionResult {
-  protocol: TProtocolType;
-  confidence: number; // 0-100
-  requiresMoreData?: boolean;
-  metadata?: {
-    version?: string;
-    method?: string;
-    [key: string]: any;
-  };
-}
-
-/**
- * Routing information extracted from protocols
- */
-export interface IRoutingInfo {
-  domain?: string;
-  port?: number;
-  path?: string;
-  protocol: TProtocolType;
-}
-
-/**
- * Connection context for protocol operations
- */
-export interface IConnectionContext {
-  id: string;
-  sourceIp?: string;
-  sourcePort?: number;
-  destIp?: string;
-  destPort?: number;
-  timestamp?: number;
-}
-
-/**
- * Protocol detection options
- */
-export interface IProtocolDetectionOptions {
-  quickMode?: boolean;        // Only do minimal detection
-  extractRouting?: boolean;   // Extract routing information
-  maxWaitTime?: number;       // Max time to wait for complete data
-  maxBufferSize?: number;     // Max buffer size for fragmented data
-}
-
-/**
- * Base interface for protocol detectors
- */
-export interface IProtocolDetector {
-  /**
-   * Check if this detector can handle the data
-   */
-  canHandle(data: Buffer): boolean;
-  
-  /**
-   * Perform quick detection (first few bytes only)
-   */
-  quickDetect(data: Buffer): IProtocolDetectionResult;
-  
-  /**
-   * Extract routing information if possible
-   */
-  extractRouting?(data: Buffer, context?: IConnectionContext): IRoutingInfo | null;
-}

ts/protocols/http/index.ts

@@ -4,5 +4,4 @@
  */
 
 export * from './constants.js';
-export * from './types.js';
-export * from './parser.js';
+export * from './types.js';

ts/protocols/http/parser.ts

@@ -1,219 +0,0 @@
-/**
- * HTTP Protocol Parser
- * Generic HTTP parsing utilities
- */
-
-import { HTTP_METHODS, type THttpMethod, type THttpVersion } from './constants.js';
-import type { IHttpRequestLine, IHttpHeader } from './types.js';
-
-/**
- * HTTP parser utilities
- */
-export class HttpParser {
-  /**
-   * Check if string is a valid HTTP method
-   */
-  static isHttpMethod(str: string): str is THttpMethod {
-    return HTTP_METHODS.includes(str as THttpMethod);
-  }
-  
-  /**
-   * Parse HTTP request line
-   */
-  static parseRequestLine(line: string): IHttpRequestLine | null {
-    const parts = line.trim().split(' ');
-    
-    if (parts.length !== 3) {
-      return null;
-    }
-    
-    const [method, path, version] = parts;
-    
-    // Validate method
-    if (!this.isHttpMethod(method)) {
-      return null;
-    }
-    
-    // Validate version
-    if (!version.startsWith('HTTP/')) {
-      return null;
-    }
-    
-    return {
-      method: method as THttpMethod,
-      path,
-      version: version as THttpVersion
-    };
-  }
-  
-  /**
-   * Parse HTTP header line
-   */
-  static parseHeaderLine(line: string): IHttpHeader | null {
-    const colonIndex = line.indexOf(':');
-    
-    if (colonIndex === -1) {
-      return null;
-    }
-    
-    const name = line.slice(0, colonIndex).trim();
-    const value = line.slice(colonIndex + 1).trim();
-    
-    if (!name) {
-      return null;
-    }
-    
-    return { name, value };
-  }
-  
-  /**
-   * Parse HTTP headers from lines
-   */
-  static parseHeaders(lines: string[]): Record<string, string> {
-    const headers: Record<string, string> = {};
-    
-    for (const line of lines) {
-      const header = this.parseHeaderLine(line);
-      if (header) {
-        // Convert header names to lowercase for consistency
-        headers[header.name.toLowerCase()] = header.value;
-      }
-    }
-    
-    return headers;
-  }
-  
-  /**
-   * Extract domain from Host header value
-   */
-  static extractDomainFromHost(hostHeader: string): string {
-    // Remove port if present
-    const colonIndex = hostHeader.lastIndexOf(':');
-    if (colonIndex !== -1) {
-      // Check if it's not part of IPv6 address
-      const beforeColon = hostHeader.slice(0, colonIndex);
-      if (!beforeColon.includes(']')) {
-        return beforeColon;
-      }
-    }
-    return hostHeader;
-  }
-  
-  /**
-   * Validate domain name
-   */
-  static isValidDomain(domain: string): boolean {
-    // Basic domain validation
-    if (!domain || domain.length > 253) {
-      return false;
-    }
-    
-    // Check for valid characters and structure
-    const domainRegex = /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(\.[A-Za-z0-9-]{1,63})*$/;
-    return domainRegex.test(domain);
-  }
-  
-  /**
-   * Extract line from buffer
-   */
-  static extractLine(buffer: Buffer, offset: number = 0): { line: string; nextOffset: number } | null {
-    // Look for CRLF
-    const crlfIndex = buffer.indexOf('\r\n', offset);
-    if (crlfIndex === -1) {
-      // Look for just LF
-      const lfIndex = buffer.indexOf('\n', offset);
-      if (lfIndex === -1) {
-        return null;
-      }
-      
-      return {
-        line: buffer.slice(offset, lfIndex).toString('utf8'),
-        nextOffset: lfIndex + 1
-      };
-    }
-    
-    return {
-      line: buffer.slice(offset, crlfIndex).toString('utf8'),
-      nextOffset: crlfIndex + 2
-    };
-  }
-  
-  /**
-   * Check if buffer contains printable ASCII
-   */
-  static isPrintableAscii(buffer: Buffer, length?: number): boolean {
-    const checkLength = Math.min(length || buffer.length, buffer.length);
-    
-    for (let i = 0; i < checkLength; i++) {
-      const byte = buffer[i];
-      // Allow printable ASCII (32-126) plus tab (9), LF (10), and CR (13)
-      if (byte < 32 || byte > 126) {
-        if (byte !== 9 && byte !== 10 && byte !== 13) {
-          return false;
-        }
-      }
-    }
-    
-    return true;
-  }
-  
-  /**
-   * Quick check if buffer starts with HTTP method
-   */
-  static quickCheck(buffer: Buffer): boolean {
-    if (buffer.length < 3) {
-      return false;
-    }
-    
-    // Check common HTTP methods
-    const start = buffer.slice(0, 7).toString('ascii');
-    return start.startsWith('GET ') ||
-           start.startsWith('POST ') ||
-           start.startsWith('PUT ') ||
-           start.startsWith('DELETE ') ||
-           start.startsWith('HEAD ') ||
-           start.startsWith('OPTIONS') ||
-           start.startsWith('PATCH ') ||
-           start.startsWith('CONNECT') ||
-           start.startsWith('TRACE ');
-  }
-  
-  /**
-   * Parse query string
-   */
-  static parseQueryString(queryString: string): Record<string, string> {
-    const params: Record<string, string> = {};
-    
-    if (!queryString) {
-      return params;
-    }
-    
-    // Remove leading '?' if present
-    if (queryString.startsWith('?')) {
-      queryString = queryString.slice(1);
-    }
-    
-    const pairs = queryString.split('&');
-    for (const pair of pairs) {
-      const [key, value] = pair.split('=');
-      if (key) {
-        params[decodeURIComponent(key)] = value ? decodeURIComponent(value) : '';
-      }
-    }
-    
-    return params;
-  }
-  
-  /**
-   * Build query string from params
-   */
-  static buildQueryString(params: Record<string, string>): string {
-    const pairs: string[] = [];
-    
-    for (const [key, value] of Object.entries(params)) {
-      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
-    }
-    
-    return pairs.length > 0 ? '?' + pairs.join('&') : '';
-  }
-}

ts/protocols/index.ts

@@ -1,12 +1,5 @@
 /**
  * Protocol-specific modules for smartproxy
- * 
- * This directory contains generic protocol knowledge separated from
- * smartproxy-specific implementation details.
  */
 
-export * as common from './common/index.js';
-export * as tls from './tls/index.js';
 export * as http from './http/index.js';
-export * as proxy from './proxy/index.js';
-export * as websocket from './websocket/index.js';

ts/protocols/proxy/index.ts

@@ -1,7 +0,0 @@
-/**
- * PROXY Protocol Module
- * HAProxy PROXY protocol implementation
- */
-
-export * from './types.js';
-export * from './parser.js';

ts/protocols/proxy/parser.ts

@@ -1,183 +0,0 @@
-/**
- * PROXY Protocol Parser
- * Implementation of HAProxy PROXY protocol v1 (text format)
- * Spec: https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt
- */
-
-import type { IProxyInfo, IProxyParseResult, TProxyProtocol } from './types.js';
-
-/**
- * PROXY protocol parser
- */
-export class ProxyProtocolParser {
-  static readonly PROXY_V1_SIGNATURE = 'PROXY ';
-  static readonly MAX_HEADER_LENGTH = 107; // Max length for v1 header
-  static readonly HEADER_TERMINATOR = '\r\n';
-  
-  /**
-   * Parse PROXY protocol v1 header from buffer
-   * Returns proxy info and remaining data after header
-   */
-  static parse(data: Buffer): IProxyParseResult {
-    // Check if buffer starts with PROXY signature
-    if (!data.toString('ascii', 0, 6).startsWith(this.PROXY_V1_SIGNATURE)) {
-      return {
-        proxyInfo: null,
-        remainingData: data
-      };
-    }
-    
-    // Find header terminator
-    const headerEndIndex = data.indexOf(this.HEADER_TERMINATOR);
-    if (headerEndIndex === -1) {
-      // Header incomplete, need more data
-      if (data.length > this.MAX_HEADER_LENGTH) {
-        // Header too long, invalid
-        throw new Error('PROXY protocol header exceeds maximum length');
-      }
-      return {
-        proxyInfo: null,
-        remainingData: data
-      };
-    }
-    
-    // Extract header line
-    const headerLine = data.toString('ascii', 0, headerEndIndex);
-    const remainingData = data.slice(headerEndIndex + 2); // Skip \r\n
-    
-    // Parse header
-    const parts = headerLine.split(' ');
-    
-    if (parts.length < 2) {
-      throw new Error(`Invalid PROXY protocol header format: ${headerLine}`);
-    }
-    
-    const [signature, protocol] = parts;
-    
-    // Validate protocol
-    if (!['TCP4', 'TCP6', 'UNKNOWN'].includes(protocol)) {
-      throw new Error(`Invalid PROXY protocol: ${protocol}`);
-    }
-    
-    // For UNKNOWN protocol, ignore addresses
-    if (protocol === 'UNKNOWN') {
-      return {
-        proxyInfo: {
-          protocol: 'UNKNOWN',
-          sourceIP: '',
-          sourcePort: 0,
-          destinationIP: '',
-          destinationPort: 0
-        },
-        remainingData
-      };
-    }
-    
-    // For TCP4/TCP6, we need all 6 parts
-    if (parts.length !== 6) {
-      throw new Error(`Invalid PROXY protocol header format: ${headerLine}`);
-    }
-    
-    const [, , srcIP, dstIP, srcPort, dstPort] = parts;
-    
-    // Validate and parse ports
-    const sourcePort = parseInt(srcPort, 10);
-    const destinationPort = parseInt(dstPort, 10);
-    
-    if (isNaN(sourcePort) || sourcePort < 0 || sourcePort > 65535) {
-      throw new Error(`Invalid source port: ${srcPort}`);
-    }
-    
-    if (isNaN(destinationPort) || destinationPort < 0 || destinationPort > 65535) {
-      throw new Error(`Invalid destination port: ${dstPort}`);
-    }
-    
-    // Validate IP addresses
-    const protocolType = protocol as TProxyProtocol;
-    if (!this.isValidIP(srcIP, protocolType)) {
-      throw new Error(`Invalid source IP for ${protocol}: ${srcIP}`);
-    }
-    
-    if (!this.isValidIP(dstIP, protocolType)) {
-      throw new Error(`Invalid destination IP for ${protocol}: ${dstIP}`);
-    }
-    
-    return {
-      proxyInfo: {
-        protocol: protocolType,
-        sourceIP: srcIP,
-        sourcePort,
-        destinationIP: dstIP,
-        destinationPort
-      },
-      remainingData
-    };
-  }
-  
-  /**
-   * Generate PROXY protocol v1 header
-   */
-  static generate(info: IProxyInfo): Buffer {
-    if (info.protocol === 'UNKNOWN') {
-      return Buffer.from(`PROXY UNKNOWN\r\n`, 'ascii');
-    }
-    
-    const header = `PROXY ${info.protocol} ${info.sourceIP} ${info.destinationIP} ${info.sourcePort} ${info.destinationPort}\r\n`;
-    
-    if (header.length > this.MAX_HEADER_LENGTH) {
-      throw new Error('Generated PROXY protocol header exceeds maximum length');
-    }
-    
-    return Buffer.from(header, 'ascii');
-  }
-  
-  /**
-   * Validate IP address format
-   */
-  static isValidIP(ip: string, protocol: TProxyProtocol): boolean {
-    if (protocol === 'TCP4') {
-      return this.isIPv4(ip);
-    } else if (protocol === 'TCP6') {
-      return this.isIPv6(ip);
-    }
-    return false;
-  }
-  
-  /**
-   * Check if string is valid IPv4
-   */
-  static isIPv4(ip: string): boolean {
-    const parts = ip.split('.');
-    if (parts.length !== 4) return false;
-    
-    for (const part of parts) {
-      const num = parseInt(part, 10);
-      if (isNaN(num) || num < 0 || num > 255 || part !== num.toString()) {
-        return false;
-      }
-    }
-    return true;
-  }
-  
-  /**
-   * Check if string is valid IPv6
-   */
-  static isIPv6(ip: string): boolean {
-    // Basic IPv6 validation
-    const ipv6Regex = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/;
-    return ipv6Regex.test(ip);
-  }
-  
-  /**
-   * Create a connection ID string for tracking
-   */
-  static createConnectionId(connectionInfo: {
-    sourceIp?: string;
-    sourcePort?: number;
-    destIp?: string;
-    destPort?: number;
-  }): string {
-    const { sourceIp, sourcePort, destIp, destPort } = connectionInfo;
-    return `${sourceIp}:${sourcePort}-${destIp}:${destPort}`;
-  }
-}

ts/protocols/proxy/types.ts

@@ -1,53 +0,0 @@
-/**
- * PROXY Protocol Type Definitions
- * Based on HAProxy PROXY protocol specification
- */
-
-/**
- * PROXY protocol version
- */
-export type TProxyProtocolVersion = 'v1' | 'v2';
-
-/**
- * Connection protocol type
- */
-export type TProxyProtocol = 'TCP4' | 'TCP6' | 'UNKNOWN';
-
-/**
- * Interface representing parsed PROXY protocol information
- */
-export interface IProxyInfo {
-  protocol: TProxyProtocol;
-  sourceIP: string;
-  sourcePort: number;
-  destinationIP: string;
-  destinationPort: number;
-}
-
-/**
- * Interface for parse result including remaining data
- */
-export interface IProxyParseResult {
-  proxyInfo: IProxyInfo | null;
-  remainingData: Buffer;
-}
-
-/**
- * PROXY protocol v2 header format
- */
-export interface IProxyV2Header {
-  signature: Buffer;
-  versionCommand: number;
-  family: number;
-  length: number;
-}
-
-/**
- * Connection information for PROXY protocol
- */
-export interface IProxyConnectionInfo {
-  sourceIp?: string;
-  sourcePort?: number;
-  destIp?: string;
-  destPort?: number;
-}

ts/protocols/tls/alerts/index.ts

@@ -1,3 +0,0 @@
-/**
- * TLS alerts
- */

ts/protocols/tls/alerts/tls-alert.ts

@@ -1,259 +0,0 @@
-import * as plugins from '../../../plugins.js';
-import { TlsAlertLevel, TlsAlertDescription, TlsVersion } from '../utils/tls-utils.js';
-
-/**
- * TlsAlert class for creating and sending TLS alert messages
- */
-export class TlsAlert {
-  // Use enum values from TlsAlertLevel
-  static readonly LEVEL_WARNING = TlsAlertLevel.WARNING;
-  static readonly LEVEL_FATAL = TlsAlertLevel.FATAL;
-
-  // Use enum values from TlsAlertDescription
-  static readonly CLOSE_NOTIFY = TlsAlertDescription.CLOSE_NOTIFY;
-  static readonly UNEXPECTED_MESSAGE = TlsAlertDescription.UNEXPECTED_MESSAGE;
-  static readonly BAD_RECORD_MAC = TlsAlertDescription.BAD_RECORD_MAC;
-  static readonly DECRYPTION_FAILED = TlsAlertDescription.DECRYPTION_FAILED;
-  static readonly RECORD_OVERFLOW = TlsAlertDescription.RECORD_OVERFLOW;
-  static readonly DECOMPRESSION_FAILURE = TlsAlertDescription.DECOMPRESSION_FAILURE;
-  static readonly HANDSHAKE_FAILURE = TlsAlertDescription.HANDSHAKE_FAILURE;
-  static readonly NO_CERTIFICATE = TlsAlertDescription.NO_CERTIFICATE;
-  static readonly BAD_CERTIFICATE = TlsAlertDescription.BAD_CERTIFICATE;
-  static readonly UNSUPPORTED_CERTIFICATE = TlsAlertDescription.UNSUPPORTED_CERTIFICATE;
-  static readonly CERTIFICATE_REVOKED = TlsAlertDescription.CERTIFICATE_REVOKED;
-  static readonly CERTIFICATE_EXPIRED = TlsAlertDescription.CERTIFICATE_EXPIRED;
-  static readonly CERTIFICATE_UNKNOWN = TlsAlertDescription.CERTIFICATE_UNKNOWN;
-  static readonly ILLEGAL_PARAMETER = TlsAlertDescription.ILLEGAL_PARAMETER;
-  static readonly UNKNOWN_CA = TlsAlertDescription.UNKNOWN_CA;
-  static readonly ACCESS_DENIED = TlsAlertDescription.ACCESS_DENIED;
-  static readonly DECODE_ERROR = TlsAlertDescription.DECODE_ERROR;
-  static readonly DECRYPT_ERROR = TlsAlertDescription.DECRYPT_ERROR;
-  static readonly EXPORT_RESTRICTION = TlsAlertDescription.EXPORT_RESTRICTION;
-  static readonly PROTOCOL_VERSION = TlsAlertDescription.PROTOCOL_VERSION;
-  static readonly INSUFFICIENT_SECURITY = TlsAlertDescription.INSUFFICIENT_SECURITY;
-  static readonly INTERNAL_ERROR = TlsAlertDescription.INTERNAL_ERROR;
-  static readonly INAPPROPRIATE_FALLBACK = TlsAlertDescription.INAPPROPRIATE_FALLBACK;
-  static readonly USER_CANCELED = TlsAlertDescription.USER_CANCELED;
-  static readonly NO_RENEGOTIATION = TlsAlertDescription.NO_RENEGOTIATION;
-  static readonly MISSING_EXTENSION = TlsAlertDescription.MISSING_EXTENSION;
-  static readonly UNSUPPORTED_EXTENSION = TlsAlertDescription.UNSUPPORTED_EXTENSION;
-  static readonly CERTIFICATE_REQUIRED = TlsAlertDescription.CERTIFICATE_REQUIRED;
-  static readonly UNRECOGNIZED_NAME = TlsAlertDescription.UNRECOGNIZED_NAME;
-  static readonly BAD_CERTIFICATE_STATUS_RESPONSE = TlsAlertDescription.BAD_CERTIFICATE_STATUS_RESPONSE;
-  static readonly BAD_CERTIFICATE_HASH_VALUE = TlsAlertDescription.BAD_CERTIFICATE_HASH_VALUE;
-  static readonly UNKNOWN_PSK_IDENTITY = TlsAlertDescription.UNKNOWN_PSK_IDENTITY;
-  static readonly CERTIFICATE_REQUIRED_1_3 = TlsAlertDescription.CERTIFICATE_REQUIRED_1_3;
-  static readonly NO_APPLICATION_PROTOCOL = TlsAlertDescription.NO_APPLICATION_PROTOCOL;
-  
-  /**
-   * Create a TLS alert buffer with the specified level and description code
-   *
-   * @param level Alert level (warning or fatal)
-   * @param description Alert description code
-   * @param tlsVersion TLS version bytes (default is TLS 1.2: 0x0303)
-   * @returns Buffer containing the TLS alert message
-   */
-  static create(
-    level: number,
-    description: number,
-    tlsVersion: [number, number] = [TlsVersion.TLS1_2[0], TlsVersion.TLS1_2[1]]
-  ): Buffer {
-    return Buffer.from([
-      0x15, // Alert record type
-      tlsVersion[0],
-      tlsVersion[1], // TLS version (default to TLS 1.2: 0x0303)
-      0x00,
-      0x02, // Length
-      level, // Alert level
-      description, // Alert description
-    ]);
-  }
-  
-  /**
-   * Create a warning-level TLS alert
-   * 
-   * @param description Alert description code
-   * @returns Buffer containing the warning-level TLS alert message
-   */
-  static createWarning(description: number): Buffer {
-    return this.create(this.LEVEL_WARNING, description);
-  }
-  
-  /**
-   * Create a fatal-level TLS alert
-   * 
-   * @param description Alert description code
-   * @returns Buffer containing the fatal-level TLS alert message
-   */
-  static createFatal(description: number): Buffer {
-    return this.create(this.LEVEL_FATAL, description);
-  }
-  
-  /**
-   * Send a TLS alert to a socket and optionally close the connection
-   * 
-   * @param socket The socket to send the alert to
-   * @param level Alert level (warning or fatal)
-   * @param description Alert description code
-   * @param closeAfterSend Whether to close the connection after sending the alert
-   * @param closeDelay Milliseconds to wait before closing the connection (default: 200ms)
-   * @returns Promise that resolves when the alert has been sent
-   */
-  static async send(
-    socket: plugins.net.Socket,
-    level: number,
-    description: number,
-    closeAfterSend: boolean = false,
-    closeDelay: number = 200
-  ): Promise<void> {
-    const alert = this.create(level, description);
-    
-    return new Promise<void>((resolve, reject) => {
-      try {
-        // Ensure the alert is written as a single packet
-        socket.cork();
-        const writeSuccessful = socket.write(alert, (err) => {
-          if (err) {
-            reject(err);
-            return;
-          }
-          
-          if (closeAfterSend) {
-            setTimeout(() => {
-              socket.end();
-              resolve();
-            }, closeDelay);
-          } else {
-            resolve();
-          }
-        });
-        socket.uncork();
-        
-        // If write wasn't successful immediately, wait for drain
-        if (!writeSuccessful && !closeAfterSend) {
-          socket.once('drain', () => {
-            resolve();
-          });
-        }
-      } catch (err) {
-        reject(err);
-      }
-    });
-  }
-  
-  /**
-   * Pre-defined TLS alert messages
-   */
-  static readonly alerts = {
-    // Warning level alerts
-    closeNotify: TlsAlert.createWarning(TlsAlert.CLOSE_NOTIFY),
-    unsupportedExtension: TlsAlert.createWarning(TlsAlert.UNSUPPORTED_EXTENSION),
-    certificateRequired: TlsAlert.createWarning(TlsAlert.CERTIFICATE_REQUIRED),
-    unrecognizedName: TlsAlert.createWarning(TlsAlert.UNRECOGNIZED_NAME),
-    noRenegotiation: TlsAlert.createWarning(TlsAlert.NO_RENEGOTIATION),
-    userCanceled: TlsAlert.createWarning(TlsAlert.USER_CANCELED),
-    
-    // Warning level alerts for session resumption
-    certificateExpiredWarning: TlsAlert.createWarning(TlsAlert.CERTIFICATE_EXPIRED),
-    handshakeFailureWarning: TlsAlert.createWarning(TlsAlert.HANDSHAKE_FAILURE),
-    insufficientSecurityWarning: TlsAlert.createWarning(TlsAlert.INSUFFICIENT_SECURITY),
-    
-    // Fatal level alerts
-    unexpectedMessage: TlsAlert.createFatal(TlsAlert.UNEXPECTED_MESSAGE),
-    badRecordMac: TlsAlert.createFatal(TlsAlert.BAD_RECORD_MAC),
-    recordOverflow: TlsAlert.createFatal(TlsAlert.RECORD_OVERFLOW),
-    handshakeFailure: TlsAlert.createFatal(TlsAlert.HANDSHAKE_FAILURE),
-    badCertificate: TlsAlert.createFatal(TlsAlert.BAD_CERTIFICATE),
-    certificateExpired: TlsAlert.createFatal(TlsAlert.CERTIFICATE_EXPIRED),
-    certificateUnknown: TlsAlert.createFatal(TlsAlert.CERTIFICATE_UNKNOWN),
-    illegalParameter: TlsAlert.createFatal(TlsAlert.ILLEGAL_PARAMETER),
-    unknownCA: TlsAlert.createFatal(TlsAlert.UNKNOWN_CA),
-    accessDenied: TlsAlert.createFatal(TlsAlert.ACCESS_DENIED),
-    decodeError: TlsAlert.createFatal(TlsAlert.DECODE_ERROR),
-    decryptError: TlsAlert.createFatal(TlsAlert.DECRYPT_ERROR),
-    protocolVersion: TlsAlert.createFatal(TlsAlert.PROTOCOL_VERSION),
-    insufficientSecurity: TlsAlert.createFatal(TlsAlert.INSUFFICIENT_SECURITY),
-    internalError: TlsAlert.createFatal(TlsAlert.INTERNAL_ERROR),
-    unrecognizedNameFatal: TlsAlert.createFatal(TlsAlert.UNRECOGNIZED_NAME),
-  };
-  
-  /**
-   * Utility method to send a warning-level unrecognized_name alert
-   * Specifically designed for SNI issues to encourage the client to retry with SNI
-   * 
-   * @param socket The socket to send the alert to
-   * @returns Promise that resolves when the alert has been sent
-   */
-  static async sendSniRequired(socket: plugins.net.Socket): Promise<void> {
-    return this.send(socket, this.LEVEL_WARNING, this.UNRECOGNIZED_NAME);
-  }
-  
-  /**
-   * Utility method to send a close_notify alert and close the connection
-   * 
-   * @param socket The socket to send the alert to
-   * @param closeDelay Milliseconds to wait before closing the connection (default: 200ms)
-   * @returns Promise that resolves when the alert has been sent and the connection closed
-   */
-  static async sendCloseNotify(socket: plugins.net.Socket, closeDelay: number = 200): Promise<void> {
-    return this.send(socket, this.LEVEL_WARNING, this.CLOSE_NOTIFY, true, closeDelay);
-  }
-  
-  /**
-   * Utility method to send a certificate_expired alert to force new TLS session
-   * 
-   * @param socket The socket to send the alert to
-   * @param fatal Whether to send as a fatal alert (default: false)
-   * @param closeAfterSend Whether to close the connection after sending the alert (default: true)
-   * @param closeDelay Milliseconds to wait before closing the connection (default: 200ms)
-   * @returns Promise that resolves when the alert has been sent
-   */
-  static async sendCertificateExpired(
-    socket: plugins.net.Socket,
-    fatal: boolean = false,
-    closeAfterSend: boolean = true,
-    closeDelay: number = 200
-  ): Promise<void> {
-    const level = fatal ? this.LEVEL_FATAL : this.LEVEL_WARNING;
-    return this.send(socket, level, this.CERTIFICATE_EXPIRED, closeAfterSend, closeDelay);
-  }
-  
-  /**
-   * Send a sequence of alerts to force SNI from clients
-   * This combines multiple alerts to ensure maximum browser compatibility
-   * 
-   * @param socket The socket to send the alerts to
-   * @returns Promise that resolves when all alerts have been sent
-   */
-  static async sendForceSniSequence(socket: plugins.net.Socket): Promise<void> {
-    try {
-      // Send unrecognized_name (warning)
-      socket.cork();
-      socket.write(this.alerts.unrecognizedName);
-      socket.uncork();
-      
-      // Give the socket time to send the alert
-      return new Promise((resolve) => {
-        setTimeout(resolve, 50);
-      });
-    } catch (err) {
-      return Promise.reject(err);
-    }
-  }
-  
-  /**
-   * Send a fatal level alert that immediately terminates the connection
-   * 
-   * @param socket The socket to send the alert to
-   * @param description Alert description code
-   * @param closeDelay Milliseconds to wait before closing the connection (default: 100ms)
-   * @returns Promise that resolves when the alert has been sent and the connection closed
-   */
-  static async sendFatalAndClose(
-    socket: plugins.net.Socket,
-    description: number, 
-    closeDelay: number = 100
-  ): Promise<void> {
-    return this.send(socket, this.LEVEL_FATAL, description, true, closeDelay);
-  }
-}

ts/protocols/tls/index.ts

@@ -1,37 +0,0 @@
-/**
- * TLS Protocol Module
- * Contains generic TLS protocol knowledge including parsers, constants, and utilities
- */
-
-// Export all sub-modules
-export * from './alerts/index.js';
-export * from './sni/index.js';
-export * from './utils/index.js';
-
-// Re-export main utilities and types for convenience
-export { 
-  TlsUtils,
-  TlsRecordType,
-  TlsHandshakeType,
-  TlsExtensionType,
-  TlsAlertLevel,
-  TlsAlertDescription,
-  TlsVersion
-} from './utils/tls-utils.js';
-export { TlsAlert } from './alerts/tls-alert.js';
-export { ClientHelloParser } from './sni/client-hello-parser.js';
-export { SniExtraction } from './sni/sni-extraction.js';
-
-// Export tlsVersionToString helper
-export function tlsVersionToString(major: number, minor: number): string | null {
-  if (major === 0x03) {
-    switch (minor) {
-      case 0x00: return 'SSLv3';
-      case 0x01: return 'TLSv1.0';
-      case 0x02: return 'TLSv1.1';
-      case 0x03: return 'TLSv1.2';
-      case 0x04: return 'TLSv1.3';
-    }
-  }
-  return null;
-}

ts/protocols/tls/sni/client-hello-parser.ts

@@ -1,629 +0,0 @@
-import { Buffer } from 'node:buffer';
-import { 
-  TlsRecordType,
-  TlsHandshakeType,
-  TlsExtensionType,
-  TlsUtils
-} from '../utils/tls-utils.js';
-
-/**
- * Interface for logging functions used by the parser
- */
-export type LoggerFunction = (message: string) => void;
-
-/**
- * Result of a session resumption check
- */
-export interface SessionResumptionResult {
-  isResumption: boolean;
-  hasSNI: boolean;
-}
-
-/**
- * Information about parsed TLS extensions
- */
-export interface ExtensionInfo {
-  type: number;
-  length: number;
-  data: Buffer;
-}
-
-/**
- * Result of a ClientHello parse operation
- */
-export interface ClientHelloParseResult {
-  isValid: boolean;
-  version?: [number, number];
-  random?: Buffer;
-  sessionId?: Buffer;
-  hasSessionId: boolean;
-  cipherSuites?: Buffer;
-  compressionMethods?: Buffer;
-  extensions: ExtensionInfo[];
-  serverNameList?: string[];
-  hasSessionTicket: boolean;
-  hasPsk: boolean;
-  hasEarlyData: boolean;
-  error?: string;
-}
-
-/**
- * Fragment tracking information
- */
-export interface FragmentTrackingInfo {
-  buffer: Buffer;
-  timestamp: number;
-  connectionId: string;
-}
-
-/**
- * Class for parsing TLS ClientHello messages
- */
-export class ClientHelloParser {
-  // Buffer for handling fragmented ClientHello messages
-  private static fragmentedBuffers: Map<string, FragmentTrackingInfo> = new Map();
-  private static fragmentTimeout: number = 1000; // ms to wait for fragments before cleanup
-
-  /**
-   * Clean up expired fragments
-   */
-  private static cleanupExpiredFragments(): void {
-    const now = Date.now();
-    for (const [connectionId, info] of this.fragmentedBuffers.entries()) {
-      if (now - info.timestamp > this.fragmentTimeout) {
-        this.fragmentedBuffers.delete(connectionId);
-      }
-    }
-  }
-
-  /**
-   * Handles potential fragmented ClientHello messages by buffering and reassembling
-   * TLS record fragments that might span multiple TCP packets.
-   *
-   * @param buffer The current buffer fragment
-   * @param connectionId Unique identifier for the connection
-   * @param logger Optional logging function
-   * @returns A complete buffer if reassembly is successful, or undefined if more fragments are needed
-   */
-  public static handleFragmentedClientHello(
-    buffer: Buffer,
-    connectionId: string,
-    logger?: LoggerFunction
-  ): Buffer | undefined {
-    const log = logger || (() => {});
-    
-    // Periodically clean up expired fragments
-    this.cleanupExpiredFragments();
-
-    // Check if we've seen this connection before
-    if (!this.fragmentedBuffers.has(connectionId)) {
-      // New connection, start with this buffer
-      this.fragmentedBuffers.set(connectionId, {
-        buffer,
-        timestamp: Date.now(),
-        connectionId
-      });
-
-      // Evaluate if this buffer already contains a complete ClientHello
-      try {
-        if (buffer.length >= 5) {
-          // Get the record length from TLS header
-          const recordLength = (buffer[3] << 8) + buffer[4] + 5; // +5 for the TLS record header itself
-          log(`Initial buffer size: ${buffer.length}, expected record length: ${recordLength}`);
-
-          // Check if this buffer already contains a complete TLS record
-          if (buffer.length >= recordLength) {
-            log(`Initial buffer contains complete ClientHello, length: ${buffer.length}`);
-            return buffer;
-          }
-        } else {
-          log(
-            `Initial buffer too small (${buffer.length} bytes), needs at least 5 bytes for TLS header`
-          );
-        }
-      } catch (e) {
-        log(`Error checking initial buffer completeness: ${e}`);
-      }
-
-      log(`Started buffering connection ${connectionId}, initial size: ${buffer.length}`);
-      return undefined; // Need more fragments
-    } else {
-      // Existing connection, append this buffer
-      const existingInfo = this.fragmentedBuffers.get(connectionId)!;
-      const newBuffer = Buffer.concat([existingInfo.buffer, buffer]);
-      
-      // Update the buffer and timestamp
-      this.fragmentedBuffers.set(connectionId, {
-        ...existingInfo,
-        buffer: newBuffer,
-        timestamp: Date.now()
-      });
-
-      log(`Appended to buffer for ${connectionId}, new size: ${newBuffer.length}`);
-
-      // Check if we now have a complete ClientHello
-      try {
-        if (newBuffer.length >= 5) {
-          // Get the record length from TLS header
-          const recordLength = (newBuffer[3] << 8) + newBuffer[4] + 5; // +5 for the TLS record header itself
-          log(
-            `Reassembled buffer size: ${newBuffer.length}, expected record length: ${recordLength}`
-          );
-
-          // Check if we have a complete TLS record now
-          if (newBuffer.length >= recordLength) {
-            log(
-              `Assembled complete ClientHello, length: ${newBuffer.length}, needed: ${recordLength}`
-            );
-
-            // Extract the complete TLS record (might be followed by more data)
-            const completeRecord = newBuffer.slice(0, recordLength);
-
-            // Check if this record is indeed a ClientHello (type 1) at position 5
-            if (
-              completeRecord.length > 5 &&
-              completeRecord[5] === TlsHandshakeType.CLIENT_HELLO
-            ) {
-              log(`Verified record is a ClientHello handshake message`);
-
-              // Complete message received, remove from tracking
-              this.fragmentedBuffers.delete(connectionId);
-              return completeRecord;
-            } else {
-              log(`Record is complete but not a ClientHello handshake, continuing to buffer`);
-              // This might be another TLS record type preceding the ClientHello
-
-              // Try checking for a ClientHello starting at the end of this record
-              if (newBuffer.length > recordLength + 5) {
-                const nextRecordType = newBuffer[recordLength];
-                log(
-                  `Next record type: ${nextRecordType} (looking for ${TlsRecordType.HANDSHAKE})`
-                );
-
-                if (nextRecordType === TlsRecordType.HANDSHAKE) {
-                  const handshakeType = newBuffer[recordLength + 5];
-                  log(
-                    `Next handshake type: ${handshakeType} (looking for ${TlsHandshakeType.CLIENT_HELLO})`
-                  );
-
-                  if (handshakeType === TlsHandshakeType.CLIENT_HELLO) {
-                    // Found a ClientHello in the next record, return the entire buffer
-                    log(`Found ClientHello in subsequent record, returning full buffer`);
-                    this.fragmentedBuffers.delete(connectionId);
-                    return newBuffer;
-                  }
-                }
-              }
-            }
-          }
-        }
-      } catch (e) {
-        log(`Error checking reassembled buffer completeness: ${e}`);
-      }
-
-      return undefined; // Still need more fragments
-    }
-  }
-
-  /**
-   * Parses a TLS ClientHello message and extracts all components
-   * 
-   * @param buffer The buffer containing the ClientHello message
-   * @param logger Optional logging function
-   * @returns Parsed ClientHello or undefined if parsing failed
-   */
-  public static parseClientHello(
-    buffer: Buffer,
-    logger?: LoggerFunction
-  ): ClientHelloParseResult {
-    const log = logger || (() => {});
-    const result: ClientHelloParseResult = {
-      isValid: false,
-      hasSessionId: false,
-      extensions: [],
-      hasSessionTicket: false,
-      hasPsk: false,
-      hasEarlyData: false
-    };
-
-    try {
-      // Check basic validity
-      if (buffer.length < 5) {
-        result.error = 'Buffer too small for TLS record header';
-        return result;
-      }
-
-      // Check record type (must be HANDSHAKE)
-      if (buffer[0] !== TlsRecordType.HANDSHAKE) {
-        result.error = `Not a TLS handshake record: ${buffer[0]}`;
-        return result;
-      }
-
-      // Get TLS version from record header
-      const majorVersion = buffer[1];
-      const minorVersion = buffer[2];
-      result.version = [majorVersion, minorVersion];
-      log(`TLS record version: ${majorVersion}.${minorVersion}`);
-
-      // Parse record length (bytes 3-4, big-endian)
-      const recordLength = (buffer[3] << 8) + buffer[4];
-      log(`Record length: ${recordLength}`);
-
-      // Validate record length against buffer size
-      if (buffer.length < recordLength + 5) {
-        result.error = 'Buffer smaller than expected record length';
-        return result;
-      }
-
-      // Start of handshake message in the buffer
-      let pos = 5;
-
-      // Check handshake type (must be CLIENT_HELLO)
-      if (buffer[pos] !== TlsHandshakeType.CLIENT_HELLO) {
-        result.error = `Not a ClientHello message: ${buffer[pos]}`;
-        return result;
-      }
-
-      // Skip handshake type (1 byte)
-      pos += 1;
-
-      // Parse handshake length (3 bytes, big-endian)
-      const handshakeLength = (buffer[pos] << 16) + (buffer[pos + 1] << 8) + buffer[pos + 2];
-      log(`Handshake length: ${handshakeLength}`);
-
-      // Skip handshake length (3 bytes)
-      pos += 3;
-
-      // Check client version (2 bytes)
-      const clientMajorVersion = buffer[pos];
-      const clientMinorVersion = buffer[pos + 1];
-      log(`Client version: ${clientMajorVersion}.${clientMinorVersion}`);
-
-      // Skip client version (2 bytes)
-      pos += 2;
-
-      // Extract client random (32 bytes)
-      if (pos + 32 > buffer.length) {
-        result.error = 'Buffer too small for client random';
-        return result;
-      }
-      
-      result.random = buffer.slice(pos, pos + 32);
-      log(`Client random: ${result.random.toString('hex')}`);
-
-      // Skip client random (32 bytes)
-      pos += 32;
-
-      // Parse session ID
-      if (pos + 1 > buffer.length) {
-        result.error = 'Buffer too small for session ID length';
-        return result;
-      }
-
-      const sessionIdLength = buffer[pos];
-      log(`Session ID length: ${sessionIdLength}`);
-      pos += 1;
-      
-      result.hasSessionId = sessionIdLength > 0;
-      
-      if (sessionIdLength > 0) {
-        if (pos + sessionIdLength > buffer.length) {
-          result.error = 'Buffer too small for session ID';
-          return result;
-        }
-        
-        result.sessionId = buffer.slice(pos, pos + sessionIdLength);
-        log(`Session ID: ${result.sessionId.toString('hex')}`);
-      }
-
-      // Skip session ID
-      pos += sessionIdLength;
-
-      // Check if we have enough bytes left for cipher suites
-      if (pos + 2 > buffer.length) {
-        result.error = 'Buffer too small for cipher suites length';
-        return result;
-      }
-
-      // Parse cipher suites length (2 bytes, big-endian)
-      const cipherSuitesLength = (buffer[pos] << 8) + buffer[pos + 1];
-      log(`Cipher suites length: ${cipherSuitesLength}`);
-      pos += 2;
-      
-      // Extract cipher suites
-      if (pos + cipherSuitesLength > buffer.length) {
-        result.error = 'Buffer too small for cipher suites';
-        return result;
-      }
-      
-      result.cipherSuites = buffer.slice(pos, pos + cipherSuitesLength);
-
-      // Skip cipher suites
-      pos += cipherSuitesLength;
-
-      // Check if we have enough bytes left for compression methods
-      if (pos + 1 > buffer.length) {
-        result.error = 'Buffer too small for compression methods length';
-        return result;
-      }
-
-      // Parse compression methods length (1 byte)
-      const compressionMethodsLength = buffer[pos];
-      log(`Compression methods length: ${compressionMethodsLength}`);
-      pos += 1;
-      
-      // Extract compression methods
-      if (pos + compressionMethodsLength > buffer.length) {
-        result.error = 'Buffer too small for compression methods';
-        return result;
-      }
-      
-      result.compressionMethods = buffer.slice(pos, pos + compressionMethodsLength);
-
-      // Skip compression methods
-      pos += compressionMethodsLength;
-
-      // Check if we have enough bytes for extensions length
-      if (pos + 2 > buffer.length) {
-        // No extensions present - this is valid for older TLS versions
-        result.isValid = true;
-        return result;
-      }
-
-      // Parse extensions length (2 bytes, big-endian)
-      const extensionsLength = (buffer[pos] << 8) + buffer[pos + 1];
-      log(`Extensions length: ${extensionsLength}`);
-      pos += 2;
-
-      // Extensions end position
-      const extensionsEnd = pos + extensionsLength;
-
-      // Check if extensions length is valid
-      if (extensionsEnd > buffer.length) {
-        result.error = 'Extensions length exceeds buffer size';
-        return result;
-      }
-
-      // Iterate through extensions
-      const serverNames: string[] = [];
-      
-      while (pos + 4 <= extensionsEnd) {
-        // Parse extension type (2 bytes, big-endian)
-        const extensionType = (buffer[pos] << 8) + buffer[pos + 1];
-        log(`Extension type: 0x${extensionType.toString(16).padStart(4, '0')}`);
-        pos += 2;
-
-        // Parse extension length (2 bytes, big-endian)
-        const extensionLength = (buffer[pos] << 8) + buffer[pos + 1];
-        log(`Extension length: ${extensionLength}`);
-        pos += 2;
-        
-        // Extract extension data
-        if (pos + extensionLength > extensionsEnd) {
-          result.error = `Extension ${extensionType} data exceeds bounds`;
-          return result;
-        }
-        
-        const extensionData = buffer.slice(pos, pos + extensionLength);
-        
-        // Record all extensions
-        result.extensions.push({
-          type: extensionType,
-          length: extensionLength,
-          data: extensionData
-        });
-        
-        // Track specific extension types
-        if (extensionType === TlsExtensionType.SERVER_NAME) {
-          // Server Name Indication (SNI)
-          this.parseServerNameExtension(extensionData, serverNames, logger);
-        } else if (extensionType === TlsExtensionType.SESSION_TICKET) {
-          // Session ticket
-          result.hasSessionTicket = true;
-        } else if (extensionType === TlsExtensionType.PRE_SHARED_KEY) {
-          // TLS 1.3 PSK
-          result.hasPsk = true;
-        } else if (extensionType === TlsExtensionType.EARLY_DATA) {
-          // TLS 1.3 Early Data (0-RTT)
-          result.hasEarlyData = true;
-        }
-        
-        // Move to next extension
-        pos += extensionLength;
-      }
-      
-      // Store any server names found
-      if (serverNames.length > 0) {
-        result.serverNameList = serverNames;
-      }
-      
-      // Mark as valid if we get here
-      result.isValid = true;
-      return result;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log(`Error parsing ClientHello: ${errorMessage}`);
-      result.error = errorMessage;
-      return result;
-    }
-  }
-  
-  /**
-   * Parses the server name extension data and extracts hostnames
-   * 
-   * @param data Extension data buffer
-   * @param serverNames Array to populate with found server names
-   * @param logger Optional logging function
-   * @returns true if parsing succeeded
-   */
-  private static parseServerNameExtension(
-    data: Buffer,
-    serverNames: string[],
-    logger?: LoggerFunction
-  ): boolean {
-    const log = logger || (() => {});
-    
-    try {
-      // Need at least 2 bytes for server name list length
-      if (data.length < 2) {
-        log('SNI extension too small for server name list length');
-        return false;
-      }
-      
-      // Parse server name list length (2 bytes)
-      const listLength = (data[0] << 8) + data[1];
-      
-      // Skip to first name entry
-      let pos = 2;
-      
-      // End of list
-      const listEnd = pos + listLength;
-      
-      // Validate length
-      if (listEnd > data.length) {
-        log('SNI server name list exceeds extension data');
-        return false;
-      }
-      
-      // Process all name entries
-      while (pos + 3 <= listEnd) {
-        // Name type (1 byte)
-        const nameType = data[pos];
-        pos += 1;
-        
-        // For hostname, type must be 0
-        if (nameType !== 0) {
-          // Skip this entry
-          if (pos + 2 <= listEnd) {
-            const nameLength = (data[pos] << 8) + data[pos + 1];
-            pos += 2 + nameLength;
-            continue;
-          } else {
-            log('Malformed SNI entry');
-            return false;
-          }
-        }
-        
-        // Parse hostname length (2 bytes)
-        if (pos + 2 > listEnd) {
-          log('SNI extension truncated');
-          return false;
-        }
-        
-        const nameLength = (data[pos] << 8) + data[pos + 1];
-        pos += 2;
-        
-        // Extract hostname
-        if (pos + nameLength > listEnd) {
-          log('SNI hostname truncated');
-          return false;
-        }
-        
-        // Extract the hostname as UTF-8
-        try {
-          const hostname = data.slice(pos, pos + nameLength).toString('utf8');
-          log(`Found SNI hostname: ${hostname}`);
-          serverNames.push(hostname);
-        } catch (err) {
-          log(`Error extracting hostname: ${err}`);
-        }
-        
-        // Move to next entry
-        pos += nameLength;
-      }
-      
-      return serverNames.length > 0;
-    } catch (error) {
-      log(`Error parsing SNI extension: ${error}`);
-      return false;
-    }
-  }
-  
-  /**
-   * Determines if a ClientHello contains session resumption indicators
-   * 
-   * @param buffer The ClientHello buffer
-   * @param logger Optional logging function
-   * @returns Session resumption result
-   */
-  public static hasSessionResumption(
-    buffer: Buffer,
-    logger?: LoggerFunction
-  ): SessionResumptionResult {
-    const log = logger || (() => {});
-    
-    if (!TlsUtils.isClientHello(buffer)) {
-      return { isResumption: false, hasSNI: false };
-    }
-    
-    const parseResult = this.parseClientHello(buffer, logger);
-    if (!parseResult.isValid) {
-      log(`ClientHello parse failed: ${parseResult.error}`);
-      return { isResumption: false, hasSNI: false };
-    }
-    
-    // Check resumption indicators
-    const hasSessionId = parseResult.hasSessionId;
-    const hasSessionTicket = parseResult.hasSessionTicket;
-    const hasPsk = parseResult.hasPsk;
-    const hasEarlyData = parseResult.hasEarlyData;
-    
-    // Check for SNI
-    const hasSNI = !!parseResult.serverNameList && parseResult.serverNameList.length > 0;
-    
-    // Consider it a resumption if any resumption mechanism is present
-    const isResumption = hasSessionTicket || hasPsk || hasEarlyData || 
-                         (hasSessionId && !hasPsk); // Legacy resumption
-    
-    // Log details
-    if (isResumption) {
-      log(
-        'Session resumption detected: ' +
-        (hasSessionTicket ? 'session ticket, ' : '') +
-        (hasPsk ? 'PSK, ' : '') +
-        (hasEarlyData ? 'early data, ' : '') +
-        (hasSessionId ? 'session ID' : '') +
-        (hasSNI ? ', with SNI' : ', without SNI')
-      );
-    }
-    
-    return { isResumption, hasSNI };
-  }
-  
-  /**
-   * Checks if a ClientHello appears to be from a tab reactivation 
-   * 
-   * @param buffer The ClientHello buffer 
-   * @param logger Optional logging function
-   * @returns true if it appears to be a tab reactivation
-   */
-  public static isTabReactivationHandshake(
-    buffer: Buffer,
-    logger?: LoggerFunction
-  ): boolean {
-    const log = logger || (() => {});
-    
-    if (!TlsUtils.isClientHello(buffer)) {
-      return false;
-    }
-    
-    // Parse the ClientHello
-    const parseResult = this.parseClientHello(buffer, logger);
-    if (!parseResult.isValid) {
-      return false;
-    }
-    
-    // Tab reactivation pattern: session identifier + (ticket or PSK) but no SNI
-    const hasSessionId = parseResult.hasSessionId;
-    const hasSessionTicket = parseResult.hasSessionTicket;
-    const hasPsk = parseResult.hasPsk;
-    const hasSNI = !!parseResult.serverNameList && parseResult.serverNameList.length > 0;
-    
-    if ((hasSessionId && (hasSessionTicket || hasPsk)) && !hasSNI) {
-      log('Detected tab reactivation pattern: session resumption without SNI');
-      return true;
-    }
-    
-    return false;
-  }
-}

ts/protocols/tls/sni/index.ts

@@ -1,6 +0,0 @@
-/**
- * TLS SNI (Server Name Indication) protocol utilities
- */
-
-export * from './client-hello-parser.js';
-export * from './sni-extraction.js';