//! Minimal OpenSubsonic client covering what the browser and player need. use std::hash::{BuildHasher, RandomState}; use std::time::{SystemTime, UNIX_EPOCH}; use anyhow::{Context, Result, anyhow, bail}; use serde::de::{DeserializeOwned, Deserializer}; use serde::{Deserialize, Serialize}; const API_VERSION: &str = "1.16.1"; const CLIENT_NAME: &str = "remus"; /// Subsonic error 41: the server does not accept token authentication. const TOKEN_AUTH_NOT_SUPPORTED: i64 = 41; /// Subsonic error 40: wrong username or password. pub const WRONG_CREDENTIALS: i64 = 40; /// How requests prove who is asking. #[derive(Clone, Debug, PartialEq, Eq)] pub enum Auth { /// `t` = md5(password + `s`). The password itself is not kept. Token { salt: String, token: String }, /// The password, sent hex-encoded on every request. For servers that /// refuse tokens, such as Nextcloud Music. Password(String), } /// An error reported by the server inside a Subsonic response. #[derive(Debug)] pub struct ApiError { pub code: i64, pub message: String, /// The `type` the server reports about itself, such as "nextcloud music". pub server: Option, } impl std::fmt::Display for ApiError { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.write_str(&self.message) } } impl std::error::Error for ApiError {} /// The server's error code, if `e` is an error reported by the server. pub fn api_error(e: &anyhow::Error) -> Option<&ApiError> { e.downcast_ref::() } #[derive(Clone)] pub struct Client { http: reqwest::Client, base: String, user: String, auth: Auth, } impl Client { pub fn new(base: &str, user: &str, auth: Auth) -> Self { let http = reqwest::Client::builder() .user_agent(concat!("remus/", env!("CARGO_PKG_VERSION"))) .timeout(std::time::Duration::from_secs(30)) .build() .expect("http client"); Client { http, base: normalize_base(base), user: user.to_string(), auth, } } /// Derives a token from the password so the password itself is never stored. /// The token is still password-equivalent for this server. pub fn from_password(base: &str, user: &str, password: &str) -> Self { let salt = random_salt(); let token = format!("{:x}", md5::compute(format!("{password}{salt}"))); Client::new(base, user, Auth::Token { salt, token }) } /// Logs in with a token, or with the password itself when the server /// refuses tokens. Returns the client that worked. pub async fn login(base: &str, user: &str, password: &str) -> Result { let client = Client::from_password(base, user, password); match client.ping().await { Ok(()) => Ok(client), Err(e) if api_error(&e).is_some_and(|a| a.code == TOKEN_AUTH_NOT_SUPPORTED) => { log::info!("server does not accept token auth, logging in with the password"); let client = Client::new(base, user, Auth::Password(password.to_string())); client.ping().await?; Ok(client) } Err(e) => Err(e), } } pub fn base(&self) -> &str { &self.base } pub fn user(&self) -> &str { &self.user } pub fn auth(&self) -> &Auth { &self.auth } /// The query parameters every request starts with. fn auth_params(&self) -> Vec<(&'static str, String)> { let mut params = vec![("u", self.user.clone())]; match &self.auth { Auth::Token { salt, token } => { params.push(("t", token.clone())); params.push(("s", salt.clone())); } Auth::Password(password) => { // Hex keeps the password out of plain sight in URLs; it is not encryption. let hex: String = password.bytes().map(|b| format!("{b:02x}")).collect(); params.push(("p", format!("enc:{hex}"))); } } params.push(("v", API_VERSION.to_string())); params.push(("c", CLIENT_NAME.to_string())); params.push(("f", "json".to_string())); params } fn endpoint_url(&self, endpoint: &str, params: &[(&str, String)]) -> Result { let mut all = self.auth_params(); all.extend(params.iter().cloned()); reqwest::Url::parse_with_params(&format!("{}/rest/{endpoint}", self.base), &all) .with_context(|| format!("invalid server url {}", self.base)) } async fn call(&self, endpoint: &str, params: &[(&str, String)]) -> Result { let url = self.endpoint_url(endpoint, params)?; let resp = self .http .get(url) .send() .await .map_err(redact) .with_context(|| format!("{endpoint} request failed"))?; let status = resp.status(); if !status.is_success() { bail!("{endpoint}: server returned {status}"); } let body: serde_json::Value = resp .json() .await .map_err(redact) .with_context(|| format!("{endpoint}: invalid json"))?; let inner = unwrap_response(endpoint, body)?; serde_json::from_value(inner).with_context(|| format!("{endpoint}: unexpected response shape")) } pub async fn ping(&self) -> Result<()> { let _: serde_json::Value = self.call("ping", &[]).await?; Ok(()) } /// `kind` is a getAlbumList2 type: newest, random, alphabeticalByName, frequent, recent... pub async fn album_list(&self, kind: &str, size: u32, offset: u32) -> Result> { #[derive(Deserialize)] struct R { #[serde(rename = "albumList2", default)] list: AlbumList, } #[derive(Deserialize, Default)] struct AlbumList { #[serde(default)] album: Vec, } let r: R = self .call( "getAlbumList2", &[ ("type", kind.into()), ("size", size.to_string()), ("offset", offset.to_string()), ], ) .await?; Ok(r.list.album) } pub async fn artists(&self) -> Result> { #[derive(Deserialize)] struct R { #[serde(default)] artists: Indexes, } #[derive(Deserialize, Default)] struct Indexes { #[serde(default)] index: Vec, } #[derive(Deserialize)] struct Index { #[serde(default)] artist: Vec, } let r: R = self.call("getArtists", &[]).await?; Ok(r.artists.index.into_iter().flat_map(|i| i.artist).collect()) } pub async fn artist(&self, id: &str) -> Result { #[derive(Deserialize)] struct R { artist: ArtistDetail, } let r: R = self.call("getArtist", &[("id", id.into())]).await?; Ok(r.artist) } /// Every song on the artist's albums, album by album. A few albums are /// fetched at a time, so an artist with dozens does not flood the server. pub async fn artist_songs(&self, id: &str) -> Result> { let albums = self.artist(id).await?.album; let limit = std::sync::Arc::new(tokio::sync::Semaphore::new(4)); let tasks: Vec<_> = albums .into_iter() .map(|a| { let (client, limit) = (self.clone(), limit.clone()); tokio::spawn(async move { let _permit = limit.acquire_owned().await?; anyhow::Ok(client.album(&a.id).await?.song) }) }) .collect(); let mut songs = Vec::new(); for t in tasks { songs.extend(t.await??); } Ok(songs) } pub async fn album(&self, id: &str) -> Result { #[derive(Deserialize)] struct R { album: AlbumDetail, } let r: R = self.call("getAlbum", &[("id", id.into())]).await?; Ok(r.album) } pub async fn playlists(&self) -> Result> { #[derive(Deserialize)] struct R { #[serde(default)] playlists: Lists, } #[derive(Deserialize, Default)] struct Lists { #[serde(default)] playlist: Vec, } let r: R = self.call("getPlaylists", &[]).await?; Ok(r.playlists.playlist) } pub async fn playlist(&self, id: &str) -> Result { #[derive(Deserialize)] struct R { playlist: PlaylistDetail, } let r: R = self.call("getPlaylist", &[("id", id.into())]).await?; Ok(r.playlist) } pub async fn search(&self, query: &str) -> Result { #[derive(Deserialize)] struct R { #[serde(rename = "searchResult3", default)] result: SearchResult, } let r: R = self .call( "search3", &[ ("query", query.into()), ("artistCount", "20".into()), ("albumCount", "40".into()), ("songCount", "80".into()), ], ) .await?; Ok(r.result) } /// Up to `size` random songs from the whole library. Servers cap `size` /// at 500. pub async fn random_songs(&self, size: u32) -> Result> { #[derive(Deserialize)] struct R { #[serde(rename = "randomSongs", default)] list: Songs, } #[derive(Deserialize, Default)] struct Songs { #[serde(default)] song: Vec, } let r: R = self.call("getRandomSongs", &[("size", size.to_string())]).await?; Ok(r.list.song) } pub async fn scrobble(&self, id: &str, submission: bool) -> Result<()> { let _: serde_json::Value = self .call("scrobble", &[("id", id.into()), ("submission", submission.to_string())]) .await?; Ok(()) } pub async fn cover_art(&self, id: &str, size: u32) -> Result> { let url = self.endpoint_url("getCoverArt", &[("id", id.into()), ("size", size.to_string())])?; let resp = self.http.get(url).send().await.map_err(redact)?; let status = resp.status(); if !status.is_success() { bail!("getCoverArt: server returned {status}"); } let is_json = resp .headers() .get(reqwest::header::CONTENT_TYPE) .and_then(|v| v.to_str().ok()) .is_some_and(|v| v.contains("json") || v.contains("xml")); if is_json { bail!("getCoverArt: no image for {id}"); } Ok(resp.bytes().await.map_err(redact)?.to_vec()) } pub fn stream_url(&self, id: &str) -> String { self.endpoint_url("stream", &[("id", id.into())]) .map(|u| u.to_string()) .unwrap_or_default() } } /// The payload of a Subsonic response, or the server's error as an `ApiError`. fn unwrap_response(endpoint: &str, mut body: serde_json::Value) -> Result { let inner = body .get_mut("subsonic-response") .map(serde_json::Value::take) .ok_or_else(|| anyhow!("{endpoint}: not a subsonic response"))?; if inner.get("status").and_then(|s| s.as_str()) == Some("ok") { return Ok(inner); } Err(ApiError { code: inner.pointer("/error/code").and_then(|c| c.as_i64()).unwrap_or(0), message: inner .pointer("/error/message") .and_then(|m| m.as_str()) .unwrap_or("unknown error") .to_string(), server: inner.get("type").and_then(|s| s.as_str()).map(str::to_string), } .into()) } /// Request URLs carry the auth token, so they must never reach an error /// message: those end up on screen and in the logs. fn redact(e: reqwest::Error) -> reqwest::Error { e.without_url() } fn normalize_base(base: &str) -> String { let base = base.trim().trim_end_matches('/'); let base = base.strip_suffix("/rest").unwrap_or(base); if base.starts_with("http://") || base.starts_with("https://") { base.to_string() } else { format!("https://{base}") } } fn random_salt() -> String { let nanos = SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_nanos()) .unwrap_or(0); let a = RandomState::new().hash_one(nanos); let b = RandomState::new().hash_one(a ^ u64::from(std::process::id())); format!("{a:016x}{b:016x}") } /// Older servers send ids as numbers, OpenSubsonic as strings. fn de_id<'de, D: Deserializer<'de>>(d: D) -> Result { Ok(match serde_json::Value::deserialize(d)? { serde_json::Value::String(s) => s, serde_json::Value::Number(n) => n.to_string(), other => other.to_string(), }) } fn de_opt_id<'de, D: Deserializer<'de>>(d: D) -> Result, D::Error> { Ok(match Option::::deserialize(d)? { Some(serde_json::Value::String(s)) if !s.is_empty() => Some(s), Some(serde_json::Value::Number(n)) => Some(n.to_string()), _ => None, }) } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Album { #[serde(deserialize_with = "de_id")] pub id: String, #[serde(default)] pub name: String, #[serde(default)] pub artist: Option, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, #[serde(default)] pub year: Option, } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Artist { #[serde(deserialize_with = "de_id")] pub id: String, #[serde(default)] pub name: String, #[serde(default)] pub album_count: Option, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ArtistDetail { #[serde(default)] pub name: String, #[serde(default)] pub album: Vec, } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct AlbumDetail { #[serde(default)] pub name: String, #[serde(default)] pub artist: Option, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, #[serde(default)] pub year: Option, #[serde(default)] pub duration: Option, #[serde(default)] pub song: Vec, } #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Song { #[serde(deserialize_with = "de_id")] pub id: String, #[serde(default)] pub title: String, #[serde(default)] pub artist: Option, #[serde(default)] pub album: Option, /// None in queues saved before it was kept, and from servers that leave it out. #[serde(default, deserialize_with = "de_opt_id")] pub album_id: Option, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, #[serde(default)] pub duration: Option, #[serde(default)] pub track: Option, #[serde(default)] pub disc_number: Option, } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Playlist { #[serde(deserialize_with = "de_id")] pub id: String, #[serde(default)] pub name: String, #[serde(default)] pub song_count: Option, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, #[serde(default)] pub owner: Option, } #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] pub struct PlaylistDetail { #[serde(default)] pub name: String, #[serde(default, deserialize_with = "de_opt_id")] pub cover_art: Option, #[serde(default)] pub duration: Option, #[serde(default)] pub entry: Vec, } #[derive(Debug, Clone, Default, Deserialize)] pub struct SearchResult { #[serde(default)] pub artist: Vec, #[serde(default)] pub album: Vec, #[serde(default)] pub song: Vec, } #[cfg(test)] mod tests { use super::*; #[test] fn base_url_is_normalized() { assert_eq!(normalize_base("music.example.com/"), "https://music.example.com"); assert_eq!(normalize_base("http://nas:4533/rest"), "http://nas:4533"); } #[test] fn numeric_ids_are_accepted() { let a: Album = serde_json::from_str(r#"{"id": 42, "name": "X", "coverArt": 7}"#).unwrap(); assert_eq!(a.id, "42"); assert_eq!(a.cover_art.as_deref(), Some("7")); let s: Song = serde_json::from_str(r#"{"id": 1, "albumId": 42}"#).unwrap(); assert_eq!(s.album_id.as_deref(), Some("42")); let s: Song = serde_json::from_str(r#"{"id": 1}"#).unwrap(); assert_eq!(s.album_id, None); } /// A loopback HTTP server that answers every request with `body` and /// sends each request line back. fn fake_server(body: &'static str) -> (String, std::sync::mpsc::Receiver) { use std::io::{BufRead, BufReader, Write}; let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let addr = listener.local_addr().unwrap(); let (tx, rx) = std::sync::mpsc::channel(); std::thread::spawn(move || { for stream in listener.incoming() { let Ok(mut stream) = stream else { continue }; let mut line = String::new(); let _ = BufReader::new(stream.try_clone().unwrap()).read_line(&mut line); let _ = tx.send(line); let _ = write!( stream, "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}", body.len() ); } }); (format!("http://{addr}"), rx) } #[tokio::test] async fn random_songs_asks_for_the_size_and_reads_the_songs() { let (base, requests) = fake_server( r#"{"subsonic-response":{"status":"ok","randomSongs":{"song":[ {"id":"s1","title":"One","albumId":"al-1"},{"id":"s2","title":"Two"}]}}}"#, ); let c = Client::new(&base, "u", Auth::Password("sesame".into())); let songs = c.random_songs(50).await.unwrap(); let ids: Vec<_> = songs.iter().map(|s| s.id.as_str()).collect(); assert_eq!(ids, ["s1", "s2"]); assert_eq!(songs[0].album_id.as_deref(), Some("al-1")); let line = requests.recv().unwrap(); assert!(line.contains("/rest/getRandomSongs?"), "{line}"); assert!(line.contains("size=50"), "{line}"); } #[tokio::test] async fn random_songs_from_an_empty_library_is_empty() { let (base, _) = fake_server(r#"{"subsonic-response":{"status":"ok","randomSongs":{}}}"#); let c = Client::new(&base, "u", Auth::Password("sesame".into())); assert!(c.random_songs(50).await.unwrap().is_empty()); } /// Exercises every endpoint against a real server: /// REMUS_TEST_URL=... REMUS_TEST_USER=... REMUS_TEST_PASS=... cargo test -- --ignored #[tokio::test] #[ignore] async fn live_server() { let var = |k| std::env::var(k).unwrap_or_else(|_| panic!("{k} not set")); let (url, user, pass) = (var("REMUS_TEST_URL"), var("REMUS_TEST_USER"), var("REMUS_TEST_PASS")); let Ok(c) = Client::login(&url, &user, &pass).await else { panic!("login to {url} failed"); }; println!( "auth: {}", if matches!(c.auth(), Auth::Token { .. }) { "token" } else { "password" } ); let albums = c.album_list("newest", 10, 0).await.unwrap(); assert!(!albums.is_empty(), "no albums"); let album = c.album(&albums[0].id).await.unwrap(); assert!(!album.song.is_empty(), "album has no songs"); assert_eq!(album.song[0].album_id.as_deref(), Some(albums[0].id.as_str())); println!( "album: {} by {:?}, {} songs", album.name, album.artist, album.song.len() ); let cover = album.cover_art.as_deref().expect("album has no cover id"); let bytes = c.cover_art(cover, 256).await.unwrap(); let img = image::load_from_memory(&bytes).unwrap(); println!("cover: {}x{}", img.width(), img.height()); let artists = c.artists().await.unwrap(); assert!(!artists.is_empty(), "no artists"); let artist = c.artist(&artists[0].id).await.unwrap(); println!("artist: {} with {} albums", artist.name, artist.album.len()); let songs = c.artist_songs(&artists[0].id).await.unwrap(); assert!(!songs.is_empty(), "artist has no songs"); println!("artist songs: {}", songs.len()); let playlists = c.playlists().await.unwrap(); if let Some(p) = playlists.first() { let p = c.playlist(&p.id).await.unwrap(); println!("playlist: {} with {} entries", p.name, p.entry.len()); } let random = c.random_songs(20).await.unwrap(); assert!(!random.is_empty(), "no random songs"); println!("random: {} songs", random.len()); let found = c.search(&album.name).await.unwrap(); assert!(!found.album.is_empty(), "search found nothing for {}", album.name); let url = c.stream_url(&album.song[0].id); let resp = reqwest::get(&url).await.unwrap(); assert!(resp.status().is_success(), "stream returned {}", resp.status()); println!("stream content-type: {:?}", resp.headers().get("content-type")); } #[tokio::test] async fn errors_never_contain_the_token() { // Port 1 on loopback refuses the connection, so the request fails. let auth = Auth::Token { salt: "somesalt".into(), token: "secrettoken".into(), }; let c = Client::new("http://127.0.0.1:1", "u", auth); let err = format!("{:#}", c.ping().await.unwrap_err()); assert!(!err.contains("secrettoken"), "token leaked: {err}"); assert!(!err.contains("somesalt"), "salt leaked: {err}"); let err = format!("{:#}", c.cover_art("al-1", 256).await.unwrap_err()); assert!(!err.contains("secrettoken"), "token leaked: {err}"); } #[tokio::test] async fn errors_never_contain_the_password() { let c = Client::new("http://127.0.0.1:1", "u", Auth::Password("sesame".into())); let hex = "736573616d65"; for err in [ format!("{:#}", c.ping().await.unwrap_err()), format!("{:#}", c.cover_art("al-1", 256).await.unwrap_err()), ] { assert!(!err.contains("sesame") && !err.contains(hex), "password leaked: {err}"); } } #[test] fn token_is_md5_of_password_and_salt() { let c = Client::from_password("http://x", "u", "sesame"); let Auth::Token { salt, token } = c.auth() else { panic!("from_password should use a token"); }; assert_eq!(*token, format!("{:x}", md5::compute(format!("sesame{salt}")))); } fn query(c: &Client) -> Vec<(String, String)> { c.endpoint_url("ping", &[]) .unwrap() .query_pairs() .map(|(k, v)| (k.into_owned(), v.into_owned())) .collect() } #[test] fn token_auth_sends_token_and_salt_only() { let c = Client::new( "http://x", "u", Auth::Token { salt: "s1".into(), token: "t1".into(), }, ); let q = query(&c); assert!(q.contains(&("t".into(), "t1".into()))); assert!(q.contains(&("s".into(), "s1".into()))); assert!(!q.iter().any(|(k, _)| k == "p")); } #[test] fn password_auth_sends_the_password_hex_encoded() { let c = Client::new("http://x", "u", Auth::Password("sesame".into())); let q = query(&c); assert!(q.contains(&("u".into(), "u".into()))); assert!(q.contains(&("p".into(), "enc:736573616d65".into()))); assert!(!q.iter().any(|(k, _)| k == "t" || k == "s")); } #[test] fn server_errors_keep_their_code() { // As Nextcloud Music answers a token login. let body = serde_json::json!({"subsonic-response": { "error": {"code": 41, "message": "Token-based authentication not supported"}, "status": "failed", "version": "1.16.1", "type": "nextcloud music", "openSubsonic": true }}); let e = unwrap_response("ping", body).unwrap_err(); let api = api_error(&e).expect("an ApiError"); assert_eq!(api.code, 41); assert_eq!(api.server.as_deref(), Some("nextcloud music")); assert_eq!(e.to_string(), "Token-based authentication not supported"); let ok = serde_json::json!({"subsonic-response": {"status": "ok", "version": "1.16.1"}}); assert!(unwrap_response("ping", ok).is_ok()); } /// A one-request-per-connection HTTP server on loopback that answers like /// Nextcloud Music: tokens refused, the password "sesame" accepted. fn fake_tokenless_server() -> String { use std::io::{BufRead, BufReader, Write}; let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap(); let addr = listener.local_addr().unwrap(); std::thread::spawn(move || { for stream in listener.incoming() { let Ok(mut stream) = stream else { continue }; let mut line = String::new(); let mut reader = BufReader::new(stream.try_clone().unwrap()); let _ = reader.read_line(&mut line); let error = |code: i64, msg: &str| { format!( r#"{{"subsonic-response":{{"status":"failed","error":{{"code":{code},"message":"{msg}"}}}}}}"# ) }; let body = if line.contains("t=") { error(41, "Token-based authentication not supported") } else if line.contains("p=enc%3A736573616d65") || line.contains("p=enc:736573616d65") { r#"{"subsonic-response":{"status":"ok"}}"#.to_string() } else { error(40, "Wrong username or password") }; let _ = write!( stream, "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{body}", body.len() ); } }); format!("http://{addr}") } #[tokio::test] async fn login_falls_back_to_the_password_when_tokens_are_refused() { let base = fake_tokenless_server(); let c = Client::login(&base, "u", "sesame").await.unwrap(); assert_eq!(*c.auth(), Auth::Password("sesame".into())); let Err(e) = Client::login(&base, "u", "wrong").await else { panic!("a wrong password logged in"); }; assert_eq!(api_error(&e).map(|a| a.code), Some(WRONG_CREDENTIALS)); } }