RustVault 🛡️

RustVault is a high-performance, ACID-compliant custom database engine built from scratch in Rust. It features a Write-Ahead Log (WAL) with CRC32 verification, snapshot compaction, an ACID transaction manager, a multi-dialect query parser/engine (supporting both Key-Value and SQL-like commands), an interactive terminal CLI REPL, an asynchronous REST API server, and an embedded modern Web GUI dashboard.

---

🚀 Key Features

• Custom Durable Storage Engine:
  • MemTable: In-memory B-Tree index for microsecond reads and sorted range scans.
  • Write-Ahead Logging (WAL): Append-only persistent journal with binary framing and CRC32 checksums for deterministic crash recovery.
  • Snapshot Compaction: Point-in-time state checkpointing and automatic WAL truncation.
  • Time-to-Live (TTL): Automatic record expiration and lazy background cleanup.
• ACID Transaction Management:
  • Staging buffers with snapshot isolation.
  • Full BEGIN, COMMIT, and ROLLBACK support with atomic batch writes.
• Rich Query Engine & Parser:
  • Lexer and recursive descent parser.
  • Key-Value dialect: SET, GET, DEL, EXISTS, KEYS, SCAN.
  • SQL-like dialect: SELECT ... FROM ... WHERE ... LIMIT ..., INSERT INTO ..., UPDATE ..., DELETE FROM ....
  • Admin commands: STATS, COMPACT, PING, HELP.
• Async HTTP REST API & Web GUI:
  • High-throughput asynchronous server powered by Tokio and Axum.
  • Embedded modern Web Dashboard with live Query Console, Key-Value Explorer, and System Metrics.
• Interactive CLI & REPL:
  • Colored interactive terminal shell with command execution timing and history.

---

🏗️ Architecture Overview

                      +---------------------------------------+
                      |         Clients & Interfaces          |
                      |  CLI REPL  |  REST API  |   Web GUI   |
                      +-------------------+-------------------+
                                          |
                                          v
                      +---------------------------------------+
                      |       Lexer, Parser & Query AST       |
                      +-------------------+-------------------+
                                          |
                                          v
                      +---------------------------------------+
                      |       ACID Transaction Manager        |
                      |    (Staged Writes & Isolation)        |
                      +-------------------+-------------------+
                                          |
                                          v
                      +---------------------------------------+
                      |             Storage Engine            |
                      |  +----------------+ +---------------+ |
                      |  |    MemTable    | |      WAL      | |
                      |  | (B-Tree Index) | | (CRC32 Frame) | |
                      |  +----------------+ +---------------+ |
                      |  +----------------------------------+ |
                      |  |     Snapshots & Compactor        | |
                      |  +----------------------------------+ |
                      +---------------------------------------+

---

⚡ Quick Start

1. Run Feature Tour & Demo

cargo run -- demo

2. Start the HTTP Server & Web GUI Dashboard

cargo run -- server --port 8080 --dir ./vault_data

Open your browser and visit: http://127.0.0.1:8080/

3. Launch Interactive Terminal REPL

cargo run -- cli --dir ./vault_data

4. Execute a Single Query

cargo run -- exec "SET user:1 'Aditya Pandey' TTL 3600"
cargo run -- exec "GET user:1"
cargo run -- exec "SELECT * FROM user"

---

📖 Query Command Reference

Key-Value Operations

Command	Description	Example
SET <key> <value> [TTL <secs>]	Store a key-value pair with optional TTL	SET session:123 "active" TTL 300
GET <key>	Retrieve value for key	GET session:123
DEL <key>	Delete a key	DEL session:123
EXISTS <key>	Check if a key exists (returns 1 or 0)	EXISTS session:123
KEYS [pattern]	List matching keys (supports * and ?)	KEYS user:*
SCAN [start] [end] [LIMIT n]	Range scan sorted keys	SCAN user:001 user:100 LIMIT 10

SQL-Like Operations

Statement	Description	Example
SELECT * FROM <table> [WHERE ...] [LIMIT n]	Query table documents	SELECT * FROM users WHERE id = '101'
INSERT INTO <table> <key> <val>	Insert record into table	INSERT INTO users 101 '{"name":"Aditya"}'
UPDATE <table> SET col = <val> [WHERE ...]	Update matching records	UPDATE users SET value = '{"name":"Aditya P"}' WHERE id = '101'
DELETE FROM <table> [WHERE ...]	Delete matching table records	DELETE FROM users WHERE id = '101'

ACID Transactions

BEGIN;
SET account:A "900";
SET account:B "350";
COMMIT;  -- Or ROLLBACK to abort and discard changes

System & Maintenance

• STATS: Display active keys, WAL size, IO throughput, and uptime.
• COMPACT: Persist MemTable snapshot and truncate WAL logs.
• PING: Check server liveness (returns PONG).
• HELP: Display query syntax cheatsheet.

---

🌐 REST API Reference

• POST /api/query: Run query string ({ "query": "...", "session_id": "..." })
• GET /api/stats: Fetch real-time storage engine metrics
• GET /api/keys: List stored keys with timestamps and TTL metadata
• POST /api/kv: Quick store endpoint ({ "key": "...", "value": "...", "ttl_secs": ... })
• DELETE /api/kv/{key}: Quick delete endpoint
• POST /api/compact: Trigger snapshot compaction
• GET /api/health: Healthcheck

---

🧪 Testing

Run the full test suite covering storage persistence, WAL crash recovery, ACID transactions, and query engine:

cargo test --all