# RookKV

RookKV is a distributed key-value store designed for small to medium-scale services that need predictable latency, replication, and operational simplicity. It uses a Raft-based consensus layer for metadata and shard ownership, with log-structured storage on each node.

RookKV is intended for service configuration, feature flags, queues, session state, and other workloads where strong consistency and simple deployment matter more than complex query support.

## Features

- Strongly consistent reads and writes using Raft-backed replication
- Automatic shard rebalancing when nodes join or leave
- Persistent log-structured storage with periodic compaction
- Optional TTL support for expiring keys
- Namespaces for isolating application data
- HTTP and gRPC APIs
- Built-in health, metrics, and readiness endpoints
- Snapshot and restore support
- TLS and token-based node authentication

## Install

### Binary

Download the latest release for your platform:

```bash
curl -L https://github.com/example/rookkv/releases/latest/download/rookkv-linux-amd64 \
  -o rookkv

chmod +x rookkv
sudo mv rookkv /usr/local/bin/
```

Verify the installation:

```bash
rookkv --version
```

### Docker

```bash
docker pull ghcr.io/example/rookkv:latest
```

## Usage

### Start a Single Node

```bash
rookkv server \
  --node-id node-1 \
  --data-dir ./data/node-1 \
  --listen-client 127.0.0.1:7379 \
  --listen-peer 127.0.0.1:7380
```

### Put a Key

```bash
curl -X PUT http://127.0.0.1:7379/v1/kv/default/app/theme \
  -H "Content-Type: application/json" \
  -d '{"value":"dark"}'
```

### Get a Key

```bash
curl http://127.0.0.1:7379/v1/kv/default/app/theme
```

Example response:

```json
{
  "key": "app/theme",
  "namespace": "default",
  "value": "dark",
  "revision": 42,
  "expires_at": null
}
```

### Delete a Key

```bash
curl -X DELETE http://127.0.0.1:7379/v1/kv/default/app/theme
```

### Start a Three-Node Cluster

Node 1:

```bash
rookkv server --config ./config/node-1.yaml
```

Node 2:

```bash
rookkv server --config ./config/node-2.yaml
```

Node 3:

```bash
rookkv server --config ./config/node-3.yaml
```

Bootstrap the cluster:

```bash
rookkv cluster init \
  --endpoint http://127.0.0.1:7379 \
  --members node-1=http://127.0.0.1:7380,node-2=http://127.0.0.1:7480,node-3=http://127.0.0.1:7580
```

Check cluster status:

```bash
rookkv cluster status --endpoint http://127.0.0.1:7379
```

## Configuration

RookKV can be configured using command-line flags, environment variables, or a YAML configuration file.

Example `config/node-1.yaml`:

```yaml
node:
  id: node-1
  data_dir: /var/lib/rookkv/node-1

network:
  client_addr: 0.0.0.0:7379
  peer_addr: 10.0.1.10:7380
  advertise_client_addr: http://10.0.1.10:7379
  advertise_peer_addr: http://10.0.1.10:7380

cluster:
  name: production
  replication_factor: 3
  shard_count: 128
  election_timeout_ms: 1500
  heartbeat_interval_ms: 250

storage:
  engine: lsm
  max_log_segment_mb: 128
  compaction_interval: 10m
  snapshot_interval: 30m

api:
  enable_http: true
  enable_grpc: true
  max_request_bytes: 1048576

security:
  tls_enabled: true
  cert_file: /etc/rookkv/tls/server.crt
  key_file: /etc/rookkv/tls/server.key
  ca_file: /etc/rookkv/tls/ca.crt
  auth_token_file: /etc/rookkv/token

observability:
  metrics_addr: 0.0.0.0:9090
  log_level: info
```

### Common Options

| Option | Description | Default |
| --- | --- | --- |
| `node.id` | Unique node identifier | Required |
| `node.data_dir` | Directory for logs, snapshots, and local data | `./data` |
| `network.client_addr` | Address for client traffic | `127.0.0.1:7379` |
| `network.peer_addr` | Address for node-to-node replication | `127.0.0.1:7380` |
| `cluster.replication_factor` | Number of replicas per shard | `3` |
| `cluster.shard_count` | Number of logical shards | `64` |
| `storage.compaction_interval` | Background compaction frequency | `10m` |
| `api.max_request_bytes` | Maximum size of a single API request | `1048576` |
| `observability.metrics_addr` | Prometheus metrics bind address | `127.0.0.1:9090` |
| `observability.log_level` | Log verbosity | `info` |

### Environment Variables

All configuration values can be provided with the `ROOKKV_` prefix:

```bash
export ROOKKV_NODE_ID=node-1
export ROOKKV_NODE_DATA_DIR=/var/lib/rookkv/node-1
export ROOKKV_NETWORK_CLIENT_ADDR=0.0.0.0:7379
export ROOKKV_OBSERVABILITY_LOG_LEVEL=debug
```

## Operations

### Health Check

```bash
curl http://127.0.0.1:7379/healthz
```

### Metrics

```bash
curl http://127.0.0.1:9090/metrics
```

### Snapshot

```bash
rookkv snapshot save \
  --endpoint http://127.0.0.1:7379 \
  --output ./rookkv.snapshot
```

### Restore

```bash
rookkv snapshot restore \
  --input ./rookkv.snapshot \
  --data-dir /var/lib/rookkv/restore
```

## License

Apache-2.0