//! Descriptions objects for different kinds of directory requests

//! that we can make.

use tor_circmgr::ClientDirTunnel;

use tor_llcrypto::pk::rsa::RsaIdentity;

use tor_netdoc::doc::authcert::AuthCertKeyIds;

use tor_netdoc::doc::microdesc::MdDigest;

use tor_netdoc::doc::netstatus::ConsensusFlavor;

#[cfg(feature = "routerdesc")]

use tor_netdoc::doc::routerdesc::{ExtraInfoDigest, RdDigest};

#[cfg(feature = "hs-client")]

use tor_hscrypto::pk::HsBlindId;

/// Alias for a result with a `RequestError`.

type Result<T> = std::result::Result<T, crate::err::RequestError>;

use base64ct::{Base64Unpadded, Encoding as _};

use std::borrow::Cow;

use std::future::Future;

use std::iter::FromIterator;

use std::pin::Pin;

use std::sync::Arc;

use std::time::{Duration, SystemTime};

use itertools::Itertools;

use crate::AnonymizedRequest;

use crate::body::RequestBody;

use crate::err::RequestError;

/// Declare an inaccessible public type.

pub(crate) mod sealed {

    use tor_circmgr::ClientDirTunnel;

    use crate::body::RequestBody;

    use super::{AnonymizedRequest, Result};

    use std::future::Future;

    use std::pin::Pin;

    /// Sealed trait to help implement [`Requestable`](super::Requestable): not

    /// visible outside this crate, so we can change its methods however we like.

    pub trait RequestableInner: Send + Sync {

        /// Build an [`http::Request`] from this Requestable, if

        /// it is well-formed.

        fn make_request(&self) -> Result<http::Request<RequestBody>>;

        /// Return true if partial response bodies are potentially useful.

        ///

        /// This is true for request types where we're going to be downloading

        /// multiple documents, and we know how to parse out the ones we wanted

        /// if the answer is truncated.

        fn partial_response_body_ok(&self) -> bool;

        /// Return the maximum allowable response length we'll accept for this

        /// request.

        fn max_response_len(&self) -> usize;

        /// Optimization: return an error if there is some problem with the provided circuit that

        /// makes it unlikely to be useful for this request.

        ///

        /// *Do not* use this method to check for security properties.

        /// Return a value to say whether this request must be anonymized.

        fn anonymized(&self) -> AnonymizedRequest;

    }

}

/// A request for an object that can be served over the Tor directory system.

pub trait Requestable: sealed::RequestableInner {

    /// Return a wrapper around this [`Requestable`] that implements `Debug`,

    /// and whose output shows the actual HTTP request that will be generated.

    ///

    /// The format is not guaranteed to  be stable.

    {

}

impl<T: sealed::RequestableInner> Requestable for T {}

/// A wrapper to implement [`Requestable::debug_request`].

pub struct DisplayRequestable<'a, R: Requestable>(&'a R);

impl<'a, R: Requestable> std::fmt::Debug for DisplayRequestable<'a, R> {

}

impl sealed::RequestableInner for Arc<dyn Requestable> {

}

/// How much clock skew do we allow in the distance between the directory

/// cache's clock and our own?

///

///  If we find more skew than this, we end the

/// request early, on the theory that the directory will not tell us any

/// information we'd accept.

#[derive(Clone, Debug)]

struct SkewLimit {

    /// We refuse to proceed if the directory says we are more fast than this.

    ///

    /// (This is equivalent to deciding that, from our perspective, the

    /// directory is at least this slow.)

    max_fast: Duration,

    /// We refuse to proceed if the directory says that we are more slow than

    /// this.

    ///

    /// (This is equivalent to deciding that, from our perspective, the

    /// directory is at least this fast.)

    max_slow: Duration,

}

/// A Request for a consensus directory.

#[derive(Debug, Clone)]

pub struct ConsensusRequest {

    /// What flavor of consensus are we asking for?  Right now, only

    /// "microdesc" and "ns" are supported.

    flavor: ConsensusFlavor,

    /// A list of the authority identities that we believe in.  We tell the

    /// directory cache only to give us a consensus if it is signed by enough

    /// of these authorities.

    authority_ids: Vec<RsaIdentity>,

    /// The publication time of the most recent consensus we have.  Used to

