evoid-cluster 0.1.2

Cluster plugin for evoid — connect multiple nodes into a unified system

evoid-cluster

Multi-node clustering — Intent Handler system

Quick Start • Intent Handler • Architecture • API

---

Quick Start

uv add evoid-cluster

Method 1: Intent Handler (Recommended)

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

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)

[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.

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
• Documentation
• Plugin Collection

License

MIT