refactor: Introduce SpotifyUri struct

Contributes to #1266

Introduces a new `SpotifyUri` struct which is layered on top of the
existing `SpotifyId`, but has the capability to support URIs that do
not confirm to the canonical base62 encoded format. This allows it to
describe URIs like `spotify:local`, `spotify:genre` and others that
`SpotifyId` cannot represent.

Changed the internal player state to use these URIs as much as possible,
such that the player could in the future accept a URI of the type
`spotify:local`, as a means of laying the groundwork for local file
support.

Author: SapiensAnatis

CHANGELOG.md

@@ -9,10 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- [playback] Add `load_uri()` function to load a `SpotifyUri`
+- [playback] Add `preload_uri()` function to load a `SpotifyUri`
+- [core] Add `SpotifyUri` type to represent more types of URI than `SpotifyId` can
+
 ### Changed
 
+- [connect] Changed `track_id` parameter in `SpircTask::handle_unavailable` from `SpotifyId` to `&SpotifyUri` (breaking)
+- [connect] Changed return type of `ConnectState::preview_next_track` from `Option<SpotifyId>` to
+  `Option<SpotifyUri>` (breaking)
+- [connect] Changed type of `id` parameter `ConnectState::mark_unavailable` from `SpotifyId` to `&SpotifyUri` (breaking)
+- [playback] Changed type of `SpotifyId` fields in `PlayerEvent` members to `SpotifyUri` (breaking)
+- [metadata] Changed arguments for `Metadata` trait from `&SpotifyId` to `&SpotifyUri` (breaking)
+
 ### Deprecated
 
+- [player] `load()` function marked for deprecation
+- [player] `preload()` function marked for deprecation
+
 ### Removed
 
 ### Fixed

connect/src/spirc.rs

@@ -2,7 +2,7 @@ use crate::{
     LoadContextOptions, LoadRequestOptions, PlayContext,
     context_resolver::{ContextAction, ContextResolver, ResolveContext},
     core::{
-        Error, Session, SpotifyId,
+        Error, Session, SpotifyUri,
         authentication::Credentials,
         dealer::{
             manager::{BoxedStream, BoxedStreamResult, Reply, RequestReply},
@@ -778,7 +778,7 @@ impl SpircTask {
                 return Ok(());
             }
             PlayerEvent::Unavailable { track_id, .. } => {
-                self.handle_unavailable(track_id)?;
+                self.handle_unavailable(&track_id)?;
                 if self.connect_state.current_track(|t| &t.uri) == &track_id.to_uri()? {
                     self.handle_next(None)?
                 }
@@ -1494,12 +1494,12 @@ impl SpircTask {
         }
 
         if let Some(track_id) = self.connect_state.preview_next_track() {
-            self.player.preload(track_id);
+            self.player.preload_uri(track_id);
         }
     }
 
     // Mark unavailable tracks so we can skip them later
-    fn handle_unavailable(&mut self, track_id: SpotifyId) -> Result<(), Error> {
+    fn handle_unavailable(&mut self, track_id: &SpotifyUri) -> Result<(), Error> {
         self.connect_state.mark_unavailable(track_id)?;
         self.handle_preload_next_track();
 
@@ -1704,8 +1704,8 @@ impl SpircTask {
         }
 
         let current_uri = self.connect_state.current_track(|t| &t.uri);
-        let id = SpotifyId::from_uri(current_uri)?;
-        self.player.load(id, start_playing, position_ms);
+        let id = SpotifyUri::from_uri(current_uri)?;
+        self.player.load_uri(id, start_playing, position_ms);
 
         self.connect_state
             .update_position(position_ms, self.now_ms());

connect/src/state/context.rs

@@ -1,5 +1,5 @@
 use crate::{
-    core::{Error, SpotifyId},
+    core::{Error, SpotifyUri},
     protocol::{
         context::Context,
         context_page::ContextPage,
@@ -14,6 +14,7 @@ use crate::{
         provider::{IsProvider, Provider},
     },
 };
+use librespot_core::spotify_id::SpotifyItemType;
 use protobuf::MessageField;
 use std::collections::HashMap;
 use uuid::Uuid;
@@ -444,8 +445,8 @@ impl ConnectState {
             (Some(uri), _) if uri.contains(['?', '%']) => {
                 Err(StateError::InvalidTrackUri(Some(uri.clone())))?
             }
-            (Some(uri), _) if !uri.is_empty() => SpotifyId::from_uri(uri)?,
-            (_, Some(gid)) if !gid.is_empty() => SpotifyId::from_raw(gid)?,
+            (Some(uri), _) if !uri.is_empty() => SpotifyUri::from_uri(uri)?,
+            (_, Some(gid)) if !gid.is_empty() => SpotifyUri::from_raw(gid, SpotifyItemType::Track)?,
             _ => Err(StateError::InvalidTrackUri(None))?,
         };
 

connect/src/state/tracks.rs

@@ -1,5 +1,5 @@
 use crate::{
-    core::{Error, SpotifyId},
+    core::{Error, SpotifyUri},
     protocol::player::ProvidedTrack,
     state::{
         ConnectState, SPOTIFY_MAX_NEXT_TRACKS_SIZE, SPOTIFY_MAX_PREV_TRACKS_SIZE, StateError,
@@ -348,14 +348,14 @@ impl<'ct> ConnectState {
         Ok(())
     }
 
-    pub fn preview_next_track(&mut self) -> Option<SpotifyId> {
+    pub fn preview_next_track(&mut self) -> Option<SpotifyUri> {
         let next = if self.repeat_track() {
             self.current_track(|t| &t.uri)
         } else {
             &self.next_tracks().first()?.uri
         };
 
-        SpotifyId::from_uri(next).ok()
+        SpotifyUri::from_uri(next).ok()
     }
 
     pub fn has_next_tracks(&self, min: Option<usize>) -> bool {
@@ -377,7 +377,7 @@ impl<'ct> ConnectState {
         prev
     }
 
-    pub fn mark_unavailable(&mut self, id: SpotifyId) -> Result<(), Error> {
+    pub fn mark_unavailable(&mut self, id: &SpotifyUri) -> Result<(), Error> {
         let uri = id.to_uri()?;
 
         debug!("marking {uri} as unavailable");

core/src/lib.rs

@@ -32,6 +32,7 @@ mod socket;
 #[allow(dead_code)]
 pub mod spclient;
 pub mod spotify_id;
+pub mod spotify_uri;
 pub mod token;
 #[doc(hidden)]
 pub mod util;
@@ -42,3 +43,4 @@ pub use error::Error;
 pub use file_id::FileId;
 pub use session::Session;
 pub use spotify_id::SpotifyId;
+pub use spotify_uri::SpotifyUri;

core/src/spclient.rs

@@ -5,7 +5,7 @@ use std::{
 
 use crate::config::{OS, os_version};
 use crate::{
-    Error, FileId, SpotifyId,
+    Error, FileId, SpotifyId, SpotifyUri,
     apresolve::SocketAddress,
     config::SessionConfig,
     error::ErrorKind,
@@ -676,10 +676,10 @@ impl SpClient {
             .await
     }
 
-    pub async fn get_radio_for_track(&self, track_id: &SpotifyId) -> SpClientResult {
+    pub async fn get_radio_for_track(&self, track_uri: &SpotifyUri) -> SpClientResult {
         let endpoint = format!(
             "/inspiredby-mix/v2/seed_to_playlist/{}?response-format=json",
-            track_id.to_uri()?
+            track_uri.to_uri()?
         );
 
         self.request_as_json(&Method::GET, &endpoint, None, None)