Kotlin Multiplatform

plugins {
    // …plugins from the KMP project template
    kotlin("plugin.serialization") // same version as Kotlin
}

// Versions live in gradle.properties: Ktor 3.x, kotlinx-coroutines, kotlinx-serialization.
val ktorVersion: String by project
val coroutinesVersion: String by project
val serializationVersion: String by project

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.ktor:ktor-client-core:$ktorVersion")
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutinesVersion")
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:$serializationVersion")
        }
        androidMain.dependencies {
            implementation("io.ktor:ktor-client-okhttp:$ktorVersion")
        }
        iosMain.dependencies {
            implementation("io.ktor:ktor-client-darwin:$ktorVersion")
        }
    }
}

package analytics

/** Platform key from the Integration tab: Android and iOS have different keys. */
internal expect val writeKey: String

/** Device and build context; platform is "android" or "ios". */
internal expect fun deviceContext(): EventContext

internal expect fun loadInstallId(): String?
internal expect fun saveInstallId(id: String)

/** Contents of the queue file, or null if the file doesn't exist yet. */
internal expect fun readQueue(): String?
internal expect fun writeQueue(json: String)

package analytics

import kotlin.uuid.ExperimentalUuidApi
import kotlin.uuid.Uuid

@OptIn(ExperimentalUuidApi::class)
internal object InstallId {
    /** Created on first launch and kept permanently. */
    val current: String by lazy {
        loadInstallId() ?: Uuid.random().toString().also(::saveInstallId)
    }
}

package analytics

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

@Serializable
internal data class EventContext(
    val platform: String,
    @SerialName("os_name") val osName: String,
    @SerialName("os_version") val osVersion: String,
    @SerialName("app_version") val appVersion: String,
    @SerialName("app_build") val appBuild: String,
    @SerialName("device_model") val deviceModel: String,
    @SerialName("device_type") val deviceType: String,
    val locale: String,
    val environment: String,
)

/** user_id and duration_ms set to null are left out of the JSON: encodeDefaults is off. */
@Serializable
internal data class Event(
    @SerialName("insert_id") val insertId: String,
    val name: String,
    val timestamp: String, // RFC 3339 in UTC: Clock.System.now().toString()
    @SerialName("install_id") val installId: String,
    @SerialName("session_id") val sessionId: String,
    @SerialName("user_id") val userId: String? = null,
    @SerialName("duration_ms") val durationMs: Long? = null,
    val context: EventContext,
)

@Serializable
internal class Batch(@SerialName("sent_at") val sentAt: String, val events: List<Event>)

@Serializable
internal class IngestResult(val rejected: List<Rejection> = emptyList()) {
    @Serializable
    class Rejection(
        @SerialName("insert_id") val insertId: String? = null,
        val retryable: Boolean = false,
    )
}

package analytics

import io.ktor.client.HttpClient
import io.ktor.client.plugins.HttpTimeout
import io.ktor.client.request.header
import io.ktor.client.request.post
import io.ktor.client.request.setBody
import io.ktor.client.statement.bodyAsText
import io.ktor.http.ContentType
import io.ktor.http.contentType
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.serialization.builtins.ListSerializer
import kotlinx.serialization.json.Json
import kotlin.random.Random
import kotlin.time.Clock
import kotlin.time.Duration.Companion.days
import kotlin.time.Instant

internal object EventQueue {
    private const val ENDPOINT = "https://i.analytics.example.com/v1/events"
    private const val MAX_BATCH = 500

