oxirs-cluster 0.2.2

Raft-backed distributed dataset for high availability and horizontal scaling
Documentation

OxiRS Cluster

Version Rust License

Status: v0.2.2 - Released March 16, 2026

✨ Production Release: Production-ready with API stability guarantees and comprehensive testing.

A high-performance, distributed RDF storage system using Raft consensus for horizontal scaling and fault tolerance. Part of the OxiRS ecosystem providing a JVM-free alternative to Apache Jena + Fuseki with enhanced clustering capabilities.

Features

  • Raft Consensus: Strong consistency with automated leader election and log replication
  • Horizontal Scaling: Linear performance scaling to 1000+ nodes
  • High Availability: 99.9% uptime with automatic failover
  • Distributed RDF Storage: Efficient partitioning and indexing of RDF triples
  • SPARQL 1.2 Support: Distributed query processing with federated queries
  • Enterprise Security: TLS encryption, authentication, and access control
  • Operational Excellence: Comprehensive monitoring, alerting, and management tools

Architecture

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   Node A        │  │   Node B        │  │   Node C        │
│   (Leader)      │  │   (Follower)    │  │   (Follower)    │
├─────────────────┤  ├─────────────────┤  ├─────────────────┤
│ Raft Consensus  │◄─┤ Raft Consensus  │◄─┤ Raft Consensus  │
│ RDF Storage     │  │ RDF Storage     │  │ RDF Storage     │
│ Query Engine    │  │ Query Engine    │  │ Query Engine    │
│ Network Layer   │  │ Network Layer   │  │ Network Layer   │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Core Components

  • Consensus Layer: Raft-based distributed consensus for strong consistency
  • Storage Layer: Distributed RDF triple storage with efficient indexing
  • Network Layer: High-performance inter-node communication
  • Discovery Service: Automatic node registration and cluster membership
  • Query Engine: Distributed SPARQL query processing
  • Replication: Multi-master replication with conflict resolution

Quick Start

Prerequisites

  • Rust 1.70+ (MSRV)
  • Memory: 4GB+ recommended
  • Network: Low-latency connection between nodes

Installation

Add to your Cargo.toml:

# Experimental feature
[dependencies]
oxirs-cluster = "0.2.2"

Basic Usage

use oxirs_cluster::{Cluster, ClusterConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize cluster configuration
    let config = ClusterConfig::builder()
        .node_id("node-1")
        .bind_address("127.0.0.1:8080")
        .peers(vec!["127.0.0.1:8081", "127.0.0.1:8082"])
        .data_dir("./data")
        .build()?;

    // Start cluster node
    let cluster = Cluster::new(config).await?;
    cluster.start().await?;

    // Insert RDF data
    cluster.insert_triple("http://example.org/alice", 
                         "http://example.org/knows", 
                         "http://example.org/bob").await?;

    // Execute SPARQL query
    let results = cluster.query("SELECT ?s ?p ?o WHERE { ?s ?p ?o }").await?;
    println!("Results: {:?}", results);

    Ok(())
}

Multi-Node Cluster Setup

# Start first node (bootstrap)
cargo run --bin oxirs-cluster -- \
    --node-id node-1 \
    --bind 127.0.0.1:8080 \
    --data-dir ./data/node1 \
    --bootstrap

# Start second node
cargo run --bin oxirs-cluster -- \
    --node-id node-2 \
    --bind 127.0.0.1:8081 \
    --data-dir ./data/node2 \
    --join 127.0.0.1:8080

# Start third node
cargo run --bin oxirs-cluster -- \
    --node-id node-3 \
    --bind 127.0.0.1:8082 \
    --data-dir ./data/node3 \
    --join 127.0.0.1:8080

Configuration

Environment Variables

OXIRS_CLUSTER_NODE_ID=node-1
OXIRS_CLUSTER_BIND_ADDR=0.0.0.0:8080
OXIRS_CLUSTER_DATA_DIR=/var/lib/oxirs
OXIRS_CLUSTER_LOG_LEVEL=info
OXIRS_CLUSTER_HEARTBEAT_INTERVAL=150ms
OXIRS_CLUSTER_ELECTION_TIMEOUT=1500ms

Configuration File (oxirs-cluster.toml)

[cluster]
node_id = "node-1"
bind_address = "0.0.0.0:8080"
data_dir = "/var/lib/oxirs"

[raft]
heartbeat_interval = "150ms"
election_timeout = "1500ms"
max_log_entries = 10000
snapshot_threshold = 5000

[storage]
partition_count = 16
replication_factor = 3
compression = "lz4"

[network]
max_connections = 1000
connection_timeout = "30s"
message_timeout = "5s"

Performance

Benchmarks

  • Throughput: 10,000+ operations/second per cluster
  • Latency: <100ms for read queries, <200ms for writes
  • Scalability: Linear performance to 1000+ nodes
  • Recovery: <30 seconds for automatic failover

Tuning

let config = ClusterConfig::builder()
    .node_id("node-1")
    .heartbeat_interval(Duration::from_millis(150))
    .election_timeout(Duration::from_millis(1500))
    .max_log_entries(10000)
    .snapshot_threshold(5000)
    .build()?;

Monitoring

Metrics

The cluster exposes Prometheus-compatible metrics:

  • oxirs_cluster_nodes_total: Total number of cluster nodes
  • oxirs_cluster_leader_changes_total: Number of leader changes
  • oxirs_cluster_queries_total: Total queries processed
  • oxirs_cluster_query_duration_seconds: Query latency histogram
  • oxirs_cluster_replication_lag_seconds: Replication lag

Health Checks

# Check cluster health
curl http://localhost:8080/health

# Check node status
curl http://localhost:8080/status

# Get cluster metrics
curl http://localhost:8080/metrics

Development

Building

# Build with all features
cargo build --all-features

# Run tests
cargo nextest run --no-fail-fast

# Run benchmarks
cargo bench

Testing

# Unit tests
cargo test

# Integration tests
cargo test --test integration

# Chaos engineering tests
cargo test --test chaos

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for your changes
  5. Ensure all tests pass (cargo nextest run --no-fail-fast)
  6. Run clippy (cargo clippy --workspace --all-targets -- -D warnings)
  7. Format your code (cargo fmt --all)
  8. Commit your changes (git commit -am 'Add amazing feature')
  9. Push to the branch (git push origin feature/amazing-feature)
  10. Open a Pull Request

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Acknowledgments

Roadmap

Version 0.1.0

  • Multi-region deployment support
  • Advanced conflict resolution
  • Improved monitoring dashboard
  • Performance optimizations
  • Machine learning-based query optimization
  • Edge computing integration
  • Advanced security features
  • GraphQL federation support

For more information, see the OxiRS documentation and TODO.md for detailed implementation progress.