Core Client Operations

/**
 * A multiplatform asynchronous HTTP client that allows you to make requests, handle responses,
 * and extend its functionality with plugins such as authentication, JSON serialization, and more.
 */
class HttpClient(
    engine: HttpClientEngine,
    userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig()
) : CoroutineScope, Closeable {
    /** The underlying HTTP engine */
    val engine: HttpClientEngine
    
    /** Pipeline for processing all requests sent by this client */
    val requestPipeline: HttpRequestPipeline
    
    /** Pipeline for processing all responses sent by the server */
    val responsePipeline: HttpResponsePipeline
    
    /** Pipeline for sending requests */
    val sendPipeline: HttpSendPipeline
    
    /** Pipeline for receiving responses */
    val receivePipeline: HttpReceivePipeline
    
    /** Typed attributes used as a lightweight container for this client */
    val attributes: Attributes
    
    /** Access to the client's engine configuration */
    val engineConfig: HttpClientEngineConfig
    
    /** Access to the events of the client's lifecycle */
    val monitor: Events
    
    /**
     * Initiates the shutdown process for the HttpClient. This is a non-blocking call.
     */
    fun close()
    
    /**
     * Returns a new HttpClient by copying this client's configuration
     * and additionally configured by the block parameter.
     */
    fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient
    
    /**
     * Checks if the specified capability is supported by this client.
     */
    fun isSupported(capability: HttpClientEngineCapability<*>): Boolean
}

/**
 * Creates an HttpClient using a service loader mechanism to determine the appropriate 
 * default engine. On JVM, this can introduce performance overhead.
 */
expect fun HttpClient(block: HttpClientConfig<*>.() -> Unit = {}): HttpClient

/**
 * Creates an HttpClient with a specific engine factory.
 */
fun <T : HttpClientEngineConfig> HttpClient(
    engineFactory: HttpClientEngineFactory<T>,
    block: HttpClientConfig<T>.() -> Unit = {}
): HttpClient

/**
 * Creates an HttpClient with an existing engine instance.
 */
fun HttpClient(
    engine: HttpClientEngine,
    block: HttpClientConfig<*>.() -> Unit
): HttpClient

/**
 * Configuration builder for HttpClient
 */
class HttpClientConfig<T : HttpClientEngineConfig> {
    /** Enable/disable automatic redirect following */
    var followRedirects: Boolean
    
    /** Enable/disable default response transformers */
    var useDefaultTransformers: Boolean
    
    /** Enable/disable automatic HTTP status validation */
    var expectSuccess: Boolean
    
    /**
     * Configure the underlying HTTP engine
     */
    fun engine(block: T.() -> Unit)
    
    /**
     * Install a plugin into the client
     */
    fun <TBuilder : Any, TPlugin : Any> install(
        plugin: HttpClientPlugin<TBuilder, TPlugin>,
        configure: TBuilder.() -> Unit = {}
    ): TPlugin
    
    /**
     * Install a custom interceptor with the given key
     */
    fun install(key: String, block: HttpClient.() -> Unit)
}

/**
 * Get an installed plugin instance (nullable)
 */
fun <TBuilder : Any, TPlugin : Any> HttpClient.pluginOrNull(
    plugin: HttpClientPlugin<TBuilder, TPlugin>
): TPlugin?

/**
 * Get an installed plugin instance (throws if not found)
 */
fun <TBuilder : Any, TPlugin : Any> HttpClient.plugin(
    plugin: HttpClientPlugin<TBuilder, TPlugin>
): TPlugin

import io.ktor.client.*
import io.ktor.client.engine.apache.*
import io.ktor.client.plugins.*

// Create client with default engine (uses ServiceLoader on JVM)
val client = HttpClient {
    followRedirects = true
    expectSuccess = true
}

// Create client with specific engine
val apacheClient = HttpClient(Apache) {
    engine {
        socketTimeout = 10000
        connectTimeout = 5000
    }
    
    // Configure client features
    followRedirects = false
    useDefaultTransformers = true
}

// Create client with engine instance
val engine = Apache.create {
    socketTimeout = 15000
}
val customClient = HttpClient(engine) {
    expectSuccess = false
}

// Check engine capabilities
if (client.isSupported(SomeCapability)) {
    // Use capability-specific functionality
}

// Create configured copy
val configuredClient = client.config {
    expectSuccess = false
    install(SomePlugin) {
        // Plugin configuration
    }
}

// Cleanup
client.close()
apacheClient.close()
customClient.close()
configuredClient.close()

// For proper resource cleanup in coroutines
client.coroutineContext[Job]?.join() // Wait for completion

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

/** Event raised when an HTTP request is created */
val HttpRequestCreated: EventDefinition<HttpRequestBuilder>

/** Event raised when an HTTP response is received */
val HttpResponseReceived: EventDefinition<HttpResponse>

/** Event raised when HTTP response receiving fails */
val HttpResponseReceiveFailed: EventDefinition<HttpResponseReceiveFail>

/**
 * ServiceLoader container for client engine discovery on JVM
 */
interface HttpClientEngineContainer {
    val factory: HttpClientEngineFactory<*>
}

/**
 * Base class for HTTP response exceptions
 */
abstract class ResponseException(
    response: HttpResponse,
    cachedResponseText: String,
    cause: Throwable? = null
) : IllegalStateException() {
    val response: HttpResponse
}

/**
 * Thrown for 4xx HTTP status codes
 */
class ClientRequestException(
    response: HttpResponse,
    cachedResponseText: String
) : ResponseException(response, cachedResponseText)

/**
 * Thrown for 5xx HTTP status codes
 */
class ServerResponseException(
    response: HttpResponse,
    cachedResponseText: String
) : ResponseException(response, cachedResponseText)

/**
 * Thrown for 3xx HTTP status codes when redirects are not followed
 */
class RedirectResponseException(
    response: HttpResponse,
    cachedResponseText: String
) : ResponseException(response, cachedResponseText)