Stamp the version as YYYY.MM.DD-<branch>-<sha>

build.rs builds the string (git, or SLINUXM_* env for builds without .git)
and the lib exposes it as VERSION. --version, /healthz, /api/v1/ping, MCP
server info and OTel service.version use it; OpenAPI info.version stays on
the semver so docs/openapi.json does not change per commit. The flake passes
the commit date and short rev to the package.
This commit is contained in:
ari committed 2026-10-20 23:27:46 -04:00
1 parent 435a54a02d
commit 1a30b20ac0
18 files changed
+322 -18

No files matched your search

+3
View File
@@ -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
@@ -200,6 +201,7 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
| DEC-13 | Outbound peer credentials are external files | Decided 2026-10-19 |
| DEC-14 | Consolidator (peers) design | Decided 2026-10-19, implemented 2026-10-20 |
| DEC-15 | Generated OpenAPI document | 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.
@@ -219,6 +221,7 @@ All accepted. Rationale is kept; the build history is in [`docs/workstreams/`](d
- **HTTP client outcome.** `reqwest` 0.13 with `rustls-no-provider`; the ring provider and webpki roots are passed to the client explicitly, so nothing is installed process-wide and `cargo tree -i openssl` stays empty. Redirects are off and the system proxy is ignored.
- **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-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