proxy_watch/

mode.rs

//! The unified proxy mode.

use std::collections::HashMap;
use std::fmt;

use url::Url;

use crate::bypass::BypassRules;
use crate::diagnostic::RejectedValue;
use crate::endpoint::{ProxyEndpoint, ProxyEntry, Scheme};

/// What a single configuration source says about proxying.
///
/// Hand-written [`Debug`], because [`ProxyConfig`](crate::ProxyConfig)'s is derived and
/// prints whatever this one does. The variants withhold different things: a
/// [`Pac`](ProxyMode::Pac) URL is printed minus its userinfo (the location makes a report
/// actionable, and only the credentials are secret) while a
/// [`PacInline`](ProxyMode::PacInline) body is withheld whole and stands in as length plus
/// hash, because a script is not a locator and any part of it may be one.
/// [`Manual`](ProxyMode::Manual) delegates: [`ProxyEntry`] masks auth.
#[derive(Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum ProxyMode {
    /// No proxy at all (Windows `ProxyEnable=0`, GNOME `mode=none`, macOS all
    /// `*Enable` keys zero). This is the [`Default`].
    #[default]
    Direct,
    /// Static per-scheme proxies plus bypass rules.
    ///
    /// Sealed, like the other variants that carry fields: build it with
    /// [`ProxyMode::manual`], which keeps the [`rejected`](ProxyMode::Manual) list and the
    /// `per_scheme` entries mirroring it in step: the constructor reads the list back out
    /// of the map, so the two cannot be handed in disagreeing. The enum's own
    /// `#[non_exhaustive]` does not seal a variant: it only forces a `_` arm in a match,
    /// so without this a caller could assemble a `Manual` whose two halves disagree, and
    /// `resolve` answers from the mirror.
    #[non_exhaustive]
    Manual {
        /// Per-scheme proxy entries.
        per_scheme: HashMap<Scheme, ProxyEntry>,
        /// Bypass rules.
        bypass: BypassRules,
        /// Fail-open drops (redacted); opposite of [`BypassRules::rejected`].
        rejected: Vec<RejectedValue>,
    },
    /// PAC script at a URL (fetch/evaluate via `pac` / `resolve_with_pac`).
    ///
    /// Sealed; build it with [`ProxyMode::pac`].
    #[non_exhaustive]
    Pac {
        /// Script URL.
        url: Url,
        /// Fail-open drops (redacted), as in [`Manual`](ProxyMode::Manual): a source can
        /// reach a PAC answer having already lost an unrelated key. With no `per_scheme` to
        /// mirror them into, they are reachable only through [`ProxyMode::rejected`].
        rejected: Vec<RejectedValue>,
    },
    /// Inline PAC script body.
    ///
    /// Sealed; build it with [`ProxyMode::pac_inline`].
    #[non_exhaustive]
    PacInline {
        /// JavaScript source.
        script: String,
        /// Fail-open drops (redacted); see [`Pac`](ProxyMode::Pac)'s field of the same name.
        rejected: Vec<RejectedValue>,
    },
    /// WPAD enabled (no DHCP/DNS probe in this crate).
    ///
    /// Not sealed, and neither is [`Direct`](ProxyMode::Direct): a sealed unit variant
    /// cannot be *named* by another crate, not only constructed by one, so sealing these
    /// two would break every caller's `mode == ProxyMode::Direct`. `Direct` could not be
    /// sealed in any case: it is this enum's [`Default`], and a default variant must be
    /// exhaustive. Neither carries fields, and neither will: a backend that dropped a
    /// setting answers [`Manual`](ProxyMode::Manual) so the record has somewhere to go.
    WpadAutoDetect,
}

// Both lookups' precedence rule, defined only here, so that adding a step to either cannot
// put them out of step: the first entry that is an *answer* wins, and a drop is not one. A
// later step that answers is a proxy the platform did configure (including macOS' SOCKS
// fallback and Windows' `socks=` fill), so preferring the record over it would turn a
// resolvable request into an error. With nothing to answer anywhere the earliest record is
// returned, because that is the slot whose loss took the answer away; walking the chain is
// what keeps that order the *lookup's* order rather than a second one maintained by hand.
fn first_answer<'a>(chain: impl IntoIterator<Item = &'a ProxyEntry>) -> Option<&'a ProxyEntry> {
    let mut dropped = None;
    for entry in chain {
        match entry {
            ProxyEntry::Unusable(_) => dropped = dropped.or(Some(entry)),
            _ => return Some(entry),
        }
    }
    dropped
}

