or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdmessage-serialization.mdplugin-configuration.mdsession-management.mdwebsocket-connections.md
tile.json

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

Ktor client WebSocket plugin for iOS x64 target providing WebSocket client capabilities for iOS simulator applications using Kotlin Multiplatform.

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

To install, run

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

index.mddocs/

Ktor Client WebSockets

Ktor Client WebSockets provides WebSocket client capabilities for iOS x64 (iOS simulator) applications using Kotlin Multiplatform. This plugin enables asynchronous bidirectional communication with WebSocket servers, offering coroutine-based APIs for connection management, message sending/receiving, and connection lifecycle handling.

Package Information

  • Package Name: ktor-client-websockets-iosx64
  • Package Type: maven
  • Coordinates: io.ktor:ktor-client-websockets-iosx64
  • Language: Kotlin Multiplatform
  • Platform: iOS x64 (iOS simulator)
  • Installation: Add implementation("io.ktor:ktor-client-websockets:3.2.0") to your iOS x64 target dependencies (the iosX64 artifact is automatically resolved)

Core Imports

import io.ktor.client.*
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.*

// Create client with WebSocket support
val client = HttpClient {
    install(WebSockets) {
        pingInterval = 20.seconds
        maxFrameSize = 1024 * 1024 // 1MB
    }
}

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

client.close()

Architecture

The Ktor Client WebSocket plugin is built around several key components:

  • Plugin Installation: WebSockets plugin integrates with Ktor's client architecture
  • Session Management: ClientWebSocketSession and DefaultClientWebSocketSession provide connection context
  • Connection Builders: Multiple convenience functions (webSocket, ws, wss, webSocketSession) for different use cases
  • Frame Handling: Direct access to WebSocket frames for low-level control
  • Serialization Support: Built-in content converter support for object serialization
  • Configuration: Ping intervals, max frame sizes, and extension support

Capabilities

Plugin Configuration

WebSocket plugin installation and configuration including ping intervals, frame size limits, content converters, and extension support.

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

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

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

Plugin Configuration

WebSocket Connections

Connection establishment functions providing flexible ways to connect to WebSocket servers with both high-level and low-level APIs.

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

suspend fun HttpClient.webSocket(
    method: HttpMethod = HttpMethod.Get,
    host: String? = null,
    port: Int? = null,
    path: String? = null,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
)

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

WebSocket Connections

Session Management

WebSocket session types and lifecycle management for maintaining connection state and handling communication context.

interface ClientWebSocketSession : WebSocketSession {
    val call: HttpClientCall
}

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

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

Session Management

Message Serialization

Content conversion support for serializing and deserializing objects to/from WebSocket frames with type safety.

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

suspend fun DefaultClientWebSocketSession.sendSerialized(data: Any?, typeInfo: TypeInfo)

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

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

val DefaultClientWebSocketSession.converter: WebsocketContentConverter?

Message Serialization

Types

Core Types

data object WebSocketCapability : HttpClientEngineCapability<Unit>

data object WebSocketExtensionsCapability : HttpClientEngineCapability<Unit>

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

const val PINGER_DISABLED: Long = 0

interface WebsocketContentConverter

class WebsocketConverterNotFoundException(message: String) : Exception(message)

class WebsocketDeserializeException(message: String, val frame: Frame) : Exception(message)

Error Handling

The plugin throws specific exceptions for different error conditions:

  • WebSocketException: Handshake failures, connection errors, or protocol violations
  • WebsocketConverterNotFoundException: When no content converter is available for serialization
  • WebsocketDeserializeException: When frame deserialization fails
  • Standard WebSocket exceptions from the underlying io.ktor.websocket package