Fix test suite + update Cargo.toml file

Reviewed-on: #2

README.md

@@ -0,0 +1,83 @@
+# HeroDB
+
+Redis-compatible database server with encryption and AGE cryptographic operations.
+
+## Features
+
+- Redis protocol compatibility
+- String, hash, and list data types
+- Key expiration and persistence
+- Database encryption with ChaCha20-Poly1305
+- AGE encryption/decryption operations
+- Digital signatures with Ed25519
+- Persistent storage using redb
+
+## Installation
+
+```bash
+cargo build --release
+```
+
+## Usage
+
+```bash
+./target/release/herodb --dir /path/to/db --port 6379
+```
+
+### Options
+
+- `--dir`: Database directory (required)
+- `--port`: Server port (default: 6379)
+- `--debug`: Enable debug logging
+- `--encrypt`: Enable database encryption
+- `--encryption-key`: Master encryption key for encrypted databases
+
+### Examples
+
+```bash
+# Basic server
+herodb --dir ./data
+
+# Encrypted database
+herodb --dir ./data --encrypt --encryption-key "your-key"
+
+# Custom port with debug
+herodb --dir ./data --port 7000 --debug
+```
+
+## Redis Commands
+
+Supports standard Redis commands including:
+
+- **Strings**: GET, SET, MGET, MSET, INCR, DEL
+- **Hashes**: HGET, HSET, HGETALL, HDEL, HEXISTS
+- **Lists**: LPUSH, RPUSH, LPOP, RPOP, LLEN, LRANGE
+- **Keys**: KEYS, SCAN, EXISTS, EXPIRE, TTL
+- **Transactions**: MULTI, EXEC, DISCARD
+- **Server**: PING, ECHO, INFO, CONFIG
+
+## AGE Commands
+
+Extended commands for cryptographic operations:
+
+- **Key Generation**: `AGE GENENC`, `AGE GENSIGN`, `AGE KEYGEN`
+- **Encryption**: `AGE ENCRYPT`, `AGE DECRYPT`, `AGE ENCRYPTNAME`
+- **Signing**: `AGE SIGN`, `AGE VERIFY`, `AGE SIGNNAME`
+- **Management**: `AGE LIST`
+
+## Client Usage
+
+Connect using any Redis client:
+
+```bash
+redis-cli -p 6379 SET key value
+redis-cli -p 6379 GET key
+redis-cli -p 6379 AGE GENENC
+```
+
+## Architecture
+
+- **Storage**: redb embedded database
+- **Protocol**: Redis RESP protocol over TCP
+- **Encryption**: ChaCha20-Poly1305 for data, AGE for operations
+- **Concurrency**: Tokio async runtime

herodb/Cargo.toml

@@ -1,8 +1,8 @@
 [package]
 name = "herodb"
 version = "0.0.1"
-authors = ["Pin Fang <fpfangpin@hotmail.com>"]
-edition = "2021"
+authors = ["ThreeFold Tech"]
+edition = "2024"
 
 [dependencies]
 anyhow = "1.0.59"

herodb/docs/age.md

@@ -16,33 +16,40 @@ Note: Database-at-rest encryption flags in the test harness are unrelated to AGE
 
 ## Quick start
 
-Assuming the server is running on localhost on some PORT:
+Assuming the server is running on localhost on some $PORT:
+```bash
+~/code/git.ourworld.tf/herocode/herodb/herodb/build.sh
+~/code/git.ourworld.tf/herocode/herodb/target/release/herodb --dir /tmp/data --debug --$PORT 6381 --encryption-key 1234 --encrypt
+```
+
 
 ```bash
+export PORT=6381
 # Generate an ephemeral keypair and encrypt/decrypt a message (stateless mode)
-redis-cli -p PORT AGE GENENC
+redis-cli -p $PORT AGE GENENC
 # → returns an array: [recipient, identity]
 
-redis-cli -p PORT AGE ENCRYPT <recipient> "hello world"
+redis-cli -p $PORT AGE ENCRYPT <recipient> "hello world"
 # → returns ciphertext (base64 in a bulk string)
 
-redis-cli -p PORT AGE DECRYPT <identity> <ciphertext_b64>
+redis-cli -p $PORT AGE DECRYPT <identity> <ciphertext_b64>
 # → returns "hello world"
 ```
 
 For key‑managed mode, generate a named key once and reference it by name afterwards:
 
 ```bash
-redis-cli -p PORT AGE KEYGEN app1
+redis-cli -p $PORT AGE KEYGEN app1
 # → persists encryption keypair under name "app1"
 
-redis-cli -p PORT AGE ENCRYPTNAME app1 "hello"
-redis-cli -p PORT AGE DECRYPTNAME app1 <ciphertext_b64>
+redis-cli -p $PORT AGE ENCRYPTNAME app1 "hello"
+redis-cli -p $PORT AGE DECRYPTNAME app1 <ciphertext_b64>
 ```
 
 ## Stateless AGE (ephemeral)
 
 Characteristics