impl ProxyMode {
    /// Build a [`ProxyMode::Manual`] value, taking the
    /// [`rejected`](ProxyMode::Manual) list from whatever drops `per_scheme` already holds.
    ///
    /// Empty for the map a backend builds, which records its drops separately and attaches
    /// them once the map is complete. A caller filtering or merging a *parsed* `Manual`
    /// hands back a map already carrying [`ProxyEntry::Unusable`] entries, and the list is
    /// recovered from them rather than left empty: an empty list beside a lookup that
    /// answers `Unusable` would say nothing was lost about a request that cannot be
    /// routed. Read in [`Scheme::ALL`]'s order, not the map's, which is seeded per
    /// instance. A record that named no scheme was never in the map and cannot come back
    /// this way.
    #[must_use]
    pub fn manual(per_scheme: HashMap<Scheme, ProxyEntry>, bypass: BypassRules) -> Self {
        let rejected = Scheme::ALL
            .iter()
            .filter_map(|scheme| match per_scheme.get(scheme) {
                Some(ProxyEntry::Unusable(value)) => Some(value.clone()),
                _ => None,
            })
            .collect();
        ProxyMode::Manual {
            per_scheme,
            bypass,
            rejected,
        }
    }

    /// Build a [`ProxyMode::Pac`] value with an empty `rejected` list.
    #[must_use]
    pub fn pac(url: Url) -> Self {
        ProxyMode::Pac {
            url,
            rejected: Vec::new(),
        }
    }

    /// Build a [`ProxyMode::PacInline`] value with an empty `rejected` list.
    #[must_use]
    pub fn pac_inline(script: String) -> Self {
        ProxyMode::PacInline {
            script,
            rejected: Vec::new(),
        }
    }

    /// Set the [`rejected`](ProxyMode::Manual) list of a [`ProxyMode::Manual`] value,
    /// *replacing* whatever it held. Every caller builds the list first and hands it over
    /// once; a second call replaces the list but leaves behind the `per_scheme` entries the
    /// first one derived (below), so a lookup could still reach a record that
    /// [`ProxyMode::rejected`] no longer lists. That is why the `kioslaverc`
    /// `ProxyType = 4` path merges the environment's list and its own skipped slots into
    /// one vector before calling, rather than calling twice.
    ///
    /// A no-op on [`ProxyMode::Direct`] and [`ProxyMode::WpadAutoDetect`], which have
    /// nowhere to put the list. No backend needs one there: a reader that dropped a setting
    /// answers [`Manual`](ProxyMode::Manual) rather than `Direct` so the record has
    /// somewhere to go, and every backend's WPAD return is reached only from a flag that
    /// read cleanly, so nothing can have been recorded by the time one is taken.
    ///
    /// Only [`Manual`](ProxyMode::Manual) mirrors the list into `per_scheme`; the PAC
    /// variants have no map, and a lookup against them answers `None` for every scheme
    /// anyway. The rest of this describes that mirror.
    ///
    /// Every record that names a scheme is also written into `per_scheme` as
    /// [`ProxyEntry::Unusable`], so a drop is reachable from a lookup instead of only from
    /// a second list the lookup would have to be kept in step with. It is done here rather
    /// than in each backend because, spread across the backends, five readers express "keep
    /// this scheme out of the map so the record answers instead" in five dialects, and the
    /// two orderings (the lookup's and the record walk's) have to agree by hand.
    ///
    /// Two rules:
    ///
    /// - An occupied slot stands, including one holding [`ProxyEntry::Disabled`]: that is
    ///   an answer the platform gave, and a backend that recorded a drop and wrote the slot
    ///   anyway (macOS' SOCKS fallback, GNOME's `use-same-proxy`) meant the write. A backend
    ///   that wants the record to answer leaves the slot empty. A record naming
    ///   [`Scheme::All`] is no exception here: a *live* catch-all does not reach past a
    ///   `Disabled` either ([`entry_for`](Self::entry_for)'s first rule), so losing one took
    ///   nothing from that scheme: clearing it would turn `http_proxy=` beside an
    ///   unparseable `all_proxy=` into an error. The one reader whose catch-all *overwrites*
    ///   `Disabled` rather than filling around it is macOS', and it empties those slots
    ///   itself before calling this.
    /// - The first record for a slot wins, which is what
    ///   [`Error::ProxyEntryUnusable`](crate::Error::ProxyEntryUnusable) promises.
    ///
    /// A record naming no scheme stays in the list alone: there is no slot to put it in, and
    /// it never took any one request's answer away.
    #[must_use]
    pub(crate) fn with_rejected(mut self, rejected: Vec<RejectedValue>) -> Self {
        match &mut self {
            ProxyMode::Manual {
                per_scheme,
                rejected: slot,
                ..
            } => {
                for value in &rejected {
                    let Some(scheme) = value.affected_scheme() else {
                        continue;
                    };
                    per_scheme
                        .entry(scheme)
                        .or_insert_with(|| ProxyEntry::Unusable(value.clone()));
                }
                *slot = rejected;
            }
            ProxyMode::Pac { rejected: slot, .. } | ProxyMode::PacInline { rejected: slot, .. } => {
                *slot = rejected
            }
            ProxyMode::Direct | ProxyMode::WpadAutoDetect => {}
        }
        self
    }

