hero_redis 0.2.0

# Hero Redis

A high-performance, Redis-compatible server built on [redb](https://github.com/cberner/redb) with ChaCha20-Poly1305 encryption and dual authentication modes.

## Features

- **Redis Protocol Compatible** - Works with any Redis client including Redis Desktop Manager
- **Dual Authentication**:
  - **Simple**: Secret-based auth with `AUTH <secret>` (recommended for most users)
  - **Advanced**: Ed25519 signature-based auth (for high-security environments)
- **Multi-Database with ACL** - Per-database Read/Write/Admin permissions
- **Persistent Storage** - Data stored in redb (pure Rust embedded database)
- **Encryption** - All values encrypted with ChaCha20-Poly1305
- **Multiple Databases** - Up to 1000 databases with lazy loading
- **Low Memory** - ~3MB at startup, databases loaded on demand
- **Auto-cleanup** - Idle databases automatically closed after 5 minutes
- **Unix Socket & TCP** - Both connection methods supported
- **Vector Search** - HNSW-based similarity search with hannoy library
- **Cross-platform** - Linux (x86_64, aarch64) and macOS (x86_64, aarch64)

## Quick Start

### Build from Source

```bash
git clone https://github.com/herocode/hero_redis.git
cd hero_redis
cargo build --release
```

### Start Server (Simple Auth)

```bash
# Start with admin secret (simplest way)
./target/release/hero_redis \
  --encryption-key "your-encryption-key" \
  --admin-secret "your-admin-secret" \
  --data-dir ~/.hero_redis
```

### Connect and Use

```bash
# Using redis-cli (default port is 6666)
redis-cli -p 6666

# Authenticate with your secret
> AUTH your-admin-secret
OK

# Now use any Redis command
> SET mykey myvalue
OK
> GET mykey
"myvalue"
```

### Using with Redis Desktop Manager

1. Start server with `--admin-secret`
2. In Redis Desktop Manager, configure connection:
   - Host: 127.0.0.1
   - Port: 6666
   - Auth: your-admin-secret
3. Connect and use normally

## Authentication Modes

### 1. Simple Auth (Recommended)

Start the server with `--admin-secret`:

```bash
./target/release/hero_redis \
  --encryption-key "encryption-key" \
  --admin-secret "my-secret-password"
```

Connect with `AUTH`:
```
AUTH my-secret-password
```

Create users with secrets:
```
USER.CREATESECRET alice alice-secret-123
USER.GRANT 1 alice write
```

Users authenticate with:
```
AUTH alice-secret-123
```

### 2. Advanced Auth (Ed25519)

For high-security environments, use Ed25519 signature-based authentication:

```bash
# Generate keypair
./target/release/hero_redis_login --generate

# Start server with pubkey
./target/release/hero_redis \
  --encryption-key "encryption-key" \
  --admin-pubkey "a1b2c3d4..."
```

Authentication flow:
```
CHALLENGE          → returns random challenge
TOKEN <pubkey> <signature>  → returns session token
AUTH <token>       → authenticates session
```

## Command Line Options

### Server (hero_redis)

| Option | Default | Description |
|--------|---------|-------------|
| `-d, --data-dir` | `~/.hero_redis` | Database directory |
| `-s, --socket` | `~/.hero_redis/redis.sock` | Unix socket path |
| `-p, --port` | `6666` | TCP port (0 to disable) |
| `--encryption-key` | *required* | Encryption key for DB 0 |
| `--admin-secret` | - | Admin secret for simple auth |
| `--admin-pubkey` | - | Admin public key for Ed25519 auth |
| `-v, --verbose` | false | Enable debug logging |

Note: At least one of `--admin-secret` or `--admin-pubkey` must be provided.

## User Management

### Create Users (Secret-based)

```
# As admin, create a user with a secret
USER.CREATESECRET <username> <secret>

# Example
USER.CREATESECRET alice mysecretpassword
```

### Create Users (Ed25519-based)

```
# As admin, register a user's public key
USER.CREATE <pubkey>

# Example
USER.CREATE a1b2c3d4e5f6...
```

### Grant Permissions

```
# Grant access to a database
USER.GRANT <db_number> <username_or_pubkey> <read|write|admin>

# Examples
USER.GRANT 1 alice write
USER.GRANT 2 bob read
USER.GRANT 1 a1b2c3d4e5f6... admin
```

### Revoke Permissions

```
USER.REVOKE <db_number> <username_or_pubkey>

# Example
USER.REVOKE 1 alice
```

## Permission Levels

| Level | Can Read | Can Write | Can FLUSHDB | Can USER.GRANT | Can DATABASE.CREATE |
|-------|----------|-----------|-------------|----------------|---------------------|
| **read** | Yes | No | No | No | No |
| **write** | Yes | Yes | No | No | No |
| **admin** | Yes | Yes | Yes | Yes (same db) | No |
| **server admin** | Yes | Yes | Yes | Yes | Yes |

## Admin Commands

### Server Admin Commands

| Command | Description |
|---------|-------------|
| `DATABASE.CREATE <encryption_key>` | Create new database, returns db number |
| `DATABASE.STATUS [db\|all]` | Show database info |
| `DATABASE.PUBLIC <db> <on\|off>` | Enable/disable public read-only access |
| `USER.CREATE <pubkey>` | Register Ed25519 user |
| `USER.CREATESECRET <username> <secret>` | Create secret-based user |
| `USER.DELETE <username_or_pubkey>` | Delete a user |
| `ADMIN.ADD <pubkey>` | Add server admin (Ed25519) |
| `ADMIN.REMOVE <pubkey>` | Remove server admin |
| `ADMIN.LIST` | List server admins |

### Public Read-Only Access

You can make a database publicly readable (no authentication required for reads):

```bash
# As admin, make database 1 public
DATABASE.PUBLIC 1 on

# Now anyone can read without AUTH
SELECT 1
GET publickey    # Works without authentication
SET key value    # Fails - writes still require auth
```

### Database Admin Commands

| Command | Description |
|---------|-------------|
| `USER.GRANT <db> <user> <perm>` | Grant permission (read/write/admin) |
| `USER.REVOKE <db> <user>` | Revoke permission |
| `FLUSHDB` | Clear current database |

## Supported Redis Commands

### Authentication
`AUTH`, `SAUTH`, `CHALLENGE`, `TOKEN`

### String Commands
`GET`, `SET`, `MGET`, `MSET`, `DEL`, `EXISTS`, `EXPIRE`, `TTL`, `KEYS`, `SCAN`, `INCR`, `INCRBY`, `DECR`, `DECRBY`, `APPEND`, `STRLEN`, `GETRANGE`, `SETNX`, `SETEX`, `GETSET`, `TYPE`

### Hash Commands
`HSET`, `HGET`, `HMSET`, `HMGET`, `HGETALL`, `HDEL`, `HEXISTS`, `HLEN`, `HKEYS`, `HVALS`, `HINCRBY`, `HSETNX`, `HSCAN`

### List Commands
`LPUSH`, `RPUSH`, `LPOP`, `RPOP`, `LRANGE`, `LLEN`, `LINDEX`, `LSET`, `LREM`

### Set Commands
`SADD`, `SREM`, `SMEMBERS`, `SISMEMBER`, `SCARD`, `SPOP`, `SUNION`, `SINTER`, `SDIFF`, `SSCAN`

### Stream Commands
`XADD`, `XLEN`, `XRANGE`, `XREVRANGE`, `XREAD`, `XINFO`, `XTRIM`, `XGROUP`, `XREADGROUP`, `XACK`, `XPENDING`

### Vector Commands
`VECTOR.CREATE`, `VECTOR.ADD`, `VECTOR.SEARCH`, `VECTOR.SEARCHBYID`, `VECTOR.GET`, `VECTOR.DEL`, `VECTOR.BUILD`, `VECTOR.INFO`, `VECTOR.LIST`, `VECTOR.DROP`, `VECTOR.CLEAR`, `VECTOR.EXISTS`, `VECTOR.LEN`

### Connection Commands
`PING`, `AUTH`, `SAUTH`, `SELECT`, `QUIT`, `COMMAND`

### Management Commands
`COMPACT`, `SHUTDOWN`, `MEMORY USAGE`, `MEMORY STATS`, `DBSIZE`, `FLUSHDB`, `INFO`, `CONFIG`, `CLIENT`

## Vector Search

Hero Redis includes HNSW-based vector similarity search:

```bash
# Create a vector index (128 dimensions, cosine similarity)
VECTOR.CREATE myindex 128 cosine

# Add vectors
VECTOR.ADD myindex 1 0.1 0.2 0.3 ...
VECTOR.ADD myindex 2 0.4 0.5 0.6 ...

# Build the index
VECTOR.BUILD myindex

# Search for similar vectors (returns top 10)
VECTOR.SEARCH myindex 10 0.1 0.2 0.3 ...

# Search by existing vector ID
VECTOR.SEARCHBYID myindex 1 10
```

## Using as a Library

```rust
use hero_redis::hero_redis_client::HeroRedisClient;

// Connect with your private key
let mut client = HeroRedisClient::new("127.0.0.1", 6379, "your_private_key_hex")?;
client.select(1)?;

// String operations
client.set("name", "Alice")?;
let name = client.get("name")?.unwrap();

// Hashes
client.hset("user:1", "name", "Bob")?;
let user = client.hgetall("user:1")?;

// Lists
client.rpush("queue", "job1")?;
let job = client.lpop("queue")?;

// Sets
client.sadd("tags", "rust")?;
let tags = client.smembers("tags")?;
```

## Data Storage

- Data directory: `~/.hero_redis/` (configurable)
- Database files: `db0.redb`, `db1.redb`, ... `db999.redb`
- DB 0 is reserved for admin metadata
- Each database has its own encryption key
- Values are encrypted with ChaCha20-Poly1305

## License

Apache 2.0