herocode/herodb
12
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

WIP1: implementing JSON-RPC calls over Unix Sockets

Browse Source
This commit is contained in:
Maxime Van Hees
2025-10-21 16:37:11 +02:00
parent c4ae52b6ff
commit 219e612eca
8 changed files with 265 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/basics.md
View File

@@ -9,8 +9,10 @@ To launch HeroDB, use the binary with required and optional flags. The `--admin-
- `--port <port>`: TCP port for Redis protocol (default: 6379).
- `--debug`: Enable debug logging.
- `--sled`: Use Sled backend (default: Redb).
- `--enable-rpc`: Start JSON-RPC management server on port 8080.
- `--enable-rpc`: Start JSON-RPC management server on port 8080 (HTTP over TCP).
- `--rpc-port <port>`: Custom RPC port (default: 8080).
- `--enable-rpc-ipc`: Start JSON-RPC over a Unix Domain Socket (non-HTTP).
- `--rpc-ipc-path <path>`: Path to the Unix socket for IPC (default: `/tmp/herodb.ipc`).
- `--admin-secret <secret>`: Required secret for DB 0 encryption and admin access.
Example:
@@ -18,6 +20,23 @@ Example:
./target/release/herodb --dir /tmp/herodb --admin-secret mysecret --port 6379 --enable-rpc
```
To enable JSON-RPC over a Unix Domain Socket at `/tmp/herodb.sock`:
```bash
./target/release/herodb --dir /tmp/herodb --admin-secret mysecret --enable-rpc-ipc --rpc-ipc-path /tmp/herodb.sock
```
Test the IPC endpoint interactively with socat (non-HTTP transport):
```bash
sudo socat -d -d -t 5 - UNIX-CONNECT:/tmp/herodb.sock
```
Then paste a framed JSON-RPC request (Content-Length header, blank line, then JSON body). Example:
```
Content-Length: 73
{"jsonrpc":"2.0","method":"hero_listDatabases","params":[],"id":3}
```
More IPC examples are in [docs/rpc_examples.md](docs/rpc_examples.md).
Deprecated flags (`--encrypt`, `--encryption-key`) are ignored for data DBs; per-database encryption is managed via RPC.
## Admin Database (DB 0)

28
docs/rpc_examples.md
View File

@@ -138,4 +138,30 @@ Returns stats like total databases and uptime.
- 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.
- 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](src/rpc.rs) and CLI flags in [src/main.rs](src/main.rs). The IPC bootstrap is in [src/rpc_server.rs](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: &lt;LEN-BYTES-OF-JSON&gt;
{"jsonrpc":"2.0","id":3,"method":"hero_listDatabases","params":[]}
Notes:
- Replace &lt;LEN-BYTES-OF-JSON&gt; 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.