Fix hook flake checks, relax markdownlint style rules, add hook pointers

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
This commit is contained in:
ariandClaude Sonnet 5.5 committed 2026-10-20 10:21:52 -04:00
1 parent 9e4fb38993
commit 8c0f996262
6 files changed
+15 -6

No files matched your search

+4
View File
@@ -6,3 +6,7 @@ MD033: false # inline HTML
MD036: false # emphasis used as heading
MD041: false # first line heading
MD060: false # table column style
MD012: false # multiple blank lines
MD026: false # trailing punctuation in headings
MD040: false # fenced code language
MD049: false # emphasis style
+2
View File
@@ -34,6 +34,8 @@ nix build && nix flake check # package, module, VM te
`devenv up` runs a local OTLP collector (`dev/otelcol.yaml`). Do not run nix builds unless the task involves Nix files, and never while another agent is running the nix gate. When editing `dev/dev-test.nu`, run `nu dev/dev-test.nu self-check`; it fails if the command table, the subcommands, the help text, the cargo argv or the shell completion drift apart.
Git hooks run fmt, clippy, lint and a secret scan on commit and path-filtered tests on push; see [`docs/hooks.md`](docs/hooks.md).
## Conventions
- Rust edition 2021, axum 0.8: routes use `/{name}`, never `:name` (it panics at startup).
+2
View File
@@ -199,3 +199,5 @@ devenv shell -- dev-test all # fmt, clippy, unit
```
`devenv shell -- dev-test --help` shows the underlying commands (`cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test --lib --bins`, `cargo test --test '*'`). Nushell: `use dev/dev-test.nu *` gives `dev-test unit`, `dev-test vm peers`, ... with tab completion. zsh users add `source <(nu dev/dev-test.nu completions zsh)` to `.zshrc` after `compinit`. An interactive `devenv shell` installs bash completion. The integration tests in `tests/` start the real router on an ephemeral port with fake sources. Design notes live in [ARCHITECTURE.md](ARCHITECTURE.md); work tracking in [TODO.md](TODO.md); extended docs in [docs/](docs/README.md).
Contributors: enter `devenv shell` to install the git hooks; details in [docs/hooks.md](docs/hooks.md).
+4 -3
View File
@@ -1,4 +1,5 @@
#!/usr/bin/env bash
# shellcheck disable=SC2329 # chk_* functions are dispatched by name
# Hook runner. One definition of every check, used by the devenv git-hooks
# entries and by the Nix flake checks.
#
@@ -68,7 +69,7 @@ chk_hygiene() {
bad=1
fi
done
return $bad
return "$bad"
}
# Credentials must never reach the repo (AGENTS.md Safety). A line carrying
@@ -94,7 +95,7 @@ chk_secrets() {
bad=1
fi
done
return $bad
return "$bad"
}
# Repo rules from AGENTS.md that clippy cannot see.
@@ -113,7 +114,7 @@ chk_rules() {
bad=1
fi
done
return $bad
return "$bad"
}
chk_rust-fmt() { cargo fmt --check; }
+2 -2
View File
@@ -59,7 +59,7 @@ in
rust-fmt = rustCheck "fmt" "cargo fmt --check";
rust-clippy = rustCheck "clippy" "cargo clippy --all-targets --offline -- -D warnings";
rust-no-openssl = rustCheck "no-openssl" ''
out=$(cargo tree --offline -i openssl 2>/dev/null || true)
if [ -n "$out" ]; then echo "$out"; echo "openssl is in the dependency tree"; exit 1; fi
found=$(cargo tree --offline -i openssl 2>/dev/null || true)
if [ -n "$found" ]; then echo "$found"; echo "openssl is in the dependency tree"; exit 1; fi
'';
}
+1 -1
View File
@@ -21,7 +21,7 @@ Part of [Phase 5: Consolidator](README.md). Record decisions here and nowhere el
| D5 | Intervals, timeouts, state? | Proposed: TCP 10 s / 3 s, API 30 s / 5 s, 2 consecutive failures to flip down, immediate recovery; state in memory only | Accept the proposal; `last_change` resets on restart (documented). Persisting history conflicts with "live reads only" (DEC-5 reasoning); history belongs to the OTel backend. | Accepted 2026-10-19 (recommendation) |
| D6 | REST proxy shape | (a) `/api/v1/peers/{peer}/...` pass-through of an allowlist; (b) typed endpoints per peer resource; (c) status only | (a). Zero duplicated DTOs, peers evolve independently, allowlist keeps it from becoming an open proxy. | Accepted 2026-10-19 (recommendation) |
| D7 | MCP shape | (a) optional `peer` arg on existing 8 tools plus `list_peers`/`get_peer` (10 tools); (b) separate `peer_*` tool copies (16+); (c) status tools only | (a). Tool count becomes 10 only when `peers.enabled`; snapshot test covers both. Keeps context small for agents. | Accepted 2026-10-19 (recommendation) |
| D8 | Aggregation (fan-out, e.g. "failed units on all peers") | (a) none in this phase; (b) `peer = "*"` on the list tools plus `GET /api/v1/fleet/failed`; (c) both with per-peer partial-failure reporting | (a) for this phase, (b) as the first follow-up: partial failures need a result shape decision (`{peer, ok, data|error}`) that is easier to get right once pass-through is proven. | Accepted 2026-10-19 (recommendation) |
| D8 | Aggregation (fan-out, e.g. "failed units on all peers") | (a) none in this phase; (b) `peer = "*"` on the list tools plus `GET /api/v1/fleet/failed`; (c) both with per-peer partial-failure reporting | (a) for this phase, (b) as the first follow-up: partial failures need a result shape decision (`{peer, ok, data\|error}`) that is easier to get right once pass-through is proven. | Accepted 2026-10-19 (recommendation) |
| D9 | Peer error mapping | Peer 404 -> `NotFound`; 400/422 -> `BadRequest`; peer 401/403 (our token rejected) -> `Unavailable` "peer rejected credentials" (never `Unauthorized`, which would tell the caller to re-auth with us); timeout, refused, DNS, TLS, 5xx, oversize -> `Unavailable` with peer name and class; unknown `{peer}` -> `NotFound`; malformed peer JSON -> `Internal`. Optionally a new `BadGateway` variant (502/504). | Reuse `Unavailable` (503) and put the class in the message and an extra `peer` field; no new variant, so the error contract and MCP mapping are unchanged. Revisit if clients need to distinguish "consolidator down" from "peer down". | Accepted 2026-10-19 (recommendation) |
| D10 | OTel metrics | `peer.up` (0/1; attrs `peer.name`, `peer.check` = `server`\|`api`); `peer.api.auth_ok` (0/1; `peer.name`; **confirmed by the user as a first-class metric**: `server up` + `api up` + `auth_ok = 0` is the "token rejected" state, kept separate from "API down" so alerts can distinguish a revoked or rotated credential from an outage); `peer.check.duration_seconds` (`s`; `peer.name`, `peer.check`); `peer.last_change_timestamp_seconds` (`s`; `peer.name`, `peer.check`). All observable f64 gauges from the registry snapshot; no URL or version in attributes (cardinality, and URLs may embed hostnames the operator treats as sensitive). | Accept. | Accepted 2026-10-19 (recommendation) |
| D11 | SSRF and TLS to peers | Peers come only from configuration (root- or Nix-managed); no request parameter ever supplies a URL. `http`/`https` only, no userinfo, query or fragment; redirects never followed; `deny_cidrs` checked against the resolved IP at connect time (LAN/private ranges must stay allowed, so default denies only link-local/metadata and unspecified). HTTPS verified against the webpki roots plus an optional per-peer `ca_file`; no skip-verify flag. Plain `http` to a non-loopback host requires `allow_plain_http = true` on that peer and logs a warning (the token travels in clear, same stance as DEC-12). | Accept. Alternative to weigh: system roots (needs `rustls-native-certs`, one more dep) instead of webpki roots; recommend webpki plus custom CA since LAN peers will use a private CA anyway. | Accepted 2026-10-19 (recommendation) |