//! Implement GuardFilter and related types.

use tor_linkspec::ChanTarget;

// TODO(nickm): Conceivably, this type should be exposed from a lower-level crate than

// tor-netdoc.

use tor_netdoc::types::policy::AddrPortPattern;

use tor_relay_selection::{LowLevelRelayPredicate, RelayRestriction, RelaySelector, RelayUsage};

/// An object specifying which relays are eligible to be guards.

///

/// We _always_ restrict the set of possible guards to be the set of

/// relays currently listed in the consensus directory document, and

/// tagged with the `Guard` flag.  But clients may narrow the eligible set

/// even further—for example, to those supporting only a given set of ports,

/// or to those in a given country.

#[derive(Debug, Clone, Default, Eq, PartialEq)]

pub struct GuardFilter {

    /// A list of filters to apply to guard or fallback selection.  Each filter

    /// restricts which guards may be used, and possibly how those guards may be

    /// contacted.

    ///

    /// This list of filters has "and" semantics: a relay is permitted by this

    /// filter if ALL patterns in this list permit that first hop.

    filters: Vec<SingleFilter>,

}

/// A single restriction places upon usable guards.

#[derive(Debug, Clone, Eq, PartialEq)]

enum SingleFilter {

    /// A set of allowable addresses that we are willing to try to connect to.

    ///

    /// This list of patterns has "or" semantics: a guard is permitted by this filter

    /// if ANY pattern in this list permits one of the guard's addresses.

    ReachableAddrs(Vec<AddrPortPattern>),

}

impl GuardFilter {

    /// Create a new [`GuardFilter`] that doesn't restrict the set of

    /// permissible guards at all.

    /// Restrict this filter to only permit connections to an address permitted

    /// by one of the patterns in `addrs`.

    /// Return true if this filter permits the provided `target`.

    /// Modify `first_hop` so that it contains no elements not permitted by this

    /// filter.

    ///

    /// (For example, if we are restricted only to use certain addresses, then

    /// `permits` will return true for a guard that has multiple addresses even

    /// if _some_ of those addresses are not permitted.  In that scenario, this

    /// method will remove disallowed addresses from `first_hop`.)

        }

    /// Return true if this filter excludes no guards at all.

    /// Return a fraction between 0.0 and 1.0 describing what fraction of the

    /// guard bandwidth this filter permits.

        use tor_netdir::{RelayWeight, WeightRole};

        // TODO #504: This is an unaccompanied RelayUsage, and is therefore a

        // bit suspect.  We should consider whether we like this behavior,

        // or whether we should convert it into a RelaySelector.

        //

        // It is not _too_ bad, however, since we're only looking at the

        // fraction of the relays that might be guards; we won't use these

        // relays without later choosing them via a RelaySelector.  Nonetheless,

        // it would be better to construct a RelaySelector.

        // TODO: There is a case to be made for converting "permitted by this

        // address-port filter?" into a RelayRestriction.

        }

    /// Update `selector` with all the restrictions from this filter.

        // TODO #504: There is a case to be made that we should refactor

        // `tor-guardmgr` crate so that GuardFilter no longer exists

        // independently, but instead is just a part of RelaySelector.

        //

        // But before we do that, we should let the rest of #504 settle.

}

impl SingleFilter {

    /// Return true if this filter permits the provided target.

            // TODO: This is partially duplicated with tor-relay-selection,

            // but (for now) that only covers Relays, not general ChanTargets.

                        // Check whether _any_ address actually used by this

                        // method is permitted by _any_ pattern.

                        // This target doesn't use addresses: only hostnames or "None"

                    }

            }

        }

    /// Modify `first_hop` so that it contains no elements not permitted by this

    /// filter.

    ///

    /// It is an internal error to call this function on a guard not already

    /// passed by `self.permits()`.

                    // TODO(nickm): The fact that this check needs to be checked

                    // happen indicates a likely problem in our code design.

                    // Right now, we have `modify_hop` and `permits` as separate

                    // methods because our GuardSet logic needs a way to check

                    // whether a guard will be permitted by a filter without

                    // actually altering that guard (since another filter might

                    // be used in the future that would allow the same guard).

                    //

                    // To mitigate the risk of hitting this error, we try to

                    // make sure that modify_hop is always called right after

                    // (or at least soon after) the filter is checked, with the

                    // same filter object.

            }

        }

}

#[cfg(test)]

mod test {

    // @@ begin test lint list maintained by maint/add_warning @@

    #![allow(clippy::bool_assert_comparison)]

    #![allow(clippy::clone_on_copy)]

    #![allow(clippy::dbg_macro)]

    #![allow(clippy::mixed_attributes_style)]

    #![allow(clippy::print_stderr)]

    #![allow(clippy::print_stdout)]

    #![allow(clippy::single_char_pattern)]

    #![allow(clippy::unwrap_used)]

    #![allow(clippy::unchecked_time_subtraction)]

    #![allow(clippy::useless_vec)]

    #![allow(clippy::needless_pass_by_value)]

    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->

    use super::*;

    use float_eq::assert_float_eq;

    use tor_netdir::testnet;

    #[test]

    fn permissiveness() {

        let nd = testnet::construct_netdir().unwrap_if_sufficient().unwrap();

        const TOL: f64 = 0.01;

        let non_filter = GuardFilter::default();

        assert_float_eq!(non_filter.frac_bw_permitted(&nd), 1.0, abs <= TOL);

        let forbid_all = {

            let mut f = GuardFilter::default();

            f.push_reachable_addresses(vec!["*:1".parse().unwrap()]);

            f

        };

        assert_float_eq!(forbid_all.frac_bw_permitted(&nd), 0.0, abs <= TOL);

        let net_1_only = {

            let mut f = GuardFilter::default();

            f.push_reachable_addresses(vec!["1.0.0.0/8:*".parse().unwrap()]);

            f

        };

        assert_float_eq!(net_1_only.frac_bw_permitted(&nd), 0.28, abs <= TOL);

    }

}