Struct AddressPolicy 

pub struct AddressPolicy { /* private fields */ }

Outbound address policy carried by crate::ClientConfig::address_policy.

The default is public-web policy: only public addresses are reachable. Callers add extra denials with AddressPolicy::deny_ranges and AddressPolicy::deny_if, and open specific non-public destinations with AddressPolicy::allow_if. Custom denials always win over allowances.

Implementations

impl AddressPolicy

pub fn public_web() -> Self

Public-web policy: only public addresses are reachable. This is the default.

pub fn first_party(hosts: Vec<String>) -> Self

First-party policy: only the listed hosts (exact match, ASCII case-insensitive, one trailing dot ignored), only over HTTPS, on any redirect hop as well. The resolved addresses of those hosts are classified with the public-web classes too, so a listed name that resolves to a private address is refused; opt a host out with AddressPolicy::allow_private_resolution. Link-local and metadata destinations stay denied and the custom denials below still apply.

pub fn is_first_party(&self) -> bool

True for a policy built with AddressPolicy::first_party.

pub fn allow_legacy_ipv4(self) -> Self

Accept non-canonical IPv4 host spellings (127.1, 0177.0.0.1, 0x7f.0.0.1, 2130706433, 1.1.1.1.) and read them as inet_aton does. They are refused by default with crate::HttpError::AddressDenied, because parsers disagree about them (some read 0177.0.0.1 as decimal 177), and that mismatch is an SSRF bypass. No legitimate URL spells a host this way. Cloud metadata and the address classes still apply to an accepted spelling.

pub fn allow_insecure_redirects(self) -> Self

Follow redirects from HTTPS to plain HTTP. Refused by default: the redirect target (often a signed URL) would travel unencrypted and the answer could not be trusted.

pub fn allows_redirect(&self, from_scheme: &str, to_scheme: &str) -> bool

False for a redirect from HTTPS to plain HTTP, unless AddressPolicy::allow_insecure_redirects was set. Other transports use it to apply the same rule.

pub fn allow_private_resolution(self, host: impl Into<String>) -> Self

Let a first-party host resolve to non-public addresses (loopback, RFC 1918, …), for example an on-premises server. Exact host match like AddressPolicy::first_party. Link-local and metadata addresses, deny_ranges and deny_if still refuse. It has no effect on hosts that are not first-party.

pub fn deny_ranges(self, ranges: Vec<IpNet>) -> Self

Deny these ranges in addition to the class rules. An IPv6 address that embeds an IPv4 address is also tested by its embedded IPv4 address.

pub fn deny_if<F>(self, f: F) -> Self

where F: Fn(&IpAddr) -> Option<String> + Send + Sync + 'static,

Deny addresses for which f returns Some(text). The text becomes the reason of crate::HttpError::AddressDenied. f also sees the embedded IPv4 address of an IPv6 form. Several hooks run in the order added.

pub fn allow_if<F>(self, hosts: Vec<String>, pred: F) -> Self

where F: Fn(&IpAddr) -> bool + Send + Sync + 'static,

Let the explicitly listed hosts (exact match, like AddressPolicy::first_party) reach addresses for which pred is true, even when their class is denied by default. It does not apply to other hosts, never overrides link-local or metadata denials, and never overrides deny_ranges or deny_if.

pub fn with_resolver<F>(self, f: F) -> Self

where F: Fn(&str) -> Vec<IpAddr> + Send + Sync + 'static,

Replace the system resolver (offline tests, pinned DNS, split-horizon setups). The hook gets the normalized host name and returns every address for it.

pub fn resolve_vetted( &self, host: &str, port: u16, ) -> Result<Vec<SocketAddr>, HttpError>

Resolve host once and vet every address with exactly the rules the HTTP clients use: the address classes, deny_ranges, deny_if, allow_if, the first-party host pin and its private-resolution opt-outs, metadata names, and the rule that a name with no address is denied. Returns the vetted socket addresses on port. The error is the same HttpError::AddressDenied the clients return; a failed lookup is a HttpError::Transport or HttpError::Timeout in Phase::Connect.

Other transports (a WebSocket, a raw TCP or gRPC client) use it to apply the identical policy, and must connect to the returned addresses and not look the name up again. A transport that cannot pin the connection to these addresses leaves a DNS-rebinding window between this check and its own lookup.

The host is treated as reached over HTTPS: a first-party policy checks the host pin but cannot see the caller’s transport, so requiring TLS stays the caller’s job. A system lookup is bounded at ten seconds.

Trait Implementations

impl Clone for AddressPolicy

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AddressPolicy

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AddressPolicy

fn default() -> Self

Returns the “default value” for a type.