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

—

Pending

Overview

Eval results

Files

WebSocket Extensions

Name: tessl/maven-io-ktor--ktor-client-cio-jvm
Author: tessl

Raw WebSocket functionality specifically designed for the Ktor Client CIO engine on JVM platform. These extensions provide low-level WebSocket operations without automatic ping-pong handling, giving developers full control over the WebSocket connection lifecycle.

Note: These extensions are only available on the JVM platform.

Capabilities

Raw WebSocket Session Creation

Creates a raw ClientWebSocketSession without automatic ping-pong and service message handling.

/**
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
 * @param host Target host (optional, can be null)
 * @param port Target port (optional, can be null)
 * @param path URL path for the WebSocket endpoint (optional, can be null)
 * @param block Configuration block for the HTTP request builder
 * @returns ClientWebSocketSession for direct interaction
 */
suspend fun HttpClient.webSocketRawSession(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    block: HttpRequestBuilder.() -> Unit = {}
): ClientWebSocketSession

Usage Example:

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

val client = HttpClient(CIO)

val session = client.webSocketRawSession(
    host = "echo.websocket.org",
    port = 443,
    path = "/"
) {
    // Configure the WebSocket handshake request
    headers {
        append("Authorization", "Bearer token")
    }
}

// Use the session directly
session.send(Frame.Text("Hello, WebSocket!"))
val response = session.incoming.receive()
session.close()

Raw WebSocket with Block Execution

Creates and executes a raw WebSocket session with automatic session management.

/**
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
 * @param host Target host (optional, can be null)
 * @param port Target port (optional, can be null)
 * @param path URL path for the WebSocket endpoint (optional, can be null)
 * @param request Configuration block for the HTTP request builder
 * @param block Suspend block that operates on the WebSocket session
 */
suspend fun HttpClient.webSocketRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
)

Usage Example:

client.webSocketRaw(
    host = "echo.websocket.org",
    port = 443,
    path = "/",
    request = {
        headers {
            append("Authorization", "Bearer token")
        }
    }
) {
    // WebSocket session operations
    send(Frame.Text("Hello from CIO WebSocket!"))
    
    for (frame in incoming) {
        when (frame) {
            is Frame.Text -> {
                val text = frame.readText()
                println("Received: $text")
                if (text == "bye") break
            }
            is Frame.Close -> break
            else -> continue
        }
    }
}

Insecure WebSocket (ws://)

Convenience function for creating raw WebSocket connections over insecure ws:// protocol.

/**
 * Creates a raw ClientWebSocketSession: no ping-pong and other service messages are used.
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
 * @param host Target host (optional, can be null)
 * @param port Target port (optional, can be null)
 * @param path URL path for the WebSocket endpoint (optional, can be null)
 * @param request Configuration block for the HTTP request builder
 * @param block Suspend block that operates on the WebSocket session
 */
suspend fun HttpClient.wsRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
)

Usage Example:

client.wsRaw(
    host = "localhost",
    port = 8080,
    path = "/websocket"
) {
    send(Frame.Text("Testing insecure WebSocket"))
    val response = incoming.receive()
    println("Response: ${(response as Frame.Text).readText()}")
}

Secure WebSocket (wss://)

Convenience function for creating raw WebSocket connections over secure wss:// protocol.

/**
 * Create secure raw ClientWebSocketSession: no ping-pong and other service messages are used.
 * @param method HTTP method for the WebSocket handshake (default: HttpMethod.Get)
 * @param host Target host (optional, can be null)
 * @param port Target port (optional, can be null)
 * @param path URL path for the WebSocket endpoint (optional, can be null)
 * @param request Configuration block for the HTTP request builder
 * @param block Suspend block that operates on the WebSocket session
 */
suspend fun HttpClient.wssRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
)

Usage Example:

client.wssRaw(
    host = "secure.websocket.org",
    port = 443,
    path = "/secure-chat"
) {
    send(Frame.Text("Secure WebSocket message"))
    
    while (true) {
        val frame = incoming.receive()
        when (frame) {
            is Frame.Text -> {
                println("Secure message: ${frame.readText()}")
            }
            is Frame.Close -> {
                println("Connection closed")
                break
            }
            else -> continue
        }
    }
}

Integration Notes

Raw vs Standard WebSocket

These raw WebSocket extensions differ from Ktor's standard WebSocket plugin in several key ways:

No automatic ping-pong: You must handle ping/pong frames manually if needed
No automatic close handling: Connection lifecycle is entirely under your control
Direct frame access: All WebSocket frames are exposed without filtering
Manual session management: You're responsible for proper session cleanup

Error Handling

When using raw WebSocket extensions, handle exceptions appropriately:

try {
    client.webSocketRaw(host = "example.com") {
        // WebSocket operations
    }
} catch (e: Exception) {
    // Handle connection errors, protocol violations, etc.
    println("WebSocket error: ${e.message}")
}

Platform Limitations

These WebSocket extensions are JVM-only. For other platforms, use Ktor's standard WebSocket plugin or platform-specific WebSocket implementations.

Types

Import Dependencies

import io.ktor.client.*
import io.ktor.client.plugins.websocket.cio.*
import io.ktor.http.*
import io.ktor.client.request.*
import io.ktor.websocket.*

All WebSocket extension functions are available in the io.ktor.client.plugins.websocket.cio package and require the Ktor Client CIO engine to function properly.

Install with Tessl CLI

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

docs

index.md

websocket-extensions.md

tile.json

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