Merge branch 'circmgr' into 'main'

tor-circmgr make get_or_launch_dir_specific depend on specific-relay feature

See merge request tpo/core/arti!795

crates/tor-chanmgr/src/transport/proxied.rs

@@ -377,6 +377,7 @@ fn settings_to_protocol(s: String) -> Result<Protocol, ProxyError> {
 #[cfg(test)]
 mod test {
     #![allow(clippy::unwrap_used)]
+    #[allow(unused_imports)]
     use super::*;
 
     #[cfg(feature = "pt-client")]

crates/tor-circmgr/Cargo.toml

@@ -17,8 +17,9 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
 #
 # These APIs are not covered by semantic versioning.  Using this
 # feature voids your "semver warrantee".
-experimental = ["experimental-api"]
+experimental = ["experimental-api", "specific-relay"]
 experimental-api = []
+specific-relay = []
 
 [dependencies]
 async-trait = "0.1.2"

crates/tor-circmgr/README.md

@@ -16,10 +16,26 @@ anticipate those needs.  If a client request can be satisfied with
 an existing circuit, it should return that circuit instead of
 constructing a new one.
 
-## Limitations
+## Compile-time features
 
-But for now, this `tor-circmgr` code is extremely preliminary; its
-data structures are all pretty bad, and it's likely that the API
-is wrong too.
+### Experimental and unstable features
+
+Note that the APIs enabled by these features are NOT covered by
+semantic versioning[^1] guarantees: we might break them or remove
+them between patch versions.
+
+* `experimental-api`: Add additional non-stable APIs to our public
+  interfaces.
+
+* `specific-relay`: Support for connecting to a relay via
+   specifically provided connection instructions, rather than
+   using information from a Tor network directory.
+
+* `experimental`: Enable all the above experimental features.
+
+[^1]: Remember, semantic versioning is what makes various `cargo`
+features work reliably. To be explicit: if you want `cargo update`
+to _only_ make safe changes, then you cannot enable these
+features.
 
 License: MIT OR Apache-2.0

crates/tor-circmgr/src/lib.rs

@@ -38,11 +38,14 @@
 
 use tor_basic_utils::retry::RetryDelay;
 use tor_chanmgr::ChanMgr;
-use tor_linkspec::{ChanTarget, OwnedChanTarget};
+use tor_linkspec::ChanTarget;
 use tor_netdir::{DirEvent, NetDir, NetDirProvider, Timeliness};
 use tor_proto::circuit::{CircParameters, ClientCirc, UniqId};
 use tor_rtcompat::Runtime;
 
+#[cfg(feature = "specific-relay")]
+use tor_linkspec::OwnedChanTarget;
+
 use futures::task::SpawnExt;
 use futures::StreamExt;
 use std::sync::{Arc, Mutex, Weak};
@@ -420,7 +423,9 @@ impl<R: Runtime> CircMgr<R> {
     /// Return a circuit to a specific relay, suitable for using for directory downloads.
     ///
     /// This could be used, for example, to download a descriptor for a bridge.
-    pub async fn get_or_launch_dir_bridge<T: Into<OwnedChanTarget>>(
+    #[cfg_attr(docsrs, doc(cfg(feature = "specific-relay")))]
+    #[cfg(feature = "specific-relay")]
+    pub async fn get_or_launch_dir_specific<T: Into<OwnedChanTarget>>(
         &self,
         target: T,
     ) -> Result<ClientCirc> {

crates/tor-circmgr/src/usage.rs

@@ -10,11 +10,13 @@ use tracing::debug;
 use crate::path::{dirpath::DirPathBuilder, exitpath::ExitPathBuilder, TorPath};
 use tor_chanmgr::ChannelUsage;
 use tor_guardmgr::{GuardMgr, GuardMonitor, GuardUsable};
-use tor_linkspec::OwnedChanTarget;
 use tor_netdir::Relay;
 use tor_netdoc::types::policy::PortPolicy;
 use tor_rtcompat::Runtime;
 
+#[cfg(feature = "specific-relay")]
+use tor_linkspec::OwnedChanTarget;
+
 use crate::isolation::{IsolationHelper, StreamIsolation};
 use crate::mgr::{abstract_spec_find_supported, AbstractCirc, OpenEntry, RestrictionFailed};
 use crate::Result;
@@ -160,6 +162,7 @@ pub(crate) enum TargetCircUsage {
     },
     /// Use for BEGINDIR-based non-anonymous directory connections to a particular target,
     /// and therefore to a specific relay (which need not be in any netdir).
+    #[cfg(feature = "specific-relay")]
     DirSpecificTarget(OwnedChanTarget),
 }
 
@@ -183,6 +186,7 @@ pub(crate) enum SupportedCircUsage {
     NoUsage,
     /// Use only for BEGINDIR-based non-anonymous directory connections
     /// to a particular target (which may not be in the netdir).
+    #[cfg(feature = "specific-relay")]
     DirSpecificTarget(OwnedChanTarget),
 }
 
@@ -257,6 +261,7 @@ impl TargetCircUsage {
 
                 Ok((path, usage, mon, usable))
             }
+            #[cfg(feature = "specific-relay")]
             TargetCircUsage::DirSpecificTarget(target) => {
                 let path = TorPath::new_one_hop_owned(target);
                 let usage = SupportedCircUsage::DirSpecificTarget(target.clone());
@@ -373,7 +378,9 @@ impl crate::mgr::AbstractSpec for SupportedCircUsage {
         use ChannelUsage as CU;
         use SupportedCircUsage as SCU;
         match self {
-            SCU::Dir | SCU::DirSpecificTarget(_) => CU::Dir,
+            SCU::Dir => CU::Dir,
+            #[cfg(feature = "specific-relay")]
+            SCU::DirSpecificTarget(_) => CU::Dir,
             SCU::Exit { .. } => CU::UserTraffic,
             SCU::NoUsage => CU::UselessCircuit,
         }

crates/tor-dirmgr/Cargo.toml

@@ -15,7 +15,7 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
 default = ["mmap"]
 full = ["routerdesc"]
 experimental = ["experimental-api", "dirfilter", "bridge-client"]
-bridge-client = ["tor-guardmgr/bridge-client", "routerdesc"]
+bridge-client = ["tor-circmgr/specific-relay", "tor-guardmgr/bridge-client", "routerdesc"]
 
 mmap = ["memmap2"]
 static = ["rusqlite/bundled"]

crates/tor-dirmgr/README.md

@@ -26,10 +26,6 @@ reading large directory objects from disk.
 `routerdesc` -- (Incomplete) support for downloading and storing
      router descriptors.
 
-### Experimental features
-
-## Compile-time features
-
 ### Experimental and unstable features
 
 Note that the APIs enabled by these features are NOT covered by