Engine Configuration

/**
 * HTTP client engine interface for platform-specific implementations
 */
interface HttpClientEngine : CoroutineScope, Closeable {
    /** I/O operations dispatcher */
    val dispatcher: CoroutineDispatcher
    
    /** Engine configuration */
    val config: HttpClientEngineConfig
    
    /** Set of supported engine capabilities */
    val supportedCapabilities: Set<HttpClientEngineCapability<*>>
}

/**
 * Factory for creating HTTP client engine instances
 */
interface HttpClientEngineFactory<out T : HttpClientEngineConfig> {
    /**
     * Create engine instance with configuration
     */
    fun create(block: T.() -> Unit = {}): HttpClientEngine
}

/**
 * Create a configured engine factory
 */
fun <T : HttpClientEngineConfig> HttpClientEngineFactory<T>.config(
    nested: T.() -> Unit
): HttpClientEngineFactory<T>

import io.ktor.client.engine.cio.*

// Create engine with factory
val engine = CIO.create {
    maxConnectionsCount = 1000
    requestTimeout = 30_000
}

// Create configured factory
val configuredFactory = CIO.config {
    maxConnectionsCount = 500
    endpoint {
        maxConnectionsPerRoute = 100
    }
}

val client = HttpClient(configuredFactory)

/**
 * Base configuration for HTTP client engines
 */
open class HttpClientEngineConfig {
    /** Network threads count - deprecated, use engine-specific configuration */
    @Deprecated("Use engine-specific configuration instead")
    var threadsCount: Int = 4
    
    /** HTTP pipelining advice (not all engines support this) */
    var pipelining: Boolean = false
    
    /** Proxy configuration */
    var proxy: ProxyConfig? = null
}

val client = HttpClient(CIO) {
    engine {
        // Base engine configuration
        pipelining = true
        proxy = ProxyBuilder.http("http://proxy.example.com:8080")
        
        // CIO-specific configuration
        maxConnectionsCount = 1000
        requestTimeout = 30_000
        
        endpoint {
            maxConnectionsPerRoute = 100
            pipelineMaxSize = 20
            keepAliveTime = 5000
            connectTimeout = 5000
            connectAttempts = 5
        }
    }
}

/**
 * Proxy configuration - platform-specific implementation
 */
expect class ProxyConfig {
    val type: ProxyType
    fun resolveAddress(): NetworkAddress
}

/**
 * Proxy type enumeration
 */
enum class ProxyType {
    SOCKS, HTTP, UNKNOWN
}

/**
 * Proxy builder for creating proxy configurations
 */
expect object ProxyBuilder {
    /**
     * Create HTTP proxy configuration from URL
     */
    fun http(url: Url): ProxyConfig
    
    /**
     * Create HTTP proxy configuration from URL string
     */
    fun http(urlString: String): ProxyConfig
    
    /**
     * Create SOCKS proxy configuration
     */
    fun socks(host: String, port: Int): ProxyConfig
}

import io.ktor.client.engine.*

// HTTP proxy
val httpProxy = ProxyBuilder.http("http://proxy.example.com:8080")
val httpsProxy = ProxyBuilder.http("https://secure-proxy.example.com:8443")

// SOCKS proxy
val socksProxy = ProxyBuilder.socks("socks-proxy.example.com", 1080)

// Use proxy in client
val client = HttpClient(CIO) {
    engine {
        proxy = httpProxy
    }
}

// Check proxy type
when (httpProxy.type) {
    ProxyType.HTTP -> println("Using HTTP proxy")
    ProxyType.SOCKS -> println("Using SOCKS proxy")
    ProxyType.UNKNOWN -> println("Unknown proxy type")
}

/**
 * Interface for engine capabilities
 */
interface HttpClientEngineCapability<T>

/**
 * Check if client supports a capability
 */
fun HttpClient.isSupported(capability: HttpClientEngineCapability<*>): Boolean

/**
 * Set capability in request builder
 */
fun <T> HttpRequestBuilder.setCapability(
    key: HttpClientEngineCapability<T>, 
    capability: T
)

/**
 * Get capability from request builder
 */
fun <T> HttpRequestBuilder.getCapabilityOrNull(
    key: HttpClientEngineCapability<T>
): T?

// Check engine capabilities
val client = HttpClient(CIO)

if (client.isSupported(WebSocketCapability)) {
    println("WebSocket is supported")
}

if (client.isSupported(HttpTimeoutCapability)) {
    println("Timeout configuration is supported")
}

// Set capability in request
client.get("https://api.example.com/data") {
    setCapability(SomeEngineCapability, capabilityValue)
}

// JVM Engines
// CIO - Coroutine-based I/O engine (pure Kotlin)
// Apache - Apache HttpClient engine
// OkHttp - OkHttp engine
// Jetty - Jetty HttpClient engine

// JavaScript Engine
// Js - Browser fetch API or Node.js

// Native Engines  
// Curl - libcurl-based engine for native platforms
// Darwin - URLSession-based engine for iOS/macOS

// JVM - CIO Engine (recommended)
import io.ktor.client.engine.cio.*
val cioClient = HttpClient(CIO) {
    engine {
        maxConnectionsCount = 1000
        requestTimeout = 30_000
    }
}

// JVM - OkHttp Engine
import io.ktor.client.engine.okhttp.*
val okHttpClient = HttpClient(OkHttp) {
    engine {
        config {
            retryOnConnectionFailure(true)
            connectTimeout(30, TimeUnit.SECONDS)
        }
    }
}

// JavaScript Engine
import io.ktor.client.engine.js.*
val jsClient = HttpClient(Js) {
    engine {
        // JavaScript-specific configuration
    }
}

// Native - Darwin Engine (iOS/macOS)
import io.ktor.client.engine.darwin.*
val darwinClient = HttpClient(Darwin) {
    engine {
        configureRequest {
            setAllowsCellularAccess(true)
        }
    }
}

// Production configuration example
val productionClient = HttpClient(CIO) {
    engine {
        // Connection pool settings
        maxConnectionsCount = 1000
        
        // Timeouts
        requestTimeout = 30_000
        
        // Per-endpoint configuration
        endpoint {
            maxConnectionsPerRoute = 100
            pipelineMaxSize = 20
            keepAliveTime = 5000
            connectTimeout = 5000
            connectAttempts = 5
        }
        
        // Proxy for corporate environment
        proxy = ProxyBuilder.http("http://corporate-proxy.com:8080")
    }
    
    // Additional configuration
    followRedirects = true
    expectSuccess = false
}

// Development configuration example
val developmentClient = HttpClient(CIO) {
    engine {
        // Relaxed settings for development
        maxConnectionsCount = 100
        requestTimeout = 60_000 // Longer timeout for debugging
        
        endpoint {
            connectTimeout = 10_000
            connectAttempts = 3
        }
    }
    
    // Development mode features
    developmentMode = true
}

// High-performance configuration
val highPerfClient = HttpClient(CIO) {
    engine {
        // Optimized for high throughput
        maxConnectionsCount = 2000
        
        endpoint {
            maxConnectionsPerRoute = 200
            pipelineMaxSize = 50
            keepAliveTime = 10_000
        }
        
        // Disable pipelining for compatibility
        pipelining = false
    }
}