#![cfg_attr(docsrs, feature(doc_cfg))]

#![doc = include_str!("../README.md")]

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

#![allow(renamed_and_removed_lints)] // @@REMOVE_WHEN(ci_arti_stable)

#![allow(unknown_lints)] // @@REMOVE_WHEN(ci_arti_nightly)

#![warn(missing_docs)]

#![warn(noop_method_call)]

#![warn(unreachable_pub)]

#![warn(clippy::all)]

#![deny(clippy::await_holding_lock)]

#![deny(clippy::cargo_common_metadata)]

#![deny(clippy::cast_lossless)]

#![deny(clippy::checked_conversions)]

#![allow(clippy::cognitive_complexity)] // See arti#2556

#![deny(clippy::debug_assert_with_mut_call)]

#![deny(clippy::exhaustive_enums)]

#![deny(clippy::exhaustive_structs)]

#![deny(clippy::expl_impl_clone_on_copy)]

#![deny(clippy::fallible_impl_from)]

#![deny(clippy::implicit_clone)]

#![deny(clippy::large_stack_arrays)]

#![warn(clippy::manual_ok_or)]

#![deny(clippy::missing_docs_in_private_items)]

#![warn(clippy::needless_borrow)]

#![warn(clippy::needless_pass_by_value)]

#![warn(clippy::option_option)]

#![deny(clippy::print_stderr)]

#![deny(clippy::print_stdout)]

#![warn(clippy::rc_buffer)]

#![deny(clippy::ref_option_ref)]

#![warn(clippy::semicolon_if_nothing_returned)]

#![warn(clippy::trait_duplication_in_bounds)]

#![deny(clippy::unchecked_time_subtraction)]

#![deny(clippy::unnecessary_wraps)]

#![warn(clippy::unseparated_literal_suffix)]

#![deny(clippy::unwrap_used)]

#![deny(clippy::mod_module_files)]

#![allow(clippy::let_unit_value)] // This can reasonably be done for explicitness

#![allow(clippy::uninlined_format_args)]

#![allow(clippy::significant_drop_in_scrutinee)] // arti/-/merge_requests/588/#note_2812945

#![allow(clippy::result_large_err)] // temporary workaround for arti#587

#![allow(clippy::needless_raw_string_hashes)] // complained-about code is fine, often best

#![allow(clippy::needless_lifetimes)] // See arti#1765

#![allow(mismatched_lifetime_syntaxes)] // temporary workaround for arti#2060

#![allow(clippy::collapsible_if)] // See arti#2342

#![deny(clippy::unused_async)]

#![deny(clippy::string_slice)] // See arti#2571

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

use std::fmt;

use std::ops::{RangeInclusive, RangeToInclusive};

use std::path::Path;

use std::time::Duration;

pub mod error_sources;

pub mod intern;

pub mod iter;

pub mod n_key_list;

pub mod n_key_set;

pub mod rand_hostname;

pub mod rangebounds;

pub mod retry;

pub mod test_rng;

pub mod token_bucket;

mod byte_qty;

pub use byte_qty::ByteQty;

pub use paste::paste;

#[doc(hidden)]

pub use derive_deftly;

use extend::ext;

use rand::Rng;

/// Sealed

mod sealed {

    /// Sealed

    pub trait Sealed {}

}

use sealed::Sealed;

// ----------------------------------------------------------------------

/// Function with the signature of `Debug::fmt` that just prints `".."`

///

/// ```

/// use educe::Educe;

/// use tor_basic_utils::skip_fmt;

///

/// #[derive(Educe, Default)]

/// #[educe(Debug)]

/// struct Wombat {

///     visible: usize,

///

///     #[educe(Debug(method = "skip_fmt"))]

///     invisible: [u8; 2],

/// }

///

/// assert_eq!( format!("{:?}", &Wombat::default()),

///             "Wombat { visible: 0, invisible: .. }" );

/// ```

    /// Inner function avoids code bloat due to generics

// ----------------------------------------------------------------------

/// Formats an iterator as an object whose display implementation is a `separator`-separated string

/// of items from `iter`.

///

/// Performs a similar function to `Itertools::format`.  Differences:

///

///  * `Itertools::format` panics if the returned formatting helper is formatted twice;

///    conversely, `iter_join` requires that the iterator be `Clone`.

///  * `iter_join` only supports `Display`; `.format` supports all formatting traits.

///  * `iter_join` accepts an `IntoIterator` rather than requiring an `Iterator`.

//

