or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection-management.mdindex.mdmessage-handling.mdplugin-configuration.md
tile.json

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

WebSocket plugin for Ktor HTTP client enabling full-duplex real-time communication

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

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-websockets-macosarm64@3.2.0

index.mddocs/

Ktor Client WebSockets

Ktor Client WebSockets provides comprehensive WebSocket client support for the Ktor HTTP client framework. It enables full-duplex real-time communication over a single TCP connection, supporting both text and binary message types with automatic connection management, configurable frame sizes and ping intervals, and seamless integration with Ktor's multiplatform architecture.

Package Information

  • Package Name: ktor-client-websockets
  • Package Type: Maven (Kotlin Multiplatform)
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-client-websockets:3.2.0")
  • Platforms: All Kotlin Multiplatform targets including JVM, Android, iOS, JavaScript, and Native

Core Imports

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

Basic Usage

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

// Install WebSocket plugin
val client = HttpClient {
    install(WebSockets) {
        pingIntervalMillis = 20_000  // 20 seconds
        maxFrameSize = Long.MAX_VALUE
    }
}

// Basic WebSocket connection
client.webSocket("ws://localhost:8080/websocket") {
    // Send text message
    send("Hello, WebSocket!")
    
    // Receive and handle incoming frames
    for (frame in incoming) {
        when (frame) {
            is Frame.Text -> {
                val receivedText = frame.readText()
                println("Received: $receivedText")
            }
            is Frame.Binary -> {
                val receivedBytes = frame.readBytes()
                println("Received binary data: ${receivedBytes.size} bytes")
            }
            is Frame.Close -> {
                println("Connection closed")
                break
            }
            else -> {}
        }
    }
}

Architecture

Ktor Client WebSockets is built around several key components:

  • WebSockets Plugin: The main plugin that manages WebSocket connections and handles protocol upgrades
  • Client Sessions: Specialized WebSocket session interfaces that integrate with Ktor's HTTP client call lifecycle
  • Builder Functions: Convenient extension functions for establishing WebSocket connections with various configuration options
  • Content Serialization: Optional content converters for automatic serialization/deserialization of messages
  • Platform Abstraction: Multiplatform implementation with platform-specific optimizations (e.g., JavaScript browser WebSocket API)

Capabilities

Plugin Configuration

Core WebSocket plugin installation and configuration, including ping intervals, frame size limits, and content serialization.

class WebSockets(
    val pingIntervalMillis: Long,
    val maxFrameSize: Long,
    val contentConverter: WebsocketContentConverter? = null
)

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

Plugin Configuration

Connection Management

Functions for establishing and managing WebSocket connections with support for various URL formats and request configurations.

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

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

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

Connection Management

Message Handling

Client-specific WebSocket session interfaces providing access to HTTP call context and message serialization capabilities.

interface ClientWebSocketSession : WebSocketSession {
    val call: HttpClientCall
}

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

suspend fun <T> DefaultClientWebSocketSession.sendSerialized(data: T)
suspend fun <T> DefaultClientWebSocketSession.receiveDeserialized(): T

Message Handling

Types

data object WebSocketCapability : HttpClientEngineCapability<Unit>

data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>

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

val DefaultClientWebSocketSession.converter: WebsocketContentConverter?