From 764fcb68fafa0382dc0b4a1ab06c8b23eec4d358 Mon Sep 17 00:00:00 2001
From: Maxime Van Hees <maxime.vanhees99@gmail.com>
Date: Wed, 10 Sep 2025 11:59:31 +0200
Subject: [PATCH] update documentation with info about RPC server

---
 README.md       |  8 +++++
 RPC_COMMANDS.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+)
 create mode 100644 RPC_COMMANDS.md

diff --git a/README.md b/README.md
index f78a347..50e47db 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,12 @@ cargo build --release
 ./target/release/herodb --dir /path/to/db --port 6379
 ```
 
+## RPC Server
+
+HeroDB includes an optional JSON-RPC 2.0 management server for database administration tasks. Enable it with the `--enable-rpc` flag and specify the port with `--rpc-port` (default: 8080).
+
+For a complete list of available RPC commands and usage examples, see [RPC_COMMANDS.md](RPC_COMMANDS.md).
+
 ### Options
 
 - `--dir`: Database directory (required)
@@ -31,6 +37,8 @@ cargo build --release
 - `--debug`: Enable debug logging
 - `--encrypt`: Enable database encryption
 - `--encryption-key`: Master encryption key for encrypted databases
+- `--enable-rpc`: Enable RPC management server
+- `--rpc-port`: RPC server port (default: 8080)
 
 ### Examples
 
diff --git a/RPC_COMMANDS.md b/RPC_COMMANDS.md
new file mode 100644
index 0000000..3f23917
--- /dev/null
+++ b/RPC_COMMANDS.md
@@ -0,0 +1,93 @@
+# HeroDB RPC Commands
+
+HeroDB provides a JSON-RPC 2.0 interface for database management operations. The RPC server runs on a separate port (default 8080) and can be enabled with the `--enable-rpc` flag.
+
+All RPC methods are prefixed with the namespace `herodb`.
+
+## Available Commands
+
+### herodb_listDatabases
+Lists all database indices that exist.
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_listDatabases", "id": 1}'
+```
+
+### herodb_createDatabase
+Creates a new database at the specified index.
+
+**Parameters:**
+- `db_index` (number): Database index to create
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_createDatabase", "params": [1], "id": 1}'
+```
+
+### herodb_getDatabaseInfo
+Retrieves detailed information about a specific database.
+
+**Parameters:**
+- `db_index` (number): Database index
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_getDatabaseInfo", "params": [0], "id": 1}'
+```
+
+### herodb_configureDatabase
+Configures an existing database with specific settings.
+
+**Parameters:**
+- `db_index` (number): Database index
+- `config` (object): Configuration object
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_configureDatabase", "params": [0, {"name": "test", "max_size": 1048576}], "id": 1}'
+```
+
+### herodb_setDatabaseEncryption
+Sets encryption for a specific database index.
+
+**Parameters:**
+- `db_index` (number): Database index
+- `encryption_key` (string): Encryption key
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_setDatabaseEncryption", "params": [10, "my-secret-key"], "id": 1}'
+```
+
+### herodb_deleteDatabase
+Deletes a database and its files.
+
+**Parameters:**
+- `db_index` (number): Database index to delete
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_deleteDatabase", "params": [1], "id": 1}'
+```
+
+### herodb_getServerStats
+Retrieves server statistics.
+
+**Example:**
+```bash
+curl -X POST http://localhost:8080 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "herodb_getServerStats", "id": 1}'
\ No newline at end of file