Crate proxy_watch

Expand description

Detect — and on Windows, macOS and Linux watch — the operating system’s proxy settings.

read answers once, starting no watcher and arming no notification route:

use proxy_watch::{Scheme, read};

let config = read()?;
match config.effective.endpoint_for(Scheme::Https) {
    Some(endpoint) => println!("https goes through {endpoint}"),
    None => println!("https is direct"),
}

ProxyWatcher follows the settings instead — a Stream of WatchEvent that opens with a snapshot, then publishes changes coalesced over WatchOptions::debounce (200 ms). It runs its own OS threads, so it needs no async runtime. Where there is no store to read — any other platform, or a Linux host with no desktop — the answer is Error::Unsupported, which means “read ProxyEnv::from_env() instead”, not “give up”.

resolve() (behind the resolve feature, so unlinked here) turns a snapshot and a URL into the ordered endpoints to try, bypass rules applied; a host on PAC or WPAD stops it with Error::PacNotSupported until pac and an engine — pac-boa, or pac-windows-native on Windows — are on. The remaining flags are linux-gnome and linux-kde (the Linux stores, on by default), tokio for a tokio::sync::watch::Receiver, and tracing for lifecycle logs.

The README carries the feature table, the per-OS map of where these settings live, and a runnable example for each of the above.

§Platform coverage

Windows, GNOME and KDE are exercised on real machines. Under Flatpak or snap without dconf the Linux backend falls back to the desktop portal, which has no change notification of its own — set WatchOptions::poll_interval to poll — or reports Error::Sandboxed.

Unverified: the macOS backend and that sandbox path have only ever run in CI — no Mac, no Flatpak, no Snap. Risk: macOS reads a missing or unexpected answer as “nothing is configured” rather than as an error, so a host that does have a proxy is reported as having none. The sandbox path fails loudly instead, so what is open there is whether the detection fires at all, not what it does once it has. Symptom: on a machine whose settings plainly show a proxy, the stream yields ProxyMode::Direct and never publishes an error. src/sys/mac/mod.rs, src/sys/linux/sandbox.rs and src/sys/linux/portal.rs carry the per-backend form.

Modules§

pacpac: PAC evaluation (pac feature, off by default): script → Vec<ProxyStep> like resolve.
parse: Pure parsers for OS proxy string formats.

Structs§

BypassRules: Destinations that must not go through a proxy (parse::no_proxy / parse::proxy_override).
ProxyAuth: Credentials for a proxy endpoint (HTTP Basic only).
ProxyConfig: Point-in-time system proxy snapshot.
ProxyEndpoint: Concrete proxy address. IPv6 brackets resolved at parse; use authority. #[non_exhaustive] — construct via new / parse.
ProxyEnv: Env snapshot of *_proxy / no_proxy (not a Stream; ProxyWatcher does not merge these in — except where an OS setting names them, which KDE’s ProxyType=4 does).
ProxyWatcher: OS proxy watcher: initial snapshot, then debounced changes (equality ignores captured_at). Own OS threads — one, and on Linux one more per live source, plus one for WatchOptions::poll_interval (elsewhere that interval shortens the single thread’s own wait instead of adding one). Drop joins them. ProxyWatcher::health for route liveness. Win/macOS/Linux; else Error::Unsupported. Applies no *_proxy convention of its own — only KDE’s ProxyType = 4 builds a ProxyEnv, from the variables kioslaverc names.
RejectedValue: One fail-soft drop with a typed reason and origin.
Url: Re-export of url::Url for ProxyMode::Pac. A parsed URL record.
WatchHealth: Liveness of change-notification routes (ProxyWatcher::health).
WatchOptions: Tuning knobs for ProxyWatcher::with_options (#[non_exhaustive] — use WatchOptions::new / with_*).
WatchState: One internally consistent observation of a watcher.

Enums§

EnvPrecedence: Where the process environment ranks against the OS settings in ProxyConfig::with_env.
Error: Errors from reading OS proxy configuration, and from routing a URL through what was read.
Host: Re-export of url::Host (IPv6 brackets already resolved). The host name of an URL.
HostPattern: A single entry of a bypass list.
IpNet: Re-export of ipnet::IpNet for HostPattern::Cidr. An IP network address, either IPv4 or IPv6.
ProxyConfigSource: Where a ProxyMode came from. ProxyConfig keeps all of them for explanation.
ProxyEntry: Whether a given Scheme uses a proxy at all.
ProxyMode: What a single configuration source says about proxying.
ProxyScheme: The wire protocol used to reach the proxy itself.
ProxyStepresolve: Routing decisions, behind the resolve feature (on by default). One way to reach a destination (resolve).
RejectionKind: Why one configuration value was ignored.
RejectionSource: Where a rejected value was read from.
Scheme: Request scheme a proxy setting applies to (ProxyMode::Manual per_scheme key). Not ProxyScheme (how to talk to the proxy).
WatchEvent: Stream item of ProxyWatcher: a state snapshot or a failed re-read, each stamped with the watcher’s WatchState as it stood at delivery.

Constants§

CGI_MARKER_VAR: The variable whose presence with a method in it marks a CGI environment (see Error::CgiHttpProxy).
DEFAULT_DEBOUNCE: The default debounce window (200 ms).
LOCAL_TOKEN: The Windows ProxyOverride token that bypasses dot-less (intranet) host names.
NO_LOOPBACK_TOKEN: Windows <-loopback>: subtracts the whole implicit bypass set — loopback and link-local — from the entries written before it. Parsed to HostPattern::SubtractImplicit; see BypassRules::bypass_loopback.

Traits§

Stream: Re-export of futures_core::Stream. A stream of values produced asynchronously.

Functions§

read: Read the OS proxy configuration once, without starting a watcher.
read_with_options: read, with the one option a read can honour: WatchOptions::watch_group_policy. The debounce and poll-interval fields describe a watcher this call never starts, so they are ignored.
resolveresolve: Routing decisions, behind the resolve feature (on by default). Decide how to reach url under config.
resolve_with_pacpac and resolve: Routing decisions that may need a PAC script, behind the pac feature (off by default). Like resolve, but evaluates PAC when the mode requires it.
watch_channeltokio: The tokio bridge, behind the tokio feature (off by default). Drive watcher into a tokio::sync::watch channel (clone watch::Receiver for fan-out).