MASQUE

What "building blocks" means

hopf-masque ships no proxy binary and no example crate. It gives an application, on the server side, two ServerHandlerFactory implementations that plug into any of hopf-http's H1/H2/H3 servers, and, on the client side (feature h3), two functions that dial a proxy the same way any other hopf-http request would. What each side does past accepting/dialling the tunnel differs by protocol:

• CONNECT-UDP is a complete relay on its own. ConnectUdpFactory resolves the request's {host}/{port} target via a supplied DnsResolver, opens a real outbound UDP socket on one of the supplied Runtime's workers, and pumps datagrams between it and the HTTP Datagram / Capsule Protocol channel for the tunnel's lifetime (crates/hopf-masque/src/relay.rs). The only thing an application supplies is a ConnectUdpPolicy deciding which resolved targets to allow.
• CONNECT-IP has no relay of its own. RFC 9484's target/ipproto segments are optionally wildcarded and are never resolved by this crate — what a hostname, IP literal, IP prefix, or bare * even means is left to the deployment (RFC 9484 itself takes no position either). hopf-masque therefore has zero packet-forwarding code: no TUN device, no userspace router, no kernel network stack dependency anywhere in the workspace. ConnectIpFactory only parses the target, asks a ConnectIpPolicy whether to accept it, and — once accepted — hands the application a ConnectIpHandler that receives raw decoded IP packets and address requests and a ConnectIpSession to send packets, assign addresses, and advertise routes back. What happens to a packet in between is entirely the application's job.
• The client side (feature h3) is a dial helper, not a user agent. connect_udp/connect_ip build the RFC 9298/9484 request, negotiate transport through hopf_http::connect_auto (h3 first when a QUIC client config is supplied, falling back per HttpFallback), and hand the application a session handle plus an event-handler trait. There is no bundled SOCKS-to-MASQUE or TUN-to-MASQUE adapter — an application wanting to expose a MASQUE tunnel as, say, a local SOCKS proxy or a virtual network interface has to write that glue itself.

In short: CONNECT-UDP is proxy-grade out of the box (bring a policy); CONNECT-IP is protocol plumbing only (bring a policy and a forwarder).

Standards

CONNECT-UDP server (ConnectUdpFactory)

ConnectUdpFactory::new(dns, runtime, policy) builds a ServerHandlerFactory to hand to any hopf-http server (H1, H2, or H3 via listen_h3). Per accepted request it: matches the Extended-CONNECT or Upgrade shape for connect-udp, requires Capsule-Protocol: ?1, parses the target path, resolves it via the supplied DnsResolver, asks the policy, opens an outbound UDP socket on one of the supplied Runtime's workers, and installs a ConnectUdpRelay (ProtocolUpgradeHandler) that pumps datagrams both ways until closed or idle.

