pub struct HttpAcl { /* private fields */ }Expand description
Represents an HTTP ACL.
Built via HttpAcl::builder (an HttpAclBuilder) rather than constructed
directly. Once built, an HttpAcl is immutable; the various is_*_allowed
methods check a single aspect of a request (scheme, method, host, port, IP,
header, or URL path) and return an AclClassification. See the module-level
documentation for how allow-lists, deny-lists, and per-category defaults combine.
Implementations§
Source§impl HttpAcl
impl HttpAcl
Sourcepub fn builder() -> HttpAclBuilder
pub fn builder() -> HttpAclBuilder
Returns a new HttpAclBuilder.
Sourcepub fn is_scheme_allowed(&self, scheme: &str) -> AclClassification
pub fn is_scheme_allowed(&self, scheme: &str) -> AclClassification
Returns whether the scheme is allowed.
Unlike the other is_*_allowed methods, this is a plain per-scheme flag (set
via HttpAclBuilder::http/HttpAclBuilder::https) rather than an
allow/deny/default check, so it only ever returns
AclClassification::AllowedUserAcl or AclClassification::DeniedUserAcl.
Any scheme other than "http"/"https" is denied.
Sourcepub fn is_method_allowed(
&self,
method: impl Into<HttpRequestMethod>,
) -> AclClassification
pub fn is_method_allowed( &self, method: impl Into<HttpRequestMethod>, ) -> AclClassification
Returns whether the method is allowed.
Note: If you pass a string ensure it is uppercased first.
Sourcepub fn is_host_allowed(&self, host: &str) -> AclClassification
pub fn is_host_allowed(&self, host: &str) -> AclClassification
Returns whether the host is allowed.
Hosts may be exact hostnames or wildcard patterns (see
HttpAclBuilder::add_allowed_host for the wildcard syntax).
Note: The host should be in its canonical form (lowercase, punycode for IDN).
Sourcepub fn is_port_allowed(&self, port: u16) -> AclClassification
pub fn is_port_allowed(&self, port: u16) -> AclClassification
Returns whether the port is allowed.
Sourcepub fn is_ip_allowed(&self, ip: &IpAddr) -> AclClassification
pub fn is_ip_allowed(&self, ip: &IpAddr) -> AclClassification
Returns whether an IP is allowed.
A non-global IP (private, loopback, link-local, and other special-use
addresses) is denied with AclClassification::DeniedNotGlobal before the
allow/deny lists are even checked, unless
HttpAclBuilder::non_global_ip_ranges was set to true.
Sourcepub fn resolve_static_dns_mapping(&self, host: &str) -> Option<SocketAddr>
pub fn resolve_static_dns_mapping(&self, host: &str) -> Option<SocketAddr>
Resolve a static DNS mapping.
The returned address is still subject to the IP and port ACL - callers must
check it with Self::is_ip_allowed and Self::is_port_allowed themselves.
Use Self::resolve_trusted_static_dns_mapping for mappings that should
bypass those checks entirely.
Note: The host should be in its canonical form (lowercase, punycode for IDN).
Sourcepub fn resolve_trusted_static_dns_mapping(
&self,
host: &str,
) -> Option<SocketAddr>
pub fn resolve_trusted_static_dns_mapping( &self, host: &str, ) -> Option<SocketAddr>
Resolve a trusted static DNS mapping.
Unlike Self::resolve_static_dns_mapping, the returned 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).
Sourcepub fn is_header_allowed(
&self,
header_name: &str,
header_value: &str,
) -> AclClassification
pub fn is_header_allowed( &self, header_name: &str, header_value: &str, ) -> AclClassification
Returns whether a header is allowed.
Note: Header names are case-insensitive, but this function assumes the caller provides them in a consistent case.
Sourcepub fn is_url_path_allowed(&self, url_path: &str) -> AclClassification
pub fn is_url_path_allowed(&self, url_path: &str) -> AclClassification
Returns whether a URL path is allowed.
Note: The URL path should be percent-decoded before passing it to this function.
Sourcepub fn is_valid<'h>(
&self,
scheme: &str,
authority: &Authority,
headers: impl Iterator<Item = (&'h str, &'h str)> + Send + Sync + 'h,
body: Option<&[u8]>,
) -> AclClassification
pub fn is_valid<'h>( &self, scheme: &str, authority: &Authority, headers: impl Iterator<Item = (&'h str, &'h str)> + Send + Sync + 'h, body: Option<&[u8]>, ) -> AclClassification
Runs the ValidateFn attached to this ACL, if any, against a request.
Returns AclClassification::AllowedDefault when no ValidateFn was
attached (the default for an HttpAcl built without one), so calling this is
always safe even if you never configured custom validation.
Sourcepub fn has_modify_request(&self) -> bool
pub fn has_modify_request(&self) -> bool
Returns whether a ModifyRequestFn is attached to this ACL.
Cheap (a single field read). Check this before doing any work to make a
request’s body/headers available for mutation (e.g. buffering a streaming
body), so that omitting a ModifyRequestFn costs nothing at request time.
Sourcepub fn has_modify_response(&self) -> bool
pub fn has_modify_response(&self) -> bool
Returns whether a ModifyResponseFn is attached to this ACL.
See Self::has_modify_request - same rationale, for the response side.
Sourcepub fn modify_request(
&self,
scheme: &str,
authority: &Authority,
mutation: &mut RequestMutation,
)
pub fn modify_request( &self, scheme: &str, authority: &Authority, mutation: &mut RequestMutation, )
Runs the ModifyRequestFn attached to this ACL, if any, against
mutation, mutating it in place.
Does nothing when no ModifyRequestFn was attached, so calling this is
always safe even if you never configured one - though see
Self::has_modify_request if you want to skip preparing mutation at all
in that case.
Sourcepub fn modify_response(
&self,
scheme: &str,
authority: &Authority,
mutation: &mut ResponseMutation,
)
pub fn modify_response( &self, scheme: &str, authority: &Authority, mutation: &mut ResponseMutation, )
Runs the ModifyResponseFn attached to this ACL, if any, against
mutation, mutating it in place. See Self::modify_request.