// TODO maybe this should be an extension trait method?

    // TODO MSRV 1.93: Replace with `std::fmt::from_fn()`?

    struct Fmt<'a, I: IntoIterator<Item: fmt::Display> + Clone> {

        /// Separates items in `iter`.

        separator: &'a str,

        /// Iterator to join.

        iter: I,

    }

    impl<'a, I: IntoIterator<Item: fmt::Display> + Clone> fmt::Display for Fmt<'a, I> {

            }

    }

// ----------------------------------------------------------------------

/// Extension trait to provide `.strip_suffix_ignore_ascii_case()` etc.

#[ext(name = StrExt)]

pub impl str {

    /// Like `str.strip_suffix()` but ASCII-case-insensitive

    /// Like `str.ends_with()` but ASCII-case-insensitive

}

// ----------------------------------------------------------------------

/// Extension trait to provide `.gen_range_checked()`

pub trait RngExt: Rng {

    /// Generate a random value in the given range.

    ///

    /// This function is optimised for the case that only a single sample is made from the given range. See also the [`Uniform`](rand::distr::uniform::Uniform)  distribution type which may be faster if sampling from the same range repeatedly.

    ///

    /// If the supplied range is empty, returns `None`.

    ///

    /// (This is a non-panicking version of [`rand::RngExt::random_range`].)

    ///

    /// ### Example

    ///

    /// ```

    /// use tor_basic_utils::RngExt as _;

    //

    // Fake plastic imitation tor_error, since that's actually higher up the stack

    /// # #[macro_use]

    /// # mod tor_error {

    /// #     #[derive(Debug)]

    /// #     pub struct Bug;

    /// #     pub fn internal() {} // makes `use` work

    /// # }

    /// # macro_rules! internal { { $x:expr } => { Bug } }

    //

    /// use tor_error::{Bug, internal};

    ///

    /// fn choose(slice: &[i32]) -> Result<i32, Bug> {

    ///     let index = rand::rng()

    ///         .gen_range_checked(0..slice.len())

    ///         .ok_or_else(|| internal!("empty slice"))?;

    ///     Ok(slice[index])

    /// }

    ///

    /// assert_eq!(choose(&[42]).unwrap(), 42);

    /// let _: Bug = choose(&[]).unwrap_err();

    /// ```

    //

    // TODO: We may someday wish to rename this function to random_range_checked,

    // since gen_range was renamed to random_range in rand 0.9.

    // Or we might decide to leave it alone.

    {

        #[allow(clippy::disallowed_methods)]

        {

            // Prove that rand::RngExt::random_range exists.  See arti.git/clippy.toml.

        }

        } else {

            use rand::RngExt;

            #[allow(clippy::disallowed_methods)]

        }

    /// Generate a random value in the given upper-bounded-only range.

    ///

    /// For use with an inclusive upper-bounded-only range,

    /// with types that implement `GenRangeInfallible`

    /// (that necessarily then implement the appropriate `rand` traits).

    ///

    /// This function is optimised for the case that only a single sample is made from the given range. See also the [`Uniform`](rand::distr::uniform::Uniform)  distribution type which may be faster if sampling from the same range repeatedly.

    ///

    /// ### Example

    ///

    /// ```

    /// use std::time::Duration;

    /// use tor_basic_utils::RngExt as _;

    ///

    /// fn stochastic_sleep(max: Duration) {

    ///     let chosen_delay = rand::rng()

    ///         .gen_range_infallible(..=max);

    ///     std::thread::sleep(chosen_delay);

    /// }

    /// ```

    {

}

impl<T: Rng> RngExt for T {}

/// Types that can be infallibly sampled using `gen_range_infallible`

///

/// In addition to the supertraits, the implementor of this trait must guarantee that:

///

/// `<Self as GenRangeInfallible>::lower_bound() ..= UPPER`

/// is a nonempty range for every value of `UPPER`.

//

// One might think that this trait is wrong because we might want to be able to

// implement gen_range_infallible for arguments other than RangeToInclusive<T>.

// However, double-ended ranges are inherently fallible because the actual values

// might be in the wrong order.  Non-inclusive ranges are fallible because the

// upper bound might be zero, unless a NonZero type is used, which seems like a further

// complication that we probably don't want to introduce here.  That leaves lower-bounded

// ranges, but those are very rare.

pub trait GenRangeInfallible: rand::distr::uniform::SampleUniform + Ord

where

    RangeInclusive<Self>: rand::distr::uniform::SampleRange<Self>,

{

    /// The usual lower bound, for converting a `RangeToInclusive` to a `RangeInclusive`

    ///

    /// Only makes sense with types with a sensible lower bound, such as zero.

    fn lower_bound() -> Self;

}

impl GenRangeInfallible for Duration {

}

// ----------------------------------------------------------------------

/// Renaming of `Path::display` as `display_lossy`

#[ext(supertraits = Sealed)]

pub impl Path {

