Crate web_faith_alt_svc 

An HTTP/3 upgrade (via Alt-Svc primarily) mechanism for reqwest.

An origin advertises HTTP/3 in an Alt-Svc header or an HTTPS DNS record. The alternative service may be unreachable even when advertised, and trying would unnecessarily fail and waste a request.

AltSvcCache is an in-memory store which keeps track of these advertisements, and decides per origin whether HTTP/3 is worth attempting.

AltSvcMiddleware then acts on that decision. There are two flavours, depending on whether you want to do background probes (with H3Prober) or not:

• With, advertisements are verified in the background, and foreground requests use HTTP/3 only once an origin is confirmed, so no user-visible request pays for discovering a broken alternative service.
• Without, the next foreground request is itself the verification, falling back to TCP if it does not produce headers in time.

The middleware also monitors connections and intelligently demotes and promotes origins between QUIC and TCP:

• if QUIC connections to the origin start failing,
• if the QUIC path becomes noticeably slower than the TCP path (PathTime),
• retries the upgrade after an exponential cooldown.

Examples

use reqwest::Url;
use web_faith_alt_svc::{AltSvcAdvertisement, AltSvcCache, AltSvcCacheConfig};

let cache = AltSvcCache::new(AltSvcCacheConfig::default());
let origin = Url::parse("https://example.com/").expect("a valid URL");

// Inject an advertisement; usually this would either be a provided hint or come from the
// middleware.
let advertised: AltSvcAdvertisement = r#"h3=":443"; ma=86400"#.parse().expect("h3 is advertised");
cache.record_alt_svc(&origin, &advertised);
assert_eq!(cache.confirmed_port(&origin), None);

// Now that there's an advertisement, a probe against the origin has something to try.
let port = cache.probe_candidate(&origin).expect("worth probing");
cache.confirm_h3(&origin, port);
assert_eq!(cache.confirmed_port(&origin), Some(443));

Use H3HttpsSink to additionally support the DNS discovery of HTTP/3 services (using the HTTPS record type).

use std::sync::Arc;

use web_faith_alt_svc::{AltSvcCache, AltSvcCacheConfig, H3HttpsSink};
use web_faith_dns::{FaithResolver, ResolverConfig};

let cache = Arc::new(AltSvcCache::new(AltSvcCacheConfig::default()));
let resolver = FaithResolver::new(ResolverConfig::default());

// The resolver will now query for `HTTPS` records, and if any exist, populate the
// Alt-Svc cache even before we start connecting.
resolver.set_https_sink(Arc::new(H3HttpsSink::new(cache, None)));

Structs

AltSvcAdvertisement

An HTTP/3 alternative service parsed out of an Alt-Svc header.

AltSvcCache

An in-memory store of HTTP/3 advertisements.

AltSvcCacheConfig

Configuration for initialising the AltSvcCache.

AltSvcEntry

One origin’s entry in the store.

AltSvcMiddleware

A reqwest middleware for HTTP/3 upgrades.

H3HttpsSinkdns

DNS discovery of HTTP/3 services via the HTTPS record type.

H3Prober

HTTP probe to verify HTTP/3 service advertisements.

NoHttp3Alternative

The header advertised no HTTP/3 alternative service.

PathTime

An estimate of network path time to an origin.