upmigration

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

@@ -0,0 +1,17 @@
+package dev.inmo.saucenaoapi
+
+sealed class OutputType {
+    abstract val typeCode: Int
+}
+
+object HtmlOutputType : dev.inmo.saucenaoapi.OutputType() {
+    override val typeCode: Int = 0
+}
+
+object XmlOutputType : dev.inmo.saucenaoapi.OutputType() {
+    override val typeCode: Int = 1
+}
+
+object JsonOutputType : dev.inmo.saucenaoapi.OutputType() {
+    override val typeCode: Int = 2
+}

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

@@ -0,0 +1,215 @@
+package dev.inmo.saucenaoapi
+
+import dev.inmo.saucenaoapi.exceptions.TooManyRequestsException
+import dev.inmo.saucenaoapi.exceptions.sauceNaoAPIException
+import dev.inmo.saucenaoapi.models.*
+import dev.inmo.saucenaoapi.utils.*
+import io.ktor.client.HttpClient
+import io.ktor.client.features.ClientRequestException
+import io.ktor.client.request.*
+import io.ktor.client.request.forms.MultiPartFormDataContent
+import io.ktor.client.request.forms.formData
+import io.ktor.client.statement.HttpResponse
+import io.ktor.client.statement.readText
+import io.ktor.http.*
+import io.ktor.utils.io.core.Input
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.Channel
+import kotlinx.serialization.json.Json
+import kotlin.coroutines.*
+
+private const val API_TOKEN_FIELD = "api_key"
+private const val OUTPUT_TYPE_FIELD = "output_type"
+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 DBMASK_FIELD = "dbmask"
+private const val DBMASKI_FIELD = "dbmaski"
+private const val RESULTS_COUNT_FIELD = "numres"
+private const val MINIMAL_SIMILARITY_FIELD = "minsim"
+
+private const val SEARCH_URL = "https://saucenao.com/search.php"
+
+val defaultSauceNaoParser = Json {
+    allowSpecialFloatingPointValues = true
+    allowStructuredMapKeys = true
+    ignoreUnknownKeys = true
+    useArrayPolymorphism = true
+}
+
+data class SauceNaoAPI(
+    private val apiToken: String? = null,
+    private val outputType: dev.inmo.saucenaoapi.OutputType = dev.inmo.saucenaoapi.JsonOutputType,
+    private val client: HttpClient = HttpClient(),
+    private val searchUrl: String = SEARCH_URL,
+    private val scope: CoroutineScope = CoroutineScope(Dispatchers.Default),
+    private val parser: Json = defaultSauceNaoParser
+) : SauceCloseable {
+    private val requestsChannel = Channel<Pair<Continuation<SauceNaoAnswer>, HttpRequestBuilder>>(Channel.UNLIMITED)
+    private val timeManager = TimeManager(scope)
+    private val quotaManager = RequestQuotaManager(scope)
+
+    val limitsState: LimitsState
+        get() = quotaManager.limitsState
+
+    private val requestsJob = scope.launch {
+        for ((callback, requestBuilder) in requestsChannel) {
+            quotaManager.getQuota()
+            launch {
+                try {
+                    val answer = makeRequest(requestBuilder)
+                    callback.resume(answer)
+
+                    quotaManager.updateQuota(answer.header, timeManager)
+                } catch (e: TooManyRequestsException) {
+                    quotaManager.happenTooManyRequests(timeManager, e)
+                    requestsChannel.send(callback to requestBuilder)
+                } catch (e: Exception) {
+                    try {
+                        callback.resumeWithException(e)
+                    } catch (e: IllegalStateException) { // may happen when already resumed and api was closed
+                        // do nothing
+                    }
+                }
+            }
+        }
+    }
+
+    suspend fun request(
+        url: String,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? = makeRequest(
+        url.asSauceRequestSubject,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    suspend fun request(
+        mediaInput: Input,
+        mimeType: ContentType,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? = makeRequest(
+        mediaInput.asSauceRequestSubject(mimeType),
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    suspend fun requestByDb(
+        url: String,
+        db: Int,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? = makeRequest(
+        url.asSauceRequestSubject,
+        db = db,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    suspend fun requestByMask(
+        url: String,
+        dbmask: Int,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? = makeRequest(
+        url.asSauceRequestSubject,
+        dbmask = dbmask,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    suspend fun requestByMaskI(
+        url: String,
+        dbmaski: Int,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? = makeRequest(
+        url.asSauceRequestSubject,
+        dbmaski = dbmaski,
+        resultsCount = resultsCount,
+        minSimilarity = minSimilarity
+    )
+
+    private suspend fun makeRequest(
+        builder: HttpRequestBuilder
+    ): SauceNaoAnswer {
+        return try {
+            val call = client.request<HttpResponse>(builder)
+            val answerText = call.readText()
+            timeManager.addTimeAndClear()
+            parser.decodeFromString(
+                SauceNaoAnswerSerializer,
+                answerText
+            )
+        } catch (e: ClientRequestException) {
+            throw e.sauceNaoAPIException()
+        }
+    }
+
+    private suspend fun makeRequest(
+        request: SauceRequestSubject,
+        db: Int? = null,
+        dbmask: Int? = null,
+        dbmaski: Int? = null,
+        resultsCount: Int? = null,
+        minSimilarity: Float? = null
+    ): SauceNaoAnswer? {
+        return suspendCoroutine<SauceNaoAnswer> {
+            requestsChannel.offer(
+                it to HttpRequestBuilder().apply {
+                    url(searchUrl)
+
+                    apiToken ?.also { parameter(API_TOKEN_FIELD, it) }
+                    parameter(OUTPUT_TYPE_FIELD, outputType.typeCode)
+                    db ?.also { parameter(DB_FIELD, it) }
+                    dbmask ?.also { parameter(DBMASK_FIELD, it) }
+                    dbmaski ?.also { parameter(DBMASKI_FIELD, it) }
+                    resultsCount ?.also { parameter(RESULTS_COUNT_FIELD, it) }
+                    minSimilarity ?.also { parameter(MINIMAL_SIMILARITY_FIELD, it) }
+
+                    when (request) {
+                        is UrlSauceRequestSubject -> {
+                            parameter(URL_FIELD, request.url)
+                        }
+                        is InputRequestSubject -> {
+                            val mimeType = request.mimeType
+
+                            method = HttpMethod.Post
+                            body = MultiPartFormDataContent(formData {
+                                    appendInput(
+                                        FILE_FIELD,
+                                        Headers.build {
+                                            append(HttpHeaders.ContentType, mimeType.toString())
+
+                                            val fakeFilename = "filename=file" + when (mimeType) {
+                                                ContentType.Image.GIF -> ".gif"
+                                                ContentType.Image.JPEG -> ".jpeg"
+                                                ContentType.Image.PNG -> ".png"
+                                                ContentType.Image.SVG -> ".svg"
+                                                else -> throw IllegalArgumentException(
+                                                    "Currently supported formats for uploading in sauce: gif, jpeg, png, svg"
+                                                )
+                                            }
+                                            append(HttpHeaders.ContentDisposition, "filename=$fakeFilename")
+                                        },
+                                        block = request::input
+                                    )
+                            })
+                        }
+                    }
+                }
+            )
+        }
+    }
+
+    override fun close() {
+        requestsChannel.close()
+        client.close()
+        requestsJob.cancel()
+        timeManager.close()
+        quotaManager.close()
+    }
+}

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

@@ -0,0 +1,16 @@
+package dev.inmo.saucenaoapi
+
+import io.ktor.http.ContentType
+import io.ktor.utils.io.core.Input
+
+internal sealed class SauceRequestSubject
+
+internal data class UrlSauceRequestSubject(val url: String) : SauceRequestSubject()
+
+internal data class InputRequestSubject(val input: Input, val mimeType: ContentType) : SauceRequestSubject()
+
+internal val String.asSauceRequestSubject
+    get() = UrlSauceRequestSubject(this)
+
+internal fun Input.asSauceRequestSubject(mimeType: ContentType)
+    = InputRequestSubject(this, mimeType)

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/AdaptedAnswer.kt

@@ -0,0 +1,23 @@
+package dev.inmo.saucenaoapi.additional
+
+import dev.inmo.saucenaoapi.additional.header.ResultMetaInfo
+import dev.inmo.saucenaoapi.additional.header.adapted
+import dev.inmo.saucenaoapi.additional.results.AdaptedResult
+import dev.inmo.saucenaoapi.additional.results.adapted
+import dev.inmo.saucenaoapi.models.SauceNaoAnswer
+
+val SauceNaoAnswer.adapted: AdaptedAnswer
+    get() = header.adapted.let { resultMetainfo ->
+        val adaptedResults = results.map {
+            it.adapted(resultMetainfo)
+        }
+        AdaptedAnswer(
+            resultMetainfo,
+            adaptedResults
+        )
+    }
+
+data class AdaptedAnswer(
+    val resultMetaInfo: ResultMetaInfo,
+    val results: List<AdaptedResult>
+)

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/Utils.kt

@@ -0,0 +1,11 @@
+package dev.inmo.saucenaoapi.additional
+
+import com.soywiz.klock.TimeSpan
+
+typealias AccountType = Int
+const val defaultAccountType: AccountType = 1 // "basic"
+
+typealias UserId = Int
+
+val SHORT_TIME_RECALCULATING_MILLIS = TimeSpan(30.0 * 1000)
+val LONG_TIME_RECALCULATING_MILLIS = TimeSpan(24.0 * 60 * 60 * 1000)

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

@@ -0,0 +1,43 @@
+package dev.inmo.saucenaoapi.additional.header
+
+import dev.inmo.saucenaoapi.additional.*
+import dev.inmo.saucenaoapi.models.Header
+
+val Header.shortLimitStatus: LimitStatus
+    get() = LimitStatus(
+        shortRemaining,
+        shortLimit
+    )
+
+val Header.longLimitStatus: LimitStatus
+    get() = LimitStatus(
+        longRemaining,
+        longLimit
+    )
+
+val Header.limits
+    get() = Limits(shortLimitStatus, longLimitStatus)
+
+val Header.accountInfo
+    get() = AccountInfo(
+        accountType ?: defaultAccountType,
+        userId,
+        limits
+    )
+
+
+data class LimitStatus(
+    val remain: Int = Int.MAX_VALUE,
+    val limit: Int = Int.MAX_VALUE
+)
+
+data class Limits(
+    val short: LimitStatus = LimitStatus(),
+    val long: LimitStatus = LimitStatus()
+)
+
+data class AccountInfo(
+    val accountType: AccountType = defaultAccountType,
+    val userId: UserId? = null,
+    val limits: Limits = Limits()
+)

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

@@ -0,0 +1,24 @@
+package dev.inmo.saucenaoapi.additional.header
+
+import dev.inmo.saucenaoapi.models.Header
+
+data class IndexInfo(
+    val id: Int,
+    val status: Int = 500,
+    val results: Int = 0,
+    val parent_id: Int? = null
+)
+
+val Header.adaptedIndexes: List<IndexInfo>
+    get() = indexes.mapNotNull {
+        it ?.let { _ ->
+            it.id ?.let { id ->
+                IndexInfo(
+                    id,
+                    it.status ?: 500, // Serverside error if not set
+                    it.results ?: 0,
+                    it.parent_id
+                )
+            }
+        }
+    }

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

@@ -0,0 +1,37 @@
+package dev.inmo.saucenaoapi.additional.header
+
+import dev.inmo.saucenaoapi.models.Header
+
+val Header.queryPreview
+    get() = QueryResultPreview(
+        queryImageDisplay,
+        queryImage
+    )
+
+val Header.queryResults
+    get() = QueryResultsMetainfo(
+        status ?: 500, // server_side error if status field was not set up
+        resultsCount ?: 0,
+        minSimilarity ?: 0F,
+        searchDepth ?: 128,
+        queryPreview,
+        adaptedIndexes
+    )
+
+data class QueryResultPreview(
+    val imageDisplay: String? = null, // something like "userdata/uuid.png",
+    val image: String? = null // something like "uuid.jpg"
+)
+
+data class QueryResultsMetainfo(
+    val status: Int = 0,
+    val count: Int = 0,
+    val minSimilarity: Float = 0F,
+    val searchDepth: Int = 128,
+    val preview: QueryResultPreview = QueryResultPreview(),
+    val indexesInfo: List<IndexInfo> = emptyList()
+) {
+    val isOk: Boolean = status == 0
+    val isClientSideError = status < 0
+    val isServerSideError = status > 0
+}

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

@@ -0,0 +1,14 @@
+package dev.inmo.saucenaoapi.additional.header
+
+import dev.inmo.saucenaoapi.models.Header
+
+data class ResultMetaInfo(
+    val accountInfo: AccountInfo = AccountInfo(),
+    val resultsInfo: QueryResultsMetainfo = QueryResultsMetainfo()
+)
+
+val Header.adapted
+    get() = ResultMetaInfo(
+        accountInfo,
+        queryResults
+    )

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/results/AdaptedResult.kt

@@ -0,0 +1,22 @@
+package dev.inmo.saucenaoapi.additional.results
+
+import dev.inmo.saucenaoapi.additional.header.IndexInfo
+import dev.inmo.saucenaoapi.additional.header.ResultMetaInfo
+import dev.inmo.saucenaoapi.models.Result
+import dev.inmo.saucenaoapi.models.ResultData
+
+fun Result.adapted(
+    resultMetaInfo: ResultMetaInfo
+): AdaptedResult = AdaptedResult(
+    ResultHeader(
+        header.similarity,
+        header.thumbnail,
+        resultMetaInfo.resultsInfo.indexesInfo.firstOrNull { it.id == header.indexId } ?: IndexInfo(header.indexId)
+    ),
+    data
+)
+
+data class AdaptedResult(
+    val resultHeader: ResultHeader,
+    val resultData: ResultData
+)

src/commonMain/kotlin/dev/inmo/saucenaoapi/additional/results/ResultHeader.kt

@@ -0,0 +1,9 @@
+package dev.inmo.saucenaoapi.additional.results
+
+import dev.inmo.saucenaoapi.additional.header.IndexInfo
+
+data class ResultHeader(
+    val similarity: Float,
+    val thumbnail: String,
+    val index: IndexInfo
+)

src/commonMain/kotlin/dev/inmo/saucenaoapi/exceptions/TooManyRequestsException.kt

@@ -0,0 +1,34 @@
+package dev.inmo.saucenaoapi.exceptions
+
+import dev.inmo.saucenaoapi.additional.LONG_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.additional.SHORT_TIME_RECALCULATING_MILLIS
+import com.soywiz.klock.TimeSpan
+import io.ktor.client.features.ClientRequestException
+import io.ktor.client.statement.readText
+import io.ktor.http.HttpStatusCode.Companion.TooManyRequests
+import io.ktor.utils.io.errors.IOException
+
+internal suspend fun ClientRequestException.sauceNaoAPIException(): Exception  {
+    return when (response.status) {
+        TooManyRequests -> {
+            val answerContent = response.readText()
+            when {
+                answerContent.contains("daily limit") -> TooManyRequestsLongException(answerContent)
+                else -> TooManyRequestsShortException(answerContent)
+            }
+        }
+        else -> this
+    }
+}
+
+sealed class TooManyRequestsException(message: String, cause: Throwable? = null) : IOException(message, cause) {
+    abstract val answerContent: String
+    abstract val waitTime: TimeSpan
+}
+
+class TooManyRequestsShortException(override val answerContent: String) : TooManyRequestsException("Too many requests were sent in the short period") {
+    override val waitTime: TimeSpan = SHORT_TIME_RECALCULATING_MILLIS
+}
+class TooManyRequestsLongException(override val answerContent: String) : TooManyRequestsException("Too many requests were sent in the long period") {
+    override val waitTime: TimeSpan = LONG_TIME_RECALCULATING_MILLIS
+}

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

@@ -0,0 +1,66 @@
+package dev.inmo.saucenaoapi.models
+
+import dev.inmo.saucenaoapi.defaultSauceNaoParser
+import kotlinx.serialization.*
+import kotlinx.serialization.builtins.serializer
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.jsonObject
+
+@Serializable
+data class Header(
+    @SerialName("status")
+    val status: Int? = null,
+    @SerialName("results_requested")
+    val resultsRequested: Int? = null,
+    @Serializable(IndexesSerializer::class)
+    @SerialName("index")
+    val indexes: List<HeaderIndex?> = emptyList(),
+    @SerialName("search_depth")
+    val searchDepth: Int? = null,
+    @SerialName("minimum_similarity")
+    val minSimilarity: Float? = null,
+    @SerialName("results_returned")
+    val resultsCount: Int? = null,
+    @SerialName("query_image_display")
+    val queryImageDisplay: String? = null, // something like "userdata/uuid.png",
+    @SerialName("query_image")
+    val queryImage: String? = null, // something like "uuid.jpg"
+    @SerialName("short_remaining")
+    val shortRemaining: Int = Int.MAX_VALUE,
+    @SerialName("long_remaining")
+    val longRemaining: Int = Int.MAX_VALUE,
+    @SerialName("short_limit")
+    val shortLimit: Int = Int.MAX_VALUE,
+    @SerialName("long_limit")
+    val longLimit: Int = Int.MAX_VALUE,
+    @SerialName("account_type")
+    val accountType: Int? = null,
+    @SerialName("user_id")
+    val userId: Int? = null
+)
+
+internal object IndexesSerializer : KSerializer<List<HeaderIndex?>> {
+    override val descriptor: SerialDescriptor = String.serializer().descriptor
+
+    override fun deserialize(decoder: Decoder): List<HeaderIndex?> {
+        val json = JsonObject.serializer().deserialize(decoder)
+        val parsed = json.keys.mapNotNull { it.toIntOrNull() }.sorted().mapNotNull {
+            val jsonObject = json[it.toString()] ?.jsonObject ?: return@mapNotNull null
+            val index = defaultSauceNaoParser.decodeFromString(
+                HeaderIndex.serializer(),
+                defaultSauceNaoParser.encodeToString(JsonObject.serializer(), jsonObject)
+            )
+            it to index
+        }.toMap()
+        return Array<HeaderIndex?>(parsed.keys.maxOrNull() ?: 0) {
+            parsed[it]
+        }.toList()
+    }
+
+    override fun serialize(encoder: Encoder, value: List<HeaderIndex?>) {
+        TODO()
+    }
+}

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

@@ -0,0 +1,11 @@
+package dev.inmo.saucenaoapi.models
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class HeaderIndex(
+    val status: Int? = null,
+    val id: Int? = null,
+    val results: Int? = null,
+    val parent_id: Int? = null
+)

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

@@ -0,0 +1,11 @@
+package dev.inmo.saucenaoapi.models
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class LimitsState(
+    val maxShortQuota: Int,
+    val maxLongQuota: Int,
+    val knownShortQuota: Int,
+    val knownLongQuota: Int
+)

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

@@ -0,0 +1,9 @@
+package dev.inmo.saucenaoapi.models
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class Result(
+    val header: ResultHeader,
+    val data: ResultData
+)

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

@@ -0,0 +1,161 @@
+package dev.inmo.saucenaoapi.models
+
+import dev.inmo.saucenaoapi.utils.CommonMultivariantStringSerializer
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ResultData(
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("danbooru_id")
+    val danbooruId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("gelbooru_id")
+    val gelbooruId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("drawr_id")
+    val drawrId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pixiv_id")
+    val pixivId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("seiga_id")
+    val seigaId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("yandere_id")
+    val yandereId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("konachan_id")
+    val konachanId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("sankaku_id")
+    val sankakuId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("anime-pictures_id")
+    val animePicturesId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("e621_id")
+    val e621Id: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("idol_id")
+    val idolId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("imdb_id")
+    val imdbId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("anidb_aid")
+    val anidbAId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("bcy_id")
+    val bcyId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("ddb_id")
+    val ddbId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("nijie_id")
+    val nijieId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("getchu_id")
+    val getchuId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("shutterstock_id")
+    val shutterstockId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("contributor_id")
+    val contributorId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("est_time")
+    val estTime: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("bcy_type")
+    val bcyType: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("da_id")
+    val daId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pg_id")
+    val pgId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("mal_id")
+    val malId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("md_id")
+    val mdId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("mu_id")
+    val muId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pawoo_id")
+    val pawooId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pawoo_user_acct")
+    val pawooUserAcct: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pawoo_user_username")
+    val pawooUserUsername: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("pawoo_user_display_name")
+    val pawooUserDisplayname: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val title: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("jp_title")
+    val titleJp: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("eng_title")
+    val titleEng: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("alt_titles")
+    val titleAlt: List<String> = emptyList(),
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("jp_name")
+    val nameJp: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("eng_name")
+    val nameEng: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val creator: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val material: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("member_name")
+    val memberName: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("member_id")
+    val memberId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val part: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("part_name")
+    val partName: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val date: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val company: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val file: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val year: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("member_link_id")
+    val memberLinkId: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("author_name")
+    val authorName: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("author_url")
+    val authorUrl: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val characters: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val source: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val url: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    val type: String? = null,
+    @Serializable(CommonMultivariantStringSerializer::class)
+    @SerialName("created_at")
+    val createdAt: String? = null,
+    @SerialName("ext_urls")
+    val extUrls: List<String> = emptyList()
+)

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

@@ -0,0 +1,14 @@
+package dev.inmo.saucenaoapi.models
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class ResultHeader(
+    val similarity: Float,
+    val thumbnail: String,
+    @SerialName("index_id")
+    val indexId: Int,
+    @SerialName("index_name")
+    val indexName: String
+)

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

@@ -0,0 +1,56 @@
+package dev.inmo.saucenaoapi.models
+
+import dev.inmo.saucenaoapi.defaultSauceNaoParser
+import kotlinx.serialization.*
+import kotlinx.serialization.builtins.ListSerializer
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.buildJsonObject
+
+@Serializable
+private data class TemporalSauceNaoAnswerRepresentation(
+    val header: Header,
+    val results: List<Result> = emptyList(),
+)
+
+@Serializable(SauceNaoAnswerSerializer::class)
+data class SauceNaoAnswer internal constructor(
+    val header: Header,
+    val results: List<Result> = emptyList(),
+    val raw: JsonObject = JsonObject(emptyMap())
+)
+
+@Serializer(SauceNaoAnswer::class)
+object SauceNaoAnswerSerializer : KSerializer<SauceNaoAnswer> {
+    private val resultsSerializer = ListSerializer(Result.serializer())
+    private const val headerField = "header"
+    private const val resultsField = "results"
+    private val serializer = defaultSauceNaoParser
+
+    override fun deserialize(decoder: Decoder): SauceNaoAnswer {
+        val raw = JsonObject.serializer().deserialize(decoder)
+
+        return serializer.decodeFromJsonElement(
+            TemporalSauceNaoAnswerRepresentation.serializer(),
+            raw
+        ).let {
+            SauceNaoAnswer(
+                it.header,
+                it.results,
+                raw
+            )
+        }
+    }
+
+    override fun serialize(encoder: Encoder, value: SauceNaoAnswer) {
+        val resultObject = buildJsonObject {
+            value.raw.forEach {
+                put(it.key, it.value)
+            }
+            put(headerField, serializer.encodeToJsonElement(Header.serializer(), value.header))
+            put(resultsField, serializer.encodeToJsonElement(resultsSerializer, value.results))
+        }
+        JsonObject.serializer().serialize(encoder, resultObject)
+    }
+}

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

@@ -0,0 +1,18 @@
+package dev.inmo.saucenaoapi.utils
+
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializer
+import kotlinx.serialization.builtins.serializer
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.json.*
+
+@Serializer(String::class)
+object CommonMultivariantStringSerializer : KSerializer<String> by String.serializer() {
+    override fun deserialize(decoder: Decoder): String {
+        return when (val parsed = JsonElement.serializer().deserialize(decoder)) {
+            is JsonPrimitive -> parsed.content
+            is JsonArray -> parsed.joinToString { it.jsonPrimitive.content }
+            else -> error("Unexpected answer object has been received: $parsed")
+        }
+    }
+}

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

@@ -0,0 +1,103 @@
+package dev.inmo.saucenaoapi.utils
+
+import dev.inmo.saucenaoapi.additional.LONG_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.additional.SHORT_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.exceptions.TooManyRequestsException
+import dev.inmo.saucenaoapi.exceptions.TooManyRequestsLongException
+import dev.inmo.saucenaoapi.models.Header
+import dev.inmo.saucenaoapi.models.LimitsState
+import com.soywiz.klock.DateTime
+import kotlinx.coroutines.*
+import kotlinx.coroutines.channels.Channel
+import kotlin.coroutines.suspendCoroutine
+import kotlin.math.max
+import kotlin.math.min
+
+internal class RequestQuotaManager (
+    scope: CoroutineScope
+) : SauceCloseable {
+    private var longQuota = 1
+    private var shortQuota = 1
+    private var longMaxQuota = 1
+    private var shortMaxQuota = 1
+
+    val limitsState: LimitsState
+        get() = LimitsState(
+            shortMaxQuota,
+            longMaxQuota,
+            shortQuota,
+            longQuota
+        )
+
+    private val quotaActions = Channel<suspend () -> Unit>(Channel.UNLIMITED)
+
+    private val quotaJob = scope.launch {
+        for (callback in quotaActions) {
+            callback()
+        }
+    }
+
+    private suspend fun updateQuota(
+        newLongQuota: Int,
+        newShortQuota: Int,
+        newMaxLongQuota: Int?,
+        newMaxShortQuota: Int?,
+        timeManager: TimeManager
+    ) {
+        quotaActions.send(
+            suspend {
+                longMaxQuota = newMaxLongQuota ?: longMaxQuota
+                shortMaxQuota = newMaxShortQuota ?: shortMaxQuota
+
+                longQuota = min(newLongQuota, longMaxQuota)
+                shortQuota = min(newShortQuota, shortMaxQuota)
+
+                when {
+                    longQuota < 1 -> (timeManager.getMostOldestInLongPeriod() ?: DateTime.now()) + LONG_TIME_RECALCULATING_MILLIS
+                    shortQuota < 1 -> (timeManager.getMostOldestInShortPeriod() ?: DateTime.now()) + SHORT_TIME_RECALCULATING_MILLIS
+                    else -> null
+                } ?.also {
+                    delay((it - DateTime.now()).millisecondsLong)
+                    shortQuota = max(shortQuota, 1)
+                    longQuota = max(longQuota, 1)
+                }
+                Unit
+            }
+        )
+    }
+
+    suspend fun updateQuota(header: Header, timeManager: TimeManager) = updateQuota(
+        header.longRemaining,
+        header.shortRemaining,
+        header.longLimit,
+        header.shortLimit,
+        timeManager
+    )
+
+    suspend fun happenTooManyRequests(timeManager: TimeManager, e: TooManyRequestsException) = updateQuota(
+        if (e is TooManyRequestsLongException) 0 else 1,
+        0,
+        null,
+        null,
+        timeManager
+    )
+
+    suspend fun getQuota() {
+        return suspendCoroutine {
+            lateinit var callback: suspend () -> Unit
+            callback = suspend {
+                if (longQuota > 0 && shortQuota > 0) {
+                    it.resumeWith(Result.success(Unit))
+                } else {
+                    quotaActions.send(callback)
+                }
+            }
+            quotaActions.offer(callback)
+        }
+    }
+
+    override fun close() {
+        quotaJob.cancel()
+        quotaActions.close()
+    }
+}

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

@@ -0,0 +1,21 @@
+package dev.inmo.saucenaoapi.utils
+
+import kotlinx.coroutines.supervisorScope
+
+interface SauceCloseable {
+    fun close()
+}
+
+fun <T> SauceCloseable.use(block: (SauceCloseable) -> T): T = try {
+    block(this)
+} finally {
+    close()
+}
+
+suspend fun <T> SauceCloseable.useSafe(block: suspend (SauceCloseable) -> T): T = try {
+    supervisorScope {
+        block(this@useSafe)
+    }
+} finally {
+    close()
+}

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

@@ -0,0 +1,18 @@
+package dev.inmo.saucenaoapi.utils
+
+import dev.inmo.saucenaoapi.additional.LONG_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.additional.SHORT_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.models.Header
+import com.soywiz.klock.DateTime
+
+internal suspend fun calculateSleepTime(
+    header: Header,
+    mostOldestInShortPeriodGetter: suspend () -> DateTime?,
+    mostOldestInLongPeriodGetter: suspend () -> DateTime?
+): DateTime? {
+    return when {
+        header.longRemaining < 1 -> mostOldestInLongPeriodGetter() ?.plus(LONG_TIME_RECALCULATING_MILLIS)
+        header.shortRemaining < 1 -> mostOldestInShortPeriodGetter() ?.plus(SHORT_TIME_RECALCULATING_MILLIS)
+        else -> null
+    }
+}

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

@@ -0,0 +1,103 @@
+package dev.inmo.saucenaoapi.utils
+
+import dev.inmo.saucenaoapi.additional.LONG_TIME_RECALCULATING_MILLIS
+import dev.inmo.saucenaoapi.additional.SHORT_TIME_RECALCULATING_MILLIS
+import com.soywiz.klock.DateTime
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.launch
+import kotlin.coroutines.Continuation
+import kotlin.coroutines.suspendCoroutine
+
+private fun MutableList<DateTime>.clearTooOldTimes(relatedTo: DateTime = DateTime.now()) {
+    val limitValue = relatedTo - LONG_TIME_RECALCULATING_MILLIS
+
+    removeAll {
+        it < limitValue
+    }
+}
+
+private interface TimeManagerAction {
+    suspend fun makeChangeWith(times: MutableList<DateTime>)
+    suspend operator fun invoke(times: MutableList<DateTime>) = makeChangeWith(times)
+}
+
+private data class TimeManagerClean(private val relatedTo: DateTime = DateTime.now()) : TimeManagerAction {
+    override suspend fun makeChangeWith(times: MutableList<DateTime>) {
+        times.clearTooOldTimes(relatedTo)
+    }
+}
+
+private data class TimeManagerTimeAdder(
+    private val time: DateTime = DateTime.now()
+) : TimeManagerAction {
+    override suspend fun makeChangeWith(times: MutableList<DateTime>) {
+        times.add(time)
+        times.clearTooOldTimes()
+    }
+}
+
+private data class TimeManagerMostOldestInLongGetter(
+    private val continuation: Continuation<DateTime?>
+) : TimeManagerAction {
+    override suspend fun makeChangeWith(times: MutableList<DateTime>) {
+        times.clearTooOldTimes()
+        continuation.resumeWith(Result.success(times.minOrNull()))
+    }
+}
+
+private data class TimeManagerMostOldestInShortGetter(
+    private val continuation: Continuation<DateTime?>
+) : TimeManagerAction {
+    override suspend fun makeChangeWith(times: MutableList<DateTime>) {
+        times.clearTooOldTimes()
+
+        val now = DateTime.now()
+
+        val limitTime = now - SHORT_TIME_RECALCULATING_MILLIS
+
+        continuation.resumeWith(
+            Result.success(
+                times.asSequence().filter {
+                    limitTime < it
+                }.minOrNull()
+            )
+        )
+    }
+}
+
+internal class TimeManager(
+    scope: CoroutineScope
+) : SauceCloseable {
+    private val actionsChannel = Channel<TimeManagerAction>(Channel.UNLIMITED)
+
+    private val timeUpdateJob = scope.launch {
+        val times = mutableListOf<DateTime>()
+        for (action in actionsChannel) {
+            action(times)
+        }
+    }
+
+    suspend fun addTimeAndClear() {
+        actionsChannel.send(TimeManagerTimeAdder())
+    }
+
+    suspend fun getMostOldestInLongPeriod(): DateTime? {
+        return suspendCoroutine {
+            actionsChannel.offer(
+                TimeManagerMostOldestInLongGetter(it)
+            )
+        }
+    }
+
+    suspend fun getMostOldestInShortPeriod(): DateTime? {
+        return suspendCoroutine {
+            actionsChannel.offer(TimeManagerMostOldestInShortGetter(it))
+        }
+    }
+
+    override fun close() {
+        actionsChannel.close()
+        timeUpdateJob.cancel()
+    }
+}