⚡️ [AI]: Refactor HTTP client with pluggable HttpEngine abstraction

Extract HTTP layer into HttpEngine interface for better testability
and custom engine support (OkHttp, Ktor, etc.)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: junerver

ai/src/commonMain/kotlin/xyz/junerver/compose/ai/BaseAIOptions.kt

@@ -3,6 +3,7 @@ package xyz.junerver.compose.ai
 import io.ktor.client.statement.HttpResponse
 import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
+import xyz.junerver.compose.ai.http.HttpEngine
 import xyz.junerver.compose.ai.usechat.ChatProvider
 import xyz.junerver.compose.ai.usechat.Providers
 
@@ -35,6 +36,7 @@ typealias OnErrorCallback = (error: Throwable) -> Unit
  * @property maxTokens Maximum number of tokens to generate
  * @property timeout Request timeout duration
  * @property headers Additional HTTP headers to send with requests
+ * @property httpEngine Custom HTTP engine (null = use global default)
  * @property onResponse Callback when receiving an HTTP response
  * @property onError Callback when an error occurs
  */
@@ -46,6 +48,7 @@ interface BaseAIOptions {
     var maxTokens: Int?
     var timeout: Duration
     var headers: Map<String, String>
+    var httpEngine: HttpEngine?
     var onResponse: OnResponseCallback?
     var onError: OnErrorCallback?
 

ai/src/commonMain/kotlin/xyz/junerver/compose/ai/http/HttpEngine.kt

@@ -0,0 +1,104 @@
+package xyz.junerver.compose.ai.http
+
+import kotlinx.coroutines.flow.Flow
+
+/*
+  Description: HTTP engine abstraction for AI module
+  Author: Junerver
+  Date: 2026/01/06
+  Email: junerver@gmail.com
+  Version: v1.0
+*/
+
+/**
+ * HTTP request parameters.
+ *
+ * @property url The full URL to request
+ * @property headers HTTP headers to send
+ * @property body Request body (JSON string)
+ * @property timeout Request timeout in milliseconds
+ */
+data class HttpRequest(
+    val url: String,
+    val headers: Map<String, String> = emptyMap(),
+    val body: String? = null,
+    val timeout: Long = 60_000L,
+)
+
+/**
+ * HTTP response result.
+ *
+ * @property statusCode HTTP status code
+ * @property body Response body as string
+ */
+data class HttpResult(
+    val statusCode: Int,
+    val body: String,
+)
+
+/**
+ * Server-Sent Events (SSE) event types.
+ */
+sealed class SseEvent {
+    /**
+     * A data line received from SSE stream.
+     */
+    data class Data(val line: String) : SseEvent()
+
+    /**
+     * Stream completed successfully.
+     */
+    data object Complete : SseEvent()
+
+    /**
+     * An error occurred during streaming.
+     */
+    data class Error(val error: Throwable) : SseEvent()
+}
+
+/**
+ * HTTP engine abstraction interface.
+ *
+ * Allows users to provide custom HTTP implementations (e.g., OkHttp)
+ * instead of the default Ktor implementation.
+ *
+ * Example custom implementation:
+ * ```kotlin
+ * class OkHttpEngine(private val client: OkHttpClient) : HttpEngine {
+ *     override suspend fun execute(request: HttpRequest): HttpResult {
+ *         // Use OkHttp to execute request
+ *     }
+ *     override suspend fun executeStream(request: HttpRequest): Flow<SseEvent> = flow {
+ *         // Use OkHttp SSE implementation
+ *     }
+ *     override fun close() {
+ *         client.dispatcher.executorService.shutdown()
+ *     }
+ * }
+ * ```
+ */
+interface HttpEngine {
+    /**
+     * Executes a standard HTTP request.
+     *
+     * @param request The HTTP request to execute
+     * @return The HTTP response result
+     */
+    suspend fun execute(request: HttpRequest): HttpResult
+
+    /**
+     * Executes an SSE streaming request.
+     *
+     * The returned Flow emits [SseEvent.Data] for each line received,
+     * [SseEvent.Complete] when the stream ends, and [SseEvent.Error] on errors.
+     *
+     * @param request The HTTP request to execute (with SSE headers)
+     * @return A Flow of SSE events
+     */
+    suspend fun executeStream(request: HttpRequest): Flow<SseEvent>
+
+    /**
+     * Closes the HTTP engine and releases resources.
+     */
+    fun close()
+}

ai/src/commonMain/kotlin/xyz/junerver/compose/ai/http/HttpEngineConfig.kt

@@ -0,0 +1,40 @@
+package xyz.junerver.compose.ai.http
+
+/*
+  Description: Global HTTP engine configuration
+  Author: Junerver
+  Date: 2026/01/06
+  Email: junerver@gmail.com
+  Version: v1.0
+*/
+
+/**
+ * Global configuration for HTTP engine.
+ *
+ * Use this to set a custom HTTP engine globally for all AI hooks.
+ *
+ * Example - Replace with OkHttp:
+ * ```kotlin
+ * // In your Application initialization
+ * HttpEngineConfig.defaultEngineFactory = { OkHttpEngine(myOkHttpClient) }
+ * ```
+ *
+ * Example - Add custom interceptors:
+ * ```kotlin
+ * HttpEngineConfig.defaultEngineFactory = {
+ *     KtorHttpEngine(HttpClient {
+ *         install(HttpTimeout) { ... }
+ *         install(Logging) { ... }
+ *     })
+ * }
+ * ```
+ */
+object HttpEngineConfig {
+    /**
+     * Factory function to create the default HTTP engine.
+     *
+     * Override this to use a custom HTTP engine globally.
+     * Default: Creates a new [KtorHttpEngine] instance.
+     */
+    var defaultEngineFactory: () -> HttpEngine = { KtorHttpEngine() }
+}

ai/src/commonMain/kotlin/xyz/junerver/compose/ai/http/KtorHttpEngine.kt

@@ -0,0 +1,117 @@
+package xyz.junerver.compose.ai.http
+
+import io.ktor.client.HttpClient
+import io.ktor.client.plugins.HttpTimeout
+import io.ktor.client.plugins.logging.LogLevel
+import io.ktor.client.plugins.logging.Logger
+import io.ktor.client.plugins.logging.Logging
+import io.ktor.client.plugins.logging.SIMPLE
+import io.ktor.client.plugins.timeout
+import io.ktor.client.request.header
+import io.ktor.client.request.post
+import io.ktor.client.request.preparePost
+import io.ktor.client.request.setBody
+import io.ktor.client.statement.bodyAsChannel
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.ContentType
+import io.ktor.http.HttpHeaders
+import io.ktor.http.contentType
+import io.ktor.http.isSuccess
+import io.ktor.http.withCharset
+import io.ktor.utils.io.charsets.Charsets
+import io.ktor.utils.io.readUTF8Line
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.flow
+
+/*
+  Description: Ktor-based default HTTP engine implementation
+  Author: Junerver
+  Date: 2026/01/06
+  Email: junerver@gmail.com
+  Version: v1.0
+*/
+
+/**
+ * Default HTTP engine implementation using Ktor.
+ *
+ * This is the default engine used when no custom engine is provided.
+ * Uses Ktor's CIO engine on JVM/Android and Darwin engine on iOS.
+ *
+ * @param client Optional custom HttpClient instance. If not provided,
+ *               a default client with timeout and logging will be created.
+ */
+class KtorHttpEngine(
+    private val client: HttpClient = createDefaultClient(),
+) : HttpEngine {
+    companion object {
+        /**
+         * Creates a default HttpClient with basic configuration.
+         */
+        fun createDefaultClient(): HttpClient = HttpClient {
+            install(HttpTimeout)
+            install(Logging) {
+                logger = Logger.SIMPLE
+                level = LogLevel.ALL
+            }
+        }
+    }
+
+    override suspend fun execute(request: HttpRequest): HttpResult {
+        val response = client.post(request.url) {
+            timeout {
+                requestTimeoutMillis = request.timeout
+                connectTimeoutMillis = request.timeout
+                socketTimeoutMillis = request.timeout
+            }
+            contentType(ContentType.Application.Json.withCharset(Charsets.UTF_8))
+            request.headers.forEach { (key, value) ->
+                header(key, value)
+            }
+            request.body?.let { setBody(it) }
+        }
+
+        return HttpResult(
+            statusCode = response.status.value,
+            body = response.bodyAsText(),
+        )
+    }
+
+    override suspend fun executeStream(request: HttpRequest): Flow<SseEvent> = flow {
+        try {
+            client.preparePost(request.url) {
+                // SSE streams need longer/no timeout
+                timeout {
+                    requestTimeoutMillis = Long.MAX_VALUE
+                    socketTimeoutMillis = Long.MAX_VALUE
+                }
+                contentType(ContentType.Application.Json.withCharset(Charsets.UTF_8))
+                header(HttpHeaders.Accept, "text/event-stream")
+                header(HttpHeaders.CacheControl, "no-cache")
+                header(HttpHeaders.Connection, "keep-alive")
+                request.headers.forEach { (key, value) ->
+                    header(key, value)
+                }
+                request.body?.let { setBody(it) }
+            }.execute { response ->
+                if (!response.status.isSuccess()) {
+                    val errorBody = response.bodyAsChannel().readUTF8Line() ?: "Unknown error"
+                    emit(SseEvent.Error(Exception("HTTP ${response.status.value}: $errorBody")))
+                    return@execute
+                }
+
+                val channel = response.bodyAsChannel()
+                while (!channel.isClosedForRead) {
+                    val line = channel.readUTF8Line() ?: continue
+                    emit(SseEvent.Data(line))
+                }
+                emit(SseEvent.Complete)
+            }
+        } catch (e: Exception) {
+            emit(SseEvent.Error(e))
+        }
+    }
+
+    override fun close() {
+        client.close()
+    }
+}