Multiple clients via features

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: check
-          args: --all-targets
+          args: --all-targets --features=cli,env-file
 
   cross-compile:
     name: Cross Compile
@@ -35,6 +35,9 @@ jobs:
           - aarch64-unknown-linux-gnu
           - arm-unknown-linux-gnueabihf
           - armv7-unknown-linux-gnueabihf
+        client:
+          - client-ureq,ureq-rustls-tls
+          - client-reqwest,reqwest-rustls-tls
     steps:
       - name: Checkout sources
         uses: actions/checkout@v2
@@ -54,11 +57,17 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: build
-          args: --target ${{ matrix.target }} --no-default-features --features "rustls-tls"
+          args: --target ${{ matrix.target }} --no-default-features --features=cli,env-file,${{ matrix.client }}
+
 
   test:
     name: Test Suite
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        client:
+          - client-ureq,ureq-rustls-tls
+          - client-reqwest,reqwest-rustls-tls
     steps:
       - name: Checkout sources
         uses: actions/checkout@v2
@@ -74,11 +83,16 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --features env-file
+          args: --no-default-features --features=cli,env-file,${{ matrix.client }}
 
   lints:
     name: Lints
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        client:
+          - client-ureq,ureq-rustls-tls
+          - client-reqwest,reqwest-rustls-tls
     steps:
       - name: Checkout sources
         uses: actions/checkout@v2
@@ -101,4 +115,4 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: clippy
-          args: -- -D warnings
+          args: --no-default-features --features=cli,env-file,${{ matrix.client }} -- -D warnings

CHANGELOG.md

@@ -1,23 +1,44 @@
 ## 0.11 (unreleased)
+This release contains *lots* of breaking changes. These were necessary to continue Rspotify's development, and no more versions like this should happen again. Lots of internal code was rewritten to make Rspotify more flexible, performant and easier to use. Sorry for the inconvenience!
+
+If we missed any change or there's something you'd like to discuss about this version, please open a new issue and let us know.
 
 - Rewritten documentation in hopes that it's easier to get started with Rspotify.
 - Reduced the number of examples. Instead of having an example for each endpoint, which is repetitive and unhelpful for newcomers, some real-life examples are now included. If you'd like to add your own example, please do! ([#113](https://github.com/ramsayleung/rspotify/pull/113))
 - Add `add_item_to_queue` endpoint.
