Developers
Add an API parameter
A parameter is never only on the API. The same option usually has to reach the storage code, the other nodes of a cluster, an AI agent's tool, the command line, and the web page, and each has a way of going wrong silently. This page is the whole path, in order.
The rules
- Typed, optional, and named for what it does. A
boolis a boolean (nameNot=true), a choice is an enum, a number is a number. Names are camelCase. A new parameter is optional, so an old client keeps working. - The doc comment is the documentation. The comments on the model's fields become the OpenAPI descriptions, which an agent reads to decide how to call the operation. Write them for that reader, and say the constraints ("Needs
name"). - Refuse a mistake; never ignore it. A parameter that makes no sense without another is a 400 whose message names the parameter and whose hint says how to fix it. A silent no-op looks like a bug in the result.
- Every operation is agent-ready (AGT-001 to AGT-005, linted by
.spectral.yaml), and exposed as an MCP tool where it fits the catalogue inspec/13. - An older node must not answer wrongly. If the parameter reaches other nodes, one that doesn't know it will ignore it and answer as if it were absent. See Extend the cluster protocol.
- Say what it costs. If a parameter makes a search slower, the description and the docs say so and what keeps it fast (a time range).
The recipe
- Decide what it means, and write it down. A requirement ID if it is new, an ADR (Proposed) if the choice is not obvious, and a roadmap task with acceptance criteria. Decide now whether an older node ignoring it would change the meaning of an answer.
- Implement it where the data is, with a test that compares the result with something independent. For a filter, a scan of every row: "what the search returns equals what a scan keeps".
- Add it to the model. The parameters struct in
crates/wrendns-api/src/model.rs: an optional field, a doc comment, and, if it must go to peers, the helper that says so. - Validate in the handler. In
crates/wrendns-api/src/lib.rs, where the other checks are, with aProblem::invalid(…).hint(…)that names the parameter. Put the operation's description (its doc comment) in step with the new behaviour. - Wire the backend.
crates/wrendns/src/api_backend.rsturns the parameters into the storage filter. Anything with its own copy of the filter (the live stream has one) needs the same change. - Decide the cluster behaviour (see the cluster page): the read variant that older nodes do not know, if the meaning changes.
- Add it to the MCP tool. The tool's input schema is written by hand in
crates/wrendns-api/src/mcp.rs, with the list that maps its arguments to query parameters. A parameter missing from the schema is invisible to agents. - Add it to the command line if the operation has one (
crates/wrendns/src/main.rsand its module), refusing the same mistakes. - Add it to the page. The web UI's state, the address's keys, and the call. Keep the old addresses meaning what they meant.
- Regenerate, then document. OpenAPI, the MCP tool list, the UI types, then the trace (the order matters). Update
docs/running.md, the spec section, and the ADR and roadmap entries with what you verified and what you did not.
The files
| Layer | File |
|---|---|
| Storage and its tests | crates/wrendns-store/src/qlog/search.rs, qlog/tests.rs |
| API model, validation, the operation's description | crates/wrendns-api/src/model.rs, crates/wrendns-api/src/lib.rs |
| Backend and the live view | crates/wrendns/src/api_backend.rs, crates/wrendns/src/tail.rs |
| The cluster | crates/wrendns/src/federated.rs |
| Agents | crates/wrendns-api/src/mcp.rs, docs/api/mcp-tools.json (generated) |
| Command line | crates/wrendns/src/main.rs, crates/wrendns/src/qlog_cli.rs |
| Web UI | ui/src/pages/Queries.svelte, ui/src/lib/api-types.ts (generated) |
| Documents | docs/api/openapi.json (generated), docs/running.md, spec/ |
The checks
| What fails | What it means |
|---|---|
api_001_committed_openapi_matches_the_code | You changed the model or a description and did not regenerate the OpenAPI document. |
The ui job's diff of api-types.ts, and the spectral lint | The UI types are stale, or the document is no longer agent-ready (a missing description or example). |
agt_006_committed_tool_catalog_matches | You changed a tool's schema and did not regenerate mcp-tools.json. |
spec/trace.py --check | A test name or the roadmap changed and the requirements file is stale. Regenerate it last. |
| Clippy's pedantic lints | Plan for them: a struct of more than three bools, a function over 100 lines, and two variables with similar names all fail. Split the function; allow the lint with a reason where the shape is the point (five independent flags). |
Nothing checks that you reached every layer. The MCP schema, the command line, and the UI's address keys are hand-written, and a missing one compiles and passes. Walk the table above.
Worked example: "does not contain" in the query log
A user asked to search the query log for what does not match (#58, ADR-171). The result: five flags (nameNot, clientNot, statusNot, qtypeNot, rcodeNot) on GET /api/v1/queries, four of them on the live stream, the same in the MCP tool, --not-name and its siblings on wrendns qlog search, and a "not" in the Match menu and beside the other filters on the page.
- The storage change was small because the design fit. A name filter is resolved against each file's dictionary into a yes or no per name, so negating it flips that set. What it gave up was the bloom filter's shortcut: a bloom says "maybe here", never "not in any row", so a negated name reads every block the time range leaves. The docs say so and advise a time range.
- An older node would have answered wrongly. The new flags would be silently ignored, and the result would mix negated rows from new nodes with ordinary rows from old ones. A negated search therefore goes out as a new read that old nodes don't know, and they are listed as not reached.
- A flag without its filter is a 400 that names it, on the API and on the command line, and the page drops such a flag from an old address instead of sending it.
- The first end-to-end test broke another test. It asked the same name three times, which put it at the top of the Cache page's list (ranked by hits), and a later test that expected a different name first failed. It asks each name once now. See Write UI tests.
- It also tripped over time. The API reads
toin whole seconds and the log is flushed about once a second, so a test window must end well after its rows and in the past. - Clippy had opinions. One function grew past 100 lines and the flag struct had five booleans. The first was split (a helper that builds the per-file sets), and the second is allowed with a comment, because the five are independent switches.