    /// Whether the mode means "connect directly".
    #[must_use]
    pub fn is_direct(&self) -> bool {
        matches!(self, ProxyMode::Direct)
    }

    /// The bypass rules, when the mode has any.
    #[must_use]
    pub fn bypass(&self) -> Option<&BypassRules> {
        match self {
            ProxyMode::Manual { bypass, .. } => Some(bypass),
            _ => None,
        }
    }

    /// The redacted text of every scheme-endpoint entry the source dropped, when the
    /// mode has any. See [`ProxyMode::Manual`]'s `rejected` field for what this
    /// records and why.
    #[must_use]
    pub fn rejected(&self) -> Option<&[RejectedValue]> {
        match self {
            ProxyMode::Manual { rejected, .. }
            | ProxyMode::Pac { rejected, .. }
            | ProxyMode::PacInline { rejected, .. } => Some(rejected),
            ProxyMode::Direct | ProxyMode::WpadAutoDetect => None,
        }
    }

    /// Entry for `scheme`. Concrete schemes beat [`Scheme::All`]; `All` has no fallback.
    /// `None` outside Manual or with no entry; `Some(Disabled)` suppresses `All`.
    /// [`Unusable`](ProxyEntry::Unusable) does not: a drop is the last resort, so a live
    /// `All` still answers and the record surfaces only when nothing else covers `scheme`.
    /// Backends may substitute before the map is built (macOS SOCKS fallback, Windows
    /// `socks=` fill); this applies to the finished map.
    #[must_use]
    pub fn entry_for(&self, scheme: Scheme) -> Option<&ProxyEntry> {
        let ProxyMode::Manual { per_scheme, .. } = self else {
            return None;
        };
        // No `scheme == Scheme::All` guard: reaching the fallback means the first lookup
        // missed, and for `All` the fallback *is* that same lookup, so it can only miss
        // again. A guard would be a branch no input can tell apart from its absence.
        first_answer(
            [scheme, Scheme::All]
                .into_iter()
                .filter_map(|scheme| per_scheme.get(&scheme)),
        )
    }

    /// The proxy endpoint that applies to `scheme`, or `None`.
    ///
    /// `None` is "no endpoint to hand out". Inside [`Manual`](ProxyMode::Manual) that is
    /// direct access when nothing covers the scheme and when what does is
    /// [`Disabled`](ProxyEntry::Disabled), but not when it is
    /// [`Unusable`](ProxyEntry::Unusable), a setting that was lost rather than an answer,
    /// which `resolve` reports as
    /// [`Error::ProxyEntryUnusable`](crate::Error::ProxyEntryUnusable). A caller that has
    /// to tell those two apart asks [`entry_for`](Self::entry_for), which is the same
    /// lookup with the entry left intact. Every other mode returns `None` for every scheme,
    /// including the PAC and WPAD ones that keep their answer in a script this method
    /// cannot run; that is [`Error::PacNotSupported`](crate::Error::PacNotSupported), not
    /// direct.
    ///
    /// ```
    /// # use proxy_watch::{parse, ProxyMode, Scheme, BypassRules};
    /// let per_scheme = parse::proxy_server("http=a:8080;https=b:8443");
    /// let mode = ProxyMode::manual(per_scheme, BypassRules::new());
    /// assert_eq!(mode.endpoint_for(Scheme::Http).unwrap().port, 8080);
    /// // No `ftp=` and no catch-all entry: nothing applies.
    /// assert!(mode.endpoint_for(Scheme::Ftp).is_none());
    /// ```
    #[must_use]
    pub fn endpoint_for(&self, scheme: Scheme) -> Option<&ProxyEndpoint> {
        self.entry_for(scheme).and_then(ProxyEntry::endpoint)
    }

