# Connect (/sdks/kotlin/tutorials/connect)



## Overview [#overview]

Every KubeMQ application starts the same way: open a connection to the broker and prove it actually works before building anything on top of it. This tutorial is that first lesson — create a client with the DSL builder, give it a stable identity, and confirm connectivity, while also previewing the configuration knobs (keep-alive, reconnection backoff, log level, environment config) you'll reach for past the defaults.

`KubeMQClient.pubSub { }` (or `.queues { }` / `.cq { }`) builds a pattern-specific client from an `address` and `clientId` — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. `it.ping()` verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just "no exception," proving the client is talking to a real broker rather than silently misconfigured. The `use { }` block closes the client automatically on exit, even on error.

**Gotchas:** building the client doesn't always mean the broker is reachable — the channel can be established lazily, so `ping()` is the only reliable proof; reusing the same client ID across running instances causes routing confusion on the broker; and skipping the `use { }` block in quick scripts is a common source of leaked connections under load.

## Prerequisites [#prerequisites]

* KubeMQ server running on `localhost:50000`
* Kotlin SDK installed (`implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1")` or Maven dependency from [Getting Started](/sdks/kotlin))

## Code [#code]

```kotlin title="ConnectExample.kt"
package io.kubemq.sdk.examples.connection

import io.kubemq.sdk.client.ClientConfig
import io.kubemq.sdk.client.KubeMQClient
import io.kubemq.sdk.client.LogLevel
import kotlinx.coroutines.runBlocking

private const val ADDRESS = "localhost:50000"

fun main() = runBlocking {
    basicConfiguration()
    keepAliveConfiguration()
    reconnectionConfiguration()
    logLevelConfiguration()
    environmentConfiguration()
    println("Connect examples completed.")
}

private suspend fun basicConfiguration() {
    println("=== Basic Configuration ===\n")
    val client = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = "kotlin-conn-basic"
    }
    client.use {
        val info = it.ping()
        println("Connected: host=${info.host}, version=${info.version}")
        println("Uptime: ${info.serverUpTimeSeconds}s\n")
    }
}

private suspend fun keepAliveConfiguration() {
    println("=== Keep-Alive Configuration ===\n")
    val client = KubeMQClient.queues {
        address = ADDRESS
        clientId = "kotlin-conn-keepalive"
        keepAlive = true
        pingIntervalSeconds = 30
        pingTimeoutSeconds = 10
    }
    client.use {
        val info = it.ping()
        println("Connected with keep-alive:")
        println("  Ping Interval: 30s, Timeout: 10s")
        println("  Server: ${info.host}\n")
    }
}

private suspend fun reconnectionConfiguration() {
    println("=== Reconnection Configuration ===\n")
    val client = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = "kotlin-conn-reconnect"
        reconnection {
            initialBackoffMs = 1000
            maxBackoffMs = 30_000
            multiplier = 2.0
            maxRetries = 10
        }
    }
    client.use {
        val info = it.ping()
        println("Connected with reconnection config:")
        println("  Initial backoff: 1000ms, Max: 30s, Multiplier: 2.0")
        println("  Server: ${info.host}\n")
    }
}

private suspend fun logLevelConfiguration() {
    println("=== Log Level Configuration ===\n")
    val client = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = "kotlin-conn-debug"
        logLevel = LogLevel.DEBUG
    }
    client.use {
        it.ping()
        println("DEBUG logging client connected.\n")
    }
}

private suspend fun environmentConfiguration() {
    println("=== Environment Configuration ===\n")
    val envConfig = ClientConfig.fromEnvironment()
    println("Env address: ${envConfig.address}")
    println("Env clientId: ${envConfig.clientId}")

    val client = KubeMQClient.pubSub {
        address = envConfig.address.ifBlank { ADDRESS }
        clientId = envConfig.clientId.ifBlank { "kotlin-conn-env" }
        authToken = envConfig.authToken
    }
    client.use {
        println("Environment-based client created.\n")
    }
}
```

## How It Works [#how-it-works]

* Each function demonstrates a different configuration approach using the DSL builder pattern.
* `KubeMQClient.pubSub { }`, `.queues { }`, and `.cq { }` create pattern-specific clients.
* The `use { }` block ensures automatic cleanup when the block exits.
* `ClientConfig.fromEnvironment()` reads `KUBEMQ_ADDRESS`, `KUBEMQ_CLIENT_ID`, and `KUBEMQ_AUTH_TOKEN` environment variables.
* Reconnection is configured with exponential backoff via the `reconnection { }` DSL block.

## Related [#related]

* [Kotlin SDK Reference](/sdks/kotlin/reference)
* [Close](/sdks/kotlin/how-to/connection/close)
* [Ping](/sdks/kotlin/how-to/connection/ping)