KitsuneNET on every platform

1. Zależność i wybór silnika1. Dependency and engine selection

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("rip.nerd.kitsunenet:kitsunenet-core:3.0.0")
        }
        androidMain.dependencies {
            // Optional legacy OkHttp/WebSocket/GraphQL adapter.
            implementation("rip.nerd.kitsunenet:kitsunenet:3.0.0")
        }
    }
}

Wariant kitsunenet-core używa Ktor Android na Androidzie, CIO na JVM/Desktop, Darwin na iOS i JS na Web/Wasm. Nie wpisuj ręcznie artefaktów z sufiksem platformy. Dla snapshotu użyj spójnie 3.0.1-SNAPSHOT.

kitsunenet-core uses Ktor Android on Android, CIO on JVM/Desktop, Darwin on iOS and JS on Web/Wasm. Never declare platform-suffixed artifacts directly. Use 3.0.1-SNAPSHOT consistently for the snapshot channel.

2. commonMain

class StatusApi(private val client: KitsuneNetClient = KitsuneNetClient()) : AutoCloseable {
    suspend fun load(): NetResult = client.execute(
        NetRequest(
            url = "https://api.example/status",
            headers = mapOf("Accept" to "application/json"),
            maxResponseBodyBytes = 256L * 1024L
        )
    )

    override fun close() = client.close()
}

when (val result = api.load()) {
    is NetResult.Success -> render(result.response.body)
    is NetResult.HttpError -> showHttpError(result.response.status)
    is NetResult.NetworkError -> showOffline(result.message)
    is NetResult.Rejected -> showBlocked(result.reason)
}

HttpError to odpowiedź spoza 2xx, NetworkError to błąd transportu, a Rejected oznacza circuit breaker albo politykę klienta.

HttpError is a non-2xx response, NetworkError is a transport failure, and Rejected represents the circuit breaker or a client policy.

3. Android, iOS, Desktop i Web3. Android, iOS, Desktop and Web

val client = KitsuneNetClient(
    retryPolicy = RetryPolicy(maxAttempts = 3),
    circuitBreaker = CircuitBreaker(failureThreshold = 5)
)

Biblioteka respektuje zabezpieczenia hosta i ich nie obchodzi.

The library respects host security policies and does not bypass them.

4. Własny transport4. Custom transport

class AppTransport(private val sdk: AppHttpSdk) : NetTransport {
    override suspend fun execute(request: NetRequest): NetResponse = sdk.execute(request)
}

val client = KitsuneNetClient(transport = AppTransport(platformSdk))

Użyj tego dla własnego NSURLSession, klienta firmowego, mocka lub mostka JavaScript. Transport musi respektować timeoutMillis, maxResponseBodyBytes i anulowanie coroutine; anulowania nie wolno zamieniać w NetworkError.

Use this for an application-owned NSURLSession, enterprise client, mock or JavaScript bridge. The transport must respect timeoutMillis, maxResponseBodyBytes and coroutine cancellation; cancellation must not become NetworkError.

5. Kolejka offline5. Offline queue

val queue = PersistentRequestQueue(
    storage = appQueueStorage,
    maxEntries = 100,
    maxAttempts = 5
)
queue.enqueue(
    NetRequest(
        url = "https://api.example/events",
        method = NetMethod.POST,
        body = payload,
        idempotent = true
    ),
    priority = 10
)
val report = queue.drain(client)

class DatabaseQueueStorage(private val db: QueueDatabase) : NetQueueStorage {
    override suspend fun load() = db.readRequests()
    override suspend fun save(entries: List<QueuedNetRequest>) = db.replaceRequests(entries)
}

Produkcyjny NetQueueStorage może używać Room/DataStore na Androidzie, pliku lub SQLDelight na iOS/Desktop i IndexedDB na Web. MemoryNetQueueStorage służy do testów albo sesji bez trwałości.

A production NetQueueStorage may use Room/DataStore on Android, a file or SQLDelight on iOS/Desktop, and IndexedDB on Web. MemoryNetQueueStorage is for tests or non-persistent sessions.

6. Cache i brak odpowiednika6. Cache and missing equivalents

ResponseCache jest otwartym punktem rozszerzeń. Użyj MemoryResponseCache dla procesu albo zaimplementuj NSURLCache, plik, SQL lub IndexedDB. Brak providera oznacza brak trwałego cache, nie fikcyjne trafienie.

ResponseCache is an open extension point. Use MemoryResponseCache for process-local caching or implement NSURLCache, file, SQL or IndexedDB storage. No provider means no persistent cache, never a fake hit.

7. Weryfikacja platform7. Platform verification

Demo Android pokazuje starsze API i klienta KMP. Wspólne testy obejmują retry, limity, circuit breaker, kolejkę, cache i SSE. CI kompiluje Android/JVM/Wasm oraz trzy warianty iOS; testy symulatora uruchamia macOS.

The Android demo covers the legacy API and KMP client. Common tests cover retry, limits, circuit breaker, queue, cache and SSE. CI compiles Android/JVM/Wasm and all three iOS variants; simulator tests run on macOS.