update documentation about 0.db admin db + symmetric encryption + include RPC examples + asymmetric transpart named key instances for encryption and signatures

2025-09-19 11:55:28 +02:00
parent 151a6ffbfa
commit 87177f4a07
6 changed files with 543 additions and 190 deletions
--- a/docs/rpc_examples.md
+++ b/docs/rpc_examples.md
@@ -0,0 +1,141 @@
+# HeroDB JSON-RPC Examples
+
+These examples show full JSON-RPC 2.0 payloads for managing HeroDB via the RPC API (enable with `--enable-rpc`). Methods are named as `hero_<function>`. Params are positional arrays; enum values are strings (e.g., `"Redb"`). Copy-paste into Postman or similar clients.
+
+## Database Management
+
+### Create Database
+Creates a new database with optional per-database encryption key (stored write-only in Admin DB 0).
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "hero_createDatabase",
+  "params": [
+    "Redb",
+    { "name": null, "storage_path": null, "max_size": null, "redis_version": null },
+    null
+  ]
+}
+```
+
+With encryption:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "hero_createDatabase",
+  "params": [
+    "Sled",
+    { "name": "secure-db", "storage_path": null, "max_size": null, "redis_version": null },
+    "my-per-db-encryption-key"
+  ]
+}
+```
+
+### List Databases
+Returns array of database infos (id, backend, encrypted status, size, etc.).
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "hero_listDatabases",
+  "params": []
+}
+```
+
+### Get Database Info
+Retrieves detailed info for a specific database.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "hero_getDatabaseInfo",
+  "params": [1]
+}
+```
+
+### Delete Database
+Removes physical database file; metadata remains in Admin DB 0.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "hero_deleteDatabase",
+  "params": [1]
+}
+```
+
+## Access Control
+
+### Add Access Key
+Adds a hashed access key for private databases. Permissions: `"read"` or `"readwrite"`.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 6,
+  "method": "hero_addAccessKey",
+  "params": [2, "my-access-key", "readwrite"]
+}
+```
+
+### List Access Keys
+Returns array of key hashes, permissions, and creation timestamps.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "method": "hero_listAccessKeys",
+  "params": [2]
+}
+```
+
+### Delete Access Key
+Removes key by its SHA-256 hash.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 8,
+  "method": "hero_deleteAccessKey",
+  "params": [2, "0123abcd...keyhash..."]
+}
+```
+
+### Set Database Public/Private
+Toggles public access (default true). Private databases require access keys.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 9,
+  "method": "hero_setDatabasePublic",
+  "params": [2, false]
+}
+```
+
+## Server Info
+
+### Get Server Stats
+Returns stats like total databases and uptime.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 10,
+  "method": "hero_getServerStats",
+  "params": []
+}
+```
+
+## Notes
+- Per-database encryption keys are write-only; set at creation and used transparently.
+- Access keys are hashed (SHA-256) for storage; provide plaintext in requests.
+- Backend options: `"Redb"` (default) or `"Sled"`.
+- Config object fields (name, storage_path, etc.) are optional and currently ignored but positional.