v27.0.0

- Add HTTP keep-alive idle timeout (60s default) with periodic watchdog that
  skips active requests (panic-safe via RAII ActiveRequestGuard)
- Make WebSocket inactivity/max-lifetime timeouts configurable from ConnectionConfig
  instead of hardcoded 1h/24h
- Replace bare copy_bidirectional in socket handler relay with timeout+cancel-aware
  split forwarding (inactivity, max lifetime, graceful shutdown)
- Add CancellationToken to forward_bidirectional_split_with_timeouts so TLS-terminated
  TCP connections respond to graceful shutdown
- Fix graceful_stop to actually abort listener tasks that exceed the shutdown deadline
  (previously they detached and ran forever)
- Add 10s metadata parsing timeout on TS socket-handler-server to prevent stuck sockets

.gitignore

@@ -17,4 +17,5 @@ dist/
 dist_*/
 
 #------# custom
-.claude/*
+.claude/*
+rust/target

.smartconfig.json

@@ -40,5 +40,8 @@
   },
   "@ship.zone/szci": {
     "npmGlobalTools": []
+  },
+  "@git.zone/tsrust": {
+    "targets": ["linux_amd64", "linux_arm64"]
   }
 }

assets/certs/cert.pem

@@ -1,19 +1,20 @@
 -----BEGIN CERTIFICATE-----
-MIIDCzCCAfOgAwIBAgIUPU4tviz3ZvsMDjCz1NZRT16b0Y4wDQYJKoZIhvcNAQEL
-BQAwFTETMBEGA1UEAwwKcHVzaC5yb2NrczAeFw0yNTAyMDMyMzA5MzRaFw0yNjAy
-MDMyMzA5MzRaMBUxEzARBgNVBAMMCnB1c2gucm9ja3MwggEiMA0GCSqGSIb3DQEB
-AQUAA4IBDwAwggEKAoIBAQCZMkBYD/pYLBv9MiyHTLRT24kQyPeJBtZqryibi1jk
-BT1ZgNl3yo5U6kjj/nYBU/oy7M4OFC0xyaJQ4wpvLHu7xzREqwT9N9WcDcxaahUi
-P8+PsjGyznPrtXa1ASzGAYMNvXyWWp3351UWZHMEs6eY/Y7i8m4+0NwP5h8RNBCF
-KSFS41Ee9rNAMCnQSHZv1vIzKeVYPmYnCVmL7X2kQb+gS6Rvq5sEGLLKMC5QtTwI
-rdkPGpx4xZirIyf8KANbt0sShwUDpiCSuOCtpze08jMzoHLG9Nv97cJQjb/BhiES
-hLL+YjfAUFjq0rQ38zFKLJ87QB9Jym05mY6IadGQLXVXAgMBAAGjUzBRMB0GA1Ud
-DgQWBBQjpowWjrql/Eo2EVjl29xcjuCgkTAfBgNVHSMEGDAWgBQjpowWjrql/Eo2
-EVjl29xcjuCgkTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQAY
-44vqbaf6ewFrZC0f3Kk4A10lC6qjWkcDFfw+JE8nzt+4+xPqp1eWgZKF2rONyAv2
-nG41Xygt19ByancXLU44KB24LX8F1GV5Oo7CGBA+xtoSPc0JulXw9fGclZDC6XiR
-P/+vhGgCHicbfP2O+N00pOifrTtf2tmOT4iPXRRo4TxmPzuCd+ZJTlBhPlKCmICq
-yGdAiEo6HsSiP+M5qVlNx8s57MhQYk5TpgmI6FU4mO7zfDfSatFonlg+aDbrnaqJ
-v/+km02M+oB460GmKwsSTnThHZgLNCLiKqD8bdziiCQjx5u0GjLI6468o+Aehb8l
-l/x9vWTTk/QKq41X5hFk
+MIIDQTCCAimgAwIBAgIUJm+igT1AVSuwNzjvqjSF6cysw6MwDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI2MDIxMzIyMzI1MloXDTM2MDIx
+MTIyMzI1MlowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEAyjitkDd4DdlVk4TfVxKUqdxnJCGj9uyrUPAqR8hB6+bR
++8rW63ryBNYNRizxOGw41E19ascNuyA98mUF4oqjid1K4VqDiKzv1Uq/3NUunCw/
+rEddR5hCoVkTsBJjzNgBJqncS606v0hfA00cCkpGR+Te7Q/E8T8lApioz1zFQ05Y
+C69oeJHIrJcrIkIFAgmXDgRF0Z4ErUeu+wVOWT267uVAYn5AdFMxCSIBsYtPseqy
+cC5EQ6BCBtsIGitlRgzLRg957ZZa+SF38ao+/ijYmOLHpQT0mFaUyLT7BKgxguGs
+8CHcIxN5Qo27J3sC5ymnrv2uk5DcAOUcxklXUbVCeQIDAQABo4GKMIGHMB0GA1Ud
+DgQWBBShZhz7aX/KhleAfYKvTgyG5ANuDjAfBgNVHSMEGDAWgBShZhz7aX/KhleA
+fYKvTgyG5ANuDjAPBgNVHRMBAf8EBTADAQH/MDQGA1UdEQQtMCuCCWxvY2FsaG9z
+dIIKcHVzaC5yb2Nrc4IMKi5wdXNoLnJvY2tzhwR/AAABMA0GCSqGSIb3DQEBCwUA
+A4IBAQAyUvjUszQp4riqa3CfBFFtjh+7DKNuQPOlYAwSEis4l+YK06Glx4fJBHcx
+eCPhQ/0wnPzi6CZe3vVRXd5fX27nVs+lMQD6Oc47F8OmTU6NXnb/1AcvrycDsP8D
+9Y9qecekbpegrN1W4D46goBAwvrd6Qy0EHi0Z5z02rfyXAdxm0OmdpuWoIMcEgUQ
+YyXIq3zSFE6uoO61WdLvBcXN6iaiSTVy0605WncDe2+UT9MeNq6zi1JD34jsgUrd
+xq0WRUk2C6C4Irkf00Q12rXeL+Jv5OwyrUUZRvz0gLgG02UUbB/6Ca5GYNXniEuI
+Py/EHTqbtjLIs7HxYjQH86FI9fUj
 -----END CERTIFICATE-----

assets/certs/key.pem

@@ -1,28 +1,28 @@
 -----BEGIN PRIVATE KEY-----
-MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCZMkBYD/pYLBv9
-MiyHTLRT24kQyPeJBtZqryibi1jkBT1ZgNl3yo5U6kjj/nYBU/oy7M4OFC0xyaJQ
-4wpvLHu7xzREqwT9N9WcDcxaahUiP8+PsjGyznPrtXa1ASzGAYMNvXyWWp3351UW
-ZHMEs6eY/Y7i8m4+0NwP5h8RNBCFKSFS41Ee9rNAMCnQSHZv1vIzKeVYPmYnCVmL
-7X2kQb+gS6Rvq5sEGLLKMC5QtTwIrdkPGpx4xZirIyf8KANbt0sShwUDpiCSuOCt
-pze08jMzoHLG9Nv97cJQjb/BhiEShLL+YjfAUFjq0rQ38zFKLJ87QB9Jym05mY6I
-adGQLXVXAgMBAAECggEARGCBBq1PBHbfoUH5TQSIAlvdEEBa9+602lZG7jIioVfT
-W7Uem5Ctuan+kcDcY9hbNsqqZ+9KgsvoJmlIGXoF2jjeE/4vUmRO9AHWoc5yk2Be
-4NjcxN3QMLdEfiLBnLlFCOd4CdX1ZxZ6TG3WRpV3a1pVIeeqHGB1sKT6Xd/atcwG
-RvpiXzu0SutGxVb6WE9r6hovZ4fVERCyCRczUGrUH5ICbxf6E7L4u8xjEYR4uEKK
-/8ZkDqrWdRASDAdPPMNqnHUEAho/WnxpNeb6B4lvvv2QWxIS9H1OikF/NzWPgVNS
-oPpvtJgjyo5xdgLm3zE4lcSPNVSrh1TBXuAn9TG4WQKBgQDScPFkUNBqjC5iPMof
-bqDHlhlptrHmiv9LC0lgjEDPgIEQfjLfdCugwDk32QyAcb5B60upDYeqCFDkfV/C
-T536qxevYPjPAjahLPHqMxkWpjvtY6NOTgbbcpVtblU2Fj8R8qbyPNADG31LicU9
-GVPtQ4YcVaMWCYbg5107+9dFWQKBgQC6XK+foKK+81RFdrqaNNgebTWTsANnBcZe
-xl0bj6oL5yY0IzroxHvgcNS7UMriWCu+K2xfkUBdMmxU773VN5JQ5k15ezjgtrvc
-8oAaEsxYP4su12JSTC/zsBANUgrNbFj8++qqKYWt2aQc2O/kbZ4MNfekIVFc8AjM
-2X9PxvxKLwKBgHXL7QO3TQLnVyt8VbQEjBFMzwriznB7i+4o8jkOKVU93IEr8zQr
-5iQElcLSR3I6uUJTALYvsaoXH5jXKVwujwL69LYiNQRDe+r6qqvrUHbiNJdsd8Rk
-XuhGGqj34tD04Pcd+h+MtO+YWqmHBBZwcA9XBeIkebbjPFH2kLT8AwN5AoGAYQy9
-hMJxnkE3hIkk+gNE/OtgeE20J+Vw/ZANkrnJEzPHyGUEW41e+W2oyvdzAFZsSTdx
-037f5ujIU58Z27x53NliRT4vS4693H0Iyws5EUfeIoGVuUflvODWKymraHjhCrXh
-6cV/0R5DAabTnsCbCr7b/MRBC8YQvyUQ0KnOXo8CgYBQYGpvJnSWyvsCjtb6apTP
-drjcBhVd0aSBpLGtDdtUCV4oLl9HPy+cLzcGaqckBqCwEq5DKruhMEf7on56bUMd
-m/3ItFk1TnhysAeJHb3zLqmJ9CKBitpqLlsOE7MEXVNmbTYeXU10Uo9yOfyt1i7T
-su+nT5VtyPkmF/l4wZl5+g==
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKOK2QN3gN2VWT
+hN9XEpSp3GckIaP27KtQ8CpHyEHr5tH7ytbrevIE1g1GLPE4bDjUTX1qxw27ID3y
+ZQXiiqOJ3UrhWoOIrO/VSr/c1S6cLD+sR11HmEKhWROwEmPM2AEmqdxLrTq/SF8D
+TRwKSkZH5N7tD8TxPyUCmKjPXMVDTlgLr2h4kcislysiQgUCCZcOBEXRngStR677
+BU5ZPbru5UBifkB0UzEJIgGxi0+x6rJwLkRDoEIG2wgaK2VGDMtGD3ntllr5IXfx
+qj7+KNiY4selBPSYVpTItPsEqDGC4azwIdwjE3lCjbsnewLnKaeu/a6TkNwA5RzG
+SVdRtUJ5AgMBAAECggEAEM8piTp9I5yQVxr1RCv+mMiB99BGjHrTij6uawlXxnPJ
+Ol574zbU6Yc/8vh/JB8l0arvzQmHCAoX8B9K4BABZE81X1paYujqJi8ImAMN9Owe
+LlQ/yhjbWAVbJDiBHHjLjrLRpaY8gwQxZqk5FpdiNG1vROIZzypeKZM2PAdke9HA
+PvJtsyfXdEz+jb5EUgaadyn7aquR6y607a8m55y34POLOcssteUOje4GdrTekHK0
+62E+iEnawBjIs7gBzJf0j1XjFNq3aAeLrn8gFCEb+yK7X++8FJ8YjwsqS5V1aMsR
+1PZguW0jCzYHATc2OcIozlvdBriPxy7eX8Y3MFvNMQKBgQD22ReUyKX5TKA/fg3z
+S/QGfYqd4T35jkwK1MaXOuFOBzNyTMT6ZJkbjxPOYPB0uakcfIlva8bI77mE5vRe
+PWYlvitp9Zz3v2kt/WgnwG32ZdVedPjEoi9aitUXmiiIoxdPVAUAgLPFFN65Sr2G
+2NM/vduZcAPUr0UWnFx4dlpo8QKBgQDRuAV44Y+1396511oW4OR8ofWFECMc5uEV
+wQ26EpbilEYhRSBty+1PAK5AcEGybeVtUn9RSmx0Ef1L15wnzP/C886LIzkaig/9
+xs0yudXgOFdBAzYQKnK2lZmSKkzcUFJtifat3E+ZMCo/duhzXpzecg/lVNGh6gcx
+xbtphJCyCQKBgEO8zvvFE8aVgGPr82gQL6aYTLGGXbtdkQBn4xcc0TbYQwXaizMq
+59joKkc30sQ1LnLiudQZfzMklYQi3Gv/7UfuJ3usKqbRn8s+/pXp+ELlLuf8sUdE
+OjpeXptbckQMfRkHtVet+abbU0MFf3zBgza6osg4NNToQ80wmy9zStwBAoGAGLeD
+jZeoBFt6OJT0/TVMOJQuB5y7RrC/Xnz+TSvbtKCdE1a+V7JtKZ5+6wFP/OOO4q+S
+adZHqfZk0Ad9VAOJMUTi1usz07jp4ZMIpC3a0y5QukzSll0qX/KJwvxRSrX8wQQ9
+mogYqYlPsWMmSlKgUmdHEFRK0LZwWqFfUTRaiWECgYEA6KR6KMbqnYn5CglHeD42
+NmOgFYXljRLIxS1coTiWWQZM/nUyx/tSk+MAS7770USHoZhAfh6lmEa/AeKSoLVl
+Su3yzgtKk1/doAtbiWD8TasHAhacwWmzTuZtH5cZUgW3QIVJg6ADi6m8zswqKxIS
+qfU/1N4aHp832v4ggRe/Og0=
 -----END PRIVATE KEY-----

changelog.md

@@ -1,5 +1,800 @@
 # Changelog
 
+## 2026-03-26 - 27.0.0 - BREAKING CHANGE(smart-proxy)
+remove route helper APIs and standardize route configuration on plain route objects
+
+- Removes TypeScript route helper exports and related Rust config helpers in favor of defining routes directly with match and action properties.
+- Updates documentation and tests to use plain IRouteConfig objects and SocketHandlers imports instead of helper factory functions.
+- Moves socket handlers to a top-level utils export and keeps direct socket-handler route configuration as the supported pattern.
+
+## 2026-03-26 - 26.3.0 - feat(nftables)
+move NFTables forwarding management from the Rust engine to @push.rocks/smartnftables
+
+- add @push.rocks/smartnftables as a runtime dependency and export it via the plugin layer
+- remove the internal rustproxy-nftables crate along with Rust-side NFTables rule application and status management
+- apply and clean up NFTables port-forwarding rules in the TypeScript SmartProxy lifecycle and route update flow
+- change getNfTablesStatus to return local smartnftables status instead of querying the Rust bridge
+- update README documentation to describe NFTables support as provided through @push.rocks/smartnftables
+
+## 2026-03-26 - 26.2.4 - fix(rustproxy-http)
+improve HTTP/3 connection reuse and clean up stale proxy state
+
+- Reuse pooled HTTP/3 SendRequest handles to skip repeated SETTINGS handshakes and reduce request overhead on QUIC pool hits
+- Add periodic cleanup for per-route rate limiters and orphaned backend metrics to prevent unbounded memory growth after traffic or backend errors stop
+- Enforce HTTP max connection lifetime alongside idle timeouts and apply configured lifetime values from the TCP listener
+- Reduce HTTP/3 body copying by using owned Bytes paths for request and response streaming, and replace the custom response body adapter with a stream-based implementation
+- Harden auxiliary proxy components by capping datagram handler buffer growth and removing duplicate RustProxy exit listeners
+
+## 2026-03-25 - 26.2.3 - fix(repo)
+no changes to commit
+
+
+## 2026-03-25 - 26.2.2 - fix(proxy)
+improve connection cleanup and route validation handling
+
+- add timeouts for HTTP/1 upstream connection drivers to prevent lingering tasks
+- ensure QUIC relay sessions cancel and abort background tasks on drop
+- avoid registering unnamed routes as duplicates and label unnamed catch-all conflicts clearly
+- fix offset mapping route helper to forward only remaining route options without overriding derived values
+- update project config filename and toolchain versions for the current build setup
+
+## 2026-03-23 - 26.2.1 - fix(rustproxy-http)
+include the upstream request URL when caching H3 Alt-Svc discoveries
+
+- Tracks the request path that triggered Alt-Svc discovery in connection activity state
+- Adds request URL context to Alt-Svc debug logging and protocol cache insertion reasons for better traceability
+
+## 2026-03-23 - 26.2.0 - feat(protocol-cache)
+add sliding TTL re-probing and eviction for backend protocol detection
+
+- extend protocol cache entries and metrics with last accessed and last probed timestamps
+- trigger periodic ALPN re-probes for cached H1/H2 entries while keeping active entries alive with a sliding 1 day TTL
+- log protocol transitions with reasons and evict cache entries when all protocol fallback attempts fail
+
+## 2026-03-22 - 26.1.0 - feat(rustproxy-http)
+add protocol failure suppression, h3 fallback escalation, and protocol cache metrics exposure
+
+- introduces escalating cooldowns for failed H2/H3 protocol detection to prevent repeated upgrades to unstable backends
+- adds within-request escalation to cached HTTP/3 when TCP or TLS backend connections fail in auto-detect mode
+- exposes detected protocol cache entries and suppression state through Rust metrics and the TypeScript metrics adapter
+
+## 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
+
+- Load updated TLS configs before swapping the route manager so newly visible routes always have their certificates available.
+- Add timeouts when peeking initial decrypted data after TLS handshake to avoid leaked idle connections.
+- Raise dropped, blocked, unmatched, and errored passthrough connection events from debug to warn for better operational visibility.
+
+## 2026-03-16 - 25.11.6 - fix(rustproxy-http,rustproxy-passthrough)
+improve upstream connection cleanup and graceful tunnel shutdown
+
+- Evict pooled HTTP/2 connections when their driver exits and shorten the maximum pooled H2 age to reduce reuse of stale upstream connections.
+- Strip hop-by-hop headers from backend responses before forwarding to HTTP/2 clients to avoid invalid H2 response handling.
+- Replace immediate task aborts in WebSocket and TCP tunnel watchdogs with cancellation-driven graceful shutdown plus timed fallback aborts.
+- Use non-blocking semaphore acquisition in the TCP listener so connection limits do not stall the accept loop for the entire port.
+
+## 2026-03-16 - 25.11.5 - fix(repo)
+no changes to commit
+
+
+## 2026-03-15 - 25.11.4 - fix(rustproxy-http)
+report streamed HTTP and WebSocket bytes per chunk for real-time throughput metrics
+
+- Update CountingBody to record bytes immediately on each data frame instead of aggregating until completion or drop
+- Record WebSocket tunnel traffic inside both copy loops and remove the final aggregate byte report to keep throughput metrics current
+
+## 2026-03-15 - 25.11.3 - fix(repo)
+no changes to commit
+
+
+## 2026-03-15 - 25.11.2 - fix(rustproxy-http)
+avoid reusing HTTP/1 senders during streaming responses and relax HTTP/2 keep-alive timeouts
+
+- Stop returning HTTP/1 senders to the connection pool before upstream response bodies finish streaming to prevent unsafe reuse on active connections.
+- Increase HTTP/2 keep-alive timeout from 5 seconds to 30 seconds in proxy connection builders to better support longer-lived backend streams.
+- Improves reliability for large streaming payloads and backend fallback request handling.
+
+## 2026-03-15 - 25.11.1 - fix(rustproxy-http)
+keep connection idle tracking alive during streaming and tune HTTP/2 connection lifetimes
+
+- Propagate connection activity tracking through HTTP/1, HTTP/2, and WebSocket forwarding so active request and response body streams do not trigger the idle watchdog.
+- Update CountingBody to refresh connection activity timestamps while data frames are polled during uploads and downloads.
+- Increase pooled HTTP/2 max age and set explicit HTTP/2 connection window sizes to improve long-lived streaming behavior.
+
+## 2026-03-15 - 25.11.0 - feat(rustproxy-http)
+add HTTP/2 Extended CONNECT WebSocket proxy support
+
+- Enable HTTP/2 CONNECT protocol support on the Hyper auto connection builder
+- Detect WebSocket requests for both HTTP/1 Upgrade and HTTP/2 Extended CONNECT flows
+- Translate HTTP/2 WebSocket requests to an HTTP/1.1 backend handshake and return RFC-compliant client responses
+
+## 2026-03-12 - 25.10.7 - fix(rustproxy-http)
+remove Host header from HTTP/2 upstream requests while preserving it for HTTP/1 retries
+
+- strips the Host header before sending HTTP/2 upstream requests so :authority from the URI is used instead
+- avoids 400 responses from nginx caused by sending both Host and :authority headers
+- keeps a cloned header set for bodyless request retries so HTTP/1 fallback still retains the Host header
+
+## 2026-03-12 - 25.10.6 - fix(rustproxy-http)
+use the requested domain as HTTP/2 authority instead of the backend host and port
+
+- build HTTP/2 absolute URIs from the client-facing domain so the :authority pseudo-header matches the Host header
+- remove backend port from generated HTTP/2 request URIs and fall back to the upstream host only when no domain is available
+- apply the authority handling consistently across pooled, inline, and generic upstream request paths
+
+## 2026-03-12 - 25.10.5 - fix(rustproxy-http)
+configure HTTP/2 client builders with a Tokio timer for keep-alive handling
+
+- Adds TokioTimer to all HTTP/2 client builder instances in proxy_service.
+- Ensures configured HTTP/2 keep-alive interval and timeout settings have the required timer runtime support.
+
+## 2026-03-12 - 25.10.4 - fix(rustproxy-http)
+stabilize upstream HTTP/2 forwarding and fallback behavior
+
+- Remove hop-by-hop headers before forwarding requests to HTTP/2 backends to comply with RFC 9113.
+- Use ALPN-enabled TLS configuration whenever HTTP/2 is possible, including explicit H2 connections and retries.
+- Add HTTP/2 handshake timeouts, tuned connection settings, and fallback to HTTP/1 when H2 negotiation times out or fails.
+- Register pooled HTTP/2 senders only after a successful first request to avoid reusing broken connections.
+- Build absolute URIs for HTTP/2 upstream requests so pseudo-headers such as scheme and authority are derived correctly.
+
+## 2026-03-12 - 25.10.3 - fix(rustproxy-http)
+include request domain in backend proxy error and protocol detection logs
+
+- Adds domain context to backend TCP/TLS connect, handshake, request failure, retry, and fallback log entries in the Rust HTTP proxy service.
+- Propagates the resolved host/domain through H1, H2, pooled, and fallback forwarding paths so backend-level diagnostics can be correlated with the original request domain.
+
+## 2026-03-12 - 25.10.2 - fix(repo)
+no code changes to release
+
+
+## 2026-03-12 - 25.10.1 - fix(repo)
+no changes to commit
+
+
+## 2026-03-12 - 25.10.0 - feat(metrics)
+add per-backend connection, error, protocol, and pool metrics with stale backend pruning
+
+- tracks backend connection lifecycle, connect timing, protocol detection, pool hit/miss rates, handshake/request errors, and h2 fallback failures in Rust metrics
+- exposes backend metrics through the TypeScript metrics adapter with backend listings, protocol lookup, and top error summaries
+- prunes backend metrics for backends no longer referenced by active routes, including preserved-port targets expanded across listening ports
+
+## 2026-03-11 - 25.9.3 - fix(rustproxy-http)
+Evict stale HTTP/2 pooled senders and retry bodyless requests with fresh backend connections to avoid 502s
+
+- Introduce MAX_H2_AGE (120s) and evict HTTP/2 senders older than this or closed
+- Check MAX_H2_AGE on checkout and during background eviction to prevent reuse of stale h2 connections
+- Add connection_pool.remove_h2() to explicitly remove dead H2 senders from the pool
+- When a pooled H2 request returns a 502 and the original request had an empty body, retry using a fresh H2 connection (retry_h2_with_fresh_connection)
+- On H2 auto-detect failures, retry as HTTP/1.1 for bodyless requests via forward_h1_empty_body; return 502 for requests with bodies
+- Evict dead H2 senders on backend request failures in reconnect_backend so subsequent attempts create fresh connections
+
+## 2026-03-08 - 25.9.2 - fix(protocol-cache)
+Include requested_host in protocol detection cache key to avoid cache oscillation when multiple frontend domains share the same backend
+
+- Add ProtocolCacheKey.requested_host: Option<String> to distinguish cache entries by incoming request Host/:authority
+- Update protocol cache lookups/inserts in proxy_service to populate requested_host
+- Enhance debug logging to show requested_host on cache hits
+- Fixes repeated ALPN probing / cache oscillation when different frontend domains share a backend with differing HTTP/2 support
+
+## 2026-03-03 - 25.9.1 - fix(rustproxy)
+Cancel connections for routes removed/disabled by adding per-route cancellation tokens and make RouteManager swappable (ArcSwap) for runtime updates
+
+- Add per-route CancellationToken map (DashMap) to TcpListenerManager and call token.cancel() when routes are removed (invalidate_removed_routes)
+- Propagate Arc<ArcSwap<RouteManager>> into HttpProxyService and passthrough listener so the route manager can be hot-swapped without restarting listeners
+- Use per-route child cancellation tokens in accept/connection handling and forwarders to terminate existing connections when a route is removed
+- Prune HTTP proxy caches and retain/cleanup per-route tokens when routes are active/removed
+- Update test.test.sni-requirement.node.ts to allocate unique free ports via findFreePorts to avoid port conflicts during tests
+
+## 2026-03-03 - 25.9.0 - feat(rustproxy-http)
+add HTTP/2 auto-detection via ALPN with TTL-backed protocol cache and h1-only/h2 ALPN client configs
+
+- Add protocol_cache module: bounded, TTL-based cache (5min TTL), max entries (4096), background cleanup task and clear() to discard stale detections.
+- Introduce BackendProtocol::Auto and expose 'auto' in TypeScript route types to allow ALPN-based protocol auto-detection.
+- Add build_tls_acceptor_h1_only() to create a TLS acceptor that advertises only http/1.1 (used for backends/tests that speak plain HTTP/1.1).
+- Add shared_backend_tls_config_alpn() and default_backend_tls_config_with_alpn() to provide client TLS configs advertising h2+http/1.1 for auto-detection.
+- Wire backend_tls_config_alpn and protocol_cache into proxy_service, tcp_listener and passthrough paths; add set_backend_tls_config_alpn() and prune protocol_cache on route updates.
+- Update passthrough tests to use h1-only acceptor to avoid false HTTP/2 detection when backends speak plain HTTP/1.1.
+- Include reconnection/fallback handling and ensure ALPN-enabled client config is used for auto-detection mode.
+
+## 2026-02-26 - 25.8.5 - fix(release)
+bump patch version (no source changes)
+
+- No changes detected in git diff
+- Current version: 25.8.4
+- Recommend patch bump to 25.8.5 to record release without code changes
+
+## 2026-02-26 - 25.8.4 - fix(proxy)
+adjust default proxy timeouts and keep-alive behavior to shorter, more consistent values
+
+- Increase connection timeout default from 30,000ms to 60,000ms (30s -> 60s).
+- Reduce socket timeout default from 3,600,000ms to 60,000ms (1h -> 60s).
+- Reduce max connection lifetime default from 86,400,000ms to 3,600,000ms (24h -> 1h).
+- Change inactivity timeout default from 14,400,000ms to 75,000ms (4h -> 75s).
+- Update keep-alive defaults: keepAliveTreatment 'extended' -> 'standard', keepAliveInactivityMultiplier 6 -> 4, extendedKeepAliveLifetime 604800000 -> 3,600,000ms (7d -> 1h).
+- Apply these consistent default values across Rust crates (rustproxy-config, rustproxy-passthrough) and the TypeScript smart-proxy implementation.
+- Update unit test expectations to match the new defaults.
+
+## 2026-02-26 - 25.8.3 - fix(smartproxy)
+no code or dependency changes detected; no version bump required
+
+- No files changed in the provided diff (No changes).
+- package.json version remains 25.8.2.
+- No dependency or source updates detected; skip release.
+
+## 2026-02-26 - 25.8.2 - fix(connection)
+improve connection handling and timeouts
+
+- Flush logs on process beforeExit and avoid calling process.exit in SIGINT/SIGTERM handlers to preserve host graceful shutdown
+- Store protocol entries with a createdAt timestamp in ProtocolDetector and remove stale entries older than 30s to prevent leaked state from abandoned handshakes or port scanners
+- Add backend connect timeout (30s) and idle timeouts (5 minutes) for dynamic forwards; destroy sockets on timeout and emit logs for timeout events
+
+## 2026-02-25 - 25.8.1 - fix(allocator)
+switch global allocator from tikv-jemallocator to mimalloc
+
+- Replaced tikv-jemallocator with mimalloc in rust/Cargo.toml workspace dependencies.
+- Updated rust/crates/rustproxy/Cargo.toml to use mimalloc as a workspace dependency.
+- Updated rust/Cargo.lock: added mimalloc and libmimalloc-sys entries and removed tikv-jemallocator and tikv-jemalloc-sys entries.
+- Changed the global allocator in crates/rustproxy/src/main.rs from tikv_jemallocator::Jemalloc to mimalloc::MiMalloc.
+- Impact: runtime memory allocator is changed which may affect memory usage and performance; no public API changes but recommend testing memory/performance in deployments.
+
+## 2026-02-24 - 25.8.0 - feat(rustproxy)
+use tikv-jemallocator as the global allocator to reduce glibc fragmentation and slow RSS growth; add allocator dependency and enable it in rustproxy, update lockfile, and run tsrust before tests
+
+- Added tikv-jemallocator dependency to rust/Cargo.toml and rust/crates/rustproxy/Cargo.toml
+- Enabled tikv_jemallocator as the global allocator in rust/crates/rustproxy/src/main.rs
+- Updated rust/Cargo.lock with tikv-jemallocator and tikv-jemalloc-sys entries
+- Modified package.json test script to run tsrust before tstest
+
+## 2026-02-24 - 25.7.10 - fix(rustproxy)
+Use cooperative cancellation for background tasks, prune stale caches and metric entries, and switch tests to dynamic port allocation to avoid port conflicts
+
+- Introduce tokio_util::sync::CancellationToken to coordinate graceful shutdown of sampling and renewal tasks; await handles on stop and reset the token so the proxy can be restarted.
+- Add safety Drop impls (RustProxy, TcpListenerManager) as a last-resort abort path when stop() is not called.
+- MetricsCollector: avoid creating per-IP metric entries when the IP has no active connections; prune orphaned per-IP metric maps during sampling; add tests covering late record_bytes races and pruning behavior.
+- Passthrough/ConnectionTracker: remove per-connection record/zombie-scanner complexity, add cleanup_stale_timestamps to prune rate-limit timestamp entries, and add an RAII ConnectionTrackerGuard to guarantee connection_closed is invoked.
+- HTTP proxy improvements: add prune_stale_routes and reset_round_robin to clear caches (rate limiters, regex cache, round-robin counters) on route updates.
+- Tests: add test/helpers/port-allocator.ts and update many tests to use findFreePorts/assertPortsFree (dynamic ports + post-test port assertions) to avoid flakiness and port collisions in CI.
+
+## 2026-02-21 - 25.7.9 - fix(tests)
+use high non-privileged ports in tests to avoid conflicts and CI failures
+
+- Updated multiple test files to use high-range, non-privileged ports instead of well-known or conflicting ports.
+- Files changed: test/test.acme-http01-challenge.ts, test/test.connection-forwarding.ts, test/test.forwarding-regression.ts, test/test.http-port8080-forwarding.ts, test/test.port-mapping.ts, test/test.smartproxy.ts, test/test.socket-handler.ts.
+- Notable port remappings: 8080/8081 -> 47730/47731 (and other proxy ports like 47710), 8443 -> 47711, 7001/7002 -> 47712/47713, 9090 -> 47721, 8181/8182 -> 47732/47733, 9999 -> 47780, TEST_PORT_START/PROXY_PORT_START -> 47750/48750, and TEST_SERVER_PORT/PROXY_PORT -> 47770/47771.
+
+## 2026-02-19 - 25.7.8 - fix(no-changes)
+no changes detected; nothing to release
+
+- Current package version: 25.7.7
+- Git diff: no changes
+- No files modified; no release necessary
+
+## 2026-02-19 - 25.7.7 - fix(proxy)
+restrict PROXY protocol parsing to configured trusted proxy IPs and parse PROXY headers before metrics/fast-path so client IPs reflect the real source
+
+- Add proxy_ips: Vec<std::net::IpAddr> to ConnectionConfig with a default empty Vec
+- Populate proxy_ips from options.proxy_ips strings in rust/crates/rustproxy/src/lib.rs, parsing each to IpAddr
+- Only peek for and parse PROXY v1 headers when the remote IP is contained in proxy_ips (prevents untrusted clients from injecting PROXY headers)
+- Move PROXY protocol parsing earlier so metrics and fast-path logic use the effective (real client) IP after PROXY parsing
+- If proxy_ips is empty, behavior remains unchanged (no PROXY parsing)
+
+## 2026-02-19 - 25.7.6 - fix(throughput)
+add tests for per-IP connection tracking and throughput history; assert per-IP eviction after connection close to prevent memory leak
+
+- Adds runtime assertions for per-IP TCP connection tracking (m.connections.byIP) while a connection is active
+- Adds checks for throughput history (m.throughput.history) to ensure history length and timestamps are recorded
+- Asserts that per-IP tracking data is evicted after connection close (byIP.size === 0) to verify memory leak fix
+- Reorders test checks so per-IP and history metrics are validated during the active connection and totals are validated after close
+
+## 2026-02-19 - 25.7.5 - fix(rustproxy)
+prune stale per-route metrics, add per-route rate limiter caching and regex cache, and improve connection tracking cleanup to prevent memory growth
+
+- Prune per-route metrics for routes removed from configuration via MetricsCollector::retain_routes invoked during route table updates
+- Introduce per-route shared RateLimiter instances (DashMap) with a request-count-triggered periodic cleanup to avoid stale limiters
+- Cache compiled URL-rewrite regexes (regex_cache) to avoid recompiling patterns on every request and insert compiled regex on first use
+- Improve upstream connection tracking to remove zero-count entries and guard against underflow, preventing unbounded DashMap growth
+- Evict per-IP metrics and timestamps when the last connection for an IP closes so per-IP DashMap entries are fully freed
+- Add unit tests validating connection tracking cleanup, per-IP eviction, and route-metrics retention behavior
+
+## 2026-02-19 - 25.7.4 - fix(smart-proxy)
+include proxy IPs in smart proxy configuration
+
+- Add proxyIps: this.settings.proxyIPs to proxy options in ts/proxies/smart-proxy/smart-proxy.ts
+- Ensures proxy IPs from settings are passed into the proxy implementation (enables proxy IP filtering/whitelisting)
+
+## 2026-02-16 - 25.7.3 - fix(metrics)
+centralize connection-closed reporting via ConnectionGuard and remove duplicate explicit metrics.connection_closed calls
+
+- Removed numerous explicit metrics.connection_closed calls from rust/crates/rustproxy-http/src/proxy_service.rs so connection teardown and byte counting are handled by the connection guard / counting body instead of ad-hoc calls.
+- Simplified ConnectionGuard in rust/crates/rustproxy-passthrough/src/tcp_listener.rs: removed the disarm flag and disarm() method so Drop always reports connection_closed.
+- Stopped disarming the TCP-level guard when handing connections off to HTTP proxy paths (HTTP/WebSocket/streaming flows) to avoid missing or double-reporting metrics.
+- Fixes incorrect/duplicate connection-closed metric emission and ensures consistent byte/connection accounting during streaming and WebSocket upgrades.
+
+## 2026-02-16 - 25.7.2 - fix(rustproxy-http)
+preserve original Host header when proxying and add X-Forwarded-* headers; add TLS WebSocket echo backend helper and integration test for terminate-and-reencrypt websocket
+
+- Preserve the client's original Host header instead of replacing it with backend host:port when proxying requests.
+- Add standard reverse-proxy headers: X-Forwarded-For (appends client IP), X-Forwarded-Host, and X-Forwarded-Proto for upstream requests.
+- Ensure raw TCP/HTTP upstream requests copy original headers and skip X-Forwarded-* (which are added explicitly).
+- Add start_tls_ws_echo_backend test helper to start a TLS WebSocket echo backend for tests.
+- Add integration test test_terminate_and_reencrypt_websocket to verify WS upgrade through terminate-and-reencrypt TLS path.
+- Rename unused parameter upstream to _upstream in proxy_service functions to avoid warnings.
+
+## 2026-02-16 - 25.7.1 - fix(proxy)
+use TLS to backends for terminate-and-reencrypt routes
+
+- Set upstream.use_tls = true when a route's TLS mode is TerminateAndReencrypt so the proxy re-encrypts to backend servers.
+- Add start_tls_http_backend test helper and update integration tests to run TLS-enabled backend servers validating re-encryption behavior.
+- Make the selected upstream mutable to allow toggling the use_tls flag during request handling.
+
+## 2026-02-16 - 25.7.0 - feat(routes)
+add protocol-based route matching and ensure terminate-and-reencrypt routes HTTP through the full HTTP proxy; update docs and tests
+
+- Introduce a new 'protocol' match field for routes (supports 'http' and 'tcp') and preserve it through cloning/merging.
+- Add Rust integration test verifying terminate-and-reencrypt decrypts TLS and routes HTTP traffic via the HTTP proxy (per-request Host/path routing) instead of raw tunneling.
+- Add TypeScript unit tests covering protocol field validation, preservation, interaction with terminate-and-reencrypt, cloning, merging, and matching behavior.
+- Update README with a Protocol-Specific Routing section and clarify terminate-and-reencrypt behavior (HTTP routed via HTTP proxy; non-HTTP uses raw TLS-to-TLS tunnel).
+- Example config: include health check thresholds (unhealthyThreshold and healthyThreshold) in the sample healthCheck settings.
+
+## 2026-02-16 - 25.6.0 - feat(rustproxy)
+add protocol-based routing and backend TLS re-encryption support
+
+- Introduce optional route_match.protocol ("http" | "tcp") in Rust and TypeScript route types to allow protocol-restricted routing.
+- RouteManager: respect protocol field during matching and treat TLS connections without SNI as not matching domain-restricted routes (except wildcard-only routes).
+- HTTP proxy: add BackendStream abstraction to unify plain TCP and tokio-rustls TLS backend streams, and support connecting to upstreams over TLS (upstream.use_tls) with an InsecureBackendVerifier for internal/self-signed backends.
+- WebSocket and HTTP forwarding updated to use BackendStream so upstream TLS is handled transparently.
+- Passthrough listener: perform post-termination protocol detection for TerminateAndReencrypt; route HTTP flows into HttpProxyService and handle non-HTTP as TLS-to-TLS tunnel.
+- Add tests for protocol matching, TLS/no-SNI behavior, and other routing edge cases.
+- Add rustls and tokio-rustls dependencies (Cargo.toml/Cargo.lock updates).
+
+## 2026-02-16 - 25.5.0 - feat(tls)
+add shared TLS acceptor with SNI resolver and session resumption; prefer shared acceptor and fall back to per-connection when routes specify custom TLS versions
+
+- Add CertResolver that pre-parses PEM certs/keys into CertifiedKey instances for SNI-based lookup and cheap runtime resolution
+- Introduce build_shared_tls_acceptor to create a shared ServerConfig with session cache (4096) and Ticketer for session ticket resumption
+- Add ArcSwap<Option<TlsAcceptor>> shared_tls_acceptor to tcp_listener for hot-reloadable, pre-built acceptor and update accept loop/handlers to use it
+- set_tls_configs now attempts to build and store the shared TLS acceptor, falling back to per-connection acceptors on failure; raw PEM configs are still retained for route-level fallbacks
+- Add get_tls_acceptor helper: prefer shared acceptor for performance and session resumption, but build per-connection acceptor when a route requests custom TLS versions
+
+## 2026-02-16 - 25.4.0 - feat(rustproxy)
+support dynamically loaded TLS certificates via loadCertificate IPC and include them in listener TLS configs for rebuilds and hot-swap
+
+- Adds loaded_certs: HashMap<String, TlsCertConfig> to RustProxy to store certificates loaded at runtime
+- Merge loaded_certs into tls_configs in rebuild and listener hot-swap paths so dynamically loaded certs are served immediately
+- Persist loaded certificates on loadCertificate so future rebuilds include them
+
+## 2026-02-15 - 25.3.1 - fix(plugins)
+remove unused dependencies and simplify plugin exports
+
+- Removed multiple dependencies from package.json to reduce dependency footprint: @push.rocks/lik, @push.rocks/smartacme, @push.rocks/smartdelay, @push.rocks/smartfile, @push.rocks/smartnetwork, @push.rocks/smartpromise, @push.rocks/smartrequest, @push.rocks/smartrx, @push.rocks/smartstring, @push.rocks/taskbuffer, @types/minimatch, @types/ws, pretty-ms, ws
+- ts/plugins.ts: stopped importing/exporting node:https and many push.rocks and third-party modules; plugins now only re-export core node modules (without https), tsclass, smartcrypto, smartlog (+ destination-local), smartrust, and minimatch
+- Intended effect: trim surface area and remove unused/optional integrations; patch-level change (no feature/API additions)
+
+## 2026-02-14 - 25.3.0 - feat(smart-proxy)
+add background concurrent certificate provisioning with per-domain timeouts and concurrency control
+
+- Add ISmartProxyOptions settings: certProvisionTimeout (ms) and certProvisionConcurrency (default 4)
+- Run certProvisionFunction as fire-and-forget background tasks (stores promise on start/route-update and awaited on stop)
+- Provision certificates in parallel with a concurrency limit using a new ConcurrencySemaphore utility
+- Introduce per-domain timeout handling (default 300000ms) via withTimeout and surface timeout errors as certificate-failed events
+- Refactor provisioning into provisionSingleDomain to isolate domain handling, ACME fallback preserved
+- Run provisioning outside route update mutex so route updates are not blocked by slow provisioning
+
+## 2026-02-14 - 25.2.2 - fix(smart-proxy)
+start metrics polling before certificate provisioning to avoid blocking metrics collection
+
+- Start metrics polling immediately after Rust engine startup so metrics are available without waiting for certificate provisioning.
+- Run certProvisionFunction after startup because ACME/DNS-01 provisioning can hang or be slow and must not block observability.
+- Code change in ts/proxies/smart-proxy/smart-proxy.ts: metricsAdapter.startPolling() moved to run before provisionCertificatesViaCallback().
+
+## 2026-02-14 - 25.2.1 - fix(smartproxy)
+no changes detected in git diff
+
+- The provided diff contains no file changes; no code or documentation updates to release.
+
+## 2026-02-14 - 25.2.0 - feat(metrics)
+add per-IP and HTTP-request metrics, propagate source IP through proxy paths, and expose new metrics to the TS adapter
+
+- Add per-IP tracking and IpMetrics in MetricsCollector (active/total connections, bytes, throughput).
+- Add HTTP request counters and tracking (total_http_requests, http_requests_per_sec, recent counters and tests).
+- Include throughput history (ThroughputSample serialization, retention and snapshotting) and expose history in snapshots.
+- Propagate source IP through HTTP and passthrough code paths: CountingBody.record_bytes and MetricsCollector methods now accept source_ip; connection_opened/closed calls include source IP.
+- Introduce ForwardMetricsCtx to carry metrics context (collector, route_id, source_ip) into passthrough forwarding routines; update ConnectionGuard to include source_ip.
+- TypeScript adapter (rust-metrics-adapter.ts) updated to return per-IP counts, top IPs, per-IP throughput, throughput history mapping, and HTTP request rates/total where available.
+- Numerous unit tests added for per-IP tracking, HTTP request tracking, throughput history and ThroughputTracker.history behavior.
+
+## 2026-02-13 - 25.1.0 - feat(metrics)
+add real-time throughput sampling and byte-counting metrics
+
+- Add CountingBody wrapper to count HTTP request and response bytes and report them to MetricsCollector.
+- Implement lock-free hot-path byte recording and a cold-path sampling API (sample_all) in MetricsCollector with throughput history and configurable retention (default 3600s).
+- Spawn a background sampling task in RustProxy (configurable sample_interval_ms) and tear it down on stop so throughput trackers are regularly sampled.
+- Instrument passthrough TCP forwarding and socket-relay paths to record per-chunk bytes (lock-free) so long-lived connections contribute to throughput measurements.
+- Wrap HTTP request/response bodies with CountingBody in proxy_service to capture bytes_in/bytes_out and report on body completion; connection_closed handling updated accordingly.
+- Expose recent throughput metrics to the TypeScript adapter (throughputRecentIn/Out) and pass metrics settings from the TS SmartProxy into Rust.
+- Add http-body dependency and update Cargo.toml/Cargo.lock entries for the new body wrapper usage.
+- Add unit tests for MetricsCollector throughput tracking and a new end-to-end throughput test (test.throughput.ts).
+- Update test certificates (assets/certs cert.pem and key.pem) used by TLS tests.
+
+## 2026-02-13 - 25.0.0 - BREAKING CHANGE(certs)
+accept a second eventComms argument in certProvisionFunction, add cert provisioning event types, and emit certificate lifecycle events
+
+- Breaking API change: certProvisionFunction signature changed from (domain: string) => Promise<TSmartProxyCertProvisionObject> to (domain: string, eventComms: ICertProvisionEventComms) => Promise<TSmartProxyCertProvisionObject>. Custom provisioners must accept (or safely ignore) the new second argument.
+- New types added and exported: ICertProvisionEventComms, ICertificateIssuedEvent, ICertificateFailedEvent.
+- smart-proxy now constructs an eventComms channel that allows provisioners to log/warn/error and set expiry date and source for the issued event.
+- Emits 'certificate-issued' (domain, expiryDate, source, isRenewal?) on successful provisioning and 'certificate-failed' (domain, error, source) on failures.
+- Updated public exports to include the new types so they are available to consumers.
+- Removed readme.byte-counting-audit.md (documentation file deleted).
+
+## 2026-02-13 - 24.0.1 - fix(proxy)
+improve proxy robustness: add connect timeouts, graceful shutdown, WebSocket watchdog, and metrics guard
+
+- Add tokio-util CancellationToken to HTTP handlers to support graceful shutdown (stop accepting new requests while letting in-flight requests finish).
+- Introduce configurable upstream connect timeout (DEFAULT_CONNECT_TIMEOUT) and return 504 Gateway Timeout on connect timeouts to avoid hanging connections.
+- Add WebSocket watchdog with inactivity and max-lifetime checks, activity tracking via AtomicU64, and cancellation-driven tunnel aborts.
+- Add ConnectionGuard RAII in passthrough listener to ensure metrics.connection_closed() is called on all exit paths and disarm the guard when handing off to the HTTP proxy.
+- Expose HttpProxyService::with_connect_timeout and wire connection timeout from ConnectionConfig into listeners.
+- Add tokio-util workspace dependency (CancellationToken) and related code changes across rustproxy-http and rustproxy-passthrough.
+
+## 2026-02-13 - 24.0.0 - BREAKING CHANGE(smart-proxy)
+move certificate persistence to an in-memory store and introduce consumer-managed certStore API; add default self-signed fallback cert and change ACME account handling
+
+- Cert persistence removed from Rust side: CertStore is now an in-memory cache (no filesystem reads/writes). Rust no longer persists or loads certs from disk.
+- ACME account credentials are no longer persisted by the library; AcmeClient uses ephemeral accounts only and account persistence APIs were removed.
+- TypeScript API changes: removed certificateStore option and added ISmartProxyCertStore + certStore option for consumer-provided persistence (loadAll, save, optional remove).
+- Default self-signed fallback certificate added (generateDefaultCertificate) and loaded as '*' unless disableDefaultCert is set.
+- SmartProxy now pre-loads certificates from consumer certStore on startup and persists certificates by calling certStore.save() after provisioning.
+- provisionCertificatesViaCallback signature changed to accept preloaded domains (prevents re-provisioning), and ACME fallback behavior adjusted with clearer logging.
+- Rust cert manager methods made infallible for cache-only operations (load_static/store no longer return errors for cache insertions); removed store-backed load_all/remove/base_dir APIs.
+- TCP listener tls_configs concurrency improved: switched to ArcSwap<HashMap<...>> so accept loops see hot-reloads immediately.
+- Removed dependencies related to filesystem cert persistence from the tls crate (serde_json, tempfile) and corresponding Cargo.lock changes and test updates.
+
+## 2026-02-13 - 23.1.6 - fix(smart-proxy)
+disable built-in Rust ACME when a certProvisionFunction is provided and improve certificate provisioning flow
+
+- Pass an optional ACME override into buildRustConfig so Rust ACME can be disabled per-run
+- Disable Rust ACME when certProvisionFunction is configured to avoid provisioning race conditions
+- Normalize routing glob patterns into concrete domain identifiers for certificate provisioning (expand leading-star globs and warn on unsupported patterns)
+- Deduplicate domains during provisioning to avoid repeated attempts
+- When the callback returns 'http01', explicitly trigger Rust ACME for the route via bridge.provisionCertificate and log success/failure
+
+## 2026-02-13 - 23.1.5 - fix(smart-proxy)
+provision certificates for wildcard domains instead of skipping them
+
+- Removed early continue that skipped domains containing '*' in the domain loop
+- Now calls provisionFn for wildcard domains so certificate provisioning can proceed for wildcard hosts
+- Fixes cases where wildcard domains never had certificates requested
+
+## 2026-02-12 - 23.1.4 - fix(tests)
+make tests more robust and bump small dependencies
+
+- Bump dependencies: @push.rocks/smartrust ^1.2.1 and minimatch ^10.2.0
+- Replace hardcoded ports with named constants (ECHO_PORT, PROXY_PORT, PROXY_PORT_1/2) to avoid collisions between tests
+- Add server 'error' handlers and reject listen promises on server errors to prevent silent hangs
+- Reduce test timeouts and intervals (shorter test durations, more frequent pings) to speed up test runs
+- Ensure proxy is stopped between tests and remove forced process.exit; export tap.start() consistently
+- Adjust assertions to match the new shorter ping/response counts
+
+## 2026-02-12 - 23.1.3 - fix(rustproxy)
+install default rustls crypto provider early; detect and skip raw fast-path for HTTP connections and return proper HTTP 502 when no route matches
+
+- Install ring-based rustls crypto provider at startup to prevent panics from instant-acme/hyper-rustls calling ClientConfig::builder() before TLS listeners are initialized
+- Add a non-blocking 10ms peek to detect HTTP traffic in the TCP passthrough fast-path to avoid misrouting HTTP and ensure HTTP proxy handles CORS, errors, and request-level routing
+- Skip the fast-path and fall back to the HTTP proxy when HTTP is detected (with a debug log)
+- When no route matches for detected HTTP connections, send an HTTP 502 Bad Gateway response and close the connection instead of silently dropping it
+
+## 2026-02-11 - 23.1.2 - fix(core)
+use node: scoped builtin imports and add route unit tests
+
+- Replaced bare Node built-in imports (events, fs, http, https, net, path, tls, url, http2, buffer, crypto) with 'node:' specifiers for ESM/bundler compatibility (files updated include ts/plugins.ts, ts/core/models/socket-types.ts, ts/core/utils/enhanced-connection-pool.ts, ts/core/utils/socket-tracker.ts, ts/protocols/common/fragment-handler.ts, ts/protocols/tls/sni/client-hello-parser.ts, ts/protocols/tls/sni/sni-extraction.ts, ts/protocols/websocket/utils.ts, ts/tls/sni/sni-handler.ts).
+- Added new unit tests (test/test.bun.ts and test/test.deno.ts) covering route helpers, validators, matching, merging and cloning to improve test coverage.
+
+## 2026-02-11 - 23.1.1 - fix(rust-proxy)
+increase rust proxy bridge maxPayloadSize to 100 MB and bump dependencies
+
+- Set maxPayloadSize to 100 * 1024 * 1024 (100 MB) in ts/proxies/smart-proxy/rust-proxy-bridge.ts to support large route configs
+- Bump devDependency @types/node from ^25.2.2 to ^25.2.3
+- Bump dependency @push.rocks/smartrust from ^1.1.1 to ^1.2.0
+
+## 2026-02-10 - 23.1.0 - feat(rust-bridge)
+integrate tsrust to build and locate cross-compiled Rust binaries; refactor rust-proxy bridge to use typed IPC and streamline process handling; add @push.rocks/smartrust and update build/dev dependencies
+
+- Add tsrust to the build script and include dist_rust candidates when locating the Rust binary (enables cross-compiled artifacts produced by tsrust).
+- Remove the old rust-binary-locator and refactor rust-proxy-bridge to use explicit, typed IPC command definitions and improved process spawn/cleanup logic.
+- Introduce @push.rocks/smartrust for type-safe JSON IPC and export it via plugins; update README with expanded metrics documentation and change initialDataTimeout default from 60s to 120s.
+- Add rust/.cargo/config.toml with aarch64 linker configuration to support cross-compilation for arm64.
+- Bump several devDependencies and runtime dependencies (e.g. @git.zone/tsbuild, @git.zone/tstest, @push.rocks/smartserve, @push.rocks/taskbuffer, ws, minimatch, etc.).
+- Update runtime message guiding local builds to use 'pnpm build' (tsrust) instead of direct cargo invocation.
+
+## 2026-02-09 - 23.0.0 - BREAKING CHANGE(proxies/nftables-proxy)
+remove nftables-proxy implementation, models, and utilities from the repository
+
+- Deleted nftables-proxy module files under ts/proxies/nftables-proxy (index, models, utils, command executor, validators, etc.)
+- Removed nftables-proxy exports from ts/index.ts and ts/proxies/index.ts
+- Updated smart-proxy types to drop dependency on nftables proxy models
+- Breaking change: any consumers importing nftables-proxy will no longer find those exports; update imports or install/use the extracted/alternative package if applicable
+
+## 2026-02-09 - 22.6.0 - feat(smart-proxy)
+add socket-handler relay, fast-path port-only forwarding, metrics and bridge improvements, and various TS/Rust integration fixes
+
+- Add Unix-domain socket relay for socket-handler routes so Rust can hand off matched connections to TypeScript handlers (metadata JSON + initial bytes, relay implementation in Rust and SocketHandlerServer in TS).
+- Implement fast-path port-only forwarding in the TCP accept/handler path to forward simple non-TLS, port-only routes immediately without peeking at client data (improves server-speaks-first protocol handling).
+- Use ArcSwap for route manager hot-reload visibility in accept loops and share socket_handler_relay via Arc<RwLock> so listeners see relay path updates immediately.
+- Enhance SNI/HTTP parsing: add extract_http_path and extract_http_host to aid domain/path matching from initial data.
+- Improve RustProxy shutdown/kill handling: remove listeners, reject pending requests, destroy stdio pipes and unref process to avoid leaking handles.
+- Enhance Rust <-> TS metrics bridge and adapter: add immediate poll(), map Rust JSON fields to IMetrics (per-route active/throughput/totals), and use safer polling/unref timers.
+- SocketHandlerServer enhancements: track active sockets, destroy on stop, pause/resume to prevent data loss, support async socketHandler callbacks and dynamic function-based target forwarding (resolve host/port functions and forward).
+- TypeScript smart-proxy lifecycle tweaks: only set bridge relay after Rust starts, guard unexpected-exit emission when intentionally stopping, stop polling and remove listeners on stop, add stopping flag.
+- Misc: README and API ergonomics updates (nft proxy option renames and config comments), various test updates to use stable http.request helper, adjust timeouts/metrics sampling and assertions, and multiple small bugfixes in listeners, timeouts and TLS typings. 
+
+## 2026-02-09 - 22.5.0 - feat(rustproxy)
+introduce a Rust-powered proxy engine and workspace with core crates for proxy functionality, ACME/TLS support, passthrough and HTTP proxies, metrics, nftables integration, routing/security, management IPC, tests, and README updates
+
+- Add Rust workspace and multiple crates: rustproxy, rustproxy-config, rustproxy-routing, rustproxy-tls, rustproxy-passthrough, rustproxy-http, rustproxy-nftables, rustproxy-metrics, rustproxy-security
+- Implement ACME integration (instant-acme) and an HTTP-01 challenge server with certificate lifecycle management
+- Add TLS management: cert store, cert manager, SNI resolver, TLS acceptor/connector and certificate hot-swap support
+- Implement TCP/TLS passthrough engine with ClientHello SNI parsing, PROXY v1 support, connection tracking and bidirectional forwarder
+- Add Hyper-based HTTP proxy components: request/response filtering, CORS, auth, header templating and upstream selection with load balancing
+- Introduce metrics (throughput tracker, metrics collector) and log deduplication utilities
+- Implement nftables manager and rule builder (safe no-op behavior when not running as root)
+- Add route types, validation, helpers, route manager and matchers (domain/path/header/ip)
+- Provide management IPC (JSON over stdin/stdout) for TypeScript wrapper control (start/stop/add/remove ports, load certificates, etc.)
+- Include extensive unit and integration tests, test helpers, and an example Rust config.json
+- Update README to document the Rust-powered engine, new features and rustBinaryPath lookup
+
 ## 2026-01-31 - 22.4.2 - fix(tests)
 shorten long-lived connection test timeouts and update certificate metadata timestamps
 

license

@@ -1,4 +1,4 @@
-Copyright (c) 2019 Lossless GmbH (hello@lossless.com)
+Copyright (c) 2019 Task Venture Capital GmbH (hello@task.vc)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "22.4.2",
+  "version": "27.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,39 +9,29 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "scripts": {
+    "test:before": "(tsrust)",
     "test": "(tstest test/**/test*.ts --verbose --timeout 60 --logfile)",
-    "build": "(tsbuild tsfolders --allowimplicitany)",
+    "build": "(tsbuild tsfolders --allowimplicitany) && (tsrust)",
     "format": "(gitzone format)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^3.1.2",
-    "@git.zone/tsrun": "^2.0.0",
-    "@git.zone/tstest": "^3.1.3",
-    "@push.rocks/smartserve": "^1.4.0",
-    "@types/node": "^24.10.2",
-    "typescript": "^5.9.3",
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsrun": "^2.0.2",
+    "@git.zone/tsrust": "^1.3.2",
+    "@git.zone/tstest": "^3.6.0",
+    "@push.rocks/smartserve": "^2.0.3",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
     "why-is-node-running": "^3.2.2"
   },
   "dependencies": {
-    "@push.rocks/lik": "^6.2.2",
-    "@push.rocks/smartacme": "^8.0.0",
     "@push.rocks/smartcrypto": "^2.0.4",
-    "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^13.1.0",
-    "@push.rocks/smartlog": "^3.1.10",
-    "@push.rocks/smartnetwork": "^4.4.0",
-    "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrequest": "^5.0.1",
-    "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smartstring": "^4.1.0",
-    "@push.rocks/taskbuffer": "^3.5.0",
-    "@tsclass/tsclass": "^9.3.0",
-    "@types/minimatch": "^6.0.0",
-    "@types/ws": "^8.18.1",
-    "minimatch": "^10.1.1",
-    "pretty-ms": "^9.3.0",
-    "ws": "^8.18.3"
+    "@push.rocks/smartlog": "^3.2.1",
+    "@push.rocks/smartnftables": "^1.0.1",
+    "@push.rocks/smartrust": "^1.3.2",
+    "@tsclass/tsclass": "^9.5.0",
+    "minimatch": "^10.2.4"
   },
   "files": [
     "ts/**/*",
@@ -52,7 +42,7 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
+    ".smartconfig.json",
     "readme.md",
     "changelog.md"
   ],

readme.byte-counting-audit.md

@@ -1,169 +0,0 @@
-# SmartProxy Byte Counting Audit Report
-
-## Executive Summary
-
-After a comprehensive audit of the SmartProxy codebase, I can confirm that **byte counting is implemented correctly** with no instances of double counting. Each byte transferred through the proxy is counted exactly once in each direction.
-
-## Byte Counting Implementation
-
-### 1. Core Tracking Mechanisms
-
-SmartProxy uses two complementary tracking systems:
-
-1. **Connection Records** (`IConnectionRecord`):
-   - `bytesReceived`: Total bytes received from client
-   - `bytesSent`: Total bytes sent to client
-
-2. **MetricsCollector**:
-   - Global throughput tracking via `ThroughputTracker`
-   - Per-connection byte tracking for route/IP metrics
-   - Called via `recordBytes(connectionId, bytesIn, bytesOut)`
-
-### 2. Where Bytes Are Counted
-
-Bytes are counted in only two files:
-
-#### a) `route-connection-handler.ts`
-- **Line 351**: TLS alert bytes when no SNI is provided
-- **Lines 1286-1301**: Data forwarding callbacks in `setupBidirectionalForwarding()`
-
-#### b) `http-proxy-bridge.ts`  
-- **Line 127**: Initial TLS chunk for HttpProxy connections
-- **Lines 142-154**: Data forwarding callbacks in `setupBidirectionalForwarding()`
-
-## Connection Flow Analysis
-
-### 1. Direct TCP Connection (No TLS)
-
-```
-Client → SmartProxy → Target Server
-```
-
-1. Connection arrives at `RouteConnectionHandler.handleConnection()`
-2. For non-TLS ports, immediately routes via `routeConnection()`
-3. `setupDirectConnection()` creates target connection
-4. `setupBidirectionalForwarding()` handles all data transfer:
-   - `onClientData`: `bytesReceived += chunk.length` + `recordBytes(chunk.length, 0)`
-   - `onServerData`: `bytesSent += chunk.length` + `recordBytes(0, chunk.length)`
-
-**Result**: ✅ Each byte counted exactly once
-
-### 2. TLS Passthrough Connection
-
-```
-Client (TLS) → SmartProxy → Target Server (TLS)
-```
-
-1. Connection waits for initial data to detect TLS
-2. TLS handshake detected, SNI extracted
-3. Route matched, `setupDirectConnection()` called
-4. Initial chunk stored in `pendingData` (NOT counted yet)
-5. On target connect, `pendingData` written to target (still not counted)
-6. `setupBidirectionalForwarding()` counts ALL bytes including initial chunk
-
-**Result**: ✅ Each byte counted exactly once
-
-### 3. TLS Termination via HttpProxy
-
-```
-Client (TLS) → SmartProxy → HttpProxy (localhost) → Target Server
-```
-
-1. TLS connection detected with `tls.mode = "terminate"`
-2. `forwardToHttpProxy()` called:
-   - Initial chunk: `bytesReceived += chunk.length` + `recordBytes(chunk.length, 0)`
-3. Proxy connection created to HttpProxy on localhost
-4. `setupBidirectionalForwarding()` handles subsequent data
-
-**Result**: ✅ Each byte counted exactly once
-
-### 4. HTTP Connection via HttpProxy
-
-```
-Client (HTTP) → SmartProxy → HttpProxy (localhost) → Target Server
-```
-
-1. Connection on configured HTTP port (`useHttpProxy` ports)
-2. Same flow as TLS termination
-3. All byte counting identical to TLS termination
-
-**Result**: ✅ Each byte counted exactly once
-
-### 5. NFTables Forwarding
-
-```
-Client → [Kernel NFTables] → Target Server
-```
-
-1. Connection detected, route matched with `forwardingEngine: 'nftables'`
-2. Connection marked as `usingNetworkProxy = true`
-3. NO application-level forwarding (kernel handles packet routing)
-4. NO byte counting in application layer
-
-**Result**: ✅ No counting (correct - kernel handles everything)
-
-## Special Cases
-
-### PROXY Protocol
-- PROXY protocol headers sent to backend servers are NOT counted in client metrics
-- Only actual client data is counted
-- **Correct behavior**: Protocol overhead is not client data
-
-### TLS Alerts
-- TLS alerts (e.g., for missing SNI) are counted as sent bytes
-- **Correct behavior**: Alerts are actual data sent to the client
-
-### Initial Chunks
-- **Direct connections**: Stored in `pendingData`, counted when forwarded
-- **HttpProxy connections**: Counted immediately upon receipt
-- **Both approaches**: Count each byte exactly once
-
-## Verification Methodology
-
-1. **Code Analysis**: Searched for all instances of:
-   - `bytesReceived +=` and `bytesSent +=`
-   - `recordBytes()` calls
-   - Data forwarding implementations
-
-2. **Flow Tracing**: Followed data path for each connection type from entry to exit
-
-3. **Handler Review**: Examined all forwarding handlers to ensure no additional counting
-
-## Findings
-
-### ✅ No Double Counting Detected
-
-- Each byte is counted exactly once in the direction it flows
-- Connection records and metrics are updated consistently
-- No overlapping or duplicate counting logic found
-
-### Areas of Excellence
-
-1. **Centralized Counting**: All byte counting happens in just two files
-2. **Consistent Pattern**: Uses `setupBidirectionalForwarding()` with callbacks
-3. **Clear Separation**: Forwarding handlers don't interfere with proxy metrics
-
-## Recommendations
-
-1. **Debug Logging**: Add optional debug logging to verify byte counts in production:
-   ```typescript
-   if (settings.debugByteCount) {
-     logger.log('debug', `Bytes counted: ${connectionId} +${bytes} (total: ${record.bytesReceived})`);
-   }
-   ```
-
-2. **Unit Tests**: Create specific tests to ensure byte counting accuracy:
-   - Test initial chunk handling
-   - Test PROXY protocol overhead exclusion
-   - Test HttpProxy forwarding accuracy
-
-3. **Protocol Overhead Tracking**: Consider separately tracking:
-   - PROXY protocol headers
-   - TLS handshake bytes
-   - HTTP headers vs body
-
-4. **NFTables Documentation**: Clearly document that NFTables-forwarded connections are not included in application metrics
-
-## Conclusion
-
-SmartProxy's byte counting implementation is **robust and accurate**. The design ensures that each byte is counted exactly once, with clear separation between connection tracking and metrics collection. No remediation is required.

readme.hints.md

@@ -462,35 +462,57 @@ For TLS termination modes (`terminate` and `terminate-and-reencrypt`), SmartProx
 
 **HTTP to HTTPS Redirect**:
 ```typescript
-import { createHttpToHttpsRedirect } from '@push.rocks/smartproxy';
+import { SocketHandlers } from '@push.rocks/smartproxy';
 
-const redirectRoute = createHttpToHttpsRedirect(['example.com', 'www.example.com']);
+const redirectRoute = {
+  name: 'http-to-https',
+  match: { ports: 80, domains: ['example.com', 'www.example.com'] },
+  action: {
+    type: 'socket-handler' as const,
+    socketHandler: SocketHandlers.httpRedirect('https://{domain}:443{path}', 301)
+  }
+};
 ```
 
 **Complete HTTPS Server (with redirect)**:
 ```typescript
-import { createCompleteHttpsServer } from '@push.rocks/smartproxy';
-
-const routes = createCompleteHttpsServer(
-  'example.com',
-  { host: 'localhost', port: 8080 },
-  { certificate: 'auto' }
-);
+const routes = [
+  {
+    name: 'https-server',
+    match: { ports: 443, domains: 'example.com' },
+    action: {
+      type: 'forward' as const,
+      targets: [{ host: 'localhost', port: 8080 }],
+      tls: { mode: 'terminate' as const, certificate: 'auto' as const }
+    }
+  },
+  {
+    name: 'http-redirect',
+    match: { ports: 80, domains: 'example.com' },
+    action: {
+      type: 'socket-handler' as const,
+      socketHandler: SocketHandlers.httpRedirect('https://{domain}:443{path}', 301)
+    }
+  }
+];
 ```
 
 **Load Balancer with Health Checks**:
 ```typescript
-import { createLoadBalancerRoute } from '@push.rocks/smartproxy';
-
-const lbRoute = createLoadBalancerRoute(
-  'api.example.com',
-  [
-    { host: 'backend1', port: 8080 },
-    { host: 'backend2', port: 8080 },
-    { host: 'backend3', port: 8080 }
-  ],
-  { tls: { mode: 'terminate', certificate: 'auto' } }
-);
+const lbRoute = {
+  name: 'load-balancer',
+  match: { ports: 443, domains: 'api.example.com' },
+  action: {
+    type: 'forward' as const,
+    targets: [
+      { host: 'backend1', port: 8080 },
+      { host: 'backend2', port: 8080 },
+      { host: 'backend3', port: 8080 }
+    ],
+    tls: { mode: 'terminate' as const, certificate: 'auto' as const },
+    loadBalancing: { algorithm: 'round-robin' as const }
+  }
+};
 ```
 
 ### Smart SNI Requirement (v22.3+)

rust/.cargo/config.toml

@@ -0,0 +1,2 @@
+[target.aarch64-unknown-linux-gnu]
+linker = "aarch64-linux-gnu-gcc"

rust/Cargo.toml

@@ -0,0 +1,110 @@
+[workspace]
+resolver = "2"
+members = [
+    "crates/rustproxy",
+    "crates/rustproxy-config",
+    "crates/rustproxy-routing",
+    "crates/rustproxy-tls",
+    "crates/rustproxy-passthrough",
+    "crates/rustproxy-http",
+    "crates/rustproxy-metrics",
+    "crates/rustproxy-security",
+]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+authors = ["Lossless GmbH <hello@lossless.com>"]
+
+[workspace.dependencies]
+# Async runtime
+tokio = { version = "1", features = ["full"] }
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# HTTP proxy engine (hyper-based)
+hyper = { version = "1", features = ["http1", "http2", "server", "client"] }
+hyper-util = { version = "0.1", features = ["tokio", "http1", "http2", "client-legacy", "server-auto"] }
+http-body = "1"
+http-body-util = "0.1"
+bytes = "1"
+
+# ACME / Let's Encrypt
+instant-acme = { version = "0.7", features = ["hyper-rustls"] }
+
+# TLS for passthrough SNI
+rustls = { version = "0.23", features = ["ring"] }
+tokio-rustls = "0.26"
+rustls-pemfile = "2"
+
+# Self-signed cert generation for tests
+rcgen = "0.13"
+
+# Temp directories for tests
+tempfile = "3"
+
+# Lock-free atomics
+arc-swap = "1"
+
+# Concurrent maps
+dashmap = "6"
+
+# Domain wildcard matching
+glob-match = "0.2"
+
+# IP/CIDR parsing
+ipnet = "2"
+
+# JWT authentication
+jsonwebtoken = "9"
+
+# Structured logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+# Error handling
+thiserror = "2"
+anyhow = "1"
+
+# CLI
+clap = { version = "4", features = ["derive"] }
+
+# Regex for URL rewriting
+regex = "1"
+
+# Base64 for basic auth
+base64 = "0.22"
+
+# Cancellation / utility
+tokio-util = "0.7"
+
+# Async traits
+async-trait = "0.1"
+
+# libc for uid checks
+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"
+
+# Internal crates
+rustproxy-config = { path = "crates/rustproxy-config" }
+rustproxy-routing = { path = "crates/rustproxy-routing" }
+rustproxy-tls = { path = "crates/rustproxy-tls" }
+rustproxy-passthrough = { path = "crates/rustproxy-passthrough" }
+rustproxy-http = { path = "crates/rustproxy-http" }
+rustproxy-metrics = { path = "crates/rustproxy-metrics" }
+rustproxy-security = { path = "crates/rustproxy-security" }

rust/config/example.json

@@ -0,0 +1,145 @@
+{
+  "routes": [
+    {
+      "id": "https-passthrough",
+      "name": "HTTPS Passthrough to Backend",
+      "match": {
+        "ports": 443,
+        "domains": "backend.example.com"
+      },
+      "action": {
+        "type": "forward",
+        "targets": [
+          {
+            "host": "10.0.0.1",
+            "port": 443
+          }
+        ],
+        "tls": {
+          "mode": "passthrough"
+        }
+      },
+      "priority": 10,
+      "enabled": true
+    },
+    {
+      "id": "https-terminate",
+      "name": "HTTPS Terminate for API",
+      "match": {
+        "ports": 443,
+        "domains": "api.example.com"
+      },
+      "action": {
+        "type": "forward",
+        "targets": [
+          {
+            "host": "localhost",
+            "port": 8080
+          }
+        ],
+        "tls": {
+          "mode": "terminate",
+          "certificate": "auto"
+        }
+      },
+      "priority": 20,
+      "enabled": true
+    },
+    {
+      "id": "http-redirect",
+      "name": "HTTP to HTTPS Redirect",
+      "match": {
+        "ports": 80,
+        "domains": ["api.example.com", "www.example.com"]
+      },
+      "action": {
+        "type": "forward",
+        "targets": [
+          {
+            "host": "localhost",
+            "port": 8080
+          }
+        ]
+      },
+      "priority": 0
+    },
+    {
+      "id": "load-balanced",
+      "name": "Load Balanced Backend",
+      "match": {
+        "ports": 443,
+        "domains": "*.example.com"
+      },
+      "action": {
+        "type": "forward",
+        "targets": [
+          {
+            "host": "backend1.internal",
+            "port": 8080
+          },
+          {
+            "host": "backend2.internal",
+            "port": 8080
+          },
+          {
+            "host": "backend3.internal",
+            "port": 8080
+          }
+        ],
+        "tls": {
+          "mode": "terminate",
+          "certificate": "auto"
+        },
+        "loadBalancing": {
+          "algorithm": "round-robin",
+          "healthCheck": {
+            "path": "/health",
+            "interval": 30,
+            "timeout": 5,
+            "unhealthyThreshold": 3,
+            "healthyThreshold": 2
+          }
+        }
+      },
+      "security": {
+        "ipAllowList": ["10.0.0.0/8", "192.168.0.0/16"],
+        "maxConnections": 1000,
+        "rateLimit": {
+          "enabled": true,
+          "maxRequests": 100,
+          "window": 60,
+          "keyBy": "ip"
+        }
+      },
+      "headers": {
+        "request": {
+          "X-Forwarded-For": "{clientIp}",
+          "X-Real-IP": "{clientIp}"
+        },
+        "response": {
+          "X-Powered-By": "RustProxy"
+        },
+        "cors": {
+          "enabled": true,
+          "allowOrigin": "*",
+          "allowMethods": "GET,POST,PUT,DELETE,OPTIONS",
+          "allowHeaders": "Content-Type,Authorization",
+          "allowCredentials": false,
+          "maxAge": 86400
+        }
+      },
+      "priority": 5
+    }
+  ],
+  "acme": {
+    "email": "admin@example.com",
+    "useProduction": false,
+    "port": 80
+  },
+  "connectionTimeout": 30000,
+  "socketTimeout": 3600000,
+  "maxConnectionsPerIp": 100,
+  "connectionRateLimitPerMinute": 300,
+  "keepAliveTreatment": "extended",
+  "enableDetailedLogging": false
+}

rust/crates/rustproxy-config/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "rustproxy-config"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Configuration types for RustProxy, compatible with SmartProxy JSON schema"
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+ipnet = { workspace = true }

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

@@ -0,0 +1,17 @@
+//! # rustproxy-config
+//!
+//! Configuration types for RustProxy, fully compatible with SmartProxy's JSON schema.
+//! All types use `#[serde(rename_all = "camelCase")]` to match TypeScript field naming.
+
+pub mod route_types;
+pub mod proxy_options;
+pub mod tls_types;
+pub mod security_types;
+pub mod validation;
+
+// Re-export all primary types
+pub use route_types::*;
+pub use proxy_options::*;
+pub use tls_types::*;
+pub use security_types::*;
+pub use validation::*;

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

@@ -0,0 +1,476 @@
+use serde::{Deserialize, Serialize};
+
+use crate::route_types::RouteConfig;
+
+/// Global ACME configuration options.
+/// Matches TypeScript: `IAcmeOptions`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AcmeOptions {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+    /// Required when any route uses certificate: 'auto'
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub email: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub environment: Option<AcmeEnvironment>,
+    /// Alias for email
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub account_email: Option<String>,
+    /// Port for HTTP-01 challenges (default: 80)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub port: Option<u16>,
+    /// Use Let's Encrypt production (default: false)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub use_production: Option<bool>,
+    /// Days before expiry to renew (default: 30)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub renew_threshold_days: Option<u32>,
+    /// Enable automatic renewal (default: true)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub auto_renew: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub skip_configured_certs: Option<bool>,
+    /// How often to check for renewals (default: 24)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub renew_check_interval_hours: Option<u32>,
+}
+
+/// ACME environment.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum AcmeEnvironment {
+    Production,
+    Staging,
+}
+
+/// Default target configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DefaultTarget {
+    pub host: String,
+    pub port: u16,
+}
+
+/// Default security configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DefaultSecurity {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ip_allow_list: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ip_block_list: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_connections: Option<u64>,
+}
+
+/// Default configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DefaultConfig {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target: Option<DefaultTarget>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub security: Option<DefaultSecurity>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub preserve_source_ip: Option<bool>,
+}
+
+/// Keep-alive treatment.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum KeepAliveTreatment {
+    Standard,
+    Extended,
+    Immortal,
+}
+
+/// Metrics configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct MetricsConfig {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sample_interval_ms: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retention_seconds: Option<u64>,
+}
+
+/// RustProxy configuration options.
+/// Matches TypeScript: `ISmartProxyOptions`
+///
+/// This is the top-level configuration that can be loaded from a JSON file
+/// or constructed programmatically.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RustProxyOptions {
+    /// The unified configuration array (required)
+    pub routes: Vec<RouteConfig>,
+
+    /// Preserve client IP when forwarding
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub preserve_source_ip: Option<bool>,
+
+    /// List of trusted proxy IPs that can send PROXY protocol
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub proxy_ips: Option<Vec<String>>,
+
+    /// Global option to accept PROXY protocol
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub accept_proxy_protocol: Option<bool>,
+
+    /// Global option to send PROXY protocol to all targets
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub send_proxy_protocol: Option<bool>,
+
+    /// Global/default settings
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub defaults: Option<DefaultConfig>,
+
+    // ─── Timeout Settings ────────────────────────────────────────────
+
+    /// Timeout for establishing connection to backend (ms), default: 30000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub connection_timeout: Option<u64>,
+
+    /// Timeout for initial data/SNI (ms), default: 60000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub initial_data_timeout: Option<u64>,
+
+    /// Socket inactivity timeout (ms), default: 3600000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub socket_timeout: Option<u64>,
+
+    /// How often to check for inactive connections (ms), default: 60000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inactivity_check_interval: Option<u64>,
+
+    /// Default max connection lifetime (ms), default: 86400000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_connection_lifetime: Option<u64>,
+
+    /// Inactivity timeout (ms), default: 14400000
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub inactivity_timeout: Option<u64>,
+
+    /// Maximum time to wait for connections to close during shutdown (ms)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub graceful_shutdown_timeout: Option<u64>,
+
+    // ─── Socket Optimization ─────────────────────────────────────────
+
+    /// Disable Nagle's algorithm (default: true)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub no_delay: Option<bool>,
+
+    /// Enable TCP keepalive (default: true)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub keep_alive: Option<bool>,
+
+    /// Initial delay before sending keepalive probes (ms)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub keep_alive_initial_delay: Option<u64>,
+
+    /// Maximum bytes to buffer during connection setup
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_pending_data_size: Option<u64>,
+
+    // ─── Enhanced Features ───────────────────────────────────────────
+
+    /// Disable inactivity checking entirely
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub disable_inactivity_check: Option<bool>,
+
+    /// Enable TCP keep-alive probes
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_keep_alive_probes: Option<bool>,
+
+    /// Enable detailed connection logging
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_detailed_logging: Option<bool>,
+
+    /// Enable TLS handshake debug logging
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_tls_debug_logging: Option<bool>,
+
+    /// Randomize timeouts to prevent thundering herd
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enable_randomized_timeouts: Option<bool>,
+
+    // ─── Rate Limiting ───────────────────────────────────────────────
+
+    /// Maximum simultaneous connections from a single IP
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_connections_per_ip: Option<u64>,
+
+    /// Max new connections per minute from a single IP
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub connection_rate_limit_per_minute: Option<u64>,
+
+    /// Global maximum simultaneous connections (default: 100000)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_connections: Option<u64>,
+
+    // ─── Keep-Alive Settings ─────────────────────────────────────────
+
+    /// How to treat keep-alive connections
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub keep_alive_treatment: Option<KeepAliveTreatment>,
+
+    /// Multiplier for inactivity timeout for keep-alive connections
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub keep_alive_inactivity_multiplier: Option<f64>,
+
+    /// Extended lifetime for keep-alive connections (ms)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub extended_keep_alive_lifetime: Option<u64>,
+
+    // ─── HttpProxy Integration ───────────────────────────────────────
+
+    /// Array of ports to forward to HttpProxy
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub use_http_proxy: Option<Vec<u16>>,
+
+    /// Port where HttpProxy is listening (default: 8443)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub http_proxy_port: Option<u16>,
+
+    // ─── Metrics ─────────────────────────────────────────────────────
+
+    /// Metrics configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metrics: Option<MetricsConfig>,
+
+    // ─── ACME ────────────────────────────────────────────────────────
+
+    /// Global ACME configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub acme: Option<AcmeOptions>,
+}
+
+impl Default for RustProxyOptions {
+    fn default() -> Self {
+        Self {
+            routes: Vec::new(),
+            preserve_source_ip: None,
+            proxy_ips: None,
+            accept_proxy_protocol: None,
+            send_proxy_protocol: None,
+            defaults: None,
+            connection_timeout: None,
+            initial_data_timeout: None,
+            socket_timeout: None,
+            inactivity_check_interval: None,
+            max_connection_lifetime: None,
+            inactivity_timeout: None,
+            graceful_shutdown_timeout: None,
+            no_delay: None,
+            keep_alive: None,
+            keep_alive_initial_delay: None,
+            max_pending_data_size: None,
+            disable_inactivity_check: None,
+            enable_keep_alive_probes: None,
+            enable_detailed_logging: None,
+            enable_tls_debug_logging: None,
+            enable_randomized_timeouts: None,
+            max_connections_per_ip: None,
+            connection_rate_limit_per_minute: None,
+            max_connections: None,
+            keep_alive_treatment: None,
+            keep_alive_inactivity_multiplier: None,
+            extended_keep_alive_lifetime: None,
+            use_http_proxy: None,
+            http_proxy_port: None,
+            metrics: None,
+            acme: None,
+        }
+    }
+}
+
+impl RustProxyOptions {
+    /// Load configuration from a JSON file.
+    pub fn from_file(path: &str) -> Result<Self, Box<dyn std::error::Error>> {
+        let content = std::fs::read_to_string(path)?;
+        let options: Self = serde_json::from_str(&content)?;
+        Ok(options)
+    }
+
+    /// Get the effective connection timeout in milliseconds.
+    pub fn effective_connection_timeout(&self) -> u64 {
+        self.connection_timeout.unwrap_or(60_000)
+    }
+
+    /// Get the effective initial data timeout in milliseconds.
+    pub fn effective_initial_data_timeout(&self) -> u64 {
+        self.initial_data_timeout.unwrap_or(60_000)
+    }
+
+    /// Get the effective socket timeout in milliseconds.
+    pub fn effective_socket_timeout(&self) -> u64 {
+        self.socket_timeout.unwrap_or(60_000)
+    }
+
+    /// Get the effective max connection lifetime in milliseconds.
+    pub fn effective_max_connection_lifetime(&self) -> u64 {
+        self.max_connection_lifetime.unwrap_or(3_600_000)
+    }
+
+    /// Get all unique ports that routes listen on.
+    pub fn all_listening_ports(&self) -> Vec<u16> {
+        let mut ports: Vec<u16> = self.routes
+            .iter()
+            .flat_map(|r| r.listening_ports())
+            .collect();
+        ports.sort();
+        ports.dedup();
+        ports
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::route_types::*;
+    use crate::tls_types::*;
+
+    fn make_route(domain: &str, host: &str, port: u16, listen_port: u16) -> RouteConfig {
+        RouteConfig {
+            id: None,
+            route_match: RouteMatch {
+                ports: PortRange::Single(listen_port),
+                domains: Some(DomainSpec::Single(domain.to_string())),
+                path: None, client_ip: None, transport: None, tls_version: None, headers: None, protocol: None,
+            },
+            action: RouteAction {
+                action_type: RouteActionType::Forward,
+                targets: Some(vec![RouteTarget {
+                    target_match: None,
+                    host: HostSpec::Single(host.to_string()),
+                    port: PortSpec::Fixed(port),
+                    tls: None, websocket: None, load_balancing: None, send_proxy_protocol: None,
+                    headers: None, advanced: None, backend_transport: None, priority: None,
+                }]),
+                tls: None, websocket: None, load_balancing: None, advanced: None,
+                options: None, send_proxy_protocol: None, udp: None,
+            },
+            headers: None, security: None, name: None, description: None,
+            priority: None, tags: None, enabled: None,
+        }
+    }
+
+    fn make_passthrough_route(domain: &str, host: &str, port: u16) -> RouteConfig {
+        let mut route = make_route(domain, host, port, 443);
+        route.action.tls = Some(RouteTls {
+            mode: TlsMode::Passthrough,
+            certificate: None, acme: None, versions: None, ciphers: None,
+            honor_cipher_order: None, session_timeout: None,
+        });
+        route
+    }
+
+    #[test]
+    fn test_serde_roundtrip_minimal() {
+        let options = RustProxyOptions {
+            routes: vec![make_route("example.com", "localhost", 8080, 80)],
+            ..Default::default()
+        };
+        let json = serde_json::to_string(&options).unwrap();
+        let parsed: RustProxyOptions = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.routes.len(), 1);
+    }
+
+    #[test]
+    fn test_serde_roundtrip_full() {
+        let options = RustProxyOptions {
+            routes: vec![
+                make_route("a.com", "backend1", 8080, 80),
+                make_passthrough_route("b.com", "backend2", 443),
+            ],
+            connection_timeout: Some(5000),
+            socket_timeout: Some(60000),
+            max_connections_per_ip: Some(100),
+            acme: Some(AcmeOptions {
+                enabled: Some(true),
+                email: Some("admin@example.com".to_string()),
+                environment: Some(AcmeEnvironment::Staging),
+                account_email: None,
+                port: None,
+                use_production: None,
+                renew_threshold_days: None,
+                auto_renew: None,
+                skip_configured_certs: None,
+                renew_check_interval_hours: None,
+            }),
+            ..Default::default()
+        };
+        let json = serde_json::to_string_pretty(&options).unwrap();
+        let parsed: RustProxyOptions = serde_json::from_str(&json).unwrap();
+        assert_eq!(parsed.routes.len(), 2);
+        assert_eq!(parsed.connection_timeout, Some(5000));
+    }
+
+    #[test]
+    fn test_default_timeouts() {
+        let options = RustProxyOptions::default();
+        assert_eq!(options.effective_connection_timeout(), 60_000);
+        assert_eq!(options.effective_initial_data_timeout(), 60_000);
+        assert_eq!(options.effective_socket_timeout(), 60_000);
+        assert_eq!(options.effective_max_connection_lifetime(), 3_600_000);
+    }
+
+    #[test]
+    fn test_custom_timeouts() {
+        let options = RustProxyOptions {
+            connection_timeout: Some(5000),
+            initial_data_timeout: Some(10000),
+            socket_timeout: Some(30000),
+            max_connection_lifetime: Some(60000),
+            ..Default::default()
+        };
+        assert_eq!(options.effective_connection_timeout(), 5000);
+        assert_eq!(options.effective_initial_data_timeout(), 10000);
+        assert_eq!(options.effective_socket_timeout(), 30000);
+        assert_eq!(options.effective_max_connection_lifetime(), 60000);
+    }
+
+    #[test]
+    fn test_all_listening_ports() {
+        let options = RustProxyOptions {
+            routes: vec![
+                make_route("a.com", "backend", 8080, 80),       // port 80
+                make_passthrough_route("b.com", "backend", 443), // port 443
+                make_route("c.com", "backend", 9090, 80),       // port 80 (duplicate)
+            ],
+            ..Default::default()
+        };
+        let ports = options.all_listening_ports();
+        assert_eq!(ports, vec![80, 443]);
+    }
+
+    #[test]
+    fn test_camel_case_field_names() {
+        let options = RustProxyOptions {
+            connection_timeout: Some(5000),
+            max_connections_per_ip: Some(100),
+            keep_alive_treatment: Some(KeepAliveTreatment::Extended),
+            ..Default::default()
+        };
+        let json = serde_json::to_string(&options).unwrap();
+        assert!(json.contains("connectionTimeout"));
+        assert!(json.contains("maxConnectionsPerIp"));
+        assert!(json.contains("keepAliveTreatment"));
+    }
+
+    #[test]
+    fn test_deserialize_example_json() {
+        let content = std::fs::read_to_string(
+            concat!(env!("CARGO_MANIFEST_DIR"), "/../../config/example.json")
+        ).unwrap();
+        let options: RustProxyOptions = serde_json::from_str(&content).unwrap();
+        assert_eq!(options.routes.len(), 4);
+        let ports = options.all_listening_ports();
+        assert!(ports.contains(&80));
+        assert!(ports.contains(&443));
+    }
+}

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

@@ -0,0 +1,673 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+use crate::tls_types::RouteTls;
+use crate::security_types::RouteSecurity;
+
+// ─── Port Range ──────────────────────────────────────────────────────
+
+/// Port range specification format.
+/// 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, 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 {
+    /// Expand the port range into a flat list of ports.
+    pub fn to_ports(&self) -> Vec<u16> {
+        match self {
+            PortRange::Single(p) => vec![*p],
+            PortRange::List(items) => {
+                items.iter().flat_map(|item| match item {
+                    PortRangeItem::Port(p) => vec![*p],
+                    PortRangeItem::Range(r) => (r.from..=r.to).collect(),
+                }).collect()
+            }
+        }
+    }
+}
+
+/// A from-to port range.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PortRangeSpec {
+    pub from: u16,
+    pub to: u16,
+}
+
+// ─── Route Action Type ───────────────────────────────────────────────
+
+/// Supported action types for route configurations.
+/// Matches TypeScript: `type TRouteActionType = 'forward' | 'socket-handler'`
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum RouteActionType {
+    Forward,
+    SocketHandler,
+}
+
+// ─── Route Match ─────────────────────────────────────────────────────
+
+/// Domain specification: single string or array.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum DomainSpec {
+    Single(String),
+    List(Vec<String>),
+}
+
+impl DomainSpec {
+    pub fn to_vec(&self) -> Vec<&str> {
+        match self {
+            DomainSpec::Single(s) => vec![s.as_str()],
+            DomainSpec::List(v) => v.iter().map(|s| s.as_str()).collect(),
+        }
+    }
+}
+
+// Convenience conversions for DomainSpec
+impl From<&str> for DomainSpec {
+    fn from(s: &str) -> Self {
+        DomainSpec::Single(s.to_string())
+    }
+}
+
+impl From<String> for DomainSpec {
+    fn from(s: String) -> Self {
+        DomainSpec::Single(s)
+    }
+}
+
+impl From<Vec<String>> for DomainSpec {
+    fn from(v: Vec<String>) -> Self {
+        DomainSpec::List(v)
+    }
+}
+
+impl From<Vec<&str>> for DomainSpec {
+    fn from(v: Vec<&str>) -> Self {
+        DomainSpec::List(v.into_iter().map(|s| s.to_string()).collect())
+    }
+}
+
+/// Header match value: either exact string or regex pattern.
+/// In JSON, all values come as strings. Regex patterns are prefixed with `/` and suffixed with `/`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum HeaderMatchValue {
+    Exact(String),
+}
+
+/// Route match criteria for incoming requests.
+/// Matches TypeScript: `IRouteMatch`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+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>,
+
+    /// Match specific paths
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+
+    /// Match specific client IPs
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub client_ip: Option<Vec<String>>,
+
+    /// Match specific TLS versions
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tls_version: Option<Vec<String>>,
+
+    /// Match specific HTTP headers
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<HashMap<String, String>>,
+
+    /// Match specific protocol: "http", "tcp", "udp", "quic", "http3"
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub protocol: Option<String>,
+}
+
+// ─── Target Match ────────────────────────────────────────────────────
+
+/// Target-specific match criteria for sub-routing within a route.
+/// Matches TypeScript: `ITargetMatch`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TargetMatch {
+    /// Match specific ports from the route
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ports: Option<Vec<u16>>,
+    /// Match specific paths (supports wildcards like /api/*)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub path: Option<String>,
+    /// Match specific HTTP headers
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<HashMap<String, String>>,
+    /// Match specific HTTP methods
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub method: Option<Vec<String>>,
+}
+
+// ─── WebSocket Config ────────────────────────────────────────────────
+
+/// WebSocket configuration.
+/// Matches TypeScript: `IRouteWebSocket`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteWebSocket {
+    pub enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ping_interval: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ping_timeout: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_payload_size: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub custom_headers: Option<HashMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub subprotocols: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rewrite_path: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allowed_origins: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub authenticate_request: Option<bool>,
+}
+
+// ─── Load Balancing ──────────────────────────────────────────────────
+
+/// Load balancing algorithm.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum LoadBalancingAlgorithm {
+    RoundRobin,
+    LeastConnections,
+    IpHash,
+}
+
+/// Health check configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct HealthCheck {
+    pub path: String,
+    pub interval: u64,
+    pub timeout: u64,
+    pub unhealthy_threshold: u32,
+    pub healthy_threshold: u32,
+}
+
+/// Load balancing configuration.
+/// Matches TypeScript: `IRouteLoadBalancing`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteLoadBalancing {
+    pub algorithm: LoadBalancingAlgorithm,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub health_check: Option<HealthCheck>,
+}
+
+// ─── CORS ────────────────────────────────────────────────────────────
+
+/// Allowed origin specification.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum AllowOrigin {
+    Single(String),
+    List(Vec<String>),
+}
+
+/// CORS configuration for a route.
+/// Matches TypeScript: `IRouteCors`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteCors {
+    pub enabled: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_origin: Option<AllowOrigin>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_methods: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_headers: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub allow_credentials: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expose_headers: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_age: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub preflight: Option<bool>,
+}
+
+// ─── Headers ─────────────────────────────────────────────────────────
+
+/// Headers configuration.
+/// Matches TypeScript: `IRouteHeaders`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteHeaders {
+    /// Headers to add/modify for requests to backend
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub request: Option<HashMap<String, String>>,
+    /// Headers to add/modify for responses to client
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub response: Option<HashMap<String, String>>,
+    /// CORS configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cors: Option<RouteCors>,
+}
+
+// ─── Static Files ────────────────────────────────────────────────────
+
+/// Static file server configuration.
+/// Matches TypeScript: `IRouteStaticFiles`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteStaticFiles {
+    pub root: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub index: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<HashMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub directory: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub index_files: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cache_control: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub follow_symlinks: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub disable_directory_listing: Option<bool>,
+}
+
+// ─── Test Response ───────────────────────────────────────────────────
+
+/// Test route response configuration.
+/// Matches TypeScript: `IRouteTestResponse`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteTestResponse {
+    pub status: u16,
+    pub headers: HashMap<String, String>,
+    pub body: String,
+}
+
+// ─── URL Rewriting ───────────────────────────────────────────────────
+
+/// URL rewriting configuration.
+/// Matches TypeScript: `IRouteUrlRewrite`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteUrlRewrite {
+    /// RegExp pattern to match in URL
+    pub pattern: String,
+    /// Replacement pattern
+    pub target: String,
+    /// RegExp flags
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub flags: Option<String>,
+    /// Only apply to path, not query string
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub only_rewrite_path: Option<bool>,
+}
+
+// ─── Advanced Options ────────────────────────────────────────────────
+
+/// Advanced options for route actions.
+/// Matches TypeScript: `IRouteAdvanced`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteAdvanced {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<HashMap<String, String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub keep_alive: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub static_files: Option<RouteStaticFiles>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub test_response: Option<RouteTestResponse>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub url_rewrite: Option<RouteUrlRewrite>,
+}
+
+// ─── Backend Protocol ────────────────────────────────────────────────
+
+/// Backend protocol.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+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")]
+pub struct ActionOptions {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub backend_protocol: Option<BackendProtocol>,
+    /// Catch-all for additional options
+    #[serde(flatten)]
+    pub extra: HashMap<String, serde_json::Value>,
+}
+
+// ─── Route Target ────────────────────────────────────────────────────
+
+/// Host specification: single string or array of strings.
+/// Note: Dynamic host functions are only available via programmatic API, not JSON.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum HostSpec {
+    Single(String),
+    List(Vec<String>),
+}
+
+impl HostSpec {
+    pub fn to_vec(&self) -> Vec<&str> {
+        match self {
+            HostSpec::Single(s) => vec![s.as_str()],
+            HostSpec::List(v) => v.iter().map(|s| s.as_str()).collect(),
+        }
+    }
+
+    pub fn first(&self) -> &str {
+        match self {
+            HostSpec::Single(s) => s.as_str(),
+            HostSpec::List(v) => v.first().map(|s| s.as_str()).unwrap_or(""),
+        }
+    }
+}
+
+/// Port specification: number or "preserve".
+/// Note: Dynamic port functions are only available via programmatic API, not JSON.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum PortSpec {
+    /// Fixed port number
+    Fixed(u16),
+    /// Special string value like "preserve"
+    Special(String),
+}
+
+impl PortSpec {
+    /// Resolve the port, using incoming_port when "preserve" is specified.
+    pub fn resolve(&self, incoming_port: u16) -> u16 {
+        match self {
+            PortSpec::Fixed(p) => *p,
+            PortSpec::Special(s) if s == "preserve" => incoming_port,
+            PortSpec::Special(_) => incoming_port, // fallback
+        }
+    }
+}
+
+/// Target configuration for forwarding with sub-matching and overrides.
+/// Matches TypeScript: `IRouteTarget`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteTarget {
+    /// Optional sub-matching criteria within the route
+    #[serde(rename = "match")]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_match: Option<TargetMatch>,
+
+    /// Target host(s)
+    pub host: HostSpec,
+
+    /// Target port
+    pub port: PortSpec,
+
+    /// Override route-level TLS settings
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tls: Option<RouteTls>,
+
+    /// Override route-level WebSocket settings
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub websocket: Option<RouteWebSocket>,
+
+    /// Override route-level load balancing
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub load_balancing: Option<RouteLoadBalancing>,
+
+    /// Override route-level proxy protocol setting
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub send_proxy_protocol: Option<bool>,
+
+    /// Override route-level headers
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<RouteHeaders>,
+
+    /// Override route-level advanced settings
+    #[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>,
+}
+
+// ─── Route Action ────────────────────────────────────────────────────
+
+/// Action configuration for route handling.
+/// Matches TypeScript: `IRouteAction`
+///
+/// Note: `socketHandler` is not serializable in JSON. Use the programmatic API
+/// for socket handler routes.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteAction {
+    /// Basic routing type
+    #[serde(rename = "type")]
+    pub action_type: RouteActionType,
+
+    /// Targets for forwarding (array supports multiple targets with sub-matching)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub targets: Option<Vec<RouteTarget>>,
+
+    /// TLS handling (default for all targets)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tls: Option<RouteTls>,
+
+    /// WebSocket support (default for all targets)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub websocket: Option<RouteWebSocket>,
+
+    /// Load balancing options (default for all targets)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub load_balancing: Option<RouteLoadBalancing>,
+
+    /// Advanced options (default for all targets)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub advanced: Option<RouteAdvanced>,
+
+    /// Additional options
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub options: Option<ActionOptions>,
+
+    /// 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 ────────────────────────────────────────────────────
+
+/// The core unified configuration interface.
+/// Matches TypeScript: `IRouteConfig`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteConfig {
+    /// Unique identifier
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+
+    /// What to match
+    #[serde(rename = "match")]
+    pub route_match: RouteMatch,
+
+    /// What to do with matched traffic
+    pub action: RouteAction,
+
+    /// Custom headers
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<RouteHeaders>,
+
+    /// Security features
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub security: Option<RouteSecurity>,
+
+    /// Human-readable name for this route
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+
+    /// Description of the route's purpose
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+
+    /// Controls matching order (higher = matched first)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub priority: Option<i32>,
+
+    /// Arbitrary tags for categorization
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tags: Option<Vec<String>>,
+
+    /// Whether the route is active (default: true)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+}
+
+impl RouteConfig {
+    /// Check if this route is enabled (defaults to true).
+    pub fn is_enabled(&self) -> bool {
+        self.enabled.unwrap_or(true)
+    }
+
+    /// Get the effective priority (defaults to 0).
+    pub fn effective_priority(&self) -> i32 {
+        self.priority.unwrap_or(0)
+    }
+
+    /// Get all ports this route listens on.
+    pub fn listening_ports(&self) -> Vec<u16> {
+        self.route_match.ports.to_ports()
+    }
+
+    /// Get the TLS mode for this route (from action-level or first target).
+    pub fn tls_mode(&self) -> Option<&crate::tls_types::TlsMode> {
+        // Check action-level TLS first
+        if let Some(tls) = &self.action.tls {
+            return Some(&tls.mode);
+        }
+        // Check first target's TLS
+        if let Some(targets) = &self.action.targets {
+            if let Some(first) = targets.first() {
+                if let Some(tls) = &first.tls {
+                    return Some(&tls.mode);
+                }
+            }
+        }
+        None
+    }
+}

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

@@ -0,0 +1,132 @@
+use serde::{Deserialize, Serialize};
+
+/// Rate limiting configuration.
+/// Matches TypeScript: `IRouteRateLimit`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteRateLimit {
+    pub enabled: bool,
+    pub max_requests: u64,
+    /// Time window in seconds
+    pub window: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub key_by: Option<RateLimitKeyBy>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub header_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error_message: Option<String>,
+}
+
+/// Rate limit key selection.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum RateLimitKeyBy {
+    Ip,
+    Path,
+    Header,
+}
+
+/// Authentication type.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum AuthenticationType {
+    Basic,
+    Digest,
+    Oauth,
+    Jwt,
+}
+
+/// Authentication credentials.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AuthCredentials {
+    pub username: String,
+    pub password: String,
+}
+
+/// Authentication options.
+/// Matches TypeScript: `IRouteAuthentication`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteAuthentication {
+    #[serde(rename = "type")]
+    pub auth_type: AuthenticationType,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub credentials: Option<Vec<AuthCredentials>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub realm: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jwt_secret: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jwt_issuer: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub oauth_provider: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub oauth_client_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub oauth_client_secret: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub oauth_redirect_uri: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub options: Option<serde_json::Value>,
+}
+
+/// Basic auth configuration.
+/// Matches TypeScript: `IRouteSecurity.basicAuth`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BasicAuthConfig {
+    pub enabled: bool,
+    pub users: Vec<AuthCredentials>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub realm: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exclude_paths: Option<Vec<String>>,
+}
+
+/// JWT auth configuration.
+/// Matches TypeScript: `IRouteSecurity.jwtAuth`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct JwtAuthConfig {
+    pub enabled: bool,
+    pub secret: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub algorithm: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub issuer: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub audience: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_in: Option<u64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub exclude_paths: Option<Vec<String>>,
+}
+
+/// Security options for routes.
+/// Matches TypeScript: `IRouteSecurity`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteSecurity {
+    /// IP addresses that are allowed to connect
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ip_allow_list: Option<Vec<String>>,
+    /// IP addresses that are blocked from connecting
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ip_block_list: Option<Vec<String>>,
+    /// Maximum concurrent connections
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_connections: Option<u64>,
+    /// Authentication configuration
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub authentication: Option<RouteAuthentication>,
+    /// Rate limiting
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rate_limit: Option<RouteRateLimit>,
+    /// Basic auth
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub basic_auth: Option<BasicAuthConfig>,
+    /// JWT auth
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub jwt_auth: Option<JwtAuthConfig>,
+}

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

@@ -0,0 +1,93 @@
+use serde::{Deserialize, Serialize};
+
+/// TLS handling modes for route configurations.
+/// Matches TypeScript: `type TTlsMode = 'passthrough' | 'terminate' | 'terminate-and-reencrypt'`
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum TlsMode {
+    Passthrough,
+    Terminate,
+    TerminateAndReencrypt,
+}
+
+/// Static certificate configuration (PEM-encoded).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CertificateConfig {
+    /// PEM-encoded private key
+    pub key: String,
+    /// PEM-encoded certificate
+    pub cert: String,
+    /// PEM-encoded CA chain
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ca: Option<String>,
+    /// Path to key file (overrides key)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub key_file: Option<String>,
+    /// Path to cert file (overrides cert)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cert_file: Option<String>,
+}
+
+/// Certificate specification: either automatic (ACME) or static.
+/// Matches TypeScript: `certificate?: 'auto' | { key, cert, ca?, keyFile?, certFile? }`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum CertificateSpec {
+    /// Use ACME (Let's Encrypt) for automatic provisioning
+    Auto(String), // "auto"
+    /// Static certificate configuration
+    Static(CertificateConfig),
+}
+
+impl CertificateSpec {
+    /// Check if this is an auto (ACME) certificate
+    pub fn is_auto(&self) -> bool {
+        matches!(self, CertificateSpec::Auto(s) if s == "auto")
+    }
+}
+
+/// ACME configuration for automatic certificate provisioning.
+/// Matches TypeScript: `IRouteAcme`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteAcme {
+    /// Contact email for ACME account
+    pub email: String,
+    /// Use production ACME servers (default: false)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub use_production: Option<bool>,
+    /// Port for HTTP-01 challenges (default: 80)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub challenge_port: Option<u16>,
+    /// Days before expiry to renew (default: 30)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub renew_before_days: Option<u32>,
+}
+
+/// TLS configuration for route actions.
+/// Matches TypeScript: `IRouteTls`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RouteTls {
+    /// TLS mode (passthrough, terminate, terminate-and-reencrypt)
+    pub mode: TlsMode,
+    /// Certificate configuration (auto or static)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub certificate: Option<CertificateSpec>,
+    /// ACME options when certificate is 'auto'
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub acme: Option<RouteAcme>,
+    /// Allowed TLS versions
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub versions: Option<Vec<String>>,
+    /// OpenSSL cipher string
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ciphers: Option<String>,
+    /// Use server's cipher preferences
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub honor_cipher_order: Option<bool>,
+    /// TLS session timeout in seconds
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub session_timeout: Option<u64>,
+}

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

@@ -0,0 +1,200 @@
+use thiserror::Error;
+
+use crate::route_types::{RouteConfig, RouteActionType};
+
+/// Validation errors for route configurations.
+#[derive(Debug, Error)]
+pub enum ValidationError {
+    #[error("Route '{name}' has no targets but action type is 'forward'")]
+    MissingTargets { name: String },
+
+    #[error("Route '{name}' has empty targets list")]
+    EmptyTargets { name: String },
+
+    #[error("Route '{name}' has no ports specified")]
+    NoPorts { name: String },
+
+    #[error("Route '{name}' port {port} is invalid (must be 1-65535)")]
+    InvalidPort { name: String, port: u16 },
+
+    #[error("Route '{name}': socket-handler action type is not supported in JSON config")]
+    SocketHandlerInJson { name: String },
+
+    #[error("Route '{name}': duplicate route ID '{id}'")]
+    DuplicateId { name: String, id: String },
+
+    #[error("Route '{name}': {message}")]
+    Custom { name: String, message: String },
+}
+
+/// Validate a single route configuration.
+pub fn validate_route(route: &RouteConfig) -> Result<(), Vec<ValidationError>> {
+    let mut errors = Vec::new();
+    let name = route.name.clone().unwrap_or_else(|| {
+        route.id.clone().unwrap_or_else(|| "unnamed".to_string())
+    });
+
+    // Check ports
+    let ports = route.listening_ports();
+    if ports.is_empty() {
+        errors.push(ValidationError::NoPorts { name: name.clone() });
+    }
+    for &port in &ports {
+        if port == 0 {
+            errors.push(ValidationError::InvalidPort {
+                name: name.clone(),
+                port,
+            });
+        }
+    }
+
+    // Check forward action has targets
+    if route.action.action_type == RouteActionType::Forward {
+        match &route.action.targets {
+            None => {
+                errors.push(ValidationError::MissingTargets { name: name.clone() });
+            }
+            Some(targets) if targets.is_empty() => {
+                errors.push(ValidationError::EmptyTargets { name: name.clone() });
+            }
+            _ => {}
+        }
+    }
+
+    if errors.is_empty() {
+        Ok(())
+    } else {
+        Err(errors)
+    }
+}
+
+/// Validate an entire list of routes.
+pub fn validate_routes(routes: &[RouteConfig]) -> Result<(), Vec<ValidationError>> {
+    let mut all_errors = Vec::new();
+    let mut seen_ids = std::collections::HashSet::new();
+
+    for route in routes {
+        // Check for duplicate IDs
+        if let Some(id) = &route.id {
+            if !seen_ids.insert(id.clone()) {
+                let name = route.name.clone().unwrap_or_else(|| id.clone());
+                all_errors.push(ValidationError::DuplicateId {
+                    name,
+                    id: id.clone(),
+                });
+            }
+        }
+
+        // Validate individual route
+        if let Err(errors) = validate_route(route) {
+            all_errors.extend(errors);
+        }
+    }
+
+    if all_errors.is_empty() {
+        Ok(())
+    } else {
+        Err(all_errors)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::route_types::*;
+
+    fn make_valid_route() -> RouteConfig {
+        RouteConfig {
+            id: None,
+            route_match: RouteMatch {
+                ports: PortRange::Single(80),
+                domains: Some(DomainSpec::Single("example.com".to_string())),
+                path: None,
+                client_ip: None,
+                transport: None,
+                tls_version: None,
+                headers: None,
+                protocol: None,
+            },
+            action: RouteAction {
+                action_type: RouteActionType::Forward,
+                targets: Some(vec![RouteTarget {
+                    target_match: None,
+                    host: HostSpec::Single("localhost".to_string()),
+                    port: PortSpec::Fixed(8080),
+                    tls: None,
+                    websocket: None,
+                    load_balancing: None,
+                    send_proxy_protocol: None,
+                    headers: None,
+                    advanced: None,
+                    backend_transport: None,
+                    priority: None,
+                }]),
+                tls: None,
+                websocket: None,
+                load_balancing: None,
+                advanced: None,
+                options: None,
+                send_proxy_protocol: None,
+                udp: None,
+            },
+            headers: None,
+            security: None,
+            name: None,
+            description: None,
+            priority: None,
+            tags: None,
+            enabled: None,
+        }
+    }
+
+    #[test]
+    fn test_valid_route_passes() {
+        let route = make_valid_route();
+        assert!(validate_route(&route).is_ok());
+    }
+
+    #[test]
+    fn test_missing_targets() {
+        let mut route = make_valid_route();
+        route.action.targets = None;
+        let errors = validate_route(&route).unwrap_err();
+        assert!(errors.iter().any(|e| matches!(e, ValidationError::MissingTargets { .. })));
+    }
+
+    #[test]
+    fn test_empty_targets() {
+        let mut route = make_valid_route();
+        route.action.targets = Some(vec![]);
+        let errors = validate_route(&route).unwrap_err();
+        assert!(errors.iter().any(|e| matches!(e, ValidationError::EmptyTargets { .. })));
+    }
+
+    #[test]
+    fn test_invalid_port_zero() {
+        let mut route = make_valid_route();
+        route.route_match.ports = PortRange::Single(0);
+        let errors = validate_route(&route).unwrap_err();
+        assert!(errors.iter().any(|e| matches!(e, ValidationError::InvalidPort { port: 0, .. })));
+    }
+
+    #[test]
+    fn test_duplicate_ids() {
+        let mut r1 = make_valid_route();
+        r1.id = Some("route-1".to_string());
+        let mut r2 = make_valid_route();
+        r2.id = Some("route-1".to_string());
+        let errors = validate_routes(&[r1, r2]).unwrap_err();
+        assert!(errors.iter().any(|e| matches!(e, ValidationError::DuplicateId { .. })));
+    }
+
+    #[test]
+    fn test_multiple_errors_collected() {
+        let mut r1 = make_valid_route();
+        r1.action.targets = None; // MissingTargets
+        r1.route_match.ports = PortRange::Single(0); // InvalidPort
+        let errors = validate_route(&r1).unwrap_err();
+        assert!(errors.len() >= 2);
+    }
+}

rust/crates/rustproxy-http/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "rustproxy-http"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Hyper-based HTTP proxy service for RustProxy"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+rustproxy-routing = { workspace = true }
+rustproxy-security = { workspace = true }
+rustproxy-metrics = { workspace = true }
+hyper = { workspace = true }
+hyper-util = { workspace = true }
+regex = { workspace = true }
+http-body = { workspace = true }
+http-body-util = { workspace = true }
+bytes = { workspace = true }
+tokio = { workspace = true }
+rustls = { workspace = true }
+tokio-rustls = { workspace = true }
+tracing = { workspace = true }
+thiserror = { workspace = true }
+anyhow = { workspace = true }
+arc-swap = { workspace = true }
+dashmap = { workspace = true }
+tokio-util = { workspace = true }
+socket2 = { workspace = true }
+quinn = { workspace = true }
+h3 = { workspace = true }
+h3-quinn = { workspace = true }
+futures = { version = "0.3", default-features = false, features = ["std"] }

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

@@ -0,0 +1,313 @@
+//! 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 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};
+
+/// Maximum idle connections per backend key.
+const MAX_IDLE_PER_KEY: usize = 16;
+/// Default idle timeout — connections not used within this window are evicted.
+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.
+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)]
+pub struct PoolKey {
+    pub host: String,
+    pub port: u16,
+    pub use_tls: bool,
+    pub protocol: PoolProtocol,
+}
+
+/// An idle HTTP/1.1 sender with a timestamp for eviction.
+struct IdleH1 {
+    sender: http1::SendRequest<BoxBody<Bytes, hyper::Error>>,
+    idle_since: Instant,
+}
+
+/// 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).
+/// Stores the h3 `SendRequest` handle so pool hits skip the h3 SETTINGS handshake.
+pub struct PooledH3 {
+    /// Multiplexed h3 request handle — clone to open a new stream.
+    pub send_request: h3::client::SendRequest<h3_quinn::OpenStreams, Bytes>,
+    /// Raw QUIC connection — kept for liveness probing (close_reason) only.
+    pub connection: quinn::Connection,
+    pub created_at: Instant,
+    pub generation: u64,
+}
+
+/// Backend connection pool.
+pub struct ConnectionPool {
+    /// HTTP/1.1 idle connections indexed by backend key.
+    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<()>>,
+}
+
+impl ConnectionPool {
+    /// Create a new pool and start the background eviction task.
+    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, h3_clone).await;
+        });
+
+        Self {
+            h1_pool,
+            h2_pool,
+            h3_pool,
+            h2_generation: AtomicU64::new(0),
+            eviction_handle: Some(eviction_handle),
+        }
+    }
+
+    /// Try to check out an idle HTTP/1.1 sender for the given key.
+    /// Returns `None` if no usable idle connection exists.
+    pub fn checkout_h1(&self, key: &PoolKey) -> Option<http1::SendRequest<BoxBody<Bytes, hyper::Error>>> {
+        let mut entry = self.h1_pool.get_mut(key)?;
+        let idles = entry.value_mut();
+
+        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() {
+                // H1 pool hit — no logging on hot path
+                return Some(idle.sender);
+            }
+            // Stale or closed — drop it
+        }
+
+        // Clean up empty entry
+        if idles.is_empty() {
+            drop(entry);
+            self.h1_pool.remove(key);
+        }
+        None
+    }
+
+    /// Return an HTTP/1.1 sender to the pool after the response body has been prepared.
+    /// The caller should NOT call this if the sender is closed or not ready.
+    pub fn checkin_h1(&self, key: PoolKey, sender: http1::SendRequest<BoxBody<Bytes, hyper::Error>>) {
+        if sender.is_closed() || !sender.is_ready() {
+            return; // Don't pool broken connections
+        }
+
+        let mut entry = self.h1_pool.entry(key).or_insert_with(Vec::new);
+        if entry.value().len() < MAX_IDLE_PER_KEY {
+            entry.value_mut().push(IdleH1 {
+                sender,
+                idle_since: Instant::now(),
+            });
+        }
+        // If at capacity, just drop the sender
+    }
+
+    /// 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>>, Duration)> {
+        let entry = self.h2_pool.get(key)?;
+        let pooled = entry.value();
+        let age = pooled.created_at.elapsed();
+
+        if pooled.sender.is_closed() || age >= MAX_H2_AGE {
+            drop(entry);
+            self.h2_pool.remove(key);
+            return None;
+        }
+
+        if pooled.sender.is_ready() {
+            return Some((pooled.sender.clone(), age));
+        }
+        None
+    }
+
+    /// 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);
+    }
+
+    /// 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 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<(h3::client::SendRequest<h3_quinn::OpenStreams, Bytes>, 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.send_request.clone(), pooled.connection.clone(), age))
+    }
+
+    /// Register a QUIC connection and its h3 SendRequest handle in the pool.
+    /// Returns the generation ID.
+    pub fn register_h3(
+        &self,
+        key: PoolKey,
+        connection: quinn::Connection,
+        send_request: h3::client::SendRequest<h3_quinn::OpenStreams, Bytes>,
+    ) -> u64 {
+        let gen = self.h2_generation.fetch_add(1, Ordering::Relaxed);
+        self.h3_pool.insert(key, PooledH3 {
+            send_request,
+            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 {
+            interval.tick().await;
+
+            // Evict stale H1 connections
+            let mut empty_keys = Vec::new();
+            for mut entry in h1_pool.iter_mut() {
+                entry.value_mut().retain(|idle| {
+                    idle.idle_since.elapsed() < IDLE_TIMEOUT && !idle.sender.is_closed()
+                });
+                if entry.value().is_empty() {
+                    empty_keys.push(entry.key().clone());
+                }
+            }
+            for key in empty_keys {
+                h1_pool.remove(&key);
+            }
+
+            // Evict dead or aged-out H2 connections
+            let mut dead_h2 = Vec::new();
+            for entry in h2_pool.iter() {
+                if entry.value().sender.is_closed() || entry.value().created_at.elapsed() >= MAX_H2_AGE {
+                    dead_h2.push(entry.key().clone());
+                }
+            }
+            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);
+            }
+        }
+    }
+}
+
+impl Drop for ConnectionPool {
+    fn drop(&mut self) {
+        if let Some(handle) = self.eviction_handle.take() {
+            handle.abort();
+        }
+    }
+}

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

@@ -0,0 +1,172 @@
+//! A body wrapper that counts bytes flowing through and reports them to MetricsCollector.
+
+use std::pin::Pin;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::task::{Context, Poll};
+
+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.
+///
+/// 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<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.
+#[derive(Clone, Copy)]
+pub enum Direction {
+    /// Request body: bytes flowing from client → upstream (counted as bytes_in)
+    In,
+    /// Response body: bytes flowing from upstream → client (counted as bytes_out)
+    Out,
+}
+
+impl<B> CountingBody<B> {
+    /// Create a new CountingBody wrapping an inner body.
+    pub fn new(
+        inner: B,
+        metrics: Arc<MetricsCollector>,
+        route_id: Option<Arc<str>>,
+        source_ip: Option<Arc<str>>,
+        direction: Direction,
+    ) -> Self {
+        Self {
+            inner: Box::pin(inner),
+            metrics,
+            route_id,
+            source_ip,
+            direction,
+            pending_bytes: 0,
+            connection_activity: None,
+            activity_start: None,
+            active_requests: None,
+        }
+    }
+
+    /// Set the connection-level activity tracker. When set, each data frame
+    /// updates this timestamp to prevent the idle watchdog from killing the
+    /// connection during active body streaming.
+    pub fn with_connection_activity(mut self, activity: Arc<AtomicU64>, start: std::time::Instant) -> Self {
+        self.connection_activity = Some(activity);
+        self.activity_start = Some(start);
+        self
+    }
+
+    /// 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 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(bytes, 0, route_id, source_ip),
+            Direction::Out => self.metrics.record_bytes(0, bytes, route_id, source_ip),
+        }
+    }
+}
+
+// CountingBody is Unpin because inner is Pin<Box<B>> (always Unpin).
+impl<B> Unpin for CountingBody<B> {}
+
+impl<B> http_body::Body for CountingBody<B>
+where
+    B: http_body::Body<Data = Bytes>,
+{
+    type Data = Bytes;
+    type Error = B::Error;
+
+    fn poll_frame(
+        self: Pin<&mut Self>,
+        cx: &mut Context<'_>,
+    ) -> Poll<Option<Result<Frame<Self::Data>, Self::Error>>> {
+        let this = self.get_mut();
+
+        match this.inner.as_mut().poll_frame(cx) {
+            Poll::Ready(Some(Ok(frame))) => {
+                if let Some(data) = frame.data_ref() {
+                    let len = data.len() as u64;
+                    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);
+                    }
+                }
+                Poll::Ready(Some(Ok(frame)))
+            }
+            Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))),
+            Poll::Ready(None) => {
+                // End of stream — flush any remaining bytes
+                this.flush_pending();
+                Poll::Ready(None)
+            }
+            Poll::Pending => Poll::Pending,
+        }
+    }
+
+    fn is_end_stream(&self) -> bool {
+        self.inner.is_end_stream()
+    }
+
+    fn size_hint(&self) -> http_body::SizeHint {
+        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,222 @@
+//! 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>(32);
+
+    // 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 = chunk.copy_to_bytes(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 Ok(data) = frame.into_data() {
+                    stream.send_data(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

@@ -0,0 +1,21 @@
+//! # rustproxy-http
+//!
+//! Hyper-based HTTP proxy service for RustProxy.
+//! Handles HTTP request parsing, route-based forwarding, and response filtering.
+
+pub mod connection_pool;
+pub mod counting_body;
+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::*;
+pub use proxy_service::*;
+pub use template::*;
+pub use upstream_selector::*;

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

@@ -0,0 +1,631 @@
+//! Bounded, sliding-TTL protocol detection cache with periodic re-probing and failure suppression.
+//!
+//! 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 protocol support.
+//!
+//! ## Sliding TTL
+//!
+//! Each cache hit refreshes the entry's expiry timer (`last_accessed_at`). Entries
+//! remain valid for up to 1 day of continuous use. Every 5 minutes, the next request
+//! triggers an inline ALPN re-probe to verify the cached protocol is still correct.
+//!
+//! ## Upgrade signals
+//!
+//! - ALPN (TLS handshake) → detects H2 vs H1
+//! - Alt-Svc (response header) → advertises H3
+//!
+//! ## Protocol transitions
+//!
+//! All protocol changes are logged at `info!()` level with the reason:
+//! "Protocol transition: H1 → H2 because periodic ALPN re-probe"
+//!
+//! ## Failure suppression
+//!
+//! When a protocol fails, `record_failure()` prevents upgrade signals from
+//! re-introducing it until an escalating cooldown expires (5s → 10s → ... → 300s).
+//! Within-request escalation is allowed via `can_retry()` after a 5s minimum gap.
+//!
+//! ## Total failure eviction
+//!
+//! When all protocols (H3, H2, H1) fail for a backend, the cache entry is evicted
+//! entirely via `evict()`, forcing a fresh probe on the next request.
+//!
+//! Cascading: when a lower protocol also fails, higher protocol cooldowns are
+//! reduced to 5s remaining (not instant clear), preventing tight retry loops.
+
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use dashmap::DashMap;
+use tracing::{debug, info};
+
+/// Sliding TTL for cached protocol detection results.
+/// Entries that haven't been accessed for this duration are evicted.
+/// Each `get()` call refreshes the timer (sliding window).
+const PROTOCOL_CACHE_TTL: Duration = Duration::from_secs(86400); // 1 day
+
+/// Interval between inline ALPN re-probes for H1/H2 entries.
+/// When a cached entry's `last_probed_at` exceeds this, the next request
+/// triggers an ALPN re-probe to verify the backend still speaks the same protocol.
+const PROTOCOL_REPROBE_INTERVAL: Duration = Duration::from_secs(300); // 5 minutes
+
+/// Maximum number of entries in the protocol cache.
+const PROTOCOL_CACHE_MAX_ENTRIES: usize = 4096;
+
+/// Background cleanup interval.
+const PROTOCOL_CACHE_CLEANUP_INTERVAL: Duration = Duration::from_secs(60);
+
+/// Minimum cooldown between retry attempts of a failed protocol.
+const PROTOCOL_FAILURE_COOLDOWN: Duration = Duration::from_secs(5);
+
+/// Maximum cooldown (escalation ceiling).
+const PROTOCOL_FAILURE_MAX_COOLDOWN: Duration = Duration::from_secs(300);
+
+/// Consecutive failure count at which cooldown reaches maximum.
+/// 5s × 2^5 = 160s, 5s × 2^6 = 320s → capped at 300s.
+const PROTOCOL_FAILURE_ESCALATION_CAP: u32 = 6;
+
+/// Detected backend protocol.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DetectedProtocol {
+    H1,
+    H2,
+    H3,
+}
+
+impl std::fmt::Display for DetectedProtocol {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            DetectedProtocol::H1 => write!(f, "H1"),
+            DetectedProtocol::H2 => write!(f, "H2"),
+            DetectedProtocol::H3 => write!(f, "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>,
+    /// True if the entry's `last_probed_at` exceeds `PROTOCOL_REPROBE_INTERVAL`.
+    /// Caller should perform an inline ALPN re-probe and call `update_probe_result()`.
+    /// Always `false` for H3 entries (H3 is discovered via Alt-Svc, not ALPN).
+    pub needs_reprobe: bool,
+}
+
+/// Key for the protocol cache: (host, port, requested_host).
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub struct ProtocolCacheKey {
+    pub host: String,
+    pub port: u16,
+    /// The incoming request's domain (Host header / :authority).
+    /// Distinguishes protocol detection when multiple domains share the same backend.
+    pub requested_host: Option<String>,
+}
+
+/// A cached protocol detection result with timestamps.
+struct CachedEntry {
+    protocol: DetectedProtocol,
+    /// When this protocol was first detected (or last changed).
+    detected_at: Instant,
+    /// Last time any request used this entry (sliding-window TTL).
+    last_accessed_at: Instant,
+    /// Last time an ALPN re-probe was performed for this entry.
+    last_probed_at: Instant,
+    /// For H3: the port advertised by Alt-Svc (may differ from TCP port).
+    h3_port: Option<u16>,
+}
+
+/// Failure record for a single protocol level.
+#[derive(Debug, Clone)]
+struct FailureRecord {
+    /// When the failure was last recorded.
+    failed_at: Instant,
+    /// Current cooldown duration. Escalates on consecutive failures.
+    cooldown: Duration,
+    /// Number of consecutive failures (for escalation).
+    consecutive_failures: u32,
+}
+
+/// Per-key failure state. Tracks failures at each upgradeable protocol level.
+/// H1 is never tracked (it's the protocol floor — nothing to fall back to).
+#[derive(Debug, Clone, Default)]
+struct FailureState {
+    h2: Option<FailureRecord>,
+    h3: Option<FailureRecord>,
+}
+
+impl FailureState {
+    fn is_empty(&self) -> bool {
+        self.h2.is_none() && self.h3.is_none()
+    }
+
+    fn all_expired(&self) -> bool {
+        let h2_expired = self.h2.as_ref()
+            .map(|r| r.failed_at.elapsed() >= r.cooldown)
+            .unwrap_or(true);
+        let h3_expired = self.h3.as_ref()
+            .map(|r| r.failed_at.elapsed() >= r.cooldown)
+            .unwrap_or(true);
+        h2_expired && h3_expired
+    }
+
+    fn get(&self, protocol: DetectedProtocol) -> Option<&FailureRecord> {
+        match protocol {
+            DetectedProtocol::H2 => self.h2.as_ref(),
+            DetectedProtocol::H3 => self.h3.as_ref(),
+            DetectedProtocol::H1 => None,
+        }
+    }
+
+    fn get_mut(&mut self, protocol: DetectedProtocol) -> &mut Option<FailureRecord> {
+        match protocol {
+            DetectedProtocol::H2 => &mut self.h2,
+            DetectedProtocol::H3 => &mut self.h3,
+            DetectedProtocol::H1 => unreachable!("H1 failures are never recorded"),
+        }
+    }
+}
+
+/// Snapshot of a single protocol cache entry, suitable for metrics/UI display.
+#[derive(Debug, Clone)]
+pub struct ProtocolCacheEntry {
+    pub host: String,
+    pub port: u16,
+    pub domain: Option<String>,
+    pub protocol: String,
+    pub h3_port: Option<u16>,
+    pub age_secs: u64,
+    pub last_accessed_secs: u64,
+    pub last_probed_secs: u64,
+    pub h2_suppressed: bool,
+    pub h3_suppressed: bool,
+    pub h2_cooldown_remaining_secs: Option<u64>,
+    pub h3_cooldown_remaining_secs: Option<u64>,
+    pub h2_consecutive_failures: Option<u32>,
+    pub h3_consecutive_failures: Option<u32>,
+}
+
+/// Exponential backoff: PROTOCOL_FAILURE_COOLDOWN × 2^(n-1), capped at MAX.
+fn escalate_cooldown(consecutive: u32) -> Duration {
+    let base = PROTOCOL_FAILURE_COOLDOWN.as_secs();
+    let exp = consecutive.saturating_sub(1).min(63) as u64;
+    let secs = base.saturating_mul(1u64.checked_shl(exp as u32).unwrap_or(u64::MAX));
+    Duration::from_secs(secs.min(PROTOCOL_FAILURE_MAX_COOLDOWN.as_secs()))
+}
+
+/// Bounded, sliding-TTL protocol detection cache with failure suppression.
+///
+/// Memory safety guarantees:
+/// - Hard cap at `PROTOCOL_CACHE_MAX_ENTRIES` — cannot grow unboundedly.
+/// - Sliding TTL expiry — entries age out after 1 day without access.
+/// - Background cleanup task — proactively removes expired entries every 60s.
+/// - `clear()` — called on route updates to discard stale detections.
+/// - `Drop` — aborts the background task to prevent dangling tokio tasks.
+pub struct ProtocolCache {
+    cache: Arc<DashMap<ProtocolCacheKey, CachedEntry>>,
+    /// Generic protocol failure suppression map. Tracks per-protocol failure
+    /// records (H2, H3) for each cache key. Used to prevent upgrade signals
+    /// (ALPN, Alt-Svc) from re-introducing failed protocols.
+    failures: Arc<DashMap<ProtocolCacheKey, FailureState>>,
+    cleanup_handle: Option<tokio::task::JoinHandle<()>>,
+}
+
+impl ProtocolCache {
+    /// Create a new protocol cache and start the background cleanup task.
+    pub fn new() -> Self {
+        let cache: Arc<DashMap<ProtocolCacheKey, CachedEntry>> = Arc::new(DashMap::new());
+        let failures: Arc<DashMap<ProtocolCacheKey, FailureState>> = Arc::new(DashMap::new());
+        let cache_clone = Arc::clone(&cache);
+        let failures_clone = Arc::clone(&failures);
+        let cleanup_handle = tokio::spawn(async move {
+            Self::cleanup_loop(cache_clone, failures_clone).await;
+        });
+
+        Self {
+            cache,
+            failures,
+            cleanup_handle: Some(cleanup_handle),
+        }
+    }
+
+    /// Look up the cached protocol for a backend endpoint.
+    ///
+    /// Returns `None` if not cached or expired (caller should probe via ALPN).
+    /// On hit, refreshes `last_accessed_at` (sliding TTL) and sets `needs_reprobe`
+    /// if the entry hasn't been probed in over 5 minutes (H1/H2 only).
+    pub fn get(&self, key: &ProtocolCacheKey) -> Option<CachedProtocol> {
+        let mut entry = self.cache.get_mut(key)?;
+        if entry.last_accessed_at.elapsed() < PROTOCOL_CACHE_TTL {
+            // Refresh sliding TTL
+            entry.last_accessed_at = Instant::now();
+
+            // H3 is the ceiling — can't ALPN-probe for H3 (discovered via Alt-Svc).
+            // Only H1/H2 entries trigger periodic re-probing.
+            let needs_reprobe = entry.protocol != DetectedProtocol::H3
+                && entry.last_probed_at.elapsed() >= PROTOCOL_REPROBE_INTERVAL;
+
+            Some(CachedProtocol {
+                protocol: entry.protocol,
+                h3_port: entry.h3_port,
+                needs_reprobe,
+            })
+        } else {
+            // Expired — remove and return None to trigger re-probe
+            drop(entry); // release DashMap ref before remove
+            self.cache.remove(key);
+            None
+        }
+    }
+
+    /// Insert a detected protocol into the cache.
+    /// Returns `false` if suppressed due to active failure suppression.
+    ///
+    /// **Key semantic**: only suppresses if the protocol being inserted matches
+    /// a suppressed protocol. H1 inserts are NEVER suppressed — downgrades
+    /// always succeed.
+    pub fn insert(&self, key: ProtocolCacheKey, protocol: DetectedProtocol, reason: &str) -> bool {
+        if self.is_suppressed(&key, protocol) {
+            debug!(
+                host = %key.host, port = %key.port, domain = ?key.requested_host,
+                protocol = ?protocol,
+                "Protocol cache insert suppressed — recent failure"
+            );
+            return false;
+        }
+        self.insert_internal(key, protocol, None, reason);
+        true
+    }
+
+    /// Insert an H3 detection result with the Alt-Svc advertised port.
+    /// Returns `false` if H3 is suppressed.
+    pub fn insert_h3(&self, key: ProtocolCacheKey, h3_port: u16, reason: &str) -> bool {
+        if self.is_suppressed(&key, DetectedProtocol::H3) {
+            debug!(
+                host = %key.host, port = %key.port, domain = ?key.requested_host,
+                "H3 upgrade suppressed — recent failure"
+            );
+            return false;
+        }
+        self.insert_internal(key, DetectedProtocol::H3, Some(h3_port), reason);
+        true
+    }
+
+    /// Update the cache after an inline ALPN re-probe completes.
+    ///
+    /// Always updates `last_probed_at`. If the protocol changed, logs the transition
+    /// and updates the entry. Returns `Some(new_protocol)` if changed, `None` if unchanged.
+    pub fn update_probe_result(
+        &self,
+        key: &ProtocolCacheKey,
+        probed_protocol: DetectedProtocol,
+        reason: &str,
+    ) -> Option<DetectedProtocol> {
+        if let Some(mut entry) = self.cache.get_mut(key) {
+            let old_protocol = entry.protocol;
+            entry.last_probed_at = Instant::now();
+            entry.last_accessed_at = Instant::now();
+
+            if old_protocol != probed_protocol {
+                info!(
+                    host = %key.host, port = %key.port, domain = ?key.requested_host,
+                    old = %old_protocol, new = %probed_protocol, reason = %reason,
+                    "Protocol transition"
+                );
+                entry.protocol = probed_protocol;
+                entry.detected_at = Instant::now();
+                // Clear h3_port if downgrading from H3
+                if old_protocol == DetectedProtocol::H3 && probed_protocol != DetectedProtocol::H3 {
+                    entry.h3_port = None;
+                }
+                return Some(probed_protocol);
+            }
+
+            debug!(
+                host = %key.host, port = %key.port, domain = ?key.requested_host,
+                protocol = %old_protocol, reason = %reason,
+                "Re-probe confirmed — no protocol change"
+            );
+            None
+        } else {
+            // Entry was evicted between the get() and the probe completing.
+            // Insert as a fresh entry.
+            self.insert_internal(key.clone(), probed_protocol, None, reason);
+            Some(probed_protocol)
+        }
+    }
+
+    /// Record a protocol failure. Future `insert()` calls for this protocol
+    /// will be suppressed until the escalating cooldown expires.
+    ///
+    /// Cooldown escalation: 5s → 10s → 20s → 40s → 80s → 160s → 300s.
+    /// Consecutive counter resets if the previous failure is older than 2× its cooldown.
+    ///
+    /// Cascading: when H2 fails, H3 cooldown is reduced to 5s remaining.
+    /// H1 failures are ignored (H1 is the protocol floor).
+    pub fn record_failure(&self, key: ProtocolCacheKey, protocol: DetectedProtocol) {
+        if protocol == DetectedProtocol::H1 {
+            return; // H1 is the floor — nothing to suppress
+        }
+
+        let mut entry = self.failures.entry(key.clone()).or_default();
+
+        let record = entry.get_mut(protocol);
+        let (consecutive, new_cooldown) = match record {
+            Some(existing) if existing.failed_at.elapsed() < existing.cooldown.saturating_mul(2) => {
+                // Still within the "recent" window — escalate
+                let c = existing.consecutive_failures.saturating_add(1)
+                    .min(PROTOCOL_FAILURE_ESCALATION_CAP);
+                (c, escalate_cooldown(c))
+            }
+            _ => {
+                // First failure or old failure that expired long ago — reset
+                (1, PROTOCOL_FAILURE_COOLDOWN)
+            }
+        };
+
+        *record = Some(FailureRecord {
+            failed_at: Instant::now(),
+            cooldown: new_cooldown,
+            consecutive_failures: consecutive,
+        });
+
+        // Cascading: when H2 fails, reduce H3 cooldown to 5s remaining
+        if protocol == DetectedProtocol::H2 {
+            Self::reduce_cooldown_to(entry.h3.as_mut(), PROTOCOL_FAILURE_COOLDOWN);
+        }
+
+        info!(
+            host = %key.host, port = %key.port, domain = ?key.requested_host,
+            protocol = ?protocol,
+            consecutive = consecutive,
+            cooldown_secs = new_cooldown.as_secs(),
+            "Protocol failure recorded — suppressing for {:?}", new_cooldown
+        );
+    }
+
+    /// Check whether a protocol is currently suppressed for the given key.
+    /// Returns `true` if the protocol failed within its cooldown period.
+    /// H1 is never suppressed.
+    pub fn is_suppressed(&self, key: &ProtocolCacheKey, protocol: DetectedProtocol) -> bool {
+        if protocol == DetectedProtocol::H1 {
+            return false;
+        }
+        self.failures.get(key)
+            .and_then(|entry| entry.get(protocol).map(|r| r.failed_at.elapsed() < r.cooldown))
+            .unwrap_or(false)
+    }
+
+    /// Check whether a protocol can be retried (for within-request escalation).
+    /// Returns `true` if there's no failure record OR if ≥5s have passed since
+    /// the last attempt. More permissive than `is_suppressed`.
+    pub fn can_retry(&self, key: &ProtocolCacheKey, protocol: DetectedProtocol) -> bool {
+        if protocol == DetectedProtocol::H1 {
+            return true;
+        }
+        match self.failures.get(key) {
+            Some(entry) => match entry.get(protocol) {
+                Some(r) => r.failed_at.elapsed() >= PROTOCOL_FAILURE_COOLDOWN,
+                None => true, // no failure record
+            },
+            None => true,
+        }
+    }
+
+    /// Record a retry attempt WITHOUT escalating the cooldown.
+    /// Resets the `failed_at` timestamp to prevent rapid retries (5s gate).
+    /// Called before an escalation attempt. If the attempt fails,
+    /// `record_failure` should be called afterward with proper escalation.
+    pub fn record_retry_attempt(&self, key: &ProtocolCacheKey, protocol: DetectedProtocol) {
+        if protocol == DetectedProtocol::H1 {
+            return;
+        }
+        if let Some(mut entry) = self.failures.get_mut(key) {
+            if let Some(ref mut r) = entry.get_mut(protocol) {
+                r.failed_at = Instant::now();
+            }
+        }
+    }
+
+    /// Clear the failure record for a protocol (it recovered).
+    /// Called when an escalation retry succeeds.
+    pub fn clear_failure(&self, key: &ProtocolCacheKey, protocol: DetectedProtocol) {
+        if protocol == DetectedProtocol::H1 {
+            return;
+        }
+        if let Some(mut entry) = self.failures.get_mut(key) {
+            *entry.get_mut(protocol) = None;
+            if entry.is_empty() {
+                drop(entry);
+                self.failures.remove(key);
+            }
+        }
+    }
+
+    /// Evict a cache entry entirely. Called when all protocol probes (H3, H2, H1)
+    /// have failed for a backend.
+    pub fn evict(&self, key: &ProtocolCacheKey) {
+        self.cache.remove(key);
+        self.failures.remove(key);
+        info!(
+            host = %key.host, port = %key.port, domain = ?key.requested_host,
+            "Cache entry evicted — all protocols failed"
+        );
+    }
+
+    /// Clear all entries. Called on route updates to discard stale detections.
+    pub fn clear(&self) {
+        self.cache.clear();
+        self.failures.clear();
+    }
+
+    /// Snapshot all non-expired cache entries for metrics/UI display.
+    pub fn snapshot(&self) -> Vec<ProtocolCacheEntry> {
+        self.cache.iter()
+            .filter(|entry| entry.value().last_accessed_at.elapsed() < PROTOCOL_CACHE_TTL)
+            .map(|entry| {
+                let key = entry.key();
+                let val = entry.value();
+                let failure_info = self.failures.get(key);
+
+                let (h2_sup, h2_cd, h2_cons) = Self::suppression_info(
+                    failure_info.as_deref().and_then(|f| f.h2.as_ref()),
+                );
+                let (h3_sup, h3_cd, h3_cons) = Self::suppression_info(
+                    failure_info.as_deref().and_then(|f| f.h3.as_ref()),
+                );
+
+                ProtocolCacheEntry {
+                    host: key.host.clone(),
+                    port: key.port,
+                    domain: key.requested_host.clone(),
+                    protocol: match val.protocol {
+                        DetectedProtocol::H1 => "h1".to_string(),
+                        DetectedProtocol::H2 => "h2".to_string(),
+                        DetectedProtocol::H3 => "h3".to_string(),
+                    },
+                    h3_port: val.h3_port,
+                    age_secs: val.detected_at.elapsed().as_secs(),
+                    last_accessed_secs: val.last_accessed_at.elapsed().as_secs(),
+                    last_probed_secs: val.last_probed_at.elapsed().as_secs(),
+                    h2_suppressed: h2_sup,
+                    h3_suppressed: h3_sup,
+                    h2_cooldown_remaining_secs: h2_cd,
+                    h3_cooldown_remaining_secs: h3_cd,
+                    h2_consecutive_failures: h2_cons,
+                    h3_consecutive_failures: h3_cons,
+                }
+            })
+            .collect()
+    }
+
+    // --- Internal helpers ---
+
+    /// Insert a protocol detection result with an optional H3 port.
+    /// Logs protocol transitions when overwriting an existing entry.
+    /// No suppression check — callers must check before calling.
+    fn insert_internal(&self, key: ProtocolCacheKey, protocol: DetectedProtocol, h3_port: Option<u16>, reason: &str) {
+        // Check for existing entry to log protocol transitions
+        if let Some(existing) = self.cache.get(&key) {
+            if existing.protocol != protocol {
+                info!(
+                    host = %key.host, port = %key.port, domain = ?key.requested_host,
+                    old = %existing.protocol, new = %protocol, reason = %reason,
+                    "Protocol transition"
+                );
+            }
+            drop(existing);
+        }
+
+        // Evict oldest entry if at capacity
+        if self.cache.len() >= PROTOCOL_CACHE_MAX_ENTRIES && !self.cache.contains_key(&key) {
+            let oldest = self.cache.iter()
+                .min_by_key(|entry| entry.value().last_accessed_at)
+                .map(|entry| entry.key().clone());
+            if let Some(oldest_key) = oldest {
+                self.cache.remove(&oldest_key);
+            }
+        }
+
+        let now = Instant::now();
+        self.cache.insert(key, CachedEntry {
+            protocol,
+            detected_at: now,
+            last_accessed_at: now,
+            last_probed_at: now,
+            h3_port,
+        });
+    }
+
+    /// Reduce a failure record's remaining cooldown to `target`, if it currently
+    /// has MORE than `target` remaining. Never increases cooldown.
+    fn reduce_cooldown_to(record: Option<&mut FailureRecord>, target: Duration) {
+        if let Some(r) = record {
+            let elapsed = r.failed_at.elapsed();
+            if elapsed < r.cooldown {
+                let remaining = r.cooldown - elapsed;
+                if remaining > target {
+                    // Shrink cooldown so it expires in `target` from now
+                    r.cooldown = elapsed + target;
+                }
+            }
+        }
+    }
+
+    /// Extract suppression info from a failure record for metrics.
+    fn suppression_info(record: Option<&FailureRecord>) -> (bool, Option<u64>, Option<u32>) {
+        match record {
+            Some(r) => {
+                let elapsed = r.failed_at.elapsed();
+                let suppressed = elapsed < r.cooldown;
+                let remaining = if suppressed {
+                    Some((r.cooldown - elapsed).as_secs())
+                } else {
+                    None
+                };
+                (suppressed, remaining, Some(r.consecutive_failures))
+            }
+            None => (false, None, None),
+        }
+    }
+
+    /// Background cleanup loop.
+    async fn cleanup_loop(
+        cache: Arc<DashMap<ProtocolCacheKey, CachedEntry>>,
+        failures: Arc<DashMap<ProtocolCacheKey, FailureState>>,
+    ) {
+        let mut interval = tokio::time::interval(PROTOCOL_CACHE_CLEANUP_INTERVAL);
+        loop {
+            interval.tick().await;
+
+            // Clean expired cache entries (sliding TTL based on last_accessed_at)
+            let expired: Vec<ProtocolCacheKey> = cache.iter()
+                .filter(|entry| entry.value().last_accessed_at.elapsed() >= PROTOCOL_CACHE_TTL)
+                .map(|entry| entry.key().clone())
+                .collect();
+
+            if !expired.is_empty() {
+                debug!("Protocol cache cleanup: removing {} expired entries", expired.len());
+                for key in expired {
+                    cache.remove(&key);
+                }
+            }
+
+            // Clean fully-expired failure entries
+            let expired_failures: Vec<ProtocolCacheKey> = failures.iter()
+                .filter(|entry| entry.value().all_expired())
+                .map(|entry| entry.key().clone())
+                .collect();
+
+            if !expired_failures.is_empty() {
+                debug!("Protocol cache cleanup: removing {} expired failure entries", expired_failures.len());
+                for key in expired_failures {
+                    failures.remove(&key);
+                }
+            }
+
+            // Safety net: cap failures map at 2× max entries
+            if failures.len() > PROTOCOL_CACHE_MAX_ENTRIES * 2 {
+                let oldest: Vec<ProtocolCacheKey> = failures.iter()
+                    .filter(|e| e.value().all_expired())
+                    .map(|e| e.key().clone())
+                    .take(failures.len() - PROTOCOL_CACHE_MAX_ENTRIES)
+                    .collect();
+                for key in oldest {
+                    failures.remove(&key);
+                }
+            }
+        }
+    }
+}
+
+impl Drop for ProtocolCache {
+    fn drop(&mut self) {
+        if let Some(handle) = self.cleanup_handle.take() {
+            handle.abort();
+        }
+    }
+}

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

@@ -0,0 +1,262 @@
+//! Request filtering: security checks, auth, CORS preflight.
+
+use std::net::SocketAddr;
+use std::sync::Arc;
+
+use bytes::Bytes;
+use http_body_util::Full;
+use http_body_util::BodyExt;
+use hyper::{Request, Response, StatusCode};
+use http_body_util::combinators::BoxBody;
+
+use rustproxy_config::RouteSecurity;
+use rustproxy_security::{IpFilter, BasicAuthValidator, JwtValidator, RateLimiter};
+
+pub struct RequestFilter;
+
+impl RequestFilter {
+    /// Apply security filters. Returns Some(response) if the request should be blocked.
+    pub fn apply(
+        security: &RouteSecurity,
+        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)
+    }
+
+    /// Apply security filters with an optional shared rate limiter.
+    /// Returns Some(response) if the request should be blocked.
+    pub fn apply_with_rate_limiter(
+        security: &RouteSecurity,
+        req: &Request<impl hyper::body::Body>,
+        peer_addr: &SocketAddr,
+        rate_limiter: Option<&Arc<RateLimiter>>,
+    ) -> Option<Response<BoxBody<Bytes, hyper::Error>>> {
+        let client_ip = peer_addr.ip();
+        let request_path = req.uri().path();
+
+        // IP filter
+        if security.ip_allow_list.is_some() || security.ip_block_list.is_some() {
+            let allow = security.ip_allow_list.as_deref().unwrap_or(&[]);
+            let block = security.ip_block_list.as_deref().unwrap_or(&[]);
+            let filter = IpFilter::new(allow, block);
+            let normalized = IpFilter::normalize_ip(&client_ip);
+            if !filter.is_allowed(&normalized) {
+                return Some(error_response(StatusCode::FORBIDDEN, "Access denied"));
+            }
+        }
+
+        // Rate limiting
+        if let Some(ref rate_limit_config) = security.rate_limit {
+            if rate_limit_config.enabled {
+                // Use shared rate limiter if provided, otherwise create ephemeral one
+                let should_block = if let Some(limiter) = rate_limiter {
+                    let key = Self::rate_limit_key(rate_limit_config, req, peer_addr);
+                    !limiter.check(&key)
+                } else {
+                    // Create a per-check limiter (less ideal but works for non-shared case)
+                    let limiter = RateLimiter::new(
+                        rate_limit_config.max_requests,
+                        rate_limit_config.window,
+                    );
+                    let key = Self::rate_limit_key(rate_limit_config, req, peer_addr);
+                    !limiter.check(&key)
+                };
+
+                if should_block {
+                    let message = rate_limit_config.error_message
+                        .as_deref()
+                        .unwrap_or("Rate limit exceeded");
+                    return Some(error_response(StatusCode::TOO_MANY_REQUESTS, message));
+                }
+            }
+        }
+
+        // Check exclude paths before auth
+        let should_skip_auth = Self::path_matches_exclude_list(request_path, security);
+
+        if !should_skip_auth {
+            // Basic auth
+            if let Some(ref basic_auth) = security.basic_auth {
+                if basic_auth.enabled {
+                    // Check basic auth exclude paths
+                    let skip_basic = basic_auth.exclude_paths.as_ref()
+                        .map(|paths| Self::path_matches_any(request_path, paths))
+                        .unwrap_or(false);
+
+                    if !skip_basic {
+                        let users: Vec<(String, String)> = basic_auth.users.iter()
+                            .map(|c| (c.username.clone(), c.password.clone()))
+                            .collect();
+                        let validator = BasicAuthValidator::new(users, basic_auth.realm.clone());
+
+                        let auth_header = req.headers()
+                            .get("authorization")
+                            .and_then(|v| v.to_str().ok());
+
+                        match auth_header {
+                            Some(header) => {
+                                if validator.validate(header).is_none() {
+                                    return Some(Response::builder()
+                                        .status(StatusCode::UNAUTHORIZED)
+                                        .header("WWW-Authenticate", validator.www_authenticate())
+                                        .body(boxed_body("Invalid credentials"))
+                                        .unwrap());
+                                }
+                            }
+                            None => {
+                                return Some(Response::builder()
+                                    .status(StatusCode::UNAUTHORIZED)
+                                    .header("WWW-Authenticate", validator.www_authenticate())
+                                    .body(boxed_body("Authentication required"))
+                                    .unwrap());
+                            }
+                        }
+                    }
+                }
+            }
+
+            // JWT auth
+            if let Some(ref jwt_auth) = security.jwt_auth {
+                if jwt_auth.enabled {
+                    // Check JWT auth exclude paths
+                    let skip_jwt = jwt_auth.exclude_paths.as_ref()
+                        .map(|paths| Self::path_matches_any(request_path, paths))
+                        .unwrap_or(false);
+
+                    if !skip_jwt {
+                        let validator = JwtValidator::new(
+                            &jwt_auth.secret,
+                            jwt_auth.algorithm.as_deref(),
+                            jwt_auth.issuer.as_deref(),
+                            jwt_auth.audience.as_deref(),
+                        );
+
+                        let auth_header = req.headers()
+                            .get("authorization")
+                            .and_then(|v| v.to_str().ok());
+
+                        match auth_header.and_then(JwtValidator::extract_token) {
+                            Some(token) => {
+                                if validator.validate(token).is_err() {
+                                    return Some(error_response(StatusCode::UNAUTHORIZED, "Invalid token"));
+                                }
+                            }
+                            None => {
+                                return Some(error_response(StatusCode::UNAUTHORIZED, "Bearer token required"));
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        None
+    }
+
+    /// Check if a request path matches any pattern in the exclude list.
+    fn path_matches_exclude_list(_path: &str, _security: &RouteSecurity) -> bool {
+        // No global exclude paths on RouteSecurity currently,
+        // but we check per-auth exclude paths above.
+        // This can be extended if a global exclude_paths is added.
+        false
+    }
+
+    /// Check if a path matches any pattern in the list.
+    /// Supports simple glob patterns: `/health*` matches `/health`, `/healthz`, `/health/check`
+    fn path_matches_any(path: &str, patterns: &[String]) -> bool {
+        for pattern in patterns {
+            if pattern.ends_with('*') {
+                let prefix = &pattern[..pattern.len() - 1];
+                if path.starts_with(prefix) {
+                    return true;
+                }
+            } else if path == pattern {
+                return true;
+            }
+        }
+        false
+    }
+
+    /// Determine the rate limit key based on configuration.
+    fn rate_limit_key(
+        config: &rustproxy_config::RouteRateLimit,
+        req: &Request<impl hyper::body::Body>,
+        peer_addr: &SocketAddr,
+    ) -> String {
+        use rustproxy_config::RateLimitKeyBy;
+        match config.key_by.as_ref().unwrap_or(&RateLimitKeyBy::Ip) {
+            RateLimitKeyBy::Ip => peer_addr.ip().to_string(),
+            RateLimitKeyBy::Path => req.uri().path().to_string(),
+            RateLimitKeyBy::Header => {
+                if let Some(ref header_name) = config.header_name {
+                    req.headers()
+                        .get(header_name.as_str())
+                        .and_then(|v| v.to_str().ok())
+                        .unwrap_or("unknown")
+                        .to_string()
+                } else {
+                    peer_addr.ip().to_string()
+                }
+            }
+        }
+    }
+
+    /// Check IP-based security (for use in passthrough / TCP-level connections).
+    /// Returns true if allowed, false if blocked.
+    pub fn check_ip_security(security: &RouteSecurity, client_ip: &std::net::IpAddr) -> bool {
+        if security.ip_allow_list.is_some() || security.ip_block_list.is_some() {
+            let allow = security.ip_allow_list.as_deref().unwrap_or(&[]);
+            let block = security.ip_block_list.as_deref().unwrap_or(&[]);
+            let filter = IpFilter::new(allow, block);
+            let normalized = IpFilter::normalize_ip(client_ip);
+            filter.is_allowed(&normalized)
+        } else {
+            true
+        }
+    }
+
+    /// 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<impl hyper::body::Body>,
+    ) -> Option<Response<BoxBody<Bytes, hyper::Error>>> {
+        if req.method() != hyper::Method::OPTIONS {
+            return None;
+        }
+
+        // Check for CORS preflight indicators
+        let has_origin = req.headers().contains_key("origin");
+        let has_request_method = req.headers().contains_key("access-control-request-method");
+
+        if !has_origin || !has_request_method {
+            return None;
+        }
+
+        let origin = req.headers()
+            .get("origin")
+            .and_then(|v| v.to_str().ok())
+            .unwrap_or("*");
+
+        Some(Response::builder()
+            .status(StatusCode::NO_CONTENT)
+            .header("Access-Control-Allow-Origin", origin)
+            .header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS")
+            .header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Requested-With")
+            .header("Access-Control-Max-Age", "86400")
+            .body(boxed_body(""))
+            .unwrap())
+    }
+}
+
+fn error_response(status: StatusCode, message: &str) -> Response<BoxBody<Bytes, hyper::Error>> {
+    Response::builder()
+        .status(status)
+        .header("Content-Type", "text/plain")
+        .body(boxed_body(message))
+        .unwrap()
+}
+
+fn boxed_body(data: &str) -> BoxBody<Bytes, hyper::Error> {
+    BoxBody::new(Full::new(Bytes::from(data.to_string())).map_err(|never| match never {}))
+}

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

@@ -0,0 +1,108 @@
+//! Response filtering: CORS headers, custom headers, security headers.
+
+use hyper::header::{HeaderMap, HeaderName, HeaderValue};
+use rustproxy_config::RouteConfig;
+
+use crate::template::{RequestContext, expand_template};
+
+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 {
+                for (key, value) in response_headers {
+                    if let Ok(name) = HeaderName::from_bytes(key.as_bytes()) {
+                        let expanded = match req_ctx {
+                            Some(ctx) => expand_template(value, ctx),
+                            None => value.clone(),
+                        };
+                        if let Ok(val) = HeaderValue::from_str(&expanded) {
+                            headers.insert(name, val);
+                        }
+                    }
+                }
+            }
+
+            // Apply CORS headers if configured
+            if let Some(ref cors) = route_headers.cors {
+                if cors.enabled {
+                    Self::apply_cors_headers(cors, headers);
+                }
+            }
+        }
+    }
+
+    fn apply_cors_headers(cors: &rustproxy_config::RouteCors, headers: &mut HeaderMap) {
+        // Allow-Origin
+        if let Some(ref origin) = cors.allow_origin {
+            let origin_str = match origin {
+                rustproxy_config::AllowOrigin::Single(s) => s.clone(),
+                rustproxy_config::AllowOrigin::List(list) => list.join(", "),
+            };
+            if let Ok(val) = HeaderValue::from_str(&origin_str) {
+                headers.insert("access-control-allow-origin", val);
+            }
+        } else {
+            headers.insert(
+                "access-control-allow-origin",
+                HeaderValue::from_static("*"),
+            );
+        }
+
+        // Allow-Methods
+        if let Some(ref methods) = cors.allow_methods {
+            if let Ok(val) = HeaderValue::from_str(methods) {
+                headers.insert("access-control-allow-methods", val);
+            }
+        }
+
+        // Allow-Headers
+        if let Some(ref allow_headers) = cors.allow_headers {
+            if let Ok(val) = HeaderValue::from_str(allow_headers) {
+                headers.insert("access-control-allow-headers", val);
+            }
+        }
+
+        // Allow-Credentials
+        if cors.allow_credentials == Some(true) {
+            headers.insert(
+                "access-control-allow-credentials",
+                HeaderValue::from_static("true"),
+            );
+        }
+
+        // Expose-Headers
+        if let Some(ref expose) = cors.expose_headers {
+            if let Ok(val) = HeaderValue::from_str(expose) {
+                headers.insert("access-control-expose-headers", val);
+            }
+        }
+
+        // Max-Age
+        if let Some(max_age) = cors.max_age {
+            if let Ok(val) = HeaderValue::from_str(&max_age.to_string()) {
+                headers.insert("access-control-max-age", val);
+            }
+        }
+    }
+}

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/template.rs

@@ -0,0 +1,162 @@
+//! Header template variable expansion.
+//!
+//! Supports expanding template variables like `{clientIp}`, `{domain}`, etc.
+//! in header values before they are applied to requests or responses.
+
+use std::collections::HashMap;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Context for template variable expansion.
+pub struct RequestContext {
+    pub client_ip: String,
+    pub domain: String,
+    pub port: u16,
+    pub path: String,
+    pub route_name: String,
+    pub connection_id: u64,
+}
+
+/// Expand template variables in a header value.
+/// Supported variables: {clientIp}, {domain}, {port}, {path}, {routeName}, {connectionId}, {timestamp}
+pub fn expand_template(template: &str, ctx: &RequestContext) -> String {
+    let timestamp = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+
+    template
+        .replace("{clientIp}", &ctx.client_ip)
+        .replace("{domain}", &ctx.domain)
+        .replace("{port}", &ctx.port.to_string())
+        .replace("{path}", &ctx.path)
+        .replace("{routeName}", &ctx.route_name)
+        .replace("{connectionId}", &ctx.connection_id.to_string())
+        .replace("{timestamp}", &timestamp.to_string())
+}
+
+/// Expand templates in a map of header key-value pairs.
+pub fn expand_headers(
+    headers: &HashMap<String, String>,
+    ctx: &RequestContext,
+) -> HashMap<String, String> {
+    headers.iter()
+        .map(|(k, v)| (k.clone(), expand_template(v, ctx)))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_context() -> RequestContext {
+        RequestContext {
+            client_ip: "192.168.1.100".to_string(),
+            domain: "example.com".to_string(),
+            port: 443,
+            path: "/api/v1/users".to_string(),
+            route_name: "api-route".to_string(),
+            connection_id: 42,
+        }
+    }
+
+    #[test]
+    fn test_expand_client_ip() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{clientIp}", &ctx), "192.168.1.100");
+    }
+
+    #[test]
+    fn test_expand_domain() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{domain}", &ctx), "example.com");
+    }
+
+    #[test]
+    fn test_expand_port() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{port}", &ctx), "443");
+    }
+
+    #[test]
+    fn test_expand_path() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{path}", &ctx), "/api/v1/users");
+    }
+
+    #[test]
+    fn test_expand_route_name() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{routeName}", &ctx), "api-route");
+    }
+
+    #[test]
+    fn test_expand_connection_id() {
+        let ctx = test_context();
+        assert_eq!(expand_template("{connectionId}", &ctx), "42");
+    }
+
+    #[test]
+    fn test_expand_timestamp() {
+        let ctx = test_context();
+        let result = expand_template("{timestamp}", &ctx);
+        // Timestamp should be a valid number
+        let ts: u64 = result.parse().expect("timestamp should be a number");
+        // Should be a reasonable Unix timestamp (after 2020)
+        assert!(ts > 1_577_836_800);
+    }
+
+    #[test]
+    fn test_expand_mixed_template() {
+        let ctx = test_context();
+        let result = expand_template("client={clientIp}, host={domain}:{port}", &ctx);
+        assert_eq!(result, "client=192.168.1.100, host=example.com:443");
+    }
+
+    #[test]
+    fn test_expand_no_variables() {
+        let ctx = test_context();
+        assert_eq!(expand_template("plain-value", &ctx), "plain-value");
+    }
+
+    #[test]
+    fn test_expand_empty_string() {
+        let ctx = test_context();
+        assert_eq!(expand_template("", &ctx), "");
+    }
+
+    #[test]
+    fn test_expand_multiple_same_variable() {
+        let ctx = test_context();
+        let result = expand_template("{clientIp}-{clientIp}", &ctx);
+        assert_eq!(result, "192.168.1.100-192.168.1.100");
+    }
+
+    #[test]
+    fn test_expand_headers_map() {
+        let ctx = test_context();
+        let mut headers = HashMap::new();
+        headers.insert("X-Forwarded-For".to_string(), "{clientIp}".to_string());
+        headers.insert("X-Route".to_string(), "{routeName}".to_string());
+        headers.insert("X-Static".to_string(), "no-template".to_string());
+
+        let result = expand_headers(&headers, &ctx);
+        assert_eq!(result.get("X-Forwarded-For").unwrap(), "192.168.1.100");
+        assert_eq!(result.get("X-Route").unwrap(), "api-route");
+        assert_eq!(result.get("X-Static").unwrap(), "no-template");
+    }
+
+    #[test]
+    fn test_expand_all_variables_in_one() {
+        let ctx = test_context();
+        let template = "{clientIp}|{domain}|{port}|{path}|{routeName}|{connectionId}";
+        let result = expand_template(template, &ctx);
+        assert_eq!(result, "192.168.1.100|example.com|443|/api/v1/users|api-route|42");
+    }
+
+    #[test]
+    fn test_expand_unknown_variable_left_as_is() {
+        let ctx = test_context();
+        let result = expand_template("{unknownVar}", &ctx);
+        assert_eq!(result, "{unknownVar}");
+    }
+}

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

@@ -0,0 +1,264 @@
+//! Route-aware upstream selection with load balancing.
+
+use std::collections::HashMap;
+use std::net::SocketAddr;
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::sync::Mutex;
+
+use dashmap::DashMap;
+use rustproxy_config::{RouteTarget, LoadBalancingAlgorithm};
+
+/// Upstream selection result.
+pub struct UpstreamSelection {
+    pub host: String,
+    pub port: u16,
+    pub use_tls: bool,
+}
+
+/// Selects upstream backends with load balancing support.
+pub struct UpstreamSelector {
+    /// Round-robin counters per route (keyed by first target host:port)
+    round_robin: Mutex<HashMap<String, AtomicUsize>>,
+    /// Active connection counts per host (keyed by "host:port")
+    active_connections: Arc<DashMap<String, AtomicU64>>,
+}
+
+impl UpstreamSelector {
+    pub fn new() -> Self {
+        Self {
+            round_robin: Mutex::new(HashMap::new()),
+            active_connections: Arc::new(DashMap::new()),
+        }
+    }
+
+    /// Select an upstream target based on the route target config and load balancing.
+    pub fn select(
+        &self,
+        target: &RouteTarget,
+        client_addr: &SocketAddr,
+        incoming_port: u16,
+    ) -> UpstreamSelection {
+        let hosts = target.host.to_vec();
+        let port = target.port.resolve(incoming_port);
+
+        if hosts.len() <= 1 {
+            return UpstreamSelection {
+                host: hosts.first().map(|s| s.to_string()).unwrap_or_default(),
+                port,
+                use_tls: target.tls.is_some(),
+            };
+        }
+
+        // Determine load balancing algorithm
+        let algorithm = target.load_balancing.as_ref()
+            .map(|lb| &lb.algorithm)
+            .unwrap_or(&LoadBalancingAlgorithm::RoundRobin);
+
+        let idx = match algorithm {
+            LoadBalancingAlgorithm::RoundRobin => {
+                self.round_robin_select(&hosts, port)
+            }
+            LoadBalancingAlgorithm::IpHash => {
+                let hash = Self::ip_hash(client_addr);
+                hash % hosts.len()
+            }
+            LoadBalancingAlgorithm::LeastConnections => {
+                self.least_connections_select(&hosts, port)
+            }
+        };
+
+        UpstreamSelection {
+            host: hosts[idx].to_string(),
+            port,
+            use_tls: target.tls.is_some(),
+        }
+    }
+
+    fn round_robin_select(&self, hosts: &[&str], port: u16) -> usize {
+        let key = format!("{}:{}", hosts[0], port);
+        let mut counters = self.round_robin.lock().unwrap();
+        let counter = counters
+            .entry(key)
+            .or_insert_with(|| AtomicUsize::new(0));
+        let idx = counter.fetch_add(1, Ordering::Relaxed);
+        idx % hosts.len()
+    }
+
+    fn least_connections_select(&self, hosts: &[&str], port: u16) -> usize {
+        let mut min_conns = u64::MAX;
+        let mut min_idx = 0;
+
+        for (i, host) in hosts.iter().enumerate() {
+            let key = format!("{}:{}", host, port);
+            let conns = self.active_connections
+                .get(&key)
+                .map(|entry| entry.value().load(Ordering::Relaxed))
+                .unwrap_or(0);
+            if conns < min_conns {
+                min_conns = conns;
+                min_idx = i;
+            }
+        }
+
+        min_idx
+    }
+
+    /// Record that a connection to the given host has started.
+    pub fn connection_started(&self, host: &str) {
+        self.active_connections
+            .entry(host.to_string())
+            .or_insert_with(|| AtomicU64::new(0))
+            .fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Record that a connection to the given host has ended.
+    pub fn connection_ended(&self, host: &str) {
+        if let Some(counter) = self.active_connections.get(host) {
+            let prev = counter.value().load(Ordering::Relaxed);
+            if prev == 0 {
+                // Already at zero — just clean up the entry
+                drop(counter);
+                self.active_connections.remove(host);
+                return;
+            }
+            counter.value().fetch_sub(1, Ordering::Relaxed);
+            // Clean up zero-count entries to prevent memory growth
+            if prev <= 1 {
+                drop(counter);
+                self.active_connections.remove(host);
+            }
+        }
+    }
+
+    /// Clear stale round-robin counters on route update.
+    /// Resetting is harmless — counters just restart cycling from index 0.
+    pub fn reset_round_robin(&self) {
+        if let Ok(mut counters) = self.round_robin.lock() {
+            counters.clear();
+        }
+    }
+
+    fn ip_hash(addr: &SocketAddr) -> usize {
+        let ip_str = addr.ip().to_string();
+        let mut hash: usize = 5381;
+        for byte in ip_str.bytes() {
+            hash = hash.wrapping_mul(33).wrapping_add(byte as usize);
+        }
+        hash
+    }
+}
+
+impl Default for UpstreamSelector {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Clone for UpstreamSelector {
+    fn clone(&self) -> Self {
+        Self {
+            round_robin: Mutex::new(HashMap::new()),
+            active_connections: Arc::clone(&self.active_connections),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rustproxy_config::*;
+
+    fn make_target(hosts: Vec<&str>, port: u16) -> RouteTarget {
+        RouteTarget {
+            target_match: None,
+            host: if hosts.len() == 1 {
+                HostSpec::Single(hosts[0].to_string())
+            } else {
+                HostSpec::List(hosts.iter().map(|s| s.to_string()).collect())
+            },
+            port: PortSpec::Fixed(port),
+            tls: None,
+            websocket: None,
+            load_balancing: None,
+            send_proxy_protocol: None,
+            headers: None,
+            advanced: None,
+            backend_transport: None,
+            priority: None,
+        }
+    }
+
+    #[test]
+    fn test_single_host() {
+        let selector = UpstreamSelector::new();
+        let target = make_target(vec!["backend"], 8080);
+        let addr: SocketAddr = "127.0.0.1:1234".parse().unwrap();
+        let result = selector.select(&target, &addr, 80);
+        assert_eq!(result.host, "backend");
+        assert_eq!(result.port, 8080);
+    }
+
+    #[test]
+    fn test_round_robin() {
+        let selector = UpstreamSelector::new();
+        let mut target = make_target(vec!["a", "b", "c"], 8080);
+        target.load_balancing = Some(RouteLoadBalancing {
+            algorithm: LoadBalancingAlgorithm::RoundRobin,
+            health_check: None,
+        });
+        let addr: SocketAddr = "127.0.0.1:1234".parse().unwrap();
+
+        let r1 = selector.select(&target, &addr, 80);
+        let r2 = selector.select(&target, &addr, 80);
+        let r3 = selector.select(&target, &addr, 80);
+        let r4 = selector.select(&target, &addr, 80);
+
+        // Should cycle through a, b, c, a
+        assert_eq!(r1.host, "a");
+        assert_eq!(r2.host, "b");
+        assert_eq!(r3.host, "c");
+        assert_eq!(r4.host, "a");
+    }
+
+    #[test]
+    fn test_connection_tracking_cleanup() {
+        let selector = UpstreamSelector::new();
+
+        selector.connection_started("backend:8080");
+        selector.connection_started("backend:8080");
+        assert_eq!(
+            selector.active_connections.get("backend:8080").unwrap().load(Ordering::Relaxed),
+            2
+        );
+
+        selector.connection_ended("backend:8080");
+        assert_eq!(
+            selector.active_connections.get("backend:8080").unwrap().load(Ordering::Relaxed),
+            1
+        );
+
+        // Last connection ends — entry should be removed entirely
+        selector.connection_ended("backend:8080");
+        assert!(selector.active_connections.get("backend:8080").is_none());
+
+        // Ending on a non-existent key should not panic
+        selector.connection_ended("nonexistent:9999");
+    }
+
+    #[test]
+    fn test_ip_hash_consistent() {
+        let selector = UpstreamSelector::new();
+        let mut target = make_target(vec!["a", "b", "c"], 8080);
+        target.load_balancing = Some(RouteLoadBalancing {
+            algorithm: LoadBalancingAlgorithm::IpHash,
+            health_check: None,
+        });
+        let addr: SocketAddr = "10.0.0.5:1234".parse().unwrap();
+
+        let r1 = selector.select(&target, &addr, 80);
+        let r2 = selector.select(&target, &addr, 80);
+        // Same IP should always get same backend
+        assert_eq!(r1.host, r2.host);
+    }
+}

rust/crates/rustproxy-metrics/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "rustproxy-metrics"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Metrics and throughput tracking for RustProxy"
+
+[dependencies]
+dashmap = { workspace = true }
+tracing = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+tokio = { workspace = true }
+tokio-util = { workspace = true }

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

@@ -0,0 +1,11 @@
+//! # rustproxy-metrics
+//!
+//! Metrics and throughput tracking for RustProxy.
+
+pub mod throughput;
+pub mod collector;
+pub mod log_dedup;
+
+pub use throughput::*;
+pub use collector::*;
+pub use log_dedup::*;

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

@@ -0,0 +1,219 @@
+use dashmap::DashMap;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+use tracing::info;
+
+/// An aggregated event during the deduplication window.
+struct AggregatedEvent {
+    category: String,
+    first_message: String,
+    count: AtomicU64,
+    first_seen: Instant,
+    #[allow(dead_code)]
+    last_seen: Instant,
+}
+
+/// Log deduplicator that batches similar events over a time window.
+///
+/// Events are grouped by a composite key of `category:key`. Within each
+/// deduplication window (`flush_interval`) identical events are counted
+/// instead of being emitted individually.  When the window expires (or the
+/// batch reaches `max_batch_size`) a single summary line is written via
+/// `tracing::info!`.
+pub struct LogDeduplicator {
+    events: DashMap<String, AggregatedEvent>,
+    flush_interval: Duration,
+    max_batch_size: u64,
+    #[allow(dead_code)]
+    rapid_threshold: u64, // events/sec that triggers immediate flush
+}
+
+impl LogDeduplicator {
+    pub fn new() -> Self {
+        Self {
+            events: DashMap::new(),
+            flush_interval: Duration::from_secs(5),
+            max_batch_size: 100,
+            rapid_threshold: 50,
+        }
+    }
+
+    /// Log an event, deduplicating by `category` + `key`.
+    ///
+    /// If the batch for this composite key reaches `max_batch_size` the
+    /// accumulated events are flushed immediately.
+    pub fn log(&self, category: &str, key: &str, message: &str) {
+        let map_key = format!("{}:{}", category, key);
+        let now = Instant::now();
+
+        let entry = self.events.entry(map_key).or_insert_with(|| AggregatedEvent {
+            category: category.to_string(),
+            first_message: message.to_string(),
+            count: AtomicU64::new(0),
+            first_seen: now,
+            last_seen: now,
+        });
+
+        let count = entry.count.fetch_add(1, Ordering::Relaxed) + 1;
+
+        // Check if we should flush (batch size exceeded)
+        if count >= self.max_batch_size {
+            drop(entry);
+            self.flush();
+        }
+    }
+
+    /// Flush all accumulated events, emitting summary log lines.
+    pub fn flush(&self) {
+        // Collect and remove all events
+        self.events.retain(|_key, event| {
+            let count = event.count.load(Ordering::Relaxed);
+            if count > 0 {
+                let elapsed = event.first_seen.elapsed();
+                if count == 1 {
+                    info!("[{}] {}", event.category, event.first_message);
+                } else {
+                    info!(
+                        "[SUMMARY] {} {} events in {:.1}s: {}",
+                        count,
+                        event.category,
+                        elapsed.as_secs_f64(),
+                        event.first_message
+                    );
+                }
+            }
+            false // remove all entries after flushing
+        });
+    }
+
+    /// Start a background flush task that periodically drains accumulated
+    /// events.  The task runs until the supplied `CancellationToken` is
+    /// cancelled, at which point it performs one final flush before exiting.
+    pub fn start_flush_task(self: &Arc<Self>, cancel: tokio_util::sync::CancellationToken) {
+        let dedup = Arc::clone(self);
+        let interval = self.flush_interval;
+        tokio::spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = cancel.cancelled() => {
+                        dedup.flush();
+                        break;
+                    }
+                    _ = tokio::time::sleep(interval) => {
+                        dedup.flush();
+                    }
+                }
+            }
+        });
+    }
+}
+
+impl Default for LogDeduplicator {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_single_event_emitted_as_is() {
+        let dedup = LogDeduplicator::new();
+        dedup.log("conn", "open", "connection opened from 1.2.3.4");
+        // One event should exist
+        assert_eq!(dedup.events.len(), 1);
+        let entry = dedup.events.get("conn:open").unwrap();
+        assert_eq!(entry.count.load(Ordering::Relaxed), 1);
+        assert_eq!(entry.first_message, "connection opened from 1.2.3.4");
+        drop(entry);
+        dedup.flush();
+        // After flush, map should be empty
+        assert_eq!(dedup.events.len(), 0);
+    }
+
+    #[test]
+    fn test_duplicate_events_aggregated() {
+        let dedup = LogDeduplicator::new();
+        for _ in 0..10 {
+            dedup.log("conn", "timeout", "connection timed out");
+        }
+        assert_eq!(dedup.events.len(), 1);
+        let entry = dedup.events.get("conn:timeout").unwrap();
+        assert_eq!(entry.count.load(Ordering::Relaxed), 10);
+        drop(entry);
+        dedup.flush();
+        assert_eq!(dedup.events.len(), 0);
+    }
+
+    #[test]
+    fn test_different_keys_separate() {
+        let dedup = LogDeduplicator::new();
+        dedup.log("conn", "open", "opened");
+        dedup.log("conn", "close", "closed");
+        dedup.log("tls", "handshake", "TLS handshake");
+        assert_eq!(dedup.events.len(), 3);
+        dedup.flush();
+        assert_eq!(dedup.events.len(), 0);
+    }
+
+    #[test]
+    fn test_flush_clears_events() {
+        let dedup = LogDeduplicator::new();
+        dedup.log("a", "b", "msg1");
+        dedup.log("a", "b", "msg2");
+        dedup.flush();
+        assert_eq!(dedup.events.len(), 0);
+        // Logging after flush creates a new entry
+        dedup.log("a", "b", "msg3");
+        assert_eq!(dedup.events.len(), 1);
+        let entry = dedup.events.get("a:b").unwrap();
+        assert_eq!(entry.count.load(Ordering::Relaxed), 1);
+        assert_eq!(entry.first_message, "msg3");
+    }
+
+    #[test]
+    fn test_max_batch_triggers_flush() {
+        let dedup = LogDeduplicator::new();
+        // max_batch_size defaults to 100
+        for i in 0..100 {
+            dedup.log("flood", "key", &format!("event {}", i));
+        }
+        // After hitting max_batch_size the events map should have been flushed
+        assert_eq!(dedup.events.len(), 0);
+    }
+
+    #[test]
+    fn test_default_trait() {
+        let dedup = LogDeduplicator::default();
+        assert_eq!(dedup.flush_interval, Duration::from_secs(5));
+        assert_eq!(dedup.max_batch_size, 100);
+    }
+
+    #[tokio::test]
+    async fn test_background_flush_task() {
+        let dedup = Arc::new(LogDeduplicator {
+            events: DashMap::new(),
+            flush_interval: Duration::from_millis(50),
+            max_batch_size: 100,
+            rapid_threshold: 50,
+        });
+
+        let cancel = tokio_util::sync::CancellationToken::new();
+        dedup.start_flush_task(cancel.clone());
+
+        // Log some events
+        dedup.log("bg", "test", "background flush test");
+        assert_eq!(dedup.events.len(), 1);
+
+        // Wait for the background task to flush
+        tokio::time::sleep(Duration::from_millis(100)).await;
+        assert_eq!(dedup.events.len(), 0);
+
+        // Cancel the task
+        cancel.cancel();
+        tokio::time::sleep(Duration::from_millis(20)).await;
+    }
+}

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

@@ -0,0 +1,232 @@
+use serde::{Deserialize, Serialize};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+/// A single throughput sample.
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ThroughputSample {
+    pub timestamp_ms: u64,
+    pub bytes_in: u64,
+    pub bytes_out: u64,
+}
+
+/// Circular buffer for 1Hz throughput sampling.
+/// Matches smartproxy's ThroughputTracker.
+pub struct ThroughputTracker {
+    /// Circular buffer of samples
+    samples: Vec<ThroughputSample>,
+    /// Current write index
+    write_index: usize,
+    /// Number of valid samples
+    count: usize,
+    /// Maximum number of samples to retain
+    capacity: usize,
+    /// Accumulated bytes since last sample
+    pending_bytes_in: AtomicU64,
+    pending_bytes_out: AtomicU64,
+    /// When the tracker was created
+    created_at: Instant,
+}
+
+impl ThroughputTracker {
+    /// Create a new tracker with the given capacity (seconds of retention).
+    pub fn new(retention_seconds: usize) -> Self {
+        Self {
+            samples: Vec::with_capacity(retention_seconds),
+            write_index: 0,
+            count: 0,
+            capacity: retention_seconds,
+            pending_bytes_in: AtomicU64::new(0),
+            pending_bytes_out: AtomicU64::new(0),
+            created_at: Instant::now(),
+        }
+    }
+
+    /// Record bytes (called from data flow callbacks).
+    pub fn record_bytes(&self, bytes_in: u64, bytes_out: u64) {
+        self.pending_bytes_in.fetch_add(bytes_in, Ordering::Relaxed);
+        self.pending_bytes_out.fetch_add(bytes_out, Ordering::Relaxed);
+    }
+
+    /// Take a sample (called at 1Hz).
+    pub fn sample(&mut self) {
+        let bytes_in = self.pending_bytes_in.swap(0, Ordering::Relaxed);
+        let bytes_out = self.pending_bytes_out.swap(0, Ordering::Relaxed);
+        let timestamp_ms = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis() as u64;
+
+        let sample = ThroughputSample {
+            timestamp_ms,
+            bytes_in,
+            bytes_out,
+        };
+
+        if self.samples.len() < self.capacity {
+            self.samples.push(sample);
+        } else {
+            self.samples[self.write_index] = sample;
+        }
+        self.write_index = (self.write_index + 1) % self.capacity;
+        self.count = (self.count + 1).min(self.capacity);
+    }
+
+    /// Get throughput over the last N seconds.
+    pub fn throughput(&self, window_seconds: usize) -> (u64, u64) {
+        let window = window_seconds.min(self.count);
+        if window == 0 {
+            return (0, 0);
+        }
+
+        let mut total_in = 0u64;
+        let mut total_out = 0u64;
+
+        for i in 0..window {
+            let idx = if self.write_index >= i + 1 {
+                self.write_index - i - 1
+            } else {
+                self.capacity - (i + 1 - self.write_index)
+            };
+            if idx < self.samples.len() {
+                total_in += self.samples[idx].bytes_in;
+                total_out += self.samples[idx].bytes_out;
+            }
+        }
+
+        (total_in / window as u64, total_out / window as u64)
+    }
+
+    /// Get instant throughput (last 1 second).
+    pub fn instant(&self) -> (u64, u64) {
+        self.throughput(1)
+    }
+
+    /// Get recent throughput (last 10 seconds).
+    pub fn recent(&self) -> (u64, u64) {
+        self.throughput(10)
+    }
+
+    /// Return the last N samples in chronological order (oldest first).
+    pub fn history(&self, window_seconds: usize) -> Vec<ThroughputSample> {
+        let window = window_seconds.min(self.count);
+        if window == 0 {
+            return Vec::new();
+        }
+        let mut result = Vec::with_capacity(window);
+        for i in 0..window {
+            let idx = if self.write_index >= i + 1 {
+                self.write_index - i - 1
+            } else {
+                self.capacity - (i + 1 - self.write_index)
+            };
+            if idx < self.samples.len() {
+                result.push(self.samples[idx]);
+            }
+        }
+        result.reverse(); // Return oldest-first (chronological)
+        result
+    }
+
+    /// How long this tracker has been alive.
+    pub fn uptime(&self) -> std::time::Duration {
+        self.created_at.elapsed()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_empty_throughput() {
+        let tracker = ThroughputTracker::new(60);
+        let (bytes_in, bytes_out) = tracker.throughput(10);
+        assert_eq!(bytes_in, 0);
+        assert_eq!(bytes_out, 0);
+    }
+
+    #[test]
+    fn test_single_sample() {
+        let mut tracker = ThroughputTracker::new(60);
+        tracker.record_bytes(1000, 2000);
+        tracker.sample();
+        let (bytes_in, bytes_out) = tracker.instant();
+        assert_eq!(bytes_in, 1000);
+        assert_eq!(bytes_out, 2000);
+    }
+
+    #[test]
+    fn test_circular_buffer_wrap() {
+        let mut tracker = ThroughputTracker::new(3); // Small capacity
+        for i in 0..5 {
+            tracker.record_bytes(i * 100, i * 200);
+            tracker.sample();
+        }
+        // Should still work after wrapping
+        let (bytes_in, bytes_out) = tracker.throughput(3);
+        assert!(bytes_in > 0);
+        assert!(bytes_out > 0);
+    }
+
+    #[test]
+    fn test_window_averaging() {
+        let mut tracker = ThroughputTracker::new(60);
+        // Record 3 samples of different sizes
+        tracker.record_bytes(100, 200);
+        tracker.sample();
+        tracker.record_bytes(200, 400);
+        tracker.sample();
+        tracker.record_bytes(300, 600);
+        tracker.sample();
+
+        // Average over 3 samples: (100+200+300)/3 = 200, (200+400+600)/3 = 400
+        let (avg_in, avg_out) = tracker.throughput(3);
+        assert_eq!(avg_in, 200);
+        assert_eq!(avg_out, 400);
+    }
+
+    #[test]
+    fn test_uptime_positive() {
+        let tracker = ThroughputTracker::new(60);
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        assert!(tracker.uptime().as_millis() >= 10);
+    }
+
+    #[test]
+    fn test_history_returns_chronological() {
+        let mut tracker = ThroughputTracker::new(60);
+        for i in 1..=5 {
+            tracker.record_bytes(i * 100, i * 200);
+            tracker.sample();
+        }
+        let history = tracker.history(5);
+        assert_eq!(history.len(), 5);
+        // First sample should have 100 bytes_in, last should have 500
+        assert_eq!(history[0].bytes_in, 100);
+        assert_eq!(history[4].bytes_in, 500);
+    }
+
+    #[test]
+    fn test_history_wraps_around() {
+        let mut tracker = ThroughputTracker::new(3); // Small capacity
+        for i in 1..=5 {
+            tracker.record_bytes(i * 100, i * 200);
+            tracker.sample();
+        }
+        // Only last 3 should be retained
+        let history = tracker.history(10); // Ask for more than available
+        assert_eq!(history.len(), 3);
+        assert_eq!(history[0].bytes_in, 300);
+        assert_eq!(history[1].bytes_in, 400);
+        assert_eq!(history[2].bytes_in, 500);
+    }
+
+    #[test]
+    fn test_history_empty() {
+        let tracker = ThroughputTracker::new(60);
+        let history = tracker.history(10);
+        assert!(history.is_empty());
+    }
+}

rust/crates/rustproxy-passthrough/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "rustproxy-passthrough"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Raw TCP/SNI passthrough engine for RustProxy"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+rustproxy-routing = { workspace = true }
+rustproxy-metrics = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+thiserror = { workspace = true }
+anyhow = { workspace = true }
+dashmap = { workspace = true }
+arc-swap = { workspace = true }
+rustproxy-http = { workspace = true }
+rustls = { workspace = true }
+tokio-rustls = { workspace = true }
+rustls-pemfile = { workspace = true }
+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/connection_tracker.rs

@@ -0,0 +1,247 @@
+use dashmap::DashMap;
+use std::collections::VecDeque;
+use std::net::IpAddr;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+/// Tracks active connections per IP and enforces per-IP limits and rate limiting.
+pub struct ConnectionTracker {
+    /// Active connection counts per IP
+    active: DashMap<IpAddr, AtomicU64>,
+    /// Connection timestamps per IP for rate limiting
+    timestamps: DashMap<IpAddr, VecDeque<Instant>>,
+    /// Maximum concurrent connections per IP (None = unlimited)
+    max_per_ip: Option<u64>,
+    /// Maximum new connections per minute per IP (None = unlimited)
+    rate_limit_per_minute: Option<u64>,
+}
+
+impl ConnectionTracker {
+    pub fn new(max_per_ip: Option<u64>, rate_limit_per_minute: Option<u64>) -> Self {
+        Self {
+            active: DashMap::new(),
+            timestamps: DashMap::new(),
+            max_per_ip,
+            rate_limit_per_minute,
+        }
+    }
+
+    /// Try to accept a new connection from the given IP.
+    /// Returns true if allowed, false if over limit.
+    pub fn try_accept(&self, ip: &IpAddr) -> bool {
+        // Check per-IP connection limit
+        if let Some(max) = self.max_per_ip {
+            let count = self.active
+                .get(ip)
+                .map(|c| c.value().load(Ordering::Relaxed))
+                .unwrap_or(0);
+            if count >= max {
+                return false;
+            }
+        }
+
+        // Check rate limit
+        if let Some(rate_limit) = self.rate_limit_per_minute {
+            let now = Instant::now();
+            let one_minute = std::time::Duration::from_secs(60);
+            let mut entry = self.timestamps.entry(*ip).or_default();
+            let timestamps = entry.value_mut();
+
+            // Remove timestamps older than 1 minute
+            while timestamps.front().is_some_and(|t| now.duration_since(*t) >= one_minute) {
+                timestamps.pop_front();
+            }
+
+            if timestamps.len() as u64 >= rate_limit {
+                return false;
+            }
+            timestamps.push_back(now);
+        }
+
+        true
+    }
+
+    /// Record that a connection was opened from the given IP.
+    pub fn connection_opened(&self, ip: &IpAddr) {
+        self.active
+            .entry(*ip)
+            .or_insert_with(|| AtomicU64::new(0))
+            .value()
+            .fetch_add(1, Ordering::Relaxed);
+    }
+
+    /// Record that a connection was closed from the given IP.
+    pub fn connection_closed(&self, ip: &IpAddr) {
+        if let Some(counter) = self.active.get(ip) {
+            let prev = counter.value().fetch_sub(1, Ordering::Relaxed);
+            // Clean up zero entries to prevent memory growth
+            if prev <= 1 {
+                drop(counter);
+                self.active.remove(ip);
+                self.timestamps.remove(ip);
+            }
+        }
+    }
+
+    /// Get the current number of active connections for an IP.
+    pub fn active_connections(&self, ip: &IpAddr) -> u64 {
+        self.active
+            .get(ip)
+            .map(|c| c.value().load(Ordering::Relaxed))
+            .unwrap_or(0)
+    }
+
+    /// Prune stale timestamp entries for IPs that have no active connections
+    /// and no recent timestamps. This cleans up entries left by rate-limited IPs
+    /// that never had connection_opened called.
+    pub fn cleanup_stale_timestamps(&self) {
+        if self.rate_limit_per_minute.is_none() {
+            return; // No rate limiting — timestamps map should be empty
+        }
+        let now = Instant::now();
+        let one_minute = Duration::from_secs(60);
+        self.timestamps.retain(|ip, timestamps| {
+            timestamps.retain(|t| now.duration_since(*t) < one_minute);
+            // Keep if there are active connections or recent timestamps
+            !timestamps.is_empty() || self.active.contains_key(ip)
+        });
+    }
+
+    /// Get the total number of tracked IPs.
+    pub fn tracked_ips(&self) -> usize {
+        self.active.len()
+    }
+
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_basic_tracking() {
+        let tracker = ConnectionTracker::new(None, None);
+        let ip: IpAddr = "127.0.0.1".parse().unwrap();
+
+        assert!(tracker.try_accept(&ip));
+        tracker.connection_opened(&ip);
+        assert_eq!(tracker.active_connections(&ip), 1);
+
+        tracker.connection_opened(&ip);
+        assert_eq!(tracker.active_connections(&ip), 2);
+
+        tracker.connection_closed(&ip);
+        assert_eq!(tracker.active_connections(&ip), 1);
+
+        tracker.connection_closed(&ip);
+        assert_eq!(tracker.active_connections(&ip), 0);
+    }
+
+    #[test]
+    fn test_per_ip_limit() {
+        let tracker = ConnectionTracker::new(Some(2), None);
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+
+        assert!(tracker.try_accept(&ip));
+        tracker.connection_opened(&ip);
+
+        assert!(tracker.try_accept(&ip));
+        tracker.connection_opened(&ip);
+
+        // Third connection should be rejected
+        assert!(!tracker.try_accept(&ip));
+
+        // Different IP should still be allowed
+        let ip2: IpAddr = "10.0.0.2".parse().unwrap();
+        assert!(tracker.try_accept(&ip2));
+    }
+
+    #[test]
+    fn test_rate_limit() {
+        let tracker = ConnectionTracker::new(None, Some(3));
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+
+        assert!(tracker.try_accept(&ip));
+        assert!(tracker.try_accept(&ip));
+        assert!(tracker.try_accept(&ip));
+        // 4th attempt within the minute should be rejected
+        assert!(!tracker.try_accept(&ip));
+    }
+
+    #[test]
+    fn test_no_limits() {
+        let tracker = ConnectionTracker::new(None, None);
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+
+        for _ in 0..1000 {
+            assert!(tracker.try_accept(&ip));
+            tracker.connection_opened(&ip);
+        }
+        assert_eq!(tracker.active_connections(&ip), 1000);
+    }
+
+    #[test]
+    fn test_tracked_ips() {
+        let tracker = ConnectionTracker::new(None, None);
+        assert_eq!(tracker.tracked_ips(), 0);
+
+        let ip1: IpAddr = "10.0.0.1".parse().unwrap();
+        let ip2: IpAddr = "10.0.0.2".parse().unwrap();
+
+        tracker.connection_opened(&ip1);
+        tracker.connection_opened(&ip2);
+        assert_eq!(tracker.tracked_ips(), 2);
+
+        tracker.connection_closed(&ip1);
+        assert_eq!(tracker.tracked_ips(), 1);
+    }
+
+    #[test]
+    fn test_timestamps_cleaned_on_last_close() {
+        let tracker = ConnectionTracker::new(None, Some(100));
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+
+        // try_accept populates the timestamps map (when rate limiting is enabled)
+        assert!(tracker.try_accept(&ip));
+        tracker.connection_opened(&ip);
+        assert!(tracker.try_accept(&ip));
+        tracker.connection_opened(&ip);
+
+        // Timestamps should exist
+        assert!(tracker.timestamps.get(&ip).is_some());
+
+        // Close one connection — timestamps should still exist
+        tracker.connection_closed(&ip);
+        assert!(tracker.timestamps.get(&ip).is_some());
+
+        // Close last connection — timestamps should be cleaned up
+        tracker.connection_closed(&ip);
+        assert!(tracker.timestamps.get(&ip).is_none());
+        assert!(tracker.active.get(&ip).is_none());
+    }
+
+    #[test]
+    fn test_cleanup_stale_timestamps() {
+        // Rate limit of 100/min so timestamps are tracked
+        let tracker = ConnectionTracker::new(None, Some(100));
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+
+        // try_accept adds a timestamp entry
+        assert!(tracker.try_accept(&ip));
+
+        // Simulate: connection was rate-limited and never accepted,
+        // so no connection_opened / connection_closed pair
+        assert!(tracker.timestamps.get(&ip).is_some());
+        assert!(tracker.active.get(&ip).is_none()); // never opened
+
+        // Cleanup won't remove it yet because timestamp is recent
+        tracker.cleanup_stale_timestamps();
+        assert!(tracker.timestamps.get(&ip).is_some());
+
+        // After expiry (use 0-second window trick: create tracker with 0 rate)
+        // Actually, we can't fast-forward time easily, so just verify the cleanup
+        // doesn't panic and handles the no-rate-limit case
+        let tracker2 = ConnectionTracker::new(None, None);
+        tracker2.cleanup_stale_timestamps(); // should be a no-op
+    }
+}

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

@@ -0,0 +1,216 @@
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+use tokio_util::sync::CancellationToken;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+use tracing::debug;
+
+use rustproxy_metrics::MetricsCollector;
+
+/// Context for forwarding metrics, replacing the growing tuple pattern.
+#[derive(Clone)]
+pub struct ForwardMetricsCtx {
+    pub collector: Arc<MetricsCollector>,
+    pub route_id: Option<String>,
+    pub source_ip: Option<String>,
+}
+
+/// Perform bidirectional TCP forwarding between client and backend.
+///
+/// This is the core data path for passthrough connections.
+/// Returns (bytes_from_client, bytes_from_backend) when the connection closes.
+pub async fn forward_bidirectional(
+    mut client: TcpStream,
+    mut backend: TcpStream,
+    initial_data: Option<&[u8]>,
+) -> std::io::Result<(u64, u64)> {
+    // Send initial data (peeked bytes) to backend
+    if let Some(data) = initial_data {
+        backend.write_all(data).await?;
+    }
+
+    let (mut client_read, mut client_write) = client.split();
+    let (mut backend_read, mut backend_write) = backend.split();
+
+    let client_to_backend = async {
+        let mut buf = vec![0u8; 65536];
+        let mut total = initial_data.map_or(0u64, |d| d.len() as u64);
+        loop {
+            let n = client_read.read(&mut buf).await?;
+            if n == 0 {
+                break;
+            }
+            backend_write.write_all(&buf[..n]).await?;
+            total += n as u64;
+        }
+        backend_write.shutdown().await?;
+        Ok::<u64, std::io::Error>(total)
+    };
+
+    let backend_to_client = async {
+        let mut buf = vec![0u8; 65536];
+        let mut total = 0u64;
+        loop {
+            let n = backend_read.read(&mut buf).await?;
+            if n == 0 {
+                break;
+            }
+            client_write.write_all(&buf[..n]).await?;
+            total += n as u64;
+        }
+        client_write.shutdown().await?;
+        Ok::<u64, std::io::Error>(total)
+    };
+
+    let (c2b, b2c) = tokio::join!(client_to_backend, backend_to_client);
+
+    Ok((c2b.unwrap_or(0), b2c.unwrap_or(0)))
+}
+
+/// Perform bidirectional TCP forwarding with inactivity and max lifetime timeouts.
+///
+/// When `metrics` is provided, bytes are reported to the MetricsCollector
+/// per-chunk (lock-free) as they flow through the copy loops, enabling
+/// real-time throughput sampling for long-lived connections.
+///
+/// Returns (bytes_from_client, bytes_from_backend) when the connection closes or times out.
+pub async fn forward_bidirectional_with_timeouts(
+    client: TcpStream,
+    mut backend: TcpStream,
+    initial_data: Option<&[u8]>,
+    inactivity_timeout: std::time::Duration,
+    max_lifetime: std::time::Duration,
+    cancel: CancellationToken,
+    metrics: Option<ForwardMetricsCtx>,
+) -> std::io::Result<(u64, u64)> {
+    // Send initial data (peeked bytes) to backend
+    if let Some(data) = initial_data {
+        backend.write_all(data).await?;
+        if let Some(ref ctx) = metrics {
+            ctx.collector.record_bytes(data.len() as u64, 0, ctx.route_id.as_deref(), ctx.source_ip.as_deref());
+        }
+    }
+
+    let (mut client_read, mut client_write) = client.into_split();
+    let (mut backend_read, mut backend_write) = backend.into_split();
+
+    let last_activity = Arc::new(AtomicU64::new(0));
+    let start = std::time::Instant::now();
+
+    // Per-connection cancellation token: the watchdog cancels this instead of
+    // aborting tasks, so the copy loops can shut down gracefully (TCP FIN instead
+    // of RST, TLS close_notify if the stream is TLS-wrapped).
+    let conn_cancel = CancellationToken::new();
+
+    let la1 = Arc::clone(&last_activity);
+    let initial_len = initial_data.map_or(0u64, |d| d.len() as u64);
+    let metrics_c2b = metrics.clone();
+    let cc1 = conn_cancel.clone();
+    let c2b = tokio::spawn(async move {
+        let mut buf = vec![0u8; 65536];
+        let mut total = initial_len;
+        loop {
+            let n = tokio::select! {
+                result = client_read.read(&mut buf) => match result {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => n,
+                },
+                _ = cc1.cancelled() => break,
+            };
+            if backend_write.write_all(&buf[..n]).await.is_err() {
+                break;
+            }
+            total += n as u64;
+            la1.store(start.elapsed().as_millis() as u64, Ordering::Relaxed);
+            if let Some(ref ctx) = metrics_c2b {
+                ctx.collector.record_bytes(n as u64, 0, ctx.route_id.as_deref(), ctx.source_ip.as_deref());
+            }
+        }
+        // Graceful shutdown with timeout (sends TCP FIN / TLS close_notify)
+        let _ = tokio::time::timeout(
+            std::time::Duration::from_secs(2),
+            backend_write.shutdown(),
+        ).await;
+        total
+    });
+
+    let la2 = Arc::clone(&last_activity);
+    let metrics_b2c = metrics;
+    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 = backend_read.read(&mut buf) => match result {
+                    Ok(0) | Err(_) => break,
+                    Ok(n) => n,
+                },
+                _ = cc2.cancelled() => break,
+            };
+            if client_write.write_all(&buf[..n]).await.is_err() {
+                break;
+            }
+            total += n as u64;
+            la2.store(start.elapsed().as_millis() as u64, Ordering::Relaxed);
+            if let Some(ref ctx) = metrics_b2c {
+                ctx.collector.record_bytes(0, n as u64, ctx.route_id.as_deref(), ctx.source_ip.as_deref());
+            }
+        }
+        // Graceful shutdown with timeout (sends TCP FIN / TLS close_notify)
+        let _ = tokio::time::timeout(
+            std::time::Duration::from_secs(2),
+            client_write.shutdown(),
+        ).await;
+        total
+    });
+
+    // Watchdog: inactivity, max lifetime, and cancellation.
+    // First cancels the per-connection token for graceful shutdown (FIN/close_notify),
+    // then falls back to abort if the tasks are stuck (e.g. on a blocked write_all).
+    let la_watch = Arc::clone(&last_activity);
+    let c2b_abort = c2b.abort_handle();
+    let b2c_abort = b2c.abort_handle();
+    let watchdog = tokio::spawn(async move {
+        let check_interval = std::time::Duration::from_secs(5);
+        let mut last_seen = 0u64;
+        loop {
+            tokio::select! {
+                _ = cancel.cancelled() => {
+                    debug!("Connection cancelled by shutdown");
+                    break;
+                }
+                _ = tokio::time::sleep(check_interval) => {
+                    // Check max lifetime
+                    if start.elapsed() >= max_lifetime {
+                        debug!("Connection exceeded max lifetime, closing");
+                        break;
+                    }
+
+                    // Check inactivity
+                    let current = la_watch.load(Ordering::Relaxed);
+                    if current == last_seen {
+                        let elapsed_since_activity = start.elapsed().as_millis() as u64 - current;
+                        if elapsed_since_activity >= inactivity_timeout.as_millis() as u64 {
+                            debug!("Connection inactive for {}ms, closing", elapsed_since_activity);
+                            break;
+                        }
+                    }
+                    last_seen = current;
+                }
+            }
+        }
+        // Phase 1: Signal copy loops to exit gracefully (allows FIN/close_notify)
+        conn_cancel.cancel();
+        // Phase 2: Wait for graceful shutdown (2s shutdown timeout + 2s margin)
+        tokio::time::sleep(std::time::Duration::from_secs(4)).await;
+        // Phase 3: Force-abort if still stuck (e.g. blocked on write_all)
+        c2b_abort.abort();
+        b2c_abort.abort();
+    });
+
+    let bytes_in = c2b.await.unwrap_or(0);
+    let bytes_out = b2c.await.unwrap_or(0);
+    watchdog.abort();
+    Ok((bytes_in, bytes_out))
+}

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

@@ -0,0 +1,27 @@
+//! # rustproxy-passthrough
+//!
+//! 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;
+pub mod forwarder;
+pub mod proxy_protocol;
+pub mod tls_handler;
+pub mod connection_tracker;
+pub mod socket_opts;
+pub mod udp_session;
+pub mod udp_listener;
+pub mod quic_handler;
+
+pub use tcp_listener::*;
+pub use sni_parser::*;
+pub use forwarder::*;
+pub use proxy_protocol::*;
+pub use tls_handler::*;
+pub use connection_tracker::*;
+pub use socket_opts::*;
+pub use udp_session::*;
+pub use udp_listener::*;
+pub use quic_handler::*;

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

@@ -0,0 +1,480 @@
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum ProxyProtocolError {
+    #[error("Invalid PROXY protocol header")]
+    InvalidHeader,
+    #[error("Unsupported PROXY protocol version")]
+    UnsupportedVersion,
+    #[error("Parse error: {0}")]
+    Parse(String),
+    #[error("Incomplete header: need {0} bytes, got {1}")]
+    Incomplete(usize, usize),
+}
+
+/// Parsed PROXY protocol header (v1 or v2).
+#[derive(Debug, Clone)]
+pub struct ProxyProtocolHeader {
+    pub source_addr: SocketAddr,
+    pub dest_addr: SocketAddr,
+    pub protocol: ProxyProtocol,
+}
+
+/// Protocol in PROXY header.
+#[derive(Debug, Clone, PartialEq, Eq)]
+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> {
+    let line_end = data
+        .windows(2)
+        .position(|w| w == b"\r\n")
+        .ok_or(ProxyProtocolError::InvalidHeader)?;
+
+    let line = std::str::from_utf8(&data[..line_end])
+        .map_err(|_| ProxyProtocolError::InvalidHeader)?;
+
+    if !line.starts_with("PROXY ") {
+        return Err(ProxyProtocolError::InvalidHeader);
+    }
+
+    let parts: Vec<&str> = line.split(' ').collect();
+    if parts.len() != 6 {
+        return Err(ProxyProtocolError::InvalidHeader);
+    }
+
+    let protocol = match parts[1] {
+        "TCP4" => ProxyProtocol::Tcp4,
+        "TCP6" => ProxyProtocol::Tcp6,
+        "UNKNOWN" => ProxyProtocol::Unknown,
+        _ => return Err(ProxyProtocolError::UnsupportedVersion),
+    };
+
+    let src_ip: IpAddr = parts[2]
+        .parse()
+        .map_err(|_| ProxyProtocolError::Parse("Invalid source IP".to_string()))?;
+    let dst_ip: IpAddr = parts[3]
+        .parse()
+        .map_err(|_| ProxyProtocolError::Parse("Invalid destination IP".to_string()))?;
+    let src_port: u16 = parts[4]
+        .parse()
+        .map_err(|_| ProxyProtocolError::Parse("Invalid source port".to_string()))?;
+    let dst_port: u16 = parts[5]
+        .parse()
+        .map_err(|_| ProxyProtocolError::Parse("Invalid destination port".to_string()))?;
+
+    let header = ProxyProtocolHeader {
+        source_addr: SocketAddr::new(src_ip, src_port),
+        dest_addr: SocketAddr::new(dst_ip, dst_port),
+        protocol,
+    };
+
+    Ok((header, line_end + 2))
+}
+
+/// Generate a PROXY protocol v1 header string.
+pub fn generate_v1(source: &SocketAddr, dest: &SocketAddr) -> String {
+    let proto = if source.is_ipv4() { "TCP4" } else { "TCP6" };
+    format!(
+        "PROXY {} {} {} {} {}\r\n",
+        proto,
+        source.ip(),
+        dest.ip(),
+        source.port(),
+        dest.port()
+    )
+}
+
+/// Check if data starts with a PROXY protocol v1 header.
+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";
+        let (parsed, consumed) = parse_v1(header).unwrap();
+        assert_eq!(consumed, header.len());
+        assert_eq!(parsed.protocol, ProxyProtocol::Tcp4);
+        assert_eq!(parsed.source_addr.ip().to_string(), "192.168.1.100");
+        assert_eq!(parsed.source_addr.port(), 12345);
+        assert_eq!(parsed.dest_addr.ip().to_string(), "10.0.0.1");
+        assert_eq!(parsed.dest_addr.port(), 443);
+    }
+
+    #[test]
+    fn test_generate_v1() {
+        let source: SocketAddr = "192.168.1.100:12345".parse().unwrap();
+        let dest: SocketAddr = "10.0.0.1:443".parse().unwrap();
+        let header = generate_v1(&source, &dest);
+        assert_eq!(header, "PROXY TCP4 192.168.1.100 10.0.0.1 12345 443\r\n");
+    }
+
+    #[test]
+    fn test_is_proxy_protocol() {
+        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,708 @@
+//! 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,
+}
+
+impl Drop for RelaySession {
+    fn drop(&mut self) {
+        self.cancel.cancel();
+        self.return_task.abort();
+    }
+}
+
+/// 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();
+    let watchdog = 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);
+    watchdog.abort();
+
+    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/sni_parser.rs

@@ -0,0 +1,323 @@
+//! ClientHello SNI extraction via manual byte parsing.
+//! No TLS stack needed - we just parse enough of the ClientHello to extract the SNI.
+
+/// Result of SNI extraction.
+#[derive(Debug)]
+pub enum SniResult {
+    /// Successfully extracted SNI hostname.
+    Found(String),
+    /// TLS ClientHello detected but no SNI extension present.
+    NoSni,
+    /// Not a TLS ClientHello (plain HTTP or other protocol).
+    NotTls,
+    /// Need more data to determine.
+    NeedMoreData,
+}
+
+/// Extract the SNI hostname from a TLS ClientHello message.
+///
+/// This parses just enough of the TLS record to find the SNI extension,
+/// without performing any actual TLS operations.
+pub fn extract_sni(data: &[u8]) -> SniResult {
+    // Minimum TLS record header is 5 bytes
+    if data.len() < 5 {
+        return SniResult::NeedMoreData;
+    }
+
+    // Check for TLS record: content_type=22 (Handshake)
+    if data[0] != 0x16 {
+        return SniResult::NotTls;
+    }
+
+    // TLS version (major.minor) - accept any
+    // data[1..2] = version
+
+    // Record length
+    let record_len = ((data[3] as usize) << 8) | (data[4] as usize);
+    let _total_len = 5 + record_len;
+
+    // We need at least the handshake header (5 TLS + 4 handshake = 9)
+    if data.len() < 9 {
+        return SniResult::NeedMoreData;
+    }
+
+    // Handshake type = 1 (ClientHello)
+    if data[5] != 0x01 {
+        return SniResult::NotTls;
+    }
+
+    // Handshake length (3 bytes) - informational, we parse incrementally
+    let _handshake_len = ((data[6] as usize) << 16)
+        | ((data[7] as usize) << 8)
+        | (data[8] as usize);
+
+    let hello = &data[9..];
+
+    // ClientHello structure:
+    // 2 bytes: client version
+    // 32 bytes: random
+    // 1 byte: session_id length + session_id
+    let mut pos = 2 + 32; // skip version + random
+
+    if pos >= hello.len() {
+        return SniResult::NeedMoreData;
+    }
+
+    // Session ID
+    let session_id_len = hello[pos] as usize;
+    pos += 1 + session_id_len;
+
+    if pos + 2 > hello.len() {
+        return SniResult::NeedMoreData;
+    }
+
+    // Cipher suites
+    let cipher_suites_len = ((hello[pos] as usize) << 8) | (hello[pos + 1] as usize);
+    pos += 2 + cipher_suites_len;
+
+    if pos + 1 > hello.len() {
+        return SniResult::NeedMoreData;
+    }
+
+    // Compression methods
+    let compression_len = hello[pos] as usize;
+    pos += 1 + compression_len;
+
+    if pos + 2 > hello.len() {
+        // No extensions
+        return SniResult::NoSni;
+    }
+
+    // Extensions length
+    let extensions_len = ((hello[pos] as usize) << 8) | (hello[pos + 1] as usize);
+    pos += 2;
+
+    let extensions_end = pos + extensions_len;
+    if extensions_end > hello.len() {
+        // Partial extensions, try to parse what we have
+    }
+
+    // Parse extensions looking for SNI (type 0x0000)
+    while pos + 4 <= hello.len() && pos < extensions_end {
+        let ext_type = ((hello[pos] as u16) << 8) | (hello[pos + 1] as u16);
+        let ext_len = ((hello[pos + 2] as usize) << 8) | (hello[pos + 3] as usize);
+        pos += 4;
+
+        if ext_type == 0x0000 {
+            // SNI extension
+            return parse_sni_extension(&hello[pos..(pos + ext_len).min(hello.len())], ext_len);
+        }
+
+        pos += ext_len;
+    }
+
+    SniResult::NoSni
+}
+
+/// Parse the SNI extension data.
+fn parse_sni_extension(data: &[u8], _ext_len: usize) -> SniResult {
+    if data.len() < 5 {
+        return SniResult::NeedMoreData;
+    }
+
+    // Server name list length
+    let _list_len = ((data[0] as usize) << 8) | (data[1] as usize);
+
+    // Server name type (0 = hostname)
+    if data[2] != 0x00 {
+        return SniResult::NoSni;
+    }
+
+    // Hostname length
+    let name_len = ((data[3] as usize) << 8) | (data[4] as usize);
+
+    if data.len() < 5 + name_len {
+        return SniResult::NeedMoreData;
+    }
+
+    match std::str::from_utf8(&data[5..5 + name_len]) {
+        Ok(hostname) => SniResult::Found(hostname.to_lowercase()),
+        Err(_) => SniResult::NoSni,
+    }
+}
+
+/// Check if the initial bytes look like a TLS ClientHello.
+pub fn is_tls(data: &[u8]) -> bool {
+    data.len() >= 3 && data[0] == 0x16 && data[1] == 0x03
+}
+
+/// Extract the HTTP request path from initial data.
+/// E.g., from "GET /foo/bar HTTP/1.1\r\n..." returns Some("/foo/bar").
+pub fn extract_http_path(data: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(data).ok()?;
+    // Find first space (after method)
+    let method_end = text.find(' ')?;
+    let rest = &text[method_end + 1..];
+    // Find end of path (next space before "HTTP/...")
+    let path_end = rest.find(' ').unwrap_or(rest.len());
+    let path = &rest[..path_end];
+    // Strip query string for path matching
+    let path = path.split('?').next().unwrap_or(path);
+    if path.starts_with('/') {
+        Some(path.to_string())
+    } else {
+        None
+    }
+}
+
+/// Extract the HTTP Host header from initial data.
+/// E.g., from "GET / HTTP/1.1\r\nHost: example.com\r\n..." returns Some("example.com").
+pub fn extract_http_host(data: &[u8]) -> Option<String> {
+    let text = std::str::from_utf8(data).ok()?;
+    for line in text.split("\r\n") {
+        if let Some(value) = line.strip_prefix("Host: ").or_else(|| line.strip_prefix("host: ")) {
+            // Strip port if present
+            let host = value.split(':').next().unwrap_or(value).trim();
+            if !host.is_empty() {
+                return Some(host.to_lowercase());
+            }
+        }
+    }
+    None
+}
+
+/// Check if the initial bytes look like HTTP.
+pub fn is_http(data: &[u8]) -> bool {
+    if data.len() < 4 {
+        return false;
+    }
+    // Check for common HTTP methods
+    let starts = [
+        b"GET " as &[u8],
+        b"POST",
+        b"PUT ",
+        b"HEAD",
+        b"DELE",
+        b"PATC",
+        b"OPTI",
+        b"CONN",
+        b"PRI ",   // HTTP/2 connection preface
+    ];
+    starts.iter().any(|s| data.starts_with(s))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_not_tls() {
+        let http_data = b"GET / HTTP/1.1\r\n";
+        assert!(matches!(extract_sni(http_data), SniResult::NotTls));
+    }
+
+    #[test]
+    fn test_too_short() {
+        assert!(matches!(extract_sni(&[0x16, 0x03]), SniResult::NeedMoreData));
+    }
+
+    #[test]
+    fn test_is_tls() {
+        assert!(is_tls(&[0x16, 0x03, 0x01]));
+        assert!(!is_tls(&[0x47, 0x45, 0x54])); // "GET"
+    }
+
+    #[test]
+    fn test_is_http() {
+        assert!(is_http(b"GET /"));
+        assert!(is_http(b"POST /api"));
+        assert!(!is_http(&[0x16, 0x03, 0x01]));
+    }
+
+    #[test]
+    fn test_real_client_hello() {
+        // A minimal TLS 1.2 ClientHello with SNI "example.com"
+        let client_hello: Vec<u8> = build_test_client_hello("example.com");
+        match extract_sni(&client_hello) {
+            SniResult::Found(sni) => assert_eq!(sni, "example.com"),
+            other => panic!("Expected Found, got {:?}", other),
+        }
+    }
+
+    /// Build a minimal TLS ClientHello for testing.
+    fn build_test_client_hello(hostname: &str) -> Vec<u8> {
+        let hostname_bytes = hostname.as_bytes();
+
+        // SNI extension
+        let sni_ext_data = {
+            let mut d = Vec::new();
+            // Server name list length
+            let name_entry_len = 3 + hostname_bytes.len(); // type(1) + len(2) + name
+            d.push(((name_entry_len >> 8) & 0xFF) as u8);
+            d.push((name_entry_len & 0xFF) as u8);
+            // Host name type = 0
+            d.push(0x00);
+            // Host name length
+            d.push(((hostname_bytes.len() >> 8) & 0xFF) as u8);
+            d.push((hostname_bytes.len() & 0xFF) as u8);
+            // Host name
+            d.extend_from_slice(hostname_bytes);
+            d
+        };
+
+        // Extension: type=0x0000 (SNI), length, data
+        let sni_extension = {
+            let mut e = Vec::new();
+            e.push(0x00); e.push(0x00); // SNI type
+            e.push(((sni_ext_data.len() >> 8) & 0xFF) as u8);
+            e.push((sni_ext_data.len() & 0xFF) as u8);
+            e.extend_from_slice(&sni_ext_data);
+            e
+        };
+
+        // Extensions block
+        let extensions = {
+            let mut ext = Vec::new();
+            ext.push(((sni_extension.len() >> 8) & 0xFF) as u8);
+            ext.push((sni_extension.len() & 0xFF) as u8);
+            ext.extend_from_slice(&sni_extension);
+            ext
+        };
+
+        // ClientHello body
+        let hello_body = {
+            let mut h = Vec::new();
+            // Client version TLS 1.2
+            h.push(0x03); h.push(0x03);
+            // Random (32 bytes)
+            h.extend_from_slice(&[0u8; 32]);
+            // Session ID length = 0
+            h.push(0x00);
+            // Cipher suites: length=2, one suite
+            h.push(0x00); h.push(0x02);
+            h.push(0x00); h.push(0x2F); // TLS_RSA_WITH_AES_128_CBC_SHA
+            // Compression methods: length=1, null
+            h.push(0x01); h.push(0x00);
+            // Extensions
+            h.extend_from_slice(&extensions);
+            h
+        };
+
+        // Handshake: type=1 (ClientHello), length
+        let handshake = {
+            let mut hs = Vec::new();
+            hs.push(0x01); // ClientHello
+            // 3-byte length
+            hs.push(((hello_body.len() >> 16) & 0xFF) as u8);
+            hs.push(((hello_body.len() >> 8) & 0xFF) as u8);
+            hs.push((hello_body.len() & 0xFF) as u8);
+            hs.extend_from_slice(&hello_body);
+            hs
+        };
+
+        // TLS record: type=0x16, version TLS 1.0, length
+        let mut record = Vec::new();
+        record.push(0x16); // Handshake
+        record.push(0x03); record.push(0x01); // TLS 1.0
+        record.push(((handshake.len() >> 8) & 0xFF) as u8);
+        record.push((handshake.len() & 0xFF) as u8);
+        record.extend_from_slice(&handshake);
+
+        record
+    }
+}

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

@@ -0,0 +1,19 @@
+//! Socket-level options for TCP streams (keepalive, etc.).
+//!
+//! Uses `socket2::SockRef::from()` to borrow the raw fd without ownership transfer.
+
+use std::io;
+use std::time::Duration;
+use tokio::net::TcpStream;
+
+/// Apply TCP keepalive to a connected socket.
+///
+/// Enables SO_KEEPALIVE and sets the initial probe delay.
+/// On Linux, also sets the interval between probes to the same value.
+pub fn apply_keepalive(stream: &TcpStream, delay: Duration) -> io::Result<()> {
+    let sock_ref = socket2::SockRef::from(stream);
+    let ka = socket2::TcpKeepalive::new().with_time(delay);
+    #[cfg(target_os = "linux")]
+    let ka = ka.with_interval(delay);
+    sock_ref.set_tcp_keepalive(&ka)
+}

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

@@ -0,0 +1,4 @@
+//! Socket handler relay module.
+//!
+//! Note: The actual relay logic lives in `tcp_listener::relay_to_socket_handler()`
+//! which has proper timeouts, cancellation, and metrics integration.

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

@@ -0,0 +1,330 @@
+use std::collections::HashMap;
+use std::io::BufReader;
+use std::sync::{Arc, OnceLock};
+
+use rustls::pki_types::{CertificateDer, PrivateKeyDer};
+use rustls::server::ResolvesServerCert;
+use rustls::sign::CertifiedKey;
+use rustls::ServerConfig;
+use tokio::net::TcpStream;
+use tokio_rustls::{TlsAcceptor, TlsConnector, server::TlsStream as ServerTlsStream};
+use tracing::{debug, info};
+
+use crate::tcp_listener::TlsCertConfig;
+
+/// Ensure the default crypto provider is installed.
+fn ensure_crypto_provider() {
+    let _ = rustls::crypto::ring::default_provider().install_default();
+}
+
+/// SNI-based certificate resolver with pre-parsed CertifiedKeys.
+/// Enables shared ServerConfig across connections — avoids per-connection PEM parsing
+/// and enables TLS session resumption.
+#[derive(Debug)]
+pub struct CertResolver {
+    certs: HashMap<String, Arc<CertifiedKey>>,
+    fallback: Option<Arc<CertifiedKey>>,
+}
+
+impl CertResolver {
+    /// Build a resolver from PEM-encoded cert/key configs.
+    /// Parses all PEM data upfront so connections only do a cheap HashMap lookup.
+    pub fn new(configs: &HashMap<String, TlsCertConfig>) -> Result<Self, Box<dyn std::error::Error + Send + Sync>> {
+        ensure_crypto_provider();
+        let provider = rustls::crypto::ring::default_provider();
+        let mut certs = HashMap::new();
+        let mut fallback = None;
+
+        for (domain, cfg) in configs {
+            let cert_chain = load_certs(&cfg.cert_pem)?;
+            let key = load_private_key(&cfg.key_pem)?;
+            let ck = Arc::new(CertifiedKey::from_der(cert_chain, key, &provider)
+                .map_err(|e| format!("CertifiedKey for {}: {}", domain, e))?);
+            if domain == "*" {
+                fallback = Some(Arc::clone(&ck));
+            }
+            certs.insert(domain.clone(), ck);
+        }
+
+        // If no explicit "*" fallback, use the first available cert
+        if fallback.is_none() {
+            fallback = certs.values().next().map(Arc::clone);
+        }
+
+        Ok(Self { certs, fallback })
+    }
+}
+
+impl ResolvesServerCert for CertResolver {
+    fn resolve(&self, client_hello: rustls::server::ClientHello<'_>) -> Option<Arc<CertifiedKey>> {
+        let domain = match client_hello.server_name() {
+            Some(name) => name,
+            None => return self.fallback.clone(),
+        };
+        // Exact match
+        if let Some(ck) = self.certs.get(domain) {
+            return Some(Arc::clone(ck));
+        }
+        // Wildcard: sub.example.com → *.example.com
+        if let Some(dot) = domain.find('.') {
+            let wc = format!("*.{}", &domain[dot + 1..]);
+            if let Some(ck) = self.certs.get(&wc) {
+                return Some(Arc::clone(ck));
+            }
+        }
+        self.fallback.clone()
+    }
+}
+
+/// Build a shared TLS acceptor with SNI resolution, session cache, and session tickets.
+/// The returned acceptor can be reused across all connections (cheap Arc clone).
+pub fn build_shared_tls_acceptor(resolver: CertResolver) -> Result<TlsAcceptor, Box<dyn std::error::Error + Send + Sync>> {
+    ensure_crypto_provider();
+    let mut config = ServerConfig::builder()
+        .with_no_client_auth()
+        .with_cert_resolver(Arc::new(resolver));
+
+    // ALPN: advertise h2 and http/1.1 for client-facing HTTP/2 support
+    config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
+
+    // Shared session cache — enables session ID resumption across connections
+    config.session_storage = rustls::server::ServerSessionMemoryCache::new(4096);
+    // Session ticket resumption (12-hour lifetime, Chacha20Poly1305 encrypted)
+    config.ticketer = rustls::crypto::ring::Ticketer::new()
+        .map_err(|e| format!("Ticketer: {}", e))?;
+
+    info!("Built shared TLS config with session cache (4096), ticket support, and ALPN h2+http/1.1");
+    Ok(TlsAcceptor::from(Arc::new(config)))
+}
+
+/// Build a TLS acceptor from PEM-encoded cert and key data.
+/// Advertises both h2 and http/1.1 via ALPN (for client-facing connections).
+pub fn build_tls_acceptor(cert_pem: &str, key_pem: &str) -> Result<TlsAcceptor, Box<dyn std::error::Error + Send + Sync>> {
+    build_tls_acceptor_with_config(cert_pem, key_pem, None)
+}
+
+/// Build a TLS acceptor for backend servers that only speak HTTP/1.1.
+/// Does NOT advertise h2 in ALPN, preventing false h2 auto-detection.
+pub fn build_tls_acceptor_h1_only(cert_pem: &str, key_pem: &str) -> Result<TlsAcceptor, Box<dyn std::error::Error + Send + Sync>> {
+    ensure_crypto_provider();
+    let certs = load_certs(cert_pem)?;
+    let key = load_private_key(key_pem)?;
+    let mut config = ServerConfig::builder()
+        .with_no_client_auth()
+        .with_single_cert(certs, key)?;
+    config.alpn_protocols = vec![b"http/1.1".to_vec()];
+    Ok(TlsAcceptor::from(Arc::new(config)))
+}
+
+/// Build a TLS acceptor with optional RouteTls configuration for version/cipher tuning.
+pub fn build_tls_acceptor_with_config(
+    cert_pem: &str,
+    key_pem: &str,
+    tls_config: Option<&rustproxy_config::RouteTls>,
+) -> Result<TlsAcceptor, Box<dyn std::error::Error + Send + Sync>> {
+    ensure_crypto_provider();
+    let certs = load_certs(cert_pem)?;
+    let key = load_private_key(key_pem)?;
+
+    let mut config = if let Some(route_tls) = tls_config {
+        // Apply TLS version restrictions
+        let versions = resolve_tls_versions(route_tls.versions.as_deref());
+        let builder = ServerConfig::builder_with_protocol_versions(&versions);
+        builder
+            .with_no_client_auth()
+            .with_single_cert(certs, key)?
+    } else {
+        ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(certs, key)?
+    };
+
+    // ALPN: advertise h2 and http/1.1 for client-facing HTTP/2 support
+    config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
+
+    // Apply session timeout if configured
+    if let Some(route_tls) = tls_config {
+        if let Some(timeout_secs) = route_tls.session_timeout {
+            config.session_storage = rustls::server::ServerSessionMemoryCache::new(
+                256, // max sessions
+            );
+            debug!("TLS session timeout configured: {}s", timeout_secs);
+        }
+    }
+
+    Ok(TlsAcceptor::from(Arc::new(config)))
+}
+
+/// Resolve TLS version strings to rustls SupportedProtocolVersion.
+fn resolve_tls_versions(versions: Option<&[String]>) -> Vec<&'static rustls::SupportedProtocolVersion> {
+    let versions = match versions {
+        Some(v) if !v.is_empty() => v,
+        _ => return vec![&rustls::version::TLS12, &rustls::version::TLS13],
+    };
+
+    let mut result = Vec::new();
+    for v in versions {
+        match v.as_str() {
+            "TLSv1.2" | "TLS1.2" | "1.2" | "TLSv12" => {
+                if !result.contains(&&rustls::version::TLS12) {
+                    result.push(&rustls::version::TLS12);
+                }
+            }
+            "TLSv1.3" | "TLS1.3" | "1.3" | "TLSv13" => {
+                if !result.contains(&&rustls::version::TLS13) {
+                    result.push(&rustls::version::TLS13);
+                }
+            }
+            other => {
+                debug!("Unknown TLS version '{}', ignoring", other);
+            }
+        }
+    }
+
+    if result.is_empty() {
+        // Fallback to both if no valid versions specified
+        vec![&rustls::version::TLS12, &rustls::version::TLS13]
+    } else {
+        result
+    }
+}
+
+/// Accept a TLS connection from a client stream.
+pub async fn accept_tls(
+    stream: TcpStream,
+    acceptor: &TlsAcceptor,
+) -> Result<ServerTlsStream<TcpStream>, Box<dyn std::error::Error + Send + Sync>> {
+    let tls_stream = acceptor.accept(stream).await?;
+    debug!("TLS handshake completed");
+    Ok(tls_stream)
+}
+
+/// Get or create a shared backend TLS `ClientConfig`.
+///
+/// Uses `OnceLock` to ensure only one config is created across the entire process.
+/// The built-in rustls `Resumption` (session tickets + session IDs) is enabled
+/// by default, so all outbound backend connections share the same session cache.
+static SHARED_CLIENT_CONFIG: OnceLock<Arc<rustls::ClientConfig>> = OnceLock::new();
+
+pub fn shared_backend_tls_config() -> Arc<rustls::ClientConfig> {
+    SHARED_CLIENT_CONFIG.get_or_init(|| {
+        ensure_crypto_provider();
+        let config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(Arc::new(InsecureVerifier))
+            .with_no_client_auth();
+        info!("Built shared backend TLS client config with session resumption");
+        Arc::new(config)
+    }).clone()
+}
+
+/// Get or create a shared backend TLS `ClientConfig` with ALPN `h2` + `http/1.1`.
+///
+/// Used for auto-detection mode: the backend server picks its preferred protocol
+/// via ALPN, and the proxy reads the negotiated result to decide h1 vs h2 forwarding.
+static SHARED_CLIENT_CONFIG_ALPN: OnceLock<Arc<rustls::ClientConfig>> = OnceLock::new();
+
+pub fn shared_backend_tls_config_alpn() -> Arc<rustls::ClientConfig> {
+    SHARED_CLIENT_CONFIG_ALPN.get_or_init(|| {
+        ensure_crypto_provider();
+        let mut config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(Arc::new(InsecureVerifier))
+            .with_no_client_auth();
+        config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
+        info!("Built shared backend TLS client config with ALPN h2+http/1.1 for auto-detection");
+        Arc::new(config)
+    }).clone()
+}
+
+/// Connect to a backend with TLS (for terminate-and-reencrypt mode).
+/// Uses the shared backend TLS config for session resumption.
+pub async fn connect_tls(
+    host: &str,
+    port: u16,
+) -> Result<tokio_rustls::client::TlsStream<TcpStream>, Box<dyn std::error::Error + Send + Sync>> {
+    let config = shared_backend_tls_config();
+    let connector = TlsConnector::from(config);
+
+    let stream = TcpStream::connect(format!("{}:{}", host, port)).await?;
+    stream.set_nodelay(true)?;
+    // Apply keepalive with 60s default (tls_handler doesn't have ConnectionConfig access)
+    if let Err(e) = crate::socket_opts::apply_keepalive(&stream, std::time::Duration::from_secs(60)) {
+        debug!("Failed to set keepalive on backend TLS socket: {}", e);
+    }
+
+    let server_name = rustls::pki_types::ServerName::try_from(host.to_string())?;
+    let tls_stream = connector.connect(server_name, stream).await?;
+    debug!("Backend TLS connection established to {}:{}", host, port);
+    Ok(tls_stream)
+}
+
+/// Load certificates from PEM string.
+fn load_certs(pem: &str) -> Result<Vec<CertificateDer<'static>>, Box<dyn std::error::Error + Send + Sync>> {
+    let mut reader = BufReader::new(pem.as_bytes());
+    let certs: Vec<CertificateDer<'static>> = rustls_pemfile::certs(&mut reader)
+        .collect::<Result<Vec<_>, _>>()?;
+    if certs.is_empty() {
+        return Err("No certificates found in PEM data".into());
+    }
+    Ok(certs)
+}
+
+/// Load private key from PEM string.
+fn load_private_key(pem: &str) -> Result<PrivateKeyDer<'static>, Box<dyn std::error::Error + Send + Sync>> {
+    let mut reader = BufReader::new(pem.as_bytes());
+    // Try PKCS8 first, then RSA, then EC
+    let key = rustls_pemfile::private_key(&mut reader)?
+        .ok_or("No private key found in PEM data")?;
+    Ok(key)
+}
+
+/// Insecure certificate verifier for backend connections (terminate-and-reencrypt).
+/// In internal networks, backends may use self-signed certs.
+#[derive(Debug)]
+struct InsecureVerifier;
+
+impl rustls::client::danger::ServerCertVerifier for InsecureVerifier {
+    fn verify_server_cert(
+        &self,
+        _end_entity: &CertificateDer<'_>,
+        _intermediates: &[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: &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: &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::RSA_PKCS1_SHA384,
+            rustls::SignatureScheme::RSA_PKCS1_SHA512,
+            rustls::SignatureScheme::ECDSA_NISTP256_SHA256,
+            rustls::SignatureScheme::ECDSA_NISTP384_SHA384,
+            rustls::SignatureScheme::ED25519,
+            rustls::SignatureScheme::RSA_PSS_SHA256,
+            rustls::SignatureScheme::RSA_PSS_SHA384,
+            rustls::SignatureScheme::RSA_PSS_SHA512,
+        ]
+    }
+}

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/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "rustproxy-routing"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "Route matching engine for RustProxy"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+glob-match = { workspace = true }
+ipnet = { workspace = true }
+regex = { workspace = true }
+tracing = { workspace = true }
+thiserror = { workspace = true }
+arc-swap = { workspace = true }

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

@@ -0,0 +1,9 @@
+//! # rustproxy-routing
+//!
+//! Route matching engine for RustProxy.
+//! Provides domain/path/IP/header matchers and a port-indexed RouteManager.
+
+pub mod route_manager;
+pub mod matchers;
+
+pub use route_manager::*;

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

@@ -0,0 +1,100 @@
+/// Match a domain against a pattern supporting wildcards.
+///
+/// Supported patterns:
+/// - `*` matches any domain
+/// - `*.example.com` matches any subdomain of example.com
+/// - `example.com` exact match
+/// - `**.example.com` matches any depth of subdomain
+pub fn domain_matches(pattern: &str, domain: &str) -> bool {
+    let pattern = pattern.trim();
+    let domain = domain.trim();
+
+    if pattern == "*" {
+        return true;
+    }
+
+    if pattern.eq_ignore_ascii_case(domain) {
+        return true;
+    }
+
+    // Wildcard patterns
+    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.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)
+        {
+            // Check it's a single level subdomain for `*.`
+            let prefix = &domain[..domain.len() - suffix.len() - 1];
+            return !prefix.contains('.');
+        }
+        return false;
+    }
+
+    if pattern.starts_with("**.") {
+        let suffix = &pattern[3..];
+        // Match exact parent or any depth of subdomain
+        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 (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.
+pub fn domain_matches_any(patterns: &[&str], domain: &str) -> bool {
+    patterns.iter().any(|p| domain_matches(p, domain))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_exact_match() {
+        assert!(domain_matches("example.com", "example.com"));
+        assert!(!domain_matches("example.com", "other.com"));
+    }
+
+    #[test]
+    fn test_wildcard_all() {
+        assert!(domain_matches("*", "anything.com"));
+        assert!(domain_matches("*", "sub.domain.example.com"));
+    }
+
+    #[test]
+    fn test_wildcard_subdomain() {
+        assert!(domain_matches("*.example.com", "www.example.com"));
+        assert!(domain_matches("*.example.com", "api.example.com"));
+        assert!(domain_matches("*.example.com", "example.com"));
+        assert!(!domain_matches("*.example.com", "deep.sub.example.com"));
+    }
+
+    #[test]
+    fn test_double_wildcard() {
+        assert!(domain_matches("**.example.com", "www.example.com"));
+        assert!(domain_matches("**.example.com", "deep.sub.example.com"));
+        assert!(domain_matches("**.example.com", "example.com"));
+    }
+
+    #[test]
+    fn test_case_insensitive() {
+        assert!(domain_matches("Example.COM", "example.com"));
+        assert!(domain_matches("*.EXAMPLE.com", "WWW.example.COM"));
+    }
+}

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

@@ -0,0 +1,98 @@
+use std::collections::HashMap;
+use regex::Regex;
+
+/// Match HTTP headers against a set of patterns.
+///
+/// Pattern values can be:
+/// - Exact string: `"application/json"`
+/// - Regex (surrounded by /): `"/^text\/.*/"`
+pub fn headers_match(
+    patterns: &HashMap<String, String>,
+    headers: &HashMap<String, String>,
+) -> bool {
+    for (key, pattern) in patterns {
+        let key_lower = key.to_lowercase();
+
+        // Find the header (case-insensitive)
+        let header_value = headers
+            .iter()
+            .find(|(k, _)| k.to_lowercase() == key_lower)
+            .map(|(_, v)| v.as_str());
+
+        let header_value = match header_value {
+            Some(v) => v,
+            None => return false, // Required header not present
+        };
+
+        // Check if pattern is a regex (surrounded by /)
+        if pattern.starts_with('/') && pattern.ends_with('/') && pattern.len() > 2 {
+            let regex_str = &pattern[1..pattern.len() - 1];
+            match Regex::new(regex_str) {
+                Ok(re) => {
+                    if !re.is_match(header_value) {
+                        return false;
+                    }
+                }
+                Err(_) => {
+                    // Invalid regex, fall back to exact match
+                    if header_value != pattern {
+                        return false;
+                    }
+                }
+            }
+        } else {
+            // Exact match
+            if header_value != pattern {
+                return false;
+            }
+        }
+    }
+
+    true
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_exact_header_match() {
+        let patterns: HashMap<String, String> = {
+            let mut m = HashMap::new();
+            m.insert("Content-Type".to_string(), "application/json".to_string());
+            m
+        };
+        let headers: HashMap<String, String> = {
+            let mut m = HashMap::new();
+            m.insert("content-type".to_string(), "application/json".to_string());
+            m
+        };
+        assert!(headers_match(&patterns, &headers));
+    }
+
+    #[test]
+    fn test_regex_header_match() {
+        let patterns: HashMap<String, String> = {
+            let mut m = HashMap::new();
+            m.insert("Content-Type".to_string(), "/^text\\/.*/".to_string());
+            m
+        };
+        let headers: HashMap<String, String> = {
+            let mut m = HashMap::new();
+            m.insert("content-type".to_string(), "text/html".to_string());
+            m
+        };
+        assert!(headers_match(&patterns, &headers));
+    }
+
+    #[test]
+    fn test_missing_header() {
+        let patterns: HashMap<String, String> = {
+            let mut m = HashMap::new();
+            m.insert("X-Custom".to_string(), "value".to_string());
+            m
+        };
+        let headers: HashMap<String, String> = HashMap::new();
+        assert!(!headers_match(&patterns, &headers));
+    }
+}

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

@@ -0,0 +1,126 @@
+use std::net::IpAddr;
+use std::str::FromStr;
+use ipnet::IpNet;
+
+/// Match an IP address against a pattern.
+///
+/// Supported patterns:
+/// - `*` matches any IP
+/// - `192.168.1.0/24` CIDR range
+/// - `192.168.1.100` exact match
+/// - `192.168.1.*` wildcard (converted to CIDR)
+/// - `::ffff:192.168.1.100` IPv6-mapped IPv4
+pub fn ip_matches(pattern: &str, ip: &str) -> bool {
+    let pattern = pattern.trim();
+
+    if pattern == "*" {
+        return true;
+    }
+
+    // Normalize IPv4-mapped IPv6
+    let normalized_ip = normalize_ip_str(ip);
+
+    // Try CIDR match
+    if pattern.contains('/') {
+        if let Ok(net) = IpNet::from_str(pattern) {
+            if let Ok(addr) = IpAddr::from_str(&normalized_ip) {
+                return net.contains(&addr);
+            }
+        }
+        return false;
+    }
+
+    // Handle wildcard patterns like 192.168.1.*
+    if pattern.contains('*') {
+        let pattern_cidr = wildcard_to_cidr(pattern);
+        if let Some(cidr) = pattern_cidr {
+            if let Ok(net) = IpNet::from_str(&cidr) {
+                if let Ok(addr) = IpAddr::from_str(&normalized_ip) {
+                    return net.contains(&addr);
+                }
+            }
+        }
+        return false;
+    }
+
+    // Exact match
+    let normalized_pattern = normalize_ip_str(pattern);
+    normalized_ip == normalized_pattern
+}
+
+/// Check if an IP matches any of the given patterns.
+pub fn ip_matches_any(patterns: &[String], ip: &str) -> bool {
+    patterns.iter().any(|p| ip_matches(p, ip))
+}
+
+/// Normalize IPv4-mapped IPv6 addresses.
+fn normalize_ip_str(ip: &str) -> String {
+    let ip = ip.trim();
+    if ip.starts_with("::ffff:") {
+        return ip[7..].to_string();
+    }
+    ip.to_string()
+}
+
+/// Convert a wildcard IP pattern to CIDR notation.
+/// e.g., "192.168.1.*" -> "192.168.1.0/24"
+fn wildcard_to_cidr(pattern: &str) -> Option<String> {
+    let parts: Vec<&str> = pattern.split('.').collect();
+    if parts.len() != 4 {
+        return None;
+    }
+
+    let mut octets = [0u8; 4];
+    let mut prefix_len = 0;
+
+    for (i, part) in parts.iter().enumerate() {
+        if *part == "*" {
+            break;
+        }
+        if let Ok(n) = part.parse::<u8>() {
+            octets[i] = n;
+            prefix_len += 8;
+        } else {
+            return None;
+        }
+    }
+
+    Some(format!("{}.{}.{}.{}/{}", octets[0], octets[1], octets[2], octets[3], prefix_len))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_wildcard_all() {
+        assert!(ip_matches("*", "192.168.1.100"));
+        assert!(ip_matches("*", "::1"));
+    }
+
+    #[test]
+    fn test_exact_match() {
+        assert!(ip_matches("192.168.1.100", "192.168.1.100"));
+        assert!(!ip_matches("192.168.1.100", "192.168.1.101"));
+    }
+
+    #[test]
+    fn test_cidr() {
+        assert!(ip_matches("192.168.1.0/24", "192.168.1.100"));
+        assert!(ip_matches("192.168.1.0/24", "192.168.1.1"));
+        assert!(!ip_matches("192.168.1.0/24", "192.168.2.1"));
+    }
+
+    #[test]
+    fn test_wildcard_pattern() {
+        assert!(ip_matches("192.168.1.*", "192.168.1.100"));
+        assert!(ip_matches("192.168.1.*", "192.168.1.1"));
+        assert!(!ip_matches("192.168.1.*", "192.168.2.1"));
+    }
+
+    #[test]
+    fn test_ipv6_mapped() {
+        assert!(ip_matches("192.168.1.100", "::ffff:192.168.1.100"));
+        assert!(ip_matches("192.168.1.0/24", "::ffff:192.168.1.50"));
+    }
+}

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

@@ -0,0 +1,9 @@
+pub mod domain;
+pub mod path;
+pub mod ip;
+pub mod header;
+
+pub use domain::*;
+pub use path::*;
+pub use ip::*;
+pub use header::*;

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

@@ -0,0 +1,65 @@
+/// Match a URL path against a pattern supporting wildcards.
+///
+/// Supported patterns:
+/// - `/api/*` matches `/api/anything` (single level)
+/// - `/api/**` matches `/api/any/depth/here`
+/// - `/exact/path` exact match
+/// - `/prefix*` prefix match
+pub fn path_matches(pattern: &str, path: &str) -> bool {
+    // Exact match
+    if pattern == path {
+        return true;
+    }
+
+    // Double-star: match any depth
+    if pattern.ends_with("/**") {
+        let prefix = &pattern[..pattern.len() - 3];
+        return path == prefix || path.starts_with(&format!("{}/", prefix));
+    }
+
+    // Single-star at end: match single path segment
+    if pattern.ends_with("/*") {
+        let prefix = &pattern[..pattern.len() - 2];
+        if path == prefix {
+            return true;
+        }
+        if path.starts_with(&format!("{}/", prefix)) {
+            let rest = &path[prefix.len() + 1..];
+            // Single level means no more slashes
+            return !rest.contains('/');
+        }
+        return false;
+    }
+
+    // Star anywhere: use glob matching
+    if pattern.contains('*') {
+        return glob_match::glob_match(pattern, path);
+    }
+
+    false
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_exact_path() {
+        assert!(path_matches("/api/users", "/api/users"));
+        assert!(!path_matches("/api/users", "/api/posts"));
+    }
+
+    #[test]
+    fn test_single_wildcard() {
+        assert!(path_matches("/api/*", "/api/users"));
+        assert!(path_matches("/api/*", "/api/posts"));
+        assert!(!path_matches("/api/*", "/api/users/123"));
+    }
+
+    #[test]
+    fn test_double_wildcard() {
+        assert!(path_matches("/api/**", "/api/users"));
+        assert!(path_matches("/api/**", "/api/users/123"));
+        assert!(path_matches("/api/**", "/api/users/123/posts"));
+    }
+}

rust/crates/rustproxy-security/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "rustproxy-security"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "IP filtering, rate limiting, and authentication for RustProxy"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+dashmap = { workspace = true }
+ipnet = { workspace = true }
+jsonwebtoken = { workspace = true }
+base64 = { workspace = true }
+tracing = { workspace = true }
+thiserror = { workspace = true }
+serde = { workspace = true }

rust/crates/rustproxy-security/src/basic_auth.rs

@@ -0,0 +1,111 @@
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD as BASE64;
+
+/// Basic auth validator.
+pub struct BasicAuthValidator {
+    users: Vec<(String, String)>,
+    realm: String,
+}
+
+impl BasicAuthValidator {
+    pub fn new(users: Vec<(String, String)>, realm: Option<String>) -> Self {
+        Self {
+            users,
+            realm: realm.unwrap_or_else(|| "Restricted".to_string()),
+        }
+    }
+
+    /// Validate an Authorization header value.
+    /// Returns the username if valid.
+    pub fn validate(&self, auth_header: &str) -> Option<String> {
+        let auth_header = auth_header.trim();
+        if !auth_header.starts_with("Basic ") {
+            return None;
+        }
+
+        let encoded = &auth_header[6..];
+        let decoded = BASE64.decode(encoded).ok()?;
+        let credentials = String::from_utf8(decoded).ok()?;
+
+        let mut parts = credentials.splitn(2, ':');
+        let username = parts.next()?;
+        let password = parts.next()?;
+
+        for (u, p) in &self.users {
+            if u == username && p == password {
+                return Some(username.to_string());
+            }
+        }
+
+        None
+    }
+
+    /// Get the realm for WWW-Authenticate header.
+    pub fn realm(&self) -> &str {
+        &self.realm
+    }
+
+    /// Generate the WWW-Authenticate header value.
+    pub fn www_authenticate(&self) -> String {
+        format!("Basic realm=\"{}\"", self.realm)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use base64::Engine;
+
+    fn make_validator() -> BasicAuthValidator {
+        BasicAuthValidator::new(
+            vec![
+                ("admin".to_string(), "secret".to_string()),
+                ("user".to_string(), "pass".to_string()),
+            ],
+            Some("TestRealm".to_string()),
+        )
+    }
+
+    fn encode_basic(user: &str, pass: &str) -> String {
+        let encoded = BASE64.encode(format!("{}:{}", user, pass));
+        format!("Basic {}", encoded)
+    }
+
+    #[test]
+    fn test_valid_credentials() {
+        let validator = make_validator();
+        let header = encode_basic("admin", "secret");
+        assert_eq!(validator.validate(&header), Some("admin".to_string()));
+    }
+
+    #[test]
+    fn test_invalid_password() {
+        let validator = make_validator();
+        let header = encode_basic("admin", "wrong");
+        assert_eq!(validator.validate(&header), None);
+    }
+
+    #[test]
+    fn test_not_basic_scheme() {
+        let validator = make_validator();
+        assert_eq!(validator.validate("Bearer sometoken"), None);
+    }
+
+    #[test]
+    fn test_malformed_base64() {
+        let validator = make_validator();
+        assert_eq!(validator.validate("Basic !!!not-base64!!!"), None);
+    }
+
+    #[test]
+    fn test_www_authenticate_format() {
+        let validator = make_validator();
+        assert_eq!(validator.www_authenticate(), "Basic realm=\"TestRealm\"");
+    }
+
+    #[test]
+    fn test_default_realm() {
+        let validator = BasicAuthValidator::new(vec![], None);
+        assert_eq!(validator.www_authenticate(), "Basic realm=\"Restricted\"");
+    }
+}

rust/crates/rustproxy-security/src/ip_filter.rs

@@ -0,0 +1,189 @@
+use ipnet::IpNet;
+use std::net::IpAddr;
+use std::str::FromStr;
+
+/// IP filter supporting CIDR ranges, wildcards, and exact matches.
+pub struct IpFilter {
+    allow_list: Vec<IpPattern>,
+    block_list: Vec<IpPattern>,
+}
+
+/// Represents an IP pattern for matching.
+#[derive(Debug)]
+enum IpPattern {
+    /// Exact IP match
+    Exact(IpAddr),
+    /// CIDR range match
+    Cidr(IpNet),
+    /// Wildcard (matches everything)
+    Wildcard,
+}
+
+impl IpPattern {
+    fn parse(s: &str) -> Self {
+        let s = s.trim();
+        if s == "*" {
+            return IpPattern::Wildcard;
+        }
+        if let Ok(net) = IpNet::from_str(s) {
+            return IpPattern::Cidr(net);
+        }
+        if let Ok(addr) = IpAddr::from_str(s) {
+            return IpPattern::Exact(addr);
+        }
+        // Try as CIDR by appending default prefix
+        if let Ok(addr) = IpAddr::from_str(s) {
+            return IpPattern::Exact(addr);
+        }
+        // Fallback: treat as exact, will never match an invalid string
+        IpPattern::Exact(IpAddr::from_str("0.0.0.0").unwrap())
+    }
+
+    fn matches(&self, ip: &IpAddr) -> bool {
+        match self {
+            IpPattern::Wildcard => true,
+            IpPattern::Exact(addr) => addr == ip,
+            IpPattern::Cidr(net) => net.contains(ip),
+        }
+    }
+}
+
+impl IpFilter {
+    /// Create a new IP filter from allow and block lists.
+    pub fn new(allow_list: &[String], block_list: &[String]) -> Self {
+        Self {
+            allow_list: allow_list.iter().map(|s| IpPattern::parse(s)).collect(),
+            block_list: block_list.iter().map(|s| IpPattern::parse(s)).collect(),
+        }
+    }
+
+    /// Check if an IP is allowed.
+    /// If allow_list is non-empty, IP must match at least one entry.
+    /// If block_list is non-empty, IP must NOT match any entry.
+    pub fn is_allowed(&self, ip: &IpAddr) -> bool {
+        // Check block list first
+        if !self.block_list.is_empty() {
+            for pattern in &self.block_list {
+                if pattern.matches(ip) {
+                    return false;
+                }
+            }
+        }
+
+        // If allow list is non-empty, must match at least one
+        if !self.allow_list.is_empty() {
+            return self.allow_list.iter().any(|p| p.matches(ip));
+        }
+
+        true
+    }
+
+    /// Normalize IPv4-mapped IPv6 addresses (::ffff:x.x.x.x -> x.x.x.x)
+    pub fn normalize_ip(ip: &IpAddr) -> IpAddr {
+        match ip {
+            IpAddr::V6(v6) => {
+                if let Some(v4) = v6.to_ipv4_mapped() {
+                    IpAddr::V4(v4)
+                } else {
+                    *ip
+                }
+            }
+            _ => *ip,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_empty_lists_allow_all() {
+        let filter = IpFilter::new(&[], &[]);
+        let ip: IpAddr = "192.168.1.1".parse().unwrap();
+        assert!(filter.is_allowed(&ip));
+    }
+
+    #[test]
+    fn test_allow_list_exact() {
+        let filter = IpFilter::new(
+            &["10.0.0.1".to_string()],
+            &[],
+        );
+        let allowed: IpAddr = "10.0.0.1".parse().unwrap();
+        let denied: IpAddr = "10.0.0.2".parse().unwrap();
+        assert!(filter.is_allowed(&allowed));
+        assert!(!filter.is_allowed(&denied));
+    }
+
+    #[test]
+    fn test_allow_list_cidr() {
+        let filter = IpFilter::new(
+            &["10.0.0.0/8".to_string()],
+            &[],
+        );
+        let allowed: IpAddr = "10.255.255.255".parse().unwrap();
+        let denied: IpAddr = "192.168.1.1".parse().unwrap();
+        assert!(filter.is_allowed(&allowed));
+        assert!(!filter.is_allowed(&denied));
+    }
+
+    #[test]
+    fn test_block_list() {
+        let filter = IpFilter::new(
+            &[],
+            &["192.168.1.100".to_string()],
+        );
+        let blocked: IpAddr = "192.168.1.100".parse().unwrap();
+        let allowed: IpAddr = "192.168.1.101".parse().unwrap();
+        assert!(!filter.is_allowed(&blocked));
+        assert!(filter.is_allowed(&allowed));
+    }
+
+    #[test]
+    fn test_block_trumps_allow() {
+        let filter = IpFilter::new(
+            &["10.0.0.0/8".to_string()],
+            &["10.0.0.5".to_string()],
+        );
+        let blocked: IpAddr = "10.0.0.5".parse().unwrap();
+        let allowed: IpAddr = "10.0.0.6".parse().unwrap();
+        assert!(!filter.is_allowed(&blocked));
+        assert!(filter.is_allowed(&allowed));
+    }
+
+    #[test]
+    fn test_wildcard_allow() {
+        let filter = IpFilter::new(
+            &["*".to_string()],
+            &[],
+        );
+        let ip: IpAddr = "1.2.3.4".parse().unwrap();
+        assert!(filter.is_allowed(&ip));
+    }
+
+    #[test]
+    fn test_wildcard_block() {
+        let filter = IpFilter::new(
+            &[],
+            &["*".to_string()],
+        );
+        let ip: IpAddr = "1.2.3.4".parse().unwrap();
+        assert!(!filter.is_allowed(&ip));
+    }
+
+    #[test]
+    fn test_normalize_ipv4_mapped_ipv6() {
+        let mapped: IpAddr = "::ffff:192.168.1.1".parse().unwrap();
+        let normalized = IpFilter::normalize_ip(&mapped);
+        let expected: IpAddr = "192.168.1.1".parse().unwrap();
+        assert_eq!(normalized, expected);
+    }
+
+    #[test]
+    fn test_normalize_pure_ipv4() {
+        let ip: IpAddr = "10.0.0.1".parse().unwrap();
+        let normalized = IpFilter::normalize_ip(&ip);
+        assert_eq!(normalized, ip);
+    }
+}

rust/crates/rustproxy-security/src/jwt_auth.rs

@@ -0,0 +1,174 @@
+use jsonwebtoken::{decode, DecodingKey, Validation, Algorithm};
+use serde::{Deserialize, Serialize};
+
+/// JWT claims (minimal structure).
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Claims {
+    pub sub: Option<String>,
+    pub exp: Option<u64>,
+    pub iss: Option<String>,
+    pub aud: Option<String>,
+}
+
+/// JWT auth validator.
+pub struct JwtValidator {
+    decoding_key: DecodingKey,
+    validation: Validation,
+}
+
+impl JwtValidator {
+    pub fn new(
+        secret: &str,
+        algorithm: Option<&str>,
+        issuer: Option<&str>,
+        audience: Option<&str>,
+    ) -> Self {
+        let algo = match algorithm {
+            Some("HS384") => Algorithm::HS384,
+            Some("HS512") => Algorithm::HS512,
+            Some("RS256") => Algorithm::RS256,
+            _ => Algorithm::HS256,
+        };
+
+        let mut validation = Validation::new(algo);
+        if let Some(iss) = issuer {
+            validation.set_issuer(&[iss]);
+        }
+        if let Some(aud) = audience {
+            validation.set_audience(&[aud]);
+        }
+
+        Self {
+            decoding_key: DecodingKey::from_secret(secret.as_bytes()),
+            validation,
+        }
+    }
+
+    /// Validate a JWT token string (without "Bearer " prefix).
+    /// Returns the claims if valid.
+    pub fn validate(&self, token: &str) -> Result<Claims, String> {
+        decode::<Claims>(token, &self.decoding_key, &self.validation)
+            .map(|data| data.claims)
+            .map_err(|e| e.to_string())
+    }
+
+    /// Extract token from Authorization header.
+    pub fn extract_token(auth_header: &str) -> Option<&str> {
+        let header = auth_header.trim();
+        if header.starts_with("Bearer ") {
+            Some(&header[7..])
+        } else {
+            None
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use jsonwebtoken::{encode, EncodingKey, Header};
+
+    fn make_token(secret: &str, claims: &Claims) -> String {
+        encode(
+            &Header::default(),
+            claims,
+            &EncodingKey::from_secret(secret.as_bytes()),
+        )
+        .unwrap()
+    }
+
+    fn future_exp() -> u64 {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs()
+            + 3600
+    }
+
+    fn past_exp() -> u64 {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs()
+            - 3600
+    }
+
+    #[test]
+    fn test_valid_token() {
+        let secret = "test-secret";
+        let claims = Claims {
+            sub: Some("user123".to_string()),
+            exp: Some(future_exp()),
+            iss: None,
+            aud: None,
+        };
+        let token = make_token(secret, &claims);
+        let validator = JwtValidator::new(secret, None, None, None);
+        let result = validator.validate(&token);
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap().sub, Some("user123".to_string()));
+    }
+
+    #[test]
+    fn test_expired_token() {
+        let secret = "test-secret";
+        let claims = Claims {
+            sub: Some("user123".to_string()),
+            exp: Some(past_exp()),
+            iss: None,
+            aud: None,
+        };
+        let token = make_token(secret, &claims);
+        let validator = JwtValidator::new(secret, None, None, None);
+        assert!(validator.validate(&token).is_err());
+    }
+
+    #[test]
+    fn test_wrong_secret() {
+        let claims = Claims {
+            sub: Some("user123".to_string()),
+            exp: Some(future_exp()),
+            iss: None,
+            aud: None,
+        };
+        let token = make_token("correct-secret", &claims);
+        let validator = JwtValidator::new("wrong-secret", None, None, None);
+        assert!(validator.validate(&token).is_err());
+    }
+
+    #[test]
+    fn test_issuer_validation() {
+        let secret = "test-secret";
+        let claims = Claims {
+            sub: Some("user123".to_string()),
+            exp: Some(future_exp()),
+            iss: Some("my-issuer".to_string()),
+            aud: None,
+        };
+        let token = make_token(secret, &claims);
+
+        // Correct issuer
+        let validator = JwtValidator::new(secret, None, Some("my-issuer"), None);
+        assert!(validator.validate(&token).is_ok());
+
+        // Wrong issuer
+        let validator = JwtValidator::new(secret, None, Some("other-issuer"), None);
+        assert!(validator.validate(&token).is_err());
+    }
+
+    #[test]
+    fn test_extract_token_bearer() {
+        assert_eq!(
+            JwtValidator::extract_token("Bearer abc123"),
+            Some("abc123")
+        );
+    }
+
+    #[test]
+    fn test_extract_token_non_bearer() {
+        assert_eq!(JwtValidator::extract_token("Basic abc123"), None);
+        assert_eq!(JwtValidator::extract_token("abc123"), None);
+    }
+}

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

@@ -0,0 +1,13 @@
+//! # rustproxy-security
+//!
+//! IP filtering, rate limiting, and authentication for RustProxy.
+
+pub mod ip_filter;
+pub mod rate_limiter;
+pub mod basic_auth;
+pub mod jwt_auth;
+
+pub use ip_filter::*;
+pub use rate_limiter::*;
+pub use basic_auth::*;
+pub use jwt_auth::*;

rust/crates/rustproxy-security/src/rate_limiter.rs

@@ -0,0 +1,97 @@
+use dashmap::DashMap;
+use std::time::Instant;
+
+/// Sliding window rate limiter.
+pub struct RateLimiter {
+    /// Map of key -> list of request timestamps
+    windows: DashMap<String, Vec<Instant>>,
+    /// Maximum requests per window
+    max_requests: u64,
+    /// Window duration in seconds
+    window_seconds: u64,
+}
+
+impl RateLimiter {
+    pub fn new(max_requests: u64, window_seconds: u64) -> Self {
+        Self {
+            windows: DashMap::new(),
+            max_requests,
+            window_seconds,
+        }
+    }
+
+    /// Check if a request is allowed for the given key.
+    /// Returns true if allowed, false if rate limited.
+    pub fn check(&self, key: &str) -> bool {
+        let now = Instant::now();
+        let window = std::time::Duration::from_secs(self.window_seconds);
+
+        let mut entry = self.windows.entry(key.to_string()).or_default();
+        let timestamps = entry.value_mut();
+
+        // Remove expired entries
+        timestamps.retain(|t| now.duration_since(*t) < window);
+
+        if timestamps.len() as u64 >= self.max_requests {
+            false
+        } else {
+            timestamps.push(now);
+            true
+        }
+    }
+
+    /// Clean up expired entries (call periodically).
+    pub fn cleanup(&self) {
+        let now = Instant::now();
+        let window = std::time::Duration::from_secs(self.window_seconds);
+
+        self.windows.retain(|_, timestamps| {
+            timestamps.retain(|t| now.duration_since(*t) < window);
+            !timestamps.is_empty()
+        });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_allow_under_limit() {
+        let limiter = RateLimiter::new(5, 60);
+        for _ in 0..5 {
+            assert!(limiter.check("client-1"));
+        }
+    }
+
+    #[test]
+    fn test_block_over_limit() {
+        let limiter = RateLimiter::new(3, 60);
+        assert!(limiter.check("client-1"));
+        assert!(limiter.check("client-1"));
+        assert!(limiter.check("client-1"));
+        assert!(!limiter.check("client-1")); // 4th request blocked
+    }
+
+    #[test]
+    fn test_different_keys_independent() {
+        let limiter = RateLimiter::new(2, 60);
+        assert!(limiter.check("client-a"));
+        assert!(limiter.check("client-a"));
+        assert!(!limiter.check("client-a")); // blocked
+        // Different key should still be allowed
+        assert!(limiter.check("client-b"));
+        assert!(limiter.check("client-b"));
+    }
+
+    #[test]
+    fn test_cleanup_removes_expired() {
+        let limiter = RateLimiter::new(100, 0); // 0 second window = immediately expired
+        limiter.check("client-1");
+        // Sleep briefly to let entries expire
+        std::thread::sleep(std::time::Duration::from_millis(10));
+        limiter.cleanup();
+        // After cleanup, the key should be allowed again (entries expired)
+        assert!(limiter.check("client-1"));
+    }
+}

rust/crates/rustproxy-tls/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "rustproxy-tls"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "TLS certificate management for RustProxy"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+tokio = { workspace = true }
+rustls = { workspace = true }
+instant-acme = { workspace = true }
+tracing = { workspace = true }
+thiserror = { workspace = true }
+anyhow = { workspace = true }
+serde = { workspace = true }
+rcgen = { workspace = true }
+
+[dev-dependencies]

rust/crates/rustproxy-tls/src/acme.rs

@@ -0,0 +1,275 @@
+//! ACME (Let's Encrypt) integration using instant-acme.
+//!
+//! This module handles HTTP-01 challenge creation and certificate provisioning.
+//! Account credentials are ephemeral — the consumer owns all persistence.
+
+use instant_acme::{
+    Account, NewAccount, NewOrder, Identifier, ChallengeType, OrderStatus,
+    AccountCredentials,
+};
+use rcgen::{CertificateParams, KeyPair};
+use thiserror::Error;
+use tracing::{debug, info};
+
+#[derive(Debug, Error)]
+pub enum AcmeError {
+    #[error("ACME account creation failed: {0}")]
+    AccountCreation(String),
+    #[error("ACME order failed: {0}")]
+    OrderFailed(String),
+    #[error("Challenge failed: {0}")]
+    ChallengeFailed(String),
+    #[error("Certificate finalization failed: {0}")]
+    FinalizationFailed(String),
+    #[error("No HTTP-01 challenge found")]
+    NoHttp01Challenge,
+    #[error("Timeout waiting for order: {0}")]
+    Timeout(String),
+}
+
+/// Pending HTTP-01 challenge that needs to be served.
+pub struct PendingChallenge {
+    pub token: String,
+    pub key_authorization: String,
+    pub domain: String,
+}
+
+/// ACME client wrapper around instant-acme.
+pub struct AcmeClient {
+    use_production: bool,
+    email: String,
+}
+
+impl AcmeClient {
+    pub fn new(email: String, use_production: bool) -> Self {
+        Self {
+            use_production,
+            email,
+        }
+    }
+
+    /// Create a new ACME account (ephemeral — not persisted).
+    async fn get_or_create_account(&self) -> Result<Account, AcmeError> {
+        let directory_url = self.directory_url();
+
+        let contact = format!("mailto:{}", self.email);
+        let (account, _credentials) = Account::create(
+            &NewAccount {
+                contact: &[&contact],
+                terms_of_service_agreed: true,
+                only_return_existing: false,
+            },
+            directory_url,
+            None,
+        )
+        .await
+        .map_err(|e| AcmeError::AccountCreation(e.to_string()))?;
+
+        debug!("ACME account created");
+
+        Ok(account)
+    }
+
+    /// Request a certificate for a domain using the HTTP-01 challenge.
+    ///
+    /// Returns (cert_chain_pem, private_key_pem) on success.
+    ///
+    /// The caller must serve the HTTP-01 challenge at:
+    ///   `http://<domain>/.well-known/acme-challenge/<token>`
+    ///
+    /// The `challenge_handler` closure is called with a `PendingChallenge`
+    /// and must arrange for the challenge response to be served. It should
+    /// return once the challenge is ready to be validated.
+    pub async fn provision<F, Fut>(
+        &self,
+        domain: &str,
+        challenge_handler: F,
+    ) -> Result<(String, String), AcmeError>
+    where
+        F: FnOnce(PendingChallenge) -> Fut,
+        Fut: std::future::Future<Output = Result<(), AcmeError>>,
+    {
+        info!("Starting ACME provisioning for {} via {}", domain, self.directory_url());
+
+        // 1. Get or create ACME account
+        let account = self.get_or_create_account().await?;
+
+        // 2. Create order
+        let identifier = Identifier::Dns(domain.to_string());
+        let mut order = account
+            .new_order(&NewOrder {
+                identifiers: &[identifier],
+            })
+            .await
+            .map_err(|e| AcmeError::OrderFailed(e.to_string()))?;
+
+        debug!("ACME order created");
+
+        // 3. Get authorizations and find HTTP-01 challenge
+        let authorizations = order
+            .authorizations()
+            .await
+            .map_err(|e| AcmeError::OrderFailed(e.to_string()))?;
+
+        // Find the HTTP-01 challenge
+        let (challenge_token, challenge_url) = authorizations
+            .iter()
+            .flat_map(|auth| auth.challenges.iter())
+            .find(|c| c.r#type == ChallengeType::Http01)
+            .map(|c| {
+                let key_auth = order.key_authorization(c);
+                (
+                    PendingChallenge {
+                        token: c.token.clone(),
+                        key_authorization: key_auth.as_str().to_string(),
+                        domain: domain.to_string(),
+                    },
+                    c.url.clone(),
+                )
+            })
+            .ok_or(AcmeError::NoHttp01Challenge)?;
+
+        // Call the handler to set up challenge serving
+        challenge_handler(challenge_token).await?;
+
+        // 4. Notify ACME server that challenge is ready
+        order
+            .set_challenge_ready(&challenge_url)
+            .await
+            .map_err(|e| AcmeError::ChallengeFailed(e.to_string()))?;
+
+        debug!("Challenge marked as ready, waiting for validation...");
+
+        // 5. Poll for order to become ready
+        let mut attempts = 0;
+        let state = loop {
+            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+            let state = order
+                .refresh()
+                .await
+                .map_err(|e| AcmeError::OrderFailed(e.to_string()))?;
+
+            match state.status {
+                OrderStatus::Ready | OrderStatus::Valid => break state.status,
+                OrderStatus::Invalid => {
+                    return Err(AcmeError::ChallengeFailed(
+                        "Order became invalid (challenge failed)".to_string(),
+                    ));
+                }
+                _ => {
+                    attempts += 1;
+                    if attempts > 30 {
+                        return Err(AcmeError::Timeout(
+                            "Order did not become ready within 60 seconds".to_string(),
+                        ));
+                    }
+                }
+            }
+        };
+
+        debug!("Order ready, finalizing...");
+
+        // 6. Generate CSR and finalize
+        let key_pair = KeyPair::generate().map_err(|e| {
+            AcmeError::FinalizationFailed(format!("Key generation failed: {}", e))
+        })?;
+
+        let mut params = CertificateParams::new(vec![domain.to_string()]).map_err(|e| {
+            AcmeError::FinalizationFailed(format!("CSR params failed: {}", e))
+        })?;
+        params.distinguished_name.push(rcgen::DnType::CommonName, domain);
+
+        let csr = params.serialize_request(&key_pair).map_err(|e| {
+            AcmeError::FinalizationFailed(format!("CSR serialization failed: {}", e))
+        })?;
+
+        if state == OrderStatus::Ready {
+            order
+                .finalize(csr.der())
+                .await
+                .map_err(|e| AcmeError::FinalizationFailed(e.to_string()))?;
+        }
+
+        // 7. Wait for certificate to be issued
+        let mut attempts = 0;
+        loop {
+            let state = order
+                .refresh()
+                .await
+                .map_err(|e| AcmeError::OrderFailed(e.to_string()))?;
+            if state.status == OrderStatus::Valid {
+                break;
+            }
+            if state.status == OrderStatus::Invalid {
+                return Err(AcmeError::FinalizationFailed(
+                    "Order became invalid during finalization".to_string(),
+                ));
+            }
+            attempts += 1;
+            if attempts > 15 {
+                return Err(AcmeError::Timeout(
+                    "Certificate not issued within 30 seconds".to_string(),
+                ));
+            }
+            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+        }
+
+        // 8. Download certificate
+        let cert_chain_pem = order
+            .certificate()
+            .await
+            .map_err(|e| AcmeError::FinalizationFailed(e.to_string()))?
+            .ok_or_else(|| {
+                AcmeError::FinalizationFailed("No certificate returned".to_string())
+            })?;
+
+        let private_key_pem = key_pair.serialize_pem();
+
+        info!("Certificate provisioned successfully for {}", domain);
+
+        Ok((cert_chain_pem, private_key_pem))
+    }
+
+    /// Restore an ACME account from stored credentials.
+    pub async fn restore_account(
+        &self,
+        credentials: AccountCredentials,
+    ) -> Result<Account, AcmeError> {
+        Account::from_credentials(credentials)
+            .await
+            .map_err(|e| AcmeError::AccountCreation(e.to_string()))
+    }
+
+    /// Get the ACME directory URL based on production/staging.
+    pub fn directory_url(&self) -> &str {
+        if self.use_production {
+            "https://acme-v02.api.letsencrypt.org/directory"
+        } else {
+            "https://acme-staging-v02.api.letsencrypt.org/directory"
+        }
+    }
+
+    /// Whether this client is configured for production.
+    pub fn is_production(&self) -> bool {
+        self.use_production
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_directory_url_staging() {
+        let client = AcmeClient::new("test@example.com".to_string(), false);
+        assert!(client.directory_url().contains("staging"));
+        assert!(!client.is_production());
+    }
+
+    #[test]
+    fn test_directory_url_production() {
+        let client = AcmeClient::new("test@example.com".to_string(), true);
+        assert!(!client.directory_url().contains("staging"));
+        assert!(client.is_production());
+    }
+}

rust/crates/rustproxy-tls/src/cert_manager.rs

@@ -0,0 +1,168 @@
+use std::time::{SystemTime, UNIX_EPOCH};
+use thiserror::Error;
+use tracing::info;
+
+use crate::cert_store::{CertStore, CertBundle, CertMetadata, CertSource};
+use crate::acme::AcmeClient;
+
+#[derive(Debug, Error)]
+pub enum CertManagerError {
+    #[error("ACME provisioning failed for {domain}: {message}")]
+    AcmeFailure { domain: String, message: String },
+    #[error("No ACME email configured")]
+    NoEmail,
+}
+
+/// Certificate lifecycle manager.
+/// Handles ACME provisioning, static cert loading, and renewal.
+pub struct CertManager {
+    store: CertStore,
+    acme_email: Option<String>,
+    use_production: bool,
+    renew_before_days: u32,
+}
+
+impl CertManager {
+    pub fn new(
+        store: CertStore,
+        acme_email: Option<String>,
+        use_production: bool,
+        renew_before_days: u32,
+    ) -> Self {
+        Self {
+            store,
+            acme_email,
+            use_production,
+            renew_before_days,
+        }
+    }
+
+    /// Get a certificate for a domain (from cache).
+    pub fn get_cert(&self, domain: &str) -> Option<&CertBundle> {
+        self.store.get(domain)
+    }
+
+    /// Create an ACME client using this manager's configuration.
+    /// Returns None if no ACME email is configured.
+    pub fn acme_client(&self) -> Option<AcmeClient> {
+        self.acme_email.as_ref().map(|email| {
+            AcmeClient::new(email.clone(), self.use_production)
+        })
+    }
+
+    /// Load a static certificate into the store (infallible — pure cache insert).
+    pub fn load_static(
+        &mut self,
+        domain: String,
+        bundle: CertBundle,
+    ) {
+        self.store.store(domain, bundle);
+    }
+
+    /// Check and return domains that need certificate renewal.
+    ///
+    /// A certificate needs renewal if it expires within `renew_before_days`.
+    /// Returns a list of domain names needing renewal.
+    pub fn check_renewals(&self) -> Vec<String> {
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs();
+
+        let renewal_threshold = self.renew_before_days as u64 * 86400;
+        let mut needs_renewal = Vec::new();
+
+        for (domain, bundle) in self.store.iter() {
+            // Only auto-renew ACME certs
+            if bundle.metadata.source != CertSource::Acme {
+                continue;
+            }
+
+            let time_until_expiry = bundle.metadata.expires_at.saturating_sub(now);
+            if time_until_expiry < renewal_threshold {
+                info!(
+                    "Certificate for {} needs renewal (expires in {} days)",
+                    domain,
+                    time_until_expiry / 86400
+                );
+                needs_renewal.push(domain.clone());
+            }
+        }
+
+        needs_renewal
+    }
+
+    /// Renew a certificate for a domain.
+    ///
+    /// Performs the full ACME provision+store flow. The `challenge_setup` closure
+    /// is called to arrange for the HTTP-01 challenge to be served. It receives
+    /// (token, key_authorization) and must make the challenge response available.
+    ///
+    /// Returns the new CertBundle on success.
+    pub async fn renew_domain<F, Fut>(
+        &mut self,
+        domain: &str,
+        challenge_setup: F,
+    ) -> Result<CertBundle, CertManagerError>
+    where
+        F: FnOnce(String, String) -> Fut,
+        Fut: std::future::Future<Output = ()>,
+    {
+        let acme_client = self.acme_client()
+            .ok_or(CertManagerError::NoEmail)?;
+
+        info!("Renewing certificate for {}", domain);
+
+        let domain_owned = domain.to_string();
+        let result = acme_client.provision(&domain_owned, |pending| {
+            let token = pending.token.clone();
+            let key_auth = pending.key_authorization.clone();
+            async move {
+                challenge_setup(token, key_auth).await;
+                Ok(())
+            }
+        }).await.map_err(|e| CertManagerError::AcmeFailure {
+            domain: domain.to_string(),
+            message: e.to_string(),
+        })?;
+
+        let (cert_pem, key_pem) = result;
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_secs();
+
+        let bundle = CertBundle {
+            cert_pem,
+            key_pem,
+            ca_pem: None,
+            metadata: CertMetadata {
+                domain: domain.to_string(),
+                source: CertSource::Acme,
+                issued_at: now,
+                expires_at: now + 90 * 86400,
+                renewed_at: Some(now),
+            },
+        };
+
+        self.store.store(domain.to_string(), bundle.clone());
+        info!("Certificate renewed and stored for {}", domain);
+
+        Ok(bundle)
+    }
+
+    /// Whether this manager has an ACME email configured.
+    pub fn has_acme(&self) -> bool {
+        self.acme_email.is_some()
+    }
+
+    /// Get reference to the underlying store.
+    pub fn store(&self) -> &CertStore {
+        &self.store
+    }
+
+    /// Get mutable reference to the underlying store.
+    pub fn store_mut(&mut self) -> &mut CertStore {
+        &mut self.store
+    }
+}

rust/crates/rustproxy-tls/src/cert_store.rs

@@ -0,0 +1,174 @@
+use std::collections::HashMap;
+use serde::{Deserialize, Serialize};
+
+/// Certificate metadata stored alongside certs.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CertMetadata {
+    pub domain: String,
+    pub source: CertSource,
+    pub issued_at: u64,
+    pub expires_at: u64,
+    pub renewed_at: Option<u64>,
+}
+
+/// How a certificate was obtained.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum CertSource {
+    Acme,
+    Static,
+    Custom,
+    SelfSigned,
+}
+
+/// An in-memory certificate bundle.
+#[derive(Debug, Clone)]
+pub struct CertBundle {
+    pub key_pem: String,
+    pub cert_pem: String,
+    pub ca_pem: Option<String>,
+    pub metadata: CertMetadata,
+}
+
+/// In-memory certificate store.
+///
+/// All persistence is owned by the consumer (TypeScript side).
+/// This struct is a thin HashMap wrapper used as a runtime cache.
+pub struct CertStore {
+    cache: HashMap<String, CertBundle>,
+}
+
+impl CertStore {
+    /// Create a new empty cert store.
+    pub fn new() -> Self {
+        Self {
+            cache: HashMap::new(),
+        }
+    }
+
+    /// Get a certificate by domain.
+    pub fn get(&self, domain: &str) -> Option<&CertBundle> {
+        self.cache.get(domain)
+    }
+
+    /// Store a certificate in the cache.
+    pub fn store(&mut self, domain: String, bundle: CertBundle) {
+        self.cache.insert(domain, bundle);
+    }
+
+    /// Check if a certificate exists for a domain.
+    pub fn has(&self, domain: &str) -> bool {
+        self.cache.contains_key(domain)
+    }
+
+    /// Get the number of cached certificates.
+    pub fn count(&self) -> usize {
+        self.cache.len()
+    }
+
+    /// Iterate over all cached certificates.
+    pub fn iter(&self) -> impl Iterator<Item = (&String, &CertBundle)> {
+        self.cache.iter()
+    }
+
+    /// Remove a certificate from the cache.
+    pub fn remove(&mut self, domain: &str) -> bool {
+        self.cache.remove(domain).is_some()
+    }
+}
+
+impl Default for CertStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_test_bundle(domain: &str) -> CertBundle {
+        CertBundle {
+            key_pem: "-----BEGIN PRIVATE KEY-----\ntest-key\n-----END PRIVATE KEY-----\n".to_string(),
+            cert_pem: "-----BEGIN CERTIFICATE-----\ntest-cert\n-----END CERTIFICATE-----\n".to_string(),
+            ca_pem: None,
+            metadata: CertMetadata {
+                domain: domain.to_string(),
+                source: CertSource::Static,
+                issued_at: 1700000000,
+                expires_at: 1700000000 + 90 * 86400,
+                renewed_at: None,
+            },
+        }
+    }
+
+    #[test]
+    fn test_store_and_get() {
+        let mut store = CertStore::new();
+
+        let bundle = make_test_bundle("example.com");
+        store.store("example.com".to_string(), bundle.clone());
+
+        let loaded = store.get("example.com").unwrap();
+        assert_eq!(loaded.key_pem, bundle.key_pem);
+        assert_eq!(loaded.cert_pem, bundle.cert_pem);
+        assert_eq!(loaded.metadata.domain, "example.com");
+        assert_eq!(loaded.metadata.source, CertSource::Static);
+    }
+
+    #[test]
+    fn test_store_with_ca_cert() {
+        let mut store = CertStore::new();
+
+        let mut bundle = make_test_bundle("secure.com");
+        bundle.ca_pem = Some("-----BEGIN CERTIFICATE-----\nca-cert\n-----END CERTIFICATE-----\n".to_string());
+        store.store("secure.com".to_string(), bundle);
+
+        let loaded = store.get("secure.com").unwrap();
+        assert!(loaded.ca_pem.is_some());
+    }
+
+    #[test]
+    fn test_multiple_certs() {
+        let mut store = CertStore::new();
+
+        store.store("a.com".to_string(), make_test_bundle("a.com"));
+        store.store("b.com".to_string(), make_test_bundle("b.com"));
+        store.store("c.com".to_string(), make_test_bundle("c.com"));
+
+        assert_eq!(store.count(), 3);
+        assert!(store.has("a.com"));
+        assert!(store.has("b.com"));
+        assert!(store.has("c.com"));
+    }
+
+    #[test]
+    fn test_remove_cert() {
+        let mut store = CertStore::new();
+
+        store.store("remove-me.com".to_string(), make_test_bundle("remove-me.com"));
+        assert!(store.has("remove-me.com"));
+
+        let removed = store.remove("remove-me.com");
+        assert!(removed);
+        assert!(!store.has("remove-me.com"));
+    }
+
+    #[test]
+    fn test_remove_nonexistent() {
+        let mut store = CertStore::new();
+        assert!(!store.remove("nonexistent.com"));
+    }
+
+    #[test]
+    fn test_wildcard_domain() {
+        let mut store = CertStore::new();
+
+        store.store("*.example.com".to_string(), make_test_bundle("*.example.com"));
+        assert!(store.has("*.example.com"));
+
+        let loaded = store.get("*.example.com").unwrap();
+        assert_eq!(loaded.metadata.domain, "*.example.com");
+    }
+}

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

@@ -0,0 +1,13 @@
+//! # rustproxy-tls
+//!
+//! TLS certificate management for RustProxy.
+//! Handles ACME (Let's Encrypt), static certificates, and dynamic SNI resolution.
+
+pub mod cert_store;
+pub mod cert_manager;
+pub mod acme;
+pub mod sni_resolver;
+
+pub use cert_store::*;
+pub use cert_manager::*;
+pub use sni_resolver::*;

rust/crates/rustproxy-tls/src/sni_resolver.rs

@@ -0,0 +1,139 @@
+use std::collections::HashMap;
+use std::sync::{Arc, RwLock};
+
+use crate::cert_store::CertBundle;
+
+/// Dynamic SNI-based certificate resolver.
+/// Used by the TLS stack to select the right certificate based on client SNI.
+pub struct SniResolver {
+    /// Domain -> certificate bundle mapping
+    certs: RwLock<HashMap<String, Arc<CertBundle>>>,
+    /// Fallback certificate (used when no SNI or no match)
+    fallback: RwLock<Option<Arc<CertBundle>>>,
+}
+
+impl SniResolver {
+    pub fn new() -> Self {
+        Self {
+            certs: RwLock::new(HashMap::new()),
+            fallback: RwLock::new(None),
+        }
+    }
+
+    /// Register a certificate for a domain.
+    pub fn add_cert(&self, domain: String, bundle: CertBundle) {
+        let mut certs = self.certs.write().unwrap();
+        certs.insert(domain, Arc::new(bundle));
+    }
+
+    /// Set the fallback certificate.
+    pub fn set_fallback(&self, bundle: CertBundle) {
+        let mut fallback = self.fallback.write().unwrap();
+        *fallback = Some(Arc::new(bundle));
+    }
+
+    /// Resolve a certificate for the given SNI domain.
+    pub fn resolve(&self, domain: &str) -> Option<Arc<CertBundle>> {
+        let certs = self.certs.read().unwrap();
+
+        // Try exact match
+        if let Some(bundle) = certs.get(domain) {
+            return Some(Arc::clone(bundle));
+        }
+
+        // Try wildcard match (e.g., *.example.com)
+        if let Some(dot_pos) = domain.find('.') {
+            let wildcard = format!("*.{}", &domain[dot_pos + 1..]);
+            if let Some(bundle) = certs.get(&wildcard) {
+                return Some(Arc::clone(bundle));
+            }
+        }
+
+        // Fallback
+        let fallback = self.fallback.read().unwrap();
+        fallback.clone()
+    }
+
+    /// Remove a certificate for a domain.
+    pub fn remove_cert(&self, domain: &str) {
+        let mut certs = self.certs.write().unwrap();
+        certs.remove(domain);
+    }
+
+    /// Get the number of registered certificates.
+    pub fn cert_count(&self) -> usize {
+        self.certs.read().unwrap().len()
+    }
+}
+
+impl Default for SniResolver {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cert_store::{CertBundle, CertMetadata, CertSource};
+
+    fn make_bundle(domain: &str) -> CertBundle {
+        CertBundle {
+            key_pem: format!("KEY-{}", domain),
+            cert_pem: format!("CERT-{}", domain),
+            ca_pem: None,
+            metadata: CertMetadata {
+                domain: domain.to_string(),
+                source: CertSource::Static,
+                issued_at: 0,
+                expires_at: 0,
+                renewed_at: None,
+            },
+        }
+    }
+
+    #[test]
+    fn test_exact_domain_resolve() {
+        let resolver = SniResolver::new();
+        resolver.add_cert("example.com".to_string(), make_bundle("example.com"));
+        let result = resolver.resolve("example.com");
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().cert_pem, "CERT-example.com");
+    }
+
+    #[test]
+    fn test_wildcard_resolve() {
+        let resolver = SniResolver::new();
+        resolver.add_cert("*.example.com".to_string(), make_bundle("*.example.com"));
+        let result = resolver.resolve("sub.example.com");
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().cert_pem, "CERT-*.example.com");
+    }
+
+    #[test]
+    fn test_fallback() {
+        let resolver = SniResolver::new();
+        resolver.set_fallback(make_bundle("fallback"));
+        let result = resolver.resolve("unknown.com");
+        assert!(result.is_some());
+        assert_eq!(result.unwrap().cert_pem, "CERT-fallback");
+    }
+
+    #[test]
+    fn test_no_match_no_fallback() {
+        let resolver = SniResolver::new();
+        resolver.add_cert("example.com".to_string(), make_bundle("example.com"));
+        let result = resolver.resolve("other.com");
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn test_remove_cert() {
+        let resolver = SniResolver::new();
+        resolver.add_cert("example.com".to_string(), make_bundle("example.com"));
+        assert_eq!(resolver.cert_count(), 1);
+        resolver.remove_cert("example.com");
+        assert_eq!(resolver.cert_count(), 0);
+        assert!(resolver.resolve("example.com").is_none());
+    }
+}

rust/crates/rustproxy/Cargo.toml

@@ -0,0 +1,51 @@
+[package]
+name = "rustproxy"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+description = "High-performance multi-protocol proxy built on Pingora, compatible with SmartProxy configuration"
+
+[[bin]]
+name = "rustproxy"
+path = "src/main.rs"
+
+[lib]
+name = "rustproxy"
+path = "src/lib.rs"
+
+[dependencies]
+rustproxy-config = { workspace = true }
+rustproxy-routing = { workspace = true }
+rustproxy-tls = { workspace = true }
+rustproxy-passthrough = { workspace = true }
+rustproxy-http = { workspace = true }
+rustproxy-metrics = { workspace = true }
+rustproxy-security = { workspace = true }
+tokio = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+clap = { workspace = true }
+anyhow = { workspace = true }
+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 }
+hyper = { workspace = true }
+hyper-util = { workspace = true }
+http-body-util = { workspace = true }
+bytes = { workspace = true }
+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/challenge_server.rs

@@ -0,0 +1,177 @@
+//! HTTP-01 ACME challenge server.
+//!
+//! A lightweight HTTP server that serves ACME challenge responses at
+//! `/.well-known/acme-challenge/<token>`.
+
+use std::sync::Arc;
+
+use bytes::Bytes;
+use dashmap::DashMap;
+use http_body_util::Full;
+use hyper::body::Incoming;
+use hyper::{Request, Response, StatusCode};
+use hyper_util::rt::TokioIo;
+use tokio::net::TcpListener;
+use tokio_util::sync::CancellationToken;
+use tracing::{debug, info, error};
+
+/// ACME HTTP-01 challenge server.
+pub struct ChallengeServer {
+    /// Token -> key authorization mapping
+    challenges: Arc<DashMap<String, String>>,
+    /// Cancellation token to stop the server
+    cancel: CancellationToken,
+    /// Server task handle
+    handle: Option<tokio::task::JoinHandle<()>>,
+}
+
+impl ChallengeServer {
+    /// Create a new challenge server (not yet started).
+    pub fn new() -> Self {
+        Self {
+            challenges: Arc::new(DashMap::new()),
+            cancel: CancellationToken::new(),
+            handle: None,
+        }
+    }
+
+    /// Register a challenge token -> key_authorization mapping.
+    pub fn set_challenge(&self, token: String, key_authorization: String) {
+        debug!("Registered ACME challenge: token={}", token);
+        self.challenges.insert(token, key_authorization);
+    }
+
+    /// Remove a challenge token.
+    pub fn remove_challenge(&self, token: &str) {
+        self.challenges.remove(token);
+    }
+
+    /// Start the challenge server on the given port.
+    pub async fn start(&mut self, port: u16) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+        let addr = format!("0.0.0.0:{}", port);
+        let listener = TcpListener::bind(&addr).await?;
+        info!("ACME challenge server listening on port {}", port);
+
+        let challenges = Arc::clone(&self.challenges);
+        let cancel = self.cancel.clone();
+
+        let handle = tokio::spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = cancel.cancelled() => {
+                        info!("ACME challenge server stopping");
+                        break;
+                    }
+                    result = listener.accept() => {
+                        match result {
+                            Ok((stream, _)) => {
+                                let challenges = Arc::clone(&challenges);
+                                tokio::spawn(async move {
+                                    let io = TokioIo::new(stream);
+                                    let service = hyper::service::service_fn(move |req: Request<Incoming>| {
+                                        let challenges = Arc::clone(&challenges);
+                                        async move {
+                                            Self::handle_request(req, &challenges)
+                                        }
+                                    });
+
+                                    let conn = hyper::server::conn::http1::Builder::new()
+                                        .serve_connection(io, service);
+
+                                    if let Err(e) = conn.await {
+                                        debug!("Challenge server connection error: {}", e);
+                                    }
+                                });
+                            }
+                            Err(e) => {
+                                error!("Challenge server accept error: {}", e);
+                                tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        self.handle = Some(handle);
+        Ok(())
+    }
+
+    /// Stop the challenge server.
+    pub async fn stop(&mut self) {
+        self.cancel.cancel();
+        if let Some(handle) = self.handle.take() {
+            let _ = tokio::time::timeout(
+                std::time::Duration::from_secs(5),
+                handle,
+            ).await;
+        }
+        self.challenges.clear();
+        self.cancel = CancellationToken::new();
+        info!("ACME challenge server stopped");
+    }
+
+    /// Handle an HTTP request for ACME challenges.
+    fn handle_request(
+        req: Request<Incoming>,
+        challenges: &DashMap<String, String>,
+    ) -> Result<Response<Full<Bytes>>, hyper::Error> {
+        let path = req.uri().path();
+
+        if let Some(token) = path.strip_prefix("/.well-known/acme-challenge/") {
+            if let Some(key_auth) = challenges.get(token) {
+                debug!("Serving ACME challenge for token: {}", token);
+                return Ok(Response::builder()
+                    .status(StatusCode::OK)
+                    .header("content-type", "text/plain")
+                    .body(Full::new(Bytes::from(key_auth.value().clone())))
+                    .unwrap());
+            }
+        }
+
+        Ok(Response::builder()
+            .status(StatusCode::NOT_FOUND)
+            .body(Full::new(Bytes::from("Not Found")))
+            .unwrap())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_challenge_server_lifecycle() {
+        let mut server = ChallengeServer::new();
+
+        // Set a challenge before starting
+        server.set_challenge("test-token".to_string(), "test-key-auth".to_string());
+
+        // Start on a random port
+        server.start(19900).await.unwrap();
+
+        // Give server a moment to start
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+
+        // Fetch the challenge
+        let client = tokio::net::TcpStream::connect("127.0.0.1:19900").await.unwrap();
+        let io = TokioIo::new(client);
+        let (mut sender, conn) = hyper::client::conn::http1::handshake(io).await.unwrap();
+        tokio::spawn(async move { let _ = conn.await; });
+
+        let req = Request::get("/.well-known/acme-challenge/test-token")
+            .body(Full::new(Bytes::new()))
+            .unwrap();
+        let resp = sender.send_request(req).await.unwrap();
+        assert_eq!(resp.status(), StatusCode::OK);
+
+        // Test 404 for unknown token
+        let req = Request::get("/.well-known/acme-challenge/unknown")
+            .body(Full::new(Bytes::new()))
+            .unwrap();
+        let resp = sender.send_request(req).await.unwrap();
+        assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+
+        server.stop().await;
+    }
+}

rust/crates/rustproxy/src/main.rs

@@ -0,0 +1,98 @@
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
+use clap::Parser;
+use tracing_subscriber::EnvFilter;
+use anyhow::Result;
+
+use rustproxy::RustProxy;
+use rustproxy::management;
+use rustproxy_config::RustProxyOptions;
+
+/// RustProxy - High-performance multi-protocol proxy
+#[derive(Parser, Debug)]
+#[command(name = "rustproxy", version, about)]
+struct Cli {
+    /// Path to JSON configuration file
+    #[arg(short, long, default_value = "config.json")]
+    config: String,
+
+    /// Log level (trace, debug, info, warn, error)
+    #[arg(short, long, default_value = "info")]
+    log_level: String,
+
+    /// Validate configuration without starting
+    #[arg(long)]
+    validate: bool,
+
+    /// Run in management mode (JSON-over-stdin IPC for TypeScript wrapper)
+    #[arg(long)]
+    management: bool,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Install the default CryptoProvider early, before any TLS or ACME code runs.
+    // This prevents panics from instant-acme/hyper-rustls calling ClientConfig::builder()
+    // before TLS listeners have started. Idempotent — later calls harmlessly return Err.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    let cli = Cli::parse();
+
+    // Initialize tracing - write to stderr so stdout is reserved for management IPC
+    tracing_subscriber::fmt()
+        .with_writer(std::io::stderr)
+        .with_env_filter(
+            EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| EnvFilter::new(&cli.log_level))
+        )
+        .init();
+
+    // Management mode: JSON IPC over stdin/stdout
+    if cli.management {
+        tracing::info!("RustProxy starting in management mode...");
+        return management::management_loop().await;
+    }
+
+    tracing::info!("RustProxy starting...");
+
+    // Load configuration
+    let options = RustProxyOptions::from_file(&cli.config)
+        .map_err(|e| anyhow::anyhow!("Failed to load config '{}': {}", cli.config, e))?;
+
+    tracing::info!(
+        "Loaded {} routes from {}",
+        options.routes.len(),
+        cli.config
+    );
+
+    // Validate-only mode
+    if cli.validate {
+        match rustproxy_config::validate_routes(&options.routes) {
+            Ok(()) => {
+                tracing::info!("Configuration is valid");
+                return Ok(());
+            }
+            Err(errors) => {
+                for err in &errors {
+                    tracing::error!("Validation error: {}", err);
+                }
+                anyhow::bail!("{} validation errors found", errors.len());
+            }
+        }
+    }
+
+    // Create and start proxy
+    let mut proxy = RustProxy::new(options)?;
+    proxy.start().await?;
+
+    // Wait for shutdown signal
+    tracing::info!("RustProxy is running. Press Ctrl+C to stop.");
+    tokio::signal::ctrl_c().await?;
+
+    tracing::info!("Shutdown signal received");
+    proxy.stop().await?;
+
+    tracing::info!("RustProxy shutdown complete");
+    Ok(())
+}

rust/crates/rustproxy/src/management.rs

@@ -0,0 +1,470 @@
+use anyhow::Result;
+use serde::{Deserialize, Serialize};
+use tokio::io::{AsyncBufReadExt, BufReader};
+use tracing::{info, error};
+
+use crate::RustProxy;
+use rustproxy_config::RustProxyOptions;
+
+/// A management request from the TypeScript wrapper.
+#[derive(Debug, Deserialize)]
+pub struct ManagementRequest {
+    pub id: String,
+    pub method: String,
+    #[serde(default)]
+    pub params: serde_json::Value,
+}
+
+/// A management response back to the TypeScript wrapper.
+#[derive(Debug, Serialize)]
+pub struct ManagementResponse {
+    pub id: String,
+    pub success: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub result: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<String>,
+}
+
+/// An unsolicited event from the proxy to the TypeScript wrapper.
+#[derive(Debug, Serialize)]
+pub struct ManagementEvent {
+    pub event: String,
+    pub data: serde_json::Value,
+}
+
+impl ManagementResponse {
+    fn ok(id: String, result: serde_json::Value) -> Self {
+        Self {
+            id,
+            success: true,
+            result: Some(result),
+            error: None,
+        }
+    }
+
+    fn err(id: String, message: String) -> Self {
+        Self {
+            id,
+            success: false,
+            result: None,
+            error: Some(message),
+        }
+    }
+}
+
+fn send_line(line: &str) {
+    // Use blocking stdout write - we're writing short JSON lines
+    use std::io::Write;
+    let stdout = std::io::stdout();
+    let mut handle = stdout.lock();
+    let _ = handle.write_all(line.as_bytes());
+    let _ = handle.write_all(b"\n");
+    let _ = handle.flush();
+}
+
+fn send_response(response: &ManagementResponse) {
+    match serde_json::to_string(response) {
+        Ok(json) => send_line(&json),
+        Err(e) => error!("Failed to serialize management response: {}", e),
+    }
+}
+
+fn send_event(event: &str, data: serde_json::Value) {
+    let evt = ManagementEvent {
+        event: event.to_string(),
+        data,
+    };
+    match serde_json::to_string(&evt) {
+        Ok(json) => send_line(&json),
+        Err(e) => error!("Failed to serialize management event: {}", e),
+    }
+}
+
+/// Run the management loop, reading JSON commands from stdin and writing responses to stdout.
+pub async fn management_loop() -> Result<()> {
+    let stdin = BufReader::new(tokio::io::stdin());
+    let mut lines = stdin.lines();
+    let mut proxy: Option<RustProxy> = None;
+
+    send_event("ready", serde_json::json!({}));
+
+    loop {
+        let line = match lines.next_line().await {
+            Ok(Some(line)) => line,
+            Ok(None) => {
+                // stdin closed - parent process exited
+                info!("Management stdin closed, shutting down");
+                if let Some(ref mut p) = proxy {
+                    let _ = p.stop().await;
+                }
+                break;
+            }
+            Err(e) => {
+                error!("Error reading management stdin: {}", e);
+                break;
+            }
+        };
+
+        let line = line.trim().to_string();
+        if line.is_empty() {
+            continue;
+        }
+
+        let request: ManagementRequest = match serde_json::from_str(&line) {
+            Ok(r) => r,
+            Err(e) => {
+                error!("Failed to parse management request: {}", e);
+                // Send error response without an ID
+                send_response(&ManagementResponse::err(
+                    "unknown".to_string(),
+                    format!("Failed to parse request: {}", e),
+                ));
+                continue;
+            }
+        };
+
+        let response = handle_request(&request, &mut proxy).await;
+        send_response(&response);
+    }
+
+    Ok(())
+}
+
+async fn handle_request(
+    request: &ManagementRequest,
+    proxy: &mut Option<RustProxy>,
+) -> ManagementResponse {
+    let id = request.id.clone();
+
+    match request.method.as_str() {
+        "start" => handle_start(&id, &request.params, proxy).await,
+        "stop" => handle_stop(&id, proxy).await,
+        "updateRoutes" => handle_update_routes(&id, &request.params, proxy).await,
+        "getMetrics" => handle_get_metrics(&id, proxy),
+        "getStatistics" => handle_get_statistics(&id, proxy),
+        "provisionCertificate" => handle_provision_certificate(&id, &request.params, proxy).await,
+        "renewCertificate" => handle_renew_certificate(&id, &request.params, proxy).await,
+        "getCertificateStatus" => handle_get_certificate_status(&id, &request.params, proxy).await,
+        "getListeningPorts" => handle_get_listening_ports(&id, proxy),
+        "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,
+        _ => ManagementResponse::err(id, format!("Unknown method: {}", request.method)),
+    }
+}
+
+async fn handle_start(
+    id: &str,
+    params: &serde_json::Value,
+    proxy: &mut Option<RustProxy>,
+) -> ManagementResponse {
+    if proxy.is_some() {
+        return ManagementResponse::err(id.to_string(), "Proxy is already running".to_string());
+    }
+
+    let config = match params.get("config") {
+        Some(config) => config,
+        None => return ManagementResponse::err(id.to_string(), "Missing 'config' parameter".to_string()),
+    };
+
+    let options: RustProxyOptions = match serde_json::from_value(config.clone()) {
+        Ok(o) => o,
+        Err(e) => return ManagementResponse::err(id.to_string(), format!("Invalid config: {}", e)),
+    };
+
+    match RustProxy::new(options) {
+        Ok(mut p) => {
+            match p.start().await {
+                Ok(()) => {
+                    send_event("started", serde_json::json!({}));
+                    *proxy = Some(p);
+                    ManagementResponse::ok(id.to_string(), serde_json::json!({}))
+                }
+                Err(e) => {
+                    send_event("error", serde_json::json!({"message": format!("{}", e)}));
+                    ManagementResponse::err(id.to_string(), format!("Failed to start: {}", e))
+                }
+            }
+        }
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to create proxy: {}", e)),
+    }
+}
+
+async fn handle_stop(
+    id: &str,
+    proxy: &mut Option<RustProxy>,
+) -> ManagementResponse {
+    match proxy.as_mut() {
+        Some(p) => {
+            match p.stop().await {
+                Ok(()) => {
+                    *proxy = None;
+                    send_event("stopped", serde_json::json!({}));
+                    ManagementResponse::ok(id.to_string(), serde_json::json!({}))
+                }
+                Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to stop: {}", e)),
+            }
+        }
+        None => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+    }
+}
+
+async fn handle_update_routes(
+    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 routes = match params.get("routes") {
+        Some(routes) => routes,
+        None => return ManagementResponse::err(id.to_string(), "Missing 'routes' parameter".to_string()),
+    };
+
+    let routes: Vec<rustproxy_config::RouteConfig> = match serde_json::from_value(routes.clone()) {
+        Ok(r) => r,
+        Err(e) => return ManagementResponse::err(id.to_string(), format!("Invalid routes: {}", e)),
+    };
+
+    match p.update_routes(routes).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to update routes: {}", e)),
+    }
+}
+
+fn handle_get_metrics(
+    id: &str,
+    proxy: &Option<RustProxy>,
+) -> ManagementResponse {
+    match proxy.as_ref() {
+        Some(p) => {
+            let metrics = p.get_metrics();
+            match serde_json::to_value(&metrics) {
+                Ok(v) => ManagementResponse::ok(id.to_string(), v),
+                Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to serialize metrics: {}", e)),
+            }
+        }
+        None => ManagementResponse::err(id.to_string(), "Proxy is not running".to_string()),
+    }
+}
+
+fn handle_get_statistics(
+    id: &str,
+    proxy: &Option<RustProxy>,
+) -> ManagementResponse {
+    match proxy.as_ref() {
+        Some(p) => {
+            let stats = p.get_statistics();
+            match serde_json::to_value(&stats) {
+                Ok(v) => ManagementResponse::ok(id.to_string(), v),
+                Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to serialize statistics: {}", e)),
+            }
+        }
+        None => ManagementResponse::err(id.to_string(), "Proxy is not running".to_string()),
+    }
+}
+
+async fn handle_provision_certificate(
+    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 route_name = match params.get("routeName").and_then(|v| v.as_str()) {
+        Some(name) => name.to_string(),
+        None => return ManagementResponse::err(id.to_string(), "Missing 'routeName' parameter".to_string()),
+    };
+
+    match p.provision_certificate(&route_name).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to provision certificate: {}", e)),
+    }
+}
+
+async fn handle_renew_certificate(
+    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 route_name = match params.get("routeName").and_then(|v| v.as_str()) {
+        Some(name) => name.to_string(),
+        None => return ManagementResponse::err(id.to_string(), "Missing 'routeName' parameter".to_string()),
+    };
+
+    match p.renew_certificate(&route_name).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to renew certificate: {}", e)),
+    }
+}
+
+async fn handle_get_certificate_status(
+    id: &str,
+    params: &serde_json::Value,
+    proxy: &Option<RustProxy>,
+) -> ManagementResponse {
+    let p = match proxy.as_ref() {
+        Some(p) => p,
+        None => return ManagementResponse::err(id.to_string(), "Proxy is not running".to_string()),
+    };
+
+    let route_name = match params.get("routeName").and_then(|v| v.as_str()) {
+        Some(name) => name,
+        None => return ManagementResponse::err(id.to_string(), "Missing 'routeName' parameter".to_string()),
+    };
+
+    match p.get_certificate_status(route_name).await {
+        Some(status) => ManagementResponse::ok(id.to_string(), serde_json::json!({
+            "domain": status.domain,
+            "source": status.source,
+            "expiresAt": status.expires_at,
+            "isValid": status.is_valid,
+        })),
+        None => ManagementResponse::ok(id.to_string(), serde_json::Value::Null),
+    }
+}
+
+fn handle_get_listening_ports(
+    id: &str,
+    proxy: &Option<RustProxy>,
+) -> ManagementResponse {
+    match proxy.as_ref() {
+        Some(p) => {
+            let ports = p.get_listening_ports();
+            ManagementResponse::ok(id.to_string(), serde_json::json!({ "ports": ports }))
+        }
+        None => ManagementResponse::ok(id.to_string(), serde_json::json!({ "ports": [] })),
+    }
+}
+
+async fn handle_set_socket_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!("setSocketHandlerRelay: socket_path={:?}", socket_path);
+    p.set_socket_handler_relay_path(socket_path);
+
+    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,
+    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 port = match params.get("port").and_then(|v| v.as_u64()) {
+        Some(port) => port as u16,
+        None => return ManagementResponse::err(id.to_string(), "Missing 'port' parameter".to_string()),
+    };
+
+    match p.add_listening_port(port).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to add port {}: {}", port, e)),
+    }
+}
+
+async fn handle_remove_listening_port(
+    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 port = match params.get("port").and_then(|v| v.as_u64()) {
+        Some(port) => port as u16,
+        None => return ManagementResponse::err(id.to_string(), "Missing 'port' parameter".to_string()),
+    };
+
+    match p.remove_listening_port(port).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to remove port {}: {}", port, e)),
+    }
+}
+
+async fn handle_load_certificate(
+    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 domain = match params.get("domain").and_then(|v| v.as_str()) {
+        Some(d) => d.to_string(),
+        None => return ManagementResponse::err(id.to_string(), "Missing 'domain' parameter".to_string()),
+    };
+
+    let cert = match params.get("cert").and_then(|v| v.as_str()) {
+        Some(c) => c.to_string(),
+        None => return ManagementResponse::err(id.to_string(), "Missing 'cert' parameter".to_string()),
+    };
+
+    let key = match params.get("key").and_then(|v| v.as_str()) {
+        Some(k) => k.to_string(),
+        None => return ManagementResponse::err(id.to_string(), "Missing 'key' parameter".to_string()),
+    };
+
+    let ca = params.get("ca").and_then(|v| v.as_str()).map(|s| s.to_string());
+
+    info!("loadCertificate: domain={}", domain);
+
+    // Load cert into cert manager and hot-swap TLS config
+    match p.load_certificate(&domain, cert, key, ca).await {
+        Ok(()) => ManagementResponse::ok(id.to_string(), serde_json::json!({})),
+        Err(e) => ManagementResponse::err(id.to_string(), format!("Failed to load certificate for {}: {}", domain, e)),
+    }
+}

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

@@ -0,0 +1,557 @@
+use std::sync::atomic::{AtomicU16, Ordering};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpListener;
+use tokio::task::JoinHandle;
+
+/// Atomic port allocator starting at 19000 to avoid collisions.
+static PORT_COUNTER: AtomicU16 = AtomicU16::new(19000);
+
+/// Get the next available port for testing.
+pub fn next_port() -> u16 {
+    PORT_COUNTER.fetch_add(1, Ordering::SeqCst)
+}
+
+/// Start a simple TCP echo server that echoes back whatever it receives.
+/// Returns the join handle for the server task.
+pub async fn start_echo_server(port: u16) -> JoinHandle<()> {
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .expect("Failed to bind echo server");
+
+    tokio::spawn(async move {
+        loop {
+            let (mut stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            tokio::spawn(async move {
+                let mut buf = vec![0u8; 65536];
+                loop {
+                    let n = match stream.read(&mut buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => n,
+                    };
+                    if stream.write_all(&buf[..n]).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+    })
+}
+
+/// Start a TCP echo server that prefixes responses to identify which backend responded.
+pub async fn start_prefix_echo_server(port: u16, prefix: &str) -> JoinHandle<()> {
+    let prefix = prefix.to_string();
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .expect("Failed to bind prefix echo server");
+
+    tokio::spawn(async move {
+        loop {
+            let (mut stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let pfx = prefix.clone();
+            tokio::spawn(async move {
+                let mut buf = vec![0u8; 65536];
+                loop {
+                    let n = match stream.read(&mut buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => n,
+                    };
+                    let mut response = pfx.as_bytes().to_vec();
+                    response.extend_from_slice(&buf[..n]);
+                    if stream.write_all(&response).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+    })
+}
+
+/// Start a simple HTTP server that responds with a fixed status and body.
+pub async fn start_http_server(port: u16, status: u16, body: &str) -> JoinHandle<()> {
+    let body = body.to_string();
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .expect("Failed to bind HTTP server");
+
+    tokio::spawn(async move {
+        loop {
+            let (mut stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let b = body.clone();
+            tokio::spawn(async move {
+                let mut buf = vec![0u8; 8192];
+                // Read the request
+                let _n = stream.read(&mut buf).await.unwrap_or(0);
+                // Send response
+                let response = format!(
+                    "HTTP/1.1 {} OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                    status,
+                    b.len(),
+                    b,
+                );
+                let _ = stream.write_all(response.as_bytes()).await;
+                let _ = stream.shutdown().await;
+            });
+        }
+    })
+}
+
+/// Start an HTTP backend server that echoes back request details as JSON.
+/// The response body contains: {"method":"GET","path":"/foo","host":"example.com","backend":"<name>"}
+/// Supports keep-alive by reading HTTP requests properly.
+pub async fn start_http_echo_backend(port: u16, backend_name: &str) -> JoinHandle<()> {
+    let name = backend_name.to_string();
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .unwrap_or_else(|_| panic!("Failed to bind HTTP echo backend on port {}", port));
+
+    tokio::spawn(async move {
+        loop {
+            let (mut stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let backend = name.clone();
+            tokio::spawn(async move {
+                let mut buf = vec![0u8; 16384];
+                // Read request data
+                let n = match stream.read(&mut buf).await {
+                    Ok(0) | Err(_) => return,
+                    Ok(n) => n,
+                };
+                let req_str = String::from_utf8_lossy(&buf[..n]);
+
+                // Parse first line: METHOD PATH HTTP/x.x
+                let first_line = req_str.lines().next().unwrap_or("");
+                let parts: Vec<&str> = first_line.split_whitespace().collect();
+                let method = parts.first().copied().unwrap_or("UNKNOWN");
+                let path = parts.get(1).copied().unwrap_or("/");
+
+                // Extract Host header
+                let host = req_str.lines()
+                    .find(|l| l.to_lowercase().starts_with("host:"))
+                    .map(|l| l[5..].trim())
+                    .unwrap_or("unknown");
+
+                let body = format!(
+                    r#"{{"method":"{}","path":"{}","host":"{}","backend":"{}"}}"#,
+                    method, path, host, backend
+                );
+
+                let response = format!(
+                    "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                    body.len(),
+                    body,
+                );
+                let _ = stream.write_all(response.as_bytes()).await;
+                let _ = stream.shutdown().await;
+            });
+        }
+    })
+}
+
+/// Wrap a future with a timeout, preventing tests from hanging.
+pub async fn with_timeout<F, T>(future: F, secs: u64) -> Result<T, &'static str>
+where
+    F: std::future::Future<Output = T>,
+{
+    match tokio::time::timeout(std::time::Duration::from_secs(secs), future).await {
+        Ok(result) => Ok(result),
+        Err(_) => Err("Test timed out"),
+    }
+}
+
+/// Wait briefly for a server to be ready by attempting TCP connections.
+pub async fn wait_for_port(port: u16, timeout_ms: u64) -> bool {
+    let start = std::time::Instant::now();
+    let timeout = std::time::Duration::from_millis(timeout_ms);
+    while start.elapsed() < timeout {
+        if tokio::net::TcpStream::connect(format!("127.0.0.1:{}", port))
+            .await
+            .is_ok()
+        {
+            return true;
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+    }
+    false
+}
+
+/// Start a TLS HTTP echo backend: accepts TLS, then responds with HTTP JSON
+/// containing request details. Combines TLS acceptance with HTTP echo behavior.
+pub async fn start_tls_http_backend(
+    port: u16,
+    backend_name: &str,
+    cert_pem: &str,
+    key_pem: &str,
+) -> JoinHandle<()> {
+    use std::sync::Arc;
+
+    // Use h1-only acceptor: test backends speak raw HTTP/1.1 text,
+    // so they must NOT advertise h2 via ALPN (which would cause
+    // auto-detect to attempt h2 binary framing and fail).
+    let acceptor = rustproxy_passthrough::build_tls_acceptor_h1_only(cert_pem, key_pem)
+        .expect("Failed to build TLS acceptor");
+    let acceptor = Arc::new(acceptor);
+    let name = backend_name.to_string();
+
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .unwrap_or_else(|_| panic!("Failed to bind TLS HTTP backend on port {}", port));
+
+    tokio::spawn(async move {
+        loop {
+            let (stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let acc = acceptor.clone();
+            let backend = name.clone();
+            tokio::spawn(async move {
+                let mut tls_stream = match acc.accept(stream).await {
+                    Ok(s) => s,
+                    Err(_) => return,
+                };
+
+                let mut buf = vec![0u8; 16384];
+                let n = match tls_stream.read(&mut buf).await {
+                    Ok(0) | Err(_) => return,
+                    Ok(n) => n,
+                };
+                let req_str = String::from_utf8_lossy(&buf[..n]);
+
+                // Parse first line: METHOD PATH HTTP/x.x
+                let first_line = req_str.lines().next().unwrap_or("");
+                let parts: Vec<&str> = first_line.split_whitespace().collect();
+                let method = parts.first().copied().unwrap_or("UNKNOWN");
+                let path = parts.get(1).copied().unwrap_or("/");
+
+                // Extract Host header
+                let host = req_str
+                    .lines()
+                    .find(|l| l.to_lowercase().starts_with("host:"))
+                    .map(|l| l[5..].trim())
+                    .unwrap_or("unknown");
+
+                let body = format!(
+                    r#"{{"method":"{}","path":"{}","host":"{}","backend":"{}"}}"#,
+                    method, path, host, backend
+                );
+
+                let response = format!(
+                    "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                    body.len(),
+                    body,
+                );
+                let _ = tls_stream.write_all(response.as_bytes()).await;
+                let _ = tls_stream.shutdown().await;
+            });
+        }
+    })
+}
+
+/// Helper to create a minimal route config for testing.
+pub fn make_test_route(
+    port: u16,
+    domain: Option<&str>,
+    target_host: &str,
+    target_port: u16,
+) -> rustproxy_config::RouteConfig {
+    rustproxy_config::RouteConfig {
+        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,
+            tls_version: None,
+            headers: None,
+            protocol: None,
+        },
+        action: rustproxy_config::RouteAction {
+            action_type: rustproxy_config::RouteActionType::Forward,
+            targets: Some(vec![rustproxy_config::RouteTarget {
+                target_match: None,
+                host: rustproxy_config::HostSpec::Single(target_host.to_string()),
+                port: rustproxy_config::PortSpec::Fixed(target_port),
+                tls: None,
+                websocket: None,
+                load_balancing: None,
+                send_proxy_protocol: None,
+                headers: None,
+                advanced: None,
+                backend_transport: None,
+                priority: None,
+            }]),
+            tls: None,
+            websocket: None,
+            load_balancing: None,
+            advanced: None,
+            options: None,
+            send_proxy_protocol: None,
+            udp: None,
+        },
+        headers: None,
+        security: None,
+        name: None,
+        description: None,
+        priority: None,
+        tags: None,
+        enabled: None,
+    }
+}
+
+/// Start a simple WebSocket echo backend.
+///
+/// Accepts WebSocket upgrade requests (HTTP Upgrade: websocket), sends 101 back,
+/// then echoes all data received on the connection.
+pub async fn start_ws_echo_backend(port: u16) -> JoinHandle<()> {
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .unwrap_or_else(|_| panic!("Failed to bind WS echo backend on port {}", port));
+
+    tokio::spawn(async move {
+        loop {
+            let (mut stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            tokio::spawn(async move {
+                // Read the HTTP upgrade request
+                let mut buf = vec![0u8; 4096];
+                let n = match stream.read(&mut buf).await {
+                    Ok(0) | Err(_) => return,
+                    Ok(n) => n,
+                };
+
+                let req_str = String::from_utf8_lossy(&buf[..n]);
+
+                // Extract Sec-WebSocket-Key for proper handshake
+                let ws_key = req_str.lines()
+                    .find(|l| l.to_lowercase().starts_with("sec-websocket-key:"))
+                    .map(|l| l.split(':').nth(1).unwrap_or("").trim().to_string())
+                    .unwrap_or_default();
+
+                // Compute Sec-WebSocket-Accept (simplified - just echo for test purposes)
+                // Real implementation would compute SHA-1 + base64
+                let accept_response = format!(
+                    "HTTP/1.1 101 Switching Protocols\r\n\
+                     Upgrade: websocket\r\n\
+                     Connection: Upgrade\r\n\
+                     Sec-WebSocket-Accept: {}\r\n\
+                     \r\n",
+                    ws_key
+                );
+
+                if stream.write_all(accept_response.as_bytes()).await.is_err() {
+                    return;
+                }
+
+                // Echo all data back (raw TCP after upgrade)
+                let mut echo_buf = vec![0u8; 65536];
+                loop {
+                    let n = match stream.read(&mut echo_buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => n,
+                    };
+                    if stream.write_all(&echo_buf[..n]).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+    })
+}
+
+/// Generate a self-signed certificate for testing using rcgen.
+/// Returns (cert_pem, key_pem).
+pub fn generate_self_signed_cert(domain: &str) -> (String, String) {
+    use rcgen::{CertificateParams, KeyPair};
+
+    let mut params = CertificateParams::new(vec![domain.to_string()]).unwrap();
+    params.distinguished_name.push(rcgen::DnType::CommonName, domain);
+
+    let key_pair = KeyPair::generate().unwrap();
+    let cert = params.self_signed(&key_pair).unwrap();
+
+    (cert.pem(), key_pair.serialize_pem())
+}
+
+/// Start a TLS echo server using the given cert/key.
+/// Returns the join handle.
+pub async fn start_tls_echo_server(port: u16, cert_pem: &str, key_pem: &str) -> JoinHandle<()> {
+    use std::sync::Arc;
+
+    let acceptor = rustproxy_passthrough::build_tls_acceptor(cert_pem, key_pem)
+        .expect("Failed to build TLS acceptor");
+    let acceptor = Arc::new(acceptor);
+
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .expect("Failed to bind TLS echo server");
+
+    tokio::spawn(async move {
+        loop {
+            let (stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let acc = acceptor.clone();
+            tokio::spawn(async move {
+                let mut tls_stream = match acc.accept(stream).await {
+                    Ok(s) => s,
+                    Err(_) => return,
+                };
+                let mut buf = vec![0u8; 65536];
+                loop {
+                    let n = match tls_stream.read(&mut buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => n,
+                    };
+                    if tls_stream.write_all(&buf[..n]).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+    })
+}
+
+/// Helper to create a TLS terminate route with static cert for testing.
+pub fn make_tls_terminate_route(
+    port: u16,
+    domain: &str,
+    target_host: &str,
+    target_port: u16,
+    cert_pem: &str,
+    key_pem: &str,
+) -> rustproxy_config::RouteConfig {
+    let mut route = make_test_route(port, Some(domain), target_host, target_port);
+    route.action.tls = Some(rustproxy_config::RouteTls {
+        mode: rustproxy_config::TlsMode::Terminate,
+        certificate: Some(rustproxy_config::CertificateSpec::Static(
+            rustproxy_config::CertificateConfig {
+                cert: cert_pem.to_string(),
+                key: key_pem.to_string(),
+                ca: None,
+                key_file: None,
+                cert_file: None,
+            },
+        )),
+        acme: None,
+        versions: None,
+        ciphers: None,
+        honor_cipher_order: None,
+        session_timeout: None,
+    });
+    route
+}
+
+/// Start a TLS WebSocket echo backend: accepts TLS, performs WS handshake, then echoes data.
+/// Combines TLS acceptance (like `start_tls_http_backend`) with WebSocket echo (like `start_ws_echo_backend`).
+pub async fn start_tls_ws_echo_backend(
+    port: u16,
+    cert_pem: &str,
+    key_pem: &str,
+) -> JoinHandle<()> {
+    use std::sync::Arc;
+
+    let acceptor = rustproxy_passthrough::build_tls_acceptor(cert_pem, key_pem)
+        .expect("Failed to build TLS acceptor");
+    let acceptor = Arc::new(acceptor);
+
+    let listener = TcpListener::bind(format!("127.0.0.1:{}", port))
+        .await
+        .unwrap_or_else(|_| panic!("Failed to bind TLS WS echo backend on port {}", port));
+
+    tokio::spawn(async move {
+        loop {
+            let (stream, _) = match listener.accept().await {
+                Ok(conn) => conn,
+                Err(_) => break,
+            };
+            let acc = acceptor.clone();
+            tokio::spawn(async move {
+                let mut tls_stream = match acc.accept(stream).await {
+                    Ok(s) => s,
+                    Err(_) => return,
+                };
+
+                // Read the HTTP upgrade request
+                let mut buf = vec![0u8; 4096];
+                let n = match tls_stream.read(&mut buf).await {
+                    Ok(0) | Err(_) => return,
+                    Ok(n) => n,
+                };
+
+                let req_str = String::from_utf8_lossy(&buf[..n]);
+
+                // Extract Sec-WebSocket-Key for handshake
+                let ws_key = req_str
+                    .lines()
+                    .find(|l| l.to_lowercase().starts_with("sec-websocket-key:"))
+                    .map(|l| l.split(':').nth(1).unwrap_or("").trim().to_string())
+                    .unwrap_or_default();
+
+                // Send 101 Switching Protocols
+                let accept_response = format!(
+                    "HTTP/1.1 101 Switching Protocols\r\n\
+                     Upgrade: websocket\r\n\
+                     Connection: Upgrade\r\n\
+                     Sec-WebSocket-Accept: {}\r\n\
+                     \r\n",
+                    ws_key
+                );
+
+                if tls_stream
+                    .write_all(accept_response.as_bytes())
+                    .await
+                    .is_err()
+                {
+                    return;
+                }
+
+                // Echo all data back (raw TCP after upgrade)
+                let mut echo_buf = vec![0u8; 65536];
+                loop {
+                    let n = match tls_stream.read(&mut echo_buf).await {
+                        Ok(0) | Err(_) => break,
+                        Ok(n) => n,
+                    };
+                    if tls_stream.write_all(&echo_buf[..n]).await.is_err() {
+                        break;
+                    }
+                }
+            });
+        }
+    })
+}
+
+/// Helper to create a TLS passthrough route for testing.
+pub fn make_tls_passthrough_route(
+    port: u16,
+    domain: Option<&str>,
+    target_host: &str,
+    target_port: u16,
+) -> rustproxy_config::RouteConfig {
+    let mut route = make_test_route(port, domain, target_host, target_port);
+    route.action.tls = Some(rustproxy_config::RouteTls {
+        mode: rustproxy_config::TlsMode::Passthrough,
+        certificate: None,
+        acme: None,
+        versions: None,
+        ciphers: None,
+        honor_cipher_order: None,
+        session_timeout: None,
+    });
+    route
+}

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,
+        ]
+    }
+}

rust/crates/rustproxy/tests/integration_http_proxy.rs

@@ -0,0 +1,752 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::RustProxyOptions;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+/// Send a raw HTTP request and return the full response as a string.
+async fn send_http_request(port: u16, host: &str, method: &str, path: &str) -> String {
+    let mut stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", port))
+        .await
+        .unwrap();
+
+    let request = format!(
+        "{} {} HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n\r\n",
+        method, path, host,
+    );
+    stream.write_all(request.as_bytes()).await.unwrap();
+
+    let mut response = Vec::new();
+    stream.read_to_end(&mut response).await.unwrap();
+    String::from_utf8_lossy(&response).to_string()
+}
+
+/// Extract the body from a raw HTTP response string (after the \r\n\r\n).
+fn extract_body(response: &str) -> &str {
+    response.split("\r\n\r\n").nth(1).unwrap_or("")
+}
+
+#[tokio::test]
+async fn test_http_forward_basic() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_http_echo_backend(backend_port, "main").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let response = send_http_request(proxy_port, "anyhost.com", "GET", "/hello").await;
+        let body = extract_body(&response);
+        body.to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(result.contains(r#""method":"GET"#), "Expected GET method, got: {}", result);
+    assert!(result.contains(r#""path":"/hello"#), "Expected /hello path, got: {}", result);
+    assert!(result.contains(r#""backend":"main"#), "Expected main backend, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_host_routing() {
+    let backend1_port = next_port();
+    let backend2_port = next_port();
+    let proxy_port = next_port();
+
+    let _b1 = start_http_echo_backend(backend1_port, "alpha").await;
+    let _b2 = start_http_echo_backend(backend2_port, "beta").await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_test_route(proxy_port, Some("alpha.example.com"), "127.0.0.1", backend1_port),
+            make_test_route(proxy_port, Some("beta.example.com"), "127.0.0.1", backend2_port),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Test alpha domain
+    let alpha_result = with_timeout(async {
+        let response = send_http_request(proxy_port, "alpha.example.com", "GET", "/").await;
+        extract_body(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(alpha_result.contains(r#""backend":"alpha"#), "Expected alpha backend, got: {}", alpha_result);
+
+    // Test beta domain
+    let beta_result = with_timeout(async {
+        let response = send_http_request(proxy_port, "beta.example.com", "GET", "/").await;
+        extract_body(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(beta_result.contains(r#""backend":"beta"#), "Expected beta backend, got: {}", beta_result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_path_routing() {
+    let backend1_port = next_port();
+    let backend2_port = next_port();
+    let proxy_port = next_port();
+
+    let _b1 = start_http_echo_backend(backend1_port, "api").await;
+    let _b2 = start_http_echo_backend(backend2_port, "web").await;
+
+    let mut api_route = make_test_route(proxy_port, None, "127.0.0.1", backend1_port);
+    api_route.route_match.path = Some("/api/**".to_string());
+    api_route.priority = Some(10);
+
+    let web_route = make_test_route(proxy_port, None, "127.0.0.1", backend2_port);
+
+    let options = RustProxyOptions {
+        routes: vec![api_route, web_route],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Test API path
+    let api_result = with_timeout(async {
+        let response = send_http_request(proxy_port, "any.com", "GET", "/api/users").await;
+        extract_body(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(api_result.contains(r#""backend":"api"#), "Expected api backend, got: {}", api_result);
+
+    // Test web path (no /api prefix)
+    let web_result = with_timeout(async {
+        let response = send_http_request(proxy_port, "any.com", "GET", "/index.html").await;
+        extract_body(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(web_result.contains(r#""backend":"web"#), "Expected web backend, got: {}", web_result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_cors_preflight() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_http_echo_backend(backend_port, "main").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        // Send CORS preflight request
+        let request = format!(
+            "OPTIONS /api/data HTTP/1.1\r\nHost: example.com\r\nOrigin: http://localhost:3000\r\nAccess-Control-Request-Method: POST\r\nConnection: close\r\n\r\n",
+        );
+        stream.write_all(request.as_bytes()).await.unwrap();
+
+        let mut response = Vec::new();
+        stream.read_to_end(&mut response).await.unwrap();
+        String::from_utf8_lossy(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    // Should get 204 No Content with CORS headers
+    assert!(result.contains("204"), "Expected 204 status, got: {}", result);
+    assert!(result.to_lowercase().contains("access-control-allow-origin"),
+        "Expected CORS header, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_backend_error() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    // Start an HTTP server that returns 500
+    let _backend = start_http_server(backend_port, 500, "Internal Error").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let response = send_http_request(proxy_port, "example.com", "GET", "/fail").await;
+        response
+    }, 10)
+    .await
+    .unwrap();
+
+    // Proxy should relay the 500 from backend
+    assert!(result.contains("500"), "Expected 500 status, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_no_route_matched() {
+    let proxy_port = next_port();
+
+    // Create a route only for a specific domain
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, Some("known.example.com"), "127.0.0.1", 9999)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let response = send_http_request(proxy_port, "unknown.example.com", "GET", "/").await;
+        response
+    }, 10)
+    .await
+    .unwrap();
+
+    // Should get 502 Bad Gateway (no route matched)
+    assert!(result.contains("502"), "Expected 502 status, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_http_forward_backend_unavailable() {
+    let proxy_port = next_port();
+    let dead_port = next_port(); // No server running here
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", dead_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let response = send_http_request(proxy_port, "example.com", "GET", "/").await;
+        response
+    }, 10)
+    .await
+    .unwrap();
+
+    // Should get 502 Bad Gateway (backend unavailable)
+    assert!(result.contains("502"), "Expected 502 status, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_https_terminate_http_forward() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "httpproxy.example.com";
+
+    let (cert_pem, key_pem) = generate_self_signed_cert(domain);
+    let _backend = start_http_echo_backend(backend_port, "tls-backend").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_tls_terminate_route(
+            proxy_port, domain, "127.0.0.1", backend_port, &cert_pem, &key_pem,
+        )],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let _ = rustls::crypto::ring::default_provider().install_default();
+        let tls_config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(std::sync::Arc::new(InsecureVerifier))
+            .with_no_client_auth();
+        let connector = tokio_rustls::TlsConnector::from(std::sync::Arc::new(tls_config));
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let server_name = rustls::pki_types::ServerName::try_from(domain.to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        // Send HTTP request through TLS
+        let request = format!(
+            "GET /api/data HTTP/1.1\r\nHost: {}\r\nConnection: close\r\n\r\n",
+            domain
+        );
+        tls_stream.write_all(request.as_bytes()).await.unwrap();
+
+        let mut response = Vec::new();
+        tls_stream.read_to_end(&mut response).await.unwrap();
+        String::from_utf8_lossy(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    let body = extract_body(&result);
+    assert!(body.contains(r#""method":"GET"#), "Expected GET, got: {}", body);
+    assert!(body.contains(r#""path":"/api/data"#), "Expected /api/data, got: {}", body);
+    assert!(body.contains(r#""backend":"tls-backend"#), "Expected tls-backend, got: {}", body);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_websocket_through_proxy() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_ws_echo_backend(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        // Send WebSocket upgrade request
+        let request = format!(
+            "GET /ws HTTP/1.1\r\n\
+             Host: example.com\r\n\
+             Upgrade: websocket\r\n\
+             Connection: Upgrade\r\n\
+             Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
+             Sec-WebSocket-Version: 13\r\n\
+             \r\n"
+        );
+        stream.write_all(request.as_bytes()).await.unwrap();
+
+        // Read the 101 response
+        let mut response_buf = Vec::with_capacity(4096);
+        let mut temp = [0u8; 1];
+        loop {
+            let n = stream.read(&mut temp).await.unwrap();
+            if n == 0 { break; }
+            response_buf.push(temp[0]);
+            if response_buf.len() >= 4 {
+                let len = response_buf.len();
+                if response_buf[len-4..] == *b"\r\n\r\n" {
+                    break;
+                }
+            }
+        }
+
+        let response_str = String::from_utf8_lossy(&response_buf).to_string();
+        assert!(response_str.contains("101"), "Expected 101 Switching Protocols, got: {}", response_str);
+        assert!(
+            response_str.to_lowercase().contains("upgrade: websocket"),
+            "Expected Upgrade header, got: {}",
+            response_str
+        );
+
+        // After upgrade, send data and verify echo
+        let test_data = b"Hello WebSocket!";
+        stream.write_all(test_data).await.unwrap();
+
+        // Read echoed data
+        let mut echo_buf = vec![0u8; 256];
+        let n = stream.read(&mut echo_buf).await.unwrap();
+        let echoed = &echo_buf[..n];
+
+        assert_eq!(echoed, test_data, "Expected echo of sent data");
+
+        "ok".to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert_eq!(result, "ok");
+    proxy.stop().await.unwrap();
+}
+
+/// Test that terminate-and-reencrypt mode routes HTTP traffic through the
+/// full HTTP proxy with per-request Host-based routing.
+///
+/// This verifies the new behavior: after TLS termination, HTTP data is detected
+/// and routed through HttpProxyService (like nginx) instead of being blindly tunneled.
+#[tokio::test]
+async fn test_terminate_and_reencrypt_http_routing() {
+    let backend1_port = next_port();
+    let backend2_port = next_port();
+    let proxy_port = next_port();
+
+    let (cert1, key1) = generate_self_signed_cert("alpha.example.com");
+    let (cert2, key2) = generate_self_signed_cert("beta.example.com");
+
+    // Generate separate backend certs (backends are independent TLS servers)
+    let (backend_cert1, backend_key1) = generate_self_signed_cert("localhost");
+    let (backend_cert2, backend_key2) = generate_self_signed_cert("localhost");
+
+    // Start TLS HTTP echo backends (proxy re-encrypts to these)
+    let _b1 = start_tls_http_backend(backend1_port, "alpha", &backend_cert1, &backend_key1).await;
+    let _b2 = start_tls_http_backend(backend2_port, "beta", &backend_cert2, &backend_key2).await;
+
+    // Create terminate-and-reencrypt routes
+    let mut route1 = make_tls_terminate_route(
+        proxy_port, "alpha.example.com", "127.0.0.1", backend1_port, &cert1, &key1,
+    );
+    route1.action.tls.as_mut().unwrap().mode = rustproxy_config::TlsMode::TerminateAndReencrypt;
+
+    let mut route2 = make_tls_terminate_route(
+        proxy_port, "beta.example.com", "127.0.0.1", backend2_port, &cert2, &key2,
+    );
+    route2.action.tls.as_mut().unwrap().mode = rustproxy_config::TlsMode::TerminateAndReencrypt;
+
+    let options = RustProxyOptions {
+        routes: vec![route1, route2],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Test alpha domain - HTTP request through TLS terminate-and-reencrypt
+    let alpha_result = with_timeout(async {
+        let _ = rustls::crypto::ring::default_provider().install_default();
+        let tls_config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(std::sync::Arc::new(InsecureVerifier))
+            .with_no_client_auth();
+        let connector = tokio_rustls::TlsConnector::from(std::sync::Arc::new(tls_config));
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let server_name = rustls::pki_types::ServerName::try_from("alpha.example.com".to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        let request = "GET /api/data HTTP/1.1\r\nHost: alpha.example.com\r\nConnection: close\r\n\r\n";
+        tls_stream.write_all(request.as_bytes()).await.unwrap();
+
+        let mut response = Vec::new();
+        tls_stream.read_to_end(&mut response).await.unwrap();
+        String::from_utf8_lossy(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    let alpha_body = extract_body(&alpha_result);
+    assert!(
+        alpha_body.contains(r#""backend":"alpha"#),
+        "Expected alpha backend, got: {}",
+        alpha_body
+    );
+    assert!(
+        alpha_body.contains(r#""method":"GET"#),
+        "Expected GET method, got: {}",
+        alpha_body
+    );
+    assert!(
+        alpha_body.contains(r#""path":"/api/data"#),
+        "Expected /api/data path, got: {}",
+        alpha_body
+    );
+    // Verify original Host header is preserved (not replaced with backend IP:port)
+    assert!(
+        alpha_body.contains(r#""host":"alpha.example.com"#),
+        "Expected original Host header alpha.example.com, got: {}",
+        alpha_body
+    );
+
+    // Test beta domain - different host goes to different backend
+    let beta_result = with_timeout(async {
+        let _ = rustls::crypto::ring::default_provider().install_default();
+        let tls_config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(std::sync::Arc::new(InsecureVerifier))
+            .with_no_client_auth();
+        let connector = tokio_rustls::TlsConnector::from(std::sync::Arc::new(tls_config));
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let server_name = rustls::pki_types::ServerName::try_from("beta.example.com".to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        let request = "GET /other HTTP/1.1\r\nHost: beta.example.com\r\nConnection: close\r\n\r\n";
+        tls_stream.write_all(request.as_bytes()).await.unwrap();
+
+        let mut response = Vec::new();
+        tls_stream.read_to_end(&mut response).await.unwrap();
+        String::from_utf8_lossy(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    let beta_body = extract_body(&beta_result);
+    assert!(
+        beta_body.contains(r#""backend":"beta"#),
+        "Expected beta backend, got: {}",
+        beta_body
+    );
+    assert!(
+        beta_body.contains(r#""path":"/other"#),
+        "Expected /other path, got: {}",
+        beta_body
+    );
+    // Verify original Host header is preserved for beta too
+    assert!(
+        beta_body.contains(r#""host":"beta.example.com"#),
+        "Expected original Host header beta.example.com, got: {}",
+        beta_body
+    );
+
+    proxy.stop().await.unwrap();
+}
+
+/// Test that WebSocket upgrade works through terminate-and-reencrypt mode.
+///
+/// Verifies the full chain: client→TLS→proxy terminates→re-encrypts→TLS→backend WebSocket.
+/// The proxy's `handle_websocket_upgrade` checks `upstream.use_tls` and calls
+/// `connect_tls_backend()` when true. This test covers that path.
+#[tokio::test]
+async fn test_terminate_and_reencrypt_websocket() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "ws.example.com";
+
+    // Frontend cert (client→proxy TLS)
+    let (frontend_cert, frontend_key) = generate_self_signed_cert(domain);
+    // Backend cert (proxy→backend TLS)
+    let (backend_cert, backend_key) = generate_self_signed_cert("localhost");
+
+    // Start TLS WebSocket echo backend
+    let _backend = start_tls_ws_echo_backend(backend_port, &backend_cert, &backend_key).await;
+
+    // Create terminate-and-reencrypt route
+    let mut route = make_tls_terminate_route(
+        proxy_port,
+        domain,
+        "127.0.0.1",
+        backend_port,
+        &frontend_cert,
+        &frontend_key,
+    );
+    route.action.tls.as_mut().unwrap().mode = rustproxy_config::TlsMode::TerminateAndReencrypt;
+
+    let options = RustProxyOptions {
+        routes: vec![route],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(
+        async {
+            let _ = rustls::crypto::ring::default_provider().install_default();
+            let tls_config = rustls::ClientConfig::builder()
+                .dangerous()
+                .with_custom_certificate_verifier(std::sync::Arc::new(InsecureVerifier))
+                .with_no_client_auth();
+            let connector =
+                tokio_rustls::TlsConnector::from(std::sync::Arc::new(tls_config));
+
+            let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+                .await
+                .unwrap();
+            let server_name =
+                rustls::pki_types::ServerName::try_from(domain.to_string()).unwrap();
+            let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+            // Send WebSocket upgrade request through TLS
+            let request = format!(
+                "GET /ws HTTP/1.1\r\n\
+                 Host: {}\r\n\
+                 Upgrade: websocket\r\n\
+                 Connection: Upgrade\r\n\
+                 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
+                 Sec-WebSocket-Version: 13\r\n\
+                 \r\n",
+                domain
+            );
+            tls_stream.write_all(request.as_bytes()).await.unwrap();
+
+            // Read the 101 response (byte-by-byte until \r\n\r\n)
+            let mut response_buf = Vec::with_capacity(4096);
+            let mut temp = [0u8; 1];
+            loop {
+                let n = tls_stream.read(&mut temp).await.unwrap();
+                if n == 0 {
+                    break;
+                }
+                response_buf.push(temp[0]);
+                if response_buf.len() >= 4 {
+                    let len = response_buf.len();
+                    if response_buf[len - 4..] == *b"\r\n\r\n" {
+                        break;
+                    }
+                }
+            }
+
+            let response_str = String::from_utf8_lossy(&response_buf).to_string();
+            assert!(
+                response_str.contains("101"),
+                "Expected 101 Switching Protocols, got: {}",
+                response_str
+            );
+            assert!(
+                response_str.to_lowercase().contains("upgrade: websocket"),
+                "Expected Upgrade header, got: {}",
+                response_str
+            );
+
+            // After upgrade, send data and verify echo
+            let test_data = b"Hello TLS WebSocket!";
+            tls_stream.write_all(test_data).await.unwrap();
+
+            // Read echoed data
+            let mut echo_buf = vec![0u8; 256];
+            let n = tls_stream.read(&mut echo_buf).await.unwrap();
+            let echoed = &echo_buf[..n];
+
+            assert_eq!(echoed, test_data, "Expected echo of sent data");
+
+            "ok".to_string()
+        },
+        10,
+    )
+    .await
+    .unwrap();
+
+    assert_eq!(result, "ok");
+    proxy.stop().await.unwrap();
+}
+
+/// Test that the protocol field on route config is accepted and processed.
+#[tokio::test]
+async fn test_protocol_field_in_route_config() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_http_echo_backend(backend_port, "main").await;
+
+    // Create a route with protocol: "http" - should only match HTTP traffic
+    let mut route = make_test_route(proxy_port, None, "127.0.0.1", backend_port);
+    route.route_match.protocol = Some("http".to_string());
+
+    let options = RustProxyOptions {
+        routes: vec![route],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // HTTP request should match the route and get proxied
+    let result = with_timeout(async {
+        let response = send_http_request(proxy_port, "example.com", "GET", "/test").await;
+        extract_body(&response).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(
+        result.contains(r#""backend":"main"#),
+        "Expected main backend, got: {}",
+        result
+    );
+    assert!(
+        result.contains(r#""path":"/test"#),
+        "Expected /test path, got: {}",
+        result
+    );
+
+    proxy.stop().await.unwrap();
+}
+
+/// InsecureVerifier for test TLS client connections.
+#[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,
+        ]
+    }
+}

rust/crates/rustproxy/tests/integration_proxy_lifecycle.rs

@@ -0,0 +1,250 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::RustProxyOptions;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+#[tokio::test]
+async fn test_start_and_stop() {
+    let port = next_port();
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port, None, "127.0.0.1", 8080)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+
+    // Not listening before start
+    assert!(!wait_for_port(port, 200).await);
+
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(port, 2000).await, "Port should be listening after start");
+
+    proxy.stop().await.unwrap();
+
+    // Give the OS a moment to release the port
+    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+    assert!(!wait_for_port(port, 200).await, "Port should not be listening after stop");
+}
+
+#[tokio::test]
+async fn test_double_start_fails() {
+    let port = next_port();
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port, None, "127.0.0.1", 8080)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+
+    // Second start should fail
+    let result = proxy.start().await;
+    assert!(result.is_err());
+    assert!(result.unwrap_err().to_string().contains("already started"));
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_update_routes_hot_reload() {
+    let port = next_port();
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port, Some("old.example.com"), "127.0.0.1", 8080)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+
+    // Update routes atomically
+    let new_routes = vec![
+        make_test_route(port, Some("new.example.com"), "127.0.0.1", 9090),
+    ];
+    let result = proxy.update_routes(new_routes).await;
+    assert!(result.is_ok());
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_add_remove_listening_port() {
+    let port1 = next_port();
+    let port2 = next_port();
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port1, None, "127.0.0.1", 8080)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(port1, 2000).await);
+
+    // Add a new port
+    proxy.add_listening_port(port2).await.unwrap();
+    assert!(wait_for_port(port2, 2000).await, "New port should be listening");
+
+    // Remove the port
+    proxy.remove_listening_port(port2).await.unwrap();
+    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+    assert!(!wait_for_port(port2, 200).await, "Removed port should not be listening");
+
+    // Original port should still be listening
+    assert!(wait_for_port(port1, 200).await, "Original port should still be listening");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_get_statistics() {
+    let port = next_port();
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port, None, "127.0.0.1", 8080)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+
+    let stats = proxy.get_statistics();
+    assert_eq!(stats.routes_count, 1);
+    assert!(stats.listening_ports.contains(&port));
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_invalid_routes_rejected() {
+    let options = RustProxyOptions {
+        routes: vec![{
+            let mut route = make_test_route(80, None, "127.0.0.1", 8080);
+            route.action.targets = None; // Invalid: forward without targets
+            route
+        }],
+        ..Default::default()
+    };
+
+    let result = RustProxy::new(options);
+    assert!(result.is_err());
+}
+
+#[tokio::test]
+async fn test_metrics_track_connections() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // No connections yet
+    let stats = proxy.get_statistics();
+    assert_eq!(stats.total_connections, 0);
+
+    // Make a connection and send data
+    {
+        let mut stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        stream.write_all(b"hello").await.unwrap();
+        let mut buf = vec![0u8; 16];
+        let _ = stream.read(&mut buf).await;
+    }
+
+    // Small delay for metrics to update
+    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+
+    let stats = proxy.get_statistics();
+    assert!(stats.total_connections > 0, "Expected total_connections > 0, got {}", stats.total_connections);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_metrics_track_bytes() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_http_echo_backend(backend_port, "metrics-test").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Send HTTP request through proxy
+    {
+        let mut stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let request = b"GET /test HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
+        stream.write_all(request).await.unwrap();
+        let mut response = Vec::new();
+        stream.read_to_end(&mut response).await.unwrap();
+        assert!(!response.is_empty(), "Expected non-empty response");
+    }
+
+    // Small delay for metrics to update
+    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+
+    let stats = proxy.get_statistics();
+    assert!(stats.total_connections > 0,
+        "Expected some connections tracked, got {}", stats.total_connections);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_hot_reload_port_changes() {
+    let port1 = next_port();
+    let port2 = next_port();
+    let backend_port = next_port();
+
+    let _backend = start_echo_server(backend_port).await;
+
+    // Start with port1
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(port1, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(port1, 2000).await);
+    assert!(!wait_for_port(port2, 200).await, "port2 should not be listening yet");
+
+    // Update routes to use port2 instead
+    let new_routes = vec![
+        make_test_route(port2, None, "127.0.0.1", backend_port),
+    ];
+    proxy.update_routes(new_routes).await.unwrap();
+
+    // Port2 should now be listening, port1 should be closed
+    assert!(wait_for_port(port2, 2000).await, "port2 should be listening after reload");
+    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+    assert!(!wait_for_port(port1, 200).await, "port1 should be closed after reload");
+
+    // Verify port2 works
+    let ports = proxy.get_listening_ports();
+    assert!(ports.contains(&port2), "Expected port2 in listening ports: {:?}", ports);
+    assert!(!ports.contains(&port1), "port1 should not be in listening ports: {:?}", ports);
+
+    proxy.stop().await.unwrap();
+}

rust/crates/rustproxy/tests/integration_tcp_passthrough.rs

@@ -0,0 +1,197 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::RustProxyOptions;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+
+#[tokio::test]
+async fn test_tcp_forward_echo() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    // Start echo backend
+    let _backend = start_echo_server(backend_port).await;
+
+    // Configure proxy
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+
+    // Wait for proxy to be ready
+    assert!(wait_for_port(proxy_port, 2000).await, "Proxy port not ready");
+
+    // Connect and send data
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        stream.write_all(b"hello world").await.unwrap();
+
+        let mut buf = vec![0u8; 1024];
+        let n = stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 5)
+    .await
+    .unwrap();
+
+    assert_eq!(result, "hello world");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tcp_forward_large_payload() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        // Send 1MB of data
+        let data = vec![b'A'; 1_000_000];
+        stream.write_all(&data).await.unwrap();
+        stream.shutdown().await.unwrap();
+
+        // Read all back
+        let mut received = Vec::new();
+        stream.read_to_end(&mut received).await.unwrap();
+        received.len()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert_eq!(result, 1_000_000);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tcp_forward_multiple_connections() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut handles = Vec::new();
+        for i in 0..10 {
+            let port = proxy_port;
+            handles.push(tokio::spawn(async move {
+                let mut stream = TcpStream::connect(format!("127.0.0.1:{}", port))
+                    .await
+                    .unwrap();
+                let msg = format!("connection-{}", i);
+                stream.write_all(msg.as_bytes()).await.unwrap();
+
+                let mut buf = vec![0u8; 1024];
+                let n = stream.read(&mut buf).await.unwrap();
+                String::from_utf8_lossy(&buf[..n]).to_string()
+            }));
+        }
+
+        let mut results = Vec::new();
+        for handle in handles {
+            results.push(handle.await.unwrap());
+        }
+        results
+    }, 10)
+    .await
+    .unwrap();
+
+    assert_eq!(result.len(), 10);
+    for (i, r) in result.iter().enumerate() {
+        assert_eq!(r, &format!("connection-{}", i));
+    }
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tcp_forward_backend_unreachable() {
+    let proxy_port = next_port();
+    let dead_port = next_port(); // No server on this port
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", dead_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Connection should complete (proxy accepts it) but data should not flow
+    let result = with_timeout(async {
+        let stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port)).await;
+        stream.is_ok()
+    }, 5)
+    .await
+    .unwrap();
+
+    assert!(result, "Should be able to connect to proxy even if backend is down");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tcp_forward_bidirectional() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    // Start a prefix echo server to verify data flows in both directions
+    let _backend = start_prefix_echo_server(backend_port, "REPLY:").await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_test_route(proxy_port, None, "127.0.0.1", backend_port)],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        stream.write_all(b"test data").await.unwrap();
+
+        let mut buf = vec![0u8; 1024];
+        let n = stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 5)
+    .await
+    .unwrap();
+
+    assert_eq!(result, "REPLY:test data");
+
+    proxy.stop().await.unwrap();
+}

rust/crates/rustproxy/tests/integration_tls_passthrough.rs

@@ -0,0 +1,247 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::RustProxyOptions;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+use tokio::net::TcpStream;
+
+/// Build a minimal TLS ClientHello with the given SNI domain.
+/// This is enough for the proxy's SNI parser to extract the domain.
+fn build_client_hello(domain: &str) -> Vec<u8> {
+    let domain_bytes = domain.as_bytes();
+    let sni_length = domain_bytes.len() as u16;
+
+    // Server Name extension (type 0x0000)
+    let mut sni_ext = Vec::new();
+    sni_ext.extend_from_slice(&[0x00, 0x00]); // extension type: server_name
+    let sni_list_len = sni_length + 5; // 2 (list len) + 1 (type) + 2 (name len) + name
+    sni_ext.extend_from_slice(&(sni_list_len as u16).to_be_bytes()); // extension data length
+    sni_ext.extend_from_slice(&((sni_list_len - 2) as u16).to_be_bytes()); // server name list length
+    sni_ext.push(0x00); // host_name type
+    sni_ext.extend_from_slice(&sni_length.to_be_bytes());
+    sni_ext.extend_from_slice(domain_bytes);
+
+    let extensions_length = sni_ext.len() as u16;
+
+    // ClientHello message
+    let mut client_hello = Vec::new();
+    client_hello.extend_from_slice(&[0x03, 0x03]); // TLS 1.2 version
+    client_hello.extend_from_slice(&[0x00; 32]); // random
+    client_hello.push(0x00); // session_id length
+    client_hello.extend_from_slice(&[0x00, 0x02, 0x00, 0xff]); // cipher suites (1 suite)
+    client_hello.extend_from_slice(&[0x01, 0x00]); // compression methods (null)
+    client_hello.extend_from_slice(&extensions_length.to_be_bytes());
+    client_hello.extend_from_slice(&sni_ext);
+
+    let hello_len = client_hello.len() as u32;
+
+    // Handshake wrapper (type 1 = ClientHello)
+    let mut handshake = Vec::new();
+    handshake.push(0x01); // ClientHello
+    handshake.extend_from_slice(&hello_len.to_be_bytes()[1..4]); // 3-byte length
+    handshake.extend_from_slice(&client_hello);
+
+    let hs_len = handshake.len() as u16;
+
+    // TLS record
+    let mut record = Vec::new();
+    record.push(0x16); // ContentType: Handshake
+    record.extend_from_slice(&[0x03, 0x01]); // TLS 1.0 (record version)
+    record.extend_from_slice(&hs_len.to_be_bytes());
+    record.extend_from_slice(&handshake);
+
+    record
+}
+
+#[tokio::test]
+async fn test_tls_passthrough_sni_routing() {
+    let backend1_port = next_port();
+    let backend2_port = next_port();
+    let proxy_port = next_port();
+
+    let _b1 = start_prefix_echo_server(backend1_port, "BACKEND1:").await;
+    let _b2 = start_prefix_echo_server(backend2_port, "BACKEND2:").await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_tls_passthrough_route(proxy_port, Some("one.example.com"), "127.0.0.1", backend1_port),
+            make_tls_passthrough_route(proxy_port, Some("two.example.com"), "127.0.0.1", backend2_port),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Send a fake ClientHello with SNI "one.example.com"
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let hello = build_client_hello("one.example.com");
+        stream.write_all(&hello).await.unwrap();
+
+        let mut buf = vec![0u8; 4096];
+        let n = stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 5)
+    .await
+    .unwrap();
+
+    // Backend1 should have received the ClientHello and prefixed its response
+    assert!(result.starts_with("BACKEND1:"), "Expected BACKEND1 prefix, got: {}", result);
+
+    // Now test routing to backend2
+    let result2 = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let hello = build_client_hello("two.example.com");
+        stream.write_all(&hello).await.unwrap();
+
+        let mut buf = vec![0u8; 4096];
+        let n = stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 5)
+    .await
+    .unwrap();
+
+    assert!(result2.starts_with("BACKEND2:"), "Expected BACKEND2 prefix, got: {}", result2);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_passthrough_unknown_sni() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_tls_passthrough_route(proxy_port, Some("known.example.com"), "127.0.0.1", backend_port),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Send ClientHello with unknown SNI - should get no response (connection dropped)
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let hello = build_client_hello("unknown.example.com");
+        stream.write_all(&hello).await.unwrap();
+
+        let mut buf = vec![0u8; 4096];
+        // Should either get 0 bytes (closed) or an error
+        match stream.read(&mut buf).await {
+            Ok(0) => true, // Connection closed = no route matched
+            Ok(_) => false, // Got data = route shouldn't have matched
+            Err(_) => true, // Error = connection dropped
+        }
+    }, 5)
+    .await
+    .unwrap();
+
+    assert!(result, "Unknown SNI should result in dropped connection");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_passthrough_wildcard_domain() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+
+    let _backend = start_prefix_echo_server(backend_port, "WILDCARD:").await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_tls_passthrough_route(proxy_port, Some("*.example.com"), "127.0.0.1", backend_port),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Should match any subdomain of example.com
+    let result = with_timeout(async {
+        let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+        let hello = build_client_hello("anything.example.com");
+        stream.write_all(&hello).await.unwrap();
+
+        let mut buf = vec![0u8; 4096];
+        let n = stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 5)
+    .await
+    .unwrap();
+
+    assert!(result.starts_with("WILDCARD:"), "Expected WILDCARD prefix, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_passthrough_multiple_domains() {
+    let b1_port = next_port();
+    let b2_port = next_port();
+    let b3_port = next_port();
+    let proxy_port = next_port();
+
+    let _b1 = start_prefix_echo_server(b1_port, "B1:").await;
+    let _b2 = start_prefix_echo_server(b2_port, "B2:").await;
+    let _b3 = start_prefix_echo_server(b3_port, "B3:").await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_tls_passthrough_route(proxy_port, Some("alpha.example.com"), "127.0.0.1", b1_port),
+            make_tls_passthrough_route(proxy_port, Some("beta.example.com"), "127.0.0.1", b2_port),
+            make_tls_passthrough_route(proxy_port, Some("gamma.example.com"), "127.0.0.1", b3_port),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    for (domain, expected_prefix) in [
+        ("alpha.example.com", "B1:"),
+        ("beta.example.com", "B2:"),
+        ("gamma.example.com", "B3:"),
+    ] {
+        let result = with_timeout(async {
+            let mut stream = TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+                .await
+                .unwrap();
+            let hello = build_client_hello(domain);
+            stream.write_all(&hello).await.unwrap();
+
+            let mut buf = vec![0u8; 4096];
+            let n = stream.read(&mut buf).await.unwrap();
+            String::from_utf8_lossy(&buf[..n]).to_string()
+        }, 5)
+        .await
+        .unwrap();
+
+        assert!(
+            result.starts_with(expected_prefix),
+            "Domain {} should route to {}, got: {}",
+            domain, expected_prefix, result
+        );
+    }
+
+    proxy.stop().await.unwrap();
+}

rust/crates/rustproxy/tests/integration_tls_terminate.rs

@@ -0,0 +1,324 @@
+mod common;
+
+use common::*;
+use rustproxy::RustProxy;
+use rustproxy_config::RustProxyOptions;
+use std::sync::Arc;
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+/// Create a rustls client config that trusts self-signed certs.
+fn make_insecure_tls_client_config() -> Arc<rustls::ClientConfig> {
+    let _ = rustls::crypto::ring::default_provider().install_default();
+    let config = rustls::ClientConfig::builder()
+        .dangerous()
+        .with_custom_certificate_verifier(Arc::new(InsecureVerifier))
+        .with_no_client_auth();
+    Arc::new(config)
+}
+
+#[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,
+        ]
+    }
+}
+
+#[tokio::test]
+async fn test_tls_terminate_basic() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "test.example.com";
+
+    // Generate self-signed cert
+    let (cert_pem, key_pem) = generate_self_signed_cert(domain);
+
+    // Start plain TCP echo backend (proxy terminates TLS, sends plain to backend)
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_tls_terminate_route(
+            proxy_port, domain, "127.0.0.1", backend_port, &cert_pem, &key_pem,
+        )],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Connect with TLS client
+    let result = with_timeout(async {
+        let tls_config = make_insecure_tls_client_config();
+        let connector = tokio_rustls::TlsConnector::from(tls_config);
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        let server_name = rustls::pki_types::ServerName::try_from(domain.to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        tls_stream.write_all(b"hello TLS").await.unwrap();
+
+        let mut buf = vec![0u8; 1024];
+        let n = tls_stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert_eq!(result, "hello TLS");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_terminate_and_reencrypt() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "reencrypt.example.com";
+    let backend_domain = "backend.internal";
+
+    // Generate certs
+    let (proxy_cert, proxy_key) = generate_self_signed_cert(domain);
+    let (backend_cert, backend_key) = generate_self_signed_cert(backend_domain);
+
+    // Start TLS echo backend
+    let _backend = start_tls_echo_server(backend_port, &backend_cert, &backend_key).await;
+
+    // Create terminate-and-reencrypt route
+    let mut route = make_tls_terminate_route(
+        proxy_port, domain, "127.0.0.1", backend_port, &proxy_cert, &proxy_key,
+    );
+    route.action.tls.as_mut().unwrap().mode = rustproxy_config::TlsMode::TerminateAndReencrypt;
+
+    let options = RustProxyOptions {
+        routes: vec![route],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let tls_config = make_insecure_tls_client_config();
+        let connector = tokio_rustls::TlsConnector::from(tls_config);
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        let server_name = rustls::pki_types::ServerName::try_from(domain.to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        tls_stream.write_all(b"hello reencrypt").await.unwrap();
+
+        let mut buf = vec![0u8; 1024];
+        let n = tls_stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert_eq!(result, "hello reencrypt");
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_terminate_sni_cert_selection() {
+    let backend1_port = next_port();
+    let backend2_port = next_port();
+    let proxy_port = next_port();
+
+    let (cert1, key1) = generate_self_signed_cert("alpha.example.com");
+    let (cert2, key2) = generate_self_signed_cert("beta.example.com");
+
+    let _b1 = start_prefix_echo_server(backend1_port, "ALPHA:").await;
+    let _b2 = start_prefix_echo_server(backend2_port, "BETA:").await;
+
+    let options = RustProxyOptions {
+        routes: vec![
+            make_tls_terminate_route(proxy_port, "alpha.example.com", "127.0.0.1", backend1_port, &cert1, &key1),
+            make_tls_terminate_route(proxy_port, "beta.example.com", "127.0.0.1", backend2_port, &cert2, &key2),
+        ],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    // Test alpha domain
+    let result = with_timeout(async {
+        let tls_config = make_insecure_tls_client_config();
+        let connector = tokio_rustls::TlsConnector::from(tls_config);
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        let server_name = rustls::pki_types::ServerName::try_from("alpha.example.com".to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        tls_stream.write_all(b"test").await.unwrap();
+
+        let mut buf = vec![0u8; 1024];
+        let n = tls_stream.read(&mut buf).await.unwrap();
+        String::from_utf8_lossy(&buf[..n]).to_string()
+    }, 10)
+    .await
+    .unwrap();
+
+    assert!(result.starts_with("ALPHA:"), "Expected ALPHA prefix, got: {}", result);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_terminate_large_payload() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "large.example.com";
+
+    let (cert_pem, key_pem) = generate_self_signed_cert(domain);
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_tls_terminate_route(
+            proxy_port, domain, "127.0.0.1", backend_port, &cert_pem, &key_pem,
+        )],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let tls_config = make_insecure_tls_client_config();
+        let connector = tokio_rustls::TlsConnector::from(tls_config);
+
+        let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", proxy_port))
+            .await
+            .unwrap();
+
+        let server_name = rustls::pki_types::ServerName::try_from(domain.to_string()).unwrap();
+        let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+        // Send 1MB of data
+        let data = vec![b'X'; 1_000_000];
+        tls_stream.write_all(&data).await.unwrap();
+        tls_stream.shutdown().await.unwrap();
+
+        let mut received = Vec::new();
+        tls_stream.read_to_end(&mut received).await.unwrap();
+        received.len()
+    }, 15)
+    .await
+    .unwrap();
+
+    assert_eq!(result, 1_000_000);
+
+    proxy.stop().await.unwrap();
+}
+
+#[tokio::test]
+async fn test_tls_terminate_concurrent() {
+    let backend_port = next_port();
+    let proxy_port = next_port();
+    let domain = "concurrent.example.com";
+
+    let (cert_pem, key_pem) = generate_self_signed_cert(domain);
+    let _backend = start_echo_server(backend_port).await;
+
+    let options = RustProxyOptions {
+        routes: vec![make_tls_terminate_route(
+            proxy_port, domain, "127.0.0.1", backend_port, &cert_pem, &key_pem,
+        )],
+        ..Default::default()
+    };
+
+    let mut proxy = RustProxy::new(options).unwrap();
+    proxy.start().await.unwrap();
+    assert!(wait_for_port(proxy_port, 2000).await);
+
+    let result = with_timeout(async {
+        let mut handles = Vec::new();
+        for i in 0..10 {
+            let port = proxy_port;
+            let dom = domain.to_string();
+            handles.push(tokio::spawn(async move {
+                let tls_config = make_insecure_tls_client_config();
+                let connector = tokio_rustls::TlsConnector::from(tls_config);
+
+                let stream = tokio::net::TcpStream::connect(format!("127.0.0.1:{}", port))
+                    .await
+                    .unwrap();
+
+                let server_name = rustls::pki_types::ServerName::try_from(dom).unwrap();
+                let mut tls_stream = connector.connect(server_name, stream).await.unwrap();
+
+                let msg = format!("conn-{}", i);
+                tls_stream.write_all(msg.as_bytes()).await.unwrap();
+
+                let mut buf = vec![0u8; 1024];
+                let n = tls_stream.read(&mut buf).await.unwrap();
+                String::from_utf8_lossy(&buf[..n]).to_string()
+            }));
+        }
+
+        let mut results = Vec::new();
+        for handle in handles {
+            results.push(handle.await.unwrap());
+        }
+        results
+    }, 15)
+    .await
+    .unwrap();
+
+    assert_eq!(result.len(), 10);
+    for (i, r) in result.iter().enumerate() {
+        assert_eq!(r, &format!("conn-{}", i));
+    }
+
+    proxy.stop().await.unwrap();
+}

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/helpers/port-allocator.ts

@@ -0,0 +1,70 @@
+import * as net from 'net';
+
+/**
+ * Finds `count` free ports by binding to port 0 and reading the OS-assigned port.
+ * All servers are opened simultaneously to guarantee uniqueness.
+ * Returns an array of guaranteed-free ports.
+ */
+export async function findFreePorts(count: number): Promise<number[]> {
+  const servers: net.Server[] = [];
+  const ports: number[] = [];
+
+  // Open all servers simultaneously on port 0
+  await Promise.all(
+    Array.from({ length: count }, () =>
+      new Promise<void>((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+          const addr = server.address() as net.AddressInfo;
+          ports.push(addr.port);
+          servers.push(server);
+          resolve();
+        });
+        server.on('error', reject);
+      })
+    )
+  );
+
+  // Close all servers
+  await Promise.all(
+    servers.map(
+      (server) => new Promise<void>((resolve) => server.close(() => resolve()))
+    )
+  );
+
+  return ports;
+}
+
+/**
+ * Verifies that all given ports are free (not listening).
+ * Useful as a cleanup assertion at the end of tests.
+ * Throws if any port is still in use.
+ */
+export async function assertPortsFree(ports: number[]): Promise<void> {
+  const results = await Promise.all(
+    ports.map(
+      (port) =>
+        new Promise<{ port: number; free: boolean }>((resolve) => {
+          const client = net.connect({ port, host: '127.0.0.1' });
+          client.on('connect', () => {
+            client.destroy();
+            resolve({ port, free: false });
+          });
+          client.on('error', () => {
+            resolve({ port, free: true });
+          });
+          client.setTimeout(1000, () => {
+            client.destroy();
+            resolve({ port, free: true });
+          });
+        })
+    )
+  );
+
+  const occupied = results.filter((r) => !r.free);
+  if (occupied.length > 0) {
+    throw new Error(
+      `Ports still in use after cleanup: ${occupied.map((r) => r.port).join(', ')}`
+    );
+  }
+}

test/test.acme-http-challenge.ts

@@ -1,13 +1,37 @@
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import * as plugins from '../ts/plugins.js';
+import * as http from 'http';
 import { SmartProxy, SocketHandlers } from '../ts/index.js';
 
+/**
+ * Helper to make HTTP requests using Node's http module (unlike fetch/undici,
+ * http.request doesn't keep the event loop alive via a connection pool).
+ */
+function httpRequest(url: string, options: { method?: string; headers?: Record<string, string> } = {}): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: string }> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const req = http.request({
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname + parsed.search,
+      method: options.method || 'GET',
+      headers: options.headers,
+    }, (res) => {
+      let body = '';
+      res.on('data', (chunk: Buffer) => { body += chunk.toString(); });
+      res.on('end', () => resolve({ status: res.statusCode!, headers: res.headers, body }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
 tap.test('should handle HTTP requests on port 80 for ACME challenges', async (tools) => {
   tools.timeout(10000);
-  
+
   // Track HTTP requests that are handled
   const handledRequests: any[] = [];
-  
+
   const settings = {
     routes: [
       {
@@ -24,7 +48,7 @@ tap.test('should handle HTTP requests on port 80 for ACME challenges', async (to
               method: req.method,
               headers: req.headers
             });
-            
+
             // Simulate ACME challenge response
             const token = req.url?.split('/').pop() || '';
             res.header('Content-Type', 'text/plain');
@@ -34,40 +58,31 @@ tap.test('should handle HTTP requests on port 80 for ACME challenges', async (to
       }
     ]
   };
-  
+
   const proxy = new SmartProxy(settings);
-  
-  // Mock NFTables manager
-  (proxy as any).nftablesManager = {
-    ensureNFTablesSetup: async () => {},
-    stop: async () => {}
-  };
-  
+
   await proxy.start();
-  
+
   // Make an HTTP request to the challenge endpoint
-  const response = await fetch('http://localhost:18080/.well-known/acme-challenge/test-token', {
-    method: 'GET'
-  });
-  
+  const response = await httpRequest('http://localhost:18080/.well-known/acme-challenge/test-token');
+
   // Verify response
   expect(response.status).toEqual(200);
-  const body = await response.text();
-  expect(body).toEqual('challenge-response-for-test-token');
-  
+  expect(response.body).toEqual('challenge-response-for-test-token');
+
   // Verify request was handled
   expect(handledRequests.length).toEqual(1);
   expect(handledRequests[0].path).toEqual('/.well-known/acme-challenge/test-token');
   expect(handledRequests[0].method).toEqual('GET');
-  
+
   await proxy.stop();
 });
 
 tap.test('should parse HTTP headers correctly', async (tools) => {
   tools.timeout(10000);
-  
+
   const capturedContext: any = {};
-  
+
   const settings = {
     routes: [
       {
@@ -92,36 +107,30 @@ tap.test('should parse HTTP headers correctly', async (tools) => {
       }
     ]
   };
-  
+
   const proxy = new SmartProxy(settings);
-  
-  // Mock NFTables manager
-  (proxy as any).nftablesManager = {
-    ensureNFTablesSetup: async () => {},
-    stop: async () => {}
-  };
-  
+
   await proxy.start();
-  
+
   // Make request with custom headers
-  const response = await fetch('http://localhost:18081/test', {
+  const response = await httpRequest('http://localhost:18081/test', {
     method: 'POST',
     headers: {
       'X-Custom-Header': 'test-value',
       'User-Agent': 'test-agent'
     }
   });
-  
+
   expect(response.status).toEqual(200);
-  const body = await response.json();
-  
+  const body = JSON.parse(response.body);
+
   // Verify headers were parsed correctly
   expect(capturedContext.headers['x-custom-header']).toEqual('test-value');
   expect(capturedContext.headers['user-agent']).toEqual('test-agent');
   expect(capturedContext.method).toEqual('POST');
   expect(capturedContext.path).toEqual('/test');
-  
+
   await proxy.stop();
 });
 
-export default tap.start();
+export default tap.start();

test/test.acme-http01-challenge.ts

@@ -1,9 +1,12 @@
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import { SmartProxy, SocketHandlers } from '../ts/index.js';
 import * as net from 'net';
+import { findFreePorts, assertPortsFree } from './helpers/port-allocator.js';
 
 // Test that HTTP-01 challenges are properly processed when the initial data arrives
 tap.test('should correctly handle HTTP-01 challenge requests with initial data chunk', async (tapTest) => {
+  const [PORT] = await findFreePorts(1);
+
   // Prepare test data
   const challengeToken = 'test-acme-http01-challenge-token';
   const challengeResponse = 'mock-response-for-challenge';
@@ -37,7 +40,7 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
     routes: [{
       name: 'acme-challenge-route',
       match: {
-        ports: 8080,
+        ports: PORT,
         path: '/.well-known/acme-challenge/*'
       },
       action: {
@@ -60,7 +63,7 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
   
   // Connect to the proxy and send the HTTP-01 challenge request
   await new Promise<void>((resolve, reject) => {
-    testClient.connect(8080, 'localhost', () => {
+    testClient.connect(PORT, 'localhost', () => {
       // Send HTTP request for the challenge token
       testClient.write(
         `GET ${challengePath} HTTP/1.1\r\n` +
@@ -86,10 +89,13 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
   // Cleanup
   testClient.destroy();
   await proxy.stop();
+  await assertPortsFree([PORT]);
 });
 
 // Test that non-existent challenge tokens return 404
 tap.test('should return 404 for non-existent challenge tokens', async (tapTest) => {
+  const [PORT] = await findFreePorts(1);
+
   // Create a socket handler that behaves like a real ACME handler
   const acmeHandler = SocketHandlers.httpServer((req, res) => {
     if (req.url?.startsWith('/.well-known/acme-challenge/')) {
@@ -113,7 +119,7 @@ tap.test('should return 404 for non-existent challenge tokens', async (tapTest)
     routes: [{
       name: 'acme-challenge-route',
       match: {
-        ports: 8081,
+        ports: PORT,
         path: '/.well-known/acme-challenge/*'
       },
       action: {
@@ -135,7 +141,7 @@ tap.test('should return 404 for non-existent challenge tokens', async (tapTest)
   
   // Connect and send a request for a non-existent token
   await new Promise<void>((resolve, reject) => {
-    testClient.connect(8081, 'localhost', () => {
+    testClient.connect(PORT, 'localhost', () => {
       testClient.write(
         'GET /.well-known/acme-challenge/invalid-token HTTP/1.1\r\n' +
         'Host: test.example.com\r\n' +
@@ -157,6 +163,7 @@ tap.test('should return 404 for non-existent challenge tokens', async (tapTest)
   // Cleanup
   testClient.destroy();
   await proxy.stop();
+  await assertPortsFree([PORT]);
 });
 
 export default tap.start();

test/test.acme-route-creation.ts

@@ -1,218 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { SmartProxy } from '../ts/index.js';
-import * as plugins from '../ts/plugins.js';
-
-/**
- * Test that verifies ACME challenge routes are properly created
- */
-tap.test('should create ACME challenge route', async (tools) => {
-  tools.timeout(5000);
-  
-  // Create a challenge route manually to test its structure
-  const challengeRoute = {
-    name: 'acme-challenge',
-    priority: 1000,
-    match: {
-      ports: 18080,
-      path: '/.well-known/acme-challenge/*'
-    },
-    action: {
-      type: 'socket-handler' as const,
-      socketHandler: (socket: any, context: any) => {
-        socket.once('data', (data: Buffer) => {
-          const request = data.toString();
-          const lines = request.split('\r\n');
-          const [method, path] = lines[0].split(' ');
-          const token = path?.split('/').pop() || '';
-          
-          const response = [
-            'HTTP/1.1 200 OK',
-            'Content-Type: text/plain',
-            `Content-Length: ${token.length}`,
-            'Connection: close',
-            '',
-            token
-          ].join('\r\n');
-          
-          socket.write(response);
-          socket.end();
-        });
-      }
-    }
-  };
-  
-  // Test that the challenge route has the correct structure
-  expect(challengeRoute).toBeDefined();
-  expect(challengeRoute.match.path).toEqual('/.well-known/acme-challenge/*');
-  expect(challengeRoute.match.ports).toEqual(18080);
-  expect(challengeRoute.action.type).toEqual('socket-handler');
-  expect(challengeRoute.priority).toEqual(1000);
-  
-  // Create a proxy with the challenge route
-  const settings = {
-    routes: [
-      {
-        name: 'secure-route',
-        match: {
-          ports: [18443],
-          domains: 'test.local'
-        },
-        action: {
-          type: 'forward' as const,
-          targets: [{ host: 'localhost', port: 8080 }]
-        }
-      },
-      challengeRoute
-    ]
-  };
-  
-  const proxy = new SmartProxy(settings);
-  
-  // Mock NFTables manager
-  (proxy as any).nftablesManager = {
-    ensureNFTablesSetup: async () => {},
-    stop: async () => {}
-  };
-  
-  // Mock certificate manager to prevent real ACME initialization
-  (proxy as any).createCertificateManager = async function() {
-    return {
-      setUpdateRoutesCallback: () => {},
-      setHttpProxy: () => {},
-      setGlobalAcmeDefaults: () => {},
-      setAcmeStateManager: () => {},
-      initialize: async () => {},
-      provisionAllCertificates: async () => {},
-      stop: async () => {},
-      getAcmeOptions: () => ({}),
-      getState: () => ({ challengeRouteActive: false })
-    };
-  };
-  
-  await proxy.start();
-  
-  // Verify the challenge route is in the proxy's routes
-  const proxyRoutes = proxy.routeManager.getRoutes();
-  const foundChallengeRoute = proxyRoutes.find((r: any) => r.name === 'acme-challenge');
-  
-  expect(foundChallengeRoute).toBeDefined();
-  expect(foundChallengeRoute?.match.path).toEqual('/.well-known/acme-challenge/*');
-  
-  await proxy.stop();
-});
-
-tap.test('should handle HTTP request parsing correctly', async (tools) => {
-  tools.timeout(5000);
-  
-  let handlerCalled = false;
-  let receivedContext: any;
-  let parsedRequest: any = {};
-  
-  const settings = {
-    routes: [
-      {
-        name: 'test-static',
-        match: {
-          ports: [18090],
-          path: '/test/*'
-        },
-        action: {
-          type: 'socket-handler' as const,
-          socketHandler: (socket, context) => {
-            handlerCalled = true;
-            receivedContext = context;
-            
-            // Parse HTTP request from socket
-            socket.once('data', (data) => {
-              const request = data.toString();
-              const lines = request.split('\r\n');
-              const [method, path, protocol] = lines[0].split(' ');
-              
-              // Parse headers
-              const headers: any = {};
-              for (let i = 1; i < lines.length; i++) {
-                if (lines[i] === '') break;
-                const [key, value] = lines[i].split(': ');
-                if (key && value) {
-                  headers[key.toLowerCase()] = value;
-                }
-              }
-              
-              // Store parsed request data
-              parsedRequest = { method, path, headers };
-              
-              // Send HTTP response
-              const response = [
-                'HTTP/1.1 200 OK',
-                'Content-Type: text/plain',
-                'Content-Length: 2',
-                'Connection: close',
-                '',
-                'OK'
-              ].join('\r\n');
-              
-              socket.write(response);
-              socket.end();
-            });
-          }
-        }
-      }
-    ]
-  };
-  
-  const proxy = new SmartProxy(settings);
-  
-  // Mock NFTables manager
-  (proxy as any).nftablesManager = {
-    ensureNFTablesSetup: async () => {},
-    stop: async () => {}
-  };
-  
-  await proxy.start();
-  
-  // Create a simple HTTP request
-  const client = new plugins.net.Socket();
-  
-  await new Promise<void>((resolve, reject) => {
-    client.connect(18090, 'localhost', () => {
-      // Send HTTP request
-      const request = [
-        'GET /test/example HTTP/1.1',
-        'Host: localhost:18090',
-        'User-Agent: test-client',
-        '',
-        ''
-      ].join('\r\n');
-      
-      client.write(request);
-      
-      // Wait for response
-      client.on('data', (data) => {
-        const response = data.toString();
-        expect(response).toContain('HTTP/1.1 200');
-        expect(response).toContain('OK');
-        client.end();
-        resolve();
-      });
-    });
-    
-    client.on('error', reject);
-  });
-  
-  // Verify handler was called
-  expect(handlerCalled).toBeTrue();
-  expect(receivedContext).toBeDefined();
-  
-  // The context passed to socket handlers is IRouteContext, not HTTP request data
-  expect(receivedContext.port).toEqual(18090);
-  expect(receivedContext.routeName).toEqual('test-static');
-  
-  // Verify the parsed HTTP request data
-  expect(parsedRequest.path).toEqual('/test/example');
-  expect(parsedRequest.method).toEqual('GET');
-  expect(parsedRequest.headers.host).toEqual('localhost:18090');
-  
-  await proxy.stop();
-});
-
-export default tap.start();

test/test.acme-state-manager.node.ts

@@ -1,188 +0,0 @@
-import { expect, tap } from '@git.zone/tstest/tapbundle';
-import { AcmeStateManager } from '../ts/proxies/smart-proxy/acme-state-manager.js';
-import type { IRouteConfig } from '../ts/proxies/smart-proxy/models/route-types.js';
-
-tap.test('AcmeStateManager should track challenge routes correctly', async (tools) => {
-  const stateManager = new AcmeStateManager();
-  
-  const challengeRoute: IRouteConfig = {
-    name: 'acme-challenge',
-    priority: 1000,
-    match: {
-      ports: 80,
-      path: '/.well-known/acme-challenge/*'
-    },
-    action: {
-      type: 'socket-handler',
-      socketHandler: async (socket, context) => {
-        // Mock handler that would write the challenge response
-        socket.end('challenge response');
-      }
-    }
-  };
-  
-  // Initially no challenge routes
-  expect(stateManager.isChallengeRouteActive()).toBeFalse();
-  expect(stateManager.getActiveChallengeRoutes()).toEqual([]);
-  
-  // Add challenge route
-  stateManager.addChallengeRoute(challengeRoute);
-  expect(stateManager.isChallengeRouteActive()).toBeTrue();
-  expect(stateManager.getActiveChallengeRoutes()).toHaveProperty("length", 1);
-  expect(stateManager.getPrimaryChallengeRoute()).toEqual(challengeRoute);
-  
-  // Remove challenge route
-  stateManager.removeChallengeRoute('acme-challenge');
-  expect(stateManager.isChallengeRouteActive()).toBeFalse();
-  expect(stateManager.getActiveChallengeRoutes()).toEqual([]);
-  expect(stateManager.getPrimaryChallengeRoute()).toBeNull();
-});
-
-tap.test('AcmeStateManager should track port allocations', async (tools) => {
-  const stateManager = new AcmeStateManager();
-  
-  const challengeRoute1: IRouteConfig = {
-    name: 'acme-challenge-1',
-    priority: 1000,
-    match: {
-      ports: 80,
-      path: '/.well-known/acme-challenge/*'
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  const challengeRoute2: IRouteConfig = {
-    name: 'acme-challenge-2',
-    priority: 900,
-    match: {
-      ports: [80, 8080],
-      path: '/.well-known/acme-challenge/*'
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  // Add first route
-  stateManager.addChallengeRoute(challengeRoute1);
-  expect(stateManager.isPortAllocatedForAcme(80)).toBeTrue();
-  expect(stateManager.isPortAllocatedForAcme(8080)).toBeFalse();
-  expect(stateManager.getAcmePorts()).toEqual([80]);
-  
-  // Add second route
-  stateManager.addChallengeRoute(challengeRoute2);
-  expect(stateManager.isPortAllocatedForAcme(80)).toBeTrue();
-  expect(stateManager.isPortAllocatedForAcme(8080)).toBeTrue();
-  expect(stateManager.getAcmePorts()).toContain(80);
-  expect(stateManager.getAcmePorts()).toContain(8080);
-  
-  // Remove first route - port 80 should still be allocated
-  stateManager.removeChallengeRoute('acme-challenge-1');
-  expect(stateManager.isPortAllocatedForAcme(80)).toBeTrue();
-  expect(stateManager.isPortAllocatedForAcme(8080)).toBeTrue();
-  
-  // Remove second route - all ports should be deallocated
-  stateManager.removeChallengeRoute('acme-challenge-2');
-  expect(stateManager.isPortAllocatedForAcme(80)).toBeFalse();
-  expect(stateManager.isPortAllocatedForAcme(8080)).toBeFalse();
-  expect(stateManager.getAcmePorts()).toEqual([]);
-});
-
-tap.test('AcmeStateManager should select primary route by priority', async (tools) => {
-  const stateManager = new AcmeStateManager();
-  
-  const lowPriorityRoute: IRouteConfig = {
-    name: 'low-priority',
-    priority: 100,
-    match: {
-      ports: 80
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  const highPriorityRoute: IRouteConfig = {
-    name: 'high-priority',
-    priority: 2000,
-    match: {
-      ports: 80
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  const defaultPriorityRoute: IRouteConfig = {
-    name: 'default-priority',
-    // No priority specified - should default to 0
-    match: {
-      ports: 80
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  // Add low priority first
-  stateManager.addChallengeRoute(lowPriorityRoute);
-  expect(stateManager.getPrimaryChallengeRoute()?.name).toEqual('low-priority');
-  
-  // Add high priority - should become primary
-  stateManager.addChallengeRoute(highPriorityRoute);
-  expect(stateManager.getPrimaryChallengeRoute()?.name).toEqual('high-priority');
-  
-  // Add default priority - primary should remain high priority
-  stateManager.addChallengeRoute(defaultPriorityRoute);
-  expect(stateManager.getPrimaryChallengeRoute()?.name).toEqual('high-priority');
-  
-  // Remove high priority - primary should fall back to low priority
-  stateManager.removeChallengeRoute('high-priority');
-  expect(stateManager.getPrimaryChallengeRoute()?.name).toEqual('low-priority');
-});
-
-tap.test('AcmeStateManager should handle clear operation', async (tools) => {
-  const stateManager = new AcmeStateManager();
-  
-  const challengeRoute1: IRouteConfig = {
-    name: 'route-1',
-    match: {
-      ports: [80, 443]
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  const challengeRoute2: IRouteConfig = {
-    name: 'route-2',
-    match: {
-      ports: 8080
-    },
-    action: {
-      type: 'socket-handler'
-    }
-  };
-  
-  // Add routes
-  stateManager.addChallengeRoute(challengeRoute1);
-  stateManager.addChallengeRoute(challengeRoute2);
-  
-  // Verify state before clear
-  expect(stateManager.isChallengeRouteActive()).toBeTrue();
-  expect(stateManager.getActiveChallengeRoutes()).toHaveProperty("length", 2);
-  expect(stateManager.getAcmePorts()).toHaveProperty("length", 3);
-  
-  // Clear all state
-  stateManager.clear();
-  
-  // Verify state after clear
-  expect(stateManager.isChallengeRouteActive()).toBeFalse();
-  expect(stateManager.getActiveChallengeRoutes()).toEqual([]);
-  expect(stateManager.getAcmePorts()).toEqual([]);
-  expect(stateManager.getPrimaryChallengeRoute()).toBeNull();
-});
-
-export default tap.start();

test/test.acme-timing-simple.ts

@@ -1,122 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { SmartProxy } from '../ts/index.js';
-
-// Test that certificate provisioning is deferred until after ports are listening
-tap.test('should defer certificate provisioning until ports are ready', async (tapTest) => {
-  // Track when operations happen
-  let portsListening = false;
-  let certProvisioningStarted = false;
-  let operationOrder: string[] = [];
-  
-  // Create proxy with certificate route but without real ACME
-  const proxy = new SmartProxy({
-    routes: [{
-      name: 'test-route',
-      match: {
-        ports: 8443,
-        domains: ['test.local']
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'localhost', port: 8181 }],
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto',
-          acme: {
-            email: 'test@local.dev',
-            useProduction: false
-          }
-        }
-      }
-    }]
-  });
-  
-  // Override the certificate manager creation to avoid real ACME
-  const originalCreateCertManager = proxy['createCertificateManager'];
-  proxy['createCertificateManager'] = async function(...args: any[]) {
-    console.log('Creating mock cert manager');
-    operationOrder.push('create-cert-manager');
-    const mockCertManager = {
-      certStore: null,
-      smartAcme: null,
-      httpProxy: null,
-      renewalTimer: null,
-      pendingChallenges: new Map(),
-      challengeRoute: null,
-      certStatus: new Map(),
-      globalAcmeDefaults: null,
-      updateRoutesCallback: undefined,
-      challengeRouteActive: false,
-      isProvisioning: false,
-      acmeStateManager: null,
-      initialize: async () => {
-        operationOrder.push('cert-manager-init');
-        console.log('Mock cert manager initialized');
-      },
-      provisionAllCertificates: async () => {
-        operationOrder.push('cert-provisioning');
-        certProvisioningStarted = true;
-        // Check that ports are listening when provisioning starts
-        if (!portsListening) {
-          throw new Error('Certificate provisioning started before ports ready!');
-        }
-        console.log('Mock certificate provisioning (ports are ready)');
-      },
-      stop: async () => {},
-      setHttpProxy: () => {},
-      setGlobalAcmeDefaults: () => {},
-      setAcmeStateManager: () => {},
-      setUpdateRoutesCallback: () => {},
-      getAcmeOptions: () => ({}),
-      getState: () => ({ challengeRouteActive: false }),
-      getCertStatus: () => new Map(),
-      checkAndRenewCertificates: async () => {},
-      addChallengeRoute: async () => {},
-      removeChallengeRoute: async () => {},
-      getCertificate: async () => null,
-      isValidCertificate: () => false,
-      waitForProvisioning: async () => {}
-    } as any;
-    
-    // Call initialize immediately as the real createCertificateManager does
-    await mockCertManager.initialize();
-    
-    return mockCertManager;
-  };
-  
-  // Track port manager operations
-  const originalAddPorts = proxy['portManager'].addPorts;
-  proxy['portManager'].addPorts = async function(ports: number[]) {
-    operationOrder.push('ports-starting');
-    const result = await originalAddPorts.call(this, ports);
-    operationOrder.push('ports-ready');
-    portsListening = true;
-    console.log('Ports are now listening');
-    return result;
-  };
-  
-  // Start the proxy
-  await proxy.start();
-  
-  // Log the operation order for debugging
-  console.log('Operation order:', operationOrder);
-  
-  // Verify operations happened in the correct order
-  expect(operationOrder).toContain('create-cert-manager');
-  expect(operationOrder).toContain('cert-manager-init');
-  expect(operationOrder).toContain('ports-starting');
-  expect(operationOrder).toContain('ports-ready');
-  expect(operationOrder).toContain('cert-provisioning');
-  
-  // Verify ports were ready before certificate provisioning
-  const portsReadyIndex = operationOrder.indexOf('ports-ready');
-  const certProvisioningIndex = operationOrder.indexOf('cert-provisioning');
-  
-  expect(portsReadyIndex).toBeLessThan(certProvisioningIndex);
-  expect(certProvisioningStarted).toEqual(true);
-  expect(portsListening).toEqual(true);
-  
-  await proxy.stop();
-});
-
-export default tap.start();

test/test.acme-timing.ts

@@ -1,204 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-import { SmartProxy } from '../ts/index.js';
-import * as net from 'net';
-
-// Test that certificate provisioning waits for ports to be ready
-tap.test('should defer certificate provisioning until after ports are listening', async (tapTest) => {
-  // Track the order of operations
-  const operationLog: string[] = [];
-  
-  // Create a mock server to verify ports are listening
-  let port80Listening = false;
-  
-  // Try to use port 8080 instead of 80 to avoid permission issues in testing
-  const acmePort = 8080;
-  
-  // Create proxy with ACME certificate requirement
-  const proxy = new SmartProxy({
-    useHttpProxy: [acmePort],
-    httpProxyPort: 8845, // Use different port to avoid conflicts
-    acme: {
-      email: 'test@test.local',
-      useProduction: false,
-      port: acmePort
-    },
-    routes: [{
-      name: 'test-acme-route',
-      match: {
-        ports: 8443,
-        domains: ['test.local']
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'localhost', port: 8181 }],
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto',
-          acme: {
-            email: 'test@test.local',
-            useProduction: false
-          }
-        }
-      }
-    }]
-  });
-  
-  // Mock some internal methods to track operation order
-  const originalAddPorts = proxy['portManager'].addPorts;
-  proxy['portManager'].addPorts = async function(ports: number[]) {
-    operationLog.push('Starting port listeners');
-    const result = await originalAddPorts.call(this, ports);
-    operationLog.push('Port listeners started');
-    port80Listening = true;
-    return result;
-  };
-  
-  // Track that we created a certificate manager and SmartProxy will call provisionAllCertificates
-  let certManagerCreated = false;
-  
-  // Override createCertificateManager to set up our tracking
-  const originalCreateCertManager = (proxy as any).createCertificateManager;
-  (proxy as any).certManagerCreated = false;
-  
-  // Mock certificate manager to avoid real ACME initialization
-  (proxy as any).createCertificateManager = async function() {
-    operationLog.push('Creating certificate manager');
-    const mockCertManager = {
-      setUpdateRoutesCallback: () => {},
-      setHttpProxy: () => {},
-      setGlobalAcmeDefaults: () => {},
-      setAcmeStateManager: () => {},
-      initialize: async () => {
-        operationLog.push('Certificate manager initialized');
-      },
-      provisionAllCertificates: async () => {
-        operationLog.push('Starting certificate provisioning');
-        if (!port80Listening) {
-          operationLog.push('ERROR: Certificate provisioning started before ports ready');
-        }
-        operationLog.push('Certificate provisioning completed');
-      },
-      stop: async () => {},
-      getAcmeOptions: () => ({ email: 'test@test.local', useProduction: false }),
-      getState: () => ({ challengeRouteActive: false })
-    };
-    certManagerCreated = true;
-    (proxy as any).certManager = mockCertManager;
-    return mockCertManager;
-  };
-  
-  // Start the proxy
-  await proxy.start();
-  
-  // Verify the order of operations
-  expect(operationLog).toContain('Starting port listeners');
-  expect(operationLog).toContain('Port listeners started');
-  expect(operationLog).toContain('Starting certificate provisioning');
-  
-  // Ensure port listeners started before certificate provisioning
-  const portStartIndex = operationLog.indexOf('Port listeners started');
-  const certStartIndex = operationLog.indexOf('Starting certificate provisioning');
-  
-  expect(portStartIndex).toBeLessThan(certStartIndex);
-  expect(operationLog).not.toContain('ERROR: Certificate provisioning started before ports ready');
-  
-  await proxy.stop();
-});
-
-// Test that ACME challenge route is available when certificate is requested
-tap.test('should have ACME challenge route ready before certificate provisioning', async (tapTest) => {
-  let challengeRouteActive = false;
-  let certificateProvisioningStarted = false;
-  
-  const proxy = new SmartProxy({
-    useHttpProxy: [8080],
-    httpProxyPort: 8846, // Use different port to avoid conflicts
-    acme: {
-      email: 'test@test.local',
-      useProduction: false,
-      port: 8080
-    },
-    routes: [{
-      name: 'test-route',
-      match: {
-        ports: 8443,
-        domains: ['test.example.com']
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'localhost', port: 8181 }],
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto'
-        }
-      }
-    }]
-  });
-  
-  // Mock the certificate manager to track operations
-  const originalInitialize = proxy['certManager'] ? 
-    proxy['certManager'].initialize : null;
-    
-  if (proxy['certManager']) {
-    const certManager = proxy['certManager'];
-    
-    // Track when challenge route is added
-    const originalAddChallenge = certManager['addChallengeRoute'];
-    certManager['addChallengeRoute'] = async function() {
-      await originalAddChallenge.call(this);
-      challengeRouteActive = true;
-    };
-    
-    // Track when certificate provisioning starts
-    const originalProvisionAcme = certManager['provisionAcmeCertificate'];
-    certManager['provisionAcmeCertificate'] = async function(...args: any[]) {
-      certificateProvisioningStarted = true;
-      // Verify challenge route is active
-      expect(challengeRouteActive).toEqual(true);
-      // Don't actually provision in test
-      return;
-    };
-  }
-  
-  // Mock certificate manager to avoid real ACME initialization
-  (proxy as any).createCertificateManager = async function() {
-    const mockCertManager = {
-      setUpdateRoutesCallback: () => {},
-      setHttpProxy: () => {},
-      setGlobalAcmeDefaults: () => {},
-      setAcmeStateManager: () => {},
-      initialize: async () => {
-        challengeRouteActive = true;
-      },
-      provisionAllCertificates: async () => {
-        certificateProvisioningStarted = true;
-        expect(challengeRouteActive).toEqual(true);
-      },
-      stop: async () => {},
-      getAcmeOptions: () => ({ email: 'test@test.local', useProduction: false }),
-      getState: () => ({ challengeRouteActive: false }),
-      addChallengeRoute: async () => {
-        challengeRouteActive = true;
-      },
-      provisionAcmeCertificate: async () => {
-        certificateProvisioningStarted = true;
-        expect(challengeRouteActive).toEqual(true);
-      }
-    };
-    // Call initialize like the real createCertificateManager does
-    await mockCertManager.initialize();
-    return mockCertManager;
-  };
-  
-  await proxy.start();
-  
-  // Give it a moment to complete initialization
-  await new Promise(resolve => setTimeout(resolve, 100));
-  
-  // Verify challenge route was added before any certificate provisioning
-  expect(challengeRouteActive).toEqual(true);
-  
-  await proxy.stop();
-});
-
-export default tap.start();

test/test.bun.ts

@@ -0,0 +1,120 @@
+import { tap, expect } from '@git.zone/tstest/tapbundle';
+
+import {
+  mergeRouteConfigs,
+  cloneRoute,
+  routeMatchesPath,
+} from '../ts/proxies/smart-proxy/utils/route-utils.js';
+
+import {
+  validateRoutes,
+  validateRouteConfig,
+} from '../ts/proxies/smart-proxy/utils/route-validator.js';
+
+import type { IRouteConfig } from '../ts/proxies/smart-proxy/models/route-types.js';
+
+tap.test('route creation - HTTPS terminate route has correct structure', async () => {
+  const route: IRouteConfig = {
+    match: { ports: 443, domains: 'secure.example.com' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 8443 }], tls: { mode: 'terminate', certificate: 'auto' } }
+  };
+  expect(route).toHaveProperty('match');
+  expect(route).toHaveProperty('action');
+  expect(route.action.type).toEqual('forward');
+  expect(route.action.tls).toBeDefined();
+  expect(route.action.tls!.mode).toEqual('terminate');
+  expect(route.match.domains).toEqual('secure.example.com');
+});
+
+tap.test('route validation - validateRoutes on a set of routes', async () => {
+  const routes: IRouteConfig[] = [
+    { match: { ports: 80, domains: 'a.com' }, action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] } },
+    { match: { ports: 80, domains: 'b.com' }, action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 4000 }] } },
+  ];
+  const result = validateRoutes(routes);
+  expect(result.valid).toBeTrue();
+  expect(result.errors).toHaveLength(0);
+});
+
+tap.test('route validation - validateRoutes catches invalid route in set', async () => {
+  const routes: any[] = [
+    { match: { ports: 80, domains: 'valid.com' }, action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] } },
+    { match: { ports: 80 } }, // missing action
+  ];
+  const result = validateRoutes(routes);
+  expect(result.valid).toBeFalse();
+  expect(result.errors.length).toBeGreaterThan(0);
+});
+
+tap.test('path matching - routeMatchesPath with exact path', async () => {
+  const route: IRouteConfig = {
+    match: { ports: 80, domains: 'example.com', path: '/api' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] }
+  };
+  expect(routeMatchesPath(route, '/api')).toBeTrue();
+  expect(routeMatchesPath(route, '/other')).toBeFalse();
+});
+
+tap.test('path matching - route without path matches everything', async () => {
+  const route: IRouteConfig = {
+    match: { ports: 80, domains: 'example.com' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] }
+  };
+  expect(routeMatchesPath(route, '/anything')).toBeTrue();
+  expect(routeMatchesPath(route, '/')).toBeTrue();
+});
+
+tap.test('route merging - mergeRouteConfigs combines routes', async () => {
+  const base: IRouteConfig = {
+    match: { ports: 80, domains: 'example.com' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] },
+    priority: 10,
+    name: 'base-route'
+  };
+
+  const merged = mergeRouteConfigs(base, {
+    priority: 50,
+    name: 'merged-route',
+  });
+
+  expect(merged.priority).toEqual(50);
+  expect(merged.name).toEqual('merged-route');
+  expect(merged.match.domains).toEqual('example.com');
+  expect(merged.action.targets![0].host).toEqual('127.0.0.1');
+});
+
+tap.test('route merging - mergeRouteConfigs does not mutate original', async () => {
+  const base: IRouteConfig = {
+    match: { ports: 80, domains: 'example.com' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] },
+    name: 'original'
+  };
+
+  const merged = mergeRouteConfigs(base, { name: 'changed' });
+  expect(base.name).toEqual('original');
+  expect(merged.name).toEqual('changed');
+});
+
+tap.test('route cloning - cloneRoute produces independent copy', async () => {
+  const original: IRouteConfig = {
+    match: { ports: 80, domains: 'example.com' },
+    action: { type: 'forward', targets: [{ host: '127.0.0.1', port: 3000 }] },
+    priority: 42,
+    name: 'original-route'
+  };
+
+  const cloned = cloneRoute(original);
+
+  expect(cloned.match.domains).toEqual('example.com');
+  expect(cloned.priority).toEqual(42);
+  expect(cloned.name).toEqual('original-route');
+  expect(cloned.action.targets![0].host).toEqual('127.0.0.1');
+  expect(cloned.action.targets![0].port).toEqual(3000);
+
+  cloned.name = 'cloned-route';
+  cloned.priority = 99;
+  expect(original.name).toEqual('original-route');
+  expect(original.priority).toEqual(42);
+});
+
+export default tap.start();