-- Fix typo in `transfer_playback`: `device_id` to `device_ids`.
-- Fix race condition when using a single client from multiple threads (see [#114](https://github.com/ramsayleung/rspotify/pull/114) for more information).
+- Fix race condition when using a single client from multiple threads ([#114](https://github.com/ramsayleung/rspotify/pull/114)).
 - Rspotify should now be considerably lighter and less bloated ([discussion in #108](https://github.com/ramsayleung/rspotify/issues/108)):
-  + Remove unused dependencies: `base64`, `env_logger`, `derive_builder`, `random`, `url`. <!-- NOTE: derive_builder might not be removed after all -->
+  + Remove unused dependencies: `base64`, `env_logger`, `random`, `url`.
   + Remove `itertools` dependency by using the standard library.
   + Remove `rand` in place of `getrandom` to [reduce total dependencies and compile times](https://github.com/ramsayleung/rspotify/issues/108#issuecomment-673587185).
-  + `webbrowser` and access to functions that use it (`util::get_token`, `util::get_token_without_cache` and `util::request_token`) can be disabled for the non-CLI applications with the `browser` feature. It's still enabled by default due to [its frequent usage](https://github.com/ramsayleung/rspotify/pull/110#issuecomment-674410604).
   + Cleanup, reduced repetitive code and boilerplate internally in several places ([#117](https://github.com/ramsayleung/rspotify/pull/117), [#113](https://github.com/ramsayleung/rspotify/pull/113), [#107](https://github.com/ramsayleung/rspotify/pull/107), [#106](https://github.com/ramsayleung/rspotify/pull/106)).
 - Updated dependencies to the latest versions, integrated Dependabot to keep track of them ([#105](https://github.com/ramsayleung/rspotify/pull/105), [#111](https://github.com/ramsayleung/rspotify/pull/111)).
 
 **Breaking changes:**
-- `dotenv` support is now optional. You can enable it with the `env-file` feature to have the same behavior as before ([#108](https://github.com/ramsayleung/rspotify/issues/108)).
+- `SpotifyClientCredentials` has been renamed to `Credentials` ([#129](https://github.com/ramsayleung/rspotify/pull/129)), and its members `client_id` and `client_secret` to `id` and `secret`, respectively.
+- `TokenInfo` has been renamed to `Token`. It no longer has the `token_type` member, as it's always `Bearer` for now ([#129](https://github.com/ramsayleung/rspotify/pull/129)).
+- `SpotifyOAuth` has been renamed to `OAuth`. It only contains the necessary parameters for OAuth authorization instead of repeating the items from `Credentials` and `Spotify`, so `client_id`, `client_secret` and `cache_path` are no longer in `OAuth` ([#129](https://github.com/ramsayleung/rspotify/pull/129)).
+- `TokenBuilder` and `OAuthBuilder` will only read from environment variables when `from_env` is used, instead of `default`.
+- `dotenv` support is now optional. You can enable it with the `env-file` feature to have the same behavior as before ([#108](https://github.com/ramsayleung/rspotify/issues/108)). It may be used with `from_env` as well.
 - Renamed environmental variables to `RSPOTIFY_CLIENT_ID`, `RSPOTIFY_CLIENT_SECRET` and `RSPOTIFY_REDIRECT_URI` to avoid name collisions with other libraries that use OAuth2 ([#118](https://github.com/ramsayleung/rspotify/issues/118)).
+- All fallible calls in the client return a `ClientResult` rather than using `failure`, which is equivalent to a `Result<T, ClientError>`.
+- `ApiError` is now `APIError` for consistency.
+- A real builder pattern is used now. For example, `Token` is constructed now with `TokenBuilder::default().access_token("...").build().unwrap()`. This has been applied to `Spotify`, `OAuth`, `Token` and `Credentials` ([#129](https://github.com/ramsayleung/rspotify/pull/129)).
+- The `blocking` module has been removed, since Rspotify is able to use multiple HTTP clients now. `reqwest` and `ureq` are currently supported, meaning that you can still use blocking code by enabling the `client-ureq` feature and a TLS like `ureq-rustls-tls`. Read the docs for more information ([#129](https://github.com/ramsayleung/rspotify/pull/129)).
+- The authentication process has been completely rewritten in order to make it more performant and robust. Please read the docs to learn more about how that works now ([#129](https://github.com/ramsayleung/rspotify/pull/129)). These are the main changes:
+    + `TokenInfo::get_cached_token` is now `TokenBuilder::from_cache` and `Spotify::read_token_cache` (using the internal cache path). Instead of panicking, the resulting `TokenBuilder` may be empty (and `build` will fail).
+    + `Spotify::save_token_info` is now `Token::write_cache` and `Spotify::write_token_cache`. The latter uses the client's set cache path for the write. These functions also now return `ClientResult` instead of panicking.
+    + `Spotify::is_token_expired` is now `Token::is_expired`.
+    + `SpotifyOAuth2::get_authorize_url` is now `Spotify::get_authorize_url`, and it returns `ClientResult<String>` instead of panicking.
+    + `SpotifyOAuth2::refresh_access_token[_without_cache]` are now `Spotify::refresh_user_token[_with_cache]`. It returns `ClientResult<()>`, and the resulting token will be saved internally instead of returned.
+    + `SpotifyOAuth2::request_client_token[_without_cache]` are now `Spotify::request_client_token[_with_cache]`. It returns `ClientResult<()>`, and the resulting token will be saved internally instead of returned.
+    + `SpotifyOAuth2::get_access_token[_without_cache]` are now `Spotify::request_user_token[_with_cache]`. It returns `ClientResult<()>`, and the resulting token will be saved internally instead of returned.
+    + `get_token[_without_cache]` is now `Spotify::prompt_for_user_token[_without_cache]`. It returns `ClientResult<()>`, and the resulting token will be saved internally instead of returned.
+- CLI-exclusive functions and  are now optional under the `cli` feature:
+    + `Spotify::prompt_for_user_token[_without_cache]`
+    + The `ClientError::CLI` variant, for whenever user interaction goes wrong
 - Fix typo in `user_playlist_remove_specific_occurrenes_of_tracks`, now it's `user_playlist_remove_specific_occurrences_of_tracks`.
-- All fallible calls in the client return a `ClientError` rather than using `failure`.
+- Fix typo in `transfer_playback`: `device_id` to `device_ids`.
 - Changed type of `track` in `PlayHistory` to `FullTrack` ([#139](https://github.com/ramsayleung/rspotify/pull/139)).
 
 ## 0.10 (2020/07/01)

Cargo.toml

@@ -11,81 +11,103 @@ keywords = ["spotify","api"]
 edition = "2018"
 
 [dependencies]
+# Temporary until https://github.com/rust-lang/rfcs/issues/2739, for
+# `maybe_async`.
+async-trait = "0.1.40"
+base64 = "0.12.3"
 chrono = { version = "0.4.13", features = ["serde", "rustc-serialize"] }
+derive_builder = "0.9.0"
 dotenv = { version = "0.15.0", optional = true }
+getrandom = "0.2.0"
 lazy_static = "1.4.0"
 log = "0.4.11"
-percent-encoding = "2.1.0"
-getrandom = "0.2.0"
-reqwest = { version = "0.10.7", features = ["json", "socks"], default-features = false }
+maybe-async = "0.2.1"
+reqwest = { version = "0.10.7", default-features = false, features = ["json", "socks"], optional = true }
 serde = { version = "1.0.115", features = ["derive"] }
 serde_json = "1.0.57"
-webbrowser = { version = "0.5.5", optional = true }
 thiserror = "1.0.20"
+ureq = { version = "1.4.1", default-features = false, features = ["json", "cookies"], optional = true }
+url = "2.1.1"
+webbrowser = { version = "0.5.5", optional = true }
 
 [dev-dependencies]
-async_once = { version = "0.1.0", features = ["tokio"] }
+env_logger = "0.7.1"
 tokio = { version = "0.2.22", features = ["full"] }
 futures = "0.3.5"
 
 [features]
-default = ["reqwest/default-tls", "browser"]
+default = ["client-reqwest", "reqwest-default-tls"]
+cli = ["webbrowser"]
 env-file = ["dotenv"]
-browser = ["webbrowser"]
-blocking = ["reqwest/default-tls", "reqwest/blocking"]
+
+# Available clients. By default they don't include a TLS so that it can be
+# configured.
+client-ureq = ["ureq", "__sync"]
+client-reqwest = ["reqwest", "__async"]
+
 # Passing the TLS features to reqwest.
-native-tls = ["reqwest/native-tls"]
-native-tls-blocking = ["reqwest/native-tls", "reqwest/blocking"]
-native-tls-vendored = ["reqwest/native-tls-vendored"]
-native-tls-vendored-blocking = ["reqwest/native-tls-vendored", "reqwest/blocking"]
-rustls-tls = ["reqwest/rustls-tls"]
-rustls-tls-blocking = ["reqwest/rustls-tls", "reqwest/blocking"]
+reqwest-default-tls = ["reqwest/default-tls"]
+reqwest-rustls-tls = ["reqwest/rustls-tls"]
+reqwest-native-tls = ["reqwest/native-tls"]
+reqwest-native-tls-vendored = ["reqwest/native-tls-vendored"]
+# Same for ureq.
+ureq-rustls-tls = ["ureq/tls"]
+ureq-native-tls = ["ureq/native-tls"]
+
+# Internal features for checking async or sync compilation
+__async = []
+__sync = ["maybe-async/is_sync"]
 
 [package.metadata.docs.rs]
-# Also documenting the blocking module
-features = ["blocking"]
+# Also documenting the CLI methods
+features = ["cli"]
 
 [[example]]
 name = "album"
-required-features = ["env-file"]
+required-features = ["env-file", "cli", "client-reqwest"]
 path = "examples/album.rs"
 
 [[example]]
 name = "current_user_recently_played"
-required-features = ["env-file"]
+required-features = ["env-file", "cli", "client-reqwest"]
 path = "examples/current_user_recently_played.rs"
 
+[[example]]
+name = "oauth_tokens"
+required-features = ["env-file", "cli", "client-reqwest"]
+path = "examples/oauth_tokens.rs"
+
 [[example]]
 name = "track"
-required-features = ["env-file"]
+required-features = ["env-file", "cli", "client-reqwest"]
 path = "examples/track.rs"
 
 [[example]]
 name = "tracks"
-required-features = ["env-file"]
+required-features = ["env-file", "cli", "client-reqwest"]
 path = "examples/tracks.rs"
 
 [[example]]
 name = "with_refresh_token"
-required-features = ["env-file"]
+required-features = ["env-file", "cli", "client-reqwest"]
 path = "examples/with_refresh_token.rs"
 
 [[example]]
 name = "device"
-required-features = ["env-file", "blocking"]
-path = "examples/blocking/device.rs"
+required-features = ["env-file", "cli", "client-ureq"]
+path = "examples/ureq/device.rs"
 
 [[example]]
 name = "me"
-required-features = ["env-file", "blocking"]
-path = "examples/blocking/me.rs"
+required-features = ["env-file", "cli", "client-ureq"]
+path = "examples/ureq/me.rs"
 
 [[example]]
-name = "blocking_search"
-required-features = ["env-file", "blocking"]
-path = "examples/blocking/search.rs"
+name = "search"
+required-features = ["env-file", "cli", "client-ureq"]
+path = "examples/ureq/search.rs"
 
 [[example]]
 name = "seek_track"
-required-features = ["env-file", "blocking"]
-path = "examples/blocking/seek_track.rs"
+required-features = ["env-file", "cli", "client-ureq"]
+path = "examples/ureq/seek_track.rs"

README.md

@@ -17,6 +17,30 @@ Please see the [changelog](./CHANGELOG.md) for a release history and indications
 
 If you find any problems or have suggestions about this crate, please submit an issue. Moreover, any pull request, code review and feedback are welcome.
 
+## Building
+
+Rspotify uses [`maybe_async`](https://docs.rs/maybe-async/0.2.0/maybe_async/) to switch between async and blocking clients, which is triggered inside `Cargo.toml`. So that must be taken into account when building `rspotify`. Read the Configuration section in the docs for more information about how to build with custom TLS implementations, and more.
+
+`client-reqwest` is used by default. It should be as easy as
+
+```sh
+$ cargo build
+```
+
+`client-ureq` is also available as the `blocking` interface, which compiles Rspotify with [`ureq`](https://docs.rs/ureq/) (a TLS has to be specified as well):
+
+```sh
+$ cargo build --no-default-features --features client-ureq,ureq-rustls-tls
+```
+
+Notice that you can't build `rspotify` with all features like this:
+
+```sh
+$ cargo build --all-features
+```
+
+Because in order to switch between clients, the different clients have to implement the same base trait in [src/http/mod.rs](https://github.com/ramsayleung/rspotify/blob/master/src/http/mod.rs), so if you build with all features, you'll get `duplicate definitions` error. As every coin has two sides, you can only have one side at a time, not all sides of it.
+
 ## License
 
 [MIT](./LICENSE)

examples/album.rs

@@ -1,22 +1,41 @@
-use rspotify::client::Spotify;
-use rspotify::oauth2::SpotifyClientCredentials;
+use rspotify::client::SpotifyBuilder;
+use rspotify::oauth2::CredentialsBuilder;
 
 #[tokio::main]
 async fn main() {
-    // Set client_id and client_secret in .env file or
+    // You can use any logger for debugging.
+    env_logger::init();
+
+    // Set RSPOTIFY_CLIENT_ID, RSPOTIFY_CLIENT_SECRET and
+    // RSPOTIFY_REDIRECT_URI in an .env file or export them manually:
+    //
     // export RSPOTIFY_CLIENT_ID="your client_id"
     // export RSPOTIFY_CLIENT_SECRET="secret"
-    let client_credential = SpotifyClientCredentials::default().build();
-
-    // Or set client_id and client_secret explictly
-    // let client_credential = SpotifyClientCredentials::default()
+    //
+    // These will then be read with `from_env`.
+    //
+    // Otherwise, set client_id and client_secret explictly:
+    //
+    // let creds = CredentialsBuilder::default()
     //     .client_id("this-is-my-client-id")
     //     .client_secret("this-is-my-client-secret")
-    //     .build();
-    let spotify = Spotify::default()
-        .client_credentials_manager(client_credential)
-        .build();
+    //     .build()
+    //     .unwrap();
+    let creds = CredentialsBuilder::from_env().build().unwrap();
+
+    let mut spotify = SpotifyBuilder::default()
+        .credentials(creds)
+        .build()
+        .unwrap();
+
+    // Obtaining the access token. Requires to be mutable because the internal
+    // token will be modified. We don't need OAuth for this specific endpoint,
+    // so `...` is used instead of `prompt_for_user_token`.
+    spotify.request_client_token().await.unwrap();
+
+    // Running the requests
     let birdy_uri = "spotify:album:0sNOF9WDwhWunNAHPD3Baj";
     let albums = spotify.album(birdy_uri).await;
-    println!("{:?}", albums);
+
+    println!("Response: {:#?}", albums);
 }