dependencies {
    implementation("com.ditchoom:socket:<latest-version>")
    // Buffer v4 — required (BufferFactory API, deterministic allocation, scatter-gather)
    implementation("com.ditchoom:buffer:4.0.0")
    // Optional: streaming transforms (mapBuffer, asStringFlow, lines)
    implementation("com.ditchoom:buffer-flow:<latest-version>")
    // Optional: compression
    implementation("com.ditchoom:buffer-compression:<latest-version>")
}

dependencies {
    implementation("com.ditchoom:socket-quic:<latest-version>")
}

// Client — handshake completes before the block runs; connection closes on block exit.
withQuicConnection("example.com", 443, QuicOptions(alpnProtocols = listOf("h3"))) {
    val stream = openStream()
    stream.write(buf, 5.seconds)
    val response = stream.read(5.seconds)
    stream.close()
}

// Server — UDP socket bound for the block's lifetime.
withQuicServer(port = 4433, tlsConfig = QuicTlsConfig(certChainPath, privKeyPath), quicOptions) {
    connections {
        val stream = acceptStream()
        // … echo, multiplex, etc. …
    }
}

withQuicMux("localhost", port, quicOptions, StringCodec) {
    val conn = openBidirectional()
    conn.send("hello")
    val reply = conn.receive().first() // "echo: hello"
    conn.close()
}

// HTTP/3 client request/response
withHttp3Connection("example.com", 443) {
    val response = request(Http3Request(method = "GET", authority = "example.com", path = "/"))
    val body = response.readFullBody()
    body.freeIfNeeded() // you own the body buffer
    response.close()
}

// WebTransport session with its own multiplexed streams + datagrams
withHttp3Connection("example.com", port, webTransport = WebTransportOptions(maxSessions = 4)) {
    val session = connectWebTransport(authority = "example.com", path = "/wt")
    val stream = session.openBidiStream()
    stream.write(buf); stream.shutdownSend()
    session.close()
}

try {
    ClientSocket.connect(443, "example.com", socketOptions = SocketOptions.tlsDefault()) { socket ->
        socket.writeString("hello")
        socket.readString()
    }
} catch (e: SocketClosedException) {
    // Connection lost (reset, broken pipe, EOF)
} catch (e: SocketConnectionException.Refused) {
    // Nothing listening on that port
} catch (e: SocketUnknownHostException) {
    println("Cannot resolve: ${e.hostname}")
} catch (e: SSLSocketException) {
    // TLS certificate or protocol failure
}

val classifier = DefaultReconnectionClassifier()
while (scope.isActive) {
    try {
        ClientSocket.connect(port, hostname, socketOptions) { socket ->
            classifier.reset() // connected — reset backoff
            socket.readFlowLines().collect { process(it) }
        }
    } catch (e: SocketException) {
        when (val decision = classifier.classify(e)) {
            is ReconnectDecision.RetryAfter -> delay(decision.delay)
            is ReconnectDecision.GiveUp -> break // TLS failure, DNS failure — won't recover
        }
    }
}

// Connect, write, read, close — same code on JVM, iOS, Linux, Node.js
val socket = ClientSocket.connect(
    port = 443,
    hostname = "example.com",
    socketOptions = SocketOptions.tlsDefault(),
)
socket.writeString("GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n")
val response = socket.readString()
socket.close()

val socket = ClientSocket.connect(port = 9000, hostname = "localhost")
// Use managed (heap) buffers instead of native memory
socket.bufferFactory = BufferFactory.managed()

SocketConnection.connect(
    hostname = "broker.example.com",
    port = 8883,
    options = ConnectionOptions(
        bufferFactory = BufferFactory.deterministic(), // default — native memory, explicit cleanup
    ),
) { conn ->
    // ...
}

ClientSocket.connect(8883, hostname = "broker.example.com", socketOptions = SocketOptions.tlsDefault()) { socket ->
    socket.writeString("SUBSCRIBE events\n")
    socket.readFlowLines().collect { line ->
        println(line)
    }
} // socket closed automatically

fun streamEvents(host: String): Flow<String> = flow {
    ClientSocket.connect(8883, hostname = host, socketOptions = SocketOptions.tlsDefault()) { socket ->
        socket.writeString("SUBSCRIBE events\n")
        emitAll(socket.readFlowLines())
    }
}

// Compose with standard Flow operators
streamEvents("broker.example.com")
    .filter { "critical" in it }
    .onEach { alert(it) }
    .launchIn(scope)

socket.readFlow()
    .mapBuffer { decompress(it, Gzip).getOrThrow() }
    .asStringFlow()
    .lines()
    .collect { line -> process(line) }

val header = BufferFactory.Default.allocate(4)
header.writeInt(payload.remaining())
header.resetForRead()

socket.writeGathered(listOf(header, payload))

SocketConnection.connect(
    hostname = "broker.example.com",
    port = 8883,
    options = ConnectionOptions(
        socketOptions = SocketOptions.tlsDefault(),
        maxPoolSize = 64,
    ),
) { conn ->
    sensorReadings.collect { reading ->
        conn.withBuffer { buf ->
            val payload = reading.toJson().toReadBuffer()
            val compressed = compress(payload, CompressionAlgorithm.Gzip).getOrThrow()
            buf.writeInt(compressed.remaining())
            buf.write(compressed)
            buf.resetForRead()
            conn.write(buf)
        }
    }
}

val server = ServerSocket.allocate()
val clients = server.bind()

launch {
    clients.collect { client ->
        val message = client.readString()
        client.writeString(message) // echo
        client.close()
    }
}

// Connect a client
val client = ClientSocket.connect(server.port())
client.writeString("Hello!")
val echo = client.readString() // "Hello!"
client.close()
server.close()