Ping

Overview

A ping is a lightweight liveness check — you call it to confirm the broker is actually reachable before sending real traffic, without standing up a publisher, subscriber, or queue client just to find out. It's the tool of choice for startup readiness checks, container liveness/readiness probes, and connection-health dashboards that need a fast, cheap go/no-go signal.

client.ping() issues a minimal health-check RPC to the server and returns a ServerInfo object (host, version, serverUpTimeSeconds) confirming the broker answered. It works over the same connection regardless of which messaging pattern you use elsewhere on that client — events, queues, commands, or queries.

Gotchas: a failed ping() doesn't close the client — the SDK's reconnect logic keeps retrying in the background, so catch the thrown exception yourself rather than assume the client tears itself down. A successful ping only confirms the broker process answered, not that a specific channel or queue exists or has capacity. Unlike some other KubeMQ SDKs, Kotlin has no build-time validateOnBuild fail-fast option — you should call ping() explicitly right after construction for an early connectivity check.

Prerequisites

• KubeMQ server running on localhost:50000
• Kotlin SDK installed (implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1"))

Code

package io.kubemq.sdk.examples.connection

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

private const val ADDRESS = "localhost:50000"
private const val CLIENT_ID = "kotlin-connection-ping"

fun main() = runBlocking {
    println("=== Ping KubeMQ Server ===\n")

    val client = KubeMQClient.queues {
        address = ADDRESS
        clientId = CLIENT_ID
    }
    client.use {
        val serverInfo = client.ping()
        println("Ping successful!")
        println("  Host: ${serverInfo.host}")
        println("  Version: ${serverInfo.version}")
        println("  Server Start Time: ${serverInfo.serverStartTime}")
        println("  Server Uptime: ${serverInfo.serverUpTimeSeconds} seconds")
    }

    // Kotlin SDK does not have validateOnBuild; use explicit ping() instead
    println("\n=== Validate via Explicit Ping ===\n")
    val client2 = KubeMQClient.pubSub {
        address = ADDRESS
        clientId = "$CLIENT_ID-validate"
    }
    client2.use {
        try {
            client2.ping()
            println("Connectivity validated via explicit ping().")
        } catch (e: Exception) {
            println("Connectivity validation failed: ${e.message}")
        }
    }

    println("\nPing examples completed.")
}

How It Works

• ping() performs a health check RPC to the KubeMQ server and returns ServerInfo.
• ServerInfo contains host, version, serverStartTime, and serverUpTimeSeconds.
• Use ping() after client creation to validate connectivity before sending messages.
• The Kotlin SDK does not have a validateOnBuild flag -- use explicit ping() calls instead.

Related

• Connect
• Kotlin SDK Reference
• Connection Error