    private val json = Json { ignoreUnknownKeys = true }
    private val listSerializer = ListSerializer(Event.serializer())
    // Ktor takes the engine — OkHttp or Darwin — from the platform's dependencies.
    private val client = HttpClient { install(HttpTimeout) { requestTimeoutMillis = 15_000 } }
    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default.limitedParallelism(1))

    // Read on first access — already in the background, on the queue's dispatcher.
    private val events: MutableList<Event> by lazy {
        val saved = readQueue() ?: return@lazy mutableListOf()
        runCatching { json.decodeFromString(listSerializer, saved) }.getOrDefault(emptyList())
            .toMutableList() // a corrupted file means an empty queue
    }
    private var sending = false
    private var stopped = false
    private var retryAtMs = 0L
    private var backoffMs = 1_000L

    fun enqueue(event: Event) {
        scope.launch {
            events += event
            save() // disk first: the event survives the app being closed
            flushNow()
        }
    }

    fun flush() {
        scope.launch { flushNow() }
    }

    private suspend fun flushNow() {
        val minTime = Clock.System.now() - 7.days
        events.removeAll { Instant.parse(it.timestamp) < minTime }
        val now = Clock.System.now().toEpochMilliseconds()
        if (sending || stopped || events.isEmpty() || now < retryAtMs) return
        sending = true

        val batch = events.take(MAX_BATCH)
        val sent = batch.map { it.insertId }.toSet()
        try {
            // sent_at is this attempt's time: the server uses it to correct a skewed device clock.
            val body = Batch(sentAt = Clock.System.now().toString(), events = batch)
            val response = client.post(ENDPOINT) {
                contentType(ContentType.Application.Json)
                header("X-App-Key", writeKey)
                setBody(json.encodeToString(Batch.serializer(), body))
            }
            when (response.status.value) {
                200 -> {
                    val text = response.bodyAsText()
                    val result = json.decodeFromString(IngestResult.serializer(), text)
                    val retry = result.rejected.filter { it.retryable }.mapNotNull { it.insertId }
                    val done = sent - retry.toSet()
                    events.removeAll { it.insertId in done }
                    backoffMs = 1_000L
                    if (retry.isNotEmpty()) retryLater(60_000L)
                }
                400, 413, 415 -> events.removeAll { it.insertId in sent } // retrying won't help
                401, 403 -> stopped = true // key revoked or app archived
                429, 503 -> {
                    val seconds = response.headers["Retry-After"]?.toLongOrNull() ?: 5L
                    retryLater(seconds * 1_000L)
                }
                else -> backoff()
            }
        } catch (e: Exception) { // network error, timeout, unexpected response
            backoff()
        } finally {
            sending = false
            save()
        }
    }

    private fun backoff() {
        retryLater((backoffMs * Random.nextDouble(0.8, 1.2)).toLong())
        backoffMs = minOf(backoffMs * 2, 300_000L)
    }

    private fun retryLater(delayMs: Long) {
        retryAtMs = Clock.System.now().toEpochMilliseconds() + delayMs
        scope.launch {
            delay(delayMs)
            flushNow()
        }
    }

    private fun save() = writeQueue(json.encodeToString(listSerializer, events))
}

package analytics

import kotlin.time.Clock
import kotlin.time.TimeSource
import kotlin.uuid.ExperimentalUuidApi
import kotlin.uuid.Uuid

/** Session tracker for Android and iOS. Call start() and end() from the main thread. */
@OptIn(ExperimentalUuidApi::class)
object SessionTracker {
    /** Account ID after sign-in; null if the user isn't signed in. Not an email or phone number. */
    var userId: String? = null

    private var sessionId: String? = null
    private var startedAt = TimeSource.Monotonic.markNow()

    fun start() {
        if (sessionId != null) return
        val id = Uuid.random().toString()
        sessionId = id
        startedAt = TimeSource.Monotonic.markNow()
        track("session_start", id, durationMs = null)
    }

    fun end() {
        val id = sessionId ?: return
        val elapsed = startedAt.elapsedNow().inWholeMilliseconds
        track("session_end", id, durationMs = elapsed.coerceIn(0L, 86_400_000L))
        sessionId = null
    }

    /** Sends the events left in the queue from previous launches. */
    fun flush() = EventQueue.flush()

    private fun track(name: String, sessionId: String, durationMs: Long?) {
        EventQueue.enqueue(
            Event(
                insertId = Uuid.random().toString(),
                name = name,
                timestamp = Clock.System.now().toString(),
                installId = InstallId.current,
                sessionId = sessionId,
                userId = userId,
                durationMs = durationMs,
                context = deviceContext(),
            ),
        )
    }
}