CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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?
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-websockets@3.2.x
Publish Source
CLI
Badge
tessl/maven-io-ktor--ktor-client-websockets-macosarm64 badge