# 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.

```sh
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 |
| `--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) |

## 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.