WIP1: implementing JSON-RPC calls over Unix Sockets

docs/rpc_examples.md

@@ -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: <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.