Struct SystemProxyLayer 

pub struct SystemProxyLayer<P = SystemProxyPacDisabled> { /* private fields */ }

Available on crate feature std only.

Apply the operating system’s proxy settings to client service inputs.

Existing ProxyRoute or ProxyRoutes extensions win by default. This makes the layer safe to place below explicit CLI/application proxy layers: a common priority chain is NoProxyEnvLayer, an explicit option, ProxyEnvLayer, then this system layer. Use with_overwrite only when the system policy must replace a route already chosen by the caller.

Environment proxy variables are intentionally out of scope. Use ProxyEnvLayer for proxy variables and NoProxyEnvLayer for bypass variables.

Configuration discovery is lazy. macOS, Windows, and Linux install a private native change monitor with the first load; the cache TTL remains a fallback on every platform. Applications can replace that monitor through with_config_change_trigger, retain TTL-only refreshes through without_config_change_trigger, or make the first snapshot immutable through with_config_refresh(false).

Fixed proxies and bypass decisions publish one ProxyRoute. PAC verdicts retain their ordered ProxyRoutes plan even when it contains one entry. Compose ProxyRoutesLayer after all route selectors and before route-aware middleware.

A configured PAC URI is used only after a service is supplied through with_pac_service. Without one the layer uses a fixed proxy from the same system snapshot when available, or leaves the request unchanged. Factory, fetch, or evaluation errors fail the request instead of silently bypassing the system proxy.

Implementations

impl SystemProxyLayer

pub fn new() -> Self

Create a lazy system-proxy layer without reading platform settings.

The first unrouted request loads the settings. Call warm_up to perform that asynchronous load eagerly.

pub fn new_with_ttl(ttl: Duration) -> Self

Create a lazy system-proxy layer with a custom cache TTL.

pub fn new_with_ttl_and_invalid_bypass_rule_policy( ttl: Duration, policy: SystemProxyInvalidBypassRulePolicy, ) -> Self

Create a lazy layer with explicit refresh and bypass-rule policies.

pub fn from_cached(config: SystemProxyConfig) -> Self

Create a layer from a cached operating-system proxy snapshot.

The supplied snapshot is used immediately and refreshed from the operating system after DEFAULT_SYSTEM_PROXY_CONFIG_TTL. Use try_from_system to start with a fresh read.

pub fn from_cached_with_invalid_bypass_rule_policy( config: SystemProxyConfig, policy: SystemProxyInvalidBypassRulePolicy, ) -> Self

Create a layer from a cached operating-system proxy snapshot with an explicit invalid bypass-rule policy for subsequent refreshes.

pub async fn try_from_system() -> Result<Self, BoxError>

Create a layer and asynchronously warm its system proxy snapshot.

pub async fn try_from_system_with_invalid_bypass_rule_policy( policy: SystemProxyInvalidBypassRulePolicy, ) -> Result<Self, BoxError>

Create a layer from the current operating system proxy settings using an explicit invalid bypass-rule policy.

pub async fn try_from_system_with_ttl(ttl: Duration) -> Result<Self, BoxError>

Create a refreshing layer from the current operating system settings.

The initial read is awaited. Once ttl has elapsed, one request awaits the refresh while concurrent requests continue using the prior snapshot. A failed refresh retains that snapshot and is retried after another ttl interval.

pub async fn try_from_system_with_ttl_and_invalid_bypass_rule_policy( ttl: Duration, policy: SystemProxyInvalidBypassRulePolicy, ) -> Result<Self, BoxError>

Create a refreshing layer with explicit refresh and invalid bypass-rule policies.

impl<P> SystemProxyLayer<P>

pub async fn config(&self) -> Result<Arc<SystemProxyConfig>, BoxError>

Load and return the current operating system proxy configuration.

The first call performs lazy discovery. A native or custom change trigger can request an early refresh. Once the cache TTL expires, one caller awaits a refresh while concurrent callers use the stale snapshot.

