Command Timeout

Overview

A command timeout is the deadline you attach to a single RPC call so a caller never blocks forever waiting on a handler that isn't there or isn't responding. Commands are synchronous by design — the sender is parked until a reply arrives — so without a bound, a missing subscriber or a crashed handler turns one request into an indefinite hang that ties up the calling thread and cascades into upstream timeouts.

The timeout is set per call with timeout on KubeMQ::CQ::CommandMessage, and it's enforced by the broker itself, not by client-side polling: the broker tracks the deadline server-side and fails the request the moment it expires, regardless of what the calling thread is doing. When the window elapses with no response, send_command returns a result with a populated error instead of a clean reply — your signal to retry or fall back.

Gotchas: timeout on CommandMessage is expressed in milliseconds, not seconds, unlike queue wait timeouts — an easy unit mistake; a slow-but-alive handler and a completely absent one produce the same timeout error, so you can't tell them apart from the error alone; and setting the timeout too short under normal load turns transient latency into false failures.

Prerequisites

• KubeMQ server running on localhost:50000
• Ruby SDK installed (gem install kubemq)

Code

require 'kubemq'

address = ENV.fetch('KUBEMQ_ADDRESS', 'localhost:50000')
channel = 'ruby-rpc.command-timeout'

begin
  client = KubeMQ::CQClient.new(address: address, client_id: 'cmd-timeout-example')
  puts "Connected to #{address}"

  puts 'Sending command with short timeout and no handler...'
  msg = KubeMQ::CQ::CommandMessage.new(
    channel: channel,
    timeout: 2,
    metadata: 'will-timeout',
    body: 'no-handler'
  )

  result = client.send_command(msg)
  if result.error.to_s.empty?
    puts "Command response (unexpected): executed=#{result.executed}"
  else
    puts "Command timed out (expected): #{result.error}"
  end
rescue KubeMQ::Error => e
  puts "Command timed out (expected): #{e.message}"
ensure
  client&.close
  puts 'Done'
end

How It Works

• When no handler subscribes to the command channel, the sender receives a timeout error.
• The timeout value (in milliseconds) determines how long the broker waits for a handler to respond.
• Use appropriate timeouts based on expected handler processing time.
• Review timeouts, channel names, and client IDs before running against shared environments.

Related

• Pattern overview
• Ruby SDK Reference
• Send Command
• Handle Command