Custom Timeouts

Overview

Every client operation has an implicit deadline — how long to wait for the initial connection, how long before a dead socket is detected, how long a single RPC blocks before giving up, how long reconnection retries keep running. The defaults are reasonable for a healthy local network, but they're wrong for high-latency links, connections that pass through load balancers or NAT gateways, or servers that occasionally run slow under load. Tuning timeouts explicitly is how you trade fast-fail behavior against tolerance for transient slowness.

Each timeout targets a different phase of the client lifecycle. ClientConfig's auto_reconnect and reconnect_interval_seconds control how the client retries a dropped connection; KeepAliveConfig's ping_interval_in_seconds / ping_timeout_in_seconds configure periodic pings that detect a stale connection before you try to use it; and timeout_in_seconds on an individual message (like CommandMessage) bounds how long that specific call waits for a response before raising KubeMQTimeoutError. Gotchas: a per-message timeout shorter than the server's real processing time causes spurious failures, not faster detection of a genuinely broken command handler; an aggressive ping_interval_in_seconds can flag a slow-but-healthy link as dead; and auto_reconnect=True with no bound on attempts will keep retrying against a server that's down for good, silently masking an outage instead of surfacing it.

Prerequisites

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

Code

"""Example: Custom timeouts — configure operation and reconnection timeouts."""

from __future__ import annotations

import asyncio

from kubemq import ClientConfig, KeepAliveConfig
from kubemq import AsyncCQClient, CommandMessage


async def main() -> None:
    config = ClientConfig(
        address="localhost:50000",
        client_id="python-connection-custom-timeouts-client",
        auto_reconnect=True,
        reconnect_interval_seconds=2,
        keep_alive=KeepAliveConfig(
            enabled=True,
            ping_interval_in_seconds=15,
            ping_timeout_in_seconds=5,
        ),
    )

    async with AsyncCQClient(config=config) as client:
        info = await client.ping()
        print(f"Connected to {info.host} with custom timeouts")

        # Commands have per-message timeout via timeout_in_seconds
        try:
            response = await client.send_command(
                CommandMessage(
                    channel="python-connection.custom-timeouts",
                    body=b"test operation",
                    timeout_in_seconds=5,
                )
            )
            print(f"Command executed: {response.is_executed}")
        except Exception as e:
            print(f"Operation failed: {e}")


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

How It Works

A ClientConfig object is built with auto_reconnect=True, reconnect_interval_seconds=2, and a KeepAliveConfig that sends keep-alive pings every 15 seconds with a 5-second timeout. Passing config=config to AsyncCQClient uses these settings instead of defaults. Per-message timeouts are set separately on each CommandMessage via timeout_in_seconds, which controls how long send_command waits for a response before raising KubeMQTimeoutError.

Related

• Python SDK Reference
• Connect
• Close