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

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)

Code

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

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.

Connect

Overview

Prerequisites

Code

How It Works

Related

On this page