    // Only the first three steps come from the references (Chromium's
    // `GetProxyListForWebSocketScheme`). `all` is a fourth that neither has and Chromium
    // structurally cannot reach: there a catch-all and a per-scheme entry never coexist, so
    // it goes last, for the reason it does everywhere else here: a named entry beats
    // [`Scheme::All`]. `§4.1.3` is Chromium's way of citing it; in the RFC the note is item
    // 3 of the numbered list in §4.1, not a section of that number.
    /// Entry for `ws`/`wss`: socks → https → http (RFC 6455 §4.1.3, as Chromium reads it),
    /// then `all`: a step this crate adds.
    ///
    /// Unlike [`entry_for`](Self::entry_for), intermediate `Disabled` entries do not stop
    /// the chain: only terminal [`Scheme::All`] is returned as-is (e.g. empty
    /// `all_proxy=`).
    /// An intermediate [`Unusable`](ProxyEntry::Unusable) does not stop it either, but is
    /// remembered, and the earliest one is the answer when no step has a real one.
    ///
    /// ```
    /// # use proxy_watch::{parse, ProxyMode, BypassRules};
    /// // Only `socks=` and `http=`: the WebSocket chain prefers the SOCKS proxy.
    /// let per_scheme = parse::proxy_server("http=h:80;socks=s:1080");
    /// let mode = ProxyMode::manual(per_scheme, BypassRules::new());
    /// assert_eq!(mode.websocket_endpoint().unwrap().authority(), "s:1080");
    ///
    /// // `https=` explicitly disabled: the chain keeps going to `http=` rather than
    /// // stopping the way `entry_for(Scheme::Https)` would for an actual `https`
    /// // request.
    /// let per_scheme = parse::proxy_server("https=;http=h:80");
    /// let mode = ProxyMode::manual(per_scheme, BypassRules::new());
    /// assert_eq!(mode.websocket_endpoint().unwrap().authority(), "h:80");
    /// ```
    #[must_use]
    pub fn websocket_entry(&self) -> Option<&ProxyEntry> {
        let ProxyMode::Manual { per_scheme, .. } = self else {
            return None;
        };
        let configured = |scheme: Scheme| match per_scheme.get(&scheme) {
            entry @ Some(ProxyEntry::Use(_) | ProxyEntry::Unusable(_)) => entry,
            _ => None,
        };
        first_answer(
            [Scheme::Socks, Scheme::Https, Scheme::Http]
                .into_iter()
                .filter_map(configured)
                .chain(per_scheme.get(&Scheme::All)),
        )
    }

    /// The proxy endpoint for a `ws://`/`wss://` request; see
    /// [`websocket_entry`](Self::websocket_entry) for the resolution order.
    #[must_use]
    pub fn websocket_endpoint(&self) -> Option<&ProxyEndpoint> {
        self.websocket_entry().and_then(ProxyEntry::endpoint)
    }
}

