Struct HttpAclBuilder 

pub struct HttpAclBuilder { /* private fields */ }

A builder for HttpAcl.

Most categories (methods, hosts, port ranges, IP ranges, headers, URL paths, static DNS mappings) follow the same set of methods: add_allowed_*/ add_denied_* to add a single entry, remove_allowed_*/remove_denied_* to remove one, allowed_*/denied_* to replace the whole list at once, and clear_allowed_*/clear_denied_* to empty it. The fallible variants return AddError rather than panicking, e.g. when an entry is already present on the opposite list, so a host (or header, port range, and so on) can never end up allowed and denied at the same time.

Call Self::build or Self::try_build to finish. Only the latter validates the finished configuration (uniqueness, overlaps, non-global IP ranges); see their docs for when each applies.

Implementations

impl HttpAclBuilder

pub fn new() -> HttpAclBuilder

Create a new HttpAclBuilder.

pub fn http(self, allow: bool) -> HttpAclBuilder

Sets whether HTTP is allowed.

pub fn https(self, allow: bool) -> HttpAclBuilder

Sets whether HTTPS is allowed.

pub fn non_global_ip_ranges(self, allow: bool) -> HttpAclBuilder

Sets whether non-global IP ranges are allowed.

Non-global IP ranges include private, loopback, link-local, and other special-use addresses.

pub fn method_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for HTTP methods if no ACL match is found.

pub fn host_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for hosts if no ACL match is found.

pub fn port_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for ports if no ACL match is found.

pub fn ip_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for IPs if no ACL match is found.

pub fn header_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for headers if no ACL match is found.

pub fn url_path_acl_default(self, allow: bool) -> HttpAclBuilder

Set default action for URL paths if no ACL match is found.

pub fn add_allowed_method( self, method: impl Into<HttpRequestMethod>, ) -> Result<HttpAclBuilder, AddError>

Adds a method to the allowed methods.

Note: If you pass a string ensure it is uppercased first.

pub fn remove_allowed_method( self, method: impl Into<HttpRequestMethod>, ) -> HttpAclBuilder

Removes a method from the allowed methods.

Note: If you pass a string ensure it is uppercased first.

pub fn allowed_methods( self, methods: Vec<impl Into<HttpRequestMethod>>, ) -> Result<HttpAclBuilder, AddError>

Sets the allowed methods.

Note: If you pass strings ensure they are uppercased first.

pub fn clear_allowed_methods(self) -> HttpAclBuilder

Clears the allowed methods.

pub fn add_denied_method( self, method: impl Into<HttpRequestMethod>, ) -> Result<HttpAclBuilder, AddError>

Adds a method to the denied methods.

Note: If you pass a string ensure it is uppercased first.

pub fn remove_denied_method( self, method: impl Into<HttpRequestMethod>, ) -> HttpAclBuilder

Removes a method from the denied methods.

Note: If you pass a string ensure it is uppercased first.

pub fn denied_methods( self, methods: Vec<impl Into<HttpRequestMethod>>, ) -> Result<HttpAclBuilder, AddError>

Sets the denied methods.

Note: If you pass strings ensure they are uppercased first.

pub fn clear_denied_methods(self) -> HttpAclBuilder

Clears the denied methods.

pub fn add_allowed_host(self, host: String) -> Result<HttpAclBuilder, AddError>

Adds a host to the allowed hosts.

host may be an exact hostname, or a wildcard pattern where each label (dot-separated segment) is either literal or one of:

• ? - matches exactly one label (e.g. ?.example.com matches foo.example.com but not foo.bar.example.com or bare example.com).
• * - matches one or more labels (e.g. *.example.com matches foo.example.com and foo.bar.example.com, but not bare example.com).

A wildcard must occupy an entire label; foo*.example.com is not a valid pattern.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn remove_allowed_host(self, host: String) -> HttpAclBuilder

Removes a host from the allowed hosts.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn allowed_hosts( self, hosts: Vec<String>, ) -> Result<HttpAclBuilder, AddError>

Sets the allowed hosts.

See Self::add_allowed_host for the wildcard pattern syntax.

Note: The hosts should be in their canonical form (lowercase, punycode for IDN).

pub fn clear_allowed_hosts(self) -> HttpAclBuilder

Clears the allowed hosts.

pub fn add_denied_host(self, host: String) -> Result<HttpAclBuilder, AddError>

Adds a host to the denied hosts.

See Self::add_allowed_host for the wildcard pattern syntax.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn remove_denied_host(self, host: String) -> HttpAclBuilder

