tessl/maven-io-ktor--ktor-client-websockets-linuxx64

Ktor client WebSockets plugin for Linux x64 platform - enables full-duplex communication between client and server over TCP connection

—

Pending

Overview

Eval results

Files

Ktor Client WebSockets

Name: tessl/maven-io-ktor--ktor-client-websockets-linuxx64
Author: tessl

Ktor Client WebSockets provides comprehensive WebSocket client capabilities for Kotlin applications running on Linux x64 platforms. As part of the Ktor framework, it enables full-duplex, real-time communication between clients and servers over a single TCP connection with native performance optimizations.

Package Information

Package Name: ktor-client-websockets-linuxx64
Package Type: Maven
Language: Kotlin
Platform: Linux x64 (Native)
Installation: Add to your build.gradle.kts:

dependencies {
    implementation("io.ktor:ktor-client-websockets-linuxx64:3.2.0")
}

Core Imports

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

For WebSocket frames:

import io.ktor.websocket.Frame
import io.ktor.websocket.FrameType

Basic Usage

import io.ktor.client.*
import io.ktor.client.plugins.websocket.*
import io.ktor.websocket.*
import kotlin.time.Duration.Companion.seconds

// Install WebSocket plugin
val client = HttpClient {
    install(WebSockets) {
        pingInterval = 30.seconds
        maxFrameSize = 1024 * 1024 // 1MB
    }
}

// Connect and use WebSocket
client.webSocket("ws://echo.websocket.org") {
    // Send text message
    send("Hello WebSocket!")
    
    // Receive messages
    for (frame in incoming) {
        when (frame) {
            is Frame.Text -> println("Received: ${frame.readText()}")
            is Frame.Binary -> println("Received binary: ${frame.data.size} bytes")
            is Frame.Close -> break
        }
    }
}

client.close()

Architecture

Ktor WebSocket client is built around several key components:

Plugin System: WebSocket functionality is provided as a client plugin that integrates with Ktor's HTTP client
Session Management: WebSocket connections are managed through session interfaces with lifecycle control
Frame Processing: Low-level WebSocket frame handling with support for text, binary, and control frames
Extension Support: Pluggable WebSocket extensions system for protocol enhancements
Serialization: Content converter integration for automatic serialization/deserialization
Coroutine Integration: Full async/await support using Kotlin coroutines

Capabilities

Plugin Configuration

WebSocket plugin installation and configuration with ping intervals, frame size limits, and extension support.

class WebSockets internal constructor(
    val pingIntervalMillis: Long,
    val maxFrameSize: Long,
    val contentConverter: WebsocketContentConverter? = null
) : HttpClientPlugin<WebSockets.Config, WebSockets>

class Config {
    var pingIntervalMillis: Long
    var maxFrameSize: Long
    var contentConverter: WebsocketContentConverter?
    var pingInterval: Duration?
    fun extensions(block: WebSocketExtensionsConfig.() -> Unit)
}

fun HttpClientConfig<*>.WebSockets(config: WebSockets.Config.() -> Unit)

Plugin Configuration

WebSocket Connections

Core connection establishment functions for creating WebSocket sessions with various configuration options.

suspend fun HttpClient.webSocket(
    request: HttpRequestBuilder.() -> Unit,
    block: suspend DefaultClientWebSocketSession.() -> Unit
)

suspend fun HttpClient.webSocketSession(
    block: HttpRequestBuilder.() -> Unit
): DefaultClientWebSocketSession

suspend fun HttpClient.ws(
    host: String? = null,
    port: Int? = null, 
    path: String? = null,
    block: suspend DefaultClientWebSocketSession.() -> Unit
)

suspend fun HttpClient.wss(
    host: String? = null,
    port: Int? = null,
    path: String? = null, 
    block: suspend DefaultClientWebSocketSession.() -> Unit
)

WebSocket Connections

Session Management

WebSocket session interfaces providing frame-level control and connection lifecycle management.

interface ClientWebSocketSession : WebSocketSession {
    val call: HttpClientCall
}

