Merge branch 'build-stamped-version'
This commit is contained in:
commit
b3b9103f2f
18 files changed
+322
-18
No files matched your search
@@ -36,6 +36,7 @@ Rust edition 2021; release profile uses LTO and `strip`. Cargo.lock is committed
|
||||
|
||||
```
|
||||
Cargo.toml, Cargo.lock # bin `slinuxm`, lib `skyg_linux_tracker`
|
||||
build.rs # stamps SLINUXM_VERSION (YYYY.MM.DD-<branch>-<sha>); logic in src/version.rs
|
||||
devenv.nix # rust toolchain, pkg-config, libsystemd, otelcol; scripts build/run/smoke/token
|
||||
flake.nix, nix/ # package.nix, module.nix (NixOS), tests/vm.nix (VM test)
|
||||
config.example.toml # every key with its default and env name
|
||||
@@ -206,6 +207,7 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
|
||||
| DEC-14 | Consolidator (peers) design | Decided 2026-10-19, implemented 2026-10-20 |
|
||||
| DEC-15 | Generated OpenAPI document | Decided 2026-10-20 |
|
||||
| DEC-16 | Redoc viewer served by the binary | Decided 2026-10-20 |
|
||||
| DEC-17 | Build-stamped version | Decided 2026-10-21 |
|
||||
|
||||
- **DEC-1 name.** The plan used three names (repo `linux-system-monitor`, service `skyg-linux-tracker`, CLI `skyg`). The binary, CLI and `[[bin]]` are `slinuxm`; tokens use the `slinuxm_` prefix. Unchanged: product name `skyg-linux-tracker`, unit `skyg-linux-tracker.service`, state dir `/var/lib/skyg-linux-tracker`, config `/etc/skyg-linux-tracker.toml`, env prefix `SKYG_`.
|
||||
- **DEC-2 traits and fakes.** `SystemdSource`, `JournalSource`, `DockerSource` live in `src/sources/mod.rs`, fakes in `src/sources/fake.rs`, `AppState` holds `Arc<dyn ...>` (via `async-trait`). Surfaces can be built and tested without systemd or Docker, at the cost of about 100 extra lines.
|
||||
@@ -226,6 +228,7 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
|
||||
- **SSRF at connect time.** The host is resolved once, every address is checked against `deny_cidrs` after `to_canonical()` (so `::ffff:169.254.169.254` matches the IPv4 range), one denied address refuses the whole name, and the checked set is pinned with `resolve_to_addrs`, which closes DNS rebinding. The same `deny_networks` / `denied` code runs at config validation and at connect time. The default `deny_cidrs` covers both families (`169.254.0.0/16`, `0.0.0.0/8`, `fe80::/10`, `::/128`, `fd00:ec2::254/128`); private LAN ranges stay allowed.
|
||||
- **DEC-15 generated OpenAPI.** The document is generated so it cannot drift from the code. REST paths are declared on the handlers with `#[utoipa::path]` (utoipa 6, OpenAPI 3.1). DTO schemas are reflected from the existing `schemars::JsonSchema` derives through a bridge in `openapi.rs`, so one derive serves MCP and OpenAPI; only payloads that exist as `serde_json` literals (error body, health) are written by hand and compared with real output in tests. MCP is not REST, so the tools go in the `x-mcp-tools` extension, built from the tool router's own schemas. Peer paths and the two peer tools appear only when peers are enabled. `tests/openapi.rs` is the drift guard: every router route must be documented, `x-mcp-tools` must match `tools/list`, and `docs/openapi.json` must equal `slinuxm openapi --peers` (regenerate with `cargo run -- openapi --peers > docs/openapi.json`). The route is authenticated like the rest of `/api/v1`.
|
||||
- **DEC-16 Redoc viewer.** `GET /docs` renders the generated document with Redoc, served by the binary. The Redoc 2.5.4 standalone bundle is vendored under `src/docs/` (with its licenses) and embedded, so the page makes no CDN or other outbound request. It is stored gzipped (`redoc.standalone.js.gz`, about 320 KiB, under the 512 KiB hygiene limit) and sent as is with `Content-Encoding: gzip`; the refresh recipe is in the `docs.rs` module doc. 2.x was chosen over 3.x because 3.x is an ES module with a telemetry option; the 2.x bundle is a plain script. The viewer routes are public because a browser navigation cannot carry a bearer header, but they are static and hold no host data: the page asks for a token, keeps it in `sessionStorage` and sends it only to `GET /api/v1/openapi.json`, which stays authenticated. The page's one inline script is admitted by a CSP `sha256` computed from the same constant, so the policy cannot drift (`default-src 'none'`, `connect-src 'self'`, `form-action 'none'`, `frame-ancestors 'none'`; `style-src 'unsafe-inline'` and `worker-src blob:` are needed by Redoc itself). Both routes are in the OpenAPI document, so the drift test covers them. Redoc does not render the `x-mcp-tools` extension; the tools are in the JSON only.
|
||||
- **DEC-17 build-stamped version.** The runtime version is `YYYY.MM.DD-<branch>-<sha>`, computed by `build.rs` and exposed as `skyg_linux_tracker::VERSION` (`SLINUXM_VERSION`); `--version`, `/healthz`, `/api/v1/ping`, MCP server info and OTel `service.version` use it. `Cargo.toml` stays semver because zero-padded CalVer parts (`2026.03.05`) are not valid semver, and `docs/openapi.json` keeps `info.version` from `CARGO_PKG_VERSION`: a stamp that changes per commit would fail the byte-for-byte drift test on every commit. The string logic (`src/version.rs`) is std-only and compiled into both `build.rs` and the library, so one implementation is unit-tested. Every part can come from `SLINUXM_GIT_SHA`, `SLINUXM_GIT_BRANCH` and `SLINUXM_BUILD_DATE`, and `SLINUXM_VERSION` overrides the whole string; the Nix sandbox has no `.git`, so `flake.nix` passes the commit date (`lastModifiedDate`, which keeps the build reproducible) and short rev, with the placeholder branch `nix` because a flake does not expose its branch. `SOURCE_DATE_EPOCH` is ignored because Nix dev shells set it to 1980. A dirty tree appends `-dirty` to the sha, a small extension of the pattern. Because naming any `rerun-if-changed` path turns off cargo's default package-wide watch, `build.rs` also lists `src`, `Cargo.toml`, `Cargo.lock` and `build.rs`, and watches HEAD through `git rev-parse --git-path` so linked worktrees work. A peer's `peer_version` is an opaque string, so a consolidator shows each peer's own stamp.
|
||||
|
||||
## Design notes and gotchas
|
||||
|
||||
|
||||
Reference in new issue
Block a user