Merge branch 'hserror' into 'main'

tor-error: Errors for hidden services

See merge request tpo/core/arti!1099

crates/tor-error/Cargo.toml

@@ -13,6 +13,7 @@ categories = ["rust-patterns"]
 
 [features]
 default = ["backtrace"]
+experimental-api = []
 
 [dependencies]
 backtrace = { version = "0.3.39", optional = true }

crates/tor-error/README.md

@@ -8,4 +8,22 @@ and associated [`HasKind`] trait.
 There is also some other miscellany, supporting error handling in
 crates higher up the dependency stack.
 
+## Features
+
+`backtrace` -- Enable backtraces in internal errors.  (On by default.)
+
+### 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.
+
+[^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-error/src/lib.rs

@@ -454,6 +454,39 @@ pub enum ErrorKind {
     #[display(fmt = "remote hostname not found")]
     RemoteHostNotFound,
 
+    /// The target hidden service (`.onion` service) was not found in the directory
+    ///
+    /// We successfully connected to at least one directory server,
+    /// but it didn't have a record of the hidden service.
+    ///
+    /// This probably means that the hidden service is not running, or does not exist.
+    /// (It might mean that the directory servers are faulty,
+    /// and that the hidden service was unable to publish its descriptor.)
+    #[cfg(feature = "experimental-api")]
+    #[display(fmt = "Onion Service not found")]
+    OnionServiceNotFound,
+
+    /// The target hidden service (`.onion` service) seems to be down
+    ///
+    /// We successfully obtained a hidden service descriptor for the service,
+    /// so we know it is supposed to exist,
+    /// but we weren't able to communicate with it via any of its
+    /// introduction points.
+    ///
+    /// This probably means that the hidden service is not running.
+    /// (It might mean that the introduction point relays are faulty.)
+    #[cfg(feature = "experimental-api")]
+    #[display(fmt = "Onion Service not running")]
+    OnionServiceNotRunning,
+
+    /// Protocol trouble involving the target hidden service (`.onion` service)
+    ///
+    /// Something unexpected happened when trying to connect to the selected hidden service.
+    /// It seems to have been due to the hidden service violating the Tor protocols somehow.
+    #[cfg(feature = "experimental-api")]
+    #[display(fmt = "Onion Service protocol failed (apprently due to service behaviour)")]
+    OnionServiceProtocolFailed,
+
     /// An resolve operation finished with an error.
     ///
     /// Contrary to [`RemoteHostNotFound`](ErrorKind::RemoteHostNotFound),