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

DI Integration

Cluster connects its registry to evoid-di, making remote services available as fallbacks:

from evoid_di import di
from evoid_cluster import ClusterBridge

bridge = ClusterBridge(config)
await bridge.start()

# Remote services become available via DI:
di.set_cluster_registry(bridge._registry)
storage = di.resolve("storage.postgresql")  # checks peers if not local

Dependencies

• evoid>=0.4.0
• websockets>=12.0

Links

• EVOID Runtime
• Documentation
• Plugin Collection

License

MIT