{"_id":"@aigentic/cluster","_rev":"2-3425a2e6a854c4c39ecba578e01d969b","name":"@aigentic/cluster","dist-tags":{"alpha":"0.1.0","latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aigentic/cluster","version":"0.1.0","keywords":["cluster","distributed","sharding","raft","consensus","vector-database"],"author":{"name":"rUv"},"license":"MIT","_id":"@aigentic/cluster@0.1.0","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"1fde8ffd67aa45defb5a98f10bb4e987d7928a42","tarball":"https://registry.npmjs.org/@aigentic/cluster/-/cluster-0.1.0.tgz","fileCount":2,"integrity":"sha512-Upy0YauPUxdcpFxts14aO8KRs6MLhdzMqH6v/Y3oKwNiKBCxAf36Ss6YeNcnDBBW03yyjMfCtdtr5jGFMHyFZA==","signatures":[{"sig":"MEYCIQD8TP4OWukw95wo5YdmuIHqYedQVmZhfYq1F8iLnqszUgIhAIHNWUDAYmJS3HfCr2Q1MgMm+iq/Ly30ma/CHjhtX99G","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7863},"main":"index.js","types":"index.d.ts","gitHead":"e2cb6210ce8d478b39cad81872a4aef78a05ceb4","scripts":{"test":"cargo test","build":"cargo build --release"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"_npmVersion":"11.12.0","description":"Distributed clustering and coordination for RuVector - auto-sharding, Raft consensus integration","directories":{},"_nodeVersion":"22.22.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cluster_0.1.0_1779324068263_0.23996656938028949","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-21T00:41:08.047Z","modified":"2026-09-13T15:30:28.573Z","0.1.0":"2026-05-21T00:41:08.433Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"author":{"name":"rUv"},"license":"MIT","homepage":"https://github.com/ruvnet/ruvector","keywords":["cluster","distributed","sharding","raft","consensus","vector-database"],"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git"},"description":"Distributed clustering and coordination for RuVector - auto-sharding, Raft consensus integration","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# Ruvector Cluster\n\n[![Crates.io](https://img.shields.io/crates/v/ruvector-cluster.svg)](https://crates.io/crates/ruvector-cluster)\n[![Documentation](https://docs.rs/ruvector-cluster/badge.svg)](https://docs.rs/ruvector-cluster)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Rust](https://img.shields.io/badge/rust-1.77%2B-orange.svg)](https://www.rust-lang.org)\n\n**Distributed clustering and sharding for Ruvector vector databases.**\n\n`ruvector-cluster` provides horizontal scaling capabilities with consistent hashing, shard management, and cluster coordination. Enables Ruvector to scale to billions of vectors across multiple nodes. Part of the [Ruvector](https://github.com/ruvnet/ruvector) ecosystem.\n\n## Why Ruvector Cluster?\n\n- **Horizontal Scaling**: Distribute data across multiple nodes\n- **Consistent Hashing**: Minimal rebalancing on cluster changes\n- **Auto-Sharding**: Automatic shard distribution and balancing\n- **Fault Tolerant**: Handle node failures gracefully\n- **Async-First**: Built on Tokio for high-performance networking\n\n## Features\n\n### Core Capabilities\n\n- **Cluster Membership**: Node discovery and health monitoring\n- **Consistent Hashing**: Ketama/Jump hash for shard placement\n- **Shard Management**: Create, migrate, and balance shards\n- **Node Coordination**: Leader election and consensus\n- **Failure Detection**: Heartbeat-based failure detection\n\n### Advanced Features\n\n- **Dynamic Rebalancing**: Auto-balance on node join/leave\n- **Rack Awareness**: Place replicas across failure domains\n- **Hot Spot Detection**: Identify and redistribute hot shards\n- **Gradual Migration**: Zero-downtime shard migration\n- **Cluster Metrics**: Prometheus-compatible metrics\n\n## Installation\n\nAdd `ruvector-cluster` to your `Cargo.toml`:\n\n```toml\n[dependencies]\nruvector-cluster = \"0.1.1\"\n```\n\n## Quick Start\n\n### Initialize Cluster\n\n```rust\nuse ruvector_cluster::{Cluster, ClusterConfig, Node};\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n    // Configure cluster\n    let config = ClusterConfig {\n        node_id: \"node-1\".to_string(),\n        listen_addr: \"0.0.0.0:7000\".parse()?,\n        seeds: vec![\"10.0.0.1:7000\".parse()?, \"10.0.0.2:7000\".parse()?],\n        replication_factor: 3,\n        num_shards: 64,\n        ..Default::default()\n    };\n\n    // Create and start cluster\n    let cluster = Cluster::new(config).await?;\n    cluster.start().await?;\n\n    // Wait for cluster to stabilize\n    cluster.wait_for_stable().await?;\n\n    println!(\"Cluster ready with {} nodes\", cluster.node_count().await);\n\n    Ok(())\n}\n```\n\n### Shard Operations\n\n```rust\nuse ruvector_cluster::{Cluster, ShardId};\n\n// Get shard for a vector ID\nlet shard_id = cluster.get_shard_for_key(\"vector-123\")?;\n\n// Get nodes hosting a shard\nlet nodes = cluster.get_shard_nodes(shard_id).await?;\nprintln!(\"Shard {} hosted on: {:?}\", shard_id, nodes);\n\n// Manual shard migration\ncluster.migrate_shard(shard_id, target_node).await?;\n\n// Trigger rebalance\ncluster.rebalance().await?;\n```\n\n### Cluster Health\n\n```rust\n// Check cluster health\nlet health = cluster.health().await?;\nprintln!(\"Status: {:?}\", health.status);\nprintln!(\"Healthy nodes: {}/{}\", health.healthy_nodes, health.total_nodes);\n\n// Get node status\nfor node in cluster.nodes().await? {\n    println!(\"{}: {:?} (last seen: {})\",\n        node.id,\n        node.status,\n        node.last_heartbeat\n    );\n}\n```\n\n## API Overview\n\n### Core Types\n\n```rust\n// Cluster configuration\npub struct ClusterConfig {\n    pub node_id: String,\n    pub listen_addr: SocketAddr,\n    pub seeds: Vec<SocketAddr>,\n    pub replication_factor: usize,\n    pub num_shards: usize,\n    pub heartbeat_interval: Duration,\n    pub failure_timeout: Duration,\n}\n\n// Node information\npub struct Node {\n    pub id: String,\n    pub addr: SocketAddr,\n    pub status: NodeStatus,\n    pub shards: Vec<ShardId>,\n    pub last_heartbeat: DateTime<Utc>,\n}\n\n// Shard information\npub struct Shard {\n    pub id: ShardId,\n    pub primary: NodeId,\n    pub replicas: Vec<NodeId>,\n    pub status: ShardStatus,\n    pub size_bytes: u64,\n}\n```\n\n### Cluster Operations\n\n```rust\nimpl Cluster {\n    pub async fn new(config: ClusterConfig) -> Result<Self>;\n    pub async fn start(&self) -> Result<()>;\n    pub async fn stop(&self) -> Result<()>;\n\n    // Membership\n    pub async fn nodes(&self) -> Result<Vec<Node>>;\n    pub async fn node_count(&self) -> usize;\n    pub async fn is_leader(&self) -> bool;\n\n    // Sharding\n    pub fn get_shard_for_key(&self, key: &str) -> Result<ShardId>;\n    pub async fn get_shard_nodes(&self, shard: ShardId) -> Result<Vec<Node>>;\n    pub async fn migrate_shard(&self, shard: ShardId, target: &NodeId) -> Result<()>;\n\n    // Health\n    pub async fn health(&self) -> Result<ClusterHealth>;\n    pub async fn rebalance(&self) -> Result<()>;\n}\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        Cluster                               │\n│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │\n│  │ Node 1  │  │ Node 2  │  │ Node 3  │  │ Node 4  │        │\n│  │ Shards: │  │ Shards: │  │ Shards: │  │ Shards: │        │\n│  │ 0,4,8   │  │ 1,5,9   │  │ 2,6,10  │  │ 3,7,11  │        │\n│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │\n│       │            │            │            │              │\n│       └────────────┴────────────┴────────────┘              │\n│                    Gossip Protocol                          │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Related Crates\n\n- **[ruvector-core](../ruvector-core/)** - Core vector database engine\n- **[ruvector-raft](../ruvector-raft/)** - RAFT consensus\n- **[ruvector-replication](../ruvector-replication/)** - Data replication\n\n## Documentation\n\n- **[Main README](../../README.md)** - Complete project overview\n- **[API Documentation](https://docs.rs/ruvector-cluster)** - Full API reference\n- **[GitHub Repository](https://github.com/ruvnet/ruvector)** - Source code\n\n## License\n\n**MIT License** - see [LICENSE](../../LICENSE) for details.\n\n---\n\n<div align=\"center\">\n\n**Part of [Ruvector](https://github.com/ruvnet/ruvector) - Built by [rUv](https://ruv.io)**\n\n[![Star on GitHub](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)\n\n[Documentation](https://docs.rs/ruvector-cluster) | [Crates.io](https://crates.io/crates/ruvector-cluster) | [GitHub](https://github.com/ruvnet/ruvector)\n\n</div>\n","readmeFilename":"README.md"}