vdm/tools/mockd/README.md

tools/mockd — a fake veloxd

Serves contracts/fixtures over both transports, keeps just enough state that adding and pausing a download does something visible, and fakes progress events at 4 Hz.

The GUI and extension lanes develop against this from day one and never wait for the real daemon. Its unhappy-path flags exist so those lanes can test the cases that are hard to arrange on purpose — a slow daemon, a flaky one, a dropped socket, a refused pairing.

cd tools/mockd
npm install
npm start -- --help
npm start                      # both transports, default paths

Defaults: $XDG_RUNTIME_DIR/velox/velox.sock and ws://127.0.0.1:52000.

Flags

Flag	Effect
--uds <path> / --no-uds	Unix socket path, or don't listen
--ws-port <n> / --no-ws	loopback WebSocket port, or don't listen
--progress-hz <n>	progress event rate (default 4, the contract's ceiling)
--speed <bytes>	synthetic per-task speed
--tasks <n>	seed n plausible synthetic tasks instead of the fixture's two — see below
--active-cap <n>	ceiling on concurrently-"downloading" synthetic tasks (default 24)
--seed <n>	PRNG seed for --tasks, so a run is exactly reproducible (default 1337)
--slow <ms>	delay every reply. Past 750 ms capture.offer must fail open.
--flaky <0..1>	answer this fraction of calls with -32603
--drop-connection <s>	terminate every connection every N seconds
--refuse-pairing	session.pair fails, as if the user clicked Deny
--lockout	session.pair answers -32014, as if the brute-force lockout tripped
--allowed-root <dir>	add a root that download.add's saveDir may resolve inside
--allow-any-origin	skip the moz-extension:// Origin check (debugging only)
--no-validate	stop validating params (to see what a client actually sends)

--tasks — load testing the GUI's table

GUI's M1 definition of done is "10 000 synthetic rows scroll at 60 fps with flat memory over 10 minutes (mockd --tasks 10000)". That takes more than 10 000 identical rows:

npm start -- --tasks 10000

Seeds a plausible population — varied state, size, category, queue position and description, drawn from the same category.list / queue.list fixtures the rest of mockd serves, so nothing here can name a category or queue those methods don't also return. Roughly 55% land complete, the rest split across failed, cancelled, paused, retry_wait and queued, plus a bounded pool (--active-cap, default 24) seeded straight into downloading.

That pool is rotating, not fixed: as an active task finishes, the next one is promoted from its queue's FIFO — with the rest of that queue's queuePosition renumbered, as a real scheduler would — and a small fraction of "finishing" active tasks fail instead and cycle through retry_wait before rejoining. Over a ten-minute run this means hundreds of distinct rows have shown live progress by the time it ends, not the same handful forever, while at any instant the active count stays realistic. A manual download.add is always admitted immediately regardless of --active-cap — a human driving the GUI by hand is never made to wait behind synthetic load.

tick() only ever walks the active pool plus whatever retry-wait entries just came due, never the full task list, so the per-tick cost stays flat regardless of --tasks.

--seed makes a run reproducible: the same seed always produces the same table, which matters when a GUI bug only shows up at a particular row.

What is real and what is faked

Real, because a client's correctness depends on it:

• transport and privilege rules, taken from the generated METHODS table — so a privileged method is refused with -32003 over the WebSocket exactly as veloxd must;
• param validation, through the generated validators, including range and length checks;
• saveDir canonicalization against the allowed roots, so -32011 is reachable;
• the capture.offer decision — monitored types, minimum size, excluded hosts — so both the take and the ignore paths get exercised;
• pairing: session.hello accepts only a token this process actually issued;
• task state, so add / pause / resume / cancel / remove do what a client expects to see.

Faked: bytes advance on a clock, not from a socket. There is no network, no disk, and no engine. Anything not listed above is answered from its golden fixture.

Why it imports the generated protocol code

mockd uses extension/src/shared/protocol/ — the generated TypeScript — rather than types of its own. A mock with hand-written types is a third source of truth, and it drifts. This way a schema change that breaks a client breaks mockd in the same commit.

It imports the individual generated modules (types.js, methods.js, …) rather than index.js, because the extension/ tree has no package.json of its own for Node to resolve a star re-export through. That is a quirk of running from outside that package, not a problem with the generated code; the extension's own bundler is unaffected.