impl fmt::Debug for ProxyMode {
    // Not a derive, for the reason [`ProxyMode`]'s own doc gives.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ProxyMode::Direct => write!(f, "Direct"),
            ProxyMode::Manual {
                per_scheme,
                bypass,
                rejected,
            } => f
                .debug_struct("Manual")
                // Sorted, which a `HashMap` is not: its iteration order is seeded per
                // instance, so the same configuration would print differently on each run
                // and a diff between two logged configurations would report changes that
                // did not happen. `Scheme`'s `Ord` is the declaration order, which is
                // [`Scheme::ALL`]'s documented one. Every map this crate's `Debug` prints
                // is ordered for that reason: `ProxyEnv`'s is the other public one.
                .field(
                    "per_scheme",
                    &per_scheme
                        .iter()
                        .collect::<std::collections::BTreeMap<_, _>>(),
                )
                .field("bypass", bypass)
                .field("rejected", rejected)
                .finish(),
            ProxyMode::Pac { url, rejected } => f
                .debug_struct("Pac")
                .field(
                    "url",
                    &format_args!("{}", crate::util::redact_userinfo(url.as_str())),
                )
                .field("rejected", rejected)
                .finish(),
            ProxyMode::PacInline { script, rejected } => f
                .debug_struct("PacInline")
                .field("len", &script.len())
                .field(
                    "fnv1a",
                    &format_args!("{:016x}", crate::util::fnv1a(script.as_bytes())),
                )
                .field("rejected", rejected)
                .finish(),
            ProxyMode::WpadAutoDetect => write!(f, "WpadAutoDetect"),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn rejection(input: &str) -> RejectedValue {
        RejectedValue::new(
            crate::RejectionKind::InvalidProxyEndpoint,
            crate::RejectionSource::ProxyServer,
            input,
        )
    }

    const SECRET: &str = "hunter2";

    #[test]
    fn manual_debug_delegates_to_proxy_entrys_own_masking() {
        use crate::auth::ProxyAuth;
        use crate::endpoint::ProxyEndpoint;

        let mut per_scheme = HashMap::new();
        per_scheme.insert(
            Scheme::Http,
            ProxyEntry::Use(
                ProxyEndpoint::new(url::Host::Domain("proxy.corp".to_owned()), 8080)
                    .with_auth(ProxyAuth::new("alice", Some(SECRET))),
            ),
        );
        let mode = ProxyMode::manual(per_scheme, BypassRules::new());
        let debug = format!("{mode:?}");
        assert!(!debug.contains(SECRET), "{debug}");
        assert!(debug.contains("Manual"), "{debug}");
        assert!(debug.contains("proxy.corp"), "{debug}");
    }

    // Two `Debug` renderings of the same configuration must be the same text. A `HashMap`
    // gives no such promise: its iteration order is seeded per instance, so the field would
    // come out in a different order on each run and a diff between two logged
    // configurations would report changes that did not happen.
    #[test]
    fn manual_debug_prints_the_schemes_in_a_fixed_order() {
        use crate::parse;

        let mode = ProxyMode::manual(
            parse::proxy_server("all=e:5;socks=d:4;ftp=c:3;https=b:2;http=a:1"),
            BypassRules::new(),
        );
        let debug = format!("{mode:?}");

        let mut at = 0;
        for scheme in Scheme::ALL {
            // With the `:` the map's separator prints, so `Http` does not match inside
            // `Https`.
            let name = format!("{scheme:?}:");
            let found = debug[at..]
                .find(&name)
                .unwrap_or_else(|| panic!("{name} out of order or missing in {debug}"));
            at += found + name.len();
        }
    }

    // The impl is hand-written for the whole enum, and only this test checks four of its
    // renderings. `WpadAutoDetect` printed as `Direct` makes "discovery is running" and "no
    // proxy at all" the same line in a log, and `is_direct` is false for one of them, so a
    // reader comparing the two would be told the line is wrong. `Pac`'s `rejected` is where
    // a PAC configuration parks what it could not read, and `PacInline`'s `len` is named
    // here for the same reason.
    //
    // Exact strings, so that a label, a field order or a variant name cannot change unseen.
    // The `RejectedValue` and the hash keep their own renderings, which this impl does not
    // own, so the expectations defer to them rather than copying them out.
    #[test]
    fn every_mode_debug_names_itself_and_keeps_its_fields() {
        const SCRIPT: &str = "function FindProxyForURL(){}";
        let dropped = rejection("h:99999");
        for (mode, expected) in [
            (ProxyMode::Direct, "Direct".to_owned()),
            (ProxyMode::WpadAutoDetect, "WpadAutoDetect".to_owned()),
            (
                // No credentials, so the row pins the framing and not the masking, which
                // `debug_masking`'s registry owns for this variant.
                ProxyMode::pac(url::Url::parse("https://wpad.corp/proxy.pac").unwrap())
                    .with_rejected(vec![dropped.clone()]),
                format!("Pac {{ url: https://wpad.corp/proxy.pac, rejected: [{dropped:?}] }}"),
            ),
            (
                ProxyMode::pac_inline(SCRIPT.to_owned()),
                format!(
                    "PacInline {{ len: {}, fnv1a: {:016x}, rejected: [] }}",
                    SCRIPT.len(),
                    crate::util::fnv1a(SCRIPT.as_bytes())
                ),
            ),
        ] {
            assert_eq!(format!("{mode:?}"), expected);
        }
    }

