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 a task and cascades into upstream timeouts.

The timeout is set per call with timeout_in_seconds on 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's happening in your event loop. When the window elapses with no response, send_command raises an exception surfaced as KubeMQTimeoutError — your signal to retry or circuit-break.

Gotchas: a command timeout and any asyncio cancellation you've layered on top are two separate clocks, so don't assume one implies the other; a slow-but-alive handler and a completely absent one produce the same timeout error, so you can't tell them apart from the exception alone; and setting the timeout too short under normal load turns transient latency into false failures.

Prerequisites

• KubeMQ server running on localhost:50000
• Python SDK installed (pip install kubemq)

Code

"""Example: Command timeout — demonstrate command timeout when no responder exists."""

from __future__ import annotations

import asyncio

from kubemq import AsyncCQClient, CommandMessage


async def main() -> None:
    async with AsyncCQClient(
        address="localhost:50000",
        client_id="python-commands-command-timeout-client",
    ) as client:
        try:
            # Send a command with no responder — will time out
            response = await client.send_command(
                CommandMessage(
                    channel="python-commands.command-timeout",
                    body=b"this will time out",
                    timeout_in_seconds=3,
                )
            )
            print(f"Executed: {response.is_executed}, Error: {response.error}")
        except Exception as e:
            print(f"Command timed out as expected: {e}")


if __name__ == "__main__":
    asyncio.run(main())

How It Works

send_command sends the command with timeout_in_seconds=3 but no responder is subscribed on python-commands.command-timeout. After 3 seconds KubeMQ returns a timeout response. The exception handler catches it so the program exits cleanly rather than crashing. In production, a missing responder typically means a service is down — the KubeMQTimeoutError is your signal to circuit-break or retry.

Related

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