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

Ktor client WebSocket plugin - provides WebSocket support for the Ktor HTTP client on multiple platforms including iOS x64

—

Pending

Overview

Eval results

Files

Plugin Configuration

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

The WebSockets plugin provides configuration options for ping intervals, frame size limits, content conversion, and WebSocket extensions.

Installation

Install the WebSockets plugin in your HttpClient configuration:

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

val client = HttpClient(CIO) {
    install(WebSockets) {
        // Configure plugin options
        pingInterval = 20_000 // 20 seconds
        maxFrameSize = 1024 * 1024 // 1MB
        contentConverter = MyWebSocketConverter()
    }
}

Configuration Options

Ping Interval

Controls the automatic ping frame interval for connection keep-alive:

var WebSockets.Config.pingInterval: Long

Default: -1L (disabled)
Units: Milliseconds
Description: Interval between automatic ping frames. Set to -1L to disable automatic pings.

Usage:

install(WebSockets) {
    pingInterval = 30_000 // Send ping every 30 seconds
    // or
    pingInterval = -1L // Disable automatic pings
}

Maximum Frame Size

Sets the maximum allowed size for incoming WebSocket frames:

var WebSockets.Config.maxFrameSize: Long

Default: Int.MAX_VALUE.toLong()
Units: Bytes
Description: Maximum size of a single WebSocket frame. Connections will be closed if this limit is exceeded.

Usage:

install(WebSockets) {
    maxFrameSize = 512 * 1024 // 512KB limit
    // or
    maxFrameSize = Long.MAX_VALUE // No practical limit
}

Content Converter

Configures automatic serialization/deserialization for WebSocket messages:

var WebSockets.Config.contentConverter: WebsocketContentConverter?

Default: null
Description: Content converter for automatic serialization of objects sent via sendSerialized() and deserialization via receiveDeserialized().

Usage:

import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

install(WebSockets) {
    contentConverter = KotlinxWebsocketSerializationConverter(Json)
}

WebSocket Extensions

Configure WebSocket protocol extensions:

fun WebSockets.Config.extensions(block: WebSocketExtensionsConfig.() -> Unit)

Usage:

install(WebSockets) {
    extensions {
        // Configure extensions like compression, etc.
        // Note: Extension availability depends on the client engine
    }
}

Complete Configuration Example

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.websocket.*
import io.ktor.serialization.kotlinx.*
import kotlinx.serialization.json.*

val client = HttpClient(CIO) {
    install(WebSockets) {
        // Send ping every 20 seconds
        pingInterval = 20_000
        
        // Limit frames to 1MB
        maxFrameSize = 1024 * 1024
        
        // Enable JSON serialization
        contentConverter = KotlinxWebsocketSerializationConverter(Json {
            prettyPrint = true
            isLenient = true
        })
        
        // Configure extensions (if supported by engine)
        extensions {
            // Extension configuration would go here
        }
    }
}

Engine Compatibility

Not all client engines support all WebSocket features:

CIO Engine: Full WebSocket support including extensions
JavaScript Engine: Basic WebSocket support, no ping-pong control, no extensions
Native Engines: WebSocket support varies by platform

Check engine capabilities:

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

Usage:

val hasWebSocketSupport = client.engine.supportedCapabilities.contains(WebSocketCapability)
val hasExtensionsSupport = client.engine.supportedCapabilities.contains(WebSocketExtensionsCapability)

Error Handling

Configuration errors and WebSocket-specific exceptions:

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

Common configuration issues:

Invalid ping interval values
Frame size limits that are too small
Missing content converter when using serialization functions
Engine incompatibility with requested features

Install with Tessl CLI

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

docs

content-serialization.md

index.md

plugin-configuration.md

raw-websocket-operations.md

session-operations.md

websocket-connections.md

tile.json

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