feat(iroh-base): Implement From & Into between NodeAddr and `No…

…deTicket` (#2717)

## Description

Previously, when all you had was a `NodeTicket`, all you could get was a
reference `&NodeAddr` from it to use with `Endpoint::connect`, which
requires an *owned* `NodeAddr`.

This adds `From` impls for converting between `NodeTicket` and
`NodeAddr`, so you can call `endpoint.connect(ticket.into())`.
<!-- A summary of what this pull request achieves and a rough list of
changes. -->

## Breaking Changes

None - only additions.
<!-- Optional, if there are any breaking changes document them,
including how to migrate older code. -->

## Notes & open questions

When I originally raised this, I thought of making the `node_addr`
argument `impl Into<NodeAddr>`, but we have an `instrument(remote =
%node_addr.node_id.fmt_sort)` annotation on that function. Due to
ownership, it's hard to make that work with `impl Into<NodeAddr>`. As
far as I can see there's three options:
- Make it `node_addr: impl Into<NodeAddr> + Clone`
- Split `Endpoint::connect` into two functions, a public, outer one with
`node_addr: impl Into<NodeAddr>` and without an `instrument` annotation,
and an inner private one with `node_addr: NodeAddr`, but with an
`instrument` annotation.
- We just keep it as `node_addr: NodeAddr` with the `instrument`
annotation and require users to call `.into()`.

I found the third option to be the simplest. @flub please let me know if
that sounds good.
<!-- Any notes, remarks or open questions you have to make about the PR.
-->

## Change checklist

- [x] Self-review.
- [x] Documentation updates following the [style
guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text),
if relevant.
- ~~[ ] Tests if relevant.~~ I honestly don't think we need tests for
this.
- [x] All breaking changes documented.

---------

Co-authored-by: Floris Bruynooghe <flub@n0.computer>

iroh-base/src/ticket/node.rs

@@ -10,9 +10,19 @@ use crate::{
     ticket::{self, Ticket},
 };
 
-/// A token containing everything to get a file from the provider.
+/// A token containing information for establishing a connection to a node.
 ///
-/// It is a single item which can be easily serialized and deserialized.
+/// Contains
+/// - The [`NodeId`] of the node to connect to (a 32-byte ed25519 public key).
+/// - If used, the ['RelayUrl`] of on which the node can be reached.
+/// - Any *direct addresses* on which the node might be reachable.
+///
+/// This allows establishing a connection to the node in most circumstances where it is
+/// possible to do so.
+///
+/// This [`NodeTicket`] is a single item which can be easily serialized and deserialized.
+///
+/// [`NodeId`]: crate::key::NodeId
 #[derive(Debug, Clone, PartialEq, Eq, derive_more::Display)]
 #[display("{}", Ticket::serialize(self))]
 pub struct NodeTicket {
@@ -60,6 +70,20 @@ impl NodeTicket {
     }
 }
 
+impl From<NodeAddr> for NodeTicket {
+    /// Creates a ticket from given addressing info.
+    fn from(addr: NodeAddr) -> Self {
+        Self { node: addr }
+    }
+}
+
+impl From<NodeTicket> for NodeAddr {
+    /// Returns the addressing info from given ticket.
+    fn from(ticket: NodeTicket) -> Self {
+        ticket.node
+    }
+}
+
 impl Serialize for NodeTicket {
     fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
         if serializer.is_human_readable() {