herodb/docs/rpc_examples.md

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).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "hero_createDatabase",
  "params": [
    "Redb",
    { "name": null, "storage_path": null, "max_size": null, "redis_version": null },
    null
  ]
}

With encryption:

{
  "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.).

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "hero_listDatabases",
  "params": []
}

Get Database Info

Retrieves detailed info for a specific database.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "hero_getDatabaseInfo",
  "params": [1]
}

Delete Database

Removes physical database file; metadata remains in Admin DB 0.

{
  "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".

{
  "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.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "hero_listAccessKeys",
  "params": [2]
}

Delete Access Key

Removes key by its SHA-256 hash.

{
  "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.

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "hero_setDatabasePublic",
  "params": [2, false]
}

Server Info

Get Server Stats

Returns stats like total databases and uptime.

{
  "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.

IPC over Unix Socket (non-HTTP)

HeroDB supports JSON-RPC over a Unix Domain Socket using reth-ipc. This transport is not HTTP; messages are JSON-RPC framed with a Content-Length header.

• Enable IPC on startup (adjust the socket path as needed):

  • herodb --dir /path/to/data --admin-secret YOUR_SECRET --enable-rpc-ipc --rpc-ipc-path /tmp/herodb.sock

• The same RPC methods are available as over HTTP. Namespace is "hero" (e.g. hero_listDatabases). See the RPC trait in src/rpc.rs and CLI flags in src/main.rs. The IPC bootstrap is in src/rpc_server.rs.

Test via socat (interactive)

1. Connect to the socket with a small timeout:

sudo socat -d -d -t 5 - UNIX-CONNECT:/tmp/herodb.sock

2. Paste a framed JSON-RPC request (Content-Length header, then a blank line, then the JSON body). For example to call hero_listDatabases:

Content-Length: <LEN-BYTES-OF-JSON>

{"jsonrpc":"2.0","id":3,"method":"hero_listDatabases","params":[]}

Notes:

• Replace <LEN-BYTES-OF-JSON> with the byte-length of the exact JSON payload you paste. There must be an empty line between the header and the JSON.
• The response will appear in the same terminal, also framed with Content-Length.