    fn authority(mode: &ProxyMode, want: Option<&str>) {
        assert_eq!(
            mode.websocket_endpoint()
                .map(ProxyEndpoint::authority)
                .as_deref(),
            want
        );
    }

    #[test]
    fn websocket_entry_prefers_socks_then_https_then_http() {
        use crate::parse;

        let mode = ProxyMode::manual(
            parse::proxy_server("http=h:80;https=s:443;socks=k:1080"),
            BypassRules::new(),
        );
        authority(&mode, Some("k:1080"));

        let mode = ProxyMode::manual(
            parse::proxy_server("http=h:80;https=s:443"),
            BypassRules::new(),
        );
        authority(&mode, Some("s:443"));

        let mode = ProxyMode::manual(parse::proxy_server("http=h:80"), BypassRules::new());
        authority(&mode, Some("h:80"));
    }

    #[test]
    fn websocket_entry_falls_back_to_the_bare_catch_all_last() {
        use crate::parse;

        let mode = ProxyMode::manual(parse::proxy_server("bare:9000"), BypassRules::new());
        authority(&mode, Some("bare:9000"));

        // "Last" means after `http=`, not merely "used when it is the only entry". This is
        // the step the references do not have: in `net/proxy_resolution/proxy_config.h`,
        // Chromium's `ProxyConfig::ProxyRules::type` is `PROXY_LIST` (the catch-all, in
        // `single_proxies`) or `PROXY_LIST_PER_SCHEME` (`proxies_for_http` and its
        // siblings) and never both at once, so the input above is not a shape it can hold.
        let mode = ProxyMode::manual(parse::proxy_server("all=a:1;http=h:80"), BypassRules::new());
        authority(&mode, Some("h:80"));

        // Nothing configured at all: no entry, same as a direct connection.
        let mode = ProxyMode::manual(HashMap::new(), BypassRules::new());
        authority(&mode, None);
    }

    // Unlike [`ProxyMode::entry_for`], a disabled entry along the chain does not stop
    // it: [`ProxyMode::websocket_entry`]'s doc states that difference, and it is why
    // the chain cannot be three `entry_for` calls.
    #[test]
    fn websocket_entry_treats_a_disabled_tier_as_absent_not_as_a_stop_signal() {
        use crate::parse;

        // `https=` explicitly off: the chain still reaches `http=` instead of jumping
        // straight to "no entry".
        let mode = ProxyMode::manual(parse::proxy_server("https=;http=h:80"), BypassRules::new());
        authority(&mode, Some("h:80"));

        // Confirm the asymmetry: `entry_for(Https)` itself *does* stop at `Disabled`
        // for an actual `https` request.
        assert_eq!(mode.entry_for(Scheme::Https), Some(&ProxyEntry::Disabled));

        // The same at the head of the chain rather than in its middle. Without this the
        // claim is "a `Disabled` at the `https` tier is skipped", which is one position,
        // not the rule the doc states.
        let mode = ProxyMode::manual(
            parse::proxy_server("socks=;https=s:443"),
            BypassRules::new(),
        );
        authority(&mode, Some("s:443"));
    }

    // The other half of the same doc sentence: the three tiers above drop a `Disabled`,
    // but the terminal [`Scheme::All`] is returned as-is. [`authority`] cannot see the
    // difference: it reads through [`ProxyMode::websocket_endpoint`], which turns both
    // `Some(Disabled)` and `None` into no endpoint, so the entry is asserted directly.
    #[test]
    fn a_disabled_terminal_catch_all_is_returned_rather_than_dropped() {
        use crate::parse;

        let mode = ProxyMode::manual(parse::proxy_server("all="), BypassRules::new());
        assert_eq!(mode.websocket_entry(), Some(&ProxyEntry::Disabled));
        authority(&mode, None);
    }

