Module connect_ip 

Available on crate feature masque only.

IP proxying over HTTP (RFC 9484), using rama_net::ip packet primitives.

ConnectIpTemplate builds H1 Upgrade and H2/H3 Extended CONNECT requests. ConnectIpConnector wraps an existing HTTP client; ConnectIpService combines a request admission service with a packet-session handler. Admission returns ConnectIpSessionConfig; its ConnectIpPolicy defaults to deny all. Authenticate before admission and explicitly authorize source/destination prefixes. Peer address assignments and routes never grant local permission.

ConnectIpSession is the application packet boundary: send/receive entire IP packets, exchange control snapshots, or split it into send/receive halves. No host interface, route, DNS configuration or privileges are changed. Route and address capsules replace complete snapshots; the caller owns allocation and any administrative installation. The server pins resolved hostname scope for the tunnel lifetime, visible through ConnectIpSession::policy.

Construct a scoped request

use rama_masque::connect_ip::{ConnectIpScope, ConnectIpTemplate};
use rama_http::Version;

let template = ConnectIpTemplate::try_new(
    "https://proxy.example/.well-known/masque/ip/{target}/{ipproto}/",
)?;
let scope = ConnectIpScope::new(
    rama_masque::connect_ip::IpTarget::Prefix("192.0.2.0/24".parse()?),
).with_protocol(rama_net::ip::IpProtocol::UDP);
let request = template.request(&scope, Version::HTTP_3)?;
assert_eq!(template.match_request(&request)?, scope);

Forwarding and MTU

IpPacketOrigin::Forwarded decrements TTL/hop limit once on encapsulation; IpPacketOrigin::Local preserves packets already prepared by a local stack. Receipt does not decrement it. Link-local traffic cannot be forwarded across links. Use rama_net::ip::icmp::encode_icmp_error for bounded forwarding-error replies, choosing an authorized source and applying a rate limit. Invalid or unauthorized incoming packets are dropped before delivery to the handler. A client’s receive-source policy must also authorize intermediate routers whose ICMP errors it needs (including Packet Too Big for path MTU discovery). Router addresses may lie outside the target scope; the quoted flow is still checked against that scope and local permissions.

IPv6 is disabled until an end-to-end link MTU is guaranteed in configuration or ConnectIpSession::probe_ipv6_mtu succeeds. A local QUIC datagram limit alone does not prove an intermediary path. Native shrink below 1280 aborts the tunnel; oversized native packets do not silently switch to Capsules. H1/H2 and H3 without negotiated datagrams use reliable Capsule delivery and inherit its head-of-line blocking. Packet/byte budgets and send deadlines apply to both carriers. Closing the send half leaves reception active. Dropping an unfinished half aborts the tunnel; completed halves can be dropped independently.

No IP reassembly, jumbograms, NAT, DHCP, platform TUN, context compression, or DNS/PREF64 protocol extensions are implemented here.

Structs

AddressAssignment

One source prefix assigned to the peer. An assignment capsule is a full snapshot.

AddressRequest

A preferred source prefix requested from the peer.

AddressRequestId

A nonzero address request identifier in the QUIC variable-length range.

ConnectIpConnector

Adapt an HTTP client into a service opening prepared CONNECT-IP sessions.

ConnectIpPolicy

Packet policy evaluated after decoding and before delivery/transmission.

ConnectIpReceiver

The unique receive half; malformed control closes the request stream.

ConnectIpRequest

Input to the admission service, before DNS resolution and HTTP acceptance.

ConnectIpRequestBuilder

Prepare a CONNECT-IP handshake from a configured endpoint and typed scope.

ConnectIpScope

Destination and protocol requested by the client, before local authorization.

ConnectIpSender

The unique send half; state is shared with the receive half.

ConnectIpService

A Rama CONNECT-IP proxy service, independent of the platform packet interface.

ConnectIpSession

One CONNECT-IP stream, independent of HTTP version and platform packet interfaces.

ConnectIpSessionConfig

Configuration shared by a tunnel’s send and receive halves.

ConnectIpState

Validated, directional address/route state for one CONNECT-IP request stream.

ConnectIpStateLimits

Bounds for directional control state, independent of packet queue limits.

ConnectIpStateSnapshot

Immutable packet-routing state, without the request-ID history. Cloning an Arc to this view does not copy routes, assignments or request maps.

ConnectIpStats

Cheap counters without addresses, payloads or credentials.

ConnectIpTemplate

A configured CONNECT-IP HTTPS URI template, shared by clients and server matchers.

IpDirectionPolicy

Local permissions for a packet direction; defaults to deny all.

IpRoute

An inclusive IP address range the sender is willing to route.

Enums

ConnectIpCapsule

CONNECT-IP control capsules. Unknown capsules are skipped by the HTTP session.

ConnectIpError

Terminal session failures. Ordinary IP forwarding errors are reported as drops.

ConnectIpEvent

Observable tunnel events. Control snapshots have already been validated/applied.

ConnectIpProtocolError

Invalid CONNECT-IP control state or framing. No peer data is included in errors.

ConnectIpRequestError

A configuration or HTTP handshake error. Peer-controlled values are not echoed.

ConnectIpRole

Which endpoint originated the HTTP request.

IpPacketDrop

Why an IP packet was dropped. Control errors use a separate terminal error path.

IpPacketOrigin

Whether an outgoing packet was generated here or is crossing links.

IpPacketSend

Result of a packet send. Unreliable delivery does not imply peer receipt.

IpSourcePolicy

Source-address authorization for one direction.

IpTarget

Requested destination scope. A name is resolved once under server policy.

Constants

ADDRESS_ASSIGN

ADDRESS_ASSIGN (RFC 9484 §4.7.1).

ADDRESS_REQUEST

ADDRESS_REQUEST (RFC 9484 §4.7.2).

ROUTE_ADVERTISEMENT

ROUTE_ADVERTISEMENT (RFC 9484 §4.7.3).

Functions

decode_ip_datagram

Decode a datagram’s context ID without imposing a UDP payload limit. Unknown context IDs are returned so the session can discard them.

encode_ip_datagram

Prefix an IP packet with context zero. IP validation belongs to the packet/session API.

validate_connect_ip_response

Validate the proxy’s response before exposing packet I/O.

validate_routes

Validate the wire ordering, disjointness and all-protocol overlap rules.