Merge pull request #152 from adamint/suspending_requests

Suspending requests

Author: adamint

src/commonMain/kotlin/com.adamratzman.spotify/Builder.kt

@@ -6,7 +6,9 @@ import com.adamratzman.spotify.http.HttpRequestMethod
 import com.adamratzman.spotify.models.SpotifyAuthenticationException
 import com.adamratzman.spotify.models.Token
 import com.adamratzman.spotify.models.serialization.toObject
-import kotlinx.coroutines.GlobalScope
+import com.adamratzman.spotify.utils.runBlocking
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.launch
 
@@ -97,7 +99,7 @@ class SpotifyApiBuilder(
      * Create a [SpotifyApi] instance with the given [SpotifyApiBuilder] parameters and the type -
      * [AuthorizationType.CLIENT] for client authentication, or otherwise [AuthorizationType.APPLICATION]
      */
-    fun build(type: AuthorizationType): SpotifyApi {
+    fun build(type: AuthorizationType): SpotifyApi<*, *> {
         return if (type == AuthorizationType.CLIENT) buildClient()
         else buildCredentialed()
     }
@@ -110,7 +112,7 @@ class SpotifyApiBuilder(
     /**
      * Create a new [SpotifyAppApi] that only has access to *public* endpoints and data
      */
-    fun buildCredentialed(): SpotifyApi = spotifyAppApi {
+    fun buildCredentialed(): SpotifyAppApi = spotifyAppApi {
         credentials {
             clientId = this@SpotifyApiBuilder.clientId
             clientSecret = this@SpotifyApiBuilder.clientSecret
@@ -139,7 +141,7 @@ enum class AuthorizationType {
     APPLICATION;
 }
 
-interface ISpotifyApiBuilder {
+interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>> {
     var credentials: SpotifyCredentials
     var authorization: SpotifyUserAuthorization
     var options: SpotifyApiOptions
@@ -192,27 +194,35 @@ interface ISpotifyApiBuilder {
     }
 
     fun options(options: SpotifyApiOptions) = apply { this.options = options }
-}
 
-interface ISpotifyClientApiBuilder : ISpotifyApiBuilder {
     /**
-     * Build the client api by providing an authorization code, token string, or token object. Only one of the following
-     * needs to be provided
+     * Build the [T] by provided information
+     */
+    suspend fun suspendBuild(): T
+
+    /**
+     * Build the [T] by provided information
+     */
+    fun build(): T = runBlocking { suspendBuild() }
+
+    /**
+     * Build the [T] by provided information
      *
-     * @param authorizationCode Spotify authorization code retrieved after authentication
-     * @param tokenString Spotify authorization token
-     * @param token [Token] object (useful if you already have exchanged an authorization code yourself
+     * Provide a consumer object to be executed after the api has been successfully built
      */
-    fun build(): SpotifyClientApi
+    fun buildAsyncAt(scope: CoroutineScope, consumer: (T) -> Unit): Job = with(scope) { buildAsync(consumer) }
 
     /**
-     * Build the client api using a provided authorization code, token string, or token object (only one of which
-     * is necessary)
+     * Build the [T] by provided information
      *
-     * Provide a consumer object to be executed after the client has been successfully built
+     * Provide a consumer object to be executed after the api has been successfully built
      */
-    suspend fun buildAsync(consumer: (SpotifyClientApi) -> Unit): Job
+    fun CoroutineScope.buildAsync(consumer: (T) -> Unit): Job = launch {
+        consumer(suspendBuild())
+    }
+}
 
+interface ISpotifyClientApiBuilder : ISpotifyApiBuilder<SpotifyClientApi, SpotifyClientApiBuilder> {
     /**
      * Create a Spotify authorization URL from which API access can be obtained
      *
@@ -232,47 +242,49 @@ class SpotifyClientApiBuilder(
         return getAuthUrlFull(*scopes, clientId = credentials.clientId!!, redirectUri = credentials.redirectUri!!)
     }
 
-    override fun build(): SpotifyClientApi {
+    override suspend fun suspendBuild(): SpotifyClientApi {
         val clientId = credentials.clientId
         val clientSecret = credentials.clientSecret
         val redirectUri = credentials.redirectUri
 
         require((clientId != null && clientSecret != null && redirectUri != null) || authorization.token != null || authorization.tokenString != null) { "You need to specify a valid clientId, clientSecret, and redirectUri in the credentials block!" }
         return when {
             authorization.authorizationCode != null -> try {
-                require(clientId != null && clientSecret != null && redirectUri != null) { "You need to specify a valid clientId, clientSecret, and redirectUri in the credentials block!" }
-
-                val response = executeTokenRequest(
-                    HttpConnection(
-                        "https://accounts.spotify.com/api/token",
-                        HttpRequestMethod.POST,
-                        mapOf(
-                            "grant_type" to "authorization_code",
-                            "code" to authorization.authorizationCode,
-                            "redirect_uri" to redirectUri
-                        ),
-                        null,
-                        "application/x-www-form-urlencoded",
-                        listOf(),
-                        null
-                    ), clientId, clientSecret
-                )
-
-                SpotifyClientApi(
-                    clientId,
-                    clientSecret,
-                    redirectUri,
-                    response.body.toObject(Token.serializer(), null),
-                    options.useCache,
-                    options.cacheLimit,
-                    options.automaticRefresh,
-                    options.retryWhenRateLimited,
-                    options.enableLogger,
-                    options.testTokenValidity
-                )
-            } catch (e: Exception) {
-                throw SpotifyAuthenticationException("Invalid credentials provided in the login process", e)
-            }
+                    require(clientId != null && clientSecret != null && redirectUri != null) { "You need to specify a valid clientId, clientSecret, and redirectUri in the credentials block!" }
+
+                    val response = executeTokenRequest(
+                        HttpConnection(
+                            "https://accounts.spotify.com/api/token",
+                            HttpRequestMethod.POST,
+                            mapOf(
+                                "grant_type" to "authorization_code",
+                                "code" to authorization.authorizationCode,
+                                "redirect_uri" to redirectUri
+                            ),
+                            null,
+                            "application/x-www-form-urlencoded",
+                            listOf(),
+                            null
+                        ), clientId, clientSecret
+                    )
+
+                    SpotifyClientApi(
+                        clientId,
+                        clientSecret,
+                        redirectUri,
+                        response.body.toObject(Token.serializer(), null),
+                        options.useCache,
+                        options.cacheLimit,
+                        options.automaticRefresh,
+                        options.retryWhenRateLimited,
+                        options.enableLogger,
+                        options.testTokenValidity
+                    )
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    throw SpotifyAuthenticationException("Invalid credentials provided in the login process", e)
+                }
             authorization.token != null -> SpotifyClientApi(
                 clientId,
                 clientSecret,
@@ -309,49 +321,19 @@ class SpotifyClientApiBuilder(
             )
         }
     }
-
-    override suspend fun buildAsync(consumer: (SpotifyClientApi) -> Unit) = GlobalScope.launch {
-        consumer(build())
-    }
 }
 
-interface ISpotifyAppApiBuilder : ISpotifyApiBuilder {
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     *
-     * @param consumer Consumer to be executed after the api has been successfully built
-     */
-    fun buildAsync(consumer: (SpotifyApi) -> Unit): Job
-
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     */
-    fun build(): SpotifyApi
-}
+interface ISpotifyAppApiBuilder : ISpotifyApiBuilder<SpotifyAppApi, SpotifyAppApiBuilder>
 
 class SpotifyAppApiBuilder(
     override var credentials: SpotifyCredentials = SpotifyCredentialsBuilder().build(),
     override var authorization: SpotifyUserAuthorization = SpotifyUserAuthorizationBuilder().build(),
     override var options: SpotifyApiOptions = SpotifyApiOptionsBuilder().build()
 ) : ISpotifyAppApiBuilder {
-    /**
-     * Create a new [SpotifyAppApi] that only has access to *public* endpoints and data
-     */
-    fun buildPublic() = build()
-
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     *
-     * Provide a consumer object to be executed after the api has been successfully built
-     */
-    override fun buildAsync(consumer: (SpotifyApi) -> Unit) = GlobalScope.launch {
-        consumer(build())
-    }
-
     /**
      * Build a public [SpotifyAppApi] using the provided credentials
      */
-    override fun build(): SpotifyApi {
+    override suspend fun suspendBuild(): SpotifyAppApi {
         val clientId = credentials.clientId
         val clientSecret = credentials.clientSecret
         require((clientId != null && clientSecret != null) || authorization.token != null || authorization.tokenString != null) { "You didn't specify a client id or client secret in the credentials block!" }
@@ -399,6 +381,8 @@ class SpotifyAppApiBuilder(
                     options.enableLogger,
                     options.testTokenValidity
                 )
+            } catch (e: CancellationException) {
+                throw e
             } catch (e: Exception) {
                 throw SpotifyAuthenticationException("Invalid credentials provided in the login process", e)
             }

src/commonMain/kotlin/com.adamratzman.spotify/SpotifyApi.kt

@@ -26,7 +26,11 @@ import com.adamratzman.spotify.models.SpotifyAuthenticationException
 import com.adamratzman.spotify.models.Token
 import com.adamratzman.spotify.models.TokenValidityResponse
 import com.adamratzman.spotify.models.serialization.toObject
+import com.adamratzman.spotify.utils.runBlocking
 import com.adamratzman.spotify.utils.toList
+import kotlin.coroutines.CoroutineContext
+import kotlin.jvm.JvmOverloads
+import kotlinx.coroutines.Dispatchers
 
 internal const val base = "https://api.spotify.com/v1"
 
@@ -51,7 +55,7 @@ internal const val base = "https://api.spotify.com/v1"
  * @property logger The Spotify event logger
  *
  */
-abstract class SpotifyApi internal constructor(
+sealed class SpotifyApi<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>(
     val clientId: String?,
     val clientSecret: String?,
     var token: Token,
@@ -103,7 +107,9 @@ abstract class SpotifyApi internal constructor(
      * @return The old access token if refresh was successful
      * @throws BadRequestException if refresh fails
      */
-    abstract fun refreshToken(): Token
+    fun refreshToken(): Token = runBlocking {
+        suspendRefreshToken()
+    }
 
     /**
      * A list of all endpoints included in this api type
@@ -123,7 +129,7 @@ abstract class SpotifyApi internal constructor(
     /**
      * Return a new [SpotifyApiBuilderDsl] with the parameters provided to this api instance
      */
-    abstract fun getApiBuilderDsl(): ISpotifyApiBuilder
+    abstract fun getApiBuilderDsl(): B
 
     private fun clearCaches(vararg endpoints: SpotifyEndpoint) {
         endpoints.forEach { it.cache.clear() }
@@ -160,20 +166,35 @@ abstract class SpotifyApi internal constructor(
      *
      * @return [TokenValidityResponse] containing whether this token is valid, and if not, an Exception explaining why
      */
-    fun isTokenValid(makeTestRequest: Boolean = true): TokenValidityResponse {
+    @JvmOverloads
+    fun isTokenValid(makeTestRequest: Boolean = true): TokenValidityResponse = runBlocking {
+        suspendIsTokenValid(makeTestRequest)
+    }
+
+    @JvmOverloads
+    suspend fun suspendIsTokenValid(makeTestRequest: Boolean = true, context: CoroutineContext = Dispatchers.Default): TokenValidityResponse {
         if (token.shouldRefresh()) return TokenValidityResponse(
             false,
             SpotifyAuthenticationException("Token needs to be refreshed (is it expired?)")
         )
         if (!makeTestRequest) return TokenValidityResponse(true, null)
 
         return try {
-            browse.getAvailableGenreSeeds().complete()
+            browse.getAvailableGenreSeeds().suspendComplete(context)
             TokenValidityResponse(true, null)
         } catch (e: Exception) {
             TokenValidityResponse(false, e)
         }
     }
+
+    /**
+     * If the method used to create the [token] supports token refresh and
+     * the information in [token] is accurate, attempt to refresh the token
+     *
+     * @return The old access token if refresh was successful
+     * @throws BadRequestException if refresh fails
+     */
+    abstract suspend fun suspendRefreshToken(): Token
 }
 
 /**
@@ -190,7 +211,7 @@ class SpotifyAppApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean
-) : SpotifyApi(
+) : SpotifyApi<SpotifyAppApi, SpotifyAppApiBuilder>(
     clientId,
     clientSecret,
     token,
@@ -239,7 +260,7 @@ class SpotifyAppApi internal constructor(
      */
     override val following: FollowingApi = FollowingApi(this)
 
-    override fun refreshToken(): Token {
+    override suspend fun suspendRefreshToken(): Token {
         require(clientId != null && clientSecret != null) { "Either the client id or the client secret is not set" }
         val currentToken = this.token
 
@@ -291,7 +312,7 @@ class SpotifyClientApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean
-) : SpotifyApi(
+) : SpotifyApi<SpotifyClientApi, SpotifyClientApiBuilder>(
     clientId,
     clientSecret,
     token,
@@ -389,7 +410,7 @@ class SpotifyClientApi internal constructor(
         runExecutableFunctions = false
     }
 
-    override fun refreshToken(): Token {
+    override suspend fun suspendRefreshToken(): Token {
         require(clientId != null && clientSecret != null) { "Either the client id or the client secret is not set" }
 
         val currentToken = this.token
@@ -483,10 +504,12 @@ class SpotifyClientApi internal constructor(
      * Whether the current access token allows access to all of the provided scopes
      */
     fun hasScopes(scope: SpotifyScope, vararg scopes: SpotifyScope): Boolean =
-        !isTokenValid(false).isValid && (scopes.toList() + scope).all { token.scopes.contains(it) }
+        !isTokenValid(false).isValid &&
+                token.scopes.contains(scope) &&
+                scopes.all { token.scopes.contains(it) }
 }
 
-typealias SpotifyAPI = SpotifyApi
+typealias SpotifyAPI<T, B> = SpotifyApi<T, B>
 typealias SpotifyClientAPI = SpotifyClientApi
 typealias SpotifyAppAPI = SpotifyAppApi
 
@@ -497,7 +520,7 @@ fun getAuthUrlFull(vararg scopes: SpotifyScope, clientId: String, redirectUri: S
             if (scopes.isEmpty()) "" else "&scope=${scopes.joinToString("%20") { it.uri }}"
 }
 
-fun getCredentialedToken(clientId: String, clientSecret: String, api: SpotifyApi?): Token {
+suspend fun getCredentialedToken(clientId: String, clientSecret: String, api: SpotifyApi<*, *>?): Token {
     val response = executeTokenRequest(
         HttpConnection(
             "https://accounts.spotify.com/api/token",
@@ -515,7 +538,11 @@ fun getCredentialedToken(clientId: String, clientSecret: String, api: SpotifyApi
     throw SpotifyException.BadRequestException(response.body.toObject(AuthenticationError.serializer(), null))
 }
 
-internal fun executeTokenRequest(httpConnection: HttpConnection, clientId: String, clientSecret: String): HttpResponse {
+internal suspend fun executeTokenRequest(
+    httpConnection: HttpConnection,
+    clientId: String,
+    clientSecret: String
+): HttpResponse {
     return httpConnection.execute(
         listOf(
             HttpHeader(

src/commonMain/kotlin/com.adamratzman.spotify/SpotifyExceptions.kt

@@ -25,6 +25,7 @@ sealed class SpotifyException(message: String, cause: Throwable? = null) : Excep
                     "Authentication error: ${authenticationError.error}. Description: ${authenticationError.description}",
                     401
                 )
+
         constructor(responseException: ResponseException) :
                 this(
                     responseException.message ?: "Bad Request",