feat(lib): join the distributed search network as a leaf

The server hands every client a list of possible parents and expects it to
hang from one so searches also travel peer to peer. Until now we told the
server we were a lone root and left it at that, which the network tolerates
but does not favour.

A leaf now dials each PossibleParents candidate over a D connection, adopts
the first that passes a search down after stating its branch, announces the
new branch root and level to the server, and answers those searches the same
way as ones from the server. Losing the parent or a ResetDistributed puts it
back to a parentless stance. The leaf takes no children.

The Leaf state machine is pure so its rules are unit-tested without sockets;
the e2e test drives a real client from a mock parent, since soulfind never
hands out parents.

soulseek-rs-lib/src/client/mod.rs

@@ -334,11 +334,40 @@ pub enum ClientOperation {
         requester_key: String,
         filename: String,
     },
+    /// Distributed-network parent candidates, from the server or a host.
+    PossibleParents(Vec<(String, String, u16)>),
+    /// The server told us to drop our parent.
+    ResetDistributed,
+    /// A parent candidate told us how deep it sits.
+    ParentBranchLevel {
+        parent: String,
+        level: i32,
+    },
+    /// A parent candidate told us whose branch it is on.
+    ParentBranchRoot {
+        parent: String,
+        root: String,
+    },
+    /// A search came down the tree from `parent`.
+    ParentSearch {
+        parent: String,
+        username: String,
+        token: u32,
+        query: String,
+    },
+    /// The link to a parent or candidate is gone.
+    ParentClosed {
+        parent: String,
+    },
 }
 pub struct ClientContext {
     pub peer_registry: Option<PeerRegistry>,
     pub downloads: DownloadStore,
     server_sender: Option<Sender<ServerMessage>>,
+    /// Where anything outside the operations loop posts operations.
+    operations: Option<Sender<ClientOperation>>,
+    /// Our place in the distributed search network.
+    leaf: distributed::Leaf,
     searches: HashMap<String, Search>,
     private_messages: Vec<UserMessage>,
     /// Correlation tokens for server-brokered (firewalled) connections, mapping
@@ -452,6 +481,8 @@ impl ClientContext {
         Self {
             peer_registry: None,
             server_sender: None,
+            operations: None,
+            leaf: distributed::Leaf::new(""),
             searches: HashMap::new(),
             private_messages: Vec::new(),
             pending_connect_tokens: HashMap::new(),
@@ -982,6 +1013,7 @@ impl Client {
 }
 
 mod connection;
+mod distributed;
 mod downloads;
 mod operations;
 mod rooms;