    /// generate an If-Modified-Since header so that we don't get a document

    /// we already have.

    last_consensus_published: Option<SystemTime>,

    /// A set of SHA3-256 digests of the _signed portion_ of consensuses we have.

    /// Used to declare what diffs we would accept.

    last_consensus_sha3_256: Vec<[u8; 32]>,

    /// If present, the largest amount of clock skew to allow between ourself and a directory cache.

    skew_limit: Option<SkewLimit>,

}

impl ConsensusRequest {

    /// Create a new request for a consensus directory document.

    /// Add `id` to the list of authorities that this request should

    /// say we believe in.

    /// Add `d` to the list of consensus digests this request should

    /// say we already have.

    /// Set the publication time we should say we have for our last

    /// consensus to `when`.

    /// Return a slice of the consensus digests that we're saying we

    /// already have.

    /// Return an iterator of the authority identities that this request

    /// is saying we believe in.

    /// Return the date we're reporting for our most recent consensus.

    /// Tell the directory client that we should abort the request early if the

    /// directory's clock skew exceeds certain limits.

    ///

    /// The `max_fast` parameter is the most fast that we're willing to be with

    /// respect to the directory (or in other words, the most slow that we're

    /// willing to let the directory be with respect to us).

    ///

    /// The `max_slow` parameter is the most _slow_ that we're willing to be with

    /// respect to the directory ((or in other words, the most slow that we're

    /// willing to let the directory be with respect to us).

}

/// Convert a list of digests in some format to a string, for use in a request

///

/// The digests `DL` will be sorted, converted to strings with `EF`,

/// separated with `sep`, and returned as an fresh `String`.

///

/// If the digests list is empty, returns None instead.

//

// In principle this ought to be doable with much less allocating,

// starting with hex::encode etc.

{

    // name collision with unstable Iterator::intersperse

    // https://github.com/rust-lang/rust/issues/48919

impl Default for ConsensusRequest {

}

impl sealed::RequestableInner for ConsensusRequest {

        // Build the URL.

        }

        // Without authorities, "../consensus-microdesc"

        // Possibly, add an if-modified-since header.

        // Possibly, add an X-Or-Diff-From-Consensus header.

            use tor_proto::ClockSkew::*;

            // This is the clock skew _according to the directory_.

                }

                }

            }

}

/// A request for one or more authority certificates.

#[derive(Debug, Clone, Default)]

pub struct AuthCertRequest {

    /// The identity/signing keys of the certificates we want.

    ids: Vec<AuthCertKeyIds>,

}

impl AuthCertRequest {

    /// Create a new request, asking for no authority certificates.

    /// Add `ids` to the list of certificates we're asking for.

    /// Return a list of the keys that we're asking for.

}

impl sealed::RequestableInner for AuthCertRequest {

                    "{}-{}",

                )

        // TODO: Pick a more principled number; I just made this one up.

}

impl FromIterator<AuthCertKeyIds> for AuthCertRequest {

}

/// A request for one or more microdescriptors

#[derive(Debug, Clone, Default)]

pub struct MicrodescRequest {

    /// The SHA256 digests of the microdescriptors we want.

    digests: Vec<MdDigest>,

}

impl MicrodescRequest {

    /// Construct a request for no microdescriptors.

    /// Add `d` to the list of microdescriptors we want to request.

    /// Return a list of the microdescriptor digests that we're asking for.

}

impl sealed::RequestableInner for MicrodescRequest {

        // TODO: Pick a more principled number; I just made this one up.

}

impl FromIterator<MdDigest> for MicrodescRequest {

}

/// A request for one, many or all router descriptors.

#[derive(Debug, Clone)]

#[cfg(feature = "routerdesc")]

pub struct RouterDescRequest {

    /// The descriptors to request.

    requested_descriptors: RequestedDescs,

}

/// Tracks the different router descriptor types.

#[derive(Debug, Clone)]

#[cfg(feature = "routerdesc")]

enum RequestedDescs {

    /// If this is set, we just ask for all the descriptors.

    All,

    /// A list of digests to download.

    Digests(Vec<RdDigest>),

}

#[cfg(feature = "routerdesc")]

// TODO: This is probably not a reasonable default.

impl Default for RouterDescRequest {

}

#[cfg(feature = "routerdesc")]

impl RouterDescRequest {

