dependencies {
    // Raw-socket platforms (JVM, Android, iOS/macOS, Linux, Node.js): TCP + TLS + WebSocket in one call
    implementation("com.ditchoom:websocket-tcp:<latest-version>")

    // Apple-only, backed by NSURLSessionWebSocketTask (system TLS/proxy/deflate, no socket dependency)
    implementation("com.ditchoom:websocket-apple:<latest-version>")

    // Core engine only — bring your own pre-connected ByteStream (advanced / browser lives here too)
    implementation("com.ditchoom:websocket:<latest-version>")
}

import com.ditchoom.websocket.WebSocketConnectionOptions
import com.ditchoom.websocket.WebSocketMessage
import com.ditchoom.websocket.use
import com.ditchoom.websocket.tcp.connectTcpWebSocket
import kotlinx.coroutines.flow.first

val options = WebSocketConnectionOptions(
    name = "echo.websocket.org",
    port = 443,
    tls = true,               // defaults to (port == 443)
    websocketEndpoint = "/",
)

// `use` runs the block and closes the connection (RFC 6455 close handshake) in a finally.
connectTcpWebSocket(options).use { ws ->
    ws.send(WebSocketMessage.Text("Hello, WebSocket!"))

    val reply = ws.receive().first()          // receive() is a Flow<WebSocketMessage<Unit>>
    println((reply as WebSocketMessage.Text).payload)
}

ws.receive().collect { message ->
    when (message) {
        is WebSocketMessage.Text   -> println("text: ${message.payload}")     // always a UTF-8 String
        is WebSocketMessage.Binary -> handle(message.payload)                  // payload: B (your codec's type)
        is WebSocketMessage.Ping   -> println("ping: ${message.appData}")      // auto-ponged for you
        is WebSocketMessage.Pong   -> println("pong: ${message.appData}")
        is WebSocketMessage.Close  -> println("close ${message.code}: ${message.reason}")
    }
}

// Given a Codec<SensorReading> (e.g. generated by buffer-codec):
val ws: Connection<WebSocketMessage<SensorReading>> =
    connectTcpWebSocket(options, binaryCodec = SensorReadingCodec)

ws.send(WebSocketMessage.Binary(SensorReading(id = 7u, celsius = 21)))

ws.receive().collect { msg ->
    if (msg is WebSocketMessage.Binary) update(msg.payload)   // payload: SensorReading, already decoded
}

import com.ditchoom.websocket.tcp.WebSocketTransport

val transport = WebSocketTransport(
    websocketEndpoint = "/tunnel",
    underlying = TcpTransport(),      // the WS handshake rides this transport
)

// Slots into any socket API that takes a Transport (e.g. a FallbackTransport chain):
val stream: ByteStream = transport.connect(host, port, config)
stream.write(payload)                 // one binary WebSocket frame per write

val options = WebSocketConnectionOptions(
    name = "example.com",
    requestCompression = true,
    compressionOptions = CompressionOptions(
        clientNoContextTakeover = false,  // keep the LZ77 window across messages (better ratio)
        serverNoContextTakeover = false,
        clientMaxWindowBits = 15,         // 0 = don't request (platform default)
    ),
)

try {
    connectTcpWebSocket(options).use { ws -> /* ... */ }
} catch (e: WebSocketException.HandshakeRejected) {
    println("server rejected the upgrade: HTTP ${e.statusCode}")
} catch (e: WebSocketException.TransportFailed) {
    println("network/TLS failure: ${e.cause?.message}")
} catch (e: WebSocketException.ProtocolViolation) {
    println("peer broke RFC 6455: ${e.message}")
} catch (e: WebSocketException.ConnectionClosed) {
    println("closed: code=${e.code} reason=${e.reason}")
}