URI template (RFC 9298 §2): /.well-known/masque/udp/{target_host}/{target_port}/ — both segments required, non-empty, percent-encoded (needed for an IPv6 literal's colons).

use hopf_masque::{ConnectUdpFactory, ConnectUdpPolicy};
use std::net::IpAddr;
use std::sync::Arc;

struct OnlyPort443;
impl ConnectUdpPolicy for OnlyPort443 {
    fn is_target_allowed(&self, _addr: IpAddr, port: u16) -> bool {
        port == 443
    }
}

let factory = ConnectUdpFactory::new(dns_resolver, Arc::clone(&runtime), Arc::new(OnlyPort443))
    .with_idle_timeout(std::time::Duration::from_secs(120));
// `factory` is a `ServerHandlerFactory` — wrap it the same way as any
// other hopf-http server handler (CleartextHttpEndpoint, TLS, or listen_h3).

The relay's idle timer is self-rearming: any traffic in either direction resets it, and a full idle_timeout with none tears the tunnel down. Opening the outbound socket happens off the reactor thread entirely (a plain, dedicated thread) — ReactorHandle::register_udp's blocking round trip would deadlock if run from the same worker it targets, the same constraint hopf-mdns's own one-time registration documents.

CONNECT-IP server (ConnectIpFactory)

ConnectIpFactory::new(app, policy) builds a ServerHandlerFactory. Per accepted request it matches the Extended-CONNECT/Upgrade shape for connect-ip, requires Capsule-Protocol: ?1, parses the target/ipproto scope, asks the policy, then — with no DNS lookup or socket of its own to open — synchronously builds an app-supplied ConnectIpHandler and installs a ConnectIpRelay.

URI template (RFC 9484 §3): /.well-known/masque/ip/{target}/{ipproto}/ — both segments required (either may be the literal *); target may be a hostname, an IPv4/IPv6 address, or an address+prefix (the slash before the prefix length is itself percent-encoded, e.g. 192.0.2.0%2F24, RFC 9484 §3's own example).

use hopf_masque::{
    ConnectIpFactory, ConnectIpHandler, ConnectIpHandlerFactory, ConnectIpPolicy,
    ConnectIpSession, IpProto, IpTarget,
};
use std::net::IpAddr;
use std::sync::Arc;

struct AllowWildcardOnly;
impl ConnectIpPolicy for AllowWildcardOnly {
    fn is_target_allowed(&self, target: &IpTarget, _ipproto: &IpProto) -> bool {
        matches!(target, IpTarget::Wildcard)
    }
}

struct EchoHandler { session: Option<Arc<dyn ConnectIpSession>> }
impl ConnectIpHandler for EchoHandler {
    fn opened(&mut self, session: Arc<dyn ConnectIpSession>) { self.session = Some(session); }
    fn packet_received(&mut self, packet: &[u8]) {
        if let Some(s) = &self.session { s.send_packet(packet); } // trivial echo
    }
}
struct EchoHandlerFactory;
impl ConnectIpHandlerFactory for EchoHandlerFactory {
    fn create_handler(&self) -> Box<dyn ConnectIpHandler> {
        Box::new(EchoHandler { session: None })
    }
}

let factory = ConnectIpFactory::new(Arc::new(EchoHandlerFactory), Arc::new(AllowWildcardOnly));

RFC 9484 capsules

crate::ip_capsule (private) codes the three RFC 9484 capsule types CONNECT-IP layers on top of hopf_http::capsule's generic Capsule Protocol framing (RFC 9297 §3); DATAGRAM itself needs no codec of its own here since it carries an opaque, context_id-prefixed payload both CONNECT-UDP and CONNECT-IP already share.

HTTP Datagrams and the Capsule Protocol

Both CONNECT-UDP and CONNECT-IP are unconditional Capsule Protocol users: crate::accept::accept_headers always sets Capsule-Protocol: ?1 on the 200/101 accept response, and both server request handlers reject any request missing Capsule-Protocol: ?1 of its own (via hopf_http::capsule::capsule_protocol_enabled) with a 400 before ever looking at the target. Neither this crate's relays nor its clients implement the RFC 9297 §6 fallback of raw, non-capsule HTTP Datagrams for H3 — every payload here, on every transport (H1/H2/H3 alike), goes through the generic hopf_http::capsule DATAGRAM capsule and the hopf_http::context_id varint prefix, keeping the wire format identical across transports rather than branching on whether native QUIC DATAGRAM frames are available.

ProtocolUpgradeHandler::wants_datagrams always returns true for every upgrade handler in this crate; datagram_received/capsule_received decode the Context ID or capsule type and dispatch to the relay/client event handler. See QUIC / HTTP/3 for how hopf-http itself demultiplexes HTTP Datagrams and Capsule Protocol capsules onto a request stream.

CONNECT-UDP client (connect_udp)

Feature h3 only (needs hopf-http/h3 and hopf-quic for the transport-negotiating dial path, the same reason hopf-http itself gates h3). Dials proxy_host:proxy_port via hopf_http::connect_auto — an h3 attempt first when a QuicClientConfig is supplied, falling back per HttpFallback, exactly as any other outbound hopf-http request negotiates transport — and relays to target_host:target_port once the proxy accepts.

unix_path, when set, dials the proxy over a UNIX domain socket instead of TCP/IP/QUIC (proxy_host/proxy_port/quic_client_config/resolver are then used only to fill the Host header, since QUIC/h3 has no UNIX-domain transport); HttpFallback::Tls is not yet supported for a UNIX-domain dial.

CONNECT-IP client (connect_ip)

Mirrors connect_udp closely — same transport negotiation, same unix_path caveat — scoped to a target/ipproto pair (either may be a wildcard) instead of a concrete resolved host/port, and with the extra RFC 9484 capsule types surfaced on the event handler.

Each send_address_request call encodes its whole slice into one ADDRESS_REQUEST capsule together — call it again separately if a later, distinct request shouldn't share a capsule with one already in flight.

Cargo features

In the hopf umbrella crate: feature masque pulls in hopf-masque (plus its own dns/http features); feature masque-h3 additionally enables hopf-masque/h3 (and the umbrella's own h3 feature) for the client functions.

Example

No example binary ships yet (see Limitations). This is adapted from the crate's own loopback test suite (crates/hopf-masque/src/integration.rs), which is the most realistic end-to-end usage currently in the tree — a CONNECT-UDP server relay accepting a request, plus a client dialling it and round-tripping one datagram through a UDP echo target:

use hopf_core::{ProtocolHandler, Runtime, RuntimeConfig, TcpListenerConfig};
use hopf_dns::DnsResolver;
use hopf_http::{AltSvcCache, CleartextHttpEndpoint, HttpClientTimeouts, HttpFallback, HttpLimits};
use hopf_masque::{connect_udp, ConnectUdpEventHandler, ConnectUdpFactory, ConnectUdpPolicy, ConnectUdpSession};
use std::net::IpAddr;
use std::sync::Arc;

struct AllowAny; // never do this in a real deployment
impl ConnectUdpPolicy for AllowAny {
    fn is_target_allowed(&self, _addr: IpAddr, _port: u16) -> bool { true }
}

// --- server: accept CONNECT-UDP over plain HTTP/1.1 ---
let rt = Arc::new(Runtime::start(RuntimeConfig::default())?);
let dns = Arc::new(DnsResolver::for_runtime(&rt)?);
let factory = Arc::new(ConnectUdpFactory::new(dns, Arc::clone(&rt), Arc::new(AllowAny)));
let (server_addr, _) = rt.add_tcp_listener(TcpListenerConfig::new(
    "127.0.0.1:0".parse()?,
    move || Box::new(CleartextHttpEndpoint::new(
        Arc::clone(&factory) as _, HttpLimits::default(),
    )) as Box<dyn ProtocolHandler>,
))?;

// --- client: dial the relay, tunnel to a UDP target through it ---
struct PrintHandler;
impl ConnectUdpEventHandler for PrintHandler {
    fn opened(&mut self, session: Arc<dyn ConnectUdpSession>) {
        session.send_datagram(b"ping");
    }
    fn datagram_received(&mut self, data: &[u8]) {
        println!("target replied: {data:?}");
    }
}

connect_udp(
    &rt,
    &server_addr.ip().to_string(), server_addr.port(),
    "udp-target.example", 53,
    HttpFallback::PlaintextH1,
    Box::new(PrintHandler),
    None,                          // no QUIC client config -> h1/h2 only
    Arc::new(AltSvcCache::new()),
    HttpClientTimeouts::default(),
    None,                          // default resolver
    None,                          // no UNIX-domain dial
)?;

Limitations

• No example binaries or CLI proxy tool ship for either protocol — the crate is consumed as a library, and there is nothing in examples/ exercising it.
• CONNECT-IP does no target resolution, address allocation, or packet forwarding of its own — an application must supply both a ConnectIpPolicy and a real ConnectIpHandler/ConnectIpHandlerFactory for a tunnel to do anything beyond accept.
• Neither protocol falls back to raw, non-capsule HTTP Datagrams over native QUIC DATAGRAM frames (RFC 9297 §6) — every payload goes through Capsule Protocol framing unconditionally, on every transport including H3. A peer that only speaks the non-capsule form is rejected (missing Capsule-Protocol: ?1 is a 400).
• CONNECT-UDP's relay resolves a target hostname once, using the first address DnsResolver::resolve returns — there is no Happy-Eyeballs-style multi-address racing and no re-resolution mid-tunnel.
• The server-side ConnectUdpPolicy/ConnectIpPolicy traits have no permissive default anywhere in the crate by design — omitting a real policy is a compile-time (constructor-argument) requirement, not a runtime opt-in an application could silently skip.
• connect_udp/connect_ip require the h3 feature even for an application that only ever wants h1/h2 fallback — the shared connect_auto dial path pulls in hopf-quic regardless of whether a QuicClientConfig is actually supplied at the call site.
• No standalone MASQUE proxy application, and no bundled adapter exposing an accepted tunnel as a SOCKS proxy or a virtual network interface — see What "building blocks" means.

Implementation status

Shipped: RFC 9298 CONNECT-UDP, both server relay and client, feature-complete against the RFC's URI template and Context ID framing, over H1, H2, and H3. RFC 9484 CONNECT-IP's protocol plumbing — target/ipproto parsing including wildcards, Extended CONNECT/Upgrade acceptance, all three RFC 9484 capsule types (ADDRESS_ASSIGN, ADDRESS_REQUEST, ROUTE_ADVERTISEMENT), and the client side — is complete and interop-tested end to end against this crate's own relay (loopback, not against an external MASQUE implementation). Both protocols share hopf-http's Capsule Protocol/HTTP Datagram machinery and reuse the same Extended-CONNECT/Upgrade acceptance helper (crate::accept).

Known gaps: CONNECT-IP ships no actual IP forwarding — that is an explicit non-goal of this crate, not an oversight, per What "building blocks" means. No example binaries exist for either protocol. No non-capsule HTTP Datagram fallback. See Limitations for the rest.

See also

• QUIC / HTTP/3 — the H3 transport CONNECT-UDP/CONNECT-IP dial through, and where the underlying HTTP Datagram/Capsule Protocol demux lives
• HTTP overview
• HTTP server
• HTTP client
• WebSocket — the other ProtocolUpgradeHandler-based upgrade in the tree
• DNS — DnsResolver, used by ConnectUdpFactory to resolve CONNECT-UDP targets

GitHub