Removes a host from the denied hosts.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn denied_hosts( self, hosts: Vec<String>, ) -> Result<HttpAclBuilder, AddError>

Sets the denied hosts.

See Self::add_allowed_host for the wildcard pattern syntax.

Note: The hosts should be in their canonical form (lowercase, punycode for IDN).

pub fn clear_denied_hosts(self) -> HttpAclBuilder

Clears the denied hosts.

pub fn add_allowed_port_range( self, port_range: RangeInclusive<u16>, ) -> Result<HttpAclBuilder, AddError>

Adds a port range to the allowed port ranges.

pub fn remove_allowed_port_range( self, port_range: RangeInclusive<u16>, ) -> HttpAclBuilder

Removes a port range from the allowed port ranges.

pub fn allowed_port_ranges( self, port_ranges: Vec<RangeInclusive<u16>>, ) -> Result<HttpAclBuilder, AddError>

Sets the allowed port ranges.

pub fn clear_allowed_port_ranges(self) -> HttpAclBuilder

Clears the allowed port ranges.

pub fn add_denied_port_range( self, port_range: RangeInclusive<u16>, ) -> Result<HttpAclBuilder, AddError>

Adds a port range to the denied port ranges.

pub fn remove_denied_port_range( self, port_range: RangeInclusive<u16>, ) -> HttpAclBuilder

Removes a port range from the denied port ranges.

pub fn denied_port_ranges( self, port_ranges: Vec<RangeInclusive<u16>>, ) -> Result<HttpAclBuilder, AddError>

Sets the denied port ranges.

pub fn clear_denied_port_ranges(self) -> HttpAclBuilder

Clears the denied port ranges.

