Connection Error

Overview

A network partition, a server that hasn't started yet, or a typo in the address are all normal facts of life in distributed systems — and a client that blocks indefinitely or panics on connect turns a routine outage into a cascading failure. Fail-fast connection checking lets you detect an unreachable KubeMQ server the moment you construct the client, with a bounded wait, so your service can log the failure, alert, or fall back instead of hanging.

kubemq.WithCheckConnection(true) makes NewClient perform a synchronous connectivity check during construction, paired with WithConnectionTimeout to cap how long that check waits before giving up and returning an error. Without it, NewClient succeeds unconditionally and any connection problem only surfaces later, on the first real operation. Gotchas: skip WithCheckConnection and a dead server looks identical to a healthy one until you try to use it — silent until it isn't; set the timeout too short and a merely slow (but healthy) server gets misreported as unreachable; a successful NewClient doesn't guarantee the connection stays up, so you still need reconnection handling for failures that happen mid-session.

Prerequisites

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

Code

// Example: error-handling/connection-error
//
// Demonstrates handling connection errors when the KubeMQ server is
// unreachable. Shows how to use WithCheckConnection to fail fast on
// startup, and how to handle connection failures gracefully.
//
// Channel: go-error-handling.connection-error
// Client ID: go-error-handling-connection-error-client
//
// This example intentionally connects to a non-existent server.
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()

	// Attempt to connect to a non-existent server with CheckConnection enabled.
	// This causes NewClient to fail fast if the server is unreachable.
	client, err := kubemq.NewClient(ctx,
		kubemq.WithAddress("localhost", 59999), // Non-existent server
		kubemq.WithClientId("go-error-handling-connection-error-client"),
		kubemq.WithCheckConnection(true),
		kubemq.WithConnectionTimeout(3*time.Second),
	)
	if err != nil {
		fmt.Printf("Connection failed (expected): %v\n", err)
		fmt.Println("Tip: Use WithCheckConnection(true) to detect unreachable servers at startup")
		return
	}
	defer client.Close()

	// If we get here, verify with a ping.
	info, err := client.Ping(ctx)
	if err != nil {
		log.Printf("Ping failed: %v", err)
		return
	}
	fmt.Printf("Connected: %s\n", info.Host)
}

How It Works

1. kubemq.WithCheckConnection(true) makes NewClient perform a synchronous connectivity check during construction and return an error immediately if the server is unreachable, rather than deferring errors to the first operation.
2. WithConnectionTimeout(3 * time.Second) caps how long the initial dial attempt waits before giving up.
3. Connecting to port 59999 intentionally triggers the error path so the example can demonstrate the failure message and the WithCheckConnection tip.
4. Without WithCheckConnection, the client constructor succeeds even when the server is down; failures would surface on the first actual operation instead.

Related

• Go SDK Reference
• Graceful Shutdown
• Reconnection