class DefaultClientWebSocketSession(
    override val call: HttpClientCall,
    delegate: DefaultWebSocketSession
) : ClientWebSocketSession, DefaultWebSocketSession

interface WebSocketSession : CoroutineScope {
    var masking: Boolean
    var maxFrameSize: Long
    val incoming: ReceiveChannel<Frame>
    val outgoing: SendChannel<Frame>
    val extensions: List<WebSocketExtension<*>>
}

Session Management

Frame Operations

Low-level WebSocket frame handling for text, binary, and control frame processing.

sealed class Frame {
    val fin: Boolean
    val frameType: FrameType
    val data: ByteArray
    val rsv1: Boolean
    val rsv2: Boolean  
    val rsv3: Boolean
    
    class Text(text: String) : Frame
    class Binary(fin: Boolean, data: ByteArray) : Frame
    class Close : Frame
    class Ping(data: ByteArray) : Frame
    class Pong(data: ByteArray) : Frame
}

enum class FrameType(val controlFrame: Boolean, val opcode: Int) {
    TEXT, BINARY, CLOSE, PING, PONG
}

fun Frame.Text.readText(): String
fun Frame.readBytes(): ByteArray
fun Frame.Close.readReason(): CloseReason?

Frame Operations

Serialization Support

Content converter integration for automatic serialization/deserialization of objects to/from WebSocket frames.

suspend fun DefaultClientWebSocketSession.sendSerialized(data: Any?, typeInfo: TypeInfo)
suspend inline fun <reified T> DefaultClientWebSocketSession.sendSerialized(data: T)

suspend fun <T> DefaultClientWebSocketSession.receiveDeserialized(typeInfo: TypeInfo): T  
suspend inline fun <reified T> DefaultClientWebSocketSession.receiveDeserialized(): T

val DefaultClientWebSocketSession.converter: WebsocketContentConverter?

Serialization Support

Types

WebSocket Configuration Types

interface WebsocketContentConverter {
    suspend fun serialize(
        charset: Charset,
        typeInfo: TypeInfo,
        value: Any?
    ): Frame
    
    suspend fun deserialize(
        charset: Charset,
        typeInfo: TypeInfo,
        content: Frame
    ): Any?
}

data object WebSocketCapability : HttpClientEngineCapability<Unit>
data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>

WebSocket Constants

/** Constant indicating that WebSocket pinger is disabled */
const val PINGER_DISABLED: Long = 0

Exception Types

class WebSocketException(message: String, cause: Throwable?) : IllegalStateException

class ProtocolViolationException(message: String) : Exception

class FrameTooBigException(message: String) : Exception

Extension Types

interface WebSocketExtension<ConfigType : Any> {
    val protocols: List<WebSocketExtensionHeader>
    fun clientNegotiation(extensions: List<WebSocketExtensionHeader>): Boolean
}

interface WebSocketExtensionFactory<ConfigType : Any, ExtensionType : WebSocketExtension<ConfigType>>

class WebSocketExtensionsConfig {
    fun <Config : Any, Extension : WebSocketExtension<Config>> install(
        extension: WebSocketExtensionFactory<Config, Extension>,
        configure: Config.() -> Unit = {}
    )
}

class WebSocketExtensionHeader(val name: String, val parameters: List<String>)

/** Parse WebSocket extension headers from HTTP header value */
fun parseWebSocketExtensions(value: String): List<WebSocketExtensionHeader>

Error Handling

WebSocket operations can throw several types of exceptions:

WebSocketException: General WebSocket protocol errors, handshake failures, or connection issues
ProtocolViolationException: WebSocket protocol compliance violations
FrameTooBigException: Frame size exceeds configured maximum
ClosedReceiveChannelException: Channel closed while receiving
WebsocketConverterNotFoundException: No content converter available for serialization
WebsocketDeserializeException: Deserialization failed for received frame

Install with Tessl CLI

npx tessl i tessl/maven-io-ktor--ktor-client-websockets-linuxx64

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:maven/io.ktor/ktor-client-websockets-linuxx64@3.2.x
Badge