Merge branch 'onion-api-client-toplevel' into 'main'

Make a top-level API for connecting to onion services.

See merge request tpo/core/arti!971

Cargo.lock

@@ -185,6 +185,7 @@ dependencies = [
  "tor-dirmgr",
  "tor-error",
  "tor-guardmgr",
+ "tor-hscrypto",
  "tor-llcrypto",
  "tor-netdir",
  "tor-netdoc",

crates/arti-client/Cargo.toml

@@ -49,24 +49,25 @@ accel-openssl = ["tor-llcrypto/with-openssl"]
 
 compression = ["tor-dirmgr/compression"]
 
-# Enable experimental APIs that are not yet officially supported.
-#
-# These APIs are not covered by semantic versioning.  Using this
-# feature voids your "semver warrantee".
 experimental = [
     "dirfilter",
     "experimental-api",
     "error_detail",
+    "onion-client",
     "tor-proto/experimental",
     "tor-cell/experimental",
     "tor-checkable/experimental",
     "tor-netdoc/experimental",
     "tor-dirmgr/experimental",
     "tor-circmgr/experimental",
-]
+] # Enable experimental APIs that are not yet officially supported.
+#
+# These APIs are not covered by semantic versioning.  Using this
+# feature voids your "semver warrantee".
 experimental-api = []
 dirfilter = ["tor-dirmgr/dirfilter"]
 error_detail = []
+onion-client = ["tor-hscrypto"]
 
 [dependencies]
 cfg-if = "1.0.0"
@@ -95,6 +96,7 @@ tor-dirmgr = { path = "../tor-dirmgr", version = "0.9.0", default-features = fal
 ] }
 tor-error = { path = "../tor-error", version = "0.4.0" }
 tor-guardmgr = { path = "../tor-guardmgr", version = "0.8.0" }
+tor-hscrypto = { path = "../tor-hscrypto", version = "0.1.0", optional = true }
 tor-llcrypto = { path = "../tor-llcrypto", version = "0.4.0" }
 tor-netdir = { path = "../tor-netdir", version = "0.7.0" }
 tor-netdoc = { path = "../tor-netdoc", version = "0.6.0" }

crates/arti-client/README.md

@@ -208,6 +208,9 @@ implementation with another.
 * `error_detail` -- expose the `arti_client::Error` inner error type.
 * `dirfilter` -- expose the `DirFilter` API, which lets you modify a network
   directory before it is used.
+* `onion-client` -- build with non-working stub APIs to support connecting to
+  onion services.  (These do not work yet, and will just cause your code to
+  panic.)
 
 * `experimental` -- Build with all experimental features above, along with
   all experimental features from other arti crates.

crates/arti-client/src/address.rs

@@ -179,6 +179,7 @@ impl TorAddr {
                 return Err(ErrorDetail::InvalidHostname);
             }
             if addr.to_lowercase().ends_with(".onion") {
+                // TODO hs: Allow this in some cases instead.
                 return Err(ErrorDetail::OnionAddressNotSupported);
             }
         }
@@ -219,6 +220,15 @@ enum Host {
     Hostname(String),
     /// An IP address.
     Ip(IpAddr),
+    // /// The address of an onion service.
+    //
+    // TODO hs possibly we should just have this be another type of "hostname".
+    //
+    // TODO hs possibly the contents of this enum should be a String rather than
+    // an OnionId.
+    //
+    // #[cfg(feature = "onion-client")]
+    // OnionService(OnionId),
 }
 
 impl FromStr for Host {

crates/arti-client/src/client.rs

@@ -168,6 +168,10 @@ pub struct StreamPrefs {
     isolation: StreamIsolationPreference,
     /// Whether to return the stream optimistically.
     optimistic_stream: bool,
+    /// Whether to try to make connections to onion services.
+    #[cfg(feature = "onion-client")]
+    #[allow(dead_code)]
+    connect_to_onion_services: bool, // TODO hs: this should default to "true".
 }
 
 /// Record of how we are isolating connections
@@ -263,6 +267,8 @@ impl StreamPrefs {
         self
     }
 
+    // TODO hs: make setters for the `connect_to_onion_services` field.
+
     /// Return a TargetPort to describe what kind of exit policy our
     /// target circuit needs to support.
     fn wrap_target_port(&self, port: u16) -> TargetPort {