update SauceNaoAPI structure

0.13.0

.github/workflows/build_and_publish.yml

@@ -16,8 +16,13 @@ jobs:
           mv gradle.properties.tmp gradle.properties
       - name: Build
         run: ./gradlew build
+      - name: Publish to Gitea
+        continue-on-error: true
+        run: ./gradlew publishAllPublicationsToGiteaRepository
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
       - name: Publish
-        run: ./gradlew publishAllPublicationsToGithubPackagesRepository --no-parallel -x signJsPublication -x signJvmPublication -x signKotlinMultiplatformPublication
+        run: ./gradlew publishAllPublicationsToGithubPackagesRepository --no-parallel
         continue-on-error: true
         env:
           GITHUBPACKAGES_USER: ${{ github.actor }}

CHANGELOG.md

@@ -1,5 +1,20 @@
 # SauceNaoAPI Changelog
 
+## 0.14.0
+
+* `LimitStatus` is `Comparable<LimitStatus>` since this update
+* `Limits` is `Comparable<Limits>` since this update
+* Main API has been changed
+
+## 0.13.0
+
+* Versions:
+  * `Kotlin`: `1.7.20` -> `1.7.22`
+  * `Serialization`: `1.4.0` -> `1.4.1`
+  * `Klock`: `3.2.0` -> `3.4.0`
+  * `Ktor`: `2.1.2` -> `2.2.1`
+* Now it is possible to subscribe onto API limits changes
+
 ## 0.12.2
 
 * Versions:

gradle.properties

@@ -1,3 +1,3 @@
 kotlin.code.style=official
 
-library_version=0.12.2
+library_version=0.14.0

gradle/libs.versions.toml

@@ -1,11 +1,11 @@
 [versions]
 
-kt = "1.7.20"
-kt-serialization = "1.4.0"
+kt = "1.7.22"
+kt-serialization = "1.4.1"
 kt-coroutines = "1.6.4"
 
-klock = "3.2.0"
-ktor = "2.1.2"
+klock = "3.4.0"
+ktor = "2.2.1"
 
 gh-release = "2.4.1"
 

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip

publish.gradle

@@ -42,20 +42,40 @@ publishing {
                 maven {
                     name = "GithubPackages"
                     url = uri("https://maven.pkg.github.com/InsanusMokrassar/SauceNaoAPI")
+            
                     credentials {
                         username = project.hasProperty('GITHUBPACKAGES_USER') ? project.property('GITHUBPACKAGES_USER') : System.getenv('GITHUBPACKAGES_USER')
                         password = project.hasProperty('GITHUBPACKAGES_PASSWORD') ? project.property('GITHUBPACKAGES_PASSWORD') : System.getenv('GITHUBPACKAGES_PASSWORD')
                     }
+            
+                }
+            }
+            if (project.hasProperty('GITEA_TOKEN') || System.getenv('GITEA_TOKEN') != null) {
+                maven {
+                    name = "Gitea"
+                    url = uri("https://git.inmo.dev/api/packages/InsanusMokrassar/maven")
+            
+                    credentials(HttpHeaderCredentials) {
+                        name = "Authorization"
+                        value = project.hasProperty('GITEA_TOKEN') ? project.property('GITEA_TOKEN') : System.getenv('GITEA_TOKEN')
+                    }
+            
+                    authentication {
+                        header(HttpHeaderAuthentication)
+                    }
+            
                 }
             }
             if ((project.hasProperty('SONATYPE_USER') || System.getenv('SONATYPE_USER') != null) && (project.hasProperty('SONATYPE_PASSWORD') || System.getenv('SONATYPE_PASSWORD') != null)) {
                 maven {
                     name = "sonatype"
                     url = uri("https://oss.sonatype.org/service/local/staging/deploy/maven2/")
+            
                     credentials {
                         username = project.hasProperty('SONATYPE_USER') ? project.property('SONATYPE_USER') : System.getenv('SONATYPE_USER')
                         password = project.hasProperty('SONATYPE_PASSWORD') ? project.property('SONATYPE_PASSWORD') : System.getenv('SONATYPE_PASSWORD')
                     }
+            
                 }
             }
         }

