Compare commits

...
18 Commits
Author SHA1 Message Date
noah fc573f075a Benchmark health diagnostics on representative miners 2026-10-15 20:19:18 -06:00
noah 1c364d4ff1 Guard UTF-8 naming and repair headless screenshots 2026-10-15 20:10:19 -06:00
noah d54bd6473f Stage verified flash images before device writes 2026-10-15 19:10:28 -06:00
noah a5b07d22ae Grade Toolkit code quality from static checks 2026-10-15 19:03:34 -06:00
Noah 3d17326460 Simplify Toolkit docs and update installer status 2026-10-15 14:36:09 -06:00
noah 56339a5eca Clean candidate build after prerelease decision 2026-10-15 12:43:30 -06:00
noah 00bb760451 Clean generated Toolkit builds after CI and local GUI builds 2026-10-15 11:51:55 -06:00
noah 5f472435a7 Parse Rust test harness benchmark output 2026-10-15 04:06:32 -06:00
noah f22fe19a4d Compare toolkit benchmarks on matching CPU classes 2026-10-15 03:36:53 -06:00
noah 8ab83edc73 Derive toolkit quality grade from measured coverage 2026-10-15 03:34:11 -06:00
noah 601da0548b Revalidate artifacts and guard complete flash streams 2026-10-14 20:54:29 -06:00
noah 4592b927ad Use Gitea-compatible pinned artifact upload 2026-10-14 20:51:23 -06:00
noah 5e347315e2 Publish measured toolkit badges from main CI 2026-10-14 20:44:35 -06:00
noah 603c49a395 Guard verified artifact writes with recovery checks 2026-10-14 20:40:22 -06:00
noah bc8e0535d1 Verify toolkit firmware artifacts before install 2026-10-14 20:31:04 -06:00
noah cf1eaebae1 Record private toolkit benchmark history 2026-10-14 20:21:19 -06:00
noah f89f220f3e Standardize toolkit CI badges and scoped release auth 2026-10-14 20:05:49 -06:00
alkane-ci c18a37eebc ci: refresh README badges [skip release] 2026-10-13 23:27:22 +00:00
39 changed files with 1626 additions and 286 deletions
+19
View File
@@ -0,0 +1,19 @@
name: completed-ci-badge
on:
workflow_run:
workflows: [build-test-release, next-build]
types: [completed]
jobs:
publish:
runs-on: alkane-ci
permissions:
actions: read
contents: write
steps:
- uses: actions/checkout@v4
- name: Publish last completed attempt
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/last-attempt-badge.py
+9 -2
View File
@@ -4,10 +4,14 @@ on:
push:
branches: [next]
permissions:
contents: write
jobs:
candidate:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
steps:
@@ -28,7 +32,7 @@ jobs:
bash scripts/build-wx-linux.sh
fi
- name: Build release candidate
run: cargo build --release -p alkane-gui --offline
run: cargo build --release -p alkane-gui -p alkane-artifacts -p alkane-flash -p alkane-cli --offline
- name: Select candidate version
id: version
run: bash ci/compute-rc-version.sh >> "$GITHUB_OUTPUT"
@@ -41,5 +45,8 @@ jobs:
- name: Create private prerelease
if: steps.version.outputs.release == 'true'
env:
GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/release-rc.py "${{ steps.version.outputs.tag }}" true "dist/alkane-toolkit-${{ steps.version.outputs.version }}-linux-x86_64.tar.gz"
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
+66 -76
View File
@@ -6,10 +6,15 @@ on:
push:
branches: [main]
permissions:
contents: write
actions: write
jobs:
release:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
# Set once for the whole job so build/clippy/test/bench steps don't each
# re-export it (round 18 #12).
@@ -27,6 +32,12 @@ jobs:
- name: Test version logic
run: bash ci/test-compute-version.sh
- name: Last-attempt badge checks
run: python3 ci/test-last-attempt-badge.py
- name: Benchmark history checks
run: python3 ci/test-bench-history.py
- name: Install build dependencies
run: |
apt-get update -qq
@@ -52,6 +63,7 @@ jobs:
run: |
rustup component add clippy >/dev/null 2>&1 || true
cargo clippy -p alkane-gui --no-deps --release --bins --offline -- -D warnings
cargo clippy -p alkane-artifacts -p alkane-flash -p alkane-cli --all-targets --offline -- -D warnings
- name: Set crate version to ${{ steps.ver.outputs.version }}
if: steps.ver.outputs.release == 'true'
@@ -65,7 +77,15 @@ jobs:
- name: Unit tests
run: |
cargo test -p alkane-gui --offline
set -o pipefail
cargo test -p alkane-gui --offline 2>&1 | tee tests-gui.txt
cargo test -p alkane-artifacts -p alkane-flash -p alkane-cli --offline 2>&1 | tee tests-core.txt
cat tests-gui.txt tests-core.txt > tests-current.txt
- name: Load previous main benchmark measurement
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py prepare
- name: Microbenchmarks
run: |
@@ -73,9 +93,19 @@ jobs:
# #1) while keeping the step a hard gate: pipefail preserves cargo's exit
# code (each bench asserts its own absolute ceiling) even through tee.
set -o pipefail
cargo test -p alkane-gui --release --offline -- --ignored --nocapture bench_ \
cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_ --test-threads=1 \
| tee bench-current.txt
- name: Record private benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py publish
- uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7
with:
name: alkane-toolkit-benchmark-site-preview
path: bench-site/index.html
- name: Headless UI self-test
run: |
apt-get update -qq && apt-get install -y -qq --no-install-recommends \
@@ -92,42 +122,32 @@ jobs:
echo "cargo-audit not installed on this runner; skipping"
fi
# Merge coverage from the unit tests AND the headless self-test (ci/coverage.sh)
# so the committed badge reflects real coverage, not the tests-only number a
# plain `cargo llvm-cov` reports. Best-effort: cargo-llvm-cov is fetched as a
# prebuilt binary because the vendored .cargo/config blocks `cargo install`,
# and the instrumented rebuild is slow, so a failure here never blocks a
# release. Feeds steps.cov.outputs.pct to the badge refresh below. xvfb is
# already installed by the self-test step above.
- name: Coverage (best-effort)
# Merge coverage from unit tests and the headless UI self-test. A failed
# measurement must not publish a stale badge or create a release.
- name: Coverage
id: cov
continue-on-error: true
run: |
set -euo pipefail
rustup component add llvm-tools-preview >/dev/null 2>&1 || true
if ! command -v cargo-llvm-cov >/dev/null 2>&1; then
V=0.8.7
URL="https://github.com/taiki-e/cargo-llvm-cov/releases/download/v${V}/cargo-llvm-cov-x86_64-unknown-linux-gnu.tar.gz"
DEST="${CARGO_HOME:-$HOME/.cargo}/bin"
mkdir -p "$DEST"
curl -fsSL "$URL" | tar -xz -C "$DEST" && export PATH="$DEST:$PATH" \
|| echo "cargo-llvm-cov download failed"
fi
if command -v cargo-llvm-cov >/dev/null 2>&1; then
PCT=$(bash ci/coverage.sh --summary-only 2>/dev/null \
| awk '/^TOTAL/{gsub(/%/,"",$10); print $10}')
if [ -n "$PCT" ]; then
echo "pct=${PCT}" >> "$GITHUB_OUTPUT"
echo "line coverage (tests + self-test): ${PCT}%"
else
echo "coverage report produced no TOTAL line; badge left as committed"
fi
else
echo "cargo-llvm-cov unavailable; coverage badge left as committed"
curl -fsSL "$URL" | tar -xz -C "$DEST"
export PATH="$DEST:$PATH"
fi
command -v cargo-llvm-cov >/dev/null
PCT=$(bash ci/coverage.sh --summary-only \
| awk '/^TOTAL/{gsub(/%/,"",$10); print $10}')
[ -n "$PCT" ] || { echo "coverage report produced no TOTAL line" >&2; exit 1; }
echo "pct=${PCT}" >> "$GITHUB_OUTPUT"
echo "line coverage (tests + self-test): ${PCT}%"
- name: Microbenchmark coverage
id: benchcov
run: |
set -euo pipefail
command -v cargo-llvm-cov >/dev/null
PCT=$(bash ci/bench-coverage.sh --summary-only \
| awk '/^TOTAL/{gsub(/%/,"",$10); print $10}')
@@ -135,44 +155,24 @@ jobs:
echo "pct=${PCT}" >> "$GITHUB_OUTPUT"
echo "microbenchmark line coverage: ${PCT}%"
# Refresh the committed README badges from live metrics and push any change
# back to main. Best-effort: a locked-down runner that can't push must not
# fail the release. A badges-only push does not bump the version (see
# compute-version.sh), so it does not loop back into another release.
- name: Refresh badges
if: steps.ver.outputs.release == 'true'
continue-on-error: true
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Generate measured badges
run: |
PASS=$(cargo test -p alkane-gui --offline 2>&1 \
| grep -hoE '[0-9]+ passed' | grep -oE '[0-9]+' | awk '{s+=$1} END{print s+0}')
# Update the coverage badge only when the coverage step produced a number;
# otherwise leave the committed coverage.svg untouched.
COV="${{ steps.cov.outputs.pct }}"
BENCH_COV="${{ steps.benchcov.outputs.pct }}"
COV_ARG=""
[ -n "$COV" ] && COV_ARG="--coverage $COV"
# Weighted-average microbench delta vs the previous release (round 19 #1).
# bench-badge.py also rewrites badges/bench-baseline.json, which is
# committed below with the SVGs (badges/* does not trip a release bump).
set -euo pipefail
PASS=$(grep -E '^test result: ' tests-current.txt \
| grep -oE '[0-9]+ passed' | grep -oE '[0-9]+' \
| awk '{s+=$1} END{print s+0}')
[ "$PASS" -gt 0 ] || { echo "no passing tests counted" >&2; exit 1; }
BENCH_DELTA=$(python3 ci/bench-badge.py --current bench-current.txt \
--baseline badges/bench-baseline.json 2>/dev/null || echo NEW)
python3 ci/gen-badges.py --tests "${PASS:-0}" $COV_ARG \
--bench-coverage "$BENCH_COV" \
--bench-delta "${BENCH_DELTA:-NEW}" --bench "row-render + scan-parse"
if [ -n "$(git status --porcelain badges)" ]; then
git config user.name "alkane-ci"
git config user.email "ci@bluefla.re"
git add badges
git commit -m "ci: refresh README badges [skip release]"
API="${GITHUB_API_URL:-https://gitea.bluefla.re/api/v1}"
HOST="${API%/api/v1}"
git -c http.extraheader="Authorization: token ${TOKEN}" \
push "${HOST}/${GITHUB_REPOSITORY}.git" "HEAD:main" || echo "badge push skipped"
else
echo "badges unchanged"
fi
--baseline badges/bench-baseline.json --no-write)
python3 ci/gen-badges.py --tests "$PASS" \
--coverage "${{ steps.cov.outputs.pct }}" \
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
--bench-delta "$BENCH_DELTA" --clippy clean
- name: Publish measured badges
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/publish-metrics.py
- name: Package artifact
if: steps.ver.outputs.release == 'true'
@@ -198,22 +198,12 @@ jobs:
- name: Create Gitea release + upload artifact
if: steps.ver.outputs.release == 'true'
env:
TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
TAG="${{ steps.ver.outputs.tag }}"
API="${GITHUB_API_URL:-https://gitea.bluefla.re/api/v1}"
REPO="${GITHUB_REPOSITORY}"
body="Automated ${{ steps.ver.outputs.bump }} release from ${GITHUB_SHA}."
rel=$(curl -sS -X POST -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
"${API}/repos/${REPO}/releases" \
-d "{\"tag_name\":\"${TAG}\",\"target_commitish\":\"${GITHUB_SHA}\",\"name\":\"${TAG}\",\"body\":\"${body}\"}")
id=$(echo "$rel" | grep -oE '"id":[0-9]+' | head -1 | cut -d: -f2)
if [ -z "$id" ]; then echo "release create failed: $rel"; exit 1; fi
curl -sS -X POST -H "Authorization: token ${TOKEN}" -H "Content-Type: application/gzip" \
"${API}/repos/${REPO}/releases/${id}/assets?name=${{ steps.pkg.outputs.assetname }}" \
--data-binary @"${{ steps.pkg.outputs.asset }}" | grep -oE '"browser_download_url":"[^"]+"' || true
echo "Released ${TAG}"
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/release-rc.py "${{ steps.ver.outputs.tag }}" false "${{ steps.pkg.outputs.asset }}"
- name: No release needed
if: steps.ver.outputs.release != 'true'
run: echo "No backend/UI change since ${{ steps.ver.outputs.last_tag }} - skipping release."
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
+9 -2
View File
@@ -14,6 +14,7 @@ jobs:
verify:
runs-on: alkane-ci
env:
CARGO_TARGET_DIR: target
WX_PREFIX: /root/.cache/wx-3.3.3-linux
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
steps:
@@ -44,15 +45,18 @@ jobs:
run: |
rustup component add clippy >/dev/null 2>&1 || true
cargo clippy -p alkane-gui --no-deps --release --bins --offline -- -D warnings
cargo clippy -p alkane-artifacts -p alkane-flash -p alkane-cli --all-targets --offline -- -D warnings
- name: Build
run: cargo build --release -p alkane-gui --offline
- name: Unit tests
run: cargo test -p alkane-gui --offline
run: |
cargo test -p alkane-gui --offline
cargo test -p alkane-artifacts -p alkane-flash -p alkane-cli --offline
- name: Microbenchmarks
run: cargo test -p alkane-gui --release --offline -- --ignored --nocapture bench_
run: cargo test -p alkane-gui -p alkane-artifacts --release --offline -- --ignored --nocapture bench_ --test-threads=1
- name: Headless UI self-test
run: |
@@ -73,3 +77,6 @@ jobs:
else
echo "cargo-audit not installed on this runner; skipping"
fi
- name: Clean generated Toolkit build
if: always()
run: python3 ci/cleanup-generated.py
Generated
+7
View File
@@ -40,12 +40,15 @@ name = "alkane-artifacts"
version = "0.1.0"
dependencies = [
"alkane-core",
"sha2",
"thiserror",
]
[[package]]
name = "alkane-cli"
version = "0.1.0"
dependencies = [
"alkane-artifacts",
"alkane-core",
]
@@ -69,7 +72,11 @@ dependencies = [
name = "alkane-flash"
version = "0.1.0"
dependencies = [
"alkane-artifacts",
"alkane-core",
"sha2",
"tempfile",
"thiserror",
]
[[package]]
+48 -96
View File
@@ -1,118 +1,70 @@
# alkane-toolkit
# Alkane Toolkit
[![CI](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions/workflows/release.yml/badge.svg?branch=main)](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
![tests](badges/tests.svg)
![coverage](badges/coverage.svg)
![bench](badges/bench.svg)
![bench coverage](badges/bench-coverage.svg)
![lines of code](badges/loc.svg)
![code quality](badges/quality.svg)
![dependencies](badges/dependencies.svg)
![license](badges/license.svg)
[![CI](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/main.svg)](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
![tests](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/tests.svg)
![coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/coverage.svg)
![bench](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench.svg)
![bench coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench-coverage.svg)
![lines of code](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/loc.svg)
![code quality](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/quality.svg)
![dependencies](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/dependencies.svg)
![license](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/license.svg)
A cross-platform desktop toolkit for discovering, monitoring, and re-flashing
ASIC miners. It scans a fleet over the network, shows live health and hashrate
in a sortable table, and installs **stock** or **alkaneOS** firmware onto a
control board whatever it currently runs (stock, VNish/AnthillOS, Braiins OS+,
LuxOS, ePIC, HiveOn, BixBit, WardenOS).
Desktop fleet discovery and monitoring for ASIC miners. The Rust GUI uses
wxWidgets through a patched [wx-rs bridge](thirdparty/wx-rs). Firmware
installation is under development.
The core and UI are pure Rust; the native window is wxWidgets driven through a
vendored, patched [wx-rs](thirdparty/wx-rs) bridge, so there is no Electron,
no web view, and a single self-contained binary per platform.
## What it does
- **Discover** a fleet by CIDR or IP range and identify each miner's make,
model, control board, and firmware (via a vendored [asic-rs](vendor/asic-rs)).
- **Monitor** hashrate vs. expected, per-board health, chip temperatures, fans,
PSU state, and pool workers, with an Excel-style filter and drag-reorderable
columns.
- **Operate** miners from a right-click menu: flash the locate light, pause /
resume, restart, set a power or hashrate target, select a firmware profile
(LuxOS/VNish presets), configure pools, set the timezone, and change the
password -- each action offered only when every selected miner supports it.
- **Install firmware**: push stock or aftermarket images, or revert an
aftermarket miner to stock, behind a typed confirmation.
Discovery and telemetry are read-only and safe to run against any fleet; every
mutating action is capability-gated and, where destructive, confirmed.
## Build and run (Debian/Ubuntu)
## Run locally
```sh
scripts/build-wx-linux.sh # once: builds the vendored wxWidgets 3.3.3 into ~/.cache
scripts/build-gui-linux.sh # cargo build --release -p alkane-gui
~/.cache/alkane-tk-target/release/alkane-toolkit
scripts/build-wx-linux.sh
scripts/build-gui-linux.sh
ALKANE_FAKE_SCAN=1 ~/.cache/alkane-tk-target/release/alkane-toolkit
```
Runtime needs GTK 3: `sudo apt install libgtk-3-0`. To explore the UI with no
hardware, run the offline demo fleet:
The first command builds wxWidgets 3.3.3 once. Linux runtime needs GTK 3
(`libgtk-3-0` on Debian/Ubuntu). The fake scan uses offline fixtures and
does not contact hardware. Windows and macOS use their respective
`scripts/build-gui-*.sh` scripts and platform toolchains.
```sh
ALKANE_FAKE_SCAN=1 alkane-toolkit
```
## Current scope
Windows and macOS share all GUI code; only the C++ bridge and wx build differ
(`scripts/build-gui-windows.sh` needs an msys2 toolchain, `-macos.sh` needs a
Mac).
- Discover miners by CIDR or IP range with vendored
[asic-rs](vendor/asic-rs), and show model, firmware, health, hashrate,
temperatures, fans, PSU, and pool workers.
- Filter, sort, and reorder columns in the desktop table.
- Probe discovery, telemetry, presets, and write actions with the
`miner_probe` CLI. Run it without arguments for the verb list.
## Command-line probe
`miner_probe` is a headless companion for hardware checks that should not go
through the window event loop -- discovery, telemetry, and each write action:
```sh
miner_probe scan 10.0.0.0/24 # discover + telemetry (TSV)
miner_probe presets 10.0.0.5 # list a firmware's selectable profiles
miner_probe setpreset 10.0.0.5 540MHz
```
Run `miner_probe` with no arguments for the full verb list.
The installer and some operator actions remain roadmap items; see the
[implementation plan](docs/IMPLEMENTATION-PLAN.md) and
[firmware parity matrix](docs/aftermarket-parity-roadmap.md). A listed
firmware or board is not an install claim. Discovery is read-only.
## Development
```sh
export WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config"
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" # keep the target tree off the source share
cargo test -p alkane-gui # unit tests
cargo test -p alkane-gui --release -- --ignored bench_ # microbenchmarks
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings # lint gate
xvfb-run -a env ALKANE_SELFTEST=1 \
"$CARGO_TARGET_DIR/release/alkane-toolkit" # headless UI self-test
ci/coverage.sh --summary-only # coverage (tests + self-test)
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target"
cargo test -p alkane-gui --offline
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings
scripts/ui-selftest.sh
ci/coverage.sh --summary-only
```
CI mirrors these: `verify.yml` runs lint, tests, benchmarks, the self-test, and
a dependency audit on development branches. `release.yml` runs the full gate
on every `main` push and cuts an `X.Y.Z` release when the change warrants it.
`next.yml` builds release candidates with little testing and publishes `-rc`
releases. Dependencies are vendored under `vendor/`, so builds never touch the
network.
Keep build output off the source share. `main` runs the full CI gate and
publishes qualifying releases; `next` builds `-rc` candidates. Badges
report host tests and benchmarks, not installation support. Benchmark
comparisons require the same CPU class. The code quality letter reports the
Clippy gate; the separate coverage badge reports exercised lines.
## Architecture
## Firmware safety
- `crates/alkane-gui` -- the application: scan engine, data model, wxWidgets UI,
and the `miner_probe` CLI (the other `crates/alkane-*` are early scaffolding).
- `vendor/asic-rs` -- the miner-discovery and control library, vendored and
extended through numbered patches under `thirdparty/asic-rs/patches`.
- `thirdparty/wx-rs` -- the patched wxWidgets bridge (see `docs/adr/0002`,
`0003`).
See [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md) for the roadmap
and [`docs/aftermarket-parity-roadmap.md`](docs/aftermarket-parity-roadmap.md)
for the firmware config/scan parity work.
## Firmware safety rules
Encoded in code, from alkane-sdk `docs/install-methods.md`:
1. Never write the bootloader or secure region.
2. Verify on a channel the installer does not control.
3. Reboot is root-only; a dropped SSH connection can still be success.
4. A packer is per board; never reuse one across boards.
5. Boot-switch handling is an explicit, verified step.
The [SDK install rules](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md) require
serial and recovery checks for risky writes. Installation must never write
the bootloader or secure region, must verify over an independent channel,
and must use the packer and boot-switch procedure for the exact board.
## License
Licensed under the [MIT license](LICENSE).
[MIT](LICENSE). Vendored dependencies keep their own terms.
+9 -9
View File
@@ -1,11 +1,11 @@
{
"bench_parse_line_near_max_addrs": 644187.0,
"bench_parse_targets_many_ranges_near_cap": 49565223.0,
"bench_render_cells": 3037944.0,
"bench_sort_by_each_column": 816884.0,
"bench_targets_to_cidrs_large_range": 443875.0,
"bench_upsert_cold_start_population": 8871040.0,
"bench_view_pipeline": 177652.0,
"bench_view_pipeline_default_sort": 203830.0,
"bench_view_pipeline_with_filter": 187371.0
"bench_parse_line_near_max_addrs": 807160.0,
"bench_parse_targets_many_ranges_near_cap": 54465485.0,
"bench_render_cells": 3503112.0,
"bench_sort_by_each_column": 486975.0,
"bench_targets_to_cidrs_large_range": 482167.0,
"bench_upsert_cold_start_population": 8315814.0,
"bench_view_pipeline": 191794.0,
"bench_view_pipeline_default_sort": 193214.0,
"bench_view_pipeline_with_filter": 253085.0
}
+7 -7
View File
@@ -1,19 +1,19 @@
<svg xmlns="http://www.w3.org/2000/svg" width="160.5" height="20" role="img" aria-label="bench coverage: pending">
<title>bench coverage: pending</title>
<svg xmlns="http://www.w3.org/2000/svg" width="128.0" height="20" role="img" aria-label="bench coverage: 7%">
<title>bench coverage: 7%</title>
<linearGradient id="s" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<clipPath id="r"><rect width="160.5" height="20" rx="3" fill="#fff"/></clipPath>
<clipPath id="r"><rect width="128.0" height="20" rx="3" fill="#fff"/></clipPath>
<g clip-path="url(#r)">
<rect width="103.0" height="20" fill="#555"/>
<rect x="103.0" width="57.5" height="20" fill="#9f9f9f"/>
<rect width="160.5" height="20" fill="url(#s)"/>
<rect x="103.0" width="25.0" height="20" fill="#e05d44"/>
<rect width="128.0" height="20" fill="url(#s)"/>
</g>
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
<text x="51.5" y="15" fill="#010101" fill-opacity=".3">bench coverage</text>
<text x="51.5" y="14">bench coverage</text>
<text x="131.8" y="15" fill="#010101" fill-opacity=".3">pending</text>
<text x="131.8" y="14">pending</text>
<text x="115.5" y="15" fill="#010101" fill-opacity=".3">7%</text>
<text x="115.5" y="14">7%</text>
</g>
</svg>

Before

Width:  |  Height:  |  Size: 966 B

After

Width:  |  Height:  |  Size: 946 B

+7 -7
View File
@@ -1,19 +1,19 @@
<svg xmlns="http://www.w3.org/2000/svg" width="147.5" height="20" role="img" aria-label="bench: -79.9% vs prev">
<title>bench: -79.9% vs prev</title>
<svg xmlns="http://www.w3.org/2000/svg" width="141.0" height="20" role="img" aria-label="bench: +7.4% vs prev">
<title>bench: +7.4% vs prev</title>
<linearGradient id="s" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<clipPath id="r"><rect width="147.5" height="20" rx="3" fill="#fff"/></clipPath>
<clipPath id="r"><rect width="141.0" height="20" rx="3" fill="#fff"/></clipPath>
<g clip-path="url(#r)">
<rect width="44.5" height="20" fill="#555"/>
<rect x="44.5" width="103.0" height="20" fill="#4c1"/>
<rect width="147.5" height="20" fill="url(#s)"/>
<rect x="44.5" width="96.5" height="20" fill="#dfb317"/>
<rect width="141.0" height="20" fill="url(#s)"/>
</g>
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
<text x="22.2" y="15" fill="#010101" fill-opacity=".3">bench</text>
<text x="22.2" y="14">bench</text>
<text x="96.0" y="15" fill="#010101" fill-opacity=".3">-79.9% vs prev</text>
<text x="96.0" y="14">-79.9% vs prev</text>
<text x="92.8" y="15" fill="#010101" fill-opacity=".3">+7.4% vs prev</text>
<text x="92.8" y="14">+7.4% vs prev</text>
</g>
</svg>

Before

Width:  |  Height:  |  Size: 952 B

After

Width:  |  Height:  |  Size: 950 B

+4 -4
View File
@@ -1,5 +1,5 @@
<svg xmlns="http://www.w3.org/2000/svg" width="141.0" height="20" role="img" aria-label="lines of code: 13.7k">
<title>lines of code: 13.7k</title>
<svg xmlns="http://www.w3.org/2000/svg" width="141.0" height="20" role="img" aria-label="lines of code: 13.7K">
<title>lines of code: 13.7K</title>
<linearGradient id="s" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
@@ -13,7 +13,7 @@
<g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
<text x="48.2" y="15" fill="#010101" fill-opacity=".3">lines of code</text>
<text x="48.2" y="14">lines of code</text>
<text x="118.8" y="15" fill="#010101" fill-opacity=".3">13.7k</text>
<text x="118.8" y="14">13.7k</text>
<text x="118.8" y="15" fill="#010101" fill-opacity=".3">13.7K</text>
<text x="118.8" y="14">13.7K</text>
</g>
</svg>

Before

Width:  |  Height:  |  Size: 952 B

After

Width:  |  Height:  |  Size: 952 B

+54
View File
@@ -0,0 +1,54 @@
# SPDX-License-Identifier: MIT
"""Write small badge artifacts to the private Gitea CI badge branch."""
import base64
import json
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
BADGE_BRANCH = "ci-badges"
def request_json(url: str, token: str, method: str = "GET",
payload: dict | None = None) -> dict:
body = None if payload is None else json.dumps(payload).encode()
request = Request(url, data=body, method=method,
headers={"Authorization": f"token {token}",
"Content-Type": "application/json"})
with urlopen(request, timeout=20) as response:
return json.load(response)
def publish_file(api: str, repo: str, filename: str, data: bytes,
token: str, message: str, max_bytes: int = 65_536) -> None:
if not filename or filename.startswith("/") or any(
part in ("", ".", "..") for part in filename.split("/")):
raise ValueError("invalid badge path")
if len(data) > max_bytes:
raise ValueError("artifact exceeds size limit")
path = f"{api}/repos/{repo}/contents/{quote(filename, safe='/')}"
encoded = base64.b64encode(data).decode("ascii")
for attempt in range(3):
try:
current = request_json(path + "?ref=" + BADGE_BRANCH, token)
if base64.b64decode(current["content"]) == data:
return
sha = current["sha"]
method = "PUT"
except HTTPError as error:
if error.code != 404:
raise
sha = None
method = "POST"
payload = {"branch": BADGE_BRANCH, "content": encoded,
"message": message + " [skip ci]"}
if sha is not None:
payload["sha"] = sha
try:
request_json(path, token, method, payload)
return
except HTTPError as error:
if error.code not in (409, 422) or attempt == 2:
raise
raise RuntimeError("badge write did not complete")
+1 -1
View File
@@ -31,7 +31,7 @@ import sys
# trailing (?![a-zA-Z]) stops "s" in words like "rows"/"cidrs" from matching.
_DUR = re.compile(r"([0-9]+(?:\.[0-9]+)?)\s*(ns|µs|us|ms|s)(?![a-zA-Z])")
_UNIT_NS = {"ns": 1.0, "us": 1e3, "µs": 1e3, "ms": 1e6, "s": 1e9}
_NAME = re.compile(r"^(bench_[A-Za-z0-9_]+)\s*:")
_NAME = re.compile(r"^(?:test [A-Za-z0-9_:]+ \.\.\. )?(bench_[A-Za-z0-9_]+)\s*:")
def parse_bench(text: str) -> dict:
+1 -1
View File
@@ -3,6 +3,6 @@
set -euo pipefail
export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$HOME/.cache/wx-3.3.3-linux/bin/wx-config}"
cargo llvm-cov clean --workspace
cargo llvm-cov --no-report --offline --release -p alkane-gui -- \
cargo llvm-cov --no-report --offline --release -p alkane-gui -p alkane-artifacts -- \
--ignored --nocapture bench_
cargo llvm-cov report --release --ignore-filename-regex '(thirdparty|vendor)/' "$@"
+159
View File
@@ -0,0 +1,159 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Keep measured main-branch benchmarks in the private CI artifact branch."""
import argparse
import base64
from datetime import datetime, timezone
import html
import json
import math
import os
from pathlib import Path
import re
import subprocess
import importlib.util
from urllib.error import HTTPError
from urllib.parse import quote
from badge_store import BADGE_BRANCH, publish_file, request_json
from bench_host import identity as benchmark_host
bench_spec = importlib.util.spec_from_file_location(
"bench_badge", Path(__file__).with_name("bench-badge.py"))
bench_badge = importlib.util.module_from_spec(bench_spec)
bench_spec.loader.exec_module(bench_badge)
INDEX = "history/index.json"
MAX_INDEX_ENTRIES = 50
def read_artifact(api: str, repo: str, token: str, filename: str):
url = f"{api}/repos/{repo}/contents/{quote(filename, safe='/')}?ref={BADGE_BRANCH}"
try:
value = request_json(url, token)
except HTTPError as error:
if error.code == 404:
return None
raise
return json.loads(base64.b64decode(value["content"]))
def valid_benches(metrics: dict) -> dict[str, float]:
values = metrics.get("bench_ns_per_op")
if not isinstance(values, dict) or not values:
raise ValueError("benchmark measurements are missing")
if any(not isinstance(key, str) or not re.fullmatch(r"[A-Za-z0-9_]+", key)
or not isinstance(value, (float, int)) or isinstance(value, bool)
or not math.isfinite(value) or value <= 0 for key, value in values.items()):
raise ValueError("benchmark measurements are invalid")
return values
def git_distance(ancestor: str, sha: str) -> int | None:
result = subprocess.run(("git", "rev-list", "--count", f"{ancestor}..{sha}"),
capture_output=True, text=True, check=False)
if result.returncode != 0:
return None
ancestor_check = subprocess.run(("git", "merge-base", "--is-ancestor", ancestor, sha),
capture_output=True, check=False)
return int(result.stdout.strip()) if ancestor_check.returncode == 0 else None
def previous_measurement(index: dict, sha: str, distance=None, host=None) -> dict:
distance = distance or git_distance
choices = []
for entry in index.get("entries", []):
ancestor = entry.get("sha")
if ancestor == sha or not isinstance(ancestor, str):
continue
if host is not None and entry.get("metrics", {}).get("bench_host") != host:
continue
gap = distance(ancestor, sha)
if gap is not None and gap > 0:
choices.append((gap, entry))
if not choices:
return {}
return valid_benches(min(choices, key=lambda item: item[0])[1]["metrics"])
def updated_index(index: dict, sha: str, metrics: dict, timestamp: str) -> dict:
if not re.fullmatch(r"[0-9a-f]{40}", sha):
raise ValueError("invalid commit SHA")
valid_benches(metrics)
entries = [entry for entry in index.get("entries", []) if entry.get("sha") != sha]
entries.append({"sha": sha, "timestamp": timestamp, "metrics": metrics})
return {"schema": 1, "entries": entries[-MAX_INDEX_ENTRIES:]}
def render_html(index: dict) -> str:
entries = list(reversed(index.get("entries", [])))
names = sorted({name for entry in entries
for name in valid_benches(entry["metrics"])})
rows = []
for entry in entries:
sha = entry["sha"]
if not re.fullmatch(r"[0-9a-f]{40}", sha):
raise ValueError("invalid commit SHA in history")
cells = [f'<td><a href="https://gitea.bluefla.re/blueflare/alkane-toolkit/commit/{sha}">{sha[:10]}</a></td>',
f'<td>{html.escape(entry["timestamp"])}</td>']
values = valid_benches(entry["metrics"])
host = entry["metrics"].get("bench_host", {})
host_label = host.get("cpu_model", "unknown") if isinstance(host, dict) else "unknown"
cells.append(f'<td>{html.escape(str(host_label))}</td>')
cells += [f'<td>{values[name]:.3f}</td>' if name in values else '<td>new</td>'
for name in names]
rows.append("<tr>" + "".join(cells) + "</tr>")
headings = "".join(f"<th scope=\"col\">{html.escape(name)} (ns/op)</th>" for name in names)
return ("<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">"
"<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">"
"<title>Alkane Toolkit benchmarks</title><style>"
"body{font:16px system-ui,sans-serif;max-width:1100px;margin:2rem auto;padding:0 1rem;color:#17212b}"
"h1{font-size:2rem}p{max-width:70ch;line-height:1.5}"
"table{border-collapse:collapse;min-width:100%}th,td{padding:.5rem;border-bottom:1px solid #ccd3da;text-align:right}"
"th:first-child,td:first-child{text-align:left}th:nth-child(2),td:nth-child(2){text-align:left}"
"th{background:#edf2f6;position:sticky;top:0}a{color:#145a9a}"
".scroll{overflow-x:auto}small{color:#55616d}</style></head><body>"
"<h1>Alkane Toolkit microbenchmarks</h1>"
"<p>Measured on main CI. Lower ns/op is faster. Results depend on runner load and are "
"not board performance. A new benchmark has no earlier comparison.</p>"
f"<p><small>Most recent {len(entries)} measured commits. Full per-commit JSON is retained "
"in the private ci-badges branch.</small></p>"
f"<div class=\"scroll\"><table><thead><tr><th scope=\"col\">Commit</th>"
f"<th scope=\"col\">UTC</th><th scope=\"col\">CPU</th>{headings}</tr></thead><tbody>{''.join(rows)}"
"</tbody></table></div></body></html>\n")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("action", choices=("prepare", "publish"))
args = parser.parse_args()
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
sha = os.environ["GITHUB_SHA"]
index = read_artifact(api, repo, token, INDEX) or {"schema": 1, "entries": []}
if index.get("schema") != 1 or not isinstance(index.get("entries"), list):
raise ValueError("unsupported benchmark history index")
if args.action == "prepare":
baseline = previous_measurement(index, sha, host=benchmark_host())
Path("badges").mkdir(exist_ok=True)
Path("badges/bench-baseline.json").write_text(json.dumps(baseline) + "\n")
print(f"Loaded {len(baseline)} prior benchmark measurements")
return
metrics = {"bench_ns_per_op": bench_badge.parse_bench(
Path("bench-current.txt").read_text()), "bench_host": benchmark_host()}
timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
index = updated_index(index, sha, metrics, timestamp)
record = json.dumps(index["entries"][-1], indent=2).encode() + b"\n"
publish_file(api, repo, f"history/{sha}.json", record, token,
"Record Alkane Toolkit benchmarks", max_bytes=1_048_576)
publish_file(api, repo, INDEX, json.dumps(index, indent=2).encode() + b"\n",
token, "Update Alkane Toolkit benchmark index", max_bytes=1_048_576)
Path("bench-site").mkdir(exist_ok=True)
Path("bench-site/index.html").write_text(render_html(index))
print(f"Recorded benchmarks for {sha[:10]}")
if __name__ == "__main__":
main()
+19
View File
@@ -0,0 +1,19 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Identify the CPU class used for comparable CI microbenchmark baselines."""
import os
import platform
from pathlib import Path
def identity() -> dict[str, object]:
model = "unknown"
cpuinfo = Path("/proc/cpuinfo")
if cpuinfo.is_file():
for line in cpuinfo.read_text(errors="replace").splitlines():
if line.startswith(("model name\t", "Hardware\t", "Processor\t")):
model = line.partition(":")[2].strip()[:160]
break
return {"architecture": platform.machine(), "cpu_model": model,
"logical_cpus": os.cpu_count() or 1}
+42
View File
@@ -0,0 +1,42 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Remove generated Toolkit CI work after the release asset is uploaded."""
import os
from pathlib import Path
import shutil
import sys
ROOT = Path(__file__).resolve().parents[1]
DIRECTORIES = ("target", "dist", "coverage")
FILES = ("bench-current.txt",)
def cleanup() -> None:
if not os.environ.get("GITHUB_RUN_ID"):
raise ValueError("cleanup is restricted to CI runs")
for name in DIRECTORIES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated directory: {path}")
if path.is_dir():
shutil.rmtree(path)
print(f"Removed generated directory: {name}")
elif path.exists():
raise ValueError(f"expected a generated directory: {path}")
for name in FILES:
path = ROOT / name
if path.is_symlink() or path.parent.resolve() != ROOT.resolve():
raise ValueError(f"unsafe generated file: {path}")
if path.is_file():
path.unlink()
print(f"Removed generated file: {name}")
if __name__ == "__main__":
try:
cleanup()
except (OSError, ValueError) as error:
print(f"ERROR: Toolkit cleanup: {error}", file=sys.stderr)
raise SystemExit(1)
+16 -13
View File
@@ -2,10 +2,11 @@
# Measure line coverage from BOTH the unit tests AND the headless UI self-test.
#
# The self-test (ALKANE_SELFTEST=1) builds the real wxWidgets table, renders every
# fixture through the real widgets, and checks each cell against the model -- it
# exercises most of ui.rs. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it, so ui.rs shows
# ~4% even though it is integration-tested. This combines both runs' coverage.
# fixture through the real widgets, and checks each cell against the model.
# It covers the fixture-rendering path, while interactive event handlers need
# separate tests. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it. This
# combines both runs' coverage.
#
# Usage: ci/coverage.sh [extra `cargo llvm-cov report` args, e.g. --summary-only]
set -euo pipefail
@@ -16,21 +17,23 @@ export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$HOME/.cache/wx-3.3.3-linux/bin/wx-conf
# default; override with CARGO_LLVM_COV_FLAGS if you need something else.
read -ra CARGO_FLAGS <<<"${CARGO_LLVM_COV_FLAGS:---offline}"
# A display for the self-test's real widgets.
need_xvfb() { command -v xvfb-run >/dev/null 2>&1; }
# A display is required for the self-test; skipping it would publish an
# incomplete coverage number as if the measured test set had run.
if ! command -v xvfb-run >/dev/null 2>&1; then
echo "coverage.sh: xvfb-run is required for the UI self-test" >&2
exit 1
fi
cargo llvm-cov clean --workspace
# 1. Unit tests.
# 1. Unit tests for the GUI and the artifact/flash/CLI crates.
cargo llvm-cov --no-report "${CARGO_FLAGS[@]}" -p alkane-gui --bin alkane-toolkit
cargo llvm-cov --no-report "${CARGO_FLAGS[@]}" \
-p alkane-artifacts -p alkane-flash -p alkane-cli
# 2. Headless UI self-test, under the same instrumentation, its coverage appended.
if need_xvfb; then
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
else
echo "coverage.sh: xvfb-run not found; skipping the self-test run (unit tests only)" >&2
fi
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
# 3. Merged report, our source only (vendored asic-rs + the patched wx-rs bridge
# are out of scope).
+17 -7
View File
@@ -1,10 +1,8 @@
#!/usr/bin/env python3
"""Generate self-contained shields-style SVG badges into badges/.
Self-hosted Gitea renders a README's relative image links straight from the
repo, so committing the SVGs (rather than depending on an external badge
service that would have to reach a possibly-private Gitea) is the robust choice.
CI regenerates them from live metrics and commits any changes back.
Main CI regenerates SVGs from measured metrics and publishes them to the
private ci-badges branch. The README loads those authenticated raw artifacts.
Usage:
gen-badges.py --tests N --coverage PCT --bench "label" [--out badges]
@@ -13,6 +11,7 @@ Metrics not passed on the command line are computed here (LOC from the source
tree, dependency count from Cargo.lock, license from Cargo.toml).
"""
import argparse
import math
import os
import re
import sys
@@ -132,6 +131,12 @@ def cov_color(pct: float) -> str:
return "red"
def quality_grade(clippy: str | None) -> str:
if clippy is None:
return "pending"
return "A" if clippy == "clean" else "F"
def human(n: int) -> str:
suffixes = ("", "K", "M", "G")
value = float(n)
@@ -160,8 +165,11 @@ def main() -> int:
# percentage string (e.g. "-3.2"), or "NEW"/"" when there is no baseline yet
# (round 19 #1). Takes precedence over --bench for the bench badge.
ap.add_argument("--bench-delta", default=None)
ap.add_argument("--clippy", default="clean")
ap.add_argument("--clippy", choices=("clean", "failed"))
args = ap.parse_args()
for value in (args.coverage, args.bench_coverage):
if value is not None and (not math.isfinite(value) or not 0 <= value <= 100):
ap.error("coverage must be a finite percentage between 0 and 100")
os.makedirs(os.path.join(args.root, args.out), exist_ok=True)
@@ -178,8 +186,10 @@ def main() -> int:
write("loc", "lines of code", human(loc), loc_color(loc))
write("license", "license", lic, "blue")
write("dependencies", "dependencies", str(deps), "blue")
grade = "A" if args.clippy == "clean" else "F"
write("quality", "code quality", grade, "brightgreen" if grade == "A" else "red")
grade = quality_grade(args.clippy)
write("quality", "code quality", grade,
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
"D": "orange", "F": "red", "pending": "lightgrey"}[grade])
if args.tests is not None:
write("tests", "tests", f"{args.tests} passing", "brightgreen")
if args.coverage is not None:
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish the last completed main/next CI result to a private badge branch."""
import base64
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen
WORKFLOWS = {"release.yml": "main", "next.yml": "next"}
BADGE_BRANCH = "ci-badges"
def badge(branch: str, conclusion: str, run_id: int) -> bytes:
passed = conclusion == "success"
word = "pass" if passed else "fail"
color = "#2ea043" if passed else "#d1242f"
title = f"CI {branch}: last completed attempt {word} (run {run_id})"
return (f'<svg xmlns="http://www.w3.org/2000/svg" width="102" height="20" '
f'role="img" aria-label="{title}"><title>{title}</title>'
'<rect width="102" height="20" rx="3" fill="#555"/>'
f'<path d="M39 0h60a3 3 0 0 1 3 3v14a3 3 0 0 1-3 3H39z" fill="{color}"/>'
'<text x="20" y="14" fill="#fff" text-anchor="middle" '
'font-family="sans-serif" font-size="11">CI</text>'
f'<text x="70" y="14" fill="#fff" text-anchor="middle" '
f'font-family="sans-serif" font-size="11">{word}</text></svg>\n').encode()
def request_json(url: str, token: str, method: str = "GET",
payload: dict | None = None) -> dict:
body = None if payload is None else json.dumps(payload).encode()
request = Request(url, data=body, method=method,
headers={"Authorization": f"token {token}",
"Content-Type": "application/json"})
with urlopen(request, timeout=20) as response:
return json.load(response)
def latest_completed(api: str, repo: str, workflow: str, branch: str,
token: str) -> tuple[int, str]:
path = quote(workflow, safe="")
latest = None
for page in range(1, 21):
query = urlencode({"branch": branch, "limit": 50, "page": page})
url = f"{api}/repos/{repo}/actions/workflows/{path}/runs?{query}"
runs = request_json(url, token).get("workflow_runs", [])
for run in runs:
if run.get("head_branch") != branch or run.get("status") != "completed":
continue
if run.get("conclusion") not in ("success", "failure"):
continue
candidate = (int(run["id"]), run["conclusion"])
if latest is None or candidate[0] > latest[0]:
latest = candidate
if len(runs) < 50:
break
if latest is None:
raise RuntimeError(f"no completed {branch} run found for {workflow}")
return latest
def publish(api: str, repo: str, branch: str, data: bytes, token: str) -> None:
path = f"{api}/repos/{repo}/contents/{branch}.svg"
encoded = base64.b64encode(data).decode("ascii")
for attempt in range(3):
try:
current = request_json(path + "?ref=" + BADGE_BRANCH, token)
current_data = base64.b64decode(current["content"])
if current_data == data:
return
sha = current["sha"]
method = "PUT"
except HTTPError as error:
if error.code != 404:
raise
sha = None
method = "POST"
payload = {"branch": BADGE_BRANCH, "content": encoded,
"message": f"Record completed {branch} CI attempt"}
if sha is not None:
payload["sha"] = sha
try:
request_json(path, token, method, payload)
return
except HTTPError as error:
if error.code not in (409, 422) or attempt == 2:
raise
raise RuntimeError("badge write did not complete")
def main() -> None:
event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
if event.get("action") != "completed":
raise RuntimeError("expected a completed workflow_run event")
run = event["workflow_run"]
workflow = run["path"].split("@", 1)[0].rsplit("/", 1)[-1]
expected_branch = WORKFLOWS.get(workflow)
if expected_branch is None or run.get("head_branch") != expected_branch:
raise RuntimeError("unexpected workflow or branch")
repo = os.environ["GITHUB_REPOSITORY"]
if event["repository"]["full_name"] != repo:
raise RuntimeError("repository mismatch")
api = os.environ["GITHUB_API_URL"].rstrip("/")
token = os.environ["GITEA_TOKEN"]
run_id, conclusion = latest_completed(api, repo, workflow, expected_branch, token)
publish(api, repo, expected_branch, badge(expected_branch, conclusion, run_id), token)
print(f"{expected_branch} badge records completed run {run_id}: {conclusion}")
if __name__ == "__main__":
main()
+29
View File
@@ -0,0 +1,29 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish measured toolkit badges to the private Gitea badge branch."""
import os
from pathlib import Path
from badge_store import publish_file
ROOT = Path(__file__).resolve().parents[1]
NAMES = ("tests", "coverage", "bench", "bench-coverage", "loc",
"dependencies", "quality", "license")
def main() -> None:
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
for name in NAMES:
data = (ROOT / "badges" / f"{name}.svg").read_bytes()
if not data.lstrip().startswith(b"<svg"):
raise ValueError(f"invalid {name} SVG")
publish_file(api, repo, f"badges/{name}.svg", data, token,
f"Update measured {name} badge")
print(f"Published {len(NAMES)} measured badge SVGs")
if __name__ == "__main__":
main()
+2 -1
View File
@@ -1,4 +1,5 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Create one Gitea release and attach files using the runner's scoped token."""
import json
@@ -27,7 +28,7 @@ def main():
api = os.environ.get("GITHUB_API_URL", "https://gitea.bluefla.re/api/v1").rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
sha = os.environ["GITHUB_SHA"]
body = f"Automated Alkane OS build from {sha}. Conformance results are in the repository."
body = f"Automated Alkane toolkit build from {sha}."
metadata = {
"tag_name": tag,
"target_commitish": sha,
+70
View File
@@ -0,0 +1,70 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Exercise benchmark history selection and safe site rendering."""
import sys
from pathlib import Path
import unittest
sys.path.insert(0, str(Path(__file__).resolve().parent))
from bench_history import bench_badge, previous_measurement, render_html, updated_index
class HistoryTests(unittest.TestCase):
def test_cargo_nocapture_benchmark_lines_are_parsed(self):
output = (
"test tests::bench_verify_artifact ... bench_verify_artifact: 208.302µs\n"
"test model::tests::bench_render_cells ... bench_render_cells: "
"5000 rows x 10 cols = 8.007185ms/full-render (bytes=13553600)\n"
"bench_direct: 12ns/op\n"
)
self.assertEqual(bench_badge.parse_bench(output), {
"bench_verify_artifact": 208_302.0,
"bench_render_cells": 8_007_185.0,
"bench_direct": 12.0,
})
def test_retry_uses_previous_commit(self):
first = "a" * 40
second = "b" * 40
index = {"schema": 1, "entries": [
{"sha": first, "timestamp": "2026-01-01T00:00:00+00:00",
"metrics": {"bench_ns_per_op": {"hash": 10.0}}},
{"sha": second, "timestamp": "2026-01-02T00:00:00+00:00",
"metrics": {"bench_ns_per_op": {"hash": 8.0}}}]}
self.assertEqual(previous_measurement(index, second,
lambda ancestor, sha: 1 if ancestor == first else None),
{"hash": 10.0})
updated = updated_index(index, second, {"bench_ns_per_op": {"hash": 7.5}},
"2026-01-03T00:00:00+00:00")
self.assertEqual(len(updated["entries"]), 2)
self.assertEqual(updated["entries"][-1]["metrics"]["bench_ns_per_op"]["hash"], 7.5)
def test_invalid_measurement_and_sha_rejected(self):
with self.assertRaises(ValueError):
updated_index({}, "bad", {"bench_ns_per_op": {"hash": 1}}, "now")
with self.assertRaises(ValueError):
updated_index({}, "a" * 40, {"bench_ns_per_op": {"hash": -1}}, "now")
def test_baseline_must_match_cpu_class(self):
host = {"architecture": "x86_64", "cpu_model": "A", "logical_cpus": 8}
other = {"architecture": "x86_64", "cpu_model": "B", "logical_cpus": 8}
index = {"entries": [{"sha": "a" * 40, "metrics": {
"bench_ns_per_op": {"hash": 10.0}, "bench_host": host}}]}
distance = lambda _ancestor, _sha: 1
self.assertEqual(previous_measurement(index, "b" * 40, distance, host),
{"hash": 10.0})
self.assertEqual(previous_measurement(index, "b" * 40, distance, other), {})
def test_site_escapes_history_content(self):
entry = {"sha": "a" * 40, "timestamp": "<script>alert(1)</script>",
"metrics": {"bench_ns_per_op": {"hash": 10.0},
"bench_host": {"cpu_model": "<script>cpu</script>"}}}
page = render_html({"entries": [entry]})
self.assertIn("&lt;script&gt;", page)
self.assertNotIn("<script>", page)
self.assertIn("10.000", page)
if __name__ == "__main__":
unittest.main()
+35
View File
@@ -0,0 +1,35 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Check that queued CI runs do not displace the last completed result."""
import importlib.util
from pathlib import Path
from unittest.mock import patch
import xml.etree.ElementTree as ET
path = Path(__file__).with_name("last-attempt-badge.py")
spec = importlib.util.spec_from_file_location("last_attempt_badge", path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
def runs(_url, _token):
return {"workflow_runs": [
{"id": 105, "head_branch": "main", "status": "completed", "conclusion": "cancelled"},
{"id": 104, "head_branch": "main", "status": "queued", "conclusion": None},
{"id": 103, "head_branch": "main", "status": "completed", "conclusion": "failure"},
{"id": 102, "head_branch": "main", "status": "completed", "conclusion": "success"},
]}
with patch.object(module, "request_json", runs):
assert module.latest_completed("https://example.invalid/api/v1", "owner/repo",
"release.yml", "main", "token") == (103, "failure")
svg = module.badge("main", "failure", 103)
root = ET.fromstring(svg)
assert root.attrib["aria-label"] == "CI main: last completed attempt fail (run 103)"
assert b">fail</text>" in svg
assert b"#d1242f" in svg
assert b">pass</text>" in module.badge("next", "success", 108)
print("last completed CI badge: queued run ignored, pass/fail SVGs valid")
+2
View File
@@ -6,3 +6,5 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
sha2.workspace = true
thiserror.workspace = true
+257 -1
View File
@@ -1 +1,257 @@
// alkane-artifacts
// SPDX-License-Identifier: MIT
//! Verify local firmware artifacts before an install path consumes them.
use sha2::{Digest, Sha256};
use std::collections::HashSet;
use std::fs::File;
use std::io::{Read, Seek, SeekFrom};
use std::path::{Component, Path, PathBuf};
use thiserror::Error;
const SEED: &str = include_str!("../data/manifest-seed.csv");
const HEADER: &str = "sha256,size_bytes,path,family,format,applicability";
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ArtifactRecord {
pub sha256: String,
pub size_bytes: u64,
pub path: PathBuf,
pub family: String,
pub format: String,
pub applicability: String,
}
#[derive(Debug, Error)]
pub enum VerifyError {
#[error("artifact I/O: {0}")]
Io(#[from] std::io::Error),
#[error("manifest line {0} is invalid")]
Manifest(usize),
#[error("artifact size differs from manifest")]
Size,
#[error("artifact signature does not match its declared format")]
Signature,
#[error("artifact SHA-256 differs from manifest")]
Digest,
#[error("artifact format is not recognized")]
UnsupportedFormat,
}
/// A verified, rewound descriptor. Consumers should read this descriptor
/// directly instead of reopening the path after verification.
pub struct VerifiedArtifact {
file: File,
record: ArtifactRecord,
}
impl VerifiedArtifact {
pub fn record(&self) -> &ArtifactRecord {
&self.record
}
pub fn reader(&mut self) -> &mut File {
&mut self.file
}
/// Recheck the same descriptor immediately before a guarded write.
pub fn revalidate(&mut self) -> Result<(), VerifyError> {
verify_open_file(&mut self.file, &self.record)
}
}
pub fn seed_manifest() -> Result<Vec<ArtifactRecord>, VerifyError> {
parse_manifest(SEED)
}
pub fn parse_manifest(text: &str) -> Result<Vec<ArtifactRecord>, VerifyError> {
let mut lines = text.lines();
if lines.next() != Some(HEADER) {
return Err(VerifyError::Manifest(1));
}
let mut paths = HashSet::new();
let mut records = Vec::new();
for (line_number, line) in lines.enumerate() {
let line_number = line_number + 2;
let parts: Vec<_> = line.splitn(6, ',').collect();
if parts.len() != 6 || parts.iter().any(|part| part.trim().is_empty()) {
return Err(VerifyError::Manifest(line_number));
}
let digest = parts[0];
let path = PathBuf::from(parts[2]);
if digest.len() != 64
|| !digest.bytes().all(|byte| byte.is_ascii_hexdigit())
|| !path
.components()
.all(|part| matches!(part, Component::Normal(_)))
|| !paths.insert(path.clone())
{
return Err(VerifyError::Manifest(line_number));
}
let size_bytes = parts[1]
.parse::<u64>()
.map_err(|_| VerifyError::Manifest(line_number))?;
if size_bytes == 0 {
return Err(VerifyError::Manifest(line_number));
}
records.push(ArtifactRecord {
sha256: digest.to_ascii_lowercase(),
size_bytes,
path,
family: parts[3].to_owned(),
format: parts[4].to_owned(),
applicability: parts[5].to_owned(),
});
}
if records.is_empty() {
return Err(VerifyError::Manifest(1));
}
Ok(records)
}
fn signature_matches(format: &str, first: &[u8]) -> Result<bool, VerifyError> {
let prefix: &[u8] = match format {
"IMAGEWTY-SD" | "update-zip" | "zip-installer" => b"PK\x03\x04",
"ubifs" => b"\x31\x18\x10\x06",
"swu" => b"070702",
"wm-package-0x9a5ba57c" => b"\x7c\xa5\x5b\x9a",
"bmu" => b"\x26\x01",
"bin-AES-container" => b"\x3f\x0a\x64\xae",
_ => return Err(VerifyError::UnsupportedFormat),
};
Ok(first.starts_with(prefix))
}
pub fn verify_file(path: &Path, record: &ArtifactRecord) -> Result<VerifiedArtifact, VerifyError> {
let mut file = File::open(path)?;
verify_open_file(&mut file, record)?;
Ok(VerifiedArtifact {
file,
record: record.clone(),
})
}
fn verify_open_file(file: &mut File, record: &ArtifactRecord) -> Result<(), VerifyError> {
if file.metadata()?.len() != record.size_bytes {
return Err(VerifyError::Size);
}
file.seek(SeekFrom::Start(0))?;
let mut first = [0_u8; 16];
let length = file.read(&mut first)?;
if !signature_matches(&record.format, &first[..length])? {
return Err(VerifyError::Signature);
}
file.seek(SeekFrom::Start(0))?;
let mut hasher = Sha256::new();
let mut buffer = [0_u8; 64 * 1024];
let mut read_bytes = 0_u64;
loop {
let length = file.read(&mut buffer)?;
if length == 0 {
break;
}
read_bytes += length as u64;
hasher.update(&buffer[..length]);
}
if read_bytes != record.size_bytes {
return Err(VerifyError::Size);
}
let digest = hasher.finalize();
let actual: String = digest.iter().map(|byte| format!("{byte:02x}")).collect();
if actual != record.sha256 {
return Err(VerifyError::Digest);
}
file.seek(SeekFrom::Start(0))?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use std::io::Write;
#[test]
fn manifest_has_unique_safe_records() {
let records = seed_manifest().unwrap();
assert_eq!(records.len(), 14);
let traversal = format!("{HEADER}\n{},12,../escape,bin,bmu,all\n", "0".repeat(64));
assert!(matches!(
parse_manifest(&traversal),
Err(VerifyError::Manifest(2))
));
}
#[test]
fn checks_size_signature_and_digest_before_consumption() {
let path =
std::env::temp_dir().join(format!("alkane-artifact-test-{}", std::process::id()));
let bytes = b"PK\x03\x04example";
let mut file = File::create(&path).unwrap();
file.write_all(bytes).unwrap();
drop(file);
let mut record = ArtifactRecord {
sha256: Sha256::digest(bytes)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect(),
size_bytes: bytes.len() as u64,
path: PathBuf::from("fixture.zip"),
family: "test".to_owned(),
format: "update-zip".to_owned(),
applicability: "test".to_owned(),
};
let mut verified = verify_file(&path, &record).unwrap();
verified.revalidate().unwrap();
let mut replay = Vec::new();
verified.reader().read_to_end(&mut replay).unwrap();
assert_eq!(replay, bytes);
std::fs::write(&path, b"PK\x03\x04changed").unwrap();
assert!(matches!(verified.revalidate(), Err(VerifyError::Digest)));
std::fs::write(&path, bytes).unwrap();
verified.revalidate().unwrap();
record.size_bytes += 1;
assert!(matches!(
verify_file(&path, &record),
Err(VerifyError::Size)
));
record.size_bytes -= 1;
record.format = "ubifs".to_owned();
assert!(matches!(
verify_file(&path, &record),
Err(VerifyError::Signature)
));
record.format = "update-zip".to_owned();
record.sha256 = "0".repeat(64);
assert!(matches!(
verify_file(&path, &record),
Err(VerifyError::Digest)
));
std::fs::remove_file(path).unwrap();
}
#[test]
#[ignore = "microbenchmark"]
fn bench_verify_artifact() {
let path =
std::env::temp_dir().join(format!("alkane-artifact-bench-{}", std::process::id()));
let mut bytes = vec![0x42_u8; 65_536];
bytes[..4].copy_from_slice(b"PK\x03\x04");
std::fs::write(&path, &bytes).unwrap();
let record = ArtifactRecord {
sha256: Sha256::digest(&bytes)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect(),
size_bytes: bytes.len() as u64,
path: PathBuf::from("bench.zip"),
family: "test".to_owned(),
format: "update-zip".to_owned(),
applicability: "test".to_owned(),
};
let started = std::time::Instant::now();
for _ in 0..100 {
std::hint::black_box(verify_file(&path, &record).unwrap());
}
println!("bench_verify_artifact: {:?}", started.elapsed() / 100);
std::fs::remove_file(path).unwrap();
}
}
+1
View File
@@ -6,3 +6,4 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
+29 -2
View File
@@ -1,4 +1,31 @@
//! Headless driver over the same engine the GUI uses.
// SPDX-License-Identifier: MIT
//! Headless entry point for read-only artifact verification.
use alkane_artifacts::{seed_manifest, verify_file};
use std::path::Path;
fn run() -> Result<(), Box<dyn std::error::Error>> {
let args: Vec<_> = std::env::args().collect();
if args.len() != 4 || args[1] != "verify-artifact" {
return Err("usage: alkane-cli verify-artifact <manifest-path> <local-file>".into());
}
let record = seed_manifest()?
.into_iter()
.find(|item| item.path == Path::new(&args[2]))
.ok_or("artifact path is absent from the seed manifest")?;
let verified = verify_file(Path::new(&args[3]), &record)?;
println!(
"verified {} {} {} bytes",
verified.record().family,
verified.record().format,
verified.record().size_bytes
);
Ok(())
}
fn main() {
println!("alkane-toolkit-cli: scaffold");
if let Err(error) = run() {
eprintln!("artifact verification failed: {error}");
std::process::exit(1);
}
}
+4
View File
@@ -6,3 +6,7 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
sha2.workspace = true
thiserror.workspace = true
tempfile = "3"
+446 -1
View File
@@ -1 +1,446 @@
// alkane-flash
// SPDX-License-Identifier: MIT
//! Guarded write sequence for a verified artifact and an SDK partition plan.
//! Board transport adapters must supply serial, recovery and readback evidence.
use alkane_artifacts::VerifiedArtifact;
use sha2::{Digest, Sha256};
use std::io::{Read, Seek, SeekFrom, Write};
use thiserror::Error;
pub struct PartitionSpec {
pub name: String,
pub capacity_bytes: u64,
pub secure: bool,
pub boot_critical: bool,
}
pub struct BackupEvidence {
pub location: String,
pub bytes: u64,
pub sha256: [u8; 32],
}
pub struct WriteReceipt {
pub partition: String,
pub backup: BackupEvidence,
pub image_sha256: [u8; 32],
}
pub trait Writer {
type Error: std::fmt::Display;
fn channel_id(&self) -> &str;
fn serial_console_attached(&mut self) -> Result<bool, Self::Error>;
fn recovery_image_ready(&mut self, partition: &PartitionSpec) -> Result<bool, Self::Error>;
fn backup(&mut self, partition: &PartitionSpec) -> Result<BackupEvidence, Self::Error>;
fn write(
&mut self,
partition: &PartitionSpec,
image: &mut dyn Read,
image_size: u64,
) -> Result<(), Self::Error>;
}
pub trait IndependentReadback {
type Error: std::fmt::Display;
fn channel_id(&self) -> &str;
fn sha256(&mut self, partition: &PartitionSpec, length: u64) -> Result<[u8; 32], Self::Error>;
}
#[derive(Debug, Error, Eq, PartialEq)]
pub enum FlashError {
#[error("secure partition write refused")]
SecurePartition,
#[error("image exceeds partition capacity")]
ImageTooLarge,
#[error("boot-critical write requires an attached serial console")]
SerialRequired,
#[error("boot-critical write requires verified recovery media")]
RecoveryRequired,
#[error("readback must use an independent channel")]
SameChannel,
#[error("complete backup evidence is missing")]
BackupIncomplete,
#[error("post-write readback differs from the image")]
ReadbackMismatch,
#[error("verified image has an invalid digest")]
InvalidDigest,
#[error("image changed since verification")]
ArtifactChanged,
#[error("writer did not consume the complete image")]
IncompleteWrite,
#[error("write transport: {0}")]
Write(String),
#[error("readback transport: {0}")]
Readback(String),
#[error("artifact I/O: {0}")]
ArtifactIo(String),
}
fn digest_bytes(hex: &str) -> Result<[u8; 32], FlashError> {
if hex.len() != 64 {
return Err(FlashError::InvalidDigest);
}
let mut result = [0_u8; 32];
for (index, pair) in hex.as_bytes().chunks_exact(2).enumerate() {
let text = std::str::from_utf8(pair).map_err(|_| FlashError::InvalidDigest)?;
result[index] = u8::from_str_radix(text, 16).map_err(|_| FlashError::InvalidDigest)?;
}
Ok(result)
}
fn stage_verified_artifact(
artifact: &mut VerifiedArtifact,
size: u64,
expected: [u8; 32],
) -> Result<std::fs::File, FlashError> {
let mut staged = tempfile::tempfile().map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
artifact
.reader()
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
let mut source = DigestReader {
inner: artifact.reader(),
remaining: size,
digest: Sha256::new(),
};
std::io::copy(&mut source, &mut staged).map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
if source.remaining != 0 || <[u8; 32]>::from(source.digest.finalize()) != expected {
return Err(FlashError::ArtifactChanged);
}
staged
.flush()
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
staged
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
Ok(staged)
}
struct DigestReader<'a> {
inner: &'a mut dyn Read,
remaining: u64,
digest: Sha256,
}
impl Read for DigestReader<'_> {
fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
let limit = buffer
.len()
.min(usize::try_from(self.remaining).unwrap_or(usize::MAX));
let length = self.inner.read(&mut buffer[..limit])?;
self.remaining -= length as u64;
self.digest.update(&buffer[..length]);
Ok(length)
}
}
/// Stop before reboot. The caller must still prove live boot and persistence.
pub fn write_verified<W: Writer, R: IndependentReadback>(
partition: &PartitionSpec,
artifact: &mut VerifiedArtifact,
writer: &mut W,
readback: &mut R,
) -> Result<WriteReceipt, FlashError> {
if partition.secure {
return Err(FlashError::SecurePartition);
}
let size = artifact.record().size_bytes;
if size == 0 || partition.capacity_bytes == 0 || size > partition.capacity_bytes {
return Err(FlashError::ImageTooLarge);
}
if writer.channel_id().is_empty()
|| readback.channel_id().is_empty()
|| writer.channel_id() == readback.channel_id()
{
return Err(FlashError::SameChannel);
}
if partition.boot_critical {
if !writer
.serial_console_attached()
.map_err(|e| FlashError::Write(e.to_string()))?
{
return Err(FlashError::SerialRequired);
}
if !writer
.recovery_image_ready(partition)
.map_err(|e| FlashError::Write(e.to_string()))?
{
return Err(FlashError::RecoveryRequired);
}
}
artifact
.revalidate()
.map_err(|_| FlashError::ArtifactChanged)?;
let expected = digest_bytes(&artifact.record().sha256)?;
// The source path may change while backup or transport I/O runs. Copy and
// verify it before any device write; the anonymous file is removed on drop.
let mut staged = stage_verified_artifact(artifact, size, expected)?;
let backup = writer
.backup(partition)
.map_err(|e| FlashError::Write(e.to_string()))?;
if backup.location.is_empty()
|| backup.bytes != partition.capacity_bytes
|| backup.sha256 == [0; 32]
{
return Err(FlashError::BackupIncomplete);
}
let mut stream = DigestReader {
inner: &mut staged,
remaining: size,
digest: Sha256::new(),
};
writer
.write(partition, &mut stream, size)
.map_err(|e| FlashError::Write(e.to_string()))?;
if stream.remaining != 0 {
return Err(FlashError::IncompleteWrite);
}
let written_digest: [u8; 32] = stream.digest.finalize().into();
if written_digest != expected {
return Err(FlashError::ArtifactChanged);
}
let actual = readback
.sha256(partition, size)
.map_err(|e| FlashError::Readback(e.to_string()))?;
if actual != expected {
return Err(FlashError::ReadbackMismatch);
}
Ok(WriteReceipt {
partition: partition.name.clone(),
backup,
image_sha256: expected,
})
}
#[cfg(test)]
mod tests {
use super::*;
use alkane_artifacts::{verify_file, ArtifactRecord};
use std::path::PathBuf;
const SHA: &str = "bf7d458495ed067341c7148cd3d30e6d383a2113b2cfb37de12959e057a52528";
const IMAGE: &[u8] = b"PK\x03\x04payload";
struct MockWriter {
serial: bool,
recovery: bool,
backup_bytes: u64,
max_read: Option<u64>,
writes: usize,
contents: Vec<u8>,
mutate_source_on_write: Option<PathBuf>,
}
impl Writer for MockWriter {
type Error = &'static str;
fn channel_id(&self) -> &str {
"ssh"
}
fn serial_console_attached(&mut self) -> Result<bool, Self::Error> {
Ok(self.serial)
}
fn recovery_image_ready(&mut self, _: &PartitionSpec) -> Result<bool, Self::Error> {
Ok(self.recovery)
}
fn backup(&mut self, _: &PartitionSpec) -> Result<BackupEvidence, Self::Error> {
Ok(BackupEvidence {
location: "recovery/partition.img".to_owned(),
bytes: self.backup_bytes,
sha256: [1; 32],
})
}
fn write(
&mut self,
_: &PartitionSpec,
image: &mut dyn Read,
_: u64,
) -> Result<(), Self::Error> {
self.writes += 1;
if let Some(path) = &self.mutate_source_on_write {
std::fs::write(path, b"PK\x03\x04changed").map_err(|_| "mutation failed")?;
}
if let Some(limit) = self.max_read {
image
.take(limit)
.read_to_end(&mut self.contents)
.map_err(|_| "read failed")?;
} else {
image
.read_to_end(&mut self.contents)
.map_err(|_| "read failed")?;
}
Ok(())
}
}
struct MockReadback {
channel: &'static str,
digest: [u8; 32],
}
impl IndependentReadback for MockReadback {
type Error = &'static str;
fn channel_id(&self) -> &str {
self.channel
}
fn sha256(&mut self, _: &PartitionSpec, _: u64) -> Result<[u8; 32], Self::Error> {
Ok(self.digest)
}
}
fn artifact(suffix: &str) -> (PathBuf, VerifiedArtifact) {
let path =
std::env::temp_dir().join(format!("alkane-flash-test-{}-{suffix}", std::process::id()));
std::fs::write(&path, IMAGE).unwrap();
let record = ArtifactRecord {
sha256: SHA.to_owned(),
size_bytes: IMAGE.len() as u64,
path: PathBuf::from("fixture.zip"),
family: "test".to_owned(),
format: "update-zip".to_owned(),
applicability: "test".to_owned(),
};
let verified = verify_file(&path, &record).unwrap();
(path, verified)
}
fn writer() -> MockWriter {
MockWriter {
serial: true,
recovery: true,
backup_bytes: 4096,
max_read: None,
writes: 0,
contents: Vec::new(),
mutate_source_on_write: None,
}
}
fn partition() -> PartitionSpec {
PartitionSpec {
name: "rootfs".to_owned(),
capacity_bytes: 4096,
secure: false,
boot_critical: true,
}
}
#[test]
fn refuses_secure_and_unrecoverable_writes_before_device_mutation() {
let (path, mut image) = artifact("refusals");
let mut target = partition();
let mut writer = writer();
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
target.secure = true;
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::SecurePartition)
));
target.secure = false;
target.capacity_bytes = 1;
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::ImageTooLarge)
));
target.capacity_bytes = 4096;
writer.serial = false;
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::SerialRequired)
));
writer.serial = true;
writer.recovery = false;
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::RecoveryRequired)
));
writer.recovery = true;
writer.backup_bytes = 1;
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::BackupIncomplete)
));
assert_eq!(writer.writes, 0);
std::fs::remove_file(path).unwrap();
}
#[test]
fn requires_independent_matching_readback() {
let (path, mut image) = artifact("readback");
let target = partition();
let mut writer = writer();
let mut readback = MockReadback {
channel: "ssh",
digest: [0; 32],
};
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::SameChannel)
));
assert_eq!(writer.writes, 0);
readback.channel = "serial";
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::ReadbackMismatch)
));
assert_eq!(writer.writes, 1);
assert_eq!(writer.contents, IMAGE);
writer.contents.clear();
readback.digest = digest_bytes(SHA).unwrap();
let receipt = write_verified(&target, &mut image, &mut writer, &mut readback).unwrap();
assert_eq!(receipt.image_sha256, readback.digest);
assert_eq!(receipt.backup.bytes, 4096);
assert_eq!(writer.writes, 2);
assert_eq!(writer.contents, IMAGE);
std::fs::remove_file(path).unwrap();
}
#[test]
fn refuses_changed_or_partially_consumed_artifacts() {
let (path, mut image) = artifact("changed");
let target = partition();
let mut writer = writer();
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
std::fs::write(&path, b"PK\x03\x04changed").unwrap();
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::ArtifactChanged)
));
assert_eq!(writer.writes, 0);
std::fs::write(&path, IMAGE).unwrap();
writer.max_read = Some(4);
assert!(matches!(
write_verified(&target, &mut image, &mut writer, &mut readback),
Err(FlashError::IncompleteWrite)
));
assert_eq!(writer.writes, 1);
std::fs::remove_file(path).unwrap();
}
#[test]
fn writes_verified_snapshot_when_source_changes_during_transport() {
let (path, mut image) = artifact("mutated-during-write");
let mut writer = writer();
writer.mutate_source_on_write = Some(path.clone());
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
let receipt = write_verified(&partition(), &mut image, &mut writer, &mut readback).unwrap();
assert_eq!(receipt.image_sha256, digest_bytes(SHA).unwrap());
assert_eq!(writer.contents, IMAGE);
assert_eq!(std::fs::read(&path).unwrap(), b"PK\x03\x04changed");
std::fs::remove_file(path).unwrap();
}
}
+32
View File
@@ -2604,6 +2604,38 @@ mod tests {
assert!(per.as_millis() < 100, "cell rendering regressed: {per:?}");
}
/// Microbenchmark: component health scores and operator-facing diagnostics
/// recomputed when scan results refresh the table.
#[test]
#[ignore]
fn bench_health_diagnostics() {
use std::hint::black_box;
use std::time::Instant;
let rows = bench_fleet();
let iters = 1000u32;
let start = Instant::now();
let mut sink = 0usize;
for _ in 0..iters {
for row in &rows {
for facet in [
HealthFacet::Overall,
HealthFacet::Power,
HealthFacet::Fans,
HealthFacet::Boards,
] {
sink += black_box(row.health_score(facet)) as usize;
}
sink += row.health_summary().len();
sink += row.health_tooltips(4, 3).iter().map(String::len).sum::<usize>();
}
}
black_box(sink);
let per = start.elapsed() / iters;
println!("bench_health_diagnostics: {} rows = {:?}/refresh", rows.len(), per);
assert!(per.as_millis() < 20, "health diagnostics regressed: {per:?}/refresh");
}
#[test]
fn selection_survives_upsert() {
let mut rows = bench_fleet();
+34 -1
View File
@@ -58,7 +58,11 @@ pub fn firmware_family(raw: &str) -> (String, Option<String>) {
// Vendor prefixes asic-rs prepends on stock-firmware family strings, matched
// case-insensitively.
for vendor in ["AntMiner", "WhatsMiner"] {
if trimmed.len() > vendor.len() && trimmed[..vendor.len()].eq_ignore_ascii_case(vendor) {
if trimmed.len() > vendor.len()
&& trimmed
.get(..vendor.len())
.is_some_and(|prefix| prefix.eq_ignore_ascii_case(vendor))
{
let rest = trimmed[vendor.len()..].trim();
if !rest.is_empty() {
return (rest.to_string(), Some(vendor.to_string()));
@@ -477,6 +481,35 @@ mod tests {
assert_eq!(firmware_family("Braiins"), ("Braiins".to_string(), None));
// A bare vendor word with nothing after it is left as-is (not emptied).
assert_eq!(firmware_family("AntMiner"), ("AntMiner".to_string(), None));
// Firmware strings arrive from the network and may contain UTF-8 at
// the byte position used to check a vendor prefix.
let non_ascii = "AntMine\u{e9} Stock";
assert_eq!(firmware_family(non_ascii), (non_ascii.to_string(), None));
}
#[test]
#[ignore = "microbenchmark"]
fn bench_naming_transforms() {
let cases = [
("Antminer", "S19jPro", "AntMiner Stock", "Xilinx"),
("Antminer", "S21Pro", "VNish", "CVITek"),
("Whatsminer", "M30SPlusVE40", "WhatsMiner Stock", "H616"),
("Whatsminer", "M50SPlusPlusVK30", "Braiins", "H6"),
];
let iterations = 20_000;
let started = std::time::Instant::now();
for index in 0..iterations {
let (make, model, firmware, board) = cases[index % cases.len()];
let clean = clean_model(make, model);
std::hint::black_box(firmware_family(firmware));
std::hint::black_box(control_board_code(make, board, &clean));
std::hint::black_box(chip_type_for_model(make, model));
std::hint::black_box(clean);
}
let elapsed = started.elapsed();
let per = elapsed / iterations as u32;
println!("bench_naming_transforms: {per:?}/record");
assert!(elapsed < std::time::Duration::from_millis(500));
}
#[test]
+6 -6
View File
@@ -1,10 +1,10 @@
# UI Spec — primary view
# Primary view
Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
## Header (above the table)
## Header
- **KPI block, top left — 6 KPIs:**
- **KPI block, top left: 6 KPIs:**
1. Total miners
2. Hashing
3. Slow
@@ -31,7 +31,7 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
4. Cooling (fan)
5. Firmware
6. Pool worker account name
7. …then the remaining statistics in registry order.
7. Remaining statistics in registry order.
## Data sources
@@ -45,10 +45,10 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
ships with the board registry; missing band = excluded from Slow, counted
in Hashing).
## Implementation notes
## Implementation
- wxWidgets: the view is a `wxDataViewListCtrl`/`wxDataViewCtrl` (virtual
list — thousands of rows without materializing cells), checkbox column +
list for thousands of rows without materializing cells), checkbox column +
IP column fixed via attribute/serializer, drag reorder via `wxReorderable`
column events, sort via column header click events mapped to the model.
- Filter panel: per-column distinct-value checklist with text search,
+1 -1
View File
@@ -1,4 +1,4 @@
# ADR 0001: Recipes as data, interpreted by one engine
# ADR 0001: Recipe engine
Status: ACCEPTED
Date: 2026-09-14
+15 -29
View File
@@ -1,41 +1,27 @@
# ADR 0002: GUI bindings — wxWidgets shell in C++ + Rust core, spike to revisit
# ADR 0002: GUI bindings
Status: RESOLVED 2026-09-15 - the operator chose Option B (pure Rust via
wx-rs) with vendoring (ADR-0003). wx-rs 0.2.0 was extended via the patch
queue: Linux/GTK3 wx-config build path plus the widget bridge (panel,
sizers, static text, button, text ctrl, checkbox, checklistbox, dialog,
data view list ctrl, timer). The app ships this way; no C++ shell.
Date: 2026-09-14
Resolved: 2026-09-15
## Context
The toolkit must present a native cross-platform GUI (wxWidgets chosen).
Rust bindings to wxWidgets checked on crates.io 2026-09-14:
- `wxRust` 0.0.1-alpha — unmaintained since 2022.
- `wx-rs` 0.2.0 (2023, self-contained) — ~6k downloads, no 1.0.
Betting the GUI on alpha bindings risks weeks of binding-gap debugging
(paste-heavy widgets, worker threads + event loops, GTK/WinCocoa quirks).
The toolkit needs a native wxWidgets GUI. At the time of evaluation,
`wxRust` 0.0.1-alpha had seen no maintenance since 2022, and `wx-rs`
0.2.0 lacked widgets needed for the Toolkit.
## Decision
Default: **thin C++17 wxWidgets shell (`gui/`) + Rust core exposed over a
small stable C ABI** (cdylib from `alkane-core`, header generated with
cbindgen). The shell holds frames, lists, the install wizard, and event
glue only — no business logic, no safety logic. All invariants, engines,
and tests live in Rust where they are testable headlessly.
The operator chose a Rust GUI through a vendored, patched `wx-rs` 0.2.0.
The patch queue adds the Linux/GTK3 build path and bindings for panels,
sizers, controls, dialogs, data views, timers, and event dispatch. The
application uses this bridge; it has no separate C++ shell.
Gate: M0 runs a time-boxed `wx-rs` spike (window + list/tree + wizard flow
+ worker-thread progress + cancel on Linux and Windows). If the spike is
solid, flip to pure Rust; either way the decision is recorded before M3.
The original proposal was a small C++17 wxWidgets shell calling a Rust
core through a C ABI. The `wx-rs` spike met the GUI need, so that proposal
was not adopted.
## Consequences
- The repo builds two things: a Rust workspace and a small C++ app linked
against the core cdylib. CMake in `gui/`.
- Core API surface stays small and event-oriented (discover, identify,
plan, execute, cancel, progress events, log tail) — good FFI hygiene and
a natural match for the CLI too (D4).
- If wx-rs wins the spike, the C ABI is kept as an integration boundary for
scripted/HIL use anyway.
- Keep business logic and safety checks in testable Rust code.
- Carry wx-rs changes as numbered patches under `thirdparty/wx-rs/patches`.
- Recheck the bridge on Linux, Windows, and macOS packaging changes.
+2 -2
View File
@@ -1,4 +1,4 @@
# ADR 0003: Vendoring policy — pristine upstream archives + patch queue
# ADR 0003: Vendoring
Status: ACCEPTED
Date: 2026-09-15
@@ -42,7 +42,7 @@ thirdparty/
Rules:
1. Never edit a vendored pristine tree in place — every local change is a
1. Never edit a vendored pristine tree in place. Every local change is a
patch in `patches/`, applied by the build in numeric order. This makes
an upstream update: replace pristine archive, `git apply` surviving
patches, rebase the rest.
+1
View File
@@ -5,6 +5,7 @@
# scripts/build-wx-linux.sh to produce it).
set -e
REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
trap 'bash "$REPO/scripts/clean-old-builds.sh" || true' 0
WX_PREFIX="${1:-$HOME/.cache/wx-3.3.3-linux}"
if [ ! -x "$WX_PREFIX/bin/wx-config" ]; then
"$REPO/scripts/build-wx-linux.sh"
+15
View File
@@ -6,6 +6,21 @@ REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
SRC="$REPO/thirdparty/wxwidgets/wxWidgets-3.3.3"
BUILD="$HOME/.cache/wxbuild/wxWidgets-3.3.3"
PREFIX="$HOME/.cache/wx-3.3.3-linux"
cleanup_wx_build() {
python3 - "$BUILD" "$HOME/.cache/wxbuild" <<'PY'
from pathlib import Path
import shutil
import sys
build, parent = map(Path, sys.argv[1:])
if (build.name != "wxWidgets-3.3.3" or build.parent != parent
or build.is_symlink() or parent.is_symlink()):
raise SystemExit("refusing unsafe wxWidgets build cleanup path")
if build.is_dir():
shutil.rmtree(build)
PY
}
trap cleanup_wx_build 0
[ -d "$BUILD" ] || { mkdir -p "$HOME/.cache/wxbuild"; cp -r "$SRC" "$BUILD"; }
[ -d "$BUILD" ] || { echo "thirdparty wxWidgets tree missing"; exit 1; }
chmod +x "$BUILD/configure" "$BUILD/config.guess" "$BUILD/config.sub" "$BUILD/install-sh" 2>/dev/null || true
+9
View File
@@ -18,6 +18,15 @@
set -uo pipefail
TARGET="${CARGO_TARGET_DIR:-$HOME/.cache/alkane-tk-target}"
REPO="$(cd "$(dirname "$0")/.." && pwd)"
case "$(realpath -m "$TARGET")" in
"$HOME/.cache/alkane-tk-target"|"$REPO/target") ;;
*) echo "clean-old-builds: refusing unexpected target $TARGET" >&2; exit 1 ;;
esac
if [ -L "$TARGET" ]; then
echo "clean-old-builds: refusing symlink target $TARGET" >&2
exit 1
fi
if [ ! -d "$TARGET" ]; then
echo "clean-old-builds: no target dir at $TARGET (nothing to do)"
exit 0
+27 -17
View File
@@ -8,13 +8,13 @@
#
# Usage: scripts/ui-screenshot.sh [out.png] [--live] [binary]
set -u
REPO=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
REPO=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
WX_PREFIX="${WX_PREFIX:-$HOME/.cache/wx-3.3.3-linux}"
export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$WX_PREFIX/bin/wx-config}"
OUT="${1:-alkane-toolkit.png}"
LIVE=0; BIN=""
shift 2>/dev/null || true
[ "$#" -eq 0 ] || shift
for a in "$@"; do
case "$a" in
--live) LIVE=1 ;;
@@ -32,17 +32,31 @@ if [ -z "$BIN" ]; then
fi
[ -x "$BIN" ] || { echo "binary not found: $BIN" >&2; exit 3; }
DISP=":98"
FAKE_ENV="ALKANE_FAKE_SCAN=1"
[ "$LIVE" = "1" ] && FAKE_ENV=""
Xvfb "$DISP" -screen 0 1280x850x24 -nolisten tcp >/dev/null 2>&1 &
DISPLAY_FILE=$(mktemp)
XPID=""; APID=""; WARM=""
cleanup() {
[ -z "$APID" ] || kill "$APID" 2>/dev/null || true
[ -z "$WARM" ] || kill "$WARM" 2>/dev/null || true
[ -z "$XPID" ] || kill "$XPID" 2>/dev/null || true
rm -f "$DISPLAY_FILE"
}
trap cleanup EXIT
Xvfb -displayfd 3 -screen 0 1280x850x24 -nolisten tcp 3>"$DISPLAY_FILE" >/dev/null 2>&1 &
XPID=$!
sleep 1.2
for _ in {1..30}; do
[ -s "$DISPLAY_FILE" ] && break
kill -0 "$XPID" 2>/dev/null || { echo "Xvfb exited before startup" >&2; exit 3; }
sleep 0.1
done
[ -s "$DISPLAY_FILE" ] || { echo "Xvfb did not start" >&2; exit 3; }
DISP=":$(cat "$DISPLAY_FILE")"
# warm the font/GTK caches so the first window map is not stalled
DISPLAY="$DISP" xclock >/dev/null 2>&1 & WARM=$!; sleep 1.2; kill "$WARM" 2>/dev/null
# shellcheck disable=SC2086
DISPLAY="$DISP" GDK_BACKEND=x11 $FAKE_ENV "$BIN" >/dev/null 2>&1 &
if [ "$LIVE" = "1" ]; then
DISPLAY="$DISP" GDK_BACKEND=x11 "$BIN" >/dev/null 2>&1 &
else
DISPLAY="$DISP" GDK_BACKEND=x11 ALKANE_FAKE_SCAN=1 "$BIN" >/dev/null 2>&1 &
fi
APID=$!
WID=""; t=0
while [ "$t" -lt 25 ]; do
@@ -52,10 +66,6 @@ while [ "$t" -lt 25 ]; do
[ -n "$line" ] && { WID=$(echo "$line" | awk '{print $1}'); break; }
done
sleep 2 # let it paint and drain a scan tick
if [ -n "$WID" ]; then
DISPLAY="$DISP" import -window "$WID" "$OUT" && echo "wrote $OUT (window $WID, ${t}s)"
else
DISPLAY="$DISP" import -window root "$OUT"; echo "no app window; captured root -> $OUT" >&2
fi
kill "$APID" 2>/dev/null
kill "$XPID" 2>/dev/null
[ -n "$WID" ] || { echo "no app window mapped" >&2; exit 1; }
DISPLAY="$DISP" import -window "$WID" "$OUT" || exit 1
echo "wrote $OUT (window $WID, ${t}s)"