hydra-router 0.5.0

ZeroMQ-based client-server communication framework

Hydra Router

A standalone ZeroMQ-based message routing system that provides reliable communication between multiple clients and a single server.

Features

• Centralized Message Routing: Routes messages between multiple clients and a single server
• Message Format Conversion: Automatic conversion between internal and router message formats
• Heartbeat Monitoring: Automatic client health monitoring and connection tracking
• Comprehensive Error Handling: Detailed validation and error reporting
• Simple Examples: Includes simple client/server examples for quick testing
• Client Registry Query: Query router for connected client information

Installation

pip install hydra-router

Quick Start

Start the Router

# Basic usage
hydra-router

# Custom configuration
hydra-router --address 0.0.0.0 --port 5556 --log-level INFO

Simple Client/Server Demo

# Terminal 1: Start the router
hydra-router --log-level DEBUG

# Terminal 2: Start the simple server
hydra-server_simple --router tcp://localhost:5556

# Terminal 3: Start the simple client
hydra-client_simple --router tcp://localhost:5556
# Then enter numbers to see their squares calculated by the server

Using the MQClient Library

from hydra_router import MQClient, RouterConstants

# Create a client
client = MQClient(
    router_address="tcp://localhost:5556",
    client_type=RouterConstants.HYDRA_CLIENT,
    client_id="my-client-001"
)

# Connect and send messages
await client.connect()
await client.send_message(my_message)

# Query connected clients
client_table = await client.request_client_registry()
print("Connected clients:", client_table)

Architecture

The Hydra Router system consists of:

• HydraRouter: Central message routing component
• MQClient: Generic client library for applications
• RouterConstants: Message format definitions and constants
• SimpleClient/SimpleServer: Example applications

Configuration

The router supports the following command-line options:

• --address, -a: IP address to bind to (default: 0.0.0.0)
• --port, -p: Port to bind to (default: 5556)
• --log-level: Logging level (DEBUG, INFO, WARNING, ERROR, default: INFO)
• --help, -h: Show help message

Requirements

• Python 3.11+
• ZeroMQ (pyzmq)

License

GPL-3.0

Contributing

This project follows the specification-driven development methodology. See the .kiro/specs/ directory for detailed requirements, design, and implementation tasks.

Packaging & publishing 🔁

• Local development and install (recommended):

poetry lock      # update lockfile
poetry install   # install deps into the active environment

• Run the console command from the Poetry environment:

poetry run hydra-router   # or `poetry run hydra_router`
# or: python -m hydra_router

• Publishing is handled by a GitHub Actions workflow that publishes on tag push (v*.*.*). See .github/workflows/pypi-publish.yml for the exact steps (install Poetry, build, and poetry publish).

Note: The project uses Poetry/PEP621 [project.scripts] to declare console entry points (no setuptools entry-points). If you bump the package version, tag a release vX.Y.Z to trigger the publish workflow.