Docs accuracy: HERO_DB_PORT is not an OS env var, and "any Redis client" compatibility is overstated #44

New issue

Open

opened 2026-06-10 12:55:01 +00:00 by sameh-farouk · 0 comments

sameh-farouk commented

2026-06-10 12:55:01 +00:00

Member

Two factual documentation errors found while auditing hero_db v0.6.0 (main @ aacaad1). Both are doc-only fixes — the code behaviour is intentional.

1. `HERO_DB_PORT` is documented as an OS environment variable, but it is never read from the environment

The RESP2 TCP port is sourced only from the hero_proc secret store (context core, key HERO_DB_PORT), falling back to 6378 — by design, per the "no env vars, config via hero_proc" convention. The code is correct; the docs mislabel it:

crates/hero_db_server/src/main.rs:117 — printed under the ENV VARS help section: HERO_DB_PORT RESP2 TCP port (default: 6378)
README.md:283 — listed in the env-var table
PURPOSE.md:35 — "configurable via HERO_DB_PORT"

Source of truth: resolve_resp_port() reads from hero_proc (main.rs:166) and is explicitly commented "never from an OS env var" (main.rs:205); a repo-wide search finds no env::var("HERO_DB_PORT"). README.md:183 even contradicts the table by correctly calling it "the HERO_DB_PORT hero_proc secret".

Effect of the bug: a user who runs HERO_DB_PORT=6400 hero_db_server expecting Redis to move ports sees no change — it silently stays on 6378.

Fix: move HERO_DB_PORT out of the ENV VARS help section and the README env-var table; document it as a hero_proc secret (hero_proc secret set HERO_DB_PORT --context core), matching README.md:183.

Same `ENV VARS` help block: two more mislabeled entries

The identical problem affects two sibling entries in crates/hero_db_server/src/main.rs (the print_help ENV VARS section), neither of which is read from the environment:

HERO_DB_DATA_DIR (main.rs:116) — help says "Data storage directory", but config_from_env derives the data dir from path_var() (i.e. PATH_VAR), not this var (main.rs:128).
HERO_DB_SERVER_SOCKET (main.rs:119) — help says "Override rpc.sock path", but the socket is resolve_socket_path("hero_db/rpc.sock") unconditionally (main.rs:127).

(PATH_SOCKET is fine — read inside herolib_core.) HERO_DB_ENCRYPTION_KEY in the same block is also never read, but that is a security bug, not just a doc fix — tracked separately in #46.

2. "Works with redis-cli and any Redis client library" overstates compatibility

README.md:33 — "Redis Protocol Compatible - Works with redis-cli and any Redis client library"
README.md:258 — "AUTH # standard Redis AUTH (works with any Redis client)"

These are contradicted by the compatibility audit:

HELLO is unimplemented, which breaks redis-py >= 8.0 on reconnect (#41).
AUTH is unimplemented (#42) — so the :258 claim is specifically wrong.
Keyspace introspection (KEYS/DBSIZE/EXISTS/SCAN) is incorrect across types (#39), there is no WRONGTYPE safety (#40), and ~25 standard commands are missing (#42).

redis-cli and simple string/hash/list/set usage do work, but "any Redis client library" is not currently true.

Fix: soften to something like "Speaks RESP2 and works with redis-cli and standard clients for a curated subset of Redis commands (strings, hashes, lists, sets, streams, TTL) — see issues #39–#43 for current compatibility gaps."

Doc-accuracy follow-up to the Redis-compatibility audit (issues #39–#43). Claims verified against source at the line refs above. Note: an earlier suspicion that hero_db_examples was empty was false — it ships examples/basic_usage.rs, examples/health.rs, tests/integration.rs — and is deliberately not included here.

Two factual documentation errors found while auditing hero_db v0.6.0 (`main` @ `aacaad1`). Both are **doc-only** fixes — the code behaviour is intentional. ## 1. `HERO_DB_PORT` is documented as an OS environment variable, but it is never read from the environment The RESP2 TCP port is sourced **only** from the hero_proc secret store (context `core`, key `HERO_DB_PORT`), falling back to 6378 — by design, per the "no env vars, config via hero_proc" convention. The code is correct; the docs mislabel it: - `crates/hero_db_server/src/main.rs:117` — printed under the **`ENV VARS`** help section: `HERO_DB_PORT RESP2 TCP port (default: 6378)` - `README.md:283` — listed in the env-var table - `PURPOSE.md:35` — "configurable via `HERO_DB_PORT`" Source of truth: `resolve_resp_port()` reads from hero_proc (`main.rs:166`) and is explicitly commented *"never from an OS env var"* (`main.rs:205`); a repo-wide search finds **no** `env::var("HERO_DB_PORT")`. `README.md:183` even contradicts the table by correctly calling it "the HERO_DB_PORT hero_proc secret". **Effect of the bug:** a user who runs `HERO_DB_PORT=6400 hero_db_server` expecting Redis to move ports sees no change — it silently stays on 6378. **Fix:** move `HERO_DB_PORT` out of the `ENV VARS` help section and the README env-var table; document it as a hero_proc secret (`hero_proc secret set HERO_DB_PORT --context core`), matching `README.md:183`. ### Same `ENV VARS` help block: two more mislabeled entries The identical problem affects two sibling entries in `crates/hero_db_server/src/main.rs` (the `print_help` `ENV VARS` section), neither of which is read from the environment: - `HERO_DB_DATA_DIR` (`main.rs:116`) — help says "Data storage directory", but `config_from_env` derives the data dir from `path_var()` (i.e. `PATH_VAR`), not this var (`main.rs:128`). - `HERO_DB_SERVER_SOCKET` (`main.rs:119`) — help says "Override rpc.sock path", but the socket is `resolve_socket_path("hero_db/rpc.sock")` unconditionally (`main.rs:127`). (`PATH_SOCKET` is fine — read inside `herolib_core`.) `HERO_DB_ENCRYPTION_KEY` in the same block is also never read, but that is a security bug, not just a doc fix — tracked separately in #46. ## 2. "Works with redis-cli and any Redis client library" overstates compatibility - `README.md:33` — "**Redis Protocol Compatible** - Works with redis-cli and any Redis client library" - `README.md:258` — "AUTH <secret> # standard Redis AUTH (works with any Redis client)" These are contradicted by the compatibility audit: - `HELLO` is unimplemented, which **breaks `redis-py >= 8.0`** on reconnect (#41). - `AUTH` is unimplemented (#42) — so the `:258` claim is specifically wrong. - Keyspace introspection (`KEYS`/`DBSIZE`/`EXISTS`/`SCAN`) is incorrect across types (#39), there is no `WRONGTYPE` safety (#40), and ~25 standard commands are missing (#42). `redis-cli` and simple string/hash/list/set usage do work, but "any Redis client library" is not currently true. **Fix:** soften to something like *"Speaks RESP2 and works with `redis-cli` and standard clients for a curated subset of Redis commands (strings, hashes, lists, sets, streams, TTL) — see issues #39–#43 for current compatibility gaps."* --- *Doc-accuracy follow-up to the Redis-compatibility audit (issues #39–#43). Claims verified against source at the line refs above. Note: an earlier suspicion that `hero_db_examples` was empty was **false** — it ships `examples/basic_usage.rs`, `examples/health.rs`, `tests/integration.rs` — and is deliberately not included here.*