HTTP Client Management

/**
 * Creates an HttpClient with the default engine for the current platform
 * @param block Configuration block for the client
 * @return Configured HttpClient instance
 */
expect fun HttpClient(
    block: HttpClientConfig<*>.() -> Unit = {}
): HttpClient

/**
 * Creates an HttpClient with a specific engine factory
 * @param engineFactory The engine factory to use
 * @param block Configuration block for the client
 * @return Configured HttpClient instance
 */
fun <T : HttpClientEngineConfig> HttpClient(
    engineFactory: HttpClientEngineFactory<T>,
    block: HttpClientConfig<T>.() -> Unit = {}
): HttpClient

/**
 * Creates an HttpClient with a pre-configured engine instance
 * @param engine The engine instance to use
 * @param block Configuration block for the client
 * @return Configured HttpClient instance
 */
fun HttpClient(
    engine: HttpClientEngine,
    block: HttpClientConfig<*>.() -> Unit
): HttpClient

import io.ktor.client.*

// Default client with platform-specific engine
val client = HttpClient()

// Client with configuration
val configuredClient = HttpClient {
    followRedirects = false
    expectSuccess = true
}

// Client with specific engine (example for JVM)
val jvmClient = HttpClient(CIO) {
    engine {
        threadsCount = 4
        pipelining = true
    }
}

/**
 * Main HTTP client class providing HTTP request capabilities
 */
class HttpClient(
    val engine: HttpClientEngine,
    private val userConfig: HttpClientConfig<out HttpClientEngineConfig>
) : CoroutineScope, Closeable {
    
    /** Request processing pipeline */
    val requestPipeline: HttpRequestPipeline
    
    /** Response processing pipeline */
    val responsePipeline: HttpResponsePipeline
    
    /** Send pipeline for outgoing content */
    val sendPipeline: HttpSendPipeline
    
    /** Receive pipeline for incoming content */
    val receivePipeline: HttpReceivePipeline
    
    /** Client attributes for storing metadata */
    val attributes: Attributes
    
    /** Engine configuration */
    val engineConfig: HttpClientEngineConfig
    
    /** Event monitor for client events */
    val monitor: Events
    
    /**
     * Check if the client supports a specific capability
     * @param capability The capability to check
     * @return true if supported, false otherwise
     */
    fun isSupported(capability: HttpClientEngineCapability<*>): Boolean
    
    /**
     * Create a new client with additional configuration
     * @param block Configuration block to apply
     * @return New HttpClient instance with combined configuration
     */
    fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient
    
    /**
     * Close the client and release resources
     * Must be called when the client is no longer needed
     */
    override fun close()
}

import io.ktor.client.*
import io.ktor.client.request.*

val client = HttpClient()

// Check engine capabilities
if (client.isSupported(WebSocketCapability)) {
    // Use WebSocket functionality
}

// Create derived client with additional config
val derivedClient = client.config {
    install(HttpTimeout) {
        requestTimeoutMillis = 5000
    }
}

// Always close clients when done
client.close()
derivedClient.close()

/**
 * Configuration builder for HttpClient
 */
class HttpClientConfig<T : HttpClientEngineConfig> {
    
    /** Whether to follow HTTP redirects automatically */
    var followRedirects: Boolean = true
    
    /** Whether to use default request/response transformers */
    var useDefaultTransformers: Boolean = true
    
    /** Whether to expect successful responses (2xx status codes) */
    var expectSuccess: Boolean = false
    
    /**
     * Configure the HTTP engine
     * @param block Configuration block for the engine
     */
    fun engine(block: T.() -> Unit)
    
    /**
     * Install a plugin with configuration
     * @param plugin The plugin to install
     * @param configure Configuration block for the plugin
     */
    fun <TBuilder : Any, TPlugin : Any> install(
        plugin: HttpClientPlugin<TBuilder, TPlugin>,
        configure: TBuilder.() -> Unit = {}
    )
    
    /**
     * Install a plugin by key with custom installation logic
     * @param key String identifier for the plugin
     * @param block Installation logic
     */
    fun install(key: String, block: HttpClient.() -> Unit)
}

import io.ktor.client.*
import io.ktor.client.plugins.*

val client = HttpClient {
    // Basic configuration
    followRedirects = false
    expectSuccess = true
    useDefaultTransformers = true
    
    // Engine configuration (platform-specific)
    engine {
        threadsCount = 2
        pipelining = false
    }
    
    // Plugin installation
    install(HttpTimeout) {
        requestTimeoutMillis = 30000
        connectTimeoutMillis = 10000
    }
    
    install(UserAgent) {
        agent = "MyApp/1.0"
    }
}

/**
 * Get an installed plugin, returning null if not installed
 * @param plugin The plugin to retrieve
 * @return Plugin instance or null if not installed
 */
fun <B : Any, F : Any> HttpClient.pluginOrNull(
    plugin: HttpClientPlugin<B, F>
): F?

/**
 * Get an installed plugin, throwing an exception if not installed
 * @param plugin The plugin to retrieve
 * @return Plugin instance
 * @throws IllegalStateException if plugin is not installed
 */
fun <B : Any, F : Any> HttpClient.plugin(
    plugin: HttpClientPlugin<B, F>
): F

import io.ktor.client.*
import io.ktor.client.plugins.*

val client = HttpClient {
    install(HttpTimeout) {
        requestTimeoutMillis = 5000
    }
}

// Safe access to plugin
val timeoutPlugin = client.pluginOrNull(HttpTimeout)
if (timeoutPlugin != null) {
    // Use plugin
}

// Direct access (throws if not installed)
val timeout = client.plugin(HttpTimeout)

/**
 * Events interface for monitoring client activities
 */
interface Events {
    fun <T> subscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
    fun <T> unsubscribe(definition: EventDefinition<T>, handler: (T) -> Unit)
    fun <T> raise(definition: EventDefinition<T>, value: T)
}

/**
 * Event definition for type-safe event handling
 */
interface EventDefinition<T>

/**
 * Client monitoring events
 */
val HttpRequestCreated: EventDefinition<HttpRequestBuilder>
val HttpRequestIsReadyForSending: EventDefinition<HttpRequestBuilder>
val HttpResponseReceived: EventDefinition<HttpResponse>
val HttpResponseCancelled: EventDefinition<HttpResponse>
val HttpResponseReceiveFailed: EventDefinition<HttpResponseReceiveFail>

/**
 * Event data for failed response reception
 */
class HttpResponseReceiveFail(
    val response: HttpResponse,
    val cause: Throwable
)