v25.16.2

changelog.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "25.15.0",
+  "version": "25.16.2",
   "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",

readme.md

@@ -306,6 +306,10 @@ const quicRoute: IRouteConfig = {
       port: 8443,
       backendTransport: 'tcp'  // 👈 Translate QUIC → TCP for backend
     }],
+    tls: {
+      mode: 'terminate',
+      certificate: 'auto'     // 👈 QUIC requires TLS 1.3
+    },
     udp: {
       quic: {
         enableHttp3: true,
@@ -318,9 +322,47 @@ const quicRoute: IRouteConfig = {
   }
 };
 
-const proxy = new SmartProxy({ routes: [quicRoute] });
+const proxy = new SmartProxy({
+  acme: { email: 'ssl@example.com' },
+  routes: [quicRoute]
+});
 ```
 
+### 🚄 Best-Effort Backend Protocol (H3 > H2 > H1)
+
+SmartProxy automatically uses the **highest protocol your backend supports** for HTTP requests. The backend protocol is independent of the client protocol — a client using HTTP/1.1 can be forwarded over HTTP/3 to the backend, and vice versa.
+
+```typescript
+const route: IRouteConfig = {
+  name: 'auto-protocol',
+  match: { ports: 443, domains: 'app.example.com' },
+  action: {
+    type: 'forward',
+    targets: [{ host: 'backend', port: 8443 }],
+    tls: { mode: 'terminate', certificate: 'auto' },
+    options: {
+      backendProtocol: 'auto'  // 👈 Default — best-effort selection
+    }
+  }
+};
+```
+
+**How protocol discovery works (browser model):**
+
+1. First request → TLS ALPN probe detects H2 or H1
+2. Backend response inspected for `Alt-Svc: h3=":port"` header
+3. If H3 advertised → cached and used for subsequent requests via QUIC
+4. Graceful fallback: H3 failure → H2 → H1 with automatic cache invalidation
+
+| `backendProtocol` | Behavior |
+|---|---|
+| `'auto'` (default) | Best-effort: H3 > H2 > H1 with Alt-Svc discovery |
+| `'http1'` | Always HTTP/1.1 |
+| `'http2'` | Always HTTP/2 (hard-fail if unsupported) |
+| `'http3'` | Always HTTP/3 via QUIC (hard-fail if unsupported) |
+
+> **Note:** WebSocket upgrades always use HTTP/1.1 to the backend regardless of `backendProtocol`, since there's no performance benefit from H2/H3 Extended CONNECT for tunneled connections, and backend support is rare.
+
 ### 🔁 Dual-Stack TCP + UDP Route
 
 Listen on both TCP and UDP with a single route — handle each transport with its own handler:
@@ -769,6 +811,28 @@ interface IRouteLoadBalancing {
 }
 ```
 
+### Backend Protocol Options
+
+```typescript
+// Set on action.options
+{
+  action: {
+    type: 'forward',
+    targets: [...],
+    options: {
+      backendProtocol: 'auto' | 'http1' | 'http2' | 'http3'
+    }
+  }
+}
+```
+
+| Value | Backend Behavior |
+|-------|-----------------|
+| `'auto'` | Best-effort: discovers H3 via Alt-Svc, probes H2 via ALPN, falls back to H1 |
+| `'http1'` | Always HTTP/1.1 (no ALPN probe) |
+| `'http2'` | Always HTTP/2 (hard-fail if handshake fails) |
+| `'http3'` | Always HTTP/3 over QUIC (3s connect timeout, hard-fail if unreachable) |
+
 ### UDP & QUIC Options
 
 ```typescript

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

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

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

@@ -43,6 +43,10 @@ struct ConnActivity {
     /// increments on creation and decrements on Drop, keeping the watchdog aware that
     /// a response body is still streaming after the request handler has returned.
     active_requests: Option<Arc<AtomicU64>>,
+    /// Protocol cache key for Alt-Svc discovery. When set, `build_streaming_response`
+    /// checks the backend's original response headers for Alt-Svc before our
+    /// ResponseFilter injects its own. None when not in auto-detect mode or after H3 failure.
+    alt_svc_cache_key: Option<crate::protocol_cache::ProtocolCacheKey>,
 }
 
 /// Default upstream connect timeout (30 seconds).
@@ -58,6 +62,18 @@ const DEFAULT_WS_INACTIVITY_TIMEOUT: std::time::Duration = std::time::Duration::
 /// Default WebSocket max lifetime (24 hours).
 const DEFAULT_WS_MAX_LIFETIME: std::time::Duration = std::time::Duration::from_secs(86400);
 
+/// Timeout for QUIC (H3) backend connections. Short because UDP is often firewalled.
+const QUIC_CONNECT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(3);
+
+/// Protocol decision for backend connection.
+#[derive(Debug)]
+enum ProtocolDecision {
+    H1,
+    H2,
+    H3 { port: u16 },
+    AlpnProbe,
+}
+
 /// RAII guard that decrements the active request counter on drop.
 /// Ensures the counter is correct even if the request handler panics.
 struct ActiveRequestGuard {
@@ -190,6 +206,9 @@ pub struct HttpProxyService {
     ws_inactivity_timeout: std::time::Duration,
     /// WebSocket maximum connection lifetime.
     ws_max_lifetime: std::time::Duration,
+    /// Shared QUIC client endpoint for outbound H3 backend connections.
+    /// Lazily initialized on first H3 backend attempt.
+    quinn_client_endpoint: Arc<quinn::Endpoint>,
 }
 
 impl HttpProxyService {
@@ -209,6 +228,7 @@ impl HttpProxyService {
             http_idle_timeout: DEFAULT_HTTP_IDLE_TIMEOUT,
             ws_inactivity_timeout: DEFAULT_WS_INACTIVITY_TIMEOUT,
             ws_max_lifetime: DEFAULT_WS_MAX_LIFETIME,
+            quinn_client_endpoint: Arc::new(Self::create_quinn_client_endpoint()),
         }
     }
 
@@ -233,6 +253,7 @@ impl HttpProxyService {
             http_idle_timeout: DEFAULT_HTTP_IDLE_TIMEOUT,
             ws_inactivity_timeout: DEFAULT_WS_INACTIVITY_TIMEOUT,
             ws_max_lifetime: DEFAULT_WS_MAX_LIFETIME,
+            quinn_client_endpoint: Arc::new(Self::create_quinn_client_endpoint()),
         }
     }
 
@@ -324,7 +345,7 @@ impl HttpProxyService {
             let cn = cancel_inner.clone();
             let la = Arc::clone(&la_inner);
             let st = start;
-            let ca = ConnActivity { last_activity: Arc::clone(&la_inner), start, active_requests: Some(Arc::clone(&ar_inner)) };
+            let ca = ConnActivity { last_activity: Arc::clone(&la_inner), start, active_requests: Some(Arc::clone(&ar_inner)), alt_svc_cache_key: None };
             async move {
                 let result = svc.handle_request(req, peer, port, cn, ca).await;
                 // Mark request end — update activity timestamp before guard drops
@@ -401,7 +422,7 @@ impl HttpProxyService {
         peer_addr: std::net::SocketAddr,
         port: u16,
         cancel: CancellationToken,
-        conn_activity: ConnActivity,
+        mut conn_activity: ConnActivity,
     ) -> Result<Response<BoxBody<Bytes, hyper::Error>>, hyper::Error> {
         let host = req.headers()
             .get("host")
@@ -645,37 +666,101 @@ impl HttpProxyService {
 
         // --- Resolve protocol decision based on backend protocol mode ---
         let is_auto_detect_mode = matches!(backend_protocol_mode, rustproxy_config::BackendProtocol::Auto);
-        let (use_h2, needs_alpn_probe) = match backend_protocol_mode {
-            rustproxy_config::BackendProtocol::Http1 => (false, false),
-            rustproxy_config::BackendProtocol::Http2 => (true, false),
-            rustproxy_config::BackendProtocol::Http3 => {
-                // HTTP/3 (QUIC) backend connections not yet implemented — fall back to H1
-                warn!("backendProtocol 'http3' not yet implemented, falling back to http1");
-                (false, false)
-            }
+        let protocol_cache_key = crate::protocol_cache::ProtocolCacheKey {
+            host: upstream.host.clone(),
+            port: upstream.port,
+            requested_host: host.clone(),
+        };
+        let protocol_decision = match backend_protocol_mode {
+            rustproxy_config::BackendProtocol::Http1 => ProtocolDecision::H1,
+            rustproxy_config::BackendProtocol::Http2 => ProtocolDecision::H2,
+            rustproxy_config::BackendProtocol::Http3 => ProtocolDecision::H3 { port: upstream.port },
             rustproxy_config::BackendProtocol::Auto => {
                 if !upstream.use_tls {
-                    // No ALPN without TLS — default to H1
-                    (false, false)
+                    // No ALPN without TLS, no QUIC without TLS — default to H1
+                    ProtocolDecision::H1
                 } else {
-                    let cache_key = crate::protocol_cache::ProtocolCacheKey {
-                        host: upstream.host.clone(),
-                        port: upstream.port,
-                        requested_host: host.clone(),
-                    };
-                    match self.protocol_cache.get(&cache_key) {
-                        Some(crate::protocol_cache::DetectedProtocol::H2) => (true, false),
-                        Some(crate::protocol_cache::DetectedProtocol::H1) => (false, false),
-                        Some(crate::protocol_cache::DetectedProtocol::H3) => {
-                            // H3 cached but we're on TCP — fall back to H2 probe
-                            (false, true)
-                        }
-                        None => (false, true), // needs ALPN probe
+                    match self.protocol_cache.get(&protocol_cache_key) {
+                        Some(cached) => match cached.protocol {
+                            crate::protocol_cache::DetectedProtocol::H3 => {
+                                if let Some(h3_port) = cached.h3_port {
+                                    ProtocolDecision::H3 { port: h3_port }
+                                } else {
+                                    // H3 cached but no port — fall back to ALPN probe
+                                    ProtocolDecision::AlpnProbe
+                                }
+                            }
+                            crate::protocol_cache::DetectedProtocol::H2 => ProtocolDecision::H2,
+                            crate::protocol_cache::DetectedProtocol::H1 => ProtocolDecision::H1,
+                        },
+                        None => ProtocolDecision::AlpnProbe,
                     }
                 }
             }
         };
 
+        // Derive legacy flags for the existing H1/H2 connection path
+        let (use_h2, mut needs_alpn_probe) = match &protocol_decision {
+            ProtocolDecision::H1 => (false, false),
+            ProtocolDecision::H2 => (true, false),
+            ProtocolDecision::H3 { .. } => (false, false), // H3 path handled separately below
+            ProtocolDecision::AlpnProbe => (false, true),
+        };
+
+        // Set Alt-Svc cache key on conn_activity so build_streaming_response can check
+        // the backend's original Alt-Svc header before ResponseFilter injects our own.
+        if is_auto_detect_mode {
+            conn_activity.alt_svc_cache_key = Some(protocol_cache_key.clone());
+        }
+
+        // --- H3 path: try QUIC connection before TCP ---
+        if let ProtocolDecision::H3 { port: h3_port } = protocol_decision {
+            let h3_pool_key = crate::connection_pool::PoolKey {
+                host: upstream.host.clone(),
+                port: h3_port,
+                use_tls: true,
+                protocol: crate::connection_pool::PoolProtocol::H3,
+            };
+
+            // Try H3 pool checkout first
+            if let Some((quic_conn, _age)) = self.connection_pool.checkout_h3(&h3_pool_key) {
+                self.metrics.backend_pool_hit(&upstream_key);
+                let result = self.forward_h3(
+                    quic_conn, parts, body, upstream_headers, &upstream_path,
+                    route_match.route, route_id, &ip_str, &h3_pool_key, domain_str, &conn_activity, &upstream_key,
+                ).await;
+                self.upstream_selector.connection_ended(&upstream_key);
+                return result;
+            }
+
+            // Try fresh QUIC connection
+            match self.connect_quic_backend(&upstream.host, h3_port).await {
+                Ok(quic_conn) => {
+                    self.metrics.backend_pool_miss(&upstream_key);
+                    self.metrics.backend_connection_opened(&upstream_key, std::time::Instant::now().elapsed());
+                    let result = self.forward_h3(
+                        quic_conn, parts, body, upstream_headers, &upstream_path,
+                        route_match.route, route_id, &ip_str, &h3_pool_key, domain_str, &conn_activity, &upstream_key,
+                    ).await;
+                    self.upstream_selector.connection_ended(&upstream_key);
+                    return result;
+                }
+                Err(e) => {
+                    warn!(backend = %upstream_key, error = %e,
+                        "H3 backend connect failed, falling back to H2/H1");
+                    // Suppress Alt-Svc caching for the fallback to prevent re-caching H3
+                    // from our own injected Alt-Svc header or a stale backend Alt-Svc
+                    conn_activity.alt_svc_cache_key = None;
+                    // Force ALPN probe on TCP fallback so we correctly detect H2 vs H1
+                    // (don't cache anything yet — let the ALPN probe decide)
+                    if is_auto_detect_mode && upstream.use_tls {
+                        needs_alpn_probe = true;
+                    }
+                    // Fall through to TCP path
+                }
+            }
+        }
+
         // --- Connection pooling: try reusing an existing connection first ---
         // For ALPN probe mode, skip pool checkout (we don't know the protocol yet)
         if !needs_alpn_probe {
@@ -870,6 +955,7 @@ impl HttpProxyService {
         };
         self.upstream_selector.connection_ended(&upstream_key);
         self.metrics.backend_connection_closed(&upstream_key);
+
         result
     }
 
@@ -1668,6 +1754,19 @@ impl HttpProxyService {
     ) -> Result<Response<BoxBody<Bytes, hyper::Error>>, hyper::Error> {
         let (resp_parts, resp_body) = upstream_response.into_parts();
 
+        // Check for Alt-Svc in the backend's ORIGINAL response headers BEFORE
+        // ResponseFilter::apply_headers runs — the filter may inject our own Alt-Svc
+        // for client-facing HTTP/3 advertisement, which must not be confused with
+        // backend-originated Alt-Svc.
+        if let Some(ref cache_key) = conn_activity.alt_svc_cache_key {
+            if let Some(alt_svc) = resp_parts.headers.get("alt-svc").and_then(|v| v.to_str().ok()) {
+                if let Some(h3_port) = parse_alt_svc_h3_port(alt_svc) {
+                    debug!(h3_port, "Backend advertises H3 via Alt-Svc");
+                    self.protocol_cache.insert_h3(cache_key.clone(), h3_port);
+                }
+            }
+        }
+
         let mut response = Response::builder()
             .status(resp_parts.status);
 
@@ -2393,6 +2492,252 @@ impl HttpProxyService {
         config.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
         Arc::new(config)
     }
+
+    /// Create a shared QUIC client endpoint for outbound H3 backend connections.
+    fn create_quinn_client_endpoint() -> quinn::Endpoint {
+        let _ = rustls::crypto::ring::default_provider().install_default();
+        let mut tls_config = rustls::ClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(Arc::new(InsecureBackendVerifier))
+            .with_no_client_auth();
+        tls_config.alpn_protocols = vec![b"h3".to_vec()];
+
+        let quic_crypto = quinn::crypto::rustls::QuicClientConfig::try_from(tls_config)
+            .expect("Failed to create QUIC client crypto config");
+        let client_config = quinn::ClientConfig::new(Arc::new(quic_crypto));
+
+        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
+    }
+
+    /// Connect to a backend via QUIC (H3).
+    async fn connect_quic_backend(
+        &self,
+        host: &str,
+        port: u16,
+    ) -> Result<quinn::Connection, Box<dyn std::error::Error + Send + Sync>> {
+        let addr = tokio::net::lookup_host(format!("{}:{}", host, port))
+            .await?
+            .next()
+            .ok_or("DNS resolution returned no addresses")?;
+
+        let server_name = host.to_string();
+        let connecting = self.quinn_client_endpoint.connect(addr, &server_name)?;
+
+        let connection = tokio::time::timeout(QUIC_CONNECT_TIMEOUT, connecting).await
+            .map_err(|_| "QUIC connect timeout (3s)")??;
+
+        debug!("QUIC backend connection established to {}:{}", host, port);
+        Ok(connection)
+    }
+
+    /// Forward request to backend via HTTP/3 over QUIC.
+    async fn forward_h3(
+        &self,
+        quic_conn: quinn::Connection,
+        parts: hyper::http::request::Parts,
+        body: Incoming,
+        upstream_headers: hyper::HeaderMap,
+        upstream_path: &str,
+        route: &rustproxy_config::RouteConfig,
+        route_id: Option<&str>,
+        source_ip: &str,
+        pool_key: &crate::connection_pool::PoolKey,
+        domain: &str,
+        conn_activity: &ConnActivity,
+        backend_key: &str,
+    ) -> Result<Response<BoxBody<Bytes, hyper::Error>>, hyper::Error> {
+        let h3_quinn_conn = h3_quinn::Connection::new(quic_conn.clone());
+        let (mut driver, mut send_request) = match h3::client::new(h3_quinn_conn).await {
+            Ok(pair) => pair,
+            Err(e) => {
+                error!(backend = %backend_key, domain = %domain, error = %e, "H3 client handshake failed");
+                self.metrics.backend_handshake_error(backend_key);
+                return Ok(error_response(StatusCode::BAD_GATEWAY, "H3 handshake failed"));
+            }
+        };
+
+        // Spawn the h3 connection driver
+        let driver_pool = Arc::clone(&self.connection_pool);
+        let driver_pool_key = pool_key.clone();
+        let gen_holder = Arc::new(std::sync::atomic::AtomicU64::new(u64::MAX));
+        let driver_gen = Arc::clone(&gen_holder);
+        tokio::spawn(async move {
+            let close_err = std::future::poll_fn(|cx| driver.poll_close(cx)).await;
+            debug!("H3 connection driver closed: {:?}", close_err);
+            let g = driver_gen.load(std::sync::atomic::Ordering::Relaxed);
+            if g != u64::MAX {
+                driver_pool.remove_h3_if_generation(&driver_pool_key, g);
+            }
+        });
+
+        // Build the H3 request
+        let uri = hyper::Uri::builder()
+            .scheme("https")
+            .authority(domain)
+            .path_and_query(upstream_path)
+            .build()
+            .unwrap_or_else(|_| upstream_path.parse().unwrap_or_default());
+
+        let mut h3_req = hyper::Request::builder()
+            .method(parts.method.clone())
+            .uri(uri);
+
+        if let Some(headers) = h3_req.headers_mut() {
+            *headers = upstream_headers;
+        }
+
+        let h3_req = h3_req.body(()).unwrap();
+
+        // Send the request
+        let mut stream = match send_request.send_request(h3_req).await {
+            Ok(s) => s,
+            Err(e) => {
+                error!(backend = %backend_key, domain = %domain, error = %e, "H3 send_request failed");
+                self.metrics.backend_request_error(backend_key);
+                return Ok(error_response(StatusCode::BAD_GATEWAY, "H3 request failed"));
+            }
+        };
+
+        // Stream request body
+        let rid: Option<Arc<str>> = route_id.map(Arc::from);
+        let sip: Arc<str> = Arc::from(source_ip);
+
+        {
+            use http_body_util::BodyExt;
+            let mut body = body;
+            while let Some(frame) = body.frame().await {
+                match frame {
+                    Ok(frame) => {
+                        if let Some(data) = frame.data_ref() {
+                            self.metrics.record_bytes(data.len() as u64, 0, rid.as_deref(), Some(&sip));
+                            if let Err(e) = stream.send_data(Bytes::copy_from_slice(data)).await {
+                                error!(backend = %backend_key, error = %e, "H3 send_data failed");
+                                return Ok(error_response(StatusCode::BAD_GATEWAY, "H3 body send failed"));
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        warn!(backend = %backend_key, error = %e, "Client body read error during H3 forward");
+                        break;
+                    }
+                }
+            }
+            // Signal end of body
+            stream.finish().await.ok();
+        }
+
+        // Read response
+        let h3_response = match stream.recv_response().await {
+            Ok(resp) => resp,
+            Err(e) => {
+                error!(backend = %backend_key, domain = %domain, error = %e, "H3 recv_response failed");
+                self.metrics.backend_request_error(backend_key);
+                return Ok(error_response(StatusCode::BAD_GATEWAY, "H3 response failed"));
+            }
+        };
+
+        // Build the response for the client
+        let status = h3_response.status();
+        let mut response = Response::builder().status(status);
+
+        if let Some(headers) = response.headers_mut() {
+            for (name, value) in h3_response.headers() {
+                let n = name.as_str();
+                // Skip hop-by-hop headers
+                if n == "transfer-encoding" || n == "connection" || n == "keep-alive" {
+                    continue;
+                }
+                headers.insert(name.clone(), value.clone());
+            }
+            ResponseFilter::apply_headers(route, headers, None);
+        }
+
+        // Stream response body back via an adapter
+        let h3_body = H3ClientResponseBody { stream };
+        let counting_body = CountingBody::new(
+            h3_body,
+            Arc::clone(&self.metrics),
+            rid,
+            Some(sip),
+            Direction::Out,
+        ).with_connection_activity(Arc::clone(&conn_activity.last_activity), conn_activity.start);
+
+        let counting_body = if let Some(ref ar) = conn_activity.active_requests {
+            counting_body.with_active_requests(Arc::clone(ar))
+        } else {
+            counting_body
+        };
+
+        let body: BoxBody<Bytes, hyper::Error> = BoxBody::new(counting_body);
+
+        // Register connection in pool on success
+        if status != StatusCode::BAD_GATEWAY {
+            let g = self.connection_pool.register_h3(pool_key.clone(), quic_conn);
+            gen_holder.store(g, std::sync::atomic::Ordering::Relaxed);
+        }
+
+        self.metrics.set_backend_protocol(backend_key, "h3");
+        Ok(response.body(body).unwrap())
+    }
+}
+
+/// Parse an Alt-Svc header value to extract the H3 port.
+/// Handles formats like `h3=":443"; ma=86400` and `h3=":8443", h2=":443"`.
+fn parse_alt_svc_h3_port(header_value: &str) -> Option<u16> {
+    for directive in header_value.split(',') {
+        let directive = directive.trim();
+        // Match h3=":<port>" or h3-29=":<port>" etc.
+        if directive.starts_with("h3=") || directive.starts_with("h3-") {
+            // Find the port in ":<port>"
+            if let Some(start) = directive.find("\":") {
+                let rest = &directive[start + 2..];
+                if let Some(end) = rest.find('"') {
+                    if let Ok(port) = rest[..end].parse::<u16>() {
+                        return Some(port);
+                    }
+                }
+            }
+        }
+    }
+    None
+}
+
+/// Response body adapter for H3 client responses.
+/// Reads data from the h3 `RequestStream` recv side and presents it as an `http_body::Body`.
+struct H3ClientResponseBody {
+    stream: h3::client::RequestStream<h3_quinn::BidiStream<Bytes>, Bytes>,
+}
+
+impl http_body::Body for H3ClientResponseBody {
+    type Data = Bytes;
+    type Error = hyper::Error;
+
+    fn poll_frame(
+        mut self: Pin<&mut Self>,
+        _cx: &mut Context<'_>,
+    ) -> Poll<Option<Result<http_body::Frame<Self::Data>, Self::Error>>> {
+        // h3's recv_data is async, so we need to poll it manually.
+        // Use a small future to poll the recv_data call.
+        use std::future::Future;
+        let mut fut = Box::pin(self.stream.recv_data());
+        match fut.as_mut().poll(_cx) {
+            Poll::Ready(Ok(Some(mut buf))) => {
+                use bytes::Buf;
+                let data = Bytes::copy_from_slice(buf.chunk());
+                buf.advance(buf.remaining());
+                Poll::Ready(Some(Ok(http_body::Frame::data(data))))
+            }
+            Poll::Ready(Ok(None)) => Poll::Ready(None),
+            Poll::Ready(Err(e)) => {
+                warn!("H3 response body recv error: {}", e);
+                Poll::Ready(None)
+            }
+            Poll::Pending => Poll::Pending,
+        }
+    }
 }
 
 /// Insecure certificate verifier for backend TLS connections (fallback only).
@@ -2463,6 +2808,7 @@ impl Default for HttpProxyService {
             http_idle_timeout: DEFAULT_HTTP_IDLE_TIMEOUT,
             ws_inactivity_timeout: DEFAULT_WS_INACTIVITY_TIMEOUT,
             ws_max_lifetime: DEFAULT_WS_MAX_LIFETIME,
+            quinn_client_endpoint: Arc::new(Self::create_quinn_client_endpoint()),
         }
     }
 }

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

@@ -19,6 +19,8 @@ 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.
@@ -55,6 +57,7 @@ pub async fn quic_accept_loop(
     metrics: Arc<MetricsCollector>,
     conn_tracker: Arc<ConnectionTracker>,
     cancel: CancellationToken,
+    h3_service: Option<Arc<H3ProxyService>>,
 ) {
     loop {
         let incoming = tokio::select! {
@@ -113,9 +116,10 @@ pub async fn quic_accept_loop(
         let metrics = Arc::clone(&metrics);
         let conn_tracker = Arc::clone(&conn_tracker);
         let cancel = cancel.child_token();
+        let h3_svc = h3_service.clone();
 
         tokio::spawn(async move {
-            match handle_quic_connection(incoming, route, port, Arc::clone(&metrics), &cancel).await {
+            match handle_quic_connection(incoming, route, port, Arc::clone(&metrics), &cancel, h3_svc).await {
                 Ok(()) => debug!("QUIC connection from {} completed", remote_addr),
                 Err(e) => debug!("QUIC connection from {} error: {}", remote_addr, e),
             }
@@ -139,6 +143,7 @@ async fn handle_quic_connection(
     port: u16,
     metrics: Arc<MetricsCollector>,
     cancel: &CancellationToken,
+    h3_service: Option<Arc<H3ProxyService>>,
 ) -> anyhow::Result<()> {
     let connection = incoming.await?;
     let remote_addr = connection.remote_address();
@@ -151,10 +156,20 @@ async fn handle_quic_connection(
         .unwrap_or(false);
 
     if enable_http3 {
-        // Phase 5: dispatch to H3ProxyService
-        // For now, log and accept streams for basic handling
-        debug!("HTTP/3 enabled for route {:?}, dispatching to H3 handler", route.name);
-        handle_h3_connection(connection, route, port, &metrics, cancel).await
+        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).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).await
@@ -257,29 +272,6 @@ async fn forward_quic_stream_to_tcp(
     Ok((bytes_in, bytes_out))
 }
 
-/// Placeholder for HTTP/3 connection handling (Phase 5).
-///
-/// Once h3_service is implemented, this will delegate to it.
-async fn handle_h3_connection(
-    connection: quinn::Connection,
-    _route: RouteConfig,
-    _port: u16,
-    _metrics: &MetricsCollector,
-    cancel: &CancellationToken,
-) -> anyhow::Result<()> {
-    warn!("HTTP/3 handling not yet fully implemented — accepting connection but no request processing");
-
-    // Keep the connection alive until cancelled or closed
-    tokio::select! {
-        _ = cancel.cancelled() => {}
-        reason = connection.closed() => {
-            debug!("HTTP/3 connection closed: {}", reason);
-        }
-    }
-
-    Ok(())
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

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

@@ -21,13 +21,15 @@ 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
-    listeners: HashMap<u16, JoinHandle<()>>,
+    /// 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
@@ -44,13 +46,18 @@ pub struct UdpListenerManager {
     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>>,
 }
 
 impl Drop for UdpListenerManager {
     fn drop(&mut self) {
         self.cancel_token.cancel();
-        for (_, handle) in self.listeners.drain() {
+        for (_, (handle, endpoint)) in self.listeners.drain() {
             handle.abort();
+            if let Some(ep) = endpoint {
+                ep.close(quinn::VarInt::from_u32(0), b"shutdown");
+            }
         }
     }
 }
@@ -72,9 +79,15 @@ impl UdpListenerManager {
             datagram_handler_relay: Arc::new(RwLock::new(None)),
             relay_writer: Arc::new(Mutex::new(None)),
             relay_reader_cancel: None,
+            h3_service: None,
         }
     }
 
+    /// 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);
@@ -109,8 +122,9 @@ impl UdpListenerManager {
 
         if has_quic {
             if let Some(tls) = tls_config {
-                // Create QUIC endpoint
+                // Create QUIC endpoint; clone it so we can hot-swap TLS later
                 let endpoint = crate::quic_handler::create_quic_endpoint(port, tls)?;
+                let endpoint_for_updates = endpoint.clone(); // quinn::Endpoint is Arc-based
                 let handle = tokio::spawn(crate::quic_handler::quic_accept_loop(
                     endpoint,
                     port,
@@ -118,8 +132,9 @@ impl UdpListenerManager {
                     Arc::clone(&self.metrics),
                     Arc::clone(&self.conn_tracker),
                     self.cancel_token.child_token(),
+                    self.h3_service.clone(),
                 ));
-                self.listeners.insert(port, handle);
+                self.listeners.insert(port, (handle, Some(endpoint_for_updates)));
                 info!("QUIC endpoint started on port {}", port);
                 return Ok(());
             } else {
@@ -145,7 +160,7 @@ impl UdpListenerManager {
             self.cancel_token.child_token(),
         ));
 
-        self.listeners.insert(port, handle);
+        self.listeners.insert(port, (handle, None));
 
         // Start the session cleanup task if this is the first port
         if self.listeners.len() == 1 {
@@ -157,8 +172,11 @@ impl UdpListenerManager {
 
     /// Stop listening on a UDP port.
     pub fn remove_port(&mut self, port: u16) {
-        if let Some(handle) = self.listeners.remove(&port) {
+        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);
         }
     }
@@ -173,14 +191,37 @@ impl UdpListenerManager {
     /// Stop all listeners and clean up.
     pub async fn stop(&mut self) {
         self.cancel_token.cancel();
-        for (port, handle) in self.listeners.drain() {
+        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);
+                    }
+                }
+            }
+        }
+    }
+
     /// 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

rust/crates/rustproxy/src/lib.rs

@@ -340,6 +340,17 @@ impl RustProxy {
                 self.cancel_token.clone(),
             );
 
+            // Construct H3ProxyService for HTTP/3 request handling
+            let h3_svc = rustproxy_http::h3_service::H3ProxyService::new(
+                Arc::new(ArcSwap::from(Arc::clone(&*self.route_table.load()))),
+                Arc::clone(&self.metrics),
+                Arc::new(rustproxy_http::connection_pool::ConnectionPool::new()),
+                Arc::new(rustproxy_http::protocol_cache::ProtocolCache::new()),
+                rustproxy_passthrough::tls_handler::shared_backend_tls_config(),
+                std::time::Duration::from_secs(30),
+            );
+            udp_mgr.set_h3_service(Arc::new(h3_svc));
+
             for port in &udp_ports {
                 udp_mgr.add_port_with_tls(*port, quic_tls_config.clone()).await?;
             }
@@ -772,13 +783,21 @@ impl RustProxy {
                     }
                 }
 
+                // Build TLS config for QUIC before taking mutable borrow on udp_mgr
+                let quic_tls = if new_udp_ports.iter().any(|p| !old_udp_ports.contains(p)) {
+                    let tls_configs = self.current_tls_configs().await;
+                    Self::build_quic_tls_config(&tls_configs)
+                } else {
+                    None
+                };
+
                 if let Some(ref mut udp_mgr) = self.udp_listener_manager {
                     udp_mgr.update_routes(Arc::clone(&new_manager));
 
-                    // Add new UDP ports
+                    // Add new UDP ports (with TLS for QUIC)
                     for port in &new_udp_ports {
                         if !old_udp_ports.contains(port) {
-                            udp_mgr.add_port(*port).await?;
+                            udp_mgr.add_port_with_tls(*port, quic_tls.clone()).await?;
                         }
                     }
                     // Remove old UDP ports
@@ -1005,6 +1024,33 @@ impl RustProxy {
         Some(Arc::new(tls_config))
     }
 
+    /// Build the current full TLS config map from all sources (route configs, loaded certs, cert manager).
+    async fn current_tls_configs(&self) -> HashMap<String, TlsCertConfig> {
+        let mut configs = Self::extract_tls_configs(&self.options.routes);
+
+        // Merge dynamically loaded certs (from loadCertificate IPC)
+        for (d, c) in &self.loaded_certs {
+            if !configs.contains_key(d) {
+                configs.insert(d.clone(), c.clone());
+            }
+        }
+
+        // Merge certs from cert manager store
+        if let Some(ref cm_arc) = self.cert_manager {
+            let cm = cm_arc.lock().await;
+            for (d, b) in cm.store().iter() {
+                if !configs.contains_key(d) {
+                    configs.insert(d.clone(), TlsCertConfig {
+                        cert_pem: b.cert_pem.clone(),
+                        key_pem: b.key_pem.clone(),
+                    });
+                }
+            }
+        }
+
+        configs
+    }
+
     /// Set the Unix domain socket path for relaying UDP datagrams to TypeScript datagramHandler callbacks.
     pub async fn set_datagram_handler_relay_path(&mut self, path: Option<String>) {
         info!("Datagram handler relay path set to: {:?}", path);
@@ -1055,37 +1101,21 @@ impl RustProxy {
             key_pem: key_pem.clone(),
         });
 
-        // Hot-swap TLS config on the listener
-        if let Some(ref mut listener) = self.listener_manager {
-            let mut tls_configs = Self::extract_tls_configs(&self.options.routes);
+        // Hot-swap TLS config on TCP and QUIC listeners
+        let tls_configs = self.current_tls_configs().await;
 
-            // Add the new cert
-            tls_configs.insert(domain.to_string(), TlsCertConfig {
-                cert_pem: cert_pem.clone(),
-                key_pem: key_pem.clone(),
-            });
-
-            // Also include all existing certs from cert manager
-            if let Some(ref cm_arc) = self.cert_manager {
-                let cm = cm_arc.lock().await;
-                for (d, b) in cm.store().iter() {
-                    if !tls_configs.contains_key(d) {
-                        tls_configs.insert(d.clone(), TlsCertConfig {
-                            cert_pem: b.cert_pem.clone(),
-                            key_pem: b.key_pem.clone(),
-                        });
-                    }
-                }
-            }
-
-            // Merge dynamically loaded certs from previous loadCertificate calls
-            for (d, c) in &self.loaded_certs {
-                if !tls_configs.contains_key(d) {
-                    tls_configs.insert(d.clone(), c.clone());
-                }
-            }
+        if let Some(ref listener) = self.listener_manager {
+            // Build QUIC TLS config before TCP consumes the map
+            let quic_tls = Self::build_quic_tls_config(&tls_configs);
 
             listener.set_tls_configs(tls_configs);
+
+            // Also update QUIC endpoints with the new certs
+            if let Some(ref udp_mgr) = self.udp_listener_manager {
+                if let Some(quic_config) = quic_tls {
+                    udp_mgr.update_quic_tls(quic_config);
+                }
+            }
         }
 
         info!("Certificate loaded and TLS config updated for {}", domain);

ts/00_commitinfo_data.ts

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

ts/proxies/smart-proxy/utils/route-validator.ts

@@ -7,7 +7,7 @@ import type { IRouteConfig, IRouteMatch, IRouteAction, TPortRange } from '../mod
 export class RouteValidator {
   private static readonly VALID_TLS_MODES = ['terminate', 'passthrough', 'terminate-and-reencrypt'];
   private static readonly VALID_ACTION_TYPES = ['forward', 'socket-handler'];
-  private static readonly VALID_PROTOCOLS = ['tcp', 'http', 'https', 'ws', 'wss'];
+  private static readonly VALID_PROTOCOLS = ['tcp', 'http', 'https', 'ws', 'wss', 'udp', 'quic', 'http3'];
   private static readonly MAX_PORTS = 100;
   private static readonly MAX_DOMAINS = 1000;
   private static readonly MAX_HEADER_SIZE = 8192;
@@ -173,6 +173,22 @@ export class RouteValidator {
           }
         }
       }
+
+      // QUIC routes require TLS with termination (QUIC mandates TLS 1.3)
+      if (route.action.udp?.quic && route.action.type === 'forward') {
+        if (!route.action.tls) {
+          errors.push('QUIC routes require TLS configuration (action.tls) — QUIC mandates TLS 1.3');
+        } else if (route.action.tls.mode === 'passthrough') {
+          errors.push('QUIC routes cannot use TLS mode "passthrough" — use "terminate" or "terminate-and-reencrypt"');
+        }
+      }
+
+      // Protocol quic/http3 requires transport udp or all
+      if (route.match?.protocol && ['quic', 'http3'].includes(route.match.protocol)) {
+        if (route.match.transport && route.match.transport !== 'udp' && route.match.transport !== 'all') {
+          errors.push(`Protocol "${route.match.protocol}" requires transport "udp" or "all"`);
+        }
+      }
     }
 
     // Validate security settings
@@ -619,6 +635,15 @@ export function validateRouteAction(action: IRouteAction): { valid: boolean; err
     }
   }
 
+  // QUIC routes require TLS with termination
+  if (action.udp?.quic && action.type === 'forward') {
+    if (!action.tls) {
+      errors.push('QUIC routes require TLS configuration — QUIC mandates TLS 1.3');
+    } else if (action.tls.mode === 'passthrough') {
+      errors.push('QUIC routes cannot use TLS mode "passthrough"');
+    }
+  }
+
   if (action.type === 'socket-handler') {
     if (!action.socketHandler && !action.datagramHandler) {
       errors.push('Socket handler or datagram handler function is required for socket-handler action');