pub fn cached_config(&self) -> Option<Arc<SystemProxyConfig>>

Return the cached snapshot without loading or refreshing it.

pub async fn warm_up(&self) -> Result<(), BoxError>

Asynchronously populate the cache before serving requests.

pub fn with_pac_service<Q>(self, pac: Q) -> SystemProxyLayer<Q>

Supply a PAC resolver factory.

The factory can be consulted for every request selected for PAC evaluation. Implementations should therefore reuse resolver state for the same script URI. Factory and resolver errors fail the request.

pub fn with_load_error_sink(self, error_sink: impl ErrorSink) -> Self

Handle system configuration load errors with a sink.

By default, an initial discovery failure rejects the request. With this opt-in policy, the error is sent to error_sink and an empty snapshot is cached for the configured TTL. Refresh failures retain the previous snapshot and are sent to the same sink.

pub fn set_load_error_sink(&mut self, error_sink: impl ErrorSink) -> &mut Self

Handle system configuration load errors with a sink.

By default, an initial discovery failure rejects the request. With this opt-in policy, the error is sent to error_sink and an empty snapshot is cached for the configured TTL. Refresh failures retain the previous snapshot and are sent to the same sink.

pub fn with_config_refresh(self, config_refresh: bool) -> Self

Enable periodic and change-triggered configuration refreshes.

Disabling refresh keeps the first loaded snapshot immutable. A layer created with from_cached therefore performs no operating-system reads when refresh is disabled.

pub fn set_config_refresh(&mut self, config_refresh: bool) -> &mut Self

Enable periodic and change-triggered configuration refreshes.

Disabling refresh keeps the first loaded snapshot immutable. A layer created with from_cached therefore performs no operating-system reads when refresh is disabled.

pub fn with_config_change_trigger( self, trigger: impl Service<(), Output = bool, Error: Into<BoxError>>, ) -> Self

Replace the default platform configuration-change trigger.

The service is polled before configuration access. Returning true requests an immediate refresh of an existing snapshot; returning false leaves the TTL as the fallback. Trigger errors are sent to the configured error sink and also fall back to the TTL.

pub fn set_config_change_trigger( &mut self, trigger: impl Service<(), Output = bool, Error: Into<BoxError>>, ) -> &mut Self

Replace the default platform configuration-change trigger.

The service is polled before configuration access. Returning true requests an immediate refresh of an existing snapshot; returning false leaves the TTL as the fallback. Trigger errors are sent to the configured error sink and also fall back to the TTL.

pub fn without_config_change_trigger(self) -> Self

Disable early change notifications while retaining TTL refreshes.

pub fn unset_config_change_trigger(&mut self) -> &mut Self

Disable early change notifications while retaining TTL refreshes.

pub fn with_config_change_trigger_error_sink( self, error_sink: impl ErrorSink, ) -> Self

Replace the sink for configuration-change trigger errors.

pub fn set_config_change_trigger_error_sink( &mut self, error_sink: impl ErrorSink, ) -> &mut Self

Replace the sink for configuration-change trigger errors.

pub fn with_overwrite(self, overwrite: bool) -> Self

Replace an existing route decision (defaults to false).

pub fn set_overwrite(&mut self, overwrite: bool) -> &mut Self

Replace an existing route decision (defaults to false).

Trait Implementations

impl<P: Clone> Clone for SystemProxyLayer<P>

fn clone(&self) -> SystemProxyLayer<P>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<P: Debug> Debug for SystemProxyLayer<P>

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

Formats the value using the given formatter.

impl Default for SystemProxyLayer

fn default() -> Self

Returns the “default value” for a type.

impl<S, P> Layer<S> for SystemProxyLayer<P>

where P: Clone,

type Service = SystemProxyService<S, P>

The service produced by the layer.

fn layer(&self, inner: S) -> Self::Service

Wrap the given service with the middleware, returning a new service.

fn into_layer(self, inner: S) -> Self::Service

Same as layer but consuming self after the service was created.