Counter SMR Example

This example demonstrates how to build a simple distributed counter using State Machine Replication (SMR) with the Rabia consensus protocol.

What This Example Shows

The Counter SMR demonstrates the fundamental SMR concepts:

1. Deterministic State Machine: All operations on the counter produce predictable, reproducible results
2. Operation Ordering: Rabia ensures all replicas apply increment/decrement operations in the same order
3. Fault Tolerance: The counter remains available as long as a majority of replicas are healthy
4. Strong Consistency: All replicas maintain identical counter values

State Machine Implementation

The counter implements these operations:

• Increment(value) - Add a value to the counter
• Decrement(value) - Subtract a value from the counter
• Set(value) - Set counter to a specific value
• Get - Read the current counter value
• Reset - Reset counter to zero

All operations include overflow/underflow protection and operation counting.

Key SMR Features Demonstrated

Deterministic Operations

match command {
    CounterCommand::Increment(value) => {
        // Deterministic: same input always produces same output
        match self.state.value.checked_add(value) {
            Some(new_value) => {
                self.state.value = new_value;
                CounterResponse::success(self.state.value)
            }
            None => CounterResponse::error(
                self.state.value,
                "Overflow: cannot increment counter".to_string(),
            ),
        }
    }
    // ... other operations
}

State Serialization for Snapshots

fn serialize_state(&self) -> Vec<u8> {
    bincode::serialize(&self.state).unwrap_or_default()
}

fn deserialize_state(&mut self, data: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    self.state = bincode::deserialize(data)?;
    Ok(())
}

Error Handling

The counter demonstrates proper error handling for edge cases like integer overflow/underflow, ensuring the state machine never panics or produces undefined behavior.

Running the Example

# Run the counter SMR example
cargo run --bin counter_smr_example

# Run tests to see SMR behavior
cargo test -p counter_smr

# Run with multiple replicas (if implemented)
cargo run --bin counter_smr_cluster

Use Cases

This pattern is useful for:

• Distributed Counters: Website hit counters, API rate limiting
• Resource Allocation: Database connection pools, queue sizes
• Metrics Collection: Aggregating statistics across services
• Game Scores: Leaderboards, player statistics

Extending This Example

You can extend the counter SMR to demonstrate more advanced SMR concepts:

1. Batch Operations: Apply multiple increments/decrements atomically
2. Conditional Operations: Increment only if value is below threshold
3. Named Counters: Maintain multiple named counters in one state machine
4. Time-based Operations: Add timestamps to track operation history

Implementation Notes

Why This Works Well for SMR

1. Small State: The counter state is minimal (just an integer), making snapshots efficient
2. Fast Operations: Arithmetic operations are fast and deterministic
3. No External Dependencies: Operations don't depend on external systems or current time
4. Easy to Test: Simple operations make it easy to verify correctness

Performance Characteristics

• Memory Usage: Minimal (single integer + operation counter)
• Operation Latency: Very low (simple arithmetic)
• Throughput: High (operations can be batched efficiently)
• Snapshot Size: Tiny (serialized integer)

This makes the counter an ideal first example for learning SMR concepts with Rabia.

Next Steps

After understanding the counter example, explore:

• Key-Value Store SMR - More complex state with multiple operations
• Banking SMR - Business logic with validation and transactions
• Custom State Machine - Template for your own SMR applications