Define accessors for circuit hops.

Closes #415

crates/tor-proto/src/circuit.rs

@@ -193,6 +193,24 @@ pub(crate) struct StreamTarget {
 }
 
 impl ClientCirc {
+    /// Return a description of the first hop of this circuit.
+    ///
+    /// # Panics
+    ///
+    /// Panics if there is no first hop.  (This should be impossible outside of
+    /// the tor-proto crate, but within the crate it's possible to have a
+    /// circuit with no hops.)
+    pub fn first_hop(&self) -> OwnedChanTarget {
+        self.path
+            .first_hop()
+            .expect("called first_hop on an un-constructed circuit")
+    }
+
+    /// Return a description of all the hops in this circuit.
+    pub fn path(&self) -> Vec<OwnedChanTarget> {
+        self.path.all_hops()
+    }
+
     /// Extend the circuit via the ntor handshake to a new target last
     /// hop.
     pub async fn extend_ntor<Tg>(&self, target: &Tg, params: &CircParameters) -> Result<()>
@@ -1029,6 +1047,13 @@ mod test {
 
             // Did we really add another hop?
             assert_eq!(circ.n_hops(), 4);
+
+            // Do the path accessors report a reasonable outcome?
+            let path = circ.path();
+            assert_eq!(path.len(), 4);
+            use tor_linkspec::ChanTarget;
+            assert_eq!(path[3].ed_identity(), example_target().ed_identity());
+            assert_ne!(path[0].ed_identity(), example_target().ed_identity());
         });
     }
 

crates/tor-proto/src/circuit/path.rs

@@ -23,4 +23,18 @@ impl Path {
     pub(super) fn push_hop(&self, target: OwnedChanTarget) {
         self.hops.lock().expect("poisoned lock").push(target);
     }
+
+    /// Return an OwnedChanTarget representing the first hop of this path.
+    pub(super) fn first_hop(&self) -> Option<OwnedChanTarget> {
+        self.hops
+            .lock()
+            .expect("poisoned lock")
+            .get(0)
+            .map(Clone::clone)
+    }
+
+    /// Return a copy of all the hops in this path.
+    pub(super) fn all_hops(&self) -> Vec<OwnedChanTarget> {
+        self.hops.lock().expect("poisoned lock").clone()
+    }
 }

doc/semver_status.md

@@ -65,6 +65,9 @@ tor-netdoc:
 
   api-break: changed the return type of GenericRouterStatus::version()
 
+tor-proto:
+  new-api: ClientCirc path accessors.
+
 tor-protover:
   new-api: Protocols now implements Eq, PartialEq, and Hash.