+
 - No server‑side storage of keys.
 - You pass the actual key material with every call.
 - Not listable via AGE LIST.
@@ -52,36 +59,40 @@ Commands and examples
 1) Ephemeral encryption keys
 
 ```bash
-# Generate an ephemeral encryption keypair
-redis-cli -p PORT AGE GENENC
+# Generate an ephemeral encryption keypair 
+redis-cli -p $PORT AGE GENENC
 # Example output (abridged):
-# 1) "age1qz..."          # recipient (public)
-# 2) "AGE-SECRET-KEY-1..." # identity (secret)
+# 1) "age1qz..."          # recipient (public key) = can be used by others e.g. to verify what I sign
+# 2) "AGE-SECRET-KEY-1..." # identity (secret) = is like my private, cannot lose this one
 
-# Encrypt with the recipient
-redis-cli -p PORT AGE ENCRYPT "age1qz..." "hello world"
-# → returns bulk string payload: base64 ciphertext
+# Encrypt with the recipient public key
+redis-cli -p $PORT AGE ENCRYPT "age1qz..." "hello world"
 
-# Decrypt with the identity (secret)
-redis-cli -p PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
+# → returns bulk string payload: base64 ciphertext (encrypted content)
+
+# Decrypt with the identity (secret) in other words your private key
+redis-cli -p $PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
 # → "hello world"
 ```
 
 2) Ephemeral signing keys
 
+> ? is this same as my private key
+
 ```bash
+
 # Generate an ephemeral signing keypair
-redis-cli -p PORT AGE GENSIGN
+redis-cli -p $PORT AGE GENSIGN
 # Example output:
 # 1) "<verify_pub_b64>"
 # 2) "<sign_secret_b64>"
 
 # Sign a message with the secret
-redis-cli -p PORT AGE SIGN "<sign_secret_b64>" "msg"
+redis-cli -p $PORT AGE SIGN "<sign_secret_b64>" "msg"
 # → returns "<signature_b64>"
 
 # Verify with the public key
-redis-cli -p PORT AGE VERIFY "<verify_pub_b64>" "msg" "<signature_b64>"
+redis-cli -p $PORT AGE VERIFY "<verify_pub_b64>" "msg" "<signature_b64>"
 # → 1 (valid) or 0 (invalid)
 ```
 
@@ -105,15 +116,17 @@ Commands and examples
 
 ```bash
 # Create/persist a named encryption keypair
-redis-cli -p PORT AGE KEYGEN app1
+redis-cli -p $PORT AGE KEYGEN app1
 # → returns [recipient, identity] but also stores them under name "app1"
 
+> TODO: should not return identity (security, but there can be separate function to export it e.g. AGE EXPORTKEY app1)
+
 # Encrypt using the stored public key
-redis-cli -p PORT AGE ENCRYPTNAME app1 "hello"
+redis-cli -p $PORT AGE ENCRYPTNAME app1 "hello"
 # → returns bulk string payload: base64 ciphertext
 
 # Decrypt using the stored secret
-redis-cli -p PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
+redis-cli -p $PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
 # → "hello"
 ```
 
@@ -121,22 +134,24 @@ redis-cli -p PORT AGE DECRYPTNAME app1 "<ciphertext_b64>"
 
 ```bash
 # Create/persist a named signing keypair
-redis-cli -p PORT AGE SIGNKEYGEN app1
+redis-cli -p $PORT AGE SIGNKEYGEN app1
 # → returns [verify_pub_b64, sign_secret_b64] and stores under name "app1"
 
+> TODO: should not return sign_secret_b64 (for security, but there can be separate function to export it e.g. AGE EXPORTSIGNKEY app1)
+
 # Sign using the stored secret
-redis-cli -p PORT AGE SIGNNAME app1 "msg"
+redis-cli -p $PORT AGE SIGNNAME app1 "msg"
 # → returns "<signature_b64>"
 
 # Verify using the stored public key
-redis-cli -p PORT AGE VERIFYNAME app1 "msg" "<signature_b64>"
+redis-cli -p $PORT AGE VERIFYNAME app1 "msg" "<signature_b64>"
 # → 1 (valid) or 0 (invalid)
 ```
 
 3) List stored AGE keys
 
 ```bash
-redis-cli -p PORT AGE LIST
+redis-cli -p $PORT AGE LIST
 # Example output includes labels such as "encpub" and your key names (e.g., "app1")
 ```
 

