fix(daemon): correct the published contract and harden the control socket

A review pass over the diff found seventeen confirmed defects. The worst was
the contract itself: every method's parameters were published as a single
descriptor named `params`, so a client generated from openrpc.json sent
{"params":{"params":{…}}} and every call failed -32602. Parameters are now
published per field, with a test asserting the published names are the keys
the daemon actually deserializes.

Security and lifecycle:
- download.start no longer lets a caller name a directory, which was an
  arbitrary write on the daemon's host.
- The Unix socket is bound under a temporary name and renamed into place; it
  was briefly connectable by any local user between bind and chmod, and on
  that transport connecting is authenticating.
- Pre-auth reads are capped at 1 MiB with a 30s handshake timeout, and
  connections are capped, so an unauthenticated peer cannot exhaust memory or
  threads.
- A read error no longer returns past the hub unsubscribe, which leaked a
  subscriber and two threads per occurrence.
- A client whose event queue fills is now actually disconnected. It used to be
  dropped from the fan-out and left connected, working on but blind to every
  event after — the documentation already promised otherwise.
- A client whose daemon vanishes mid-transfer is told at once instead of
  waiting out its full timeout and reporting a misleading "gave up".

Contract accuracy: errors carry an explicit null id (a missing one reads as a
notification and gets dropped), a second auth answers with the published
shape, and nullable fields are sent rather than omitted so a generated client
sees one shape.

Also splits proto.rs and server.rs, whose concerns had diverged, and applies
the review's simplifications.

soulseek-rs/src/daemon/hub.rs

@@ -12,7 +12,7 @@
 
 use super::proto::{
     BrowseEvent, ChatMessageDto, DownloadStatusEvent, Event, Response,
-    SessionLossEvent, UploadInfoDto, UserMessageDto,
+    SessionLossEvent, UploadInfoDto, UploadStatusDto, UserMessageDto,
 };
 use crate::api::SessionApi;
 use soulseek_rs::DownloadStatus;
@@ -39,6 +39,14 @@ const HISTORY_LIMIT: usize = 500;
 struct Subscriber {
     id: u64,
     sender: SyncSender<Response>,
+    /// How to end this client's connection. A stalled client cannot be
+    /// reached any other way, and leaving it attached but silently eventless
+    /// is worse than disconnecting it: it would keep working while missing
+    /// every room message, transfer update and upload it should have seen.
+    ///
+    /// A closure rather than the socket itself, so the hub stays ignorant of
+    /// what a connection is made of.
+    disconnect: Box<dyn Fn() + Send + Sync>,
 }
 
 /// Fans daemon-side events out to every attached connection.
@@ -61,12 +69,20 @@ impl Hub {
     }
 
     /// Attach a connection. The returned receiver yields notifications until