    /// Display this `Path` as an approximate string, for human consumption in messages

    ///

    /// Operating system paths cannot always be faithfully represented as Rust strings,

    /// because they might not be valid Unicode.

    ///

    /// This helper method provides a way to display a string for human users.

    /// **This may lose information** so should only be used for error messages etc.

    ///

    /// This method is exactly the same as [`std::path::Path::display`],

    /// but with a different and more discouraging name.

    #[allow(clippy::disallowed_methods)]

}

impl Sealed for Path {}

// ----------------------------------------------------------------------

/// Define an "accessor trait", which describes structs that have fields of certain types

///

/// This can be useful if a large struct, living high up in the dependency graph,

/// contains fields that lower-lever crates want to be able to use without having

/// to copy the data about etc.

///

/// ```

/// // imagine this in the lower-level module

/// pub trait Supertrait {}

/// use tor_basic_utils::define_accessor_trait;

/// define_accessor_trait! {

///     pub trait View: Supertrait {

///         lorem: String,

///         ipsum: usize,

///         +

///         fn other_accessor(&self) -> bool;

///         // any other trait items can go here

///    }

/// }

///

/// fn test_view<V: View>(v: &V) {

///     assert_eq!(v.lorem(), "sit");

///     assert_eq!(v.ipsum(), &42);

/// }

///

/// // imagine this in the higher-level module

/// use derive_more::AsRef;

/// #[derive(AsRef)]

/// struct Everything {

///     #[as_ref] lorem: String,

///     #[as_ref] ipsum: usize,

///     dolor: Vec<()>,

/// }

/// impl Supertrait for Everything { }

/// impl View for Everything {

///     fn other_accessor(&self) -> bool { false }

/// }

///

/// let everything = Everything {

///     lorem: "sit".into(),

///     ipsum: 42,

///     dolor: vec![()],

/// };

///

/// test_view(&everything);

/// ```

///

/// ### Generated code

///

/// ```

/// # pub trait Supertrait { }

/// pub trait View: AsRef<String> + AsRef<usize> + Supertrait {

///     fn lorem(&self) -> &String { self.as_ref() }

///     fn ipsum(&self) -> &usize { self.as_ref() }

/// }

/// ```

#[macro_export]

macro_rules! define_accessor_trait {

    {

        $( #[ $attr:meta ])*

        $vis:vis trait $Trait:ident $( : $( $Super:path )* )? {

            $( $accessor:ident: $type:ty, )*

            $( + $( $rest:tt )* )?

        }

    } => {

        $( #[ $attr ])*

        $vis trait $Trait: $( core::convert::AsRef<$type> + )* $( $( $Super + )* )?

        {

            $(

                /// Access the field

            )*

            $(

                $( $rest )*

            )?

        }

    }

}

// ----------------------------------------------------------------------

/// Helper for assisting with macro "argument" defaulting

///

/// ```ignore

/// macro_first_nonempty!{ [ something ]  ... }  // =>   something

/// macro_first_nonempty!{ [ ], [ other ] ... }  // =>   other

/// // etc.

/// ```

///

/// ### Usage note

///

/// It is generally possible to avoid use of `macro_first_nonempty`, at the cost of

/// providing many alternative matcher patterns.  Using `macro_first_nonempty` can make

/// it possible to provide a single pattern with the optional items in `$( )?`.

///

/// This is valuable because a single pattern with some optional items

/// makes much better documentation than several patterns which the reader must compare

/// by eye - and it also simplifies the implementation.

///

/// `macro_first_nonempty` takes each of its possible expansions in `[ ]` and returns

/// the first nonempty one.

#[macro_export]

macro_rules! macro_first_nonempty {

    { [ $($yes:tt)+ ] $($rhs:tt)* } => { $($yes)* };

    { [ ]$(,)? [ $($otherwise:tt)* ] $($rhs:tt)* } => {

        $crate::macro_first_nonempty!{ [ $($otherwise)* ] $($rhs)* }

    };

}

/// Helper for assisting with defining macros that need to expand

/// conditionally when an argument is empty.

///

/// ```ignore

/// if_empty!{ {   } { x } { y } } // => x

/// if_empty!{ { z } { x } { y } } // => y

/// // etc.

/// ```

///

/// Note: The `{ y }` argument may be omitted.

#[macro_export]

macro_rules! if_empty {

    { { }                  { $($x:tt)* } $({ $($y:tt)* })? } => { $($x)* };

    { { $($nonempty:tt)+ } { $($x:tt)* } $({ $($y:tt)* })? } => { $($($y)*)? };

}

// ----------------------------------------------------------------------

/// Define `Debug` to print as hex

///

/// # Usage

///

/// ```ignore

/// impl_debug_hex! { $type }

/// impl_debug_hex! { $type . $field_accessor }

/// impl_debug_hex! { $type , $accessor_fn }

/// ```

///

/// By default, this expects `$type` to implement `AsRef<[u8]>`.

///

/// Or, you can supply a series of tokens `$field_accessor`,

/// which will be used like this: `self.$field_accessor.as_ref()`

/// to get a `&[u8]`.

///

/// Or, you can supply `$accessor: fn(&$type) -> &[u8]`.

///

/// # Examples

///

/// ```

/// use tor_basic_utils::impl_debug_hex;

/// #[derive(Default)]

/// struct FourBytes([u8; 4]);

/// impl AsRef<[u8]> for FourBytes { fn as_ref(&self) -> &[u8] { &self.0 } }

/// impl_debug_hex! { FourBytes }

///

/// assert_eq!(

///     format!("{:?}", FourBytes::default()),

///     "FourBytes(00000000)",

/// );

/// ```

///

/// ```

/// use tor_basic_utils::impl_debug_hex;

/// #[derive(Default)]

/// struct FourBytes([u8; 4]);

/// impl_debug_hex! { FourBytes .0 }

///

/// assert_eq!(

///     format!("{:?}", FourBytes::default()),

///     "FourBytes(00000000)",

/// );

/// ```

///

/// ```

/// use tor_basic_utils::impl_debug_hex;

/// struct FourBytes([u8; 4]);

/// impl_debug_hex! { FourBytes, |self_| &self_.0 }

///

/// assert_eq!(

///     format!("{:?}", FourBytes([1,2,3,4])),

///     "FourBytes(01020304)",

/// )

/// ```

#[macro_export]

macro_rules! impl_debug_hex {

    { $type:ty $(,)? } => {

        $crate::impl_debug_hex! { $type, |self_| <$type as AsRef<[u8]>>::as_ref(&self_) }

    };

    { $type:ident . $($accessor:tt)+ } => {

    };

    { $type:ty, $obtain:expr $(,)? } => {

        impl std::fmt::Debug for $type {

                use std::fmt::Write;

                }

        }

    };

}

// ----------------------------------------------------------------------

/// Helper for defining a struct which can be (de)serialized several ways, including "natively"

///

/// Ideally we would have

/// ```rust ignore

/// #[derive(Deserialize)]

/// #[serde(try_from=Possibilities)]

/// struct Main { /* principal definition */ }

///

/// #[derive(Deserialize)]

/// #[serde(untagged)]

/// enum Possibilities { Main(Main), Other(OtherRepr) }

///

/// #[derive(Deserialize)]

/// struct OtherRepr { /* other representation we still want to read */ }

///

/// impl TryFrom<Possibilities> for Main { /* ... */ }

/// ```

///

/// But the impl for `Possibilities` ends up honouring the `try_from` on `Main`

/// so is recursive.

///

/// We solve that (ab)using serde's remote feature,

/// on a second copy of the struct definition.

///

/// See the Example for instructions.

/// It is important to **add test cases**

/// for all the representations you expect to parse and serialise,

/// since there are easy-to-write bugs,

/// for example omitting some of the necessary attributes.

///

/// # Generated output:

///

///  * The original struct definition, unmodified

///  * `#[derive(Serialize, Deserialize)] struct $main_Raw { }`

///

/// The `$main_Raw` struct ought not normally be to constructed anywhere,

/// and *isn't* convertible to or from the near-identical `$main` struct.

/// It exists only as a thing to feed to the serde remove derive,

/// and name in `with=`.

///

/// # Example

///

/// ```

/// use serde::{Deserialize, Serialize};

/// use tor_basic_utils::derive_serde_raw;

///

/// derive_serde_raw! {

///     #[derive(Deserialize, Serialize, Default, Clone, Debug)]

///     #[serde(try_from="BridgeConfigBuilderSerde", into="BridgeConfigBuilderSerde")]

///     pub struct BridgeConfigBuilder = "BridgeConfigBuilder" {

///         transport: Option<String>,

///         //...

///     }

/// }

///

/// #[derive(Serialize,Deserialize)]

/// #[serde(untagged)]

/// enum BridgeConfigBuilderSerde {

///     BridgeLine(String),

///     Dict(#[serde(with="BridgeConfigBuilder_Raw")] BridgeConfigBuilder),

/// }

///

/// impl TryFrom<BridgeConfigBuilderSerde> for BridgeConfigBuilder { //...

/// #    type Error = std::io::Error;

/// #    fn try_from(_: BridgeConfigBuilderSerde) -> Result<Self, Self::Error> { todo!() } }

/// impl From<BridgeConfigBuilder> for BridgeConfigBuilderSerde { //...

/// #    fn from(_: BridgeConfigBuilder) -> BridgeConfigBuilderSerde { todo!() } }

/// ```

#[macro_export]

macro_rules! derive_serde_raw { {

    $( #[ $($attrs:meta)* ] )*

    $vis:vis struct $main:ident=$main_s:literal

    $($body:tt)*

} => {

    $(#[ $($attrs)* ])*

    $vis struct $main

    $($body)*

    $crate::paste! {

        #[allow(non_camel_case_types)]

        #[derive(Serialize, Deserialize)]

        #[serde(remote=$main_s)]

        struct [< $main _Raw >]

        $($body)*

    }

} }

// ----------------------------------------------------------------------

/// Give a compile time error if TYPE implements TRAIT

///

/// Includes the identifier $rule in the error message, to help the user diagnose

/// the problem (unlike the similar macro in `static_assertions`.

///

/// Supports generics (also, unlike the one in static_assertions`).

///

/// # Input syntaxes

///

/// ```

// With a fair amount of trickery, we can get the compiler to (mostly) syntax-check this!

/// # #![allow(nonstandard_style)]

/// # use tor_basic_utils::assert_not_impl;

/// # use std::cell::Cell;

/// # type TYPE = Cell<u32>;

/// # use Sync as TRAIT;

/// assert_not_impl! { [RULE_IDENTIFIER] TYPE: TRAIT }

//

// We can't get the compiler to syntax check this one:

// error[E0207]: the type parameter `TYPE_GENERICS` is not constrained ...

// Instead, we hide it from the compiler and write a very similar test, hidden from the reader.

/// # let _ = r#"

/// assert_not_impl! { [RULE_IDENTIFIER <TYPE_GENERICS>] TYPE: TRAIT }

/// # "#;

/// # assert_not_impl! { [RULE_IDENTIFIER <TYPE_GENERICS>] Cell<TYPE_GENERICS>: TRAIT }

/// ```

///

///  * `RULE_IDENTIFIER` is an arbitrary identifier; it will appear in the error message.

///    (There is no way to include arbitrary explanatory text.)

///  * `TYPE_GENERICS` are generic bindings needed for `TYPE`.

///    (Generics on the trait are not supported.)

///

/// # Examples

///

/// ```

/// use std::cell::Cell;

/// use tor_basic_utils::assert_not_impl;

///

/// // No error will occur; Cell is not Sync

/// assert_not_impl! {

///     [cell_must_not_be_sync] Cell<u32>: Sync

/// }

/// assert_not_impl! {

///     [cell_must_not_be_sync <T: Copy>]

///     Cell<T>: Sync

/// }

/// ```

///

/// ```compile_fail

/// // Compile-time error _is_ given; String implements Clone.

/// assert_not_impl! {

///     [clone_is_forbidden_here] String: Clone

/// }

/// ```

#[macro_export]

macro_rules! assert_not_impl {

    // we can't match the trailing > of generics - only the leading <

    {[$rule:ident $( < $($gens:tt)* )? ] $t:ty : $trait:path } => {

        const _ : () = {

            #[allow(dead_code, non_camel_case_types)]

            trait $rule<X> {

                fn item();

            }

            impl$( < $($gens)* )? $rule<()> for $t {

            }

            struct Invalid;

        };

    }

}

// ----------------------------------------------------------------------

/// Asserts that the type of the expression implements the given trait.

///

/// Example:

///

/// ```

/// # use tor_basic_utils::assert_val_impl_trait;

/// let x: u32 = 0;

/// assert_val_impl_trait!(x, Clone);

/// ```

#[macro_export]

macro_rules! assert_val_impl_trait {

    ($check:expr, $trait:path $(,)?) => {{

        ensure_trait(&$check);

    }};

}

// ----------------------------------------------------------------------

#[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)]

    #![allow(clippy::string_slice)] // See arti#2571

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

    use super::*;

    #[test]

    fn test_strip_suffix_ignore_ascii_case() {

        assert_eq!(

            "hi there".strip_suffix_ignore_ascii_case("THERE"),

            Some("hi ")

        );

        assert_eq!("hi here".strip_suffix_ignore_ascii_case("THERE"), None);

        assert_eq!("THERE".strip_suffix_ignore_ascii_case("there"), Some(""));

        assert_eq!("hi".strip_suffix_ignore_ascii_case("THERE"), None);

    }

}