Send Command

Overview

A command is KubeMQ's fire-and-confirm RPC pattern: you reach for it when you need to know that an action actually ran on the other end — "set the temperature," "restart the service" — but you don't need any data back, just a yes/no on execution. It's the middle ground between one-way pub/sub, where you get no confirmation at all, and a query, where the handler returns a result payload. Commands turn "I hope that worked" into a definite outcome your caller can branch on.

This sample builds that lesson: createCommand() builds the message with a timeoutInSeconds window, and client.sendCommand() blocks until a handler replies — the response carries executed: true on success or an error string on failure. If no handler responds in time, the SDK throws KubeMQTimeoutError instead of returning a response you'd have to check.

Gotchas: if no handler is subscribed (or it's still starting up), sendCommand() waits for the full timeoutInSeconds before throwing — there's no fast "nobody's listening" error. Catch KubeMQTimeoutError and ConnectionError separately, since they mean different things (no handler vs. broker unreachable). And a command's response carries no business data — if you need the handler to return a value, use sendQuery instead.

Prerequisites

• KubeMQ server running on localhost:50000
• Node.js SDK installed (npm install kubemq-js)

Code

/**
 * Example: Send Command
 *
 * Demonstrates sending a command (request/reply with no response payload).
 * Commands are used when you need confirmation that an action was executed
 * but don't need data back.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *   - A command handler running (see handle-command.ts)
 *
 * Run: npx tsx examples/rpc/send-command.ts
 */
import {
  KubeMQClient,
  createCommand,
  ConnectionError,
  KubeMQTimeoutError,
} from 'kubemq-js';

async function main(): Promise<void> {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-rpc-send-command-client',
  });

  try {
    const response = await client.sendCommand(
      createCommand({
        channel: 'js-rpc.send-command',
        body: JSON.stringify({ action: 'set-temperature', value: 22 }),
        timeoutInSeconds: 5,
        tags: { device: 'thermostat-living-room' },
      }),
    );

    if (response.executed) {
      console.log('Command executed successfully');
    } else {
      console.error('Command failed:', response.error);
    }
  } catch (err) {
    if (err instanceof KubeMQTimeoutError) {
      console.error('Command timed out — no handler responded within 5 seconds');
    } else if (err instanceof ConnectionError) {
      console.error('Connection error:', (err as ConnectionError).message);
    }
  } finally {
    await client.close();
  }
}

main().catch(console.error);

// Expected output:
// Command executed successfully

How It Works

• createCommand() builds an immutable command message with timeoutInSeconds: 5 — if no handler responds within 5 seconds the SDK throws KubeMQTimeoutError.
• await client.sendCommand() blocks until a handler replies; the response carries executed: true on success and an error string on failure.
• Commands carry no response payload — they confirm that an action happened but return no data. Use queries (sendQuery) when you need data back.
• The catch block demonstrates error differentiation: KubeMQTimeoutError means no handler was available; ConnectionError means the server was unreachable.

Related

• Pattern overview
• Node.js SDK Reference
• Handle Command
• Command Timeout