Struct ProxyWatcher 

pub struct ProxyWatcher { /* private fields */ }

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.

The stream is level-triggered: while a subscriber keeps polling, a finite number of polls always reaches a WatchEvent::Snapshot matching the current state, a WatchEvent::Error, or None. An Error item does not end the stream; None comes only once the backend thread has stopped, and is preceded by a snapshot reporting WatchHealth::stopped. Undelivered snapshots fold into the newest one, so a subscriber that stops polling loses the history between snapshots, never current; undelivered failures are capped at 1024, oldest discarded first. The trim runs when a snapshot is published, so a failure arriving after a full one holds the queue at 1025 until the next snapshot trims it back.

One subscriber, not a broadcast. Only the most recently registered waker is kept, and poll_next takes &mut, so the only way to poll a watcher from more than one task is to put it behind a lock — after which the task that polled first is parked with its waker overwritten, and stays parked until something else on this watcher wakes it. To fan a stream out, poll it in one place and forward.

Send but not Sync — on every platform, for a different platform reason each time. So current, health, state and poll_now take &self and do no OS I/O, yet still belong to the thread that owns the watcher, and Arc<ProxyWatcher> is not Send. Move the watcher into the task that polls it and forward from there what other threads need. Under the tokio feature watch_channel is that forwarding already written — named in backticks rather than linked because it exists only under that feature; without it the shape is the same by hand, one owner republishing current into a Mutex or a channel after every item. Neither recovers poll_now, which stays with the owner: send it a request rather than sharing the watcher.

The Linux threads read the process environment, and keep reading it: every notification re-reads the desktop and sandbox variables, at a moment the caller does not choose. std::env::set_var and std::env::remove_var are sound only while no other thread is reading the environment, so treat them as unavailable for as long as a watcher is alive — set what you need before constructing one. Windows is exempt; std documents both as always safe there.

use std::future::poll_fn;
use std::pin::Pin;

use futures_core::Stream;
use proxy_watch::{ProxyWatcher, WatchEvent};

let mut watcher = ProxyWatcher::new()?;
println!("current: {:?}", watcher.current().effective);

let next = futures_executor::block_on(poll_fn(|cx| Pin::new(&mut watcher).poll_next(cx)));
match next {
    Some(WatchEvent::Snapshot { state, .. }) => {
        println!("now: {:?} (live: {})", state.config.effective, state.health.is_fully_live());
    }
    Some(WatchEvent::Error { error, .. }) => eprintln!("re-read failed: {error}"),
    _ => {}
}

Implementations

impl ProxyWatcher

pub fn new() -> Result<Self, Error>

Start watching with WatchOptions::default.

Errors

Error::Unsupported, Error::Io, Error::Sandboxed (Linux, in a sandbox with no dconf), or a parse error from malformed OS settings.

pub fn with_options(options: WatchOptions) -> Result<Self, Error>

Start watching with explicit options.

Blocks the way read does, and can pay that price twice: the notification route is armed before the configuration is read, not after, so a change landing between the two is already queued rather than lost. macOS is the exception on both counts — it subscribes on the watcher thread instead, closing the same window with the re-read that thread opens with, and that subscription and the read each run the same five-second retry budget, so a configd that is still coming up can hold this call for ten seconds.

Errors

Same as ProxyWatcher::new.

pub fn current(&self) -> ProxyConfig

The most recent snapshot (no OS I/O; may briefly wait for the internal mutex). Equals the constructor read right after start.

pub fn health(&self) -> WatchHealth

Construction-time routes plus any runtime degradation (see WatchHealth). Does no OS I/O; it may briefly wait for the same internal mutex ProxyWatcher::current uses.

pub fn state(&self) -> WatchState

Configuration and health copied from one shared-state observation.

This does no OS I/O, though it may briefly wait for the internal mutex. Prefer it over separate current and health calls when a route may degrade or the backend thread may stop concurrently.

pub fn poll_now(&self)

Request an immediate re-read (same debounce/equality path as a native notify).

Call it when the caller knows something this crate cannot see: a connection attempt failed in a way that might be proxy-related, or the caller’s own network-change watch fired. Watching the network itself is not this crate’s job, and this is what stands in for it.

Returns immediately, and may deliver nothing. Sharing a notification’s path means sharing its equality skip: a re-read that finds the configuration and the health unchanged publishes no WatchEvent, and asking again does not force one. The Stream reports change, not completion — and so does everything else: current and state answer the same before and after such a re-read, so they are where the current answer comes from, not evidence that this request landed. WatchEvent::Error says the same for the recovery case.

Trait Implementations

impl Debug for ProxyWatcher

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

Formats the value using the given formatter.

impl Stream for ProxyWatcher

type Item = WatchEvent

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.