pub fn add_allowed_ip_range<Ip>( self, ip_range: Ip, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Adds an IP range to the allowed IP ranges.

pub fn remove_allowed_ip_range<Ip>( self, ip_range: Ip, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Removes an IP range from the allowed IP ranges.

pub fn allowed_ip_ranges<Ip>( self, ip_ranges: Vec<Ip>, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Sets the allowed IP ranges.

pub fn clear_allowed_ip_ranges(self) -> HttpAclBuilder

Clears the allowed IP ranges.

pub fn add_denied_ip_range<Ip>( self, ip_range: Ip, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Adds an IP range to the denied IP ranges.

pub fn remove_denied_ip_range<Ip>( self, ip_range: Ip, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Removes an IP range from the denied IP ranges.

pub fn denied_ip_ranges<Ip>( self, ip_ranges: Vec<Ip>, ) -> Result<HttpAclBuilder, AddError>

where Ip: IntoIpRange,

Sets the denied IP ranges.

pub fn clear_denied_ip_ranges(self) -> HttpAclBuilder

Clears the denied IP ranges.

pub fn add_static_dns_mapping( self, host: String, sock_addr: SocketAddr, ) -> Result<HttpAclBuilder, AddError>

Add a static DNS mapping.

The resolved address is still subject to the IP and port ACL. Use Self::add_trusted_static_dns_mapping for a mapping that should bypass those checks entirely.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn remove_static_dns_mapping(self, host: &str) -> HttpAclBuilder

Removes a static DNS mapping.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn static_dns_mappings( self, mappings: HashMap<String, SocketAddr>, ) -> Result<HttpAclBuilder, AddError>

Sets the static DNS mappings.

Note: The hosts should be in their canonical form (lowercase, punycode for IDN).

pub fn clear_static_dns_mappings(self) -> HttpAclBuilder

Clears the static DNS mappings.

pub fn add_trusted_static_dns_mapping( self, host: String, sock_addr: SocketAddr, ) -> Result<HttpAclBuilder, AddError>

Add a trusted static DNS mapping.

Unlike Self::add_static_dns_mapping, the resolved address is meant to bypass the IP and port ACL entirely - only use this for mappings you trust regardless of what the ACL would otherwise say (e.g. pinning a hostname to an internal address on purpose).

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn remove_trusted_static_dns_mapping(self, host: &str) -> HttpAclBuilder

Removes a trusted static DNS mapping.

Note: The host should be in its canonical form (lowercase, punycode for IDN).

pub fn trusted_static_dns_mappings( self, mappings: HashMap<String, SocketAddr>, ) -> Result<HttpAclBuilder, AddError>

Sets the trusted static DNS mappings.

Note: The hosts should be in their canonical form (lowercase, punycode for IDN).

pub fn clear_trusted_static_dns_mappings(self) -> HttpAclBuilder

Clears the trusted static DNS mappings.

pub fn add_allowed_header( self, header: String, value: Option<String>, ) -> Result<HttpAclBuilder, AddError>

Adds a header to the allowed headers.

If value is None, any value for the header is allowed.

Note: Ensure header names are lowercased.

pub fn remove_allowed_header(self, header: &str) -> HttpAclBuilder

Removes a header from the allowed headers.

Note: Ensure header names are lowercased.

pub fn allowed_headers( self, headers: HashMap<String, Option<String>>, ) -> Result<HttpAclBuilder, AddError>

Sets the allowed headers.

Note: Ensure header names are lowercased.

pub fn clear_allowed_headers(self) -> HttpAclBuilder

Clears the allowed headers.

pub fn add_denied_header( self, header: String, value: Option<String>, ) -> Result<HttpAclBuilder, AddError>

Adds a header to the denied headers.

If value is None, any value for the header is denied.

Note: Ensure header names are lowercased.

pub fn remove_denied_header(self, header: &str) -> HttpAclBuilder

Removes a header from the denied headers.

Note: Ensure header names are lowercased.

pub fn denied_headers( self, headers: HashMap<String, Option<String>>, ) -> Result<HttpAclBuilder, AddError>

Sets the denied headers.

Note: Ensure header names are lowercased.

pub fn clear_denied_headers(self) -> HttpAclBuilder

Clears the denied headers.

pub fn add_allowed_url_path( self, url_path: String, ) -> Result<HttpAclBuilder, AddError>

Adds a URL path to the allowed URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn remove_allowed_url_path(self, url_path: &str) -> HttpAclBuilder

Removes a URL path from the allowed URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn allowed_url_paths( self, url_paths: Vec<String>, ) -> Result<HttpAclBuilder, AddError>

Sets the allowed URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn clear_allowed_url_paths(self) -> HttpAclBuilder

Clears the allowed URL paths.

pub fn add_denied_url_path( self, url_path: String, ) -> Result<HttpAclBuilder, AddError>

Adds a URL path to the denied URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn remove_denied_url_path(self, url_path: &str) -> HttpAclBuilder

Removes a URL path from the denied URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn denied_url_paths( self, url_paths: Vec<String>, ) -> Result<HttpAclBuilder, AddError>

Sets the denied URL paths.

Note: URL paths should start with a ‘/’ and be properly URL-encoded.

pub fn clear_denied_url_paths(self) -> HttpAclBuilder

Clears the denied URL paths.

pub fn build(self) -> HttpAcl

Builds the HttpAcl, without any HttpAclHooks attached.

This does not validate the configuration (uniqueness, overlaps, non-global IP ranges); use Self::try_build instead if the builder wasn’t assembled entirely through this type’s own fallible add_*/allowed_*/denied_* methods, e.g. if it was deserialized. See Self::try_build for details.

pub fn build_full(self, hooks: HttpAclHooks) -> HttpAcl

Builds the HttpAcl with the given HttpAclHooks attached.

This is the only way to attach a ValidateFn, ModifyRequestFn, or ModifyResponseFn; there is no dedicated builder setter for any of them. Like Self::build, this does not validate the configuration; use Self::try_build_full for that.

pub fn try_build_full(self, hooks: HttpAclHooks) -> Result<HttpAcl, AddError>

Builds the HttpAcl with the given HttpAclHooks attached, validating the configuration first.

Checks each category for unique entries, non-overlapping ranges, and no host (or port range, IP range, header, and so on) present on both the allowed and denied lists, returning AddError on the first problem found. It also enforces that IP ranges are global unless Self::non_global_ip_ranges was set to true, which Self::add_allowed_ip_range/ Self::add_denied_ip_range do not check themselves.

Prefer this over Self::build_full whenever the builder wasn’t assembled entirely through this type’s own fallible methods, most notably a builder deserialized from an untrusted source: deserialization writes fields directly and bypasses the checks each add_* method normally performs, so this is also what rebuilds the URL path routers and wildcard host patterns skipped for that reason.

pub fn try_build(self) -> Result<HttpAcl, AddError>

Builds the HttpAcl, without any HttpAclHooks attached, validating the configuration first. See Self::try_build_full for what is validated and when to prefer this over Self::build.

Trait Implementations

impl Clone for HttpAclBuilder

fn clone(&self) -> HttpAclBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HttpAclBuilder

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

Formats the value using the given formatter.

impl Default for HttpAclBuilder

fn default() -> HttpAclBuilder

Returns the “default value” for a type.

impl PartialEq for HttpAclBuilder

fn eq(&self, other: &HttpAclBuilder) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.