-    /// [`Hub::unsubscribe`] or a full queue drops it.
-    pub fn subscribe(&self) -> (u64, Receiver<Response>) {
+    /// [`Hub::unsubscribe`], or until a full queue costs the client its
+    /// connection.
+    pub fn subscribe(
+        &self,
+        disconnect: impl Fn() + Send + Sync + 'static,
+    ) -> (u64, Receiver<Response>) {
         let id = self.next_id.fetch_add(1, Ordering::Relaxed);
         let (sender, receiver) = sync_channel(QUEUE_DEPTH);
         if let Ok(mut subscribers) = self.subscribers.lock() {
-            subscribers.push(Subscriber { id, sender });
+            subscribers.push(Subscriber {
+                id,
+                sender,
+                disconnect: Box::new(disconnect),
+            });
         }
         (id, receiver)
     }
@@ -78,7 +94,9 @@ impl Hub {
     }
 
     pub fn subscribers(&self) -> usize {
-        self.subscribers.lock().map_or(0, |subscribers| subscribers.len())
+        self.subscribers
+            .lock()
+            .map_or(0, |subscribers| subscribers.len())
     }
 
     /// Send one event to everyone, dropping any client that has stopped
@@ -93,9 +111,14 @@ impl Hub {
                 Ok(()) => true,
                 Err(TrySendError::Full(_)) => {
                     soulseek_rs::warn!(
-                        "control client {} is not reading its events; dropping it",
+                        "control client {} is not reading its events; \
+                         disconnecting it",
                         subscriber.id
                     );
+                    // Closing the socket is the point: a client dropped from
+                    // the fan-out but left connected would carry on believing
+                    // it was subscribed, silently blind to everything after.
+                    (subscriber.disconnect)();
                     false
                 }
                 Err(TrySendError::Disconnected(_)) => false,
@@ -192,11 +215,8 @@ impl PendingBrowses {
         pending.iter().map(|(name, _)| name.clone()).collect()
     }
 
-    fn settled(&self, username: &str) {
-        self.forget(username);
-    }
-
-    /// Stop waiting on a peer whose request never reached the wire.
+    /// Stop waiting on a peer — because it answered, or because its request
+    /// never reached the wire.
     pub fn forget(&self, username: &str) {
         if let Ok(mut pending) = self.0.lock() {
             pending.retain(|(name, _)| name != username);
@@ -272,7 +292,11 @@ fn tick(
 /// Both sources matter: the drained events carry states that came and went
 /// between two ticks (a small file served straight out of the queue), and the
 /// live table carries progress.
-fn publish_uploads(session: &dyn SessionApi, hub: &Hub, state: &mut DrainState) {
+fn publish_uploads(
+    session: &dyn SessionApi,
+    hub: &Hub,
+    state: &mut DrainState,
+) {
     let sampled = session
         .take_upload_events()
         .iter()
@@ -285,11 +309,24 @@ fn publish_uploads(session: &dyn SessionApi, hub: &Hub, state: &mut DrainState)
         if state.uploads.get(&key) == Some(&upload) {
             continue;
         }
+        let settled = matches!(
+            upload.status,
+            UploadStatusDto::Completed
+                | UploadStatusDto::Cancelled
+                | UploadStatusDto::Failed { .. }
+        );
         hub.publish(
             Event::Upload,
             serde_json::to_value(&upload).unwrap_or(serde_json::Value::Null),
         );
-        state.uploads.insert(key, upload);
+        // An upload that has finished cannot change again, so remembering it
+        // would grow this table by one entry per file for the life of the
+        // daemon.
+        if settled {
+            state.uploads.remove(&key);
+        } else {
+            state.uploads.insert(key, upload);
+        }
     }
 }
 
@@ -302,7 +339,7 @@ fn publish_browses(
         let Some(directories) = session.take_browse_result(&username) else {
             continue;
         };
-        browses.settled(&username);
+        browses.forget(&username);
         hub.publish(
             Event::Browse,
             serde_json::to_value(BrowseEvent {
@@ -358,8 +395,8 @@ mod tests {
         // The whole reason the hub exists: two clients must both see an event
         // that only exists once in the library's buffer.
         let hub = Hub::new();
-        let (_, first) = hub.subscribe();
-        let (_, second) = hub.subscribe();
+        let (_, first) = hub.subscribe(|| {});
+        let (_, second) = hub.subscribe(|| {});
 
         hub.publish(Event::Room, json!({ "event": "left", "room": "lobby" }));
 
@@ -370,7 +407,7 @@ mod tests {
     #[test]
     fn unsubscribing_stops_delivery() {
         let hub = Hub::new();
-        let (id, receiver) = hub.subscribe();
+        let (id, receiver) = hub.subscribe(|| {});
         hub.unsubscribe(id);
         hub.publish(Event::Upload, json!({}));
         assert!(drain(&receiver).is_empty());
@@ -380,8 +417,8 @@ mod tests {
     #[test]
     fn a_client_that_stops_reading_is_dropped_and_the_others_keep_up() {
         let hub = Hub::new();
-        let (_, slow) = hub.subscribe();
-        let (_, healthy) = hub.subscribe();
+        let (_, slow) = hub.subscribe(|| {});
+        let (_, healthy) = hub.subscribe(|| {});
 
         // Overrun the slow client's queue while the healthy one keeps reading,
         // which is exactly the asymmetry the bound exists to survive.
@@ -408,7 +445,7 @@ mod tests {
     #[test]
     fn a_dropped_receiver_removes_its_subscriber() {
         let hub = Hub::new();
-        let (_, receiver) = hub.subscribe();
+        let (_, receiver) = hub.subscribe(|| {});
         drop(receiver);
         hub.publish(Event::Message, json!({}));
         assert_eq!(hub.subscribers(), 0);
@@ -427,7 +464,10 @@ mod tests {
         }
         let history = hub.history();
         assert_eq!(history.len(), HISTORY_LIMIT);
-        assert_eq!(history[0].at, 5, "the oldest messages are the ones dropped");
+        assert_eq!(
+            history[0].at, 5,
+            "the oldest messages are the ones dropped"
+        );
         assert_eq!(history[HISTORY_LIMIT - 1].at, HISTORY_LIMIT as i64 + 4);
     }
 
@@ -460,7 +500,7 @@ mod tests {
         pending.expect("bob");
         pending.expect("bob");
         assert_eq!(pending.snapshot(), ["bob"]);
-        pending.settled("bob");
+        pending.forget("bob");
         assert!(pending.snapshot().is_empty());
     }
 

soulseek-rs/src/daemon/mod.rs

@@ -190,7 +190,7 @@ pub fn run(
     let downloads = Arc::new(Mutex::new(Vec::new()));
     let stop = Arc::new(AtomicBool::new(false));
 
-    restore(ctx, &store, session.client.as_ref(), &hub, &downloads);
+    let rooms = restore(ctx, &store, session.client.as_ref(), &hub, &downloads);
 
     let daemon = Arc::new(Daemon {
         session: Arc::clone(&session.client),
@@ -202,7 +202,8 @@ pub fn run(
         token,
         started: Instant::now(),
         stop: Arc::clone(&stop),
-        rooms: Mutex::new(store.load_rooms()),
+        open: Arc::new(std::sync::atomic::AtomicUsize::new(0)),
+        rooms: Mutex::new(rooms),
     });
 
     let drainer = {
@@ -263,7 +264,7 @@ fn restore(
     session: &dyn SessionApi,
     hub: &Hub,
     downloads: &Mutex<Vec<PendingDownload>>,
-) {
+) -> Vec<String> {
     hub.restore(
         store
             .load_messages()
@@ -277,8 +278,9 @@ fn restore(
             .collect(),
     );
 
-    for room in store.load_rooms() {
-        if let Err(e) = session.join_room(&room) {
+    let rooms = store.load_rooms();
+    for room in &rooms {
+        if let Err(e) = session.join_room(room) {
             ctx.out.warn(&format!("cannot rejoin {room}: {e}"));
         }
     }
@@ -289,7 +291,7 @@ fn restore(
         .filter(|download| !download.completed)
         .collect();
     if unfinished.is_empty() {
-        return;
+        return rooms;
     }
     ctx.out
         .status(&format!("resuming {} transfers", unfinished.len()));
@@ -314,6 +316,7 @@ fn restore(
                 .warn(&format!("cannot resume {}: {e}", download.filename)),
         }
     }
+    rooms
 }
 
 /// Write daemon-owned state back. Best-effort: a state file that cannot be

soulseek-rs/src/daemon/openrpc.rs

@@ -9,12 +9,12 @@
 //! Regenerate with `UPDATE_OPENRPC=1 cargo test -p soulseek-rs openrpc`.
 
 use super::proto::{
-    Ack, AuthParams, AuthResult, BrowseEvent, DaemonStatus, DownloadStartParams,
-    DownloadStatusEvent, Downloads, DownloadStarted, Event, IntervalSeconds,
-    MessageParams, Members, Messages, Method, QueryParams, RoomEventDto,
-    RoomRef, SayParams, SearchResults, Seconds, SessionLossEvent, SharesStatus,
-    SlotsParams, TransferRef, UploadInfoDto, Uploads, UserMessageDto, UserRef,
-    UserResult, DirectoriesParams,
+    Ack, AuthParams, AuthResult, BrowseEvent, DaemonStatus, DirectoriesParams,
+    DownloadStartParams, DownloadStarted, DownloadStatusEvent, Downloads,
+    Event, IntervalSeconds, Members, MessageParams, Messages, Method,
+    QueryParams, RoomEventDto, RoomRef, SayParams, SearchResults, Seconds,
+    SessionLossEvent, SharesStatus, SlotsParams, TransferRef, UploadInfoDto,
+    Uploads, UserMessageDto, UserRef, UserResult,
 };
 use schemars::{JsonSchema, SchemaGenerator, generate::SchemaSettings};
 use serde_json::{Value, json};
@@ -117,15 +117,29 @@ fn result_schema(method: Method, generator: &mut SchemaGenerator) -> Value {
 /// What a method does, for the generated documentation.
 fn summary(method: Method) -> &'static str {
     match method {
-        Method::Auth => "Authenticate. Must be the first request on a connection.",
-        Method::DaemonStatus => "Who the daemon is logged in as and what its session is doing.",
+        Method::Auth => {
+            "Authenticate. Must be the first request on a connection."
+        }
+        Method::DaemonStatus => {
+            "Who the daemon is logged in as and what its session is doing."
+        }
         Method::DaemonStop => "Ask the daemon to shut down.",
         Method::RpcDiscover => "This document.",
-        Method::SearchStart => "Put a search on the wire and return at once; results accumulate.",
-        Method::SearchResults => "Everything that has answered a search so far.",
-        Method::SearchWishlist => "Send a query as a wishlist search (server code 103).",
-        Method::SearchWishlistInterval => "How long the server wants between wishlist searches.",
-        Method::DownloadStart => "Queue a transfer. Progress arrives as event.download_status.",
+        Method::SearchStart => {
+            "Put a search on the wire and return at once; results accumulate."
+        }
+        Method::SearchResults => {
+            "Everything that has answered a search so far."
+        }
+        Method::SearchWishlist => {
+            "Send a query as a wishlist search (server code 103)."
+        }
+        Method::SearchWishlistInterval => {
+            "How long the server wants between wishlist searches."
+        }
+        Method::DownloadStart => {
+            "Queue a transfer. Progress arrives as event.download_status."
+        }
         Method::DownloadList => "Every transfer the daemon knows about.",
         Method::DownloadPause => "Pause a transfer in progress.",
         Method::DownloadResume => "Resume a paused transfer.",
@@ -134,17 +148,29 @@ fn summary(method: Method) -> &'static str {
         Method::UploadList => "Uploads being served, active first.",
         Method::UploadCancel => "Stop serving an upload in progress.",
         Method::UploadSlots => "How many uploads may run at once.",
-        Method::PrivilegesCheck => "Ask the server for this account's privilege time.",
-        Method::PrivilegesOwn => "Privilege seconds left, or null if the server has not answered.",
-        Method::RoomListRequest => "Ask the server for the public room list; it arrives as event.room.",
+        Method::PrivilegesCheck => {
+            "Ask the server for this account's privilege time."
+        }
+        Method::PrivilegesOwn => {
+            "Privilege seconds left, or null if the server has not answered."
+        }
+        Method::RoomListRequest => {
+            "Ask the server for the public room list; it arrives as event.room."
+        }
         Method::RoomJoin => "Join a chat room.",
         Method::RoomLeave => "Leave a chat room.",
         Method::RoomSay => "Post a message to a room.",
         Method::RoomMembers => "Who is currently in a room.",
         Method::MessageSend => "Send a private message.",
-        Method::MessageHistory => "Private messages the daemon collected, including while nobody was attached.",
-        Method::BrowseUser => "Ask a peer for its share listing; it arrives as event.browse.",
-        Method::UserRequest => "Ask the server about a user; poll user.info for the answer.",
+        Method::MessageHistory => {
+            "Private messages the daemon collected, including while nobody was attached."
+        }
+        Method::BrowseUser => {
+            "Ask a peer for its share listing; it arrives as event.browse."
+        }
+        Method::UserRequest => {
+            "Ask the server about a user; poll user.info for the answer."
+        }
         Method::UserInfoOf => "What the server has said about a user so far.",
         Method::SharesStatusOf => "What the share index currently holds.",
         Method::SharesSet => "Replace the shared folders and re-index.",
@@ -171,10 +197,61 @@ fn event_summary(event: Event) -> &'static str {
         Event::Upload => "An upload changed state.",
         Event::DownloadStatus => "A transfer moved.",
         Event::Browse => "A peer answered a browse request.",
-        Event::SessionLoss => "The server session ended; nothing seen after this means anything.",
+        Event::SessionLoss => {
+            "The server session ended; nothing seen after this means anything."
+        }
     }
 }
 
+/// Turn a params object schema into OpenRPC content descriptors — one per
+/// field, which is what `by-name` means.
+///
+/// A single descriptor holding the whole struct would tell a generator to send
+/// `{"params": {"params": {…}}}`, and every generated call would come back
+/// `-32602`. The daemon deserializes the params object directly into the
+/// struct, so each of its fields is a parameter in its own right.
+fn descriptors(
+    params: &Value,
+    definitions: &serde_json::Map<String, Value>,
+) -> Vec<Value> {
+    let Some(schema) = resolve(params, definitions) else {
+        return Vec::new();
+    };
+    let required: Vec<&str> = schema
+        .get("required")
+        .and_then(Value::as_array)
+        .map(|names| names.iter().filter_map(Value::as_str).collect())
+        .unwrap_or_default();
+
+    schema
+        .get("properties")
+        .and_then(Value::as_object)
+        .map(|properties| {
+            properties
+                .iter()
+                .map(|(name, property)| {
+                    json!({
+                        "name": name,
+                        "required": required.contains(&name.as_str()),
+                        "schema": property,
+                    })
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+/// Follow a `$ref` into the generated definitions.
+fn resolve<'a>(
+    schema: &'a Value,
+    definitions: &'a serde_json::Map<String, Value>,
+) -> Option<&'a Value> {
+    let Some(reference) = schema.get("$ref").and_then(Value::as_str) else {
+        return schema.get("properties").map(|_| schema);
+    };
+    definitions.get(reference.strip_prefix(DEFINITIONS_PATH)?)
+}
+
 /// Build the whole document.
 fn document() -> Value {
     let settings = SchemaSettings::draft2020_12().with(|settings| {
@@ -182,56 +259,62 @@ fn document() -> Value {
     });
     let mut generator = SchemaGenerator::new(settings);
 
-    let methods: Vec<Value> = Method::ALL
+    // Schemas first, definitions second: a params schema is a `$ref` until the
+    // generator has been asked for everything, and expanding it into
+    // descriptors needs the definition it points at.
+    let shapes: Vec<(Method, Value, Value)> = Method::ALL
         .iter()
         .map(|&method| {
-            let params = params_schema(method, &mut generator);
-            let result = result_schema(method, &mut generator);
-            json!({
-                "name": method.wire_name(),
-                "summary": summary(method),
-                "paramStructure": "by-name",
-                "params": if params == json!({ "type": "null" }) {
-                    json!([])
-                } else {
-                    json!([{
-                        "name": "params",
-                        "required": true,
-                        "schema": params,
-                    }])
-                },
-                "result": {
-                    "name": "result",
-                    "schema": result,
-                },
-            })
+            (
+                method,
+                params_schema(method, &mut generator),
+                result_schema(method, &mut generator),
+            )
         })
         .collect();
+    let event_shapes: Vec<(Event, Value)> = Event::ALL
+        .iter()
+        .map(|&event| (event, event_schema(event, &mut generator)))
+        .collect();
+
+    let definitions: serde_json::Map<String, Value> =
+        generator.take_definitions(true).into_iter().collect();
+
+    let methods = shapes.into_iter().map(|(method, params, result)| {
+        json!({
+            "name": method.wire_name(),
+            "summary": summary(method),
+            "paramStructure": "by-name",
+            "params": descriptors(&params, &definitions),
+            "result": {
+                "name": "result",
+                "schema": result,
+            },
+        })
+    });
 
     // OpenRPC has no first-class notion of a server-pushed notification, so
     // the events are published as methods flagged with an extension field.
     // A generator still emits their payload types; the delivery semantics are
     // prose in docs/daemon-protocol.md.
-    let events: Vec<Value> = Event::ALL
-        .iter()
-        .map(|&event| {
-            json!({
-                "name": event.wire_name(),
-                "summary": event_summary(event),
-                "x-notification": true,
-                "paramStructure": "by-name",
-                "params": [{
-                    "name": "params",
-                    "required": true,
-                    "schema": event_schema(event, &mut generator),
-                }],
-                "result": { "name": "result", "schema": { "type": "null" } },
-            })
+    let events = event_shapes.into_iter().map(|(event, payload)| {
+        json!({
+            "name": event.wire_name(),
+            "summary": event_summary(event),
+            "x-notification": true,
+            "paramStructure": "by-name",
+            // Unlike a method, an event's `params` object *is* the payload,
+            // and several payloads are tagged enums with no single property
+            // map to split. One descriptor carrying the whole schema is
+            // what a generator needs to emit the type.
+            "params": [{
+                "name": "payload",
+                "required": true,
+                "schema": payload,
+            }],
+            "result": { "name": "result", "schema": { "type": "null" } },
         })
-        .collect();
-
-    let definitions: serde_json::Map<String, Value> =
-        generator.take_definitions(true).into_iter().collect();
+    });
 
     json!({
         "openrpc": "1.3.2",
@@ -239,11 +322,11 @@ fn document() -> Value {
             "title": "soulseek-rs daemon",
             "version": env!("CARGO_PKG_VERSION"),
             "description": "Control a running soulseek-rs daemon. Newline-delimited \
-JSON-RPC 2.0 over a Unix socket (local, authenticated by socket permissions) or \
-TCP (remote, authenticated by the token in <state-dir>/daemon.token). `auth` must \
-be the first request on a connection. Errors carry the CLI exit status in \
-`error.data.exit`. Entries marked `x-notification` are pushed by the daemon and \
-are never requested.",
+    JSON-RPC 2.0 over a Unix socket (local, authenticated by socket permissions) or \
+    TCP (remote, authenticated by the token in <state-dir>/daemon.token). `auth` must \
+    be the first request on a connection. Errors carry the CLI exit status in \
+    `error.data.exit`. Entries marked `x-notification` are pushed by the daemon and \
+    are never requested.",
             "license": { "name": "MIT" },
         },
         "methods": methods.into_iter().chain(events).collect::<Vec<_>>(),
@@ -306,6 +389,68 @@ fn every_method_and_event_is_published() {
     assert_eq!(published.len(), Method::ALL.len() + Event::ALL.len());
 }
 
+/// The published parameters must be the keys the daemon actually reads.
+///
+/// This is the shape a generated client sends. Publishing the params struct as
+/// one descriptor named `params` type-checks and generates cleanly, and every
+/// call it produces fails `-32602`, because the client then sends
+/// `{"params": {"params": {…}}}` where the daemon expects the inner object.
+#[test]
+fn published_parameters_are_the_keys_the_daemon_reads() {
+    use super::proto::{QueryParams, RoomRef, TransferRef};
+
+    let document = document();
+    let published = |name: &str| -> Vec<String> {
+        document["methods"]
+            .as_array()
+            .expect("methods is an array")
+            .iter()
+            .find(|method| method["name"] == name)
+            .unwrap_or_else(|| panic!("{name} is published"))["params"]
+            .as_array()
+            .expect("params is an array")
+            .iter()
+            .map(|p| p["name"].as_str().expect("a name").to_string())
+            .collect()
+    };
+    let keys = |value: &Value| -> Vec<String> {
+        value
+            .as_object()
+            .expect("params serialize as an object")
+            .keys()
+            .cloned()
+            .collect()
+    };
+
+    assert_eq!(
+        published("room.join"),
+        keys(
+            &serde_json::to_value(RoomRef {
+                room: "lobby".into()
+            })
+            .unwrap()
+        )
+    );
+    assert_eq!(
+        published("search.results"),
+        keys(&serde_json::to_value(QueryParams { query: "x".into() }).unwrap())
+    );
+    assert_eq!(
+        published("download.pause"),
+        keys(
+            &serde_json::to_value(TransferRef {
+                username: "bob".into(),
+                filename: "a.mp3".into()
+            })
+            .unwrap()
+        )
+    );
+    assert!(
+        published("daemon.status").is_empty(),
+        "a method that takes nothing publishes no parameters"
+    );
+}
+
 #[test]
 fn a_wire_name_round_trips_through_its_enum() {
     for method in Method::ALL {

soulseek-rs/src/daemon/proto/dto.rs

@@ -0,0 +1,612 @@
+//! The data types that cross the wire.
+//!
+//! Library types never travel as themselves. Each has an explicit DTO and a
+//! mechanical conversion, so the published shape is versioned independently of
+//! `soulseek-rs-lib` — a refactor there cannot silently change what a
+//! third-party script receives, and the compiler points here when one would.
+
+use serde::{Deserialize, Serialize};
+use soulseek_rs::types::{
+    Download, DownloadMetadata, UserPresence, UserStats, UserStatus,
+};
+use soulseek_rs::{
+    DownloadStatus, File, RoomEvent, RoomInfo, SearchResult, SessionLoss,
+    SharedDirectory, UploadInfo, UploadStatus, UserInfo, UserMessage,
+};
+use std::collections::HashMap;
+
+#[derive(Debug, Clone, Default, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct AuthParams {
+    /// Required on TCP. Omitted on a Unix socket, where the socket's own
+    /// permissions already prove the caller is this user.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub token: Option<String>,
+    #[serde(default)]
+    pub protocol: u32,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct AuthResult {
+    pub protocol: u32,
+    pub daemon_version: String,
+    /// The Soulseek account the daemon is logged in as.
+    pub username: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct FileDto {
+    pub name: String,
+    pub size: u64,
+    /// Soulseek attribute codes (0 = bitrate, 1 = duration in seconds).
+    pub attribs: HashMap<u32, u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SearchResultDto {
+    pub token: u32,
+    pub username: String,
+    pub slots: u8,
+    pub speed: u32,
+    pub files: Vec<FileDto>,
+}
+
+impl From<&SearchResult> for SearchResultDto {
+    fn from(result: &SearchResult) -> Self {
+        Self {
+            token: result.token,
+            username: result.username.clone(),
+            slots: result.slots,
+            speed: result.speed,
+            files: result
+                .files
+                .iter()
+                .map(|file| FileDto {
+                    name: file.name.clone(),
+                    size: file.size,
+                    attribs: file.attribs.clone(),
+                })
+                .collect(),
+        }
+    }
+}
+
+impl From<SearchResultDto> for SearchResult {
+    fn from(dto: SearchResultDto) -> Self {
+        Self {
+            token: dto.token,
+            slots: dto.slots,
+            speed: dto.speed,
+            files: dto
+                .files
+                .into_iter()
+                .map(|file| File {
+                    username: dto.username.clone(),
+                    name: file.name,
+                    size: file.size,
+                    attribs: file.attribs,
+                })
+                .collect(),
+            username: dto.username,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+#[serde(tag = "state", rename_all = "snake_case")]
+pub enum DownloadStatusDto {
+    Queued,
+    InProgress {
+        bytes_downloaded: u64,
+        total_bytes: u64,
+        speed_bytes_per_sec: f64,
+    },
+    Paused {
+        bytes_downloaded: u64,
+        total_bytes: u64,
+    },
+    Completed,
+    Failed {
+        reason: Option<String>,
+    },
+    TimedOut,
+}
+
+impl From<&DownloadStatus> for DownloadStatusDto {
+    fn from(status: &DownloadStatus) -> Self {
+        match status {
+            DownloadStatus::Queued => Self::Queued,
+            DownloadStatus::InProgress {
+                bytes_downloaded,
+                total_bytes,
+                speed_bytes_per_sec,
+            } => Self::InProgress {
+                bytes_downloaded: *bytes_downloaded,
+                total_bytes: *total_bytes,
+                speed_bytes_per_sec: *speed_bytes_per_sec,
+            },
+            DownloadStatus::Paused {
+                bytes_downloaded,
+                total_bytes,
+            } => Self::Paused {
+                bytes_downloaded: *bytes_downloaded,
+                total_bytes: *total_bytes,
+            },
+            DownloadStatus::Completed => Self::Completed,
+            DownloadStatus::Failed(reason) => Self::Failed {
+                reason: reason.clone(),
+            },
+            DownloadStatus::TimedOut => Self::TimedOut,
+        }
+    }
+}
+
+impl From<DownloadStatusDto> for DownloadStatus {
+    fn from(dto: DownloadStatusDto) -> Self {
+        match dto {
+            DownloadStatusDto::Queued => Self::Queued,
+            DownloadStatusDto::InProgress {
+                bytes_downloaded,
+                total_bytes,
+                speed_bytes_per_sec,
+            } => Self::InProgress {
+                bytes_downloaded,
+                total_bytes,
+                speed_bytes_per_sec,
+            },
+            DownloadStatusDto::Paused {
+                bytes_downloaded,
+                total_bytes,
+            } => Self::Paused {
+                bytes_downloaded,
+                total_bytes,
+            },
+            DownloadStatusDto::Completed => Self::Completed,
+            DownloadStatusDto::Failed { reason } => Self::Failed(reason),
+            DownloadStatusDto::TimedOut => Self::TimedOut,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DownloadMetadataDto {
+    #[serde(default)]
+    pub bitrate: Option<u32>,
+    #[serde(default)]
+    pub length_seconds: Option<u32>,
+    #[serde(default)]
+    pub peer_upload_speed: Option<u32>,
+    #[serde(default)]
+    pub peer_free_slots: Option<u8>,
+}
+
+impl From<&DownloadMetadata> for DownloadMetadataDto {
+    fn from(metadata: &DownloadMetadata) -> Self {
+        Self {
+            bitrate: metadata.bitrate,
+            length_seconds: metadata.length_seconds,
+            peer_upload_speed: metadata.peer_upload_speed,
+            peer_free_slots: metadata.peer_free_slots,
+        }
+    }
+}
+
+impl From<DownloadMetadataDto> for DownloadMetadata {
+    fn from(dto: DownloadMetadataDto) -> Self {
+        Self {
+            bitrate: dto.bitrate,
+            length_seconds: dto.length_seconds,
+            peer_upload_speed: dto.peer_upload_speed,
+            peer_free_slots: dto.peer_free_slots,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DownloadDto {
+    pub username: String,
+    pub filename: String,
+    pub token: u32,
+    pub size: u64,
+    pub download_directory: String,
+    pub status: DownloadStatusDto,
+    #[serde(default)]
+    pub queue_position: Option<u32>,
+    #[serde(default)]
+    pub metadata: DownloadMetadataDto,
+}
+
+impl From<&Download> for DownloadDto {
+    fn from(download: &Download) -> Self {
+        Self {
+            username: download.username.clone(),
+            filename: download.filename.clone(),
+            token: download.token,
+            size: download.size,
+            download_directory: download.download_directory.clone(),
+            status: DownloadStatusDto::from(&download.status),
+            queue_position: download.queue_position,
+            metadata: DownloadMetadataDto::from(&download.metadata),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+#[serde(tag = "state", rename_all = "snake_case")]
+pub enum UploadStatusDto {
+    /// Waiting for a slot, at this 1-based place in the queue.
+    Queued {
+        place: u32,
+    },
+    InProgress,
+    Completed,
+    Cancelled,
+    Failed {
+        reason: String,
+    },
+}
+
+impl From<&UploadStatus> for UploadStatusDto {
+    fn from(status: &UploadStatus) -> Self {
+        match status {
+            UploadStatus::Queued(place) => Self::Queued { place: *place },
+            UploadStatus::InProgress => Self::InProgress,
+            UploadStatus::Completed => Self::Completed,
+            UploadStatus::Cancelled => Self::Cancelled,
+            UploadStatus::Failed(reason) => Self::Failed {
+                reason: reason.clone(),
+            },
+        }
+    }
+}
+
+impl From<UploadStatusDto> for UploadStatus {
+    fn from(dto: UploadStatusDto) -> Self {
+        match dto {
+            UploadStatusDto::Queued { place } => Self::Queued(place),
+            UploadStatusDto::InProgress => Self::InProgress,
+            UploadStatusDto::Completed => Self::Completed,
+            UploadStatusDto::Cancelled => Self::Cancelled,
+            UploadStatusDto::Failed { reason } => Self::Failed(reason),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UploadInfoDto {
+    pub username: String,
+    pub filename: String,
+    pub size: u64,
+    pub bytes_sent: u64,
+    pub status: UploadStatusDto,
+    pub speed_bytes_per_sec: f64,
+}
+
+impl From<&UploadInfo> for UploadInfoDto {
+    fn from(upload: &UploadInfo) -> Self {
+        Self {
+            username: upload.username.clone(),
+            filename: upload.filename.clone(),
+            size: upload.size,
+            bytes_sent: upload.bytes_sent,
+            status: UploadStatusDto::from(&upload.status),
+            speed_bytes_per_sec: upload.speed_bytes_per_sec,
+        }
+    }
+}
+
+impl From<UploadInfoDto> for UploadInfo {
+    fn from(dto: UploadInfoDto) -> Self {
+        Self {
+            username: dto.username,
+            filename: dto.filename,
+            size: dto.size,
+            bytes_sent: dto.bytes_sent,
+            status: dto.status.into(),
+            speed_bytes_per_sec: dto.speed_bytes_per_sec,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct RoomInfoDto {
+    pub name: String,
+    pub user_count: u32,
+}
+
+impl From<&RoomInfo> for RoomInfoDto {
+    fn from(room: &RoomInfo) -> Self {
+        Self {
+            name: room.name.clone(),
+            user_count: room.user_count,
+        }
+    }
+}
+
+impl From<RoomInfoDto> for RoomInfo {
+    fn from(dto: RoomInfoDto) -> Self {
+        Self {
+            name: dto.name,
+            user_count: dto.user_count,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+#[serde(tag = "event", rename_all = "snake_case")]
+pub enum RoomEventDto {
+    List {
+        rooms: Vec<RoomInfoDto>,
+    },
+    Joined {
+        room: String,
+        users: Vec<String>,
+    },
+    Left {
+        room: String,
+    },
+    Message {
+        room: String,
+        username: String,
+        message: String,
+    },
+    UserJoined {
+        room: String,
+        username: String,
+    },
+    UserLeft {
+        room: String,
+        username: String,
+    },
+}
+
+impl From<&RoomEvent> for RoomEventDto {
+    fn from(event: &RoomEvent) -> Self {
+        match event {
+            RoomEvent::List(rooms) => Self::List {
+                rooms: rooms.iter().map(RoomInfoDto::from).collect(),
+            },
+            RoomEvent::Joined { room, users } => Self::Joined {
+                room: room.clone(),
+                users: users.clone(),
+            },
+            RoomEvent::Left { room } => Self::Left { room: room.clone() },
+            RoomEvent::Message {
+                room,
+                username,
+                message,
+            } => Self::Message {
+                room: room.clone(),
+                username: username.clone(),
+                message: message.clone(),
+            },
+            RoomEvent::UserJoined { room, username } => Self::UserJoined {
+                room: room.clone(),
+                username: username.clone(),
+            },
+            RoomEvent::UserLeft { room, username } => Self::UserLeft {
+                room: room.clone(),
+                username: username.clone(),
+            },
+        }
+    }
+}
+
+impl From<RoomEventDto> for RoomEvent {
+    fn from(dto: RoomEventDto) -> Self {
+        match dto {
+            RoomEventDto::List { rooms } => {
+                Self::List(rooms.into_iter().map(RoomInfo::from).collect())
+            }
+            RoomEventDto::Joined { room, users } => {
+                Self::Joined { room, users }
+            }
+            RoomEventDto::Left { room } => Self::Left { room },
+            RoomEventDto::Message {
+                room,
+                username,
+                message,
+            } => Self::Message {
+                room,
+                username,
+                message,
+            },
+            RoomEventDto::UserJoined { room, username } => {
+                Self::UserJoined { room, username }
+            }
+            RoomEventDto::UserLeft { room, username } => {
+                Self::UserLeft { room, username }
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserPresenceDto {
+    /// `online`, `away`, or `offline`.
+    pub status: String,
+    pub privileged: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserStatsDto {
+    pub average_speed: u32,
+    pub shared_files: u32,
+    pub shared_folders: u32,
+}
+
+/// Each half is `None` until its reply lands, so a consumer can tell "the
+/// server said offline" from "the server has not answered yet".
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserInfoDto {
+    pub username: String,
+    #[serde(default)]
+    pub presence: Option<UserPresenceDto>,
+    #[serde(default)]
+    pub stats: Option<UserStatsDto>,
+}
+
+impl From<&UserInfo> for UserInfoDto {
+    fn from(info: &UserInfo) -> Self {
+        Self {
+            username: info.username.clone(),
+            presence: info.presence.map(|presence| UserPresenceDto {
+                status: presence.status.to_string(),
+                privileged: presence.privileged,
+            }),
+            stats: info.stats.map(|stats| UserStatsDto {
+                average_speed: stats.average_speed,
+                shared_files: stats.shared_files,
+                shared_folders: stats.shared_folders,
+            }),
+        }
+    }
+}
+
+impl From<UserInfoDto> for UserInfo {
+    fn from(dto: UserInfoDto) -> Self {
+        let mut info = Self::pending(dto.username);
+        info.presence = dto.presence.map(|presence| UserPresence {
+            status: match presence.status.as_str() {
+                "online" => UserStatus::Online,
+                "away" => UserStatus::Away,
+                _ => UserStatus::Offline,
+            },
+            privileged: presence.privileged,
+        });
+        info.stats = dto.stats.map(|stats| UserStats {
+            average_speed: stats.average_speed,
+            shared_files: stats.shared_files,
+            shared_folders: stats.shared_folders,
+        });
+        info
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SharedDirectoryDto {
+    pub name: String,
+    /// Basename and size; join with the directory to get a downloadable path.
+    pub files: Vec<(String, u64)>,
+}
+
+impl From<&SharedDirectory> for SharedDirectoryDto {
+    fn from(directory: &SharedDirectory) -> Self {
+        Self {
+            name: directory.name.clone(),
+            files: directory.files.clone(),
+        }
+    }
+}
+
+impl From<SharedDirectoryDto> for SharedDirectory {
+    fn from(dto: SharedDirectoryDto) -> Self {
+        Self {
+            name: dto.name,
+            files: dto.files,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserMessageDto {
+    pub id: u32,
+    pub timestamp: u32,
+    pub username: String,
+    pub message: String,
+    pub new_message: bool,
+}
+
+impl From<&UserMessage> for UserMessageDto {
+    fn from(message: &UserMessage) -> Self {
+        Self {
+            id: message.id(),
+            timestamp: message.timestamp(),
+            username: message.username().to_string(),
+            message: message.message().to_string(),
+            new_message: message.is_new(),
+        }
+    }
+}
+
+impl From<UserMessageDto> for UserMessage {
+    fn from(dto: UserMessageDto) -> Self {
+        Self::new(
+            dto.id,
+            dto.timestamp,
+            dto.username,
+            dto.message,
+            dto.new_message,
+        )
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum SessionLossDto {
+    Displaced,
+    Disconnected,
+}
+
+impl From<SessionLoss> for SessionLossDto {
+    fn from(loss: SessionLoss) -> Self {
+        match loss {
+            SessionLoss::Displaced => Self::Displaced,
+            SessionLoss::Disconnected => Self::Disconnected,
+        }
+    }
+}
+
+impl From<SessionLossDto> for SessionLoss {
+    fn from(dto: SessionLossDto) -> Self {
+        match dto {
+            SessionLossDto::Displaced => Self::Displaced,
+            SessionLossDto::Disconnected => Self::Disconnected,
+        }
+    }
+}
+
+/// What the daemon is and what its session is doing, from `daemon.status`.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DaemonStatus {
+    pub username: String,
+    pub server: String,
+    pub daemon_version: String,
+    pub protocol: u32,
+    #[serde(default)]
+    pub listen_port: Option<u16>,
+    pub shared_folders: u32,
+    pub shared_files: u32,
+    pub download_dir: String,
+    #[serde(default)]
+    pub session_loss: Option<SessionLossDto>,
+    /// Control connections currently attached.
+    pub clients: usize,
+    pub uptime_secs: u64,
+}
+
+/// What the share index holds, from `shares.status` / `shares.reindex`.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SharesStatus {
+    pub folders: u32,
+    pub files: u32,
+    pub directories: Vec<String>,
+}

soulseek-rs/src/daemon/proto/envelope.rs

@@ -0,0 +1,150 @@
+//! JSON-RPC 2.0 framing: what a request, a reply, and an error look like on
+//! the wire, independent of the methods they carry.
+
+use crate::output::Exit;
+use serde::{Deserialize, Serialize};
+
+/// A request from a client. `id` is absent for a notification, which by
+/// JSON-RPC rule gets no reply.
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct Request {
+    #[serde(default = "jsonrpc_version")]
+    pub jsonrpc: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<serde_json::Value>,
+    pub method: String,
+    #[serde(default)]
+    pub params: serde_json::Value,
+}
+
+/// A reply. Exactly one of `result`/`error` is set; `id` echoes the request,
+/// and is absent on a daemon-initiated notification.
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct Response {
+    #[serde(default = "jsonrpc_version")]
+    pub jsonrpc: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub id: Option<serde_json::Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub method: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub params: Option<serde_json::Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub result: Option<serde_json::Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<RpcError>,
+}
+
+fn jsonrpc_version() -> String {
+    "2.0".to_string()
+}
+
+/// A failure, carrying the exit code the same command would have produced
+/// locally so a remote run exits exactly as a local one does.
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct RpcError {
+    pub code: i32,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub data: Option<ErrorData>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ErrorData {
+    /// The `Exit` discriminant this failure maps to.
+    pub exit: u8,
+}
+
+/// Application errors all share one code; the exit status in `data` is what a
+/// caller branches on.
+pub const CODE_APPLICATION: i32 = -32000;
+pub const CODE_PARSE: i32 = -32700;
+pub const CODE_INVALID_REQUEST: i32 = -32600;
+pub const CODE_METHOD_NOT_FOUND: i32 = -32601;
+pub const CODE_INVALID_PARAMS: i32 = -32602;
+
+impl RpcError {
+    #[must_use]
+    pub fn new(code: i32, message: impl Into<String>) -> Self {
+        Self {
+            code,
+            message: message.into(),
+            data: None,
+        }
+    }
+
+    /// An application failure that should reproduce `exit` on the client.
+    #[must_use]
+    pub fn application(exit: Exit, message: impl Into<String>) -> Self {
+        Self {
+            code: CODE_APPLICATION,
+            message: message.into(),
+            data: Some(ErrorData { exit: exit.code() }),
+        }
+    }
+
+    /// The exit status this error asks the client to produce, defaulting to a
+    /// generic failure when the daemon did not say.
+    #[must_use]
+    pub fn exit(&self) -> Exit {
+        match self.data.as_ref().map(|data| data.exit) {
+            Some(0) => Exit::Ok,
+            Some(2) => Exit::Usage,
+            Some(3) => Exit::Connection,
+            Some(4) => Exit::NoResults,
+            Some(5) => Exit::Timeout,
+            Some(6) => Exit::Transfer,
+            Some(7) => Exit::SessionLost,
+            _ => Exit::Failure,
+        }
+    }
+}
+
+impl Response {
+    #[must_use]
+    pub fn result(
+        id: Option<serde_json::Value>,
+        value: serde_json::Value,
+    ) -> Self {
+        Self {
+            jsonrpc: jsonrpc_version(),
+            id,
+            method: None,
+            params: None,
+            result: Some(value),
+            error: None,
+        }
+    }
+
+    /// A failed reply.
+    ///
+    /// An error always carries an `id` member, explicitly `null` when the
+    /// request was too malformed to have one. JSON-RPC requires it, and
+    /// without it a client following the "no id means a notification" rule
+    /// would drop the error and wait out its timeout for a reply that is
+    /// already there.
+    #[must_use]
+    pub fn failure(id: Option<serde_json::Value>, error: RpcError) -> Self {
+        Self {
+            jsonrpc: jsonrpc_version(),
+            id: Some(id.unwrap_or(serde_json::Value::Null)),
+            method: None,
+            params: None,
+            result: None,
+            error: Some(error),
+        }
+    }
+
+    /// A daemon-initiated event: no id, so no reply is expected.
+    #[must_use]
+    pub fn notification(method: &str, params: serde_json::Value) -> Self {
+        Self {
+            jsonrpc: jsonrpc_version(),
+            id: None,
+            method: Some(method.to_string()),
+            params: Some(params),
+            result: None,
+            error: None,
+        }
+    }
+}

soulseek-rs/src/daemon/proto/method.rs

@@ -0,0 +1,176 @@
+//! What each method takes and returns, and what each pushed event carries.
+
+use super::dto::{
+    DownloadDto, DownloadMetadataDto, DownloadStatusDto, SearchResultDto,
+    SessionLossDto, SharedDirectoryDto, UploadInfoDto, UserInfoDto,
+};
+use serde::{Deserialize, Serialize};
+
+/// A void result. JSON-RPC allows a null result, but an object leaves room to
+/// add a field later without changing the shape a client already parses.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Ack {
+    pub ok: bool,
+}
+
+impl Ack {
+    pub const OK: Self = Self { ok: true };
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct QueryParams {
+    pub query: String,
+}
+
+/// Names one transfer, which is how both directions are addressed.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct TransferRef {
+    pub username: String,
+    pub filename: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct RoomRef {
+    pub room: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserRef {
+    pub username: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SayParams {
+    pub room: String,
+    pub message: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct MessageParams {
+    pub username: String,
+    pub message: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DownloadStartParams {
+    pub username: String,
+    pub filename: String,
+    #[serde(default)]
+    pub size: u64,
+    #[serde(default)]
+    pub metadata: DownloadMetadataDto,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SlotsParams {
+    pub slots: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DirectoriesParams {
+    pub directories: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SearchResults {
+    pub results: Vec<SearchResultDto>,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Downloads {
+    pub downloads: Vec<DownloadDto>,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DownloadStarted {
+    pub download: DownloadDto,
+}
+
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Uploads {
+    pub uploads: Vec<UploadInfoDto>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Members {
+    pub users: Vec<String>,
+}
+
+/// One line of chat history. Unlike a live [`UserMessageDto`] this carries a
+/// direction, because a conversation the daemon collected includes what this
+/// account sent as well as what it received.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct ChatMessageDto {
+    /// The other party, whichever way the message went.
+    pub peer: String,
+    pub outgoing: bool,
+    pub text: String,
+    /// Unix seconds.
+    pub at: i64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Messages {
+    pub messages: Vec<ChatMessageDto>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct UserResult {
+    #[serde(default)]
+    pub user: Option<UserInfoDto>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct Seconds {
+    #[serde(default)]
+    pub seconds: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct IntervalSeconds {
+    pub seconds: u64,
+}
+
+/// A peer answered a browse request. Carried whole rather than as a "go ask
+/// for it" nudge, because the daemon's own copy is consumed when it drains.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct BrowseEvent {
+    pub username: String,
+    pub directories: Vec<SharedDirectoryDto>,
+}
+
+/// One step in a transfer this client started.
+#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct DownloadStatusEvent {
+    pub username: String,
+    pub filename: String,
+    pub status: DownloadStatusDto,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
+#[cfg_attr(test, derive(schemars::JsonSchema))]
+pub struct SessionLossEvent {
+    pub loss: SessionLossDto,
+}

soulseek-rs/src/daemon/proto/mod.rs

@@ -0,0 +1,402 @@
+//! The wire contract: JSON-RPC 2.0 framing and the data types that cross it.
+//!
+//! Library types never travel as themselves. Every payload is a DTO defined
+//! here with an explicit conversion, so the wire format is versioned
+//! independently of the library: a refactor inside `soulseek-rs-lib` cannot
+//! silently change what a third-party script receives, and the compiler points
+//! at this file when one would.
+//!
+//! The schemas published in `docs/openrpc.json` are derived from these types
+//! (see the tests at the bottom), which is what keeps the advertised contract
+//! and the running daemon in agreement.
+
+/// Bumped when a change would break a client written against the old shape.
+/// Sent in the `auth` reply so a mismatch is caught at connect time rather
+/// than as a confusing failure three calls later.
+pub const PROTOCOL_VERSION: u32 = 1;
+
+/// The OpenRPC document, served by `rpc.discover` so a generator can point at
+/// a running daemon instead of needing this repository.
+pub const OPENRPC: &str = include_str!("../../../../docs/openrpc.json");
+
+mod dto;
+mod envelope;
+mod method;
+
+pub use dto::*;
+pub use envelope::*;
+pub use method::*;
+
+/// Declare a wire vocabulary once: the enum, the complete list, and the
+/// name mapping in both directions.
+///
+/// Everything that consumes one of these matches on the enum, so the match is
+/// exhaustive and adding a line here is a compile error everywhere the new
+/// member still has to be handled — the dispatcher, the published schema, the
+/// remote client. A `&[&str]` table checked by a test would only fail after
+/// the fact, and only if someone remembered to write the test.
+macro_rules! wire_vocabulary {
+    ($(#[$meta:meta])* $name:ident { $($variant:ident => $wire:literal),* $(,)? }) => {
+        $(#[$meta])*
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+        pub enum $name {
+            $($variant),*
+        }
+
+        impl $name {
+            /// Every member, in published order.
+            pub const ALL: &'static [Self] = &[$(Self::$variant),*];
+
+            #[must_use]
+            pub const fn wire_name(self) -> &'static str {
+                match self {
+                    $(Self::$variant => $wire),*
+                }
+            }
+
+            #[must_use]
+            pub fn from_wire(name: &str) -> Option<Self> {
+                match name {
+                    $($wire => Some(Self::$variant),)*
+                    _ => None,
+                }
+            }
+        }
+
+        impl std::fmt::Display for $name {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str(self.wire_name())
+            }
+        }
+    };
+}
+
+wire_vocabulary! {
+    /// Every method the daemon answers.
+    Method {
+        Auth => "auth",
+        DaemonStatus => "daemon.status",
+        DaemonStop => "daemon.stop",
+        RpcDiscover => "rpc.discover",
+        SearchStart => "search.start",
+        SearchResults => "search.results",
+        SearchWishlist => "search.wishlist",
+        SearchWishlistInterval => "search.wishlist_interval",
+        DownloadStart => "download.start",
+        DownloadList => "download.list",
+        DownloadPause => "download.pause",
+        DownloadResume => "download.resume",
+        DownloadRemove => "download.remove",
+        DownloadRemoveQueued => "download.remove_queued",
+        UploadList => "upload.list",
+        UploadCancel => "upload.cancel",
+        UploadSlots => "upload.slots",
+        PrivilegesCheck => "privileges.check",
+        PrivilegesOwn => "privileges.own",
+        RoomListRequest => "room.list_request",
+        RoomJoin => "room.join",
+        RoomLeave => "room.leave",
+        RoomSay => "room.say",
+        RoomMembers => "room.members",
+        MessageSend => "message.send",
+        MessageHistory => "message.history",
+        BrowseUser => "browse.user",
+        UserRequest => "user.request",
+        UserInfoOf => "user.info",
+        SharesStatusOf => "shares.status",
+        SharesSet => "shares.set",
+        SharesReindex => "shares.reindex",
+    }
+}
+
+wire_vocabulary! {
+    /// Events the daemon pushes without being asked.
+    ///
+    /// These exist because the library's `take_*` accessors are destructive:
+    /// with two clients attached, whichever drained first would steal the
+    /// others' events. The daemon is the single drainer and fans out.
+    Event {
+        Room => "event.room",
+        Message => "event.message",
+        Upload => "event.upload",
+        DownloadStatus => "event.download_status",
+        Browse => "event.browse",
+        SessionLoss => "event.session_loss",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::output::Exit;
+    use soulseek_rs::types::{UserPresence, UserStats, UserStatus};
+    use soulseek_rs::{
+        DownloadStatus, File, RoomEvent, RoomInfo, SearchResult,
+        SharedDirectory, UploadStatus, UserInfo, UserMessage,
+    };
+    use std::collections::HashMap;
+
+    #[test]
+    fn a_search_result_survives_the_round_trip() {
+        let mut attribs = HashMap::new();
+        attribs.insert(0, 320);
+        attribs.insert(1, 210);
+        let original = SearchResult {
+            token: 7,
+            slots: 2,
+            speed: 900,
+            username: "bob".into(),
+            files: vec![File {
+                username: "bob".into(),
+                name: "@@x\\a.mp3".into(),
+                size: 4096,
+                attribs,
+            }],
+        };
+
+        let json = serde_json::to_string(&SearchResultDto::from(&original))
+            .expect("a DTO serializes");
+        let back: SearchResult = serde_json::from_str::<SearchResultDto>(&json)
+            .unwrap()
+            .into();
+
+        assert_eq!(back.token, original.token);
+        assert_eq!(back.username, original.username);
+        assert_eq!(back.slots, original.slots);
+        assert_eq!(back.speed, original.speed);
+        assert_eq!(back.files.len(), 1);
+        assert_eq!(back.files[0].name, "@@x\\a.mp3");
+        assert_eq!(back.files[0].size, 4096);
+        assert_eq!(back.files[0].attribs.get(&0), Some(&320));
+        // The per-file username is carried by the parent result, so it has to
+        // be restored rather than lost.
+        assert_eq!(back.files[0].username, "bob");
+    }
+
+    #[test]
+    fn every_download_status_survives_the_round_trip() {
+        let statuses = [
+            DownloadStatus::Queued,
+            DownloadStatus::InProgress {
+                bytes_downloaded: 10,
+                total_bytes: 100,
+                speed_bytes_per_sec: 1.5,
+            },
+            DownloadStatus::Paused {
+                bytes_downloaded: 10,
+                total_bytes: 100,
+            },
+            DownloadStatus::Completed,
+            DownloadStatus::Failed(Some("gone".into())),
+            DownloadStatus::Failed(None),
+            DownloadStatus::TimedOut,
+        ];
+        for status in &statuses {
+            let dto = DownloadStatusDto::from(status);
+            let json = serde_json::to_string(&dto).unwrap();
+            let back: DownloadStatusDto = serde_json::from_str(&json).unwrap();
+            assert_eq!(dto, back, "{status:?} must survive the wire");
+            assert_eq!(
+                DownloadStatusDto::from(&DownloadStatus::from(back)),
+                dto,
+                "{status:?} must convert back to the same library value"
+            );
+        }
+    }
+
+    #[test]
+    fn every_upload_status_survives_the_round_trip() {
+        let statuses = [
+            UploadStatus::Queued(3),
+            UploadStatus::InProgress,
+            UploadStatus::Completed,
+            UploadStatus::Cancelled,
+            UploadStatus::Failed("nope".into()),
+        ];
+        for status in &statuses {
+            let dto = UploadStatusDto::from(status);
+            let json = serde_json::to_string(&dto).unwrap();
+            let back: UploadStatus =
+                serde_json::from_str::<UploadStatusDto>(&json)
+                    .unwrap()
+                    .into();
+            assert_eq!(&back, status);
+        }
+    }
+
+    #[test]
+    fn every_room_event_survives_the_round_trip() {
+        let events = [
+            RoomEvent::List(vec![RoomInfo {
+                name: "lobby".into(),
+                user_count: 42,
+            }]),
+            RoomEvent::Joined {
+                room: "lobby".into(),
+                users: vec!["bob".into()],
+            },
+            RoomEvent::Left {
+                room: "lobby".into(),
+            },
+            RoomEvent::Message {
+                room: "lobby".into(),
+                username: "bob".into(),
+                message: "hi".into(),
+            },
+            RoomEvent::UserJoined {
+                room: "lobby".into(),
+                username: "sue".into(),
+            },
+            RoomEvent::UserLeft {
+                room: "lobby".into(),
+                username: "sue".into(),
+            },
+        ];
+        for event in &events {
+            let json =
+                serde_json::to_string(&RoomEventDto::from(event)).unwrap();
+            let back: RoomEvent =
+                serde_json::from_str::<RoomEventDto>(&json).unwrap().into();
+            assert_eq!(&back, event);
+        }
+    }
+
+    #[test]
+    fn a_partly_answered_user_stays_partly_answered() {
+        // "the server has not said" must not arrive as "offline, shares
+        // nothing": that is the difference between waiting and giving up.
+        let pending = UserInfo::pending("bob".into());
+        let json = serde_json::to_string(&UserInfoDto::from(&pending)).unwrap();
+        let back: UserInfo =
+            serde_json::from_str::<UserInfoDto>(&json).unwrap().into();
+        assert_eq!(back.username, "bob");
+        assert!(back.presence.is_none());
+        assert!(back.stats.is_none());
+        assert!(!back.is_complete());
+    }
+
+    #[test]
+    fn a_complete_user_survives_the_round_trip() {
+        let mut info = UserInfo::pending("bob".into());
+        info.presence = Some(UserPresence {
+            status: UserStatus::Away,
+            privileged: true,
+        });
+        info.stats = Some(UserStats {
+            average_speed: 500,
+            shared_files: 10,
+            shared_folders: 2,
+        });
+
+        let json = serde_json::to_string(&UserInfoDto::from(&info)).unwrap();
+        let back: UserInfo =
+            serde_json::from_str::<UserInfoDto>(&json).unwrap().into();
+        assert_eq!(back, info);
+    }
+
+    #[test]
+    fn a_private_message_survives_the_round_trip() {
+        let message =
+            UserMessage::new(9, 1234, "bob".into(), "hi".into(), true);
+        let json =
+            serde_json::to_string(&UserMessageDto::from(&message)).unwrap();
+        let back: UserMessage = serde_json::from_str::<UserMessageDto>(&json)
+            .unwrap()
+            .into();
+        assert_eq!(back.id(), 9);
+        assert_eq!(back.timestamp(), 1234);
+        assert_eq!(back.username(), "bob");
+        assert_eq!(back.message(), "hi");
+    }
+
+    #[test]
+    fn a_shared_listing_survives_the_round_trip() {
+        let directory = SharedDirectory {
+            name: "@@x\\Music".into(),
+            files: vec![("a.mp3".into(), 4096)],
+        };
+        let json = serde_json::to_string(&SharedDirectoryDto::from(&directory))
+            .unwrap();
+        let back: SharedDirectory =
+            serde_json::from_str::<SharedDirectoryDto>(&json)
+                .unwrap()
+                .into();
+        assert_eq!(back.name, directory.name);
+        assert_eq!(back.files, directory.files);
+    }
+
+    #[test]
+    fn an_error_carries_the_exit_code_a_local_run_would_have_produced() {
+        for exit in [
+            Exit::Usage,
+            Exit::Connection,
+            Exit::NoResults,
+            Exit::Timeout,
+            Exit::Transfer,
+            Exit::SessionLost,
+        ] {
+            let error = RpcError::application(exit, "nope");
+            let json = serde_json::to_string(&error).unwrap();
+            let back: RpcError = serde_json::from_str(&json).unwrap();
+            assert_eq!(back.exit(), exit);
+        }
+    }
+
+    #[test]
+    fn an_error_without_an_exit_code_is_a_generic_failure() {
+        let error = RpcError::new(CODE_METHOD_NOT_FOUND, "no such method");
+        assert_eq!(error.exit(), Exit::Failure);
+    }
+
+    #[test]
+    fn a_request_parses_without_optional_fields() {
+        let request: Request = serde_json::from_str(
+            r#"{"jsonrpc":"2.0","method":"daemon.status"}"#,
+        )
+        .expect("params and id are optional");
+        assert_eq!(request.method, "daemon.status");
+        assert!(request.id.is_none());
+        assert!(request.params.is_null());
+    }
+
+    #[test]
+    fn an_error_always_carries_an_id_even_when_there_was_none() {
+        // JSON-RPC requires it, and without it a client following the
+        // documented "no id means a notification" rule drops the error and
+        // waits out its timeout for a reply that already arrived.
+        let json = serde_json::to_string(&Response::failure(
+            None,
+            RpcError::new(CODE_PARSE, "unparseable"),
+        ))
+        .expect("a response is plain data");
+        assert!(json.contains("\"id\":null"), "{json}");
+    }
+
+    #[test]
+    fn a_notification_carries_no_id_so_no_reply_is_expected() {
+        let notification =
+            Response::notification("event.room", serde_json::json!({"a": 1}));
+        let json = serde_json::to_string(&notification).unwrap();
+        assert!(!json.contains("\"id\""), "{json}");
+        assert!(json.contains("\"method\":\"event.room\""), "{json}");
+    }
+
+    #[test]
+    fn a_response_serializes_exactly_one_of_result_and_error() {
+        let ok = serde_json::to_string(&Response::result(
+            Some(serde_json::json!(1)),
+            serde_json::json!({}),
+        ))
+        .unwrap();
+        assert!(ok.contains("\"result\""));
+        assert!(!ok.contains("\"error\""));
+
+        let failed = serde_json::to_string(&Response::failure(
+            Some(serde_json::json!(1)),
+            RpcError::application(Exit::NoResults, "nothing"),
+        ))
+        .unwrap();
+        assert!(failed.contains("\"error\""));
+        assert!(!failed.contains("\"result\""));
+    }
+}

soulseek-rs/src/daemon/server/mod.rs

@@ -7,12 +7,10 @@
 
 use super::hub::{Hub, PendingBrowses, PendingDownload};
 use super::proto::{
-    Ack, AuthParams, AuthResult, CODE_APPLICATION, CODE_INVALID_PARAMS,
-    ChatMessageDto,
-    CODE_INVALID_REQUEST, CODE_METHOD_NOT_FOUND, CODE_PARSE, DaemonStatus,
-    DirectoriesParams, DownloadDto, DownloadStartParams, DownloadStarted,
-    Downloads, IntervalSeconds, MessageParams, Members, Messages, Method,
-    OPENRPC, PROTOCOL_VERSION, QueryParams, Request, Response, RoomRef,
+    Ack, AuthResult, CODE_APPLICATION, CODE_INVALID_PARAMS, ChatMessageDto,
+    DaemonStatus, DirectoriesParams, DownloadDto, DownloadStartParams,
+    DownloadStarted, Downloads, IntervalSeconds, Members, MessageParams,
+    Messages, Method, OPENRPC, PROTOCOL_VERSION, QueryParams, RoomRef,
     RpcError, SayParams, SearchResultDto, SearchResults, Seconds, SharesStatus,
     SlotsParams, TransferRef, UploadInfoDto, Uploads, UserInfoDto, UserRef,
     UserResult,
@@ -21,21 +19,10 @@ use crate::api::SessionApi;
 use crate::output::Exit;
 use serde::de::DeserializeOwned;
 use serde_json::Value;
-use std::io::{BufRead, BufReader, Write};
-use std::net::{TcpListener, TcpStream};
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::mpsc::{Receiver, SyncSender, sync_channel};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 
-/// How long a failed authentication costs the caller. Not a serious defence —
-/// the token is 256 bits — but it keeps a wrong-token loop off the CPU.
-const AUTH_FAILURE_DELAY: Duration = Duration::from_secs(1);
-
-/// Replies waiting to go out on one connection. Bounded, so a client that has
-/// stopped reading cannot make the daemon buffer without limit.
-const WRITE_QUEUE_DEPTH: usize = 1024;
-
 /// Everything a connection needs to answer a request.
 pub struct Daemon {
     pub session: Arc<dyn SessionApi>,
@@ -49,6 +36,9 @@ pub struct Daemon {
     pub token: String,
     pub started: Instant,
     pub stop: Arc<AtomicBool>,
+    /// Connections currently being served, capped so an unauthenticated peer
+    /// cannot spawn threads without bound.
+    pub open: Arc<std::sync::atomic::AtomicUsize>,
     /// Rooms this session has joined, so a restart can rejoin them.
     pub rooms: Mutex<Vec<String>>,
 }
@@ -59,17 +49,27 @@ impl Daemon {
     /// The match is exhaustive over [`Method`], so a new method cannot be added
     /// to the protocol without being implemented here.
     #[allow(clippy::too_many_lines)]
-    pub fn call(&self, method: Method, params: Value) -> Result<Value, RpcError> {
+    pub fn call(
+        &self,
+        method: Method,
+        params: Value,
+    ) -> Result<Value, RpcError> {
         match method {
-            // Handled during the handshake; reaching here means a second auth.
-            Method::Auth => ok(Ack::OK),
+            // Handled during the handshake; reaching here means a second
+            // `auth` on an established connection, which is answered with the
+            // shape the contract publishes rather than a bare acknowledgement.
+            Method::Auth => ok(self.identify()),
             Method::DaemonStatus => ok(self.status()),
             Method::DaemonStop => {
                 self.stop.store(true, Ordering::Relaxed);
                 ok(Ack::OK)
             }
-            Method::RpcDiscover => serde_json::from_str(OPENRPC)
-                .map_err(|e| internal(format!("the contract is unreadable: {e}"))),
+            Method::RpcDiscover => serde_json::from_str(OPENRPC).map_err(|e| {
+                RpcError::new(
+                    CODE_APPLICATION,
+                    format!("the contract is unreadable: {e}"),
+                )
+            }),
 
             Method::SearchStart => {
                 let query: QueryParams = parse(params)?;
@@ -78,7 +78,12 @@ impl Daemon {
                 // what keeps one client's search from blocking the daemon.
                 self.session
                     .search_with_cancel(&query.query, Duration::ZERO, None)
-                    .map_err(|e| failed(Exit::Connection, format!("search failed: {e}")))?;
+                    .map_err(|e| {
+                        RpcError::application(
+                            Exit::Connection,
+                            format!("search failed: {e}"),
+                        )
+                    })?;
                 ok(Ack::OK)
             }
             Method::SearchResults => {
@@ -94,9 +99,9 @@ impl Daemon {
             }
             Method::SearchWishlist => {
                 let query: QueryParams = parse(params)?;
-                self.session
-                    .start_wishlist_search(&query.query)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.start_wishlist_search(&query.query).map_err(
+                    |e| RpcError::application(Exit::Connection, e.to_string()),
+                )?;
                 ok(Ack::OK)
             }
             Method::SearchWishlistInterval => ok(IntervalSeconds {
@@ -123,17 +128,19 @@ impl Daemon {
             Method::DownloadResume => {
                 let transfer: TransferRef = parse(params)?;
                 ok(Ack {
-                    ok: self
-                        .session
-                        .resume_download(&transfer.username, &transfer.filename),
+                    ok: self.session.resume_download(
+                        &transfer.username,
+                        &transfer.filename,
+                    ),
                 })
             }
             Method::DownloadRemove => {
                 let transfer: TransferRef = parse(params)?;
                 ok(Ack {
-                    ok: self
-                        .session
-                        .remove_download(&transfer.username, &transfer.filename),
+                    ok: self.session.remove_download(
+                        &transfer.username,
+                        &transfer.filename,
+                    ),
                 })
             }
             Method::DownloadRemoveQueued => {
@@ -169,9 +176,9 @@ impl Daemon {
             }
 
             Method::PrivilegesCheck => {
-                self.session
-                    .check_privileges()
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.check_privileges().map_err(|e| {
+                    RpcError::application(Exit::Connection, e.to_string())
+                })?;
                 ok(Ack::OK)
             }
             Method::PrivilegesOwn => ok(Seconds {
@@ -179,32 +186,32 @@ impl Daemon {
             }),
 
             Method::RoomListRequest => {
-                self.session
-                    .request_room_list()
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.request_room_list().map_err(|e| {
+                    RpcError::application(Exit::Connection, e.to_string())
+                })?;
                 ok(Ack::OK)
             }
             Method::RoomJoin => {
                 let room: RoomRef = parse(params)?;
-                self.session
-                    .join_room(&room.room)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.join_room(&room.room).map_err(|e| {
+                    RpcError::application(Exit::Connection, e.to_string())
+                })?;
                 self.joined(&room.room, true);
                 ok(Ack::OK)
             }
             Method::RoomLeave => {
                 let room: RoomRef = parse(params)?;
-                self.session
-                    .leave_room(&room.room)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.leave_room(&room.room).map_err(|e| {
+                    RpcError::application(Exit::Connection, e.to_string())
+                })?;
                 self.joined(&room.room, false);
                 ok(Ack::OK)
             }
             Method::RoomSay => {
                 let say: SayParams = parse(params)?;
-                self.session
-                    .say_in_room(&say.room, &say.message)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.say_in_room(&say.room, &say.message).map_err(
+                    |e| RpcError::application(Exit::Connection, e.to_string()),
+                )?;
                 ok(Ack::OK)
             }
             Method::RoomMembers => {
@@ -218,7 +225,9 @@ impl Daemon {
                 let message: MessageParams = parse(params)?;
                 self.session
                     .send_private_message(&message.username, &message.message)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                    .map_err(|e| {
+                        RpcError::application(Exit::Connection, e.to_string())
+                    })?;
                 // Record our own half of the conversation: the drainer only
                 // ever sees incoming messages, so without this a client that
                 // attaches later reads a one-sided chat.
@@ -241,15 +250,18 @@ impl Daemon {
                 self.browses.expect(&user.username);
                 if let Err(e) = self.session.browse_user(&user.username) {
                     self.browses.forget(&user.username);
-                    return Err(failed(Exit::Connection, e.to_string()));
+                    return Err(RpcError::application(
+                        Exit::Connection,
+                        e.to_string(),
+                    ));
                 }
                 ok(Ack::OK)
             }
             Method::UserRequest => {
                 let user: UserRef = parse(params)?;
-                self.session
-                    .request_user_info(&user.username)
-                    .map_err(|e| failed(Exit::Connection, e.to_string()))?;
+                self.session.request_user_info(&user.username).map_err(
+                    |e| RpcError::application(Exit::Connection, e.to_string()),
+                )?;
                 ok(Ack::OK)
             }
             Method::UserInfoOf => {
@@ -268,13 +280,17 @@ impl Daemon {
                 let directories: DirectoriesParams = parse(params)?;
                 self.session
                     .set_shared_directories(directories.directories)
-                    .map_err(|e| failed(Exit::Usage, e.to_string()))?;
+                    .map_err(|e| {
+                        RpcError::application(Exit::Usage, e.to_string())
+                    })?;
                 ok(self.shares())
             }
             Method::SharesReindex => {
                 self.session
                     .set_shared_directories(self.session.shared_directories())
-                    .map_err(|e| failed(Exit::Usage, e.to_string()))?;
+                    .map_err(|e| {
+                        RpcError::application(Exit::Usage, e.to_string())
+                    })?;
                 ok(self.shares())
             }
         }
@@ -303,9 +319,11 @@ impl Daemon {
         &self,
         params: DownloadStartParams,
     ) -> Result<Value, RpcError> {
-        let directory = params
-            .download_directory
-            .unwrap_or_else(|| self.download_dir.clone());
+        // The daemon's own directory, always. Letting a caller name a path
+        // would hand any authenticated client an arbitrary write on this
+        // host's filesystem, and a remote one cannot see that filesystem to
+        // choose sensibly anyway.
+        let directory = self.download_dir.clone();
         let (download, updates) = self
             .session
             .download_with_metadata(
@@ -315,7 +333,12 @@ impl Daemon {
                 directory,
                 params.metadata.into(),
             )
-            .map_err(|e| failed(Exit::Transfer, format!("cannot start: {e}")))?;
+            .map_err(|e| {
+                RpcError::application(
+                    Exit::Transfer,
+                    format!("cannot start: {e}"),
+                )
+            })?;
 
         if let Ok(mut pending) = self.downloads.lock() {
             pending.push(PendingDownload {
@@ -338,6 +361,14 @@ impl Daemon {
         }
     }
 
+    fn identify(&self) -> AuthResult {
+        AuthResult {
+            protocol: PROTOCOL_VERSION,
+            daemon_version: env!("CARGO_PKG_VERSION").to_string(),
+            username: self.session.username(),
+        }
+    }
+
     fn status(&self) -> DaemonStatus {
         let (folders, files) = self.session.shared_counts();
         DaemonStatus {
@@ -357,8 +388,12 @@ impl Daemon {
 }
 
 fn ok<T: serde::Serialize>(value: T) -> Result<Value, RpcError> {
-    serde_json::to_value(value)
-        .map_err(|e| internal(format!("cannot serialize the reply: {e}")))
+    serde_json::to_value(value).map_err(|e| {
+        RpcError::new(
+            CODE_APPLICATION,
+            format!("cannot serialize the reply: {e}"),
+        )
+    })
 }
 
 fn parse<T: DeserializeOwned>(params: Value) -> Result<T, RpcError> {
@@ -366,14 +401,6 @@ fn parse<T: DeserializeOwned>(params: Value) -> Result<T, RpcError> {
         .map_err(|e| RpcError::new(CODE_INVALID_PARAMS, e.to_string()))
 }
 
-fn failed(exit: Exit, message: impl Into<String>) -> RpcError {
-    RpcError::application(exit, message)
-}
-
-fn internal(message: impl Into<String>) -> RpcError {
-    RpcError::new(CODE_APPLICATION, message)
-}
-
 /// Wall-clock seconds, to stamp a message the way the server stamps the ones
 /// it delivers. A clock before the epoch reads as zero rather than panicking.
 fn now_seconds() -> i64 {
@@ -382,336 +409,27 @@ fn now_seconds() -> i64 {
         .map_or(0, |since| since.as_secs() as i64)
 }
 
-// ---------------------------------------------------------------------------
-// Transports
-// ---------------------------------------------------------------------------
+mod transport;
 
-/// Where control connections arrive.
-///
-/// The Unix socket is the local path — its file permissions are the
-/// authentication, the same bargain Docker and ssh-agent make. TCP is opt-in
-/// and always needs the token.
-pub enum Listener {
-    #[cfg(unix)]
-    Unix(std::os::unix::net::UnixListener),
-    Tcp(TcpListener),
-}
-
-pub enum Stream {
-    #[cfg(unix)]
-    Unix(std::os::unix::net::UnixStream),
-    Tcp(TcpStream),
-}
-
-impl Stream {
-    fn try_clone(&self) -> std::io::Result<Self> {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(stream) => stream.try_clone().map(Self::Unix),
-            Self::Tcp(stream) => stream.try_clone().map(Self::Tcp),
-        }
-    }
-
-    /// Whether the transport itself proves who is calling.
-    const fn trusted_by_transport(&self) -> bool {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(_) => true,
-            Self::Tcp(_) => false,
-        }
-    }
-}
-
-impl std::io::Read for Stream {
-    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(stream) => stream.read(buffer),
-            Self::Tcp(stream) => stream.read(buffer),
-        }
-    }
-}
-
-impl Write for Stream {
-    fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(stream) => stream.write(buffer),
-            Self::Tcp(stream) => stream.write(buffer),
-        }
-    }
-
-    fn flush(&mut self) -> std::io::Result<()> {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(stream) => stream.flush(),
-            Self::Tcp(stream) => stream.flush(),
-        }
-    }
-}
-
-impl Listener {
-    /// Accept forever, handing each connection to its own thread.
-    pub fn serve(self, daemon: Arc<Daemon>) {
-        match self {
-            #[cfg(unix)]
-            Self::Unix(listener) => {
-                for stream in listener.incoming() {
-                    match stream {
-                        Ok(stream) => spawn_connection(
-                            Stream::Unix(stream),
-                            Arc::clone(&daemon),
-                        ),
-                        Err(e) => {
-                            soulseek_rs::warn!("control accept failed: {e}");
-                        }
-                    }
-                }
-            }
-            Self::Tcp(listener) => {
-                for stream in listener.incoming() {
-                    match stream {
-                        Ok(stream) => spawn_connection(
-                            Stream::Tcp(stream),
-                            Arc::clone(&daemon),
-                        ),
-                        Err(e) => {
-                            soulseek_rs::warn!("control accept failed: {e}");
-                        }
-                    }
-                }
-            }
-        }
-    }
-}
-
-fn spawn_connection(stream: Stream, daemon: Arc<Daemon>) {
-    std::thread::spawn(move || {
-        if let Err(e) = handle(stream, daemon) {
-            soulseek_rs::debug!("control connection ended: {e}");
-        }
-    });
-}
-
-/// Serve one connection: authenticate, then answer requests until it closes.
-fn handle(stream: Stream, daemon: Arc<Daemon>) -> std::io::Result<()> {
-    let reader = BufReader::new(stream.try_clone()?);
-    let trusted = stream.trusted_by_transport();
-
-    let (out, outbox) = sync_channel::<Response>(WRITE_QUEUE_DEPTH);
-    let writer = std::thread::spawn(move || write_loop(stream, &outbox));
-
-    let mut lines = reader.lines();
-    let authenticated = authenticate(&mut lines, &daemon, trusted, &out);
-    if !authenticated {
-        drop(out);
-        let _ = writer.join();
-        return Ok(());
-    }
-
-    // Only now does this connection get to see events: an unauthenticated
-    // socket must learn nothing at all.
-    let (subscription, events) = daemon.hub.subscribe();
-    let pump = {
-        let out = out.clone();
-        std::thread::spawn(move || {
-            for event in events {
-                if out.send(event).is_err() {
-                    break;
-                }
-            }
-        })
-    };
-
-    // Requests are answered on this thread, in order. A method slow enough to
-    // matter (re-indexing a large share) delays only the connection that asked
-    // for it, which is the right person to wait — and every other client has a
-    // connection of its own. Spawning per request would instead churn a thread
-    // for each of the handful of polls a TUI makes every frame.
-    for line in lines {
-        let line = line?;
-        if line.trim().is_empty() {
-            continue;
-        }
-        if let Some(response) = answer(&line, &daemon)
-            && out.send(response).is_err()
-        {
-            break;
-        }
-    }
-
-    daemon.hub.unsubscribe(subscription);
-    drop(out);
-    let _ = pump.join();
-    let _ = writer.join();
-    Ok(())
-}
-
-/// The first request has to be `auth`, and has to be good.
-fn authenticate(
-    lines: &mut std::io::Lines<BufReader<Stream>>,
-    daemon: &Daemon,
-    trusted: bool,
-    out: &SyncSender<Response>,
-) -> bool {
-    let Some(Ok(line)) = lines.next() else {
-        return false;
-    };
-    let request: Request = match serde_json::from_str(&line) {
-        Ok(request) => request,
-        Err(e) => {
-            let _ = out.send(Response::failure(
-                None,
-                RpcError::new(CODE_PARSE, e.to_string()),
-            ));
-            return false;
-        }
-    };
-
-    if Method::from_wire(&request.method) != Some(Method::Auth) {
-        let _ = out.send(Response::failure(
-            request.id,
-            RpcError::new(
-                CODE_INVALID_REQUEST,
-                "the first request on a connection must be `auth`",
-            ),
-        ));
-        return false;
-    }
-
-    let params: AuthParams =
-        serde_json::from_value(request.params).unwrap_or_default();
-    if !accepts(daemon, trusted, params.token.as_deref()) {
-        std::thread::sleep(AUTH_FAILURE_DELAY);
-        let _ = out.send(Response::failure(
-            request.id,
-            RpcError::application(Exit::Connection, "authentication failed"),
-        ));
-        return false;
-    }
-
-    let result = serde_json::to_value(AuthResult {
-        protocol: PROTOCOL_VERSION,
-        daemon_version: env!("CARGO_PKG_VERSION").to_string(),
-        username: daemon.session.username(),
-    })
-    .unwrap_or(Value::Null);
-    let _ = out.send(Response::result(request.id, result));
-    true
-}
-
-/// A Unix socket has already proved the caller is this user, so a token is
-/// optional there and mandatory everywhere else. A token that *is* offered is
-/// always checked, so a wrong one never passes.
-fn accepts(daemon: &Daemon, trusted: bool, token: Option<&str>) -> bool {
-    match token {
-        Some(token) => constant_time_eq(token, &daemon.token),
-        None => trusted,
-    }
-}
-
-/// Compare without leaking the position of the first difference through timing.
-fn constant_time_eq(left: &str, right: &str) -> bool {
-    if left.len() != right.len() {
-        return false;
-    }
-    left.bytes()
-        .zip(right.bytes())
-        .fold(0u8, |difference, (a, b)| difference | (a ^ b))
-        == 0
-}
-
-/// Turn one request line into the reply it deserves, or `None` for a
-/// notification, which by JSON-RPC rule is answered with silence.
-fn answer(line: &str, daemon: &Daemon) -> Option<Response> {
-    let request: Request = match serde_json::from_str(line) {
-        Ok(request) => request,
-        Err(e) => {
-            return Some(Response::failure(
-                None,
-                RpcError::new(CODE_PARSE, e.to_string()),
-            ));
-        }
-    };
-    let id = request.id.clone();
-    let Some(method) = Method::from_wire(&request.method) else {
-        return id.is_some().then(|| {
-            Response::failure(
-                request.id,
-                RpcError::new(
-                    CODE_METHOD_NOT_FOUND,
-                    format!("no such method: {}", request.method),
-                ),
-            )
-        });
-    };
-
-    let outcome = daemon.call(method, request.params);
-    id.map(|id| match outcome {
-        Ok(result) => Response::result(Some(id), result),
-        Err(error) => Response::failure(Some(id), error),
-    })
-}
-
-fn write_loop(stream: Stream, outbox: &Receiver<Response>) {
-    let mut stream = stream;
-    for response in outbox {
-        let Ok(line) = serde_json::to_string(&response) else {
-            continue;
-        };
-        if writeln!(stream, "{line}").is_err() || stream.flush().is_err() {
-            return;
-        }
-    }
-}
-
-/// Bind the TCP control port, refusing to come up rather than silently
-/// listening somewhere unintended.
-pub fn bind_tcp(address: &str) -> std::io::Result<Listener> {
-    TcpListener::bind(address).map(Listener::Tcp)
-}
-
-/// Bind the Unix control socket with permissions that make it the local
-/// authentication: only this user can open it.
 #[cfg(unix)]
-pub fn bind_unix(path: &std::path::Path) -> std::io::Result<Listener> {
-    use std::os::unix::fs::PermissionsExt;
-
-    if let Some(parent) = path.parent() {
-        std::fs::create_dir_all(parent)?;
-    }
-    // A socket file outlives the process that made it, so a previous crash
-    // would otherwise make the daemon unstartable.
-    if path.exists() {
-        remove_stale_socket(path)?;
-    }
-    let listener = std::os::unix::net::UnixListener::bind(path)?;
-    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))?;
-    Ok(Listener::Unix(listener))
-}
-
-/// Remove a socket file left by a dead daemon — but never one a live daemon is
-/// still serving, which would silently steal its clients.
-#[cfg(unix)]
-fn remove_stale_socket(path: &std::path::Path) -> std::io::Result<()> {
-    match std::os::unix::net::UnixStream::connect(path) {
-        Ok(_) => Err(std::io::Error::new(
-            std::io::ErrorKind::AddrInUse,
-            format!("a daemon is already listening on {}", path.display()),
-        )),
-        Err(_) => std::fs::remove_file(path),
-    }
-}
+pub use transport::bind_unix;
+pub use transport::{Listener, bind_tcp};
 
 #[cfg(test)]
 mod tests {
+    use super::super::proto::{CODE_METHOD_NOT_FOUND, CODE_PARSE};
+    use super::transport::{accepts, answer, constant_time_eq};
     use super::*;
     use serde_json::json;
+    use std::sync::mpsc::Receiver;
 
     #[test]
     fn a_unix_socket_needs_no_token_but_tcp_does() {
         let daemon = daemon_with_token("secret");
-        assert!(accepts(&daemon, true, None), "socket permissions are the auth");
+        assert!(
+            accepts(&daemon, true, None),
+            "socket permissions are the auth"
+        );
         assert!(!accepts(&daemon, false, None), "TCP must demand a token");
     }
 
@@ -784,8 +502,9 @@ mod tests {
         assert!(
             document["methods"]
                 .as_array()
-                .is_some_and(|methods| methods.len() == Method::ALL.len()
-                    + super::super::proto::Event::ALL.len()),
+                .is_some_and(|methods| methods.len()
+                    == Method::ALL.len()
+                        + super::super::proto::Event::ALL.len()),
             "discover must describe every method and event"
         );
     }
@@ -815,6 +534,7 @@ mod tests {
             token: token.to_string(),
             started: Instant::now(),
             stop: Arc::new(AtomicBool::new(false)),
+            open: Arc::new(std::sync::atomic::AtomicUsize::new(0)),
             rooms: Mutex::new(Vec::new()),
         }
     }
@@ -859,7 +579,10 @@ mod tests {
         ) -> Option<Vec<soulseek_rs::SearchResult>> {
             None
         }
-        fn start_wishlist_search(&self, _query: &str) -> soulseek_rs::Result<()> {
+        fn start_wishlist_search(
+            &self,
+            _query: &str,
+        ) -> soulseek_rs::Result<()> {
             Ok(())
         }
         fn wishlist_interval(&self) -> Duration {
@@ -972,7 +695,10 @@ mod tests {
         ) -> Option<Vec<soulseek_rs::SharedDirectory>> {
             None
         }
-        fn request_user_info(&self, _username: &str) -> soulseek_rs::Result<()> {
+        fn request_user_info(
+            &self,
+            _username: &str,
+        ) -> soulseek_rs::Result<()> {
             Ok(())
         }
         fn user_info(&self, _username: &str) -> Option<soulseek_rs::UserInfo> {

soulseek-rs/src/daemon/server/transport.rs

@@ -0,0 +1,429 @@
+//! Getting bytes to and from a control client: who may connect, how a request
+//! is framed, and how replies and pushed events share one socket.
+//!
+//! One thread per connection, which is noise next to the thousand-odd peer
+//! threads the client already runs. Each connection owns a writer thread fed by
+//! a channel, so request replies and events interleave without a lock and
+//! neither can block the other.
+
+use super::super::proto::{
+    AuthParams, CODE_INVALID_REQUEST, CODE_METHOD_NOT_FOUND, CODE_PARSE,
+    Method, Request, Response, RpcError,
+};
+use super::Daemon;
+use crate::output::Exit;
+use serde_json::Value;
+use std::io::{BufRead, BufReader, Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::sync::Arc;
+use std::sync::atomic::Ordering;
+use std::sync::mpsc::{Receiver, SyncSender, sync_channel};
+use std::time::Duration;
+
+/// How long a failed authentication costs the caller. Not a serious defence —
+/// the token is 256 bits — but it keeps a wrong-token loop off the CPU.
+const AUTH_FAILURE_DELAY: Duration = Duration::from_secs(1);
+
+/// Replies waiting to go out on one connection. Bounded, so a client that has
+/// stopped reading cannot make the daemon buffer without limit.
+const WRITE_QUEUE_DEPTH: usize = 1024;
+
+/// The longest request line the daemon will read. Generous next to the largest
+/// real request (a `shares.set` naming every folder) and small enough that an
+/// unauthenticated peer cannot make the daemon allocate without bound.
+const MAX_LINE: u64 = 1 << 20;
+
+/// How long an unauthenticated connection may stay silent. Applies only until
+/// `auth` succeeds — an established client is expected to idle, holding its
+/// connection open for events without sending anything.
+const AUTH_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// How many control connections may be open at once. Far above any real use
+/// (a TUI, a few scripts, an agent), and low enough that an unauthenticated
+/// peer cannot exhaust the daemon's threads.
+const MAX_CONNECTIONS: usize = 64;
+
+/// Where control connections arrive.
+///
+/// The Unix socket is the local path — its file permissions are the
+/// authentication, the same bargain Docker and ssh-agent make. TCP is opt-in
+/// and always needs the token.
+pub enum Listener {
+    #[cfg(unix)]
+    Unix(std::os::unix::net::UnixListener),
+    Tcp(TcpListener),
+}
+
+pub enum Stream {
+    #[cfg(unix)]
+    Unix(std::os::unix::net::UnixStream),
+    Tcp(TcpStream),
+}
+
+impl Stream {
+    fn try_clone(&self) -> std::io::Result<Self> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.try_clone().map(Self::Unix),
+            Self::Tcp(stream) => stream.try_clone().map(Self::Tcp),
+        }
+    }
+
+    fn set_read_timeout(&self, timeout: Option<Duration>) {
+        let _ = match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.set_read_timeout(timeout),
+            Self::Tcp(stream) => stream.set_read_timeout(timeout),
+        };
+    }
+
+    /// End the connection from another thread. This is what makes "a client
+    /// that stops reading is disconnected" true rather than aspirational: the
+    /// hub can only reach a stalled client by closing its socket.
+    pub(super) fn shutdown(&self) {
+        let _ = match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.shutdown(std::net::Shutdown::Both),
+            Self::Tcp(stream) => stream.shutdown(std::net::Shutdown::Both),
+        };
+    }
+
+    /// Whether the transport itself proves who is calling.
+    const fn trusted_by_transport(&self) -> bool {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(_) => true,
+            Self::Tcp(_) => false,
+        }
+    }
+}
+
+impl std::io::Read for Stream {
+    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.read(buffer),
+            Self::Tcp(stream) => stream.read(buffer),
+        }
+    }
+}
+
+impl Write for Stream {
+    fn write(&mut self, buffer: &[u8]) -> std::io::Result<usize> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.write(buffer),
+            Self::Tcp(stream) => stream.write(buffer),
+        }
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(stream) => stream.flush(),
+            Self::Tcp(stream) => stream.flush(),
+        }
+    }
+}
+
+impl Listener {
+    /// Accept forever, handing each connection to its own thread.
+    pub fn serve(self, daemon: Arc<Daemon>) {
+        loop {
+            match self.accept() {
+                Ok(stream) => spawn_connection(stream, Arc::clone(&daemon)),
+                Err(e) => soulseek_rs::warn!("control accept failed: {e}"),
+            }
+        }
+    }
+
+    fn accept(&self) -> std::io::Result<Stream> {
+        match self {
+            #[cfg(unix)]
+            Self::Unix(listener) => {
+                listener.accept().map(|(stream, _)| Stream::Unix(stream))
+            }
+            Self::Tcp(listener) => {
+                listener.accept().map(|(stream, _)| Stream::Tcp(stream))
+            }
+        }
+    }
+}
+
+fn spawn_connection(stream: Stream, daemon: Arc<Daemon>) {
+    let open = daemon.open.fetch_add(1, Ordering::Relaxed) + 1;
+    if open > MAX_CONNECTIONS {
+        daemon.open.fetch_sub(1, Ordering::Relaxed);
+        soulseek_rs::warn!(
+            "refusing a control connection: {MAX_CONNECTIONS} already open"
+        );
+        stream.shutdown();
+        return;
+    }
+    std::thread::spawn(move || {
+        if let Err(e) = handle(stream, daemon.as_ref()) {
+            soulseek_rs::debug!("control connection ended: {e}");
+        }
+        daemon.open.fetch_sub(1, Ordering::Relaxed);
+    });
+}
+
+/// Serve one connection: authenticate, then answer requests until it closes.
+fn handle(stream: Stream, daemon: &Daemon) -> std::io::Result<()> {
+    let mut reader = BufReader::new(stream.try_clone()?);
+    let trusted = stream.trusted_by_transport();
+    let closer = stream.try_clone()?;
+
+    // A peer that connects and says nothing must not hold a thread forever.
+    stream.set_read_timeout(Some(AUTH_TIMEOUT));
+
+    let (out, outbox) = sync_channel::<Response>(WRITE_QUEUE_DEPTH);
+    let writer = std::thread::spawn(move || write_loop(stream, &outbox));
+
+    if !authenticate(&mut reader, daemon, trusted, &out) {
+        closer.shutdown();
+        drop(out);
+        let _ = writer.join();
+        return Ok(());
+    }
+    // An established client is expected to idle, holding the connection open
+    // for events without sending anything.
+    closer.set_read_timeout(None);
+
+    // Only now does this connection get to see events: an unauthenticated
+    // socket must learn nothing at all.
+    let (subscription, events) = {
+        let closer = closer.try_clone()?;
+        daemon.hub.subscribe(move || closer.shutdown())
+    };
+    let pump = {
+        let out = out.clone();
+        std::thread::spawn(move || {
+            for event in events {
+                if out.send(event).is_err() {
+                    break;
+                }
+            }
+        })
+    };
+
+    // Requests are answered on this thread, in order. A method slow enough to
+    // matter (re-indexing a large share) delays only the connection that asked
+    // for it, which is the right person to wait — and every other client has a
+    // connection of its own. Spawning per request would instead churn a thread
+    // for each of the handful of polls a TUI makes every frame.
+    //
+    // Errors break rather than propagate: returning here would skip the
+    // unsubscribe below and leak a hub subscriber plus two threads for the
+    // life of the daemon.
+    loop {
+        match read_line(&mut reader) {
+            Ok(Some(line)) => {
+                if line.trim().is_empty() {
+                    continue;
+                }
+                if let Some(response) = answer(&line, daemon)
+                    && out.send(response).is_err()
+                {
+                    break;
+                }
+            }
+            Ok(None) => break,
+            Err(e) => {
+                soulseek_rs::debug!("control connection ended: {e}");
+                break;
+            }
+        }
+    }
+
+    daemon.hub.unsubscribe(subscription);
+    closer.shutdown();
+    drop(out);
+    let _ = pump.join();
+    let _ = writer.join();
+    Ok(())
+}
+
+/// Read one newline-delimited request, refusing a line long enough to be an
+/// attack rather than a request. `Ok(None)` means the peer hung up.
+fn read_line(
+    reader: &mut BufReader<Stream>,
+) -> std::io::Result<Option<String>> {
+    let mut line = String::new();
+    let read = reader.by_ref().take(MAX_LINE).read_line(&mut line)?;
+    if read == 0 {
+        return Ok(None);
+    }
+    if read as u64 == MAX_LINE && !line.ends_with('\n') {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::InvalidData,
+            "request line exceeds the maximum size",
+        ));
+    }
+    Ok(Some(line))
+}
+
+/// The first request has to be `auth`, and has to be good.
+fn authenticate(
+    reader: &mut BufReader<Stream>,
+    daemon: &Daemon,
+    trusted: bool,
+    out: &SyncSender<Response>,
+) -> bool {
+    let Ok(Some(line)) = read_line(reader) else {
+        return false;
+    };
+    let request: Request = match serde_json::from_str(&line) {
+        Ok(request) => request,
+        Err(e) => {
+            let _ = out.send(Response::failure(
+                None,
+                RpcError::new(CODE_PARSE, e.to_string()),
+            ));
+            return false;
+        }
+    };
+
+    if Method::from_wire(&request.method) != Some(Method::Auth) {
+        let _ = out.send(Response::failure(
+            request.id,
+            RpcError::new(
+                CODE_INVALID_REQUEST,
+                "the first request on a connection must be `auth`",
+            ),
+        ));
+        return false;
+    }
+
+    let params: AuthParams =
+        serde_json::from_value(request.params).unwrap_or_default();
+    if !accepts(daemon, trusted, params.token.as_deref()) {
+        std::thread::sleep(AUTH_FAILURE_DELAY);
+        let _ = out.send(Response::failure(
+            request.id,
+            RpcError::application(Exit::Connection, "authentication failed"),
+        ));
+        return false;
+    }
+
+    let result = serde_json::to_value(daemon.identify()).unwrap_or(Value::Null);
+    let _ = out.send(Response::result(request.id, result));
+    true
+}
+
+/// A Unix socket has already proved the caller is this user, so a token is
+/// optional there and mandatory everywhere else. A token that *is* offered is
+/// always checked, so a wrong one never passes.
+pub(super) fn accepts(
+    daemon: &Daemon,
+    trusted: bool,
+    token: Option<&str>,
+) -> bool {
+    match token {
+        Some(token) => constant_time_eq(token, &daemon.token),
+        None => trusted,
+    }
+}
+
+/// Compare without leaking the position of the first difference through timing.
+pub(super) fn constant_time_eq(left: &str, right: &str) -> bool {
+    if left.len() != right.len() {
+        return false;
+    }
+    left.bytes()
+        .zip(right.bytes())
+        .fold(0u8, |difference, (a, b)| difference | (a ^ b))
+        == 0
+}
+
+/// Turn one request line into the reply it deserves, or `None` for a
+/// notification, which by JSON-RPC rule is answered with silence.
+pub(super) fn answer(line: &str, daemon: &Daemon) -> Option<Response> {
+    let request: Request = match serde_json::from_str(line) {
+        Ok(request) => request,
+        Err(e) => {
+            return Some(Response::failure(
+                None,
+                RpcError::new(CODE_PARSE, e.to_string()),
+            ));
+        }
+    };
+    let id = request.id.clone();
+    let Some(method) = Method::from_wire(&request.method) else {
+        return id.is_some().then(|| {
+            Response::failure(
+                request.id,
+                RpcError::new(
+                    CODE_METHOD_NOT_FOUND,
+                    format!("no such method: {}", request.method),
+                ),
+            )
+        });
+    };
+
+    let outcome = daemon.call(method, request.params);
+    id.map(|id| match outcome {
+        Ok(result) => Response::result(Some(id), result),
+        Err(error) => Response::failure(Some(id), error),
+    })
+}
+
+fn write_loop(stream: Stream, outbox: &Receiver<Response>) {
+    let mut stream = stream;
+    for response in outbox {
+        let Ok(line) = serde_json::to_string(&response) else {
+            continue;
+        };
+        if writeln!(stream, "{line}").is_err() || stream.flush().is_err() {
+            return;
+        }
+    }
+}
+
+/// Bind the TCP control port, refusing to come up rather than silently
+/// listening somewhere unintended.
+pub fn bind_tcp(address: &str) -> std::io::Result<Listener> {
+    TcpListener::bind(address).map(Listener::Tcp)
+}
+
+/// Bind the Unix control socket with permissions that make it the local
+/// authentication: only this user can open it.
+///
+/// Bound under a temporary name and moved into place, because `bind` creates
+/// the socket with the process umask — for the moment between `bind` and
+/// `set_permissions` the real path would be connectable by anyone on the
+/// machine, and on this transport connecting *is* authenticating. The rename
+/// is atomic, so the published path never exists with the wrong mode.
+#[cfg(unix)]
+pub fn bind_unix(path: &std::path::Path) -> std::io::Result<Listener> {
+    use std::os::unix::fs::PermissionsExt;
+
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    // A socket file outlives the process that made it, so a previous crash
+    // would otherwise make the daemon unstartable.
+    if path.exists() {
+        remove_stale_socket(path)?;
+    }
+
+    let staging = path.with_extension("binding");
+    let _ = std::fs::remove_file(&staging);
+    let listener = std::os::unix::net::UnixListener::bind(&staging)?;
+    std::fs::set_permissions(&staging, std::fs::Permissions::from_mode(0o600))?;
+    std::fs::rename(&staging, path)?;
+    Ok(Listener::Unix(listener))
+}
+
+/// Remove a socket file left by a dead daemon — but never one a live daemon is
+/// still serving, which would silently steal its clients.
+#[cfg(unix)]
+fn remove_stale_socket(path: &std::path::Path) -> std::io::Result<()> {
+    match std::os::unix::net::UnixStream::connect(path) {
+        Ok(_) => Err(std::io::Error::new(
+            std::io::ErrorKind::AddrInUse,
+            format!("a daemon is already listening on {}", path.display()),
+        )),
+        Err(_) => std::fs::remove_file(path),
+    }
+}