# ExRingRing

A consistent hash ring implementation in Elixir with Clean Architecture.

> ⚠️ **EXPERIMENTAL / UNDER ACTIVE DEVELOPMENT** ⚠️
>
> It is currently in early development and **NOT READY FOR PRODUCTION USE**.

## Features

- Consistent hashing for distributed systems
- Virtual nodes for balanced key distribution
- Node weights for weighted distribution
- Phantom nodes (weight 0) for standby members
- Multiple hash algorithms: MD5, SHA, SHA256, CRC32, phash2
- Two implementation strategies: Static (fast reads) and Dynamic (fast writes)
- Minimal redistribution when nodes join or leave

## Installation

```elixir
def deps do
  [
    {:ex_ring_ring, "~> 0.1.0"}
  ]
end
```

## Quick Start

```elixir
# Create nodes and a ring
nodes = ExRingRing.list_to_nodes([:a, :b, :c, :d, :e])
ring = ExRingRing.make(nodes)

# Find which node owns an item
{:ok, node} = ExRingRing.find_node(ring, "my_key")
node.key  # => :a (deterministic)

# Collect N nodes for replication
nodes = ExRingRing.collect_nodes(ring, "my_key", 3)

# Add and remove nodes at runtime
ring = ExRingRing.add_node(ring, ExRingRing.Domain.Entities.Node.make(:f))
ring = ExRingRing.remove_node(ring, :c)
```

## Guides

- [Getting Started](guides/getting_started.md) — Installation, basic usage, examples
- [Architecture](guides/architecture.md) — Clean Architecture layers, module design
- [Configuration](guides/configuration.md) — Hash algorithms, virtual nodes, weights
- [Implementation Strategies](guides/implementation_strategies.md) — Static vs Dynamic trade-offs

## License

Apache License 2.0