mirror of
https://github.com/kuhyx/testsAndMisc.git
synced 2026-11-11 21:34:05 +01:00
Krzysztof kuhy Rudnicki
836f4ef2de
Diagnosing "Steam downloads are slow" kept pointing at the ISP because every averaged measurement showed a steady ~170 Mbps. Sampling at 1s instead of 5s showed that plateau does not exist: the link alternates between ~450 Mbps bursts and multi-second stalls. Effective rate is burst x duty_cycle, and only the second factor was wrong. steam-download-duty.sh reports those two factors separately, which is what the Steam UI cannot do. line-speed-probe.sh separates burst from sustained throughput, because a single stream tops out near 180 Mbps on this line and reads convincingly as ISP shaping when it is not — a many-connection swarm reaches 986 Mbps with zero retransmits. Arithmetic is extracted into pure helpers with main() behind a BASH_SOURCE guard so the bats suite can source them without starting a measurement. install.sh installs bats and links both scripts onto PATH. Note: no CI workflow runs .sh/.bats tests, including the four shell tests that predate this one, so the suite is manual-only for now.
50 lines
3.6 KiB
JSON
50 lines
3.6 KiB
JSON
{
|
|
"intent": "Add two reusable network diagnostic scripts that distinguish a slow link from an idle download client, so 'Steam is slow' can be answered with measurement instead of guesswork.",
|
|
"scope": [
|
|
"linux_configuration/scripts/diagnostics/ (new): steam-download-duty.sh, line-speed-probe.sh, install.sh",
|
|
"linux_configuration/tests/test_network_diagnostics.bats (new)",
|
|
"Non-goal: wiring shell tests into CI — no workflow runs .sh/.bats today, including the 4 pre-existing shell tests",
|
|
"Non-goal: changing any Steam or system configuration; these scripts only read counters"
|
|
],
|
|
"changes": [
|
|
"steam-download-duty.sh samples /sys/class/net rx_bytes at 1s and reports duty cycle, burst rate and effective average separately. 5s averaging smears bursts and stalls into a plateau that does not exist; 1s resolution is what exposed the real behaviour.",
|
|
"line-speed-probe.sh reports burst vs sustained across single and parallel streams. Sustained deliberately means the mean of the second half, discarding TCP slow start and any ISP burst allowance.",
|
|
"Arithmetic and classification extracted into pure helpers (bytes_to_mbps, duty_pct, mean_of, classify, sustained_of, max_of, verdict_for); main() is guarded by a BASH_SOURCE check so tests can source the helpers without starting a measurement.",
|
|
"install.sh installs the bats test dependency and links both scripts into ~/.local/bin, idempotently.",
|
|
"30 bats tests covering boundary values, empty input and divide-by-zero guards."
|
|
],
|
|
"verification": [
|
|
{
|
|
"command": "bats linux_configuration/tests/test_network_diagnostics.bats",
|
|
"result": "pass",
|
|
"evidence": "1..30, all ok. One assertion initially failed and was correct to fail: sustained_of 10 20 30 returns 25, not 30 (odd counts drop only the first sample). The expectation was fixed, not the behaviour, since 25 matches the implementation that produced every measurement in the investigation."
|
|
},
|
|
{
|
|
"command": "pre-commit run --files <the 4 new files>",
|
|
"result": "pass",
|
|
"evidence": "41 hooks Passed/Skipped including shellcheck and codespell; ai-evidence-contract required this artifact."
|
|
},
|
|
{
|
|
"command": "bash linux_configuration/scripts/diagnostics/install.sh",
|
|
"result": "pass",
|
|
"evidence": "Idempotent re-run: detected existing bats 1.13.0, refreshed both ~/.local/bin symlinks."
|
|
},
|
|
{
|
|
"command": "steam-download-duty.sh 8 (via the ~/.local/bin symlink, post-refactor)",
|
|
"result": "pass",
|
|
"evidence": "Ran end to end and reported 0% duty / 0 Mbps correctly, the download having completed."
|
|
}
|
|
],
|
|
"risks": [
|
|
"IFACE defaults to enp6s0; on a different NIC the scripts read a nonexistent /sys path and fail. Overridable via the IFACE environment variable.",
|
|
"Thresholds in classify() and verdict_for() (80% duty, 400/600/350 Mbps) are calibrated to this gigabit line and would need revisiting elsewhere.",
|
|
"line-speed-probe.sh pulls real ISOs to /dev/null and will consume bandwidth for its full duration if run carelessly.",
|
|
"The bats suite runs only when invoked manually; no CI workflow executes it."
|
|
],
|
|
"rollback": [
|
|
"git revert the commit, then rm ~/.local/bin/{line-speed-probe.sh,steam-download-duty.sh} — both are symlinks into the repo, so reverting alone leaves them dangling.",
|
|
"Optionally: sudo pacman -Rns bats if the framework is not wanted (it is a new dependency introduced by this change).",
|
|
"Validate after rollback: which steam-download-duty.sh returns nothing and no repo test references the diagnostics directory."
|
|
]
|
|
}
|