    /// Construct a request for all router descriptors.

    /// Construct a new empty request.

}

#[cfg(feature = "routerdesc")]

impl sealed::RequestableInner for RouterDescRequest {

            }

        }

        }

        // TODO: Pick a more principled number; I just made these up.

        }

}

#[cfg(feature = "routerdesc")]

impl FromIterator<RdDigest> for RouterDescRequest {

}

/// A request for the descriptor of whatever relay we are making the request to

#[derive(Debug, Clone, Default)]

#[cfg(feature = "routerdesc")]

#[non_exhaustive]

pub struct RoutersOwnDescRequest {}

#[cfg(feature = "routerdesc")]

impl RoutersOwnDescRequest {

    /// Construct a new request.

}

#[cfg(feature = "routerdesc")]

impl sealed::RequestableInner for RoutersOwnDescRequest {

        // As of 2026, directory authorities don't accept a routerdesc longer than

        // 20000 bytes.  This should be plenty for the foreseeable future.

}

/// A request for one or many extra-infos.

///

/// <https://spec.torproject.org/dir-spec/general-use-http-urls.html>

/// (search in page for "extra-info")

#[derive(Debug, Clone)]

#[cfg(feature = "routerdesc")]

pub struct ExtraInfoRequest {

    /// The extra-infos to request.

    requested_extra_infos: RequestedExtraInfos,

}

/// Which extra-info documents to download.

///

/// Currently only a subset of the available URLs are supported.

#[derive(Debug, Clone)]

#[cfg(feature = "routerdesc")]

#[non_exhaustive]

enum RequestedExtraInfos {

    /// Just ask for all the extra-infos.

    ///

    /// `http://<hostname>/tor/extra/all`

    All,

    /// Download extra-infos with these SHA-1 digests.

    ///

    /// `http://<hostname>/tor/extra/d/...`

    Digests(Vec<ExtraInfoDigest>),

}

#[cfg(feature = "routerdesc")]

impl Default for ExtraInfoRequest {

    // TODO: This is probably not a reasonable default.

}

#[cfg(feature = "routerdesc")]

impl ExtraInfoRequest {

    /// Construct a request for all extra-infos.

    /// Construct a new empty request.

}

#[cfg(feature = "routerdesc")]

impl sealed::RequestableInner for ExtraInfoRequest {

            }

        }

        }

        // TODO torspec#392: Pick more principled size limits.

        // These were copied from the RouterDescRequest impl and doubled.

        }

}

#[cfg(feature = "routerdesc")]

impl FromIterator<ExtraInfoDigest> for ExtraInfoRequest {

}

/// A request to download a hidden service descriptor

///

/// rend-spec-v3 2.2.6

#[derive(Debug, Clone)]

#[cfg(feature = "hs-client")]

pub struct HsDescDownloadRequest {

    /// What hidden service?

    hsid: HsBlindId,

    /// What's the largest acceptable response length?

    max_len: usize,

}

#[cfg(feature = "hs-client")]

impl HsDescDownloadRequest {

    /// Construct a request for a single onion service descriptor by its

    /// blinded ID.

        /// Default maximum length to use when we have no other information.

        const DEFAULT_HSDESC_MAX_LEN: usize = 50_000;

    /// Set the maximum acceptable response length.

}

#[cfg(feature = "hs-client")]

impl sealed::RequestableInner for HsDescDownloadRequest {

        // We hardcode version 3 here; if we ever have a v4 onion service

        // descriptor, it will need a different kind of Request.

}

/// Define a request type for uploading a document.

#[allow(unused)]

