TLS Setup

Overview

Server-side TLS is the baseline transport security for any KubeMQ connection that leaves a trusted network — it encrypts the wire and lets the client confirm it's really talking to your KubeMQ server, not an impersonator. Reach for it whenever traffic crosses a public network or a boundary you don't fully control; skip it and channel names, payloads, and client IDs travel in plaintext with no protection against a spoofed endpoint.

It works by pairing the client with the CA certificate that signed the server's TLS certificate: the tls option with enabled: true and a caCert path loads that CA file, and the client performs a standard TLS handshake, validating the server's certificate chain before any request is sent. The client presents no certificate of its own — only the server proves its identity.

Gotchas: this is one-way trust — it stops eavesdropping and server impersonation, but the server still can't verify who the client is (that's what mTLS adds). caCert must point to the issuing CA (or full chain), not the server's leaf certificate, or the handshake fails outright. And an expired or hostname-mismatched server certificate surfaces as the same ConnectionError as a missing CA path — check err.message and err.suggestion before assuming your CA file is the problem.

Prerequisites

• KubeMQ server running with TLS enabled
• Node.js SDK installed (npm install kubemq-js)
• TLS certificates (CA certificate file)

Code

/**
 * Example: TLS Connection Setup
 *
 * Demonstrates connecting to a KubeMQ server with TLS encryption.
 * The client verifies the server's certificate against the provided
 * CA certificate.
 *
 * Prerequisites:
 *   - KubeMQ server running with TLS enabled
 *   - CA certificate file available locally
 *
 * Run: npx tsx examples/configuration/tls-setup.ts
 */
import { KubeMQClient, ConnectionError } from 'kubemq-js';

async function main(): Promise<void> {
  try {
    const client = await KubeMQClient.create({
      address: 'kubemq-server:50000',
      clientId: 'js-configuration-tls-setup-client',
      tls: {
        enabled: true,
        caCert: '/path/to/ca-cert.pem',
      },
    });

    console.log('Connected to KubeMQ with TLS');
    console.log('Connection state:', client.state);

    await client.close();
  } catch (err) {
    if (err instanceof ConnectionError) {
      console.error('TLS connection failed:', err.message);
      console.error('Suggestion:', err.suggestion);
    }
  }
}

main().catch(console.error);

How It Works

• The tls configuration object with enabled: true and a caCert path activates server-side TLS.
• The client verifies the server's certificate against the provided CA certificate before establishing the connection.
• ConnectionError provides a suggestion field with troubleshooting hints when connection fails.
• Replace '/path/to/ca-cert.pem' with the actual path to your CA certificate.

Related

• Node.js SDK Reference
• mTLS Setup