publish.kpsb

@@ -1 +1 @@
-{"licenses":[{"id":"Apache-2.0","title":"Apache Software License 2.0","url":"https://github.com/InsanusMokrassar/SauceNaoAPI/blob/master/LICENSE"}],"mavenConfig":{"name":"SauceNao API","description":"SauceNao API library","url":"https://insanusmokrassar.github.io/${project.name}","vcsUrl":"https://github.com/insanusmokrassar/${project.name}.git","developers":[{"id":"InsanusMokrassar","name":"Ovsyannikov Alexey","eMail":"ovsyannikov.alexey95@gmail.com"}],"repositories":[{"name":"GithubPackages","url":"https://maven.pkg.github.com/InsanusMokrassar/SauceNaoAPI"},{"name":"sonatype","url":"https://oss.sonatype.org/service/local/staging/deploy/maven2/"}],"gpgSigning":{"type":"dev.inmo.kmppscriptbuilder.core.models.GpgSigning.Optional"}}}
+{"licenses":[{"id":"Apache-2.0","title":"Apache Software License 2.0","url":"https://github.com/InsanusMokrassar/SauceNaoAPI/blob/master/LICENSE"}],"mavenConfig":{"name":"SauceNao API","description":"SauceNao API library","url":"https://insanusmokrassar.github.io/${project.name}","vcsUrl":"https://github.com/insanusmokrassar/${project.name}.git","developers":[{"id":"InsanusMokrassar","name":"Ovsyannikov Alexey","eMail":"ovsyannikov.alexey95@gmail.com"}],"repositories":[{"name":"GithubPackages","url":"https://maven.pkg.github.com/InsanusMokrassar/SauceNaoAPI"},{"name":"Gitea","url":"https://git.inmo.dev/api/packages/InsanusMokrassar/maven","credsType":{"type":"dev.inmo.kmppscriptbuilder.core.models.MavenPublishingRepository.CredentialsType.HttpHeaderCredentials","headerName":"Authorization","headerValueProperty":"GITEA_TOKEN"}},{"name":"sonatype","url":"https://oss.sonatype.org/service/local/staging/deploy/maven2/"}],"gpgSigning":{"type":"dev.inmo.kmppscriptbuilder.core.models.GpgSigning.Optional"}}}

src/commonMain/kotlin/dev/inmo/saucenaoapi/SauceNaoAPI.kt

@@ -22,6 +22,7 @@ private const val URL_FIELD = "url"
 private const val FILE_FIELD = "file"
 private const val FILENAME_FIELD = "filename"
 private const val DB_FIELD = "db"
+private const val DBS_FIELD = "dbs[]"
 private const val DBMASK_FIELD = "dbmask"
 private const val DBMASKI_FIELD = "dbmaski"
 private const val RESULTS_COUNT_FIELD = "numres"
