HTTP Client Configuration

/**
 * Creates an HttpClient with default engine using service loader
 * @param block Configuration block for client settings
 * @returns Configured HttpClient instance
 */
fun HttpClient(block: HttpClientConfig<*>.() -> Unit = {}): HttpClient

/**
 * Creates an HttpClient with specified engine factory
 * @param engineFactory Factory for creating the HTTP engine
 * @param block Configuration block for engine-specific settings
 * @returns Configured HttpClient instance
 */
fun <T : HttpClientEngineConfig> HttpClient(
    engineFactory: HttpClientEngineFactory<T>,
    block: HttpClientConfig<T>.() -> Unit = {}
): HttpClient

/**
 * Creates an HttpClient with pre-configured engine instance
 * @param engine Pre-configured HTTP engine
 * @param block Configuration block for client settings
 * @returns Configured HttpClient instance
 */
fun HttpClient(
    engine: HttpClientEngine,
    block: HttpClientConfig<*>.() -> Unit
): HttpClient

// Basic client with default settings
val client = HttpClient()

// Client with configuration
val configuredClient = HttpClient {
    expectSuccess = true
    followRedirects = false
    
    install(HttpTimeout) {
        requestTimeoutMillis = 30000
        connectTimeoutMillis = 10000
    }
}

// Client with specific engine (requires engine dependency)
val engineClient = HttpClient(SomeEngine) {
    engine {
        // Engine-specific configuration
        threadsCount = 4
        pipelining = true
    }
}

/**
 * Configuration class for HttpClient with settings and plugin management
 */
class HttpClientConfig<T : HttpClientEngineConfig> {
    /** Whether to follow HTTP redirects automatically (default: true) */
    var followRedirects: Boolean
    
    /** Whether to use default body transformers (default: true) */
    var useDefaultTransformers: Boolean
    
    /** Whether to throw exceptions for non-successful HTTP status codes (default: false) */
    var expectSuccess: Boolean
    
    /**
     * Configure engine-specific settings
     * @param block Configuration block for the engine
     */
    fun engine(block: T.() -> Unit)
    
    /**
     * Install a plugin with optional 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 custom interceptor with a unique key
     * @param key Unique identifier for the interceptor
     * @param block Interceptor implementation
     */
    fun install(key: String, block: HttpClient.() -> Unit)
    
    /**
     * Create a copy of this configuration
     * @returns Cloned configuration
     */
    fun clone(): HttpClientConfig<T>
}

/**
 * Base configuration class for HTTP client engines
 */
open class HttpClientEngineConfig {
    /** Connection timeout in milliseconds */
    var connectTimeout: Long
    
    /** Socket timeout in milliseconds */
    var socketTimeout: Long
    
    /** Request timeout in milliseconds */
    var requestTimeout: Long
    
    /** Number of threads in the engine thread pool */
    var threadsCount: Int
    
    /** Whether to enable HTTP pipelining */
    var pipelining: Boolean
    
    /** Proxy configuration */
    var proxy: ProxyConfig?
}

/**
 * Proxy configuration for HTTP requests
 */
sealed class ProxyConfig {
    data class HttpProxy(
        val address: SocketAddress,
        val credentials: Credentials?
    ) : ProxyConfig()
    
    data class SocksProxy(
        val address: SocketAddress,
        val credentials: Credentials?
    ) : ProxyConfig()
}

/**
 * Proxy builder utilities
 */
object ProxyBuilder {
    /**
     * Create HTTP proxy configuration
     * @param url Proxy URL (e.g., "http://proxy.example.com:8080")
     * @returns HttpProxy configuration
     */
    fun http(url: String): ProxyConfig.HttpProxy
    
    /**
     * Create SOCKS proxy configuration
     * @param host Proxy host
     * @param port Proxy port
     * @returns SocksProxy configuration
     */
    fun socks(host: String, port: Int): ProxyConfig.SocksProxy
}

val client = HttpClient {
    // Basic configuration
    followRedirects = true
    expectSuccess = false
    useDefaultTransformers = true
    
    // Engine configuration
    engine {
        connectTimeout = 10000
        socketTimeout = 15000
        threadsCount = 4
        pipelining = true
        proxy = ProxyBuilder.http("http://proxy.example.com:8080")
    }
    
    // Install plugins
    install(HttpTimeout) {
        requestTimeoutMillis = 30000
        connectTimeoutMillis = 10000
        socketTimeoutMillis = 15000
    }
    
    install(HttpRedirect) {
        checkHttpMethod = true
        allowHttpsDowngrade = false
        maxJumps = 20
    }
}

/**
 * Create a new client by copying this client's configuration
 * @param block Additional configuration to apply
 * @returns New HttpClient instance
 */
fun HttpClient.config(block: HttpClientConfig<*>.() -> Unit): HttpClient

/**
 * Check if the client supports a specific engine capability
 * @param capability The capability to check
 * @returns True if supported, false otherwise
 */
fun HttpClient.isSupported(capability: HttpClientEngineCapability<*>): Boolean

/**
 * Close the client and release resources
 */
fun HttpClient.close()

val originalClient = HttpClient()

// Create a new client with additional configuration
val enhancedClient = originalClient.config {
    install(HttpCookies) {
        storage = AcceptAllCookiesStorage()
    }
}

// Check engine capabilities
val supportsWebSockets = client.isSupported(WebSocketCapability)

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

/**
 * Configure default request parameters
 */
fun HttpClientConfig<*>.defaultRequest(block: HttpRequestBuilder.() -> Unit)

val client = HttpClient {
    defaultRequest {
        url("https://api.example.com/")
        header("User-Agent", "MyApp/1.0")
        header("Accept", "application/json")
        
        // Default timeout for all requests
        timeout {
            requestTimeoutMillis = 30000
        }
    }
}

// Now all requests will include the default configuration
val response = client.get("users") // Requests https://api.example.com/users

/**
 * Credentials for proxy authentication
 */
data class Credentials(
    val username: String,
    val password: String
)

/**
 * Socket address for proxy configuration
 */
data class SocketAddress(
    val hostname: String,
    val port: Int
)

/**
 * Engine capability marker interface
 */
interface HttpClientEngineCapability<T>

/**
 * Engine factory interface
 */
interface HttpClientEngineFactory<T : HttpClientEngineConfig> {
    fun create(block: T.() -> Unit = {}): HttpClientEngine
}