or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdwebsocket-extensions.md
tile.json

tessl/maven-io-ktor--ktor-client-cio-jvm

CIO backend for ktor http client - A coroutine-based asynchronous HTTP client engine for Ktor that provides efficient I/O operations using Kotlin coroutines and native socket operations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-cio-jvm@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-cio-jvm@3.2.0

index.mddocs/

Ktor Client CIO Engine

Ktor Client CIO Engine is a coroutine-based asynchronous HTTP client engine for Ktor that provides efficient I/O operations using Kotlin coroutines and native socket operations. It supports HTTP/1.1, WebSocket connections, Server-Sent Events, and TLS/SSL encryption with connection pooling and keep-alive functionality.

Package Information

  • Package Name: io.ktor:ktor-client-cio-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-client-cio-jvm:3.2.0")

Core Imports

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

Basic Usage

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

// Create a client with CIO engine
val client = HttpClient(CIO)

// Make requests
val response = client.get("https://api.example.com/data")

// Configure the engine
val configuredClient = HttpClient(CIO) {
    engine {
        maxConnectionsCount = 1000
        requestTimeout = 15000
        endpoint {
            maxConnectionsPerRoute = 100
            connectTimeout = 5000
            keepAliveTime = 5000
        }
        https {
            // TLS configuration
        }
    }
}

Architecture

The Ktor Client CIO Engine is built around several key components:

  • CIO Engine Factory: Main entry point (CIO object) for creating engine instances
  • Configuration System: CIOEngineConfig and EndpointConfig for comprehensive engine setup
  • Connection Management: Efficient connection pooling, keep-alive, and HTTP pipelining
  • Protocol Support: HTTP/1.1, WebSocket, Server-Sent Events, and Unix domain sockets
  • Platform Support: Cross-platform with JVM, JavaScript (Node.js), and native platforms

Capabilities

Engine Configuration

Core engine configuration for connection management, timeouts, and performance tuning.

data object CIO : HttpClientEngineFactory<CIOEngineConfig> {
    override fun create(block: CIOEngineConfig.() -> Unit): HttpClientEngine
}

val supportedCapabilities: Set<HttpClientEngineCapability<out Any>> = setOf(
    HttpTimeoutCapability,
    WebSocketCapability,
    WebSocketExtensionsCapability,
    SSECapability,
    UnixSocketCapability
)

Engine Settings

Primary configuration class for the CIO engine providing control over connections, timeouts, and HTTPS settings.

class CIOEngineConfig : HttpClientEngineConfig() {
    val endpoint: EndpointConfig
    val https: TLSConfigBuilder
    var maxConnectionsCount: Int
    var requestTimeout: Long
    
    fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder
}

fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig

Connection Configuration

Detailed endpoint configuration for connection behavior, timeouts, and performance optimization.

class EndpointConfig {
    var maxConnectionsPerRoute: Int
    var keepAliveTime: Long
    var pipelineMaxSize: Int
    var connectTimeout: Long
    var socketTimeout: Long
    var connectAttempts: Int
    
    @Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.")
    var allowHalfClose: Boolean
}

WebSocket Extensions (JVM)

Raw WebSocket functionality for low-level WebSocket operations without automatic ping-pong handling.

suspend fun HttpClient.webSocketRawSession(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    block: HttpRequestBuilder.() -> Unit = {}
): ClientWebSocketSession

suspend fun HttpClient.webSocketRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
)

WebSocket Extensions

Exception Handling

Engine-specific exceptions for connection and timeout scenarios.

class FailToConnectException : Exception("Connect timed out or retry attempts exceeded")

Server-Sent Events Support

Support for Server-Sent Events (SSE) connections through the SSECapability.

Unix Domain Socket Support

Support for Unix domain socket connections through the UnixSocketCapability.

Proxy Support

Support for HTTP proxy connections. SOCKS proxies are not currently supported.

Types

Engine Factory

data object CIO : HttpClientEngineFactory<CIOEngineConfig> {
    override fun create(block: CIOEngineConfig.() -> Unit): HttpClientEngine
}

Configuration Classes

class CIOEngineConfig : HttpClientEngineConfig() {
    /** Access to endpoint settings */
    val endpoint: EndpointConfig
    
    /** HTTPS/TLS configuration */
    val https: TLSConfigBuilder
    
    /** Maximum number of connections for requests (default: 1000) */
    var maxConnectionsCount: Int
    
    /** Request timeout in milliseconds (default: 15000) */
    var requestTimeout: Long
    
    /** Configure HTTPS settings */
    fun https(block: TLSConfigBuilder.() -> Unit): TLSConfigBuilder
}

class EndpointConfig {
    /** Maximum connections per host (default: 100) */
    var maxConnectionsPerRoute: Int
    
    /** Connection keep-alive time in milliseconds (default: 5000) */
    var keepAliveTime: Long
    
    /** Maximum requests for HTTP pipelining (default: 20) */
    var pipelineMaxSize: Int
    
    /** Connection establishment timeout in milliseconds (default: 5000) */
    var connectTimeout: Long
    
    /** Socket inactivity timeout in milliseconds (default: INFINITE_TIMEOUT_MS) */
    var socketTimeout: Long
    
    /** Maximum connection retry attempts (default: 1) */
    var connectAttempts: Int
    
    /** Allow half-closed TCP connections (default: false, deprecated) */
    @Deprecated("Half closed TCP connection is not supported by all servers, use it at your own risk.")
    var allowHalfClose: Boolean
}

Engine Container (JVM)

class CIOEngineContainer : HttpClientEngineContainer {
    override val factory: HttpClientEngineFactory<*>
    override fun toString(): String
}

TLS Configuration

class TLSConfigBuilder {
    /** List of client certificate chains with private keys */
    val certificates: MutableList<CertificateAndKey>
    
    /** SecureRandom to use in encryption */
    var random: SecureRandom?
    
    /** Custom X509TrustManager to verify server authority */
    var trustManager: TrustManager?
    
    /** List of allowed CipherSuites */
    var cipherSuites: List<CipherSuite>
    
    /** Custom server name for TLS server name extension */
    var serverName: String?
    
    /** Create TLSConfig */
    fun build(): TLSConfig
}

/** Append config from another builder */
fun TLSConfigBuilder.takeFrom(other: TLSConfigBuilder)

/** Add client certificate chain to use */
fun TLSConfigBuilder.addCertificateChain(chain: Array<X509Certificate>, key: PrivateKey)

/** Add client certificates from KeyStore */
fun TLSConfigBuilder.addKeyStore(store: KeyStore, password: CharArray?, alias: String? = null)

Extension Functions

/** Configure endpoint settings */
fun CIOEngineConfig.endpoint(block: EndpointConfig.() -> Unit): EndpointConfig