Metadata-Version: 2.4
Name: evoid-cluster
Version: 0.1.2
Summary: Cluster plugin for evoid — connect multiple nodes into a unified system
Project-URL: Homepage, https://github.com/EvolveBeyond/evoid-plugins
Project-URL: Repository, https://github.com/EvolveBeyond/evoid-plugins
Author-email: EvolveBeyond <pakrohk@gmail.com>
License: MIT
Keywords: cluster,distributed,evoid,mesh,multi-node
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: cryptography>=42.0
Requires-Dist: evoid-di>=0.1.0
Requires-Dist: evoid>=0.4.3
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/pypi/v/evoid-cluster?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI">
  <img src="https://img.shields.io/pypi/pyversions/evoid-cluster?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/pypi/l/evoid-cluster?style=for-the-badge" alt="License">
</p>

<h1 align="center">evoid-cluster</h1>

<p align="center">
  <strong>Multi-node clustering — Intent Handler system</strong>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#intent-handler">Intent Handler</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#api">API</a>
</p>

---

## Quick Start

```bash
uv add evoid-cluster
```

### Method 1: Intent Handler (Recommended)

```python
from evoid_cluster import register_handlers

# Register cluster as Intent handlers
register_handlers(config={
    "node": {"id": "node-1", "host": "0.0.0.0", "port": 9100},
    "cluster": {"secret": "my-secret"},
})
```

### Method 2: Direct API

```python
from evoid_cluster import ClusterBridge, ClusterConfig

config = ClusterConfig.from_toml("cluster.toml")
bridge = ClusterBridge(config)
```

---

## Intent Handler

evoid-cluster registers inter-node communication as Intent handlers.

---

## Architecture

```
Node A (users)  ←──WebSocket──→  Node B (chat)
       ↕                              ↕
Node C (database) ←──WebSocket──→  Node D (game)
```

Each node:
1. Announces its services via Intent through the message bus
2. ClusterBridge forwards intents to remote nodes
3. Only Intent and Result flow between nodes — never raw data

---

## Configuration

### TOML (separate file)

```toml
[node]
id = "node-1"
host = "0.0.0.0"
port = 9100

[cluster]
secret = "my-cluster-secret"

[cluster.peers]
"node-b" = { host = "192.168.1.11", port = 9100 }
```

---

## API

### `register_handlers(config: dict)`

Register cluster as Intent handlers.

### ClusterBridge Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `start` | `async start()` | Start cluster node |
| `stop` | `async stop()` | Stop cluster node |
| `broadcast` | `async broadcast(intent)` | Send intent to all peers |

---

## DI Integration

All plugins register with evoid-di for automatic service discovery and fault tolerance.

```python
from evoid_di import di

# Resolve with fallback
storage = di.resolve_with_fallback("storage.postgresql")
# Tries: postgresql → sqlite → redis → cluster peers → None
```

## Dependencies

- `evoid>=0.4.0`
- `websockets>=12.0`

## Links

- [EVOID Runtime](https://github.com/EvolveBeyond/EVOID)
- [Documentation](https://evolvebeyond.github.io/EVOID/)
- [Plugin Collection](https://evolvebeyond.github.io/EVOID/learn/plugin-collection/)

## License

MIT
