Metadata-Version: 2.1
Name: ZeroMqMessageHandler
Version: 2.5.0
Author-email: Eduardo Almeida <eduardo.almeida@e-deploy.com.br>
Maintainer-email: Eduardo Almeida <eduardo.almeida@e-deploy.com.br>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: MessageBus~=1.2
Requires-Dist: ZeroMqThreadPool~=2.4

# ZeroMqMessageHandler

ZeroMQ-based message handling and event bus infrastructure for the e-deploy microservice platform.

## Overview

ZeroMqMessageHandler provides the transport layer for inter-service communication using ZeroMQ. It handles synchronous request/reply messaging, asynchronous event pub/sub, service discovery via ServiceLocator, and automatic keep-alive management.

## Dependencies

- `MessageBus` (~1.2) - Message and event abstractions
- `ZeroMqThreadPool` (~2.3) - Thread pool with ZeroMQ worker lifecycle

## Installation

```bash
source python_path.sh
./install_lib.sh
```

Dependencies are installed into a local `lib/` directory using the private package index at `https://pip.e-deploy.com.br`.

## Usage

```python
import zmq
from zeromqmessagehandler import ZeroMqMessageBus, ZeroMqMessageHandler

context = zmq.Context()

# Create the message bus
message_bus = ZeroMqMessageBus("MyService", context)

# Create and start the handler
handler = ZeroMqMessageHandler(
    context,
    "MyService",
    message_bus,
    my_message_handler_builder,
)
handler.handle_messages()
```

## Architecture

### Request/Reply Flow

```
Client (REQ) -> QueueDevice (ROUTER/ROUTER) -> HandleMessageWorkerThread (DEALER)
```

`QueueDevice` acts as a load balancer, distributing incoming requests to available worker threads. Workers follow a READY/DYING/DIED lifecycle protocol.

### Event Flow

```
Publisher (PUB) -> EventManager -> HandleEventWorkerThread (PULL)
```

Asynchronous events are published via PUB sockets. Subscribers register with EventManager and receive events through a dedicated pull address. Non-reentrant event handling is supported via per-context per-subject locks.

### Wire Protocol

All messages use null-byte (`\0`) delimited binary format:

- **Messages**: `token\0data_type\0timeout\0header_count\0[key\0value\0]...\0data`
- **Events**: `subject<space>event_type\0header_count\0[key\0value\0]...\0data`

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `SERVICE_ADDRESS` | TCP address for this service (must start with `tcp://`) | Auto-detected |
| `HOSTNAME` | Fallback for service address resolution | - |
| `SERVICE_LOCATOR_ADDRESS` | ServiceLocator address | `tcp://localhost:6000` |
| `EVENT_MANAGER_ADDRESS` | EventManager address | `tcp://localhost:5000` |
| `ASSUME_LOCALHOST` | Rewrite all addresses to localhost (set to `TRUE` for dev) | Disabled |
| `ZMQ_SOCKET_CLOSE_STRATEGY` | `DISCONNECT`: disconnect + close(linger=0) to force TCP FD teardown; `CLOSE`: close(linger=N) only | `DISCONNECT` |

## Public API

| Class | Description |
|---|---|
| `ZeroMqMessageHandler` | Top-level orchestrator that binds a TCP port and manages thread pools |
| `ZeroMqMessageBus` | Implements `MessageBus` with service discovery, socket caching, and pub/sub |
| `HandleEventWorkerThread` | Worker thread for processing async events |
| `MessageDecoder` | Serialization/deserialization for the binary wire protocol |
