use std::collections::HashMap;
use std::net::SocketAddr;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, RwLock};
use std::time::Duration;
use bytes::Buf;
use crate::body::{RequestBody, ResponseBody};
use crate::error::{Error, Result};
use crate::pool::PoolConfig;
use crate::response::Response;
use crate::timeout::TimeoutPhase;
use crate::transport::datagram::{DatagramDialer, RouteUdpSocket, ROUTE_IO_ERROR_CODE, ROUTE_MTU};
use crate::transport::dialer::{DialError, DialErrorKind};
use crate::transport::metrics::{H3CloseKind, H3CloseSummary, H3ConnectionDiagnostic, H3RouteKind};
pub(crate) const H3_CACHE_MAX_ENTRIES: usize = 64;
pub(crate) const H3_DEFAULT_IDLE_TIMEOUT: Duration = Duration::from_secs(30);
pub(crate) const H3_DEFAULT_MAX_BIDI_STREAMS: u32 = 100;
pub(crate) const H3_DEFAULT_MAX_UNI_STREAMS: u32 = 100;
type H3Sender = h3::client::SendRequest<h3_quinn::OpenStreams, bytes::Bytes>;
struct CachedH3Sender {
sender: H3Sender,
_driver: tokio::task::JoinHandle<()>,
draining: Arc<AtomicBool>,
#[allow(
dead_code,
reason = "preserved upstream close code for diagnostics via test hook"
)]
close_reason: Arc<std::sync::Mutex<Option<String>>>,
alt_generation: Option<u64>,
_route_endpoint: Option<quinn::Endpoint>,
route_socket: Option<Arc<RouteUdpSocket>>,
}
#[derive(Debug, Clone)]
pub(crate) struct H3DispatchError {
pub(crate) error: crate::error::Error,
pub(crate) body_committed: bool,
pub(crate) draining: bool,
pub(crate) failure_class: super::alt_svc::H3FailureClass,
}
impl H3DispatchError {
fn new(error: crate::error::Error, body_committed: bool, draining: bool) -> Self {
let failure_class = super::alt_svc::H3FailureClass::from_error(&error);
Self {
error,
body_committed,
draining,
failure_class,
}
}
pub(crate) fn for_total_timeout(elapsed: Duration) -> Self {
Self::new(
crate::error::Error::Timeout {
phase: crate::timeout::TimeoutPhase::Total,
elapsed,
},
false,
false,
)
}
pub(crate) fn safe_for_fallback(&self) -> bool {
!self.body_committed
}
}
#[derive(Debug, Clone)]
pub(crate) struct H3AltTarget {
pub(crate) alt_host: String,
pub(crate) alt_port: u16,
pub(crate) sni_host: String,
pub(crate) generation: Option<u64>,
}
type CachedH3SenderCell = Arc<tokio::sync::OnceCell<CachedH3Sender>>;
type H3SenderCache = Arc<RwLock<HashMap<String, CachedH3SenderCell>>>;
fn h3_cache_get(cache: &H3SenderCache, key: &str) -> Option<CachedH3SenderCell> {
cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.get(key)
.cloned()
}
fn h3_cache_insert(cache: &H3SenderCache, key: String, cell: CachedH3SenderCell) {
cache
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.insert(key, cell);
}
fn h3_cache_remove(cache: &H3SenderCache, key: &str) {
cache
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.remove(key);
}
fn h3_cache_get_or_insert_default(cache: &H3SenderCache, key: String) -> CachedH3SenderCell {
if let Some(cell) = h3_cache_get(cache, &key) {
return cell;
}
let mut table = cache
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if let Some(cell) = table.get(&key).cloned() {
return cell;
}
let cell: CachedH3SenderCell = Arc::new(tokio::sync::OnceCell::new());
table.insert(key, cell.clone());
cell
}
#[derive(Clone)]
pub(crate) struct H3Connector {
endpoint: Option<quinn::Endpoint>,
datagram_dialer: Option<Arc<dyn DatagramDialer>>,
tls_config: Option<crate::tls::TlsConfig>,
sender_cache: H3SenderCache,
quinn_idle_timeout: Duration,
max_bidi_streams: u32,
metrics: Option<Arc<crate::transport::metrics::TransportMetrics>>,
}
fn derive_quinn_idle_timeout(pool_config: &PoolConfig) -> Duration {
pool_config.idle_timeout.unwrap_or(H3_DEFAULT_IDLE_TIMEOUT)
}
fn derive_max_bidi_streams(pool_config: &PoolConfig) -> u32 {
match pool_config.effective_max_in_flight_per_origin() {
Some(n) => u32::try_from(n).unwrap_or(u32::MAX).max(1),
None => H3_DEFAULT_MAX_BIDI_STREAMS,
}
}
fn remaining_connect_budget(deadline: Option<std::time::Instant>) -> Option<Duration> {
deadline.map(|d| d.saturating_duration_since(std::time::Instant::now()))
}
fn h3_close_summary(error: &quinn::ConnectionError, graceful: bool) -> H3CloseSummary {
let (kind, code) = match error {
quinn::ConnectionError::VersionMismatch => (H3CloseKind::VersionMismatch, None),
quinn::ConnectionError::TransportError(error) => {
(H3CloseKind::TransportError, Some(error.code.into()))
}
quinn::ConnectionError::ConnectionClosed(close) => {
(H3CloseKind::ConnectionClosed, Some(close.error_code.into()))
}
quinn::ConnectionError::ApplicationClosed(close) => (
H3CloseKind::ApplicationClosed,
Some(close.error_code.into()),
),
quinn::ConnectionError::Reset => (H3CloseKind::Reset, None),
quinn::ConnectionError::TimedOut => (H3CloseKind::TimedOut, None),
quinn::ConnectionError::LocallyClosed => (H3CloseKind::LocallyClosed, None),
quinn::ConnectionError::CidsExhausted => (H3CloseKind::CidsExhausted, None),
};
H3CloseSummary {
kind,
code,
graceful,
}
}
fn h3_connection_diagnostic(
connection: &quinn::Connection,
route: H3RouteKind,
alt_svc_generation: Option<u64>,
close: Option<&quinn::ConnectionError>,
graceful: bool,
) -> H3ConnectionDiagnostic {
let stats = connection.stats();
H3ConnectionDiagnostic {
stable_id: connection.stable_id(),
remote_address: connection.remote_address(),
local_ip: connection.local_ip(),
route,
alt_svc_generation,
rtt: connection.rtt(),
sent_packets: stats.path.sent_packets,
received_datagrams: stats.udp_rx.datagrams,
lost_packets: stats.path.lost_packets,
sent_bytes: stats.udp_tx.bytes,
received_bytes: stats.udp_rx.bytes,
lost_bytes: stats.path.lost_bytes,
close: close.map(|error| h3_close_summary(error, graceful)),
open_streams: None,
}
}
fn h3_close_label(error: &quinn::ConnectionError, graceful: bool) -> String {
let summary = h3_close_summary(error, graceful);
match summary.code {
Some(code) => format!("{:?}:{code}", summary.kind),
None => format!("{:?}", summary.kind),
}
}
fn route_close(conn: Option<&quinn::Connection>) {
if let Some(conn) = conn {
conn.close(
quinn::VarInt::from_u32(ROUTE_IO_ERROR_CODE),
b"datagram route",
);
}
}
fn build_route_endpoint(socket: Arc<RouteUdpSocket>) -> std::io::Result<quinn::Endpoint> {
let runtime = quinn::default_runtime().ok_or_else(|| {
std::io::Error::new(
std::io::ErrorKind::Unsupported,
"no QUIC runtime available for datagram route",
)
})?;
let mut endpoint_config = quinn::EndpointConfig::default();
endpoint_config
.max_udp_payload_size(u16::try_from(ROUTE_MTU).unwrap_or(u16::MAX))
.map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, e))?;
quinn::Endpoint::new_with_abstract_socket(endpoint_config, None, socket, runtime)
}
fn route_dial_error(failure: DialError) -> Error {
match failure.kind() {
DialErrorKind::Connection => {
Error::H3Connect(format!("QUIC handshake failed: {}", failure.message()))
}
DialErrorKind::Timeout => Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: Duration::ZERO,
},
DialErrorKind::Authentication | DialErrorKind::Rejected | DialErrorKind::Other => {
Error::CustomTransport(Arc::new(failure))
}
}
}
struct RouteOwnedChain {
socket: Arc<RouteUdpSocket>,
endpoint: quinn::Endpoint,
watcher: tokio::sync::watch::Receiver<bool>,
}
impl H3Connector {
#[allow(
dead_code,
reason = "kept for unit tests without metrics; client paths use with_metrics"
)]
pub(crate) fn new(
tls_config: Option<crate::tls::TlsConfig>,
pool_config: &PoolConfig,
) -> Result<Self> {
Self::with_metrics(tls_config, pool_config, None)
}
pub(crate) fn with_metrics(
tls_config: Option<crate::tls::TlsConfig>,
pool_config: &PoolConfig,
metrics: Option<Arc<crate::transport::metrics::TransportMetrics>>,
) -> Result<Self> {
Self::with_datagram_route(tls_config, pool_config, metrics, None)
}
pub(crate) fn with_datagram_route(
tls_config: Option<crate::tls::TlsConfig>,
pool_config: &PoolConfig,
metrics: Option<Arc<crate::transport::metrics::TransportMetrics>>,
datagram_dialer: Option<Arc<dyn DatagramDialer>>,
) -> Result<Self> {
let endpoint = if datagram_dialer.is_some() {
None
} else {
let bind_addr = "0.0.0.0:0"
.parse()
.map_err(|e| Error::Connect(format!("invalid QUIC bind address: {e}")))?;
Some(
quinn::Endpoint::client(bind_addr)
.map_err(|e| Error::Connect(format!("failed to create QUIC endpoint: {e}")))?,
)
};
Ok(Self {
endpoint,
datagram_dialer,
tls_config,
sender_cache: Arc::new(RwLock::new(HashMap::new())),
quinn_idle_timeout: derive_quinn_idle_timeout(pool_config),
max_bidi_streams: derive_max_bidi_streams(pool_config),
metrics,
})
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for bounded-cache assertions")]
pub(crate) fn cache_len(&self) -> usize {
self.sender_cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.len()
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for eviction assertions")]
pub(crate) fn contains_origin(&self, origin_key: &str) -> bool {
self.sender_cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.contains_key(origin_key)
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for idle-policy assertions")]
pub(crate) fn quinn_idle_timeout(&self) -> Duration {
self.quinn_idle_timeout
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for stream-limit assertions")]
pub(crate) fn max_bidi_streams(&self) -> u32 {
self.max_bidi_streams
}
fn cache_key(host: &str, port: u16) -> String {
format!("{host}:{port}")
}
fn ensure_cache_bound(&self, except_key: &str) {
let victim = {
let table = self
.sender_cache
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if table.len() < H3_CACHE_MAX_ENTRIES {
return;
}
table.keys().find(|k| *k != except_key).cloned()
};
if let Some(victim) = victim {
h3_cache_remove(&self.sender_cache, &victim);
if let Some(ref m) = self.metrics {
m.record_h3_eviction();
}
}
}
fn evict_if_current(&self, key: &str, cell: &CachedH3SenderCell) {
let is_current = h3_cache_get(&self.sender_cache, key)
.is_some_and(|current| Arc::ptr_eq(¤t, cell));
if is_current {
let mut table = self
.sender_cache
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if table
.get(key)
.is_some_and(|current| Arc::ptr_eq(current, cell))
{
table.remove(key);
if let Some(ref m) = self.metrics {
m.record_h3_eviction();
}
}
}
}
async fn resolve_addrs(
host: &str,
port: u16,
deadline: Option<std::time::Instant>,
connect_budget: Option<Duration>,
started: std::time::Instant,
) -> Result<Vec<SocketAddr>> {
let lookup = tokio::net::lookup_host(format!("{host}:{port}"));
let addrs: Vec<SocketAddr> = match remaining_connect_budget(deadline) {
Some(remaining) => tokio::time::timeout(remaining, lookup)
.await
.map_err(|_| Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
})?
.map_err(|e| Error::Connect(format!("DNS resolve: {e}")))?
.collect(),
None => lookup
.await
.map_err(|e| Error::Connect(format!("DNS resolve: {e}")))?
.collect(),
};
if addrs.is_empty() {
return Err(Error::Connect("no addresses resolved".into()));
}
let _ = connect_budget;
Ok(addrs)
}
async fn connect_with_fallback(
&self,
endpoint: &quinn::Endpoint,
addrs: &[SocketAddr],
host: &str,
deadline: Option<std::time::Instant>,
started: std::time::Instant,
) -> Result<quinn::Connection> {
let mut last_err: Option<Error> = None;
for (idx, addr) in addrs.iter().enumerate() {
let addrs_left = u32::try_from(addrs.len().saturating_sub(idx)).unwrap_or(u32::MAX);
let remaining = remaining_connect_budget(deadline).map(|r| {
let share = r.checked_div(addrs_left.max(1)).unwrap_or(r);
share
});
if deadline.is_some_and(|d| std::time::Instant::now() >= d)
|| remaining.is_some_and(|r| r.is_zero())
{
return Err(last_err.unwrap_or(Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
}));
}
match self
.connect_single(endpoint, *addr, host, remaining, started)
.await
{
Ok(conn) => return Ok(conn),
Err(e) => {
last_err = Some(e);
}
}
}
Err(last_err.unwrap_or_else(|| Error::Connect("no addresses resolved".into())))
}
async fn connect_single(
&self,
endpoint: &quinn::Endpoint,
addr: SocketAddr,
host: &str,
remaining: Option<Duration>,
started: std::time::Instant,
) -> Result<quinn::Connection> {
let quic_config = build_quic_client_config(
self.tls_config.as_ref(),
self.quinn_idle_timeout,
self.max_bidi_streams,
)?;
let connecting = endpoint
.connect_with(quic_config, addr, host)
.map_err(|e| Error::Connect(format!("QUIC connect: {e}")))?;
let conn = match remaining {
Some(budget) => tokio::time::timeout(budget, connecting)
.await
.map_err(|_| Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
})?
.map_err(|e| Error::H3Connect(format!("QUIC handshake failed: {e}")))?,
None => connecting
.await
.map_err(|e| Error::H3Connect(format!("QUIC handshake failed: {e}")))?,
};
Ok(conn)
}
async fn establish_routed_generation(
&self,
target: crate::transport::dialer::DialTarget,
sni_host: &str,
deadline: Option<std::time::Instant>,
started: std::time::Instant,
alt_generation: Option<u64>,
route_kind: H3RouteKind,
) -> Result<CachedH3Sender> {
let dialer = self
.datagram_dialer
.as_ref()
.ok_or_else(|| Error::Connect("no datagram dialer configured".into()))?;
let route = match remaining_connect_budget(deadline) {
Some(remaining) => tokio::time::timeout(remaining, dialer.connect(target))
.await
.map_err(|_| Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
})?,
None => dialer.connect(target).await,
}
.map_err(route_dial_error)?;
let socket = RouteUdpSocket::from_route(route);
let watcher = socket.failure_watcher();
let endpoint = build_route_endpoint(Arc::clone(&socket))
.map_err(|e| Error::Connect(format!("datagram route endpoint: {e}")))?;
let quic_config = build_quic_client_config(
self.tls_config.as_ref(),
self.quinn_idle_timeout,
self.max_bidi_streams,
)?;
let peer = socket.peer_addr();
let connecting = endpoint
.connect_with(quic_config, peer, sni_host)
.map_err(|e| Error::Connect(format!("QUIC connect: {e}")))?;
let conn = match remaining_connect_budget(deadline) {
Some(remaining) => tokio::time::timeout(remaining, connecting)
.await
.map_err(|_| Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
})?
.map_err(|e| Error::H3Connect(format!("QUIC handshake failed: {e}")))?,
None => connecting
.await
.map_err(|e| Error::H3Connect(format!("QUIC handshake failed: {e}")))?,
};
let sender = Self::establish_h3_sender(
conn,
deadline,
started,
alt_generation,
route_kind,
self.metrics.clone(),
Some(RouteOwnedChain {
socket,
endpoint,
watcher,
}),
)
.await?;
Ok(sender)
}
async fn establish_h3_sender(
quinn_conn: quinn::Connection,
deadline: Option<std::time::Instant>,
started: std::time::Instant,
alt_generation: Option<u64>,
route: H3RouteKind,
metrics: Option<Arc<crate::transport::metrics::TransportMetrics>>,
route_chain: Option<RouteOwnedChain>,
) -> Result<CachedH3Sender> {
let diagnostic_conn = quinn_conn.clone();
let diagnostic_conn_for_route = quinn_conn.clone();
let route_socket: Option<Arc<RouteUdpSocket>> =
route_chain.as_ref().map(|chain| Arc::clone(&chain.socket));
let route_watcher: Option<tokio::sync::watch::Receiver<bool>> =
route_chain.as_ref().map(|chain| chain.watcher.clone());
let route_endpoint: Option<quinn::Endpoint> = route_chain.map(|chain| chain.endpoint);
let init = async {
let h3_conn = h3_quinn::Connection::new(quinn_conn);
h3::client::new(h3_conn)
.await
.map_err(|e| Error::H3Protocol(format!("h3 client init: {e}")))
};
let (mut driver, sender) = match remaining_connect_budget(deadline) {
Some(remaining) => {
tokio::time::timeout(remaining, init)
.await
.map_err(|_| Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: started.elapsed(),
})??
}
None => init.await?,
};
let draining: Arc<AtomicBool> = Arc::new(AtomicBool::new(false));
let close_reason: Arc<std::sync::Mutex<Option<String>>> =
Arc::new(std::sync::Mutex::new(None));
let draining_for_driver = draining.clone();
let reason_for_driver = close_reason.clone();
let metrics_for_driver = metrics.clone();
if let Some(ref m) = metrics {
m.record_h3_diagnostic(h3_connection_diagnostic(
&diagnostic_conn,
route,
alt_generation,
None,
false,
));
}
let driver_handle = tokio::spawn(async move {
use futures_util::future;
let close_err = match route_watcher {
Some(mut watcher) => {
if *watcher.borrow() {
route_close(Some(&diagnostic_conn_for_route));
}
tokio::select! {
biased;
() = async {
while !*watcher.borrow_and_update() {
if watcher.changed().await.is_err() {
return;
}
}
} => {
route_close(Some(&diagnostic_conn_for_route));
future::poll_fn(|cx| driver.poll_close(cx)).await
}
close_err = future::poll_fn(|cx| driver.poll_close(cx)) => close_err,
}
}
None => future::poll_fn(|cx| driver.poll_close(cx)).await,
};
draining_for_driver.store(true, Ordering::Relaxed);
let graceful = close_err.is_h3_no_error();
let quinn_close = diagnostic_conn.close_reason();
if let Ok(mut guard) = reason_for_driver.lock() {
*guard = quinn_close
.as_ref()
.map(|error| h3_close_label(error, graceful));
}
if let Some(m) = metrics_for_driver {
if let Some(error) = quinn_close.as_ref() {
m.record_h3_diagnostic(h3_connection_diagnostic(
&diagnostic_conn,
route,
alt_generation,
Some(error),
graceful,
));
}
m.record_h3_closed();
if graceful {
m.record_h3_drain();
}
}
});
Ok(CachedH3Sender {
sender,
_driver: driver_handle,
draining,
close_reason,
alt_generation,
_route_endpoint: route_endpoint,
route_socket,
})
}
fn route_error_override(route_socket: Option<&Arc<RouteUdpSocket>>, fallback: Error) -> Error {
let Some(socket) = route_socket else {
return fallback;
};
let Some(failure) = socket.route_failure() else {
return fallback;
};
match failure.kind() {
DialErrorKind::Connection => {
Error::H3Connect(format!("QUIC handshake failed: {}", failure.message()))
}
DialErrorKind::Timeout => Error::Timeout {
phase: TimeoutPhase::Connect,
elapsed: Duration::ZERO,
},
DialErrorKind::Authentication | DialErrorKind::Rejected | DialErrorKind::Other => {
Error::CustomTransport(Arc::new(failure))
}
}
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for drain assertions")]
pub(crate) fn is_draining_key(&self, origin_key: &str) -> bool {
h3_cache_get(&self.sender_cache, origin_key).is_some_and(|r| {
r.get()
.is_some_and(|cached| cached.draining.load(Ordering::Relaxed))
})
}
#[cfg(any(test, feature = "test-util"))]
#[allow(dead_code, reason = "test hook for close-code assertions")]
pub(crate) fn close_reason_key(&self, origin_key: &str) -> Option<String> {
h3_cache_get(&self.sender_cache, origin_key).and_then(|r| {
let cached = r.get()?;
cached.close_reason.lock().ok()?.clone()
})
}
#[allow(
dead_code,
reason = "kept for unit tests; pipeline uses send_request_with_alt"
)]
pub(crate) async fn send_request(
&self,
request: http::Request<RequestBody>,
url: url::Url,
connect_timeout: Option<Duration>,
) -> Result<Response> {
self.send_request_inner(request, url, None, connect_timeout)
.await
.map_err(|e| e.error)
}
pub(crate) async fn send_request_with_alt(
&self,
request: http::Request<RequestBody>,
url: url::Url,
alt: Option<H3AltTarget>,
connect_timeout: Option<Duration>,
) -> std::result::Result<Response, H3DispatchError> {
self.send_request_inner(request, url, alt, connect_timeout)
.await
}
#[allow(
clippy::too_many_lines,
reason = "H3 dispatch centralizes connect/fallback/drain policy so transports do not reimplement it"
)]
async fn send_request_inner(
&self,
request: http::Request<RequestBody>,
url: url::Url,
alt: Option<H3AltTarget>,
connect_timeout: Option<Duration>,
) -> std::result::Result<Response, H3DispatchError> {
let map_err = |e: Error, committed: bool, draining: bool| {
H3DispatchError::new(e, committed, draining)
};
let host = url
.host_str()
.ok_or_else(|| map_err(Error::InvalidUrl("missing host".into()), false, false))?;
let port = url.port_or_known_default().unwrap_or(443);
let cache_key = Self::cache_key(host, port);
let host_owned = host.to_owned();
let (resolve_host, resolve_port, sni_host, alt_generation) = match &alt {
Some(a) => (
a.alt_host.clone(),
a.alt_port,
a.sni_host.clone(),
a.generation,
),
None => (host_owned.clone(), port, host_owned.clone(), None),
};
self.ensure_cache_bound(&cache_key);
let mut cell = h3_cache_get_or_insert_default(&self.sender_cache, cache_key.clone());
let mut was_reconnect = false;
if let Some(cached) = cell.get() {
let stale_generation = cached.alt_generation != alt_generation;
let draining = cached.draining.load(Ordering::Relaxed);
if stale_generation || draining {
self.evict_if_current(&cache_key, &cell);
let fresh: CachedH3SenderCell = Arc::new(tokio::sync::OnceCell::new());
self.ensure_cache_bound(&cache_key);
h3_cache_insert(&self.sender_cache, cache_key.clone(), fresh.clone());
cell = fresh;
was_reconnect = true;
}
}
let cached = if let Some(cached) = cell.get() {
cached
} else {
let started = std::time::Instant::now();
let deadline = connect_timeout.map(|d| started + d);
let endpoint_self = self.clone();
let resolve_host_clone = resolve_host.clone();
let sni_host_clone = sni_host.clone();
let route_kind = if alt.is_some() {
H3RouteKind::AltSvc
} else {
H3RouteKind::Explicit
};
let init_result: std::result::Result<&CachedH3Sender, Error> = cell
.get_or_try_init(|| async {
let sender = if endpoint_self.datagram_dialer.is_some() {
endpoint_self
.establish_routed_generation(
crate::transport::dialer::DialTarget::new(
&resolve_host_clone,
resolve_port,
),
&sni_host_clone,
deadline,
started,
alt_generation,
route_kind,
)
.await?
} else {
let endpoint = endpoint_self
.endpoint
.as_ref()
.ok_or_else(|| Error::Connect("no QUIC endpoint available".into()))?;
let addrs = Self::resolve_addrs(
&resolve_host_clone,
resolve_port,
deadline,
connect_timeout,
started,
)
.await?;
let quinn_conn = endpoint_self
.connect_with_fallback(
endpoint,
&addrs,
&sni_host_clone,
deadline,
started,
)
.await?;
Self::establish_h3_sender(
quinn_conn,
deadline,
started,
alt_generation,
route_kind,
endpoint_self.metrics.clone(),
None,
)
.await?
};
if let Some(ref m) = endpoint_self.metrics {
m.record_h3_created();
if was_reconnect {
m.record_h3_reconnected();
}
}
Ok(sender)
})
.await;
match init_result {
Ok(cached) => cached,
Err(e) => {
return Err(map_err(e.clone(), false, false));
}
}
};
let sender = cached.sender.clone();
let route_socket = cached.route_socket.clone();
let with_route_evidence =
|error: Error| Self::route_error_override(route_socket.as_ref(), error);
let (parts, body) = request.into_parts();
let mut h3_request = http::Request::builder()
.method(parts.method)
.uri(parts.uri)
.version(parts.version);
for (name, value) in &parts.headers {
h3_request = h3_request.header(name, value);
}
let h3_request = h3_request
.body(())
.map_err(|e| map_err(Error::RequestBuild(e.to_string()), false, false))?;
let mut request_stream = {
let mut sender = sender;
match sender.send_request(h3_request).await {
Ok(stream) => stream,
Err(e) => {
let draining = {
use h3::ConnectionState;
sender.is_closing()
};
if draining {
if let Some(cached) = cell.get() {
cached.draining.store(true, Ordering::Relaxed);
}
if let Some(ref m) = self.metrics {
m.record_h3_drain();
}
}
self.evict_if_current(&cache_key, &cell);
if draining {
return Err(map_err(
Error::H3ConnectionClosed("peer draining (GOAWAY)".into()),
false,
true,
));
}
return Err(map_err(
with_route_evidence(Error::H3Protocol(format!("send request: {e}"))),
false,
false,
));
}
}
};
let send_body_result = async {
match body {
RequestBody::Empty => Ok(()),
RequestBody::Bytes(bytes) => request_stream
.send_data(bytes)
.await
.map_err(|e| Error::H3Protocol(format!("send data: {e}"))),
RequestBody::Stream {
stream: body_stream,
..
} => {
use futures_util::StreamExt;
let mut body_stream = body_stream;
while let Some(chunk) = body_stream.next().await {
let bytes = chunk?;
request_stream
.send_data(bytes)
.await
.map_err(|e| Error::H3Protocol(format!("send data: {e}")))?;
}
Ok(())
}
}
}
.await;
if let Err(e) = send_body_result {
let transport_failure = matches!(
e,
Error::H3Protocol(_)
| Error::H3ConnectionClosed(_)
| Error::H3Stream(_)
| Error::H3Connect(_)
);
if transport_failure {
self.evict_if_current(&cache_key, &cell);
}
return Err(map_err(with_route_evidence(e), true, false));
}
if let Err(err) = request_stream.finish().await {
self.evict_if_current(&cache_key, &cell);
return Err(map_err(
with_route_evidence(Error::H3Protocol(format!("finish stream: {err}"))),
true,
false,
));
}
let response = match request_stream.recv_response().await {
Ok(response) => response,
Err(e) => {
self.evict_if_current(&cache_key, &cell);
return Err(map_err(
with_route_evidence(Error::H3Protocol(format!("recv response: {e}"))),
true,
false,
));
}
};
let status = response.status();
let resp_version = response.version();
let mut resp_headers = http::HeaderMap::new();
for (name, value) in response.headers() {
resp_headers.insert(name.clone(), value.clone());
}
let cache_for_body = self.sender_cache.clone();
let key_for_body = cache_key.clone();
let cell_for_body = cell.clone();
let route_for_body = route_socket.clone();
let trailers = crate::body::SharedTrailers::new();
let trailers_for_body = trailers.clone();
let body_stream = futures_util::stream::unfold(
(request_stream, false),
move |(mut stream, trailers_done)| {
let cache_for_body = cache_for_body.clone();
let key_for_body = key_for_body.clone();
let cell_for_body = cell_for_body.clone();
let trailers_for_body = trailers_for_body.clone();
let route_for_body = route_for_body.clone();
async move {
if trailers_done {
return None;
}
match stream.recv_data().await {
Ok(Some(mut data)) => {
let bytes = data.copy_to_bytes(data.remaining());
Some((Ok::<_, Error>(bytes), (stream, false)))
}
Ok(None) => {
match stream.recv_trailers().await {
Ok(Some(headers)) => {
trailers_for_body.store(headers);
}
Ok(None) => {}
Err(e) => {
if h3_cache_get(&cache_for_body, &key_for_body).is_some_and(
|current| Arc::ptr_eq(¤t, &cell_for_body),
) {
h3_cache_remove(&cache_for_body, &key_for_body);
}
return Some((
Err(Self::route_error_override(
route_for_body.as_ref(),
Error::H3Protocol(format!("recv trailers: {e}")),
)),
(stream, true),
));
}
}
None
}
Err(e) => {
if h3_cache_get(&cache_for_body, &key_for_body)
.is_some_and(|current| Arc::ptr_eq(¤t, &cell_for_body))
{
h3_cache_remove(&cache_for_body, &key_for_body);
}
Some((
Err(Self::route_error_override(
route_for_body.as_ref(),
Error::H3Protocol(format!("recv data: {e}")),
)),
(stream, true),
))
}
}
}
},
);
let body = ResponseBody::streaming(Box::pin(body_stream));
let mut core_response = Response::new(status, resp_version, resp_headers, url, body);
core_response.set_trailers(trailers);
Ok(core_response)
}
}
fn build_quic_client_config(
tls_config: Option<&crate::tls::TlsConfig>,
idle_timeout: Duration,
max_bidi_streams: u32,
) -> Result<quinn::ClientConfig> {
let default_tls_config = crate::tls::TlsConfig::default();
let tls_config = tls_config.unwrap_or(&default_tls_config);
let rc = tls_config.build_quic_rustls_config()?;
let quic_crypto = quinn::crypto::rustls::QuicClientConfig::try_from(rc)
.map_err(|e| Error::Tls(format!("QUIC TLS config conversion: {e}")))?;
let mut quic_config = quinn::ClientConfig::new(Arc::new(quic_crypto));
let mut transport = quinn::TransportConfig::default();
transport.max_concurrent_bidi_streams(max_bidi_streams.into());
transport.max_concurrent_uni_streams(H3_DEFAULT_MAX_UNI_STREAMS.into());
transport.max_idle_timeout(Some(
quinn::IdleTimeout::try_from(idle_timeout)
.map_err(|e| Error::Tls(format!("invalid idle timeout: {e}")))?,
));
quic_config.transport_config(Arc::new(transport));
Ok(quic_config)
}
#[cfg(test)]
mod tests {
use super::*;
fn pool_with(idle: Option<Duration>, per_host: Option<usize>) -> PoolConfig {
PoolConfig {
idle_timeout: idle,
max_connections_per_host: per_host,
..PoolConfig::default()
}
}
#[test]
fn idle_defaults_to_thirty_seconds() {
let derived = derive_quinn_idle_timeout(&pool_with(None, None));
assert_eq!(derived, Duration::from_secs(30));
}
#[test]
fn idle_follows_keepalive_expiry() {
let derived = derive_quinn_idle_timeout(&pool_with(Some(Duration::from_secs(5)), None));
assert_eq!(derived, Duration::from_secs(5));
}
#[test]
fn bidi_defaults_to_one_hundred() {
assert_eq!(derive_max_bidi_streams(&pool_with(None, None)), 100);
}
#[test]
fn bidi_follows_per_host_limit() {
assert_eq!(derive_max_bidi_streams(&pool_with(None, Some(10))), 10);
assert_eq!(derive_max_bidi_streams(&pool_with(None, Some(1000))), 1000);
}
#[test]
fn cache_bound_is_sixty_four() {
assert_eq!(H3_CACHE_MAX_ENTRIES, 64);
}
#[test]
fn close_classification_is_sanitized_and_preserves_codes() {
let graceful = quinn::ConnectionError::ApplicationClosed(quinn::ApplicationClose {
error_code: quinn::VarInt::from_u32(0x100),
reason: bytes::Bytes::from_static(b"peer reason must not escape"),
});
let summary = h3_close_summary(&graceful, true);
assert_eq!(summary.kind, H3CloseKind::ApplicationClosed);
assert_eq!(summary.code, Some(0x100));
assert!(summary.graceful);
assert!(!format!("{summary:?}").contains("peer reason"));
let non_graceful = h3_close_summary(&quinn::ConnectionError::Reset, false);
assert_eq!(non_graceful.kind, H3CloseKind::Reset);
assert_eq!(non_graceful.code, None);
assert!(!non_graceful.graceful);
}
#[test]
fn quic_config_uses_derived_policy() {
let _ = build_quic_client_config(None, Duration::from_secs(5), 10).expect("quic config");
let _ = build_quic_client_config(None, Duration::from_secs(30), 100).expect("quic config");
}
#[cfg(any(test, feature = "test-util"))]
#[tokio::test]
async fn connector_derives_policy_from_pool() {
let pool = pool_with(Some(Duration::from_secs(7)), Some(12));
let connector = H3Connector::new(None, &pool).expect("connector");
assert_eq!(connector.quinn_idle_timeout(), Duration::from_secs(7));
assert_eq!(connector.max_bidi_streams(), 12);
}
#[cfg(any(test, feature = "test-util"))]
#[tokio::test]
async fn connector_defaults_match_legacy_behavior() {
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector");
assert_eq!(connector.quinn_idle_timeout(), Duration::from_secs(30));
assert_eq!(connector.max_bidi_streams(), 100);
assert_eq!(connector.cache_len(), 0);
}
#[tokio::test]
async fn cache_bound_evicts_without_losing_current_origin() {
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector builds");
for i in 0..(H3_CACHE_MAX_ENTRIES + 10) {
let key = format!("host-{i}.example:443");
connector.ensure_cache_bound(&key);
h3_cache_get_or_insert_default(&connector.sender_cache, key);
}
assert!(
connector.cache_len() <= H3_CACHE_MAX_ENTRIES,
"cache must stay bounded, got {}",
connector.cache_len()
);
let current = format!("host-{}.example:443", H3_CACHE_MAX_ENTRIES + 9);
assert!(connector.contains_origin(¤t));
}
#[tokio::test]
async fn evictions_increment_transport_metrics() {
let metrics = Arc::new(crate::transport::metrics::TransportMetrics::new());
let connector =
H3Connector::with_metrics(None, &PoolConfig::default(), Some(metrics.clone()))
.expect("connector builds");
for i in 0..(H3_CACHE_MAX_ENTRIES + 5) {
let key = format!("host-{i}.example:443");
connector.ensure_cache_bound(&key);
h3_cache_get_or_insert_default(&connector.sender_cache, key);
}
let evictions = metrics
.h3_cache_evictions
.load(std::sync::atomic::Ordering::Relaxed);
assert!(
evictions >= 5,
"bounded evictions must be counted, got {evictions}"
);
}
#[test]
fn bidi_follows_new_in_flight_name() {
let pool = PoolConfig {
max_in_flight_requests_per_origin: Some(9),
..PoolConfig::default()
};
assert_eq!(derive_max_bidi_streams(&pool), 9);
}
#[tokio::test]
async fn evict_if_current_scopes_to_failed_generation() {
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector builds");
let key = "example.com:443".to_owned();
let first: CachedH3SenderCell = Arc::new(tokio::sync::OnceCell::new());
h3_cache_insert(&connector.sender_cache, key.clone(), first.clone());
let second: CachedH3SenderCell = Arc::new(tokio::sync::OnceCell::new());
h3_cache_insert(&connector.sender_cache, key.clone(), second.clone());
connector.evict_if_current(&key, &first);
assert!(
connector.contains_origin(&key),
"eviction of a stale cell must not remove the current generation"
);
connector.evict_if_current(&key, &second);
assert!(
!connector.contains_origin(&key),
"eviction of the current cell must remove the stale origin"
);
}
#[test]
fn remaining_budget_saturates_at_zero() {
let past = std::time::Instant::now()
.checked_sub(Duration::from_secs(1))
.expect("recent instant");
assert_eq!(
remaining_connect_budget(Some(past)),
Some(Duration::ZERO),
"an expired deadline must yield zero, not panic"
);
assert!(remaining_connect_budget(None).is_none());
}
#[cfg(test)]
struct LocalH3Server {
addr: SocketAddr,
shutdown: tokio::sync::watch::Sender<bool>,
}
#[cfg(test)]
impl LocalH3Server {
#[allow(
clippy::unused_async,
clippy::unused_async_trait_impl,
reason = "kept async to match the integration-test fixture shape; the awaits live in the spawned task"
)]
async fn start(body: Vec<u8>) -> Self {
use rustls::pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer};
let cert_key =
rcgen::generate_simple_self_signed(vec!["localhost".into()]).expect("rcgen cert");
let cert_der = CertificateDer::from(cert_key.cert.der().to_vec());
let key_der =
PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(cert_key.key_pair.serialize_der()));
let mut server_tls = rustls::ServerConfig::builder_with_provider(Arc::new(
rustls::crypto::ring::default_provider(),
))
.with_protocol_versions(&[&rustls::version::TLS13])
.expect("TLS13")
.with_no_client_auth()
.with_single_cert(vec![cert_der], key_der)
.expect("cert");
server_tls.alpn_protocols = vec![b"h3".to_vec()];
let quic_crypto = quinn::crypto::rustls::QuicServerConfig::try_from(server_tls)
.expect("server crypto");
let mut server_config = quinn::ServerConfig::with_crypto(Arc::new(quic_crypto));
let mut transport = quinn::TransportConfig::default();
transport.max_concurrent_bidi_streams(100u32.into());
transport.max_concurrent_uni_streams(100u32.into());
server_config.transport_config(Arc::new(transport));
let endpoint = quinn::Endpoint::server(server_config, "127.0.0.1:0".parse().unwrap())
.expect("bind server");
let addr = endpoint.local_addr().expect("addr");
let body = bytes::Bytes::from(body);
let (tx, mut rx) = tokio::sync::watch::channel(false);
tokio::spawn(async move {
loop {
tokio::select! {
incoming = endpoint.accept() => {
let Some(incoming) = incoming else { break };
let body = body.clone();
tokio::spawn(async move {
let Ok(conn) = incoming.await else { return };
let h3_conn = h3_quinn::Connection::new(conn);
let Ok(mut server) =
h3::server::Connection::<_, bytes::Bytes>::new(h3_conn).await
else {
return;
};
loop {
let Ok(Some(resolver)) = server.accept().await else { break };
let body = body.clone();
let Ok((_req, mut stream)) =
resolver.resolve_request().await
else {
continue;
};
while stream.recv_data().await.ok().flatten().is_some() {}
let resp = http::Response::builder()
.status(200)
.body(())
.unwrap();
if stream.send_response(resp).await.is_err() {
break;
}
let _ = stream.send_data(body).await;
let _ = stream.finish().await;
}
});
}
_ = rx.changed() => break,
}
}
});
Self { addr, shutdown: tx }
}
}
#[cfg(test)]
impl Drop for LocalH3Server {
fn drop(&mut self) {
let _ = self.shutdown.send(true);
}
}
#[cfg(test)]
struct Blackhole {
_socket: std::net::UdpSocket,
addr: SocketAddr,
}
#[cfg(test)]
impl Blackhole {
fn bind() -> Self {
let socket =
std::net::UdpSocket::bind("127.0.0.1:0").expect("bind blackhole UDP socket");
socket.set_nonblocking(true).expect("blackhole nonblocking");
let addr = socket.local_addr().expect("blackhole addr");
Self {
_socket: socket,
addr,
}
}
}
#[tokio::test]
async fn failed_init_does_not_poison_origin() {
let blackhole = Blackhole::bind();
let closed_port = {
let s = std::net::UdpSocket::bind("127.0.0.1:0").expect("probe bind");
s.local_addr().expect("probe addr").port()
};
let _ = &blackhole;
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector builds");
let started = std::time::Instant::now();
let deadline = Some(started + Duration::from_millis(300));
let bad = vec![SocketAddr::from(([127, 0, 0, 1], closed_port))];
let endpoint = connector
.endpoint
.as_ref()
.expect("unit tests use a direct connector");
let first = connector
.connect_with_fallback(endpoint, &bad, "localhost", deadline, started)
.await;
assert!(first.is_err(), "expected handshake failure, got {first:?}");
}
#[tokio::test]
async fn oncecell_failure_leaves_cell_empty() {
let cell = tokio::sync::OnceCell::<u32>::new();
let first: std::result::Result<&u32, &'static str> =
cell.get_or_try_init(|| async { Err("boom") }).await;
assert!(first.is_err());
assert!(cell.get().is_none(), "failed init must not poison the cell");
let second: std::result::Result<&u32, &'static str> =
cell.get_or_try_init(|| async { Ok(7u32) }).await;
assert_eq!(*second.expect("retry succeeds"), 7);
}
#[tokio::test]
async fn fallback_skips_unreachable_address() {
let server = LocalH3Server::start(b"fallback-ok".to_vec()).await;
let closed_port = {
let s = std::net::UdpSocket::bind("127.0.0.1:0").expect("probe bind");
s.local_addr().expect("probe addr").port()
};
let tls = crate::tls::TlsConfig::builder()
.danger_accept_invalid_certs(true)
.build();
let connector =
H3Connector::new(Some(tls), &PoolConfig::default()).expect("connector builds");
let started = std::time::Instant::now();
let deadline = Some(started + Duration::from_secs(8));
let addrs = vec![SocketAddr::from(([127, 0, 0, 1], closed_port)), server.addr];
let conn = tokio::time::timeout(
Duration::from_secs(20),
connector.connect_with_fallback(
connector
.endpoint
.as_ref()
.expect("unit tests use a direct connector"),
&addrs,
"localhost",
deadline,
started,
),
)
.await
.expect("fallback test must not hang")
.expect("fallback to reachable address succeeds");
assert_eq!(conn.remote_address(), server.addr);
}
#[tokio::test]
async fn connect_budget_fires_connect_phase_timeout() {
let blackhole = Blackhole::bind();
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector builds");
let started = std::time::Instant::now();
let budget = Duration::from_millis(200);
let deadline = Some(started + budget);
let err = connector
.connect_with_fallback(
connector
.endpoint
.as_ref()
.expect("unit tests use a direct connector"),
std::slice::from_ref(&blackhole.addr),
"localhost",
deadline,
started,
)
.await
.expect_err("blackhole handshake must not succeed");
match err {
Error::Timeout {
phase: TimeoutPhase::Connect,
..
} => {}
other => panic!("expected connect-phase timeout, got {other:?}"),
}
}
#[tokio::test]
async fn fallback_cancellation_aborts_promptly() {
let blackhole = Blackhole::bind();
let connector = H3Connector::new(None, &PoolConfig::default()).expect("connector builds");
let started = std::time::Instant::now();
let deadline = Some(started + Duration::from_secs(30));
let pending = connector.connect_with_fallback(
connector
.endpoint
.as_ref()
.expect("unit tests use a direct connector"),
std::slice::from_ref(&blackhole.addr),
"localhost",
deadline,
started,
);
let aborted = tokio::time::timeout(Duration::from_millis(200), pending).await;
assert!(
aborted.is_err(),
"cancellation must abort the pending connect promptly"
);
}
#[tokio::test]
async fn write_timeout_propagates_without_masking() {
let server = LocalH3Server::start(b"ok".to_vec()).await;
let tls = crate::tls::TlsConfig::builder()
.danger_accept_invalid_certs(true)
.build();
let connector =
H3Connector::new(Some(tls), &PoolConfig::default()).expect("connector builds");
let stalled = futures_util::stream::pending::<std::result::Result<bytes::Bytes, Error>>();
let wrapped =
crate::stream::write_timeout_stream(Box::pin(stalled), Duration::from_millis(100));
let body = RequestBody::Stream {
stream: wrapped,
length: None,
};
let uri: http::Uri = format!("https://127.0.0.1:{}/", server.addr.port())
.parse()
.expect("uri");
let http_req = http::Request::builder()
.method(http::Method::POST)
.uri(uri)
.version(http::Version::HTTP_3)
.body(body)
.expect("request");
let url =
url::Url::parse(&format!("https://127.0.0.1:{}/", server.addr.port())).expect("url");
let err = connector
.send_request(http_req, url, Some(Duration::from_secs(10)))
.await
.expect_err("stalled body must fail");
match err {
Error::Timeout {
phase: TimeoutPhase::Write,
..
} => {}
other => panic!("expected write-phase timeout, got {other:?}"),
}
let key = format!("127.0.0.1:{}", server.addr.port());
assert!(
connector.contains_origin(&key),
"write timeout must not evict the shared connection"
);
let _ = server;
}
}