Connect

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, give it a stable identity, and confirm connectivity with a health check, so the pattern is muscle memory before you move on to real messaging.

kubemq.NewClient dials the broker over gRPC using an address and a ClientId — the ID tags this connection in broker logs, subscriptions, and management views, so pick something stable rather than a random string. client.Ping verifies the round trip cheaply: it returns live server info (host, version, uptime) instead of just "no error," proving the client is talking to a real broker rather than silently misconfigured. defer client.Close() releases the gRPC connection — skip it and you leak a transport handle per client.

Gotchas: a successful NewClient call doesn't always mean the broker is reachable — connection can happen lazily, so Ping is the only reliable proof; reusing the same client ID across running instances causes routing confusion on the broker; and forgetting to close the client in quick scripts is a common source of leaked connections under load.

Prerequisites

• KubeMQ server running on localhost:50000
• Go SDK installed (go get github.com/kubemq-io/kubemq-go/v2)

Code

// Example: connection/connect
//
// Demonstrates how to create a basic KubeMQ client connection.
// The client connects to a KubeMQ server on localhost:50000 and verifies
// connectivity with a Ping.
//
// Channel: go-connection.connect
// Client ID: go-connection-connect-client
//
// Run with a KubeMQ server on localhost:50000
// (see https://docs.kubemq.io/deploy).
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/kubemq-io/kubemq-go/v2"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Create a KubeMQ client with basic configuration.
	client, err := kubemq.NewClient(ctx,
		kubemq.WithAddress("localhost", 50000), // TODO: Replace with your KubeMQ server address
		kubemq.WithClientId("go-connection-connect-client"),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// Verify the connection by pinging the server.
	info, err := client.Ping(ctx)
	if err != nil {
		log.Fatalf("Ping failed: %v", err)
	}
	fmt.Printf("Connected successfully: host=%s version=%s uptime=%ds\n",
		info.Host, info.Version, info.ServerUpTimeSeconds)
}

// Expected output:
// Connected successfully: host=<host> version=<version> uptime=<uptime>s

How It Works

1. kubemq.NewClient(ctx, opts...) dials the broker over gRPC and returns a connected *Client. The ctx deadline bounds the initial connection attempt only; subsequent operations use their own contexts.
2. kubemq.WithAddress("localhost", 50000) sets the target host and gRPC port. Replace these with your server address in production.
3. client.Ping(ctx) performs a lightweight health check and returns *ServerInfo with Host, Version, and ServerUpTimeSeconds from the broker.
4. defer client.Close() drains in-flight operations and closes the underlying gRPC connection; always call it to release transport resources.

Related

• Go SDK Reference
• Close
• Ping