herodb/docs/basics.md

@@ -0,0 +1,623 @@
+Here's an expanded version of the cmds.md documentation to include the list commands:
+# HeroDB Commands
+
+HeroDB implements a subset of Redis commands over the Redis protocol. This document describes the available commands and their usage.
+
+## String Commands
+
+### PING
+Ping the server to test connectivity.
+```bash
+redis-cli -p $PORT PING
+# → PONG
+```
+
+### ECHO
+Echo the given message.
+```bash
+redis-cli -p $PORT ECHO "hello"
+# → hello
+```
+
+### SET
+Set a key to hold a string value.
+```bash
+redis-cli -p $PORT SET key value
+# → OK
+```
+
+Options:
+- EX seconds: Set expiration in seconds
+- PX milliseconds: Set expiration in milliseconds
+- NX: Only set if key doesn't exist
+- XX: Only set if key exists
+- GET: Return old value
+
+Examples:
+```bash
+redis-cli -p $PORT SET key value EX 60
+redis-cli -p $PORT SET key value PX 1000
+redis-cli -p $PORT SET key value NX
+redis-cli -p $PORT SET key value XX
+redis-cli -p $PORT SET key value GET
+```
+
+### GET
+Get the value of a key.
+```bash
+redis-cli -p $PORT GET key
+# → value
+```
+
+### MGET
+Get values of multiple keys.
+```bash
+redis-cli -p $PORT MGET key1 key2 key3
+# → 1) "value1"
+#    2) "value2"
+#    3) (nil)
+```
+
+### MSET
+Set multiple key-value pairs.
+```bash
+redis-cli -p $PORT MSET key1 value1 key2 value2
+# → OK
+```
+
+### INCR
+Increment the integer value of a key by 1.
+```bash
+redis-cli -p $PORT SET counter 10
+redis-cli -p $PORT INCR counter
+# → 11
+```
+
+### DEL
+Delete a key.
+```bash
+redis-cli -p $PORT DEL key
+# → 1
+```
+
+For multiple keys:
+```bash
+redis-cli -p $PORT DEL key1 key2 key3
+# → number of keys deleted
+```
+
+### TYPE
+Determine the type of a key.
+```bash
+redis-cli -p $PORT TYPE key
+# → string
+```
+
+### EXISTS
+Check if a key exists.
+```bash
+redis-cli -p $PORT EXISTS key
+# → 1 (exists) or 0 (doesn't exist)
+```
+
+For multiple keys:
+```bash
+redis-cli -p $PORT EXISTS key1 key2 key3
+# → count of existing keys
+```
+
+### EXPIRE / PEXPIRE
+Set expiration time for a key.
+```bash
+redis-cli -p $PORT EXPIRE key 60
+# → 1 (timeout set) or 0 (timeout not set)
+
+redis-cli -p $PORT PEXPIRE key 1000
+# → 1 (timeout set) or 0 (timeout not set)
+```
+
+### EXPIREAT / PEXPIREAT
+Set expiration timestamp for a key.
+```bash
+redis-cli -p $PORT EXPIREAT key 1672531200
+# → 1 (timeout set) or 0 (timeout not set)
+
+redis-cli -p $PORT PEXPIREAT key 1672531200000
+# → 1 (timeout set) or 0 (timeout not set)
+```
+
+### TTL
+Get the time to live for a key.
+```bash
+redis-cli -p $PORT TTL key
+# → remaining time in seconds
+```
+
+### PERSIST
+Remove expiration from a key.
+```bash
+redis-cli -p $PORT PERSIST key
+# → 1 (timeout removed) or 0 (key has no timeout)
+```
+
+## Hash Commands
+
+### HSET
+Set field-value pairs in a hash.
+```bash
+redis-cli -p $PORT HSET hashkey field1 value1 field2 value2
+# → number of fields added
+```
+
+### HGET
+Get value of a field in a hash.
+```bash
+redis-cli -p $PORT HGET hashkey field1
+# → value1
+```
+
+### HGETALL
+Get all field-value pairs in a hash.
+```bash
+redis-cli -p $PORT HGETALL hashkey
+# → 1) "field1"
+#    2) "value1"
+#    3) "field2"
+#    4) "value2"
+```
+
+### HDEL
+Delete fields from a hash.
+```bash
+redis-cli -p $PORT HDEL hashkey field1 field2
+# → number of fields deleted
+```
+
+### HEXISTS
+Check if a field exists in a hash.
+```bash
+redis-cli -p $PORT HEXISTS hashkey field1
+# → 1 (exists) or 0 (doesn't exist)
+```
+
+### HKEYS
+Get all field names in a hash.
+```bash
+redis-cli -p $PORT HKEYS hashkey
+# → 1) "field1"
+#    2) "field2"
+```
+
+### HVALS
+Get all values in a hash.
+```bash
+redis-cli -p $PORT HVALS hashkey
+# → 1) "value1"
+#    2) "value2"
+```
+
+### HLEN
+Get number of fields in a hash.
+```bash
+redis-cli -p $PORT HLEN hashkey
+# → number of fields
+```
+
+### HMGET
+Get values of multiple fields in a hash.
+```bash
+redis-cli -p $PORT HMGET hashkey field1 field2 field3
+# → 1) "value1"
+#    2) "value2"
+#    3) (nil)
+```
+
+### HSETNX
+Set field-value pair in hash only if field doesn't exist.
+```bash
+redis-cli -p $PORT HSETNX hashkey field1 value1
+# → 1 (field set) or 0 (field not set)
+```
+
+### HINCRBY
+Increment integer value of a field in a hash.
+```bash
+redis-cli -p $PORT HINCRBY hashkey field1 5
+# → new value
+```
+
+### HINCRBYFLOAT
+Increment float value of a field in a hash.
+```bash
+redis-cli -p $PORT HINCRBYFLOAT hashkey field1 3.14
+# → new value
+```
+
+### HSCAN
+Incrementally iterate over fields in a hash.
+```bash
+redis-cli -p $PORT HSCAN hashkey 0
+# → 1) "next_cursor"
+#    2) 1) "field1"
+#       2) "value1"
+#       3) "field2"
+#       4) "value2"
+```
+
+Options:
+- MATCH pattern: Filter fields by pattern
+- COUNT number: Suggest number of fields to return
+
+Examples:
+```bash
+redis-cli -p $PORT HSCAN hashkey 0 MATCH f*
+redis-cli -p $PORT HSCAN hashkey 0 COUNT 10
+redis-cli -p $PORT HSCAN hashkey 0 MATCH f* COUNT 10
+```
+
+## List Commands
+
+### LPUSH
+Insert elements at the head of a list.
+```bash
+redis-cli -p $PORT LPUSH listkey element1 element2 element3
+# → number of elements in the list
+```
+
+### RPUSH
+Insert elements at the tail of a list.
+```bash
+redis-cli -p $PORT RPUSH listkey element1 element2 element3
+# → number of elements in the list
+```
+
+### LPOP
+Remove and return elements from the head of a list.
+```bash
+redis-cli -p $PORT LPOP listkey
+# → element1
+```
+
+With count:
+```bash
+redis-cli -p $PORT LPOP listkey 2
+# → 1) "element1"
+#    2) "element2"
+```
+
+### RPOP
+Remove and return elements from the tail of a list.
+```bash
+redis-cli -p $PORT RPOP listkey
+# → element3
+```
+
+With count:
+```bash
+redis-cli -p $PORT RPOP listkey 2
+# → 1) "element3"
+#    2) "element2"
+```
+
+### LLEN
+Get the length of a list.
+```bash
+redis-cli -p $PORT LLEN listkey
+# → number of elements in the list
+```
+
+### LINDEX
+Get element at index in a list.
+```bash
+redis-cli -p $PORT LINDEX listkey 0
+# → first element
+```
+
+Negative indices count from the end:
+```bash
+redis-cli -p $PORT LINDEX listkey -1
+# → last element
+```
+
+### LRANGE
+Get a range of elements from a list.
+```bash
+redis-cli -p $PORT LRANGE listkey 0 -1
+# → 1) "element1"
+#    2) "element2"
+#    3) "element3"
+```
+
+### LTRIM
+Trim a list to specified range.
+```bash
+redis-cli -p $PORT LTRIM listkey 0 1
+# → OK (list now contains only first 2 elements)
+```
+
+### LREM
+Remove elements from a list.
+```bash
+redis-cli -p $PORT LREM listkey 2 element1
+# → number of elements removed
+```
+
+Count values:
+- Positive: Remove from head
+- Negative: Remove from tail
+- Zero: Remove all
+
+### LINSERT
+Insert element before or after pivot element.
+```bash
+redis-cli -p $PORT LINSERT listkey BEFORE pivot newelement
+# → number of elements in the list
+```
+
+### BLPOP
+Blocking remove and return elements from the head of a list.
+```bash
+redis-cli -p $PORT BLPOP listkey1 listkey2 5
+# → 1) "listkey1"
+#    2) "element1"
+```
+
+If no elements are available, blocks for specified timeout (in seconds) until an element is pushed to one of the lists.
+
+### BRPOP
+Blocking remove and return elements from the tail of a list.
+```bash
+redis-cli -p $PORT BRPOP listkey1 listkey2 5
+# → 1) "listkey1"
+#    2) "element1"
+```
+
+If no elements are available, blocks for specified timeout (in seconds) until an element is pushed to one of the lists.
+
+## Keyspace Commands
+
+### KEYS
+Get all keys matching pattern.
+```bash
+redis-cli -p $PORT KEYS *
+# → 1) "key1"
+#    2) "key2"
+```
+
+### SCAN
+Incrementally iterate over keys.
+```bash
+redis-cli -p $PORT SCAN 0
+# → 1) "next_cursor"
+#    2) 1) "key1"
+#       2) "key2"
+```
+
+Options:
+- MATCH pattern: Filter keys by pattern
+- COUNT number: Suggest number of keys to return
+
+Examples:
+```bash
+redis-cli -p $PORT SCAN 0 MATCH k*
+redis-cli -p $PORT SCAN 0 COUNT 10
+redis-cli -p $PORT SCAN 0 MATCH k* COUNT 10
+```
+
+### DBSIZE
+Get number of keys in current database.
+```bash
+redis-cli -p $PORT DBSIZE
+# → number of keys
+```
+
+### FLUSHDB
+Remove all keys from current database.
+```bash
+redis-cli -p $PORT FLUSHDB
+# → OK
+```
+
+## Configuration Commands
+
+### CONFIG GET
+Get configuration parameter.
+```bash
+redis-cli -p $PORT CONFIG GET dir
+# → 1) "dir"
+#    2) "/path/to/db"
+
+redis-cli -p $PORT CONFIG GET dbfilename
+# → 1) "dbfilename"
+#    2) "0.db"
+```
+
+## Client Commands
+
+### CLIENT SETNAME
+Set current connection name.
+```bash
+redis-cli -p $PORT CLIENT SETNAME myconnection
+# → OK
+```
+
+### CLIENT GETNAME
+Get current connection name.
+```bash
+redis-cli -p $PORT CLIENT GETNAME
+# → myconnection
+```
+
+## Transaction Commands
+
+### MULTI
+Start a transaction block.
+```bash
+redis-cli -p $PORT MULTI
+# → OK
+```
+
+### EXEC
+Execute all commands in transaction block.
+```bash
+redis-cli -p $PORT MULTI
+redis-cli -p $PORT SET key1 value1
+redis-cli -p $PORT SET key2 value2
+redis-cli -p $PORT EXEC
+# → 1) OK
+#    2) OK
+```
+
+### DISCARD
+Discard all commands in transaction block.
+```bash
+redis-cli -p $PORT MULTI
+redis-cli -p $PORT SET key1 value1
+redis-cli -p $PORT DISCARD
+# → OK
+```
+
+## AGE Commands
+
+### AGE GENENC
+Generate ephemeral encryption keypair.
+```bash
+redis-cli -p $PORT AGE GENENC
+# → 1) "recipient_public_key"
+#    2) "identity_secret_key"
+```
+
+### AGE ENCRYPT
+Encrypt message with recipient public key.
+```bash
+redis-cli -p $PORT AGE ENCRYPT recipient_public_key "message"
+# → base64_encoded_ciphertext
+```
+
+### AGE DECRYPT
+Decrypt ciphertext with identity secret key.
+```bash
+redis-cli -p $PORT AGE DECRYPT identity_secret_key base64_encoded_ciphertext
+# → decrypted_message
+```
+
+### AGE GENSIGN
+Generate ephemeral signing keypair.
+```bash
+redis-cli -p $PORT AGE GENSIGN
+# → 1) "verify_public_key"
+#    2) "sign_secret_key"
+```
+
+### AGE SIGN
+Sign message with signing secret key.
+```bash
+redis-cli -p $PORT AGE SIGN sign_secret_key "message"
+# → base64_encoded_signature
+```
+
+### AGE VERIFY
+Verify signature with verify public key.
+```bash
+redis-cli -p $PORT AGE VERIFY verify_public_key "message" base64_encoded_signature
+# → 1 (valid) or 0 (invalid)
+```
+
+### AGE KEYGEN
+Generate and persist named encryption keypair.
+```bash
+redis-cli -p $PORT AGE KEYGEN keyname
+# → 1) "recipient_public_key"
+#    2) "identity_secret_key"
+```
+
+### AGE SIGNKEYGEN
+Generate and persist named signing keypair.
+```bash
+redis-cli -p $PORT AGE SIGNKEYGEN keyname
+# → 1) "verify_public_key"
+#    2) "sign_secret_key"
+```
+
+### AGE ENCRYPTNAME
+Encrypt message with named key.
+```bash
+redis-cli -p $PORT AGE ENCRYPTNAME keyname "message"
+# → base64_encoded_ciphertext
+```
+
+### AGE DECRYPTNAME
+Decrypt ciphertext with named key.
+```bash
+redis-cli -p $PORT AGE DECRYPTNAME keyname base64_encoded_ciphertext
+# → decrypted_message
+```
+
+### AGE SIGNNAME
+Sign message with named signing key.
+```bash
+redis-cli -p $PORT AGE SIGNNAME keyname "message"
+# → base64_encoded_signature
+```
+
+### AGE VERIFYNAME
+Verify signature with named verify key.
+```bash
+redis-cli -p $PORT AGE VERIFYNAME keyname "message" base64_encoded_signature
+# → 1 (valid) or 0 (invalid)
+```
+
+### AGE LIST
+List all stored AGE keys.
+```bash
+redis-cli -p $PORT AGE LIST
+# → 1) "keyname1"
+#    2) "keyname2"
+```
+
+## Server Information Commands
+
+### INFO
+Get server information.
+```bash
+redis-cli -p $PORT INFO
+# → Server information
+```
+
+With section:
+```bash
+redis-cli -p $PORT INFO replication
+# → Replication information
+```
+
+### COMMAND
+Get command information (stub implementation).
+```bash
+redis-cli -p $PORT COMMAND
+# → Empty array (stub)
+```
+
+## Database Selection
+
+### SELECT
+Select database by index.
+```bash
+redis-cli -p $PORT SELECT 0
+# → OK
+```
+
+```
+
+This expanded documentation includes all the list commands that were implemented in the cmd.rs file:
+1. LPUSH - push elements to the left (head) of a list
+2. RPUSH - push elements to the right (tail) of a list
+3. LPOP - pop elements from the left (head) of a list
+4. RPOP - pop elements from the right (tail) of a list
+5. BLPOP - blocking pop from the left with timeout
+6. BRPOP - blocking pop from the right with timeout
+7. LLEN - get list length
+8. LREM - remove elements from list
+9. LTRIM - trim list to range
+10. LINDEX - get element by index
+11. LRANGE - get range of elements
+

herodb/docs/cmds.md

@@ -0,0 +1,227 @@
+
+# HeroDB Redis Protocol Support: Commands & Client Usage
+
+HeroDB is a Redis-compatible database built using the `redb` database backend. 
+
+It supports a subset of Redis commands over the standard RESP (Redis Serialization Protocol) via TCP, allowing you to interact with it using standard Redis clients like `redis-cli`, Python's `redis-py`, Node.js's `ioredis`, etc.
+
+This document provides:
+- A list of all currently supported Redis commands.
+- Example usage with standard Redis clients.
+- Bash and Rust test-inspired usage examples.
+
+## Quick Start
+
+Assuming the server is running on localhost at port `$PORT`:
+
+```bash
+# Build HeroDB
+cargo build --release
+
+# Start HeroDB server
+./target/release/herodb --dir /tmp/herodb_data --port 6381 --debug
+```
+
+## Using Standard Redis Clients
+
+### With `redis-cli`
+
+```bash
+redis-cli -p 6381 SET mykey "hello"
+redis-cli -p 6381 GET mykey
+```
+
+### With Python (`redis-py`)
+
+```python
+import redis
+
+r = redis.Redis(host='localhost', port=6381, db=0)
+r.set('mykey', 'hello')
+print(r.get('mykey').decode())
+```
+
+### With Node.js (`ioredis`)
+
+```js
+const Redis = require("ioredis");
+const redis = new Redis({ port: 6381, host: "localhost" });
+
+await redis.set("mykey", "hello");
+const value = await redis.get("mykey");
+console.log(value); // "hello"
+```
+
+## Supported Redis Commands
+
+### String Commands
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `SET`         | Set a key to a string value              | `SET name "Alice"`                        |
+| `GET`         | Get the value of a key                   | `GET name`                                |
+| `DEL`         | Delete one or more keys                  | `DEL name age`                            |
+| `INCR`        | Increment the integer value of a key     | `INCR counter`                            |
+| `DECR`        | Decrement the integer value of a key     | `DECR counter`                            |
+| `INCRBY`      | Increment key by a given integer         | `INCRBY counter 5`                        |
+| `DECRBY`      | Decrement key by a given integer         | `DECRBY counter 3`                        |
+| `EXISTS`      | Check if a key exists                    | `EXISTS name`                             |
+| `TYPE`        | Return the type of a key                 | `TYPE name`                               |
+
+### Hash Commands
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `HSET`        | Set field in hash stored at key          | `HSET user:1 name "Alice"`                |
+| `HGET`        | Get value of a field in hash             | `HGET user:1 name`                        |
+| `HGETALL`     | Get all fields and values in a hash      | `HGETALL user:1`                          |
+| `HDEL`        | Delete one or more fields from hash      | `HDEL user:1 name age`                    |
+| `HEXISTS`     | Check if field exists in hash            | `HEXISTS user:1 name`                     |
+| `HKEYS`       | Get all field names in a hash            | `HKEYS user:1`                            |
+| `HVALS`       | Get all values in a hash                 | `HVALS user:1`                            |
+| `HLEN`        | Get number of fields in a hash           | `HLEN user:1`                             |
+| `HMGET`       | Get values of multiple fields            | `HMGET user:1 name age`                   |
+| `HSETNX`      | Set field only if it does not exist      | `HSETNX user:1 email alice@example.com`   |
+
+### List Commands
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `LPUSH`       | Insert elements at the head of a list    | `LPUSH mylist "item1" "item2"`            |
+| `RPUSH`       | Insert elements at the tail of a list    | `RPUSH mylist "item3" "item4"`            |
+| `LPOP`        | Remove and return element from head      | `LPOP mylist`                             |
+| `RPOP`        | Remove and return element from tail      | `RPOP mylist`                             |
+| `BLPOP`       | Blocking remove from head with timeout   | `BLPOP mylist1 mylist2 5`                 |
+| `BRPOP`       | Blocking remove from tail with timeout   | `BRPOP mylist1 mylist2 5`                 |
+| `LLEN`        | Get the length of a list                 | `LLEN mylist`                             |
+| `LREM`        | Remove elements from list                | `LREM mylist 2 "item"`                    |
+| `LTRIM`       | Trim list to specified range             | `LTRIM mylist 0 5`                         |
+| `LINDEX`      | Get element by index                     | `LINDEX mylist 0`                         |
+| `LRANGE`      | Get range of elements                    | `LRANGE mylist 0 -1`                      |
+
+### Keys & Scanning
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `KEYS`        | Find all keys matching a pattern         | `KEYS user:*`                             |
+| `SCAN`        | Incrementally iterate keys               | `SCAN 0 MATCH user:* COUNT 10`            |
+
+### Expiration
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `EXPIRE`      | Set a key's time to live in seconds      | `EXPIRE tempkey 60`                       |
+| `TTL`         | Get the time to live for a key           | `TTL tempkey`                             |
+| `PERSIST`     | Remove the expiration from a key         | `PERSIST tempkey`                         |
+
+### Transactions
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `MULTI`       | Start a transaction block                | `MULTI`                                   |
+| `EXEC`        | Execute all commands in a transaction    | `EXEC`                                    |
+| `DISCARD`     | Discard all commands in a transaction    | `DISCARD`                                 |
+
+### Configuration
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `CONFIG GET`  | Get configuration parameters             | `CONFIG GET dir`                           |
+| `CONFIG SET`  | Set configuration parameters             | `CONFIG SET maxmemory 100mb`               |
+
+### Info & Monitoring
+
+| Command       | Description                              | Example Usage                             |
+|---------------|------------------------------------------|-------------------------------------------|
+| `INFO`        | Get information and statistics about server | `INFO`                                 |
+| `PING`        | Ping the server                          | `PING`                                    |
+
+### AGE Cryptography Commands
+
+| Command            | Description                                   | Example Usage                                 |
+|--------------------|-----------------------------------------------|-----------------------------------------------|
+| `AGE GENENC`       | Generate ephemeral encryption keypair         | `AGE GENENC`                                  |
+| `AGE GENSIGN`      | Generate ephemeral signing keypair            | `AGE GENSIGN`                                 |
+| `AGE ENCRYPT`      | Encrypt a message using a public key          | `AGE ENCRYPT <recipient> "msg"`               |
+| `AGE DECRYPT`      | Decrypt a message using a secret key          | `AGE DECRYPT <identity> <ciphertext>`        |
+| `AGE SIGN`         | Sign a message using a secret key            | `AGE SIGN <sign_secret> "msg"`                |
+| `AGE VERIFY`       | Verify a signature using a public key         | `AGE VERIFY <pubkey> "msg" <signature>`      |
+| `AGE KEYGEN`       | Create and persist a named encryption key    | `AGE KEYGEN app1`                             |
+| `AGE SIGNKEYGEN`   | Create and persist a named signing key       | `AGE SIGNKEYGEN app1`                          |
+| `AGE ENCRYPTNAME`  | Encrypt using a named key                     | `AGE ENCRYPTNAME app1 "msg"`                   |
+| `AGE DECRYPTNAME`  | Decrypt using a named key                     | `AGE DECRYPTNAME app1 <ciphertext>`           |
+| `AGE SIGNNAME`     | Sign using a named key                       | `AGE SIGNNAME app1 "msg"`                      |
+| `AGE VERIFYNAME`   | Verify using a named key                      | `AGE VERIFYNAME app1 "msg" <signature>`       |
+| `AGE LIST`         | List all persisted named keys                | `AGE LIST`                                    |
+
+> Note: AGE commands are not part of standard Redis. They are HeroDB-specific extensions for cryptographic operations.
+
+## Example Usage
+
+### Basic String Operations
+
+```bash
+redis-cli -p 6381 SET greeting "Hello, HeroDB!"
+redis-cli -p 6381 GET greeting
+# → "Hello, HeroDB!"
+
+redis-cli -p 6381 INCR visits
+redis-cli -p 6381 INCR visits
+redis-cli -p 6381 GET visits
+# → "2"
+```
+
+### Hash Operations
+
+```bash
+redis-cli -p 6381 HSET user:1000 name "Alice" age "30" city "NYC"
+redis-cli -p 6381 HGET user:1000 name
+# → "Alice"
+
+redis-cli -p 6381 HGETALL user:1000
+# → 1) "name"
+#    2) "Alice"
+#    3) "age"
+#    4) "30"
+#    5) "city"
+#    6) "NYC"
+```
+
+### Expiration
+
+```bash
+redis-cli -p 6381 SET tempkey "temporary"
+redis-cli -p 6381 EXPIRE tempkey 5
+redis-cli -p 6381 TTL tempkey
+# → (integer) 4
+
+# After 5 seconds:
+redis-cli -p 6381 GET tempkey
+# → (nil)
+```
+
+### Transactions
+
+```bash
+redis-cli -p 6381 MULTI
+redis-cli -p 6381 SET txkey1 "value1"
+redis-cli -p 6381 SET txkey2 "value2"
+redis-cli -p 6381 INCR counter
+redis-cli -p 6381 EXEC
+# → 1) OK
+#    2) OK
+#    3) (integer) 3
+```
+
+### Scanning Keys
+
+```bash
+redis-cli -p 6381 SET scankey1 "val1"
+redis-cli -p 6381 SET scankey2 "val2"
+redis-cli -p 6381 HSET scanhash field1 "val1"
+
+redis-cli -p 6381 SCAN 0 MATCH scankey*
+# → 1) "0"
+#    2) 1) "scankey1"
+#       2) "scankey2"
+```

herodb/test_herodb.sh

@@ -298,7 +298,7 @@ main() {
     
     # Start the server
     print_status "Starting HeroDB server..."
-    ./target/release/herodb --dir "$DB_DIR" --port $PORT &
+    ../target/release/herodb --dir "$DB_DIR" --port $PORT &
     SERVER_PID=$!
     
     # Wait for server to start
@@ -352,4 +352,4 @@ check_dependencies() {
 
 # Run dependency check and main function
 check_dependencies
-main "$@"
+main "$@"

herodb/tests/usage_suite.rs

@@ -500,11 +500,11 @@ async fn test_07_age_stateless_suite() {
     let mut s = connect(port).await;
 
     // GENENC -> [recipient, identity]
-    let gen = send_cmd(&mut s, &["AGE", "GENENC"]).await;
+    let gen_result = send_cmd(&mut s, &["AGE", "GENENC"]).await;
     assert!(
-        gen.starts_with("*2\r\n$"),
+        gen_result.starts_with("*2\r\n$"),
         "AGE GENENC should return array [recipient, identity], got:\n{}",
-        gen
+        gen_result
     );
 
     // Parse simple RESP array of two bulk strings to extract keys
@@ -519,7 +519,7 @@ async fn test_07_age_stateless_suite() {
         let ident = lines.next().unwrap_or("").to_string();
         (recip, ident)
     }
-    let (recipient, identity) = parse_two_bulk_array(&gen);
+    let (recipient, identity) = parse_two_bulk_array(&gen_result);
     assert!(
         recipient.starts_with("age1") && identity.starts_with("AGE-SECRET-KEY-1"),
         "Unexpected AGE key formats.\nrecipient: {}\nidentity: {}",