RequestHandler

veltix.handler.request_handler.RequestHandler

Handles incoming message routing, correlation, and callback dispatch.

This class centralizes all message handling logic including: - Automatic PING/PONG responses - Automatic HELLO/HELLO_ACK handshake (client side) - Request/response correlation for send_and_wait() - Per-type route callbacks registered via register_route() - Default on_recv fallback for unrouted messages - All user callbacks are executed in a thread pool so slow handlers never block the recv loop

Thread-safe for concurrent message handling. Works in both SERVER and CLIENT modes.

__init__

__init__(sender: Sender, mode: Union[Mode, str], max_workers: int = 4)

Initialize the request handler.

Parameters:

Name	Type	Description	Default
sender	Sender	Sender instance for outgoing messages.	required
mode	Union[Mode, str]	Operation mode (Mode.SERVER or Mode.CLIENT).	required
max_workers	int	Number of worker threads for callback execution (default: 4).	4

handle

handle(response: Response, client=None) -> Union[Exception, bool]

Handle an incoming message with full routing logic.

Processing order: 1. Auto-respond to PING with PONG 2. Auto-handle HELLO (client side only) — respond with HELLO_ACK 3. Deliver to pending request queue if send_and_wait() is waiting 4. Dispatch to a registered route if one matches the message type 5. Fall back to the default on_recv callback 6. Log a warning if nothing handled the message

Parameters:

Name	Type	Description	Default
response	Response	Incoming response to handle.	required
client		ClientInfo if SERVER mode, None if CLIENT mode.	None

Returns:

Type	Description
Union[Exception, bool]	True if handled successfully, Exception if an unexpected error occurred.

register

register(request_id: str) -> Queue

Register a pending request before sending it.

Must be called BEFORE sending the request to avoid race conditions where the response could arrive before the queue is registered.

Parameters:

Name	Type	Description	Default
request_id	str	Unique request identifier to register.	required

Returns:

Type	Description
Queue	Queue instance that will receive the matching response.

unregister

unregister(request_id: str) -> None

Unregister a pending request, discarding its queue.

Parameters:

Name	Type	Description	Default
request_id	str	Unique request identifier to unregister.	required

wait

wait(request_id: str, timeout: float = 5.0) -> Optional[Response]

Wait for a response matching the given request_id.

Must be called after register() to ensure the queue exists. Automatically cleans up the pending request entry on completion or timeout.

Parameters:

Name	Type	Description	Default
request_id	str	Unique request identifier to wait for.	required
timeout	float	Maximum time to wait in seconds (default: 5.0).	5.0

Returns:

Type	Description
Optional[Response]	Matching Response if received within timeout, None otherwise.

set_on_recv

set_on_recv(callback: Callable) -> None

Set the default callback for all unrouted messages.

Called for any message that has no matching registered route and is not awaited by send_and_wait().

Parameters:

Name	Type	Description	Default
callback	Callable	Function to call for incoming messages. - SERVER mode: callback(client: ClientInfo, response: Response) - CLIENT mode: callback(response: Response)	required

register_route

register_route(type_: MessageType, function: Callable) -> bool

Register a callback for a specific message type.

Routed callbacks take priority over the default on_recv callback. The route callback is executed in the thread pool, just like on_recv, so slow handlers never block the recv loop.

Parameters:

Name	Type	Description	Default
type_	MessageType	Message type to intercept.	required
function	Callable	Callback to invoke when a message of this type arrives. Signature: callback(response: Response, client: ClientInfo | None)	required

Returns:

Type	Description
bool	True if the route was registered, False if already registered.

unregister_route

unregister_route(type_: MessageType) -> bool

Unregister the callback for a specific message type.

After unregistering, messages of this type will fall through to the default on_recv callback (or be dropped if none is set).

Parameters:

Name	Type	Description	Default
type_	MessageType	Message type to unregister.	required

Returns:

Type	Description
bool	True if the route was removed, False if it was not registered.

shutdown

shutdown() -> None

Shutdown the executor gracefully.

Should be called when the server or client is shutting down to allow in-progress callbacks to complete cleanly.