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/message/distributed.rs

@@ -5,6 +5,7 @@
 //! 93 EmbeddedMessage.
 
 use crate::message::Message;
+use crate::message::server::MessageFactory;
 
 /// A search relayed through the tree carries this in its first field; anything
 /// else is a frame we do not understand and must not answer.
@@ -30,10 +31,12 @@ pub fn parse(message: &mut Message) -> Option<Distributed> {
         return None;
     }
     message.set_pointer(5);
-    parse_body(message, message.get_init_code())
+    parse_at(message, message.get_init_code())
 }
 
-fn parse_body(message: &mut Message, code: u8) -> Option<Distributed> {
+/// Decode the body that follows a one-byte `code`, the pointer already past it.
+#[must_use]
+pub fn parse_at(message: &mut Message, code: u8) -> Option<Distributed> {
     match code {
         3 => {
             if message.read_int32() != SEARCH_IDENTIFIER {
@@ -55,7 +58,7 @@ fn parse_body(message: &mut Message, code: u8) -> Option<Distributed> {
         // Older branch roots wrap a search in a code-93 envelope.
         93 => {
             let inner = message.read_int8();
-            parse_body(message, inner)
+            parse_at(message, inner)
         }
         _ => None,
     }
@@ -87,6 +90,18 @@ pub fn build_branch_level(level: i32) -> Message {
     })
 }
 
+/// What we tell the server about our place in the tree: the four messages
+/// Nicotine+ sends together whenever it changes.
+#[must_use]
+pub fn stance(root: &str, level: u32, has_parent: bool) -> Vec<Message> {
+    vec![
+        MessageFactory::build_have_no_parent(!has_parent),
+        MessageFactory::build_branch_root(root),
+        MessageFactory::build_branch_level(level),
+        MessageFactory::build_accept_children(false),
+    ]
+}
+
 #[must_use]
 pub fn build_branch_root(root: &str) -> Message {
     framed(5, |m| {