macro_rules! upload_request {

    {

        $(

            $(#[$m:meta])*

            pub struct $t:ident (

                // Does this request require anonymity?

                // This should be a variant of AnonymizedRequest.

                $anonymity:ident,

                // To what URI at the server should the document be posted?

                // This should begin with "/tor">

                $uri:expr,

                // Total maximum length of the _response_ that we'll accept.

                // If the response is larger than this, we'll abort the request.

                //

                // Note that expected response body for a POST is typically _empty_,

                // but this needs to be nonzero in order to account for

                // the status line and headers.

                $max_response_len:expr

            )

        );*

        $(;)?

    } => {

        $(

            $(#[$m])*

            #[derive(Clone, Debug)]

            pub struct $t(Arc<str>);

            impl $t {

                /// Create a new upload request

            }

            impl sealed::RequestableInner for $t {

                    /// The upload URI.

                    const URI: &str = $uri;

                    $max_response_len

            }

         )*

    }

}

#[cfg(feature = "hs-service")]

upload_request! {

    /// A request to upload a hidden service descriptor

    ///

    /// rend-spec-v3 2.2.6

    pub struct HsDescUploadRequest(

        Anonymized,

        "/tor/hs/3/publish",

        // A real Tor POST _response_ will always be less than this length, which

        // will fit into 3 DATA messages at most. (The reply will be a single

        // HTTP line, followed by a Date header.)

        // Do not increase this limit without thinking about side channels!

        //

        // (Note that the body will be empty, but we need to allow some space

        // to account for the status line and headers.)

        1024

    )

}

#[cfg(feature = "relay")]

upload_request! {

    /// A request to upload a router descriptor and optional extra-info document.

    pub struct UploadRouterDesc(Direct, "/tor/", 4096);

}

/// Encodings that all Tor clients support.

const UNIVERSAL_ENCODINGS: &str = "deflate, identity";

/// List all the encodings we accept

    #[allow(unused_mut)]

    #[cfg(feature = "xz")]

    #[cfg(feature = "zstd")]

/// Add commonly used headers to the HTTP request.

///

/// (Right now, this is only Accept-Encoding.)

    // TODO: gzip, brotli

        AnonymizedRequest::Anonymized => {

            // In an anonymized request, we do not admit to supporting any

            // encoding besides those that are always available.

        }

    }

#[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::sealed::RequestableInner;

    use super::*;

    use web_time_compat::SystemTimeExt;

    #[test]

    fn test_md_request() -> Result<()> {

        let d1 = b"This is a testing digest. it isn";

        let d2 = b"'t actually SHA-256.............";

        let mut req = MicrodescRequest::default();

        req.push(*d1);

        assert!(!req.partial_response_body_ok());

        req.push(*d2);

        assert!(req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), 16 << 10);

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/micro/d/J3QgYWN0dWFsbHkgU0hBLTI1Ni4uLi4uLi4uLi4uLi4-VGhpcyBpcyBhIHRlc3RpbmcgZGlnZXN0LiBpdCBpc24 HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        // Try it with FromIterator, and use some accessors.

        let req2: MicrodescRequest = vec![*d1, *d2].into_iter().collect();

        let ds: Vec<_> = req2.digests().collect();

        assert_eq!(ds, vec![d1, d2]);

        let req2 = crate::util::request_to_string(&req2.make_request()?);

        assert_eq!(req, req2);

        Ok(())

    }

    #[test]

    fn test_cert_request() -> Result<()> {

        let d1 = b"This is a testing dn";

        let d2 = b"'t actually SHA-256.";

        let key1 = AuthCertKeyIds {

            id_fingerprint: (*d1).into(),

            sk_fingerprint: (*d2).into(),

        };

        let d3 = b"blah blah blah 1 2 3";

        let d4 = b"I like pizza from Na";

        let key2 = AuthCertKeyIds {

            id_fingerprint: (*d3).into(),

            sk_fingerprint: (*d4).into(),

        };

        let mut req = AuthCertRequest::default();

        req.push(key1);

        assert!(!req.partial_response_body_ok());

        req.push(key2);

        assert!(req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), 32 << 10);

        let keys: Vec<_> = req.keys().collect();

        assert_eq!(keys, vec![&key1, &key2]);

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/keys/fp-sk/5468697320697320612074657374696e6720646e-27742061637475616c6c79205348412d3235362e+626c616820626c616820626c6168203120322033-49206c696b652070697a7a612066726f6d204e61 HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        let req2: AuthCertRequest = vec![key1, key2].into_iter().collect();

        let req2 = crate::util::request_to_string(&req2.make_request()?);

        assert_eq!(req, req2);

        Ok(())

    }

    #[test]

    fn test_consensus_request() -> Result<()> {

        let d1 = RsaIdentity::from_bytes(

            &hex::decode("03479E93EBF3FF2C58C1C9DBF2DE9DE9C2801B3E").unwrap(),

        )

        .unwrap();

        let d2 = b"blah blah blah 12 blah blah blah";

        let d3 = SystemTime::get();

        let mut req = ConsensusRequest::default();

        let when = httpdate::fmt_http_date(d3);

        req.push_authority_id(d1);

        req.push_old_consensus_digest(*d2);

        req.set_last_consensus_date(d3);

        assert!(!req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), (16 << 20) - 1);

        assert_eq!(req.old_consensus_digests().next(), Some(d2));

        assert_eq!(req.authority_ids().next(), Some(&d1));

        assert_eq!(req.last_consensus_date(), Some(d3));

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/status-vote/current/consensus-microdesc/03479e93ebf3ff2c58c1c9dbf2de9de9c2801b3e HTTP/1.0\r\naccept-encoding: {}\r\nif-modified-since: {}\r\nx-or-diff-from-consensus: 626c616820626c616820626c616820313220626c616820626c616820626c6168\r\n\r\n",

                all_encodings(),

                when

            )

        );

        // Request without authorities

        let req = ConsensusRequest::default();

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/status-vote/current/consensus-microdesc HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        Ok(())

    }

    #[test]

    #[cfg(feature = "routerdesc")]

    fn test_rd_request_all() -> Result<()> {

        let req = RouterDescRequest::all();

        assert!(req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), 1 << 26);

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/server/all HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        Ok(())

    }

    #[test]

    #[cfg(feature = "routerdesc")]

    fn test_rd_request() -> Result<()> {

        let d1 = b"at some point I got ";

        let d2 = b"of writing in hex...";

        let mut req = RouterDescRequest::default();

        if let RequestedDescs::Digests(ref mut digests) = req.requested_descriptors {

            digests.push(*d1);

        }

        assert!(!req.partial_response_body_ok());

        if let RequestedDescs::Digests(ref mut digests) = req.requested_descriptors {

            digests.push(*d2);

        }

        assert!(req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), 16 << 10);

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/server/d/617420736f6d6520706f696e74204920676f7420+6f662077726974696e6720696e206865782e2e2e HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        // Try it with FromIterator, and use some accessors.

        let req2: RouterDescRequest = vec![*d1, *d2].into_iter().collect();

        let ds: Vec<_> = match req2.requested_descriptors {

            RequestedDescs::Digests(ref digests) => digests.iter().collect(),

            RequestedDescs::All => Vec::new(),

        };

        assert_eq!(ds, vec![d1, d2]);

        let req2 = crate::util::request_to_string(&req2.make_request()?);

        assert_eq!(req, req2);

        Ok(())

    }

    #[test]

    #[cfg(feature = "routerdesc")]

    fn test_extra_info_request() -> Result<()> {

        let req = ExtraInfoRequest::from_iter([[0; 20], [1; 20], [2; 20]]);

        assert_eq!(

            crate::util::request_to_string(&req.make_request()?),

            format!(

                "GET /tor/extra/d/{}+{}+{} HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                hex::encode_upper([0; 20]),

                hex::encode_upper([1; 20]),

                hex::encode_upper([2; 20]),

                all_encodings()

            )

        );

        let req = ExtraInfoRequest::all();

        assert_eq!(

            crate::util::request_to_string(&req.make_request()?),

            format!(

                "GET /tor/extra/all HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                all_encodings()

            )

        );

        Ok(())

    }

    #[test]

    #[cfg(feature = "hs-client")]

    fn test_hs_desc_download_request() -> Result<()> {

        use tor_llcrypto::pk::ed25519::Ed25519Identity;

        let hsid = [1, 2, 3, 4].iter().cycle().take(32).cloned().collect_vec();

        let hsid = Ed25519Identity::new(hsid[..].try_into().unwrap());

        let hsid = HsBlindId::from(hsid);

        let req = HsDescDownloadRequest::new(hsid);

        assert!(!req.partial_response_body_ok());

        assert_eq!(req.max_response_len(), 50 * 1000);

        let req = crate::util::request_to_string(&req.make_request()?);

        assert_eq!(

            req,

            format!(

                "GET /tor/hs/3/AQIDBAECAwQBAgMEAQIDBAECAwQBAgMEAQIDBAECAwQ HTTP/1.0\r\naccept-encoding: {}\r\n\r\n",

                UNIVERSAL_ENCODINGS

            )

        );

        Ok(())

    }

}