diff --git a/.markdownlint.yaml b/.markdownlint.yaml index d2f4001..fa7155a 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index c6a57e6..612c718 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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). diff --git a/README.md b/README.md index a994c3f..8e59e4e 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/dev/hooks/run.sh b/dev/hooks/run.sh index 50c9236..a7bb786 100755 --- a/dev/hooks/run.sh +++ b/dev/hooks/run.sh @@ -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; } diff --git a/nix/checks.nix b/nix/checks.nix index 997c59d..811afb9 100644 --- a/nix/checks.nix +++ b/nix/checks.nix @@ -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 ''; } diff --git a/plan/phase-5-consolidator/decisions.md b/plan/phase-5-consolidator/decisions.md index fa77900..00a2a44 100644 --- a/plan/phase-5-consolidator/decisions.md +++ b/plan/phase-5-consolidator/decisions.md @@ -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) |