@@ -52,8 +53,12 @@ data class SauceNaoAPI(
     private val timeManager = TimeManager(subscope)
     private val quotaManager = RequestQuotaManager(subscope)
 
-    val limitsState: LimitsState
-        get() = quotaManager.limitsState
+    val limitsState: LimitsState by quotaManager::limitsState
+    val longQuotaFlow by quotaManager::longQuotaFlow
+    val shortQuotaFlow by quotaManager::shortQuotaFlow
+    val longMaxQuotaFlow by quotaManager::longMaxQuotaFlow
+    val shortMaxQuotaFlow by quotaManager::shortMaxQuotaFlow
+    val limitsStateFlow by quotaManager::limitsStateFlow
 
     private val requestsJob = subscope.launch {
         for ((callback, requestBuilder) in requestsChannel) {
@@ -88,6 +93,45 @@ data class SauceNaoAPI(
         minSimilarity = minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        url: String,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        url.asSauceRequestSubject,
+        db = db,
+        dbs = dbs,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        url: String,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        url.asSauceRequestSubject,
+        dbmask = mask,
+        dbmaski = excludedMask,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
     suspend fun request(
         mediaInput: Input,
         mimeType: ContentType,
@@ -99,6 +143,47 @@ data class SauceNaoAPI(
         minSimilarity = minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        mediaInput: Input,
+        mimeType: ContentType,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        mediaInput.asSauceRequestSubject(mimeType),
+        db = db,
+        dbs = dbs,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        mediaInput: Input,
+        mimeType: ContentType,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = makeRequest(
+        mediaInput.asSauceRequestSubject(mimeType),
+        dbmask = mask,
+        dbmaski = excludedMask,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
     suspend fun request(
         file: MPPFile,
         resultsCount: Int? = null,
@@ -106,44 +191,91 @@ data class SauceNaoAPI(
     ): SauceNaoAnswer = request(
         file.input,
         file.contentType,
-        resultsCount = resultsCount,
-        minSimilarity = minSimilarity
+        resultsCount,
+        minSimilarity
     )
 
+    /**
+     * @param db search a specific index number or all without needing to generate a bitmask.
+     * @param dbs search one or more specific index number, set more than once to search multiple.
+     */
+    suspend fun requestByDBs(
+        file: MPPFile,
+        db: Int? = null,
+        dbs: Array<Int>? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = requestByDBs(
+        file.input,
+        file.contentType,
+        db,
+        dbs,
+        resultsCount,
+        minSimilarity
+    )
+
+    /**
+     * @param mask Mask for selecting specific indexes to ENABLE. dbmask=8191 will search all of the first 14 indexes. If intending to search all databases, the db=999 option is more appropriate.
+     * @param excludedMask Mask for selecting specific indexes to DISABLE. dbmaski=8191 would search only indexes higher than the first 14. This is ideal when attempting to disable only certain indexes, while allowing future indexes to be included by default.
+     *
+     * Bitmask Note: Index numbers start with 0. Even though pixiv is labeled as index 5, it would be controlled with the 6th bit position, which has a decimal value of 32 when set.
+     * db=<index num or 999 for all>
+     */
+    suspend fun requestByMasks(
+        file: MPPFile,
+        mask: Int?,
+        excludedMask: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer = requestByMasks(
+        file.input,
+        file.contentType,
+        mask,
+        excludedMask,
+        resultsCount,
+        minSimilarity
+    )
+
+    @Deprecated("Renamed", ReplaceWith("requestByDBs(url, db, null, resultsCount, minSimilarity)"))
     suspend fun requestByDb(
         url: String,
         db: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
-        url.asSauceRequestSubject,
-        db = db,
-        resultsCount = resultsCount,
-        minSimilarity = minSimilarity
+    ): SauceNaoAnswer = requestByDBs(
+        url,
+        db,
+        null,
+        resultsCount,
+        minSimilarity
     )
 
-    suspend fun requestByMask(
+    @Deprecated("Renamed", ReplaceWith("requestByMasks(url, dbmask, null, resultsCount, minSimilarity)"))
+    suspend fun request(
         url: String,
         dbmask: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
-        url.asSauceRequestSubject,
-        dbmask = dbmask,
-        resultsCount = resultsCount,
-        minSimilarity = minSimilarity
+    ): SauceNaoAnswer = requestByMasks(
+        url,
+        dbmask,
+        null,
+        resultsCount,
+        minSimilarity
     )
 
+    @Deprecated("Renamed", ReplaceWith("requestByMasks(url, null, dbmaski, resultsCount, minSimilarity)"))
     suspend fun requestByMaskI(
         url: String,
         dbmaski: Int,
         resultsCount: Int? = null,
         minSimilarity: Float? = null
-    ): SauceNaoAnswer = makeRequest(
-        url.asSauceRequestSubject,
-        dbmaski = dbmaski,
-        resultsCount = resultsCount,
-        minSimilarity = minSimilarity
+    ): SauceNaoAnswer = requestByMasks(
+        url,
+        null,
+        dbmaski,
+        resultsCount,
+        minSimilarity
     )
 
     private suspend fun makeRequest(
@@ -165,6 +297,7 @@ data class SauceNaoAPI(
     private suspend fun makeRequest(
         request: SauceRequestSubject,
         db: Int? = null,
+        dbs: Array<Int>? = null,
         dbmask: Int? = null,
         dbmaski: Int? = null,
         resultsCount: Int? = null,
@@ -179,6 +312,7 @@ data class SauceNaoAPI(
                 apiToken ?.also { parameter(API_TOKEN_FIELD, it) }
                 parameter(OUTPUT_TYPE_FIELD, JsonOutputType.typeCode)
                 db ?.also { parameter(DB_FIELD, it) }
+                dbs ?.forEach { parameter(DBS_FIELD, it) }
                 dbmask ?.also { parameter(DBMASK_FIELD, it) }
                 dbmaski ?.also { parameter(DBMASKI_FIELD, it) }
                 resultsCount ?.also { parameter(RESULTS_COUNT_FIELD, it) }

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/header/AccountInfo.kt

@@ -29,15 +29,27 @@ val Header.accountInfo
 data class LimitStatus(
     val remain: Int = Int.MAX_VALUE,
     val limit: Int = Int.MAX_VALUE
-)
+) : Comparable<LimitStatus> {
+    override fun compareTo(other: LimitStatus): Int = when {
+        limit == other.limit && remain == other.remain -> 0
+        else -> remain.compareTo(other.remain)
+    }
+}
 
 data class Limits(
     val short: LimitStatus = LimitStatus(),
     val long: LimitStatus = LimitStatus()
-)
+) : Comparable<Limits> {
+    override fun compareTo(other: Limits): Int = when {
+        long == other.long && short == other.short -> 0
+        else -> short.remain.compareTo(other.short.remain)
+    }
+}
 
 data class AccountInfo(
     val accountType: AccountType = defaultAccountType,
     val userId: UserId? = null,
     val limits: Limits = Limits()
-)
+) : Comparable<AccountInfo> {
+    override fun compareTo(other: AccountInfo): Int = limits.compareTo(other.limits)
+}

src/commonMain/kotlin/dev/inmo/saucenaoapi/models/LimitsState.kt

@@ -8,4 +8,6 @@ data class LimitsState(
     val maxLongQuota: Int,
     val knownShortQuota: Int,
     val knownLongQuota: Int
-)
+) : Comparable<LimitsState> {
+    override fun compareTo(other: LimitsState): Int = knownShortQuota.compareTo(other.knownShortQuota)
+}

src/commonMain/kotlin/dev/inmo/saucenaoapi/utils/RequestQuotaManager.kt

@@ -9,17 +9,39 @@ import dev.inmo.saucenaoapi.models.Header
 import dev.inmo.saucenaoapi.models.LimitsState
 import kotlinx.coroutines.*
 import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.merge
 import kotlin.math.max
 import kotlin.math.min
 
 internal class RequestQuotaManager (
     scope: CoroutineScope
 ) {
-    private var longQuota = 1
-    private var shortQuota = 1
-    private var longMaxQuota = 1
-    private var shortMaxQuota = 1
+    private val _longQuotaFlow = MutableStateFlow(1)
+    private val _shortQuotaFlow = MutableStateFlow(1)
+    private val _longMaxQuotaFlow = MutableStateFlow(1)
+    private val _shortMaxQuotaFlow = MutableStateFlow(1)
+    private var longQuota by _longQuotaFlow::value
+    private var shortQuota by _shortQuotaFlow::value
+    private var longMaxQuota by _longMaxQuotaFlow::value
+    private var shortMaxQuota by _shortMaxQuotaFlow::value
 
+    val longQuotaFlow = _longQuotaFlow.asStateFlow()
+    val shortQuotaFlow = _shortQuotaFlow.asStateFlow()
+    val longMaxQuotaFlow = _longMaxQuotaFlow.asStateFlow()
+    val shortMaxQuotaFlow = _shortMaxQuotaFlow.asStateFlow()
+    val limitsStateFlow = merge(
+        longQuotaFlow, shortQuotaFlow, longMaxQuotaFlow, shortMaxQuotaFlow
+    ).map { _ ->
+        LimitsState(
+            shortMaxQuota,
+            longMaxQuota,
+            shortQuota,
+            longQuota
+        )
+    }
     val limitsState: LimitsState
         get() = LimitsState(
             shortMaxQuota,