boxmaker/docs/plans/M5a/03-memoryd-crate.md

M5a task 03: the memoryd crate, its configuration and sockets

Branch: m5a (run git switch m5a; git status --short must be empty, otherwise stop) Commit subject: memoryd: the crate, memoryd.toml, and listening on a socket

Goal

A new role crate, memoryd (M5a spec, sections 2, 7 and 11), with its configuration and the socket helper its three sockets will use. It depends on proto and on one new crate, rusqlite (the index, from task 08), which is added to the workspace now so the dependency checks pass once. memoryd serve --config <path> reads its configuration and says "not implemented" until task 10.

Files

• Copy (whole, nothing to fill): crates/memoryd/Cargo.toml, crates/memoryd/src/lib.rs, crates/memoryd/src/main.rs
• Copy (skeletons): crates/memoryd/src/config.rs, crates/memoryd/src/socket.rs
• Copy (tests): crates/memoryd/tests/config.rs, crates/memoryd/tests/socket.rs, crates/memoryd/tests/support/tmp.rs
• Append: docs/plans/M5a/files/runbook-memoryd-start-failed.md to the end of docs/runbook.md (a blank line before it)
• Modify: Cargo.toml, deny.toml, docs/dependencies.md, docs/implementer-log.md

The edits, exactly

Cargo.toml (the workspace): add "crates/memoryd", to members after "crates/gatewayd",, and at the end of [workspace.dependencies] add

rusqlite = { version = "0.40.2", features = ["bundled"] }

deny.toml: the line allow = ["MIT", "Apache-2.0", "Unicode-3.0", "ISC", "BSD-3-Clause"] becomes allow = ["MIT", "Apache-2.0", "Unicode-3.0", "ISC", "BSD-3-Clause", "Zlib"] (foldhash, a dependency of rusqlite, is Zlib-licensed).

docs/dependencies.md: add this row at the end of the table:

| `rusqlite` | 0.40.2 | `memoryd` from M5a | The full-text index (`index/memory.sqlite3`, FTS5), disposable and rebuilt from files. Feature `bundled`: `libsqlite3-sys` compiles SQLite from source with FTS5 on, so no system SQLite is needed. With its dependencies: `libsqlite3-sys` (MIT; build: `cc`, `pkg-config`, `vcpkg`), `hashlink`, `hashbrown`, `foldhash` (Zlib, added to `deny.toml` for it), `fallible-iterator`, `fallible-streaming-iterator`, `smallvec`, `bitflags`. MIT. |

The skeletons

config.rs: the types, Config::parse and the path methods are written; fill Config::load and Config::socket. socket.rs: fill listen, the same five steps as listen in crates/brokerd/src/serve.rs (read it; no crate may depend on another role's crate, so this is a copy with String errors).

Steps

• 1. Copy every file above from docs/plans/M5a/files/ to the same path; make the three edits; append the runbook entry.
• 2. Build. cargo build -p memoryd. The first build downloads rusqlite and compiles SQLite; it takes a few minutes. Then cargo deny check: expected advisories ok, bans ok, licenses ok, sources ok (it needs the network).
• 3. See it fail. cargo test -p memoryd --test config --test socket: expected config 3 failed, 1 passed; socket 2 failed.
• 4. Fill Config::load, Config::socket and listen. cargo fmt --all.
• 5. See it pass. The same command: 4 and 2 passed.
• 6. Run the gate. make gate: gate: ok, with 6 more tests than before (about 868).
• 7. Log and commit. git add -A Cargo.toml Cargo.lock deny.toml crates/memoryd docs/runbook.md docs/dependencies.md docs/implementer-log.md && git commit

Done when

• make gate prints gate: ok, and cargo deny check passes.

Stop and report if

• cargo deny check reports anything but the four "ok"s: a licence other than Zlib, or two versions of one crate. Do not edit deny.toml beyond the one line above.
• The build cannot download rusqlite.