    #[test]
    fn websocket_entry_is_none_for_non_manual_modes() {
        assert!(ProxyMode::Direct.websocket_entry().is_none());
        assert!(ProxyMode::WpadAutoDetect.websocket_entry().is_none());
    }

    #[test]
    fn manual_defaults_to_an_empty_rejected_list() {
        let mode = ProxyMode::manual(HashMap::new(), BypassRules::new());
        assert_eq!(mode.rejected(), Some(&[][..]));
    }

    // Empty is the answer for a map with nothing lost in it, and the row above is the whole
    // of that case. A caller filtering or merging a parsed `Manual` reaches for its map,
    // and the map is where `with_rejected` put the drops, so handing one back to the only
    // public constructor there is must not turn them into a list that says nothing was lost
    // while a lookup still answers `Unusable`. That leaves a drop with no corresponding
    // diagnostic: `resolve` errors, and the report written from `rejected()` has no line
    // for it.
    #[test]
    fn manual_recovers_the_drops_the_map_it_was_handed_already_carries() {
        let lost = rejection("http=not a host").for_scheme(Some(Scheme::Http));
        let inherited = lost.clone().for_scheme(Some(Scheme::Https));
        let mode = ProxyMode::manual(
            HashMap::from([
                (Scheme::Http, ProxyEntry::Unusable(lost.clone())),
                (Scheme::Https, ProxyEntry::Unusable(inherited.clone())),
                (Scheme::Ftp, ProxyEntry::Disabled),
            ]),
            BypassRules::new(),
        );
        // In `Scheme::ALL`'s order, not the map's, which is seeded per instance: the same
        // reason the `Debug` above sorts.
        assert_eq!(mode.rejected(), Some(&[lost, inherited][..]));
    }

    #[test]
    fn with_rejected_attaches_the_list_to_a_manual_mode() {
        let mode = ProxyMode::manual(HashMap::new(), BypassRules::new())
            .with_rejected(vec![rejection("http=not a host")]);
        assert_eq!(
            mode.rejected().unwrap()[0].redacted_input(),
            "http=not a host"
        );
        let debug = format!("{mode:?}");
        assert!(debug.contains("not a host"), "{debug}");
    }

    #[test]
    fn with_rejected_attaches_the_list_to_the_pac_modes_too() {
        let url = Url::parse("http://wpad.corp/proxy.pac").expect("the fixture URL parses");
        for mode in [
            ProxyMode::pac(url),
            ProxyMode::pac_inline("function FindProxyForURL(u, h) {}".to_owned()),
        ] {
            let mode = mode.with_rejected(vec![rejection("ProxyAutoDiscoveryEnable=yes")]);
            assert_eq!(
                mode.rejected().unwrap()[0].redacted_input(),
                "ProxyAutoDiscoveryEnable=yes",
                "{mode:?}"
            );
        }
    }

    // `Direct` and `WpadAutoDetect` have nowhere to put a list, which is also why no backend
    // hands them one: a reader that dropped something answers `Manual` instead of `Direct`,
    // and every WPAD return is reached only from a flag that read cleanly.
    #[test]
    fn the_field_less_modes_have_no_list_and_swallow_one() {
        for mode in [ProxyMode::Direct, ProxyMode::WpadAutoDetect] {
            assert!(mode.rejected().is_none(), "{mode:?}");
            let after = mode.clone().with_rejected(vec![rejection("ignored")]);
            assert_eq!(after, mode);
            assert!(after.rejected().is_none(), "{after:?}");
        }
    }

    // Two [`ProxyMode::Manual`] values built from identical input
    // (including identical `rejected` text) must compare equal so
    // [`ProxyConfig`](crate::ProxyConfig)'s duplicate-notification suppression keeps
    // working now that `rejected` is part of the derived [`PartialEq`].
    #[test]
    fn manual_modes_with_equal_rejected_lists_are_equal() {
        let a = ProxyMode::manual(HashMap::new(), BypassRules::new())
            .with_rejected(vec![rejection("http=garbage")]);
        let b = ProxyMode::manual(HashMap::new(), BypassRules::new())
            .with_rejected(vec![rejection("http=garbage")]);
        assert_eq!(a, b);

        let c = ProxyMode::manual(HashMap::new(), BypassRules::new())
            .with_rejected(vec![rejection("http=other-garbage")]);
        assert_ne!(a, c);
    }
}