API

HydraServer

HydraClient

class hydra_router.client.HydraClientTui.HydraClientTui(address='localhost', port=5757)

Bases: App

A Textual interface to the HydraServer

TITLE: str | None = 'Hydra Client'

A class variable to set the default title for the application.

To update the title while the app is running, you can set the [title][textual.app.App.title] attribute. See also [the Screen.TITLE attribute][textual.screen.Screen.TITLE].

CSS_PATH: ClassVar[CSSPathType | None] = 'HydraClient.tcss'

File paths to load CSS from.

__init__(address='localhost', port=5757)

Constructor

compose()

The TUI is created here

check_connection_bg()

console_msg(msg)

async on_button_pressed(event)

on_mount()

async on_quit()

HydraRouter

class hydra_router.router.HydraRouterTui.HydraRouterTui(address='*', port=5757, heartbeat_port=5758)

Bases: App

A Textual interface to the HydraServer

TITLE: str | None = 'Hydra Router'

A class variable to set the default title for the application.

To update the title while the app is running, you can set the [title][textual.app.App.title] attribute. See also [the Screen.TITLE attribute][textual.screen.Screen.TITLE].

CSS_PATH: ClassVar[CSSPathType | None] = 'HydraRouter.tcss'

File paths to load CSS from.

__init__(address='*', port=5757, heartbeat_port=5758)

Constructor

bg_hb_listen()

bg_listen()

compose()

The TUI is created here

console_msg(msg)

async handle_hb(routing_id, msg)

async handle_message(routing_id, msg)

async on_button_pressed(event)

on_mount()

async on_quit()

update_client_table()

HydraMsg

class hydra_router.utils.HydraMsg.HydraMsg(sender, target, method, payload=None)

Bases: object

Structured message class for HydraRouter communication protocol.

HydraMsg encapsulates messages for ZeroMQ-based RPC communication. It handles serialization/deserialization and provides a clean API for creating and accessing message components.

Internal representation uses Python objects (dict for payload). Serialization to JSON happens only when converting to wire format.

# Serialize for transmission json_bytes = msg.to_json()

# Deserialize from received data msg = HydraMsg.from_json(json_bytes)

__init__(sender, target, method, payload=None)

Initialize a new HydraMsg instance.

Parameters:

• sender (str) – Identifier of the message sender

• target (str) – Identifier of the intended message recipient

• method (str) – RPC method or action to be performed

• payload (dict[str, Any] | None) – Message data as a dictionary (not JSON string)

Returns:

None

Return type:

None

property sender: str

Get the message sender identifier.

property target: str

Get the message target identifier.

property method: str

Get the RPC method name.

property payload: dict[str, Any]

Get the message payload as a dictionary.

classmethod from_dict(data)

Create a HydraMsg from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary containing message fields

Returns:

HydraMsg instance

Raises:

KeyError – If required fields are missing

Return type:

HydraMsg

classmethod from_json(json_data)

Create a HydraMsg from JSON bytes.

Parameters:

json_data (bytes) – JSON-encoded message as bytes

Returns:

HydraMsg instance

Raises:

• json.JSONDecodeError – If json_data is not valid JSON

• UnicodeDecodeError – If json_data cannot be decoded as UTF-8

Return type:

HydraMsg

to_dict()

Convert message to dictionary representation.

Returns:

Dictionary containing all message fields including version

Return type:

dict[str, Any]

to_json()

Convert message to JSON bytes for transmission.

Returns:

JSON-encoded message as UTF-8 bytes ready for ZeroMQ

Raises:

TypeError – If message contains non-serializable objects

Return type:

bytes

__repr__()

Return string representation of message for debugging.

Returns:

String showing message structure

Return type:

str

__str__()

Return human-readable string representation.

Returns:

Formatted string with message details

Return type:

str

HydraMQ

class hydra_router.utils.HydraMQ.HydraMQ(router_address='localhost', router_port=5757, router_hb_port=5758, identity=DModule.HYDRA_MQ, srv_bind_address='*', srv_bind_port=5759, srv_methods=None)

Bases: object

Async ZeroMQ client for HydraRouter communication.

HydraMQ provides an async DEALER socket client that connects to a HydraRouter instance. It handles message serialization, heartbeats, and connection lifecycle.

The client uses a DEALER socket which allows asynchronous bidirectional communication through a ROUTER-based message broker.

Example

mq = HydraMQ(

router_address=”localhost”, router_port=5757, id=”my-service”

)

# Send message msg = HydraMsg(

sender=mq.identity, target=”other-service”, method=”ping”, payload={“data”: “test”}

) await mq.send(msg)

# Receive message response = await mq.recv() print(response.payload)

# Cleanup await mq.quit()

__init__(router_address='localhost', router_port=5757, router_hb_port=5758, identity=DModule.HYDRA_MQ, srv_bind_address='*', srv_bind_port=5759, srv_methods=None)

Initialize HydraMQ client.

Parameters:

• router_address (str) – Hostname/IP of the HydraRouter

• router_port (int) – Port number of the HydraRouter

• id – Base identifier for this client (random suffix added)

• heartbeat_enabled – Whether to send periodic heartbeats

Returns:

None

Return type:

None

async bg_listen()

connected()

async quit()

Cleanly shutdown the HydraMQ client.

Stops heartbeat task, disconnects from router, and cleans up ZeroMQ resources.

Returns:

None

Return type:

None

async recv()

Receive a HydraMsg from the router.

Waits for an incoming message, deserializes it, and returns a HydraMsg instance.

Parameters:

timeout – Maximum time to wait for a message in seconds

Returns:

HydraMsg instance

Raises:

• asyncio.TimeoutError – If no message received within timeout

• zmq.ZMQError – If receive operation fails

• json.JSONDecodeError – If message is not valid JSON

Return type:

HydraMsg

async send(msg)

Send a HydraMsg through the router.

Serializes the message to JSON and sends it through the DEALER socket to the connected ROUTER.

Parameters:

msg (HydraMsg) – HydraMsg instance to send

Returns:

None

Raises:

zmq.ZMQError – If send operation fails

Return type:

None

start()

started()

async start_heartbeat_bg()

Periodic heartbeat loop to keep connection alive.

Sends heartbeat messages to the router at regular intervals to indicate this client is still active.

Returns:

None

Return type:

None

HydraLog

class hydra_router.utils.HydraLog.HydraLog(client_id, log_file=None, to_console=True, log_level=DHydraLog.DEBUG)

Bases: object

Centralized logging utility for HydraRouter components.

HydraLog provides a standardized logging interface with configurable output destinations (console and/or file) and log levels. It wraps Python’s standard logging module with HydraRouter-specific formatting and configuration.

__init__(client_id, log_file=None, to_console=True, log_level=DHydraLog.DEBUG)

Initialize the HydraLog instance with specified configuration.

Parameters:

• client_id (str) – Unique identifier for the logging client

• log_file (Optional[str]) – Path to log file for file output

• to_console (bool) – Whether to output logs to console

Returns:

None

Return type:

None

loglevel(loglevel)

Set the logging level for this logger instance.

Parameters:

loglevel (DHydraLog) – Log level string from DHydraLog constants

Returns:

None

Raises:

KeyError – If loglevel is not a valid log level constant

Return type:

None

shutdown()

Cleanly shutdown the logging system and flush all handlers.

Returns:

None

Return type:

None

info(message, extra=None)

Log an informational message.

Parameters:

• message (str) – The message to log

• extra (Optional[Dict[str, Any]]) – Extra context data for logging

Returns:

None

Return type:

None

debug(message, extra=None)

Log a debug message.

Parameters:

• message (str) – The message to log

• extra (Optional[Dict[str, Any]]) – Extra context data for logging

Returns:

None

Return type:

None

warning(message, extra=None)

Log a warning message.

Parameters:

• message (str) – The message to log

• extra (Optional[Dict[str, Any]]) – Extra context data for logging

Returns:

None

Return type:

None

error(message, extra=None)

Log an error message.

Parameters:

• message (str) – The message to log

• extra (Optional[Dict[str, Any]]) – Extra context data for logging

Returns:

None

Return type:

None

critical(message, extra=None)

Log a critical error message.

Parameters:

• message (str) – The message to log

• extra (Optional[Dict[str, Any]]) – Extra context data for logging

Returns:

None

Return type:

None