github-mirrors/netris-nestri
1
0
Fork 0
mirror of https://github.com/nestriness/nestri.git synced 2026-09-19 17:25:19 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(nesdoctor): a host readiness checker that measures instead of asking (#310)

Browse Source 
The first executable form of our host requirements. Until now a machine
was qualified by a human reading a table of hard requirements — and a
requirement that nothing can check is one that is silently optional.

It also replaces a form. Everything we wanted from a prospective host is
measurable, and most of it **cannot be answered honestly by a human
anyway**: almost nobody knows their real upstream, and essentially
nobody has ever seen their own bufferbloat figure. What's left for the
questions is only what a machine cannot know — intent, and what someone
already pays.

## What it does

```
nesdoctor
```

- **Checks every hard requirement**: `/dev/kvm`, an AMD or Intel GPU
with a DRM render node, `VK_KHR_video_encode_queue` plus a codec,
`virglrenderer`, the two stores, the `io` cgroup controller,
`virtiofsd`. Pass / fail / **unknown**, and unknown is never collapsed
into fail — a machine we could not ask is not a machine that failed, and
losing a capable host to a missing `lspci` is the failure mode that
matters.
- **Measures upstream and, the point of the whole thing, added latency
under load.** Grade bands come from the frame budget rather than
convention: the network allowance is ~40 ms because render, encode,
decode, display and jitter buffer have already spent ~58 ms.
- **Reads Steam, only with an explicit yes**, for library size and shape
plus an hour-of-day histogram of launches — one sample per title, which
is a real distribution obtained without asking anybody anything.
- **Asks at most five questions**, branched on what was found, all
skippable.

## No server

Nothing is uploaded and no telemetry endpoint exists. The network test
talks to Cloudflare's public speed-test sink and to `1.1.1.1`, neither
of which is ours. The output is a line on the terminal that the person
may choose to paste.

The shareable line carries **no hostname, IP, username, game title or
path** — a size band rather than a size, hours rather than dates. The
long version, which does include titles and paths, stays in a local JSON
file the person is told the path of.

That is a property of the design and not a promise about our intentions:
there is nothing to switch on later.

```
nesdoctor 0.1.0 | linux/x86_64 | gpu=AMD Barcelo | cpu=12t ram=13G |
kvm=y venc=y zfs=n boxfs=n io=y | up=28Mbps rtt=179ms bloat=+19ms grade=B |
disk=91G | edge=KE/JNB | steam=1 titles/<100G | plays=20-03h n=74 |
role=- share=- pays=- | HOST-READY-LOCAL
```

## Five bugs found by running it, every one of which would have produced
wrong data

- **`vulkaninfo --summary` lists ZERO `VK_KHR_video` entries** where
full `vulkaninfo` lists five on the same machine. Preferring the summary
reported "not advertised" on a card that advertises it — a false
negative on the check most likely to disqualify a host.
- **btrfs subvolumes counted as separate disks**: `/`, `/home` and
`/srv` each reporting 91 GiB of one 91 GiB device. Now deduped by
backing device, which the two-stores check needs anyway since it wants
*separate devices*.
- **Proton and the Steam Linux Runtimes are installed like games and are
not games.** Five of eight entries on the test machine, so the title
count was 5× too high and the library-shape question was corrupted.
- **`--quiet` printed the whole questionnaire** before its summary line,
breaking the one thing `--quiet` promises. Prompts are now skipped when
output is quiet or stdin is not a terminal — and a pipe is explicitly
*not* treated as consent to read a Steam library, unlike `--yes`.
- Boot history was reporting `13.2 h/day` off **two days** of history.
Under a three-day span it now reports the span and no rate.

## One finding, now encoded as a verdict

The development connection measures **179 ms idle RTT, served from
Johannesburg**. That machine passes every other check and cannot host
for a European player, because it is distance and no upgrade shortens
it.

`HOST-READY-LOCAL` exists for exactly that case, and the wording is
deliberate:

> Every requirement passes and your uplink queues cleanly. But the idle
round trip to the nearest major network is already most of the latency
budget, and that is distance rather than a fault: no upgrade shortens
it. So this machine is a good host for people on your side of the world
and cannot be one for anybody else. **If you are somewhere without a
cloud gaming edge, that is not a consolation prize — it is the only way
anyone there gets a playable stream.**

## CI

- **`ci.yml` gains a `nesdoctor` job** — fmt, `clippy -D warnings`,
test, one real run. Scoped to this member deliberately: the rest of the
Rust half has never been under CI, so `--workspace` would turn every PR
red for unrelated reasons. Widen it one member at a time.
- **`release-nesdoctor.yml`** builds four targets on tag `nesdoctor-v*`
— x86_64 linux-musl, x86_64 windows-msvc, aarch64 and x86_64 macOS —
with `SHA256SUMS`. musl rather than glibc so one Linux binary runs on
every distro.

The step that justifies the workflow **runs the binary it just built,
network included**. `ring` under rustls resolves root certificates
through the host trust store, so a static musl build can compile cleanly
and then fail TLS on the machine it ships to — breaking the network
test, silently, and only for other people. The step fails the build if
the summary line comes back `net=unmeasured`.

## Dependencies

Four: `anyhow`, `clap`, `serde`, `ureq`. The VDF parser, every platform
probe and the text wrapping are in-tree. A binary handed to strangers
has a dependency tree that is part of its interface, so anything that
could be done with `std` is.

4 MB release binary.

## What it deliberately does not claim

- **A pass is not a promise.** Every check is a *necessary* condition,
and nothing here runs under load — a machine that passes can still fail
on block I/O.
- **The encode extension being advertised is not proof the path works.**
We have had a correct extension list over a broken path before, so that
row says so.
- **Whether `libvirglrenderer` carries the native-context patches cannot
be determined from outside**, so that row reports presence only and
stays `unknown` rather than `pass`.










<!-- greptile_comment -->

<h3>Greptile Summary</h3>

The PR adds the nesdoctor host-readiness executable, local Steam
analysis, network measurement, installers, CI validation, and
multi-platform release packaging. Two attempted correctness fixes remain
incomplete:
- physical disk deduplication does not resolve common device-mapper
source names before comparing backing devices
- unknown historical Steam appids can still be counted as game launches
without passing runtime filtering

<h3>Confidence Score: 3/5</h3>

The PR is not yet safe to merge because shared LVM-backed stores can be
reported as physically independent and unknown Steam tools can still be
reported as game launches.

The new disk resolver fails open for common device-mapper names,
preserving a false host-readiness verdict, while Steam history still
counts absent appids without determining whether they are games or
runtime tools.

**Files Needing Attention:** apps/nesdoctor/src/sys.rs,
apps/nesdoctor/src/hostreq.rs, apps/nesdoctor/src/steam.rs

<h3>Important Files Changed</h3>




| Filename | Overview |
|----------|----------|
| apps/nesdoctor/src/sys.rs | Adds system and disk discovery, but
unresolved device-mapper names undermine physical-backing comparisons. |
| apps/nesdoctor/src/hostreq.rs | Implements host requirement verdicts
and uses physical-device sets that can falsely classify shared LVM
backing as independent. |
| apps/nesdoctor/src/steam.rs | Adds manifest and launch-history
analysis, but unknown appids bypass runtime classification and
contaminate launch metrics. |
| apps/nesdoctor/src/net.rs | Adds bounded upload-based upstream and
bufferbloat measurement; the previously reported unbounded request path
is addressed. |
| .github/workflows/release-nesdoctor.yml | Builds, smoke-tests,
packages, checksums, and publishes the four release targets. |
| .github/workflows/ci.yml | Adds focused formatting, linting, testing,
and offline execution checks for nesdoctor. |


<h3>Flowchart</h3>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Run[nesdoctor] --> Host[Host requirement probes]
  Run --> Net[Upload and latency measurement]
  Run --> Consent{Steam consent}
  Consent -->|yes| Steam[Installed manifests and LastPlayed records]
  Host --> Physical[Resolve filesystem sources to physical devices]
  Physical --> Verdict[Host readiness verdict]
  Net --> Report[Detailed JSON and shareable summary]
  Steam --> Report
  Verdict --> Report
```

<details><summary>Prompt To Fix All With AI</summary>

`````markdown
### Issue 1
apps/nesdoctor/src/sys.rs:369-374
**Mapper devices remain unresolved**

When root and box-store filesystems are separate LVM or dm-crypt mappings on the same physical disk, `df` supplies `/dev/mapper/...` names that do not exist under `/sys/class/block`. This branch returns those unrelated logical names unchanged, so the overlap check passes stores that still share one physical I/O queue.

### Issue 2
apps/nesdoctor/src/steam.rs:247-250
**Unknown appids bypass runtime filtering**

If `localconfig.vdf` retains `LastPlayed` data for an uninstalled Proton build, Steam runtime, or other non-game tool, its appid is absent from the installed-manifest map and this branch treats it as an uninstalled game. The tool activity then changes the launch histogram, peak window, and shareable `n` value.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
`````

</details>

<sub>Reviews (5): Last reviewed commit: ["fix(nesdoctor): three valid P1
findings
..."](7afc8929a6)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=59231233)</sub>

> Greptile also left **2 inline comments** on this PR.

<!-- /greptile_comment -->
This commit is contained in:
Wanjohi
2026-09-02 12:52:47 +03:00
committed by GitHub
parent 1c24a6e684
commit 79f1732a14
17 changed files with 3773 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

429
apps/nesdoctor/src/main.rs Normal file
View File

@@ -0,0 +1,429 @@
//! nesdoctor — is this machine any good, as a Nestri host or as a client?
//!
//! # What it is
//!
//! The first executable form of our host requirements. Until now a host was
//! qualified by a human reading a table, and a requirement nothing can check is
//! one that is silently optional. It is also the qualification anyone offering a
//! machine has to pass — and the check that decides it is loaded latency, not
//! throughput.
//!
//! # Usage
//!
//! ```text
//! nesdoctor [OPTIONS]
//!
//! --no-net Skip the network test (it uploads ~100 MB)
//! --no-steam Never look at Steam, and do not ask
//! --yes Accept the prompts; still prints, still saves nothing remote
//! --json <PATH> Where to write the full report [default: ./nesdoctor.json]
//! --quiet Only the summary line, for scripting
//! ```
//!
//! # What it does not do
//!
//! **It has no server.** Nothing is uploaded, no telemetry endpoint exists, and
//! there is no build of this program that reports home — the network test talks
//! to Cloudflare's public speed-test sink and to `1.1.1.1`, neither of which is
//! ours. The output is a line on your terminal. If you want us to have it, you
//! paste it somewhere; if you do not, we never had it.
//!
//! That is a design decision and not a promise about our intentions: there is
//! nothing to trust, because there is nothing to switch on later.
//!
//! # Why anyone would run it
//!
//! Because of one number almost nobody has ever seen: how much latency their
//! own connection adds when it is busy. Throughput is the figure everybody
//! knows and it is the wrong one — a 500 Mbps uplink that queues for 300 ms
//! under load cannot carry an interactive stream, and a 25 Mbps one with
//! `fq_codel` can.
mod ask;
mod hostreq;
mod net;
mod report;
mod steam;
mod sys;
mod vdf;
use std::io::{IsTerminal, Write};
use std::path::PathBuf;
use clap::Parser;
#[derive(Parser, Debug)]
#[command(
name = "nesdoctor",
about = "Is this machine any good, as a Nestri host or as a client?",
version
)]
struct Args {
/// Skip the network test. It uploads roughly 100 MB to a public speed-test
/// sink; on a metered connection that is worth knowing about up front.
#[arg(long)]
no_net: bool,
/// Never read Steam, and do not ask about it.
#[arg(long)]
no_steam: bool,
/// Answer the prompts affirmatively and take the defaults. Intended for a
/// second run, not a first one — the questions are the point.
#[arg(long)]
yes: bool,
/// Where to write the full report.
#[arg(long, default_value = "nesdoctor.json")]
json: PathBuf,
/// Print only the summary line.
#[arg(long)]
quiet: bool,
/// Where the submit link points. Override to test against a local worker.
#[arg(long, default_value = "https://doctor.nestri.io")]
submit_url: String,
/// Do not offer to open a browser; just print the link.
#[arg(long)]
no_open: bool,
}
fn main() {
let args = Args::parse();
if !args.quiet {
banner();
}
// --- what the machine is ---------------------------------------------
if !args.quiet {
net::tick(" reading hardware…");
}
let sys = sys::probe();
if !args.quiet {
println!(" done");
print_sys(&sys);
}
// --- can it host ------------------------------------------------------
let host = hostreq::probe(&sys);
if !args.quiet {
report::print_checks(&host);
}
// --- the network ------------------------------------------------------
let netr = if args.no_net {
net::NetReport::unmeasured("skipped with --no-net")
} else {
if !args.quiet {
println!("\n\x1b[1mNetwork\x1b[0m");
println!(
"\x1b[2m About 20 seconds. This saturates your upload on purpose — that is the\x1b[0m"
);
println!(
"\x1b[2m only way to see the number that matters — so expect a video call to\x1b[0m"
);
println!("\x1b[2m stutter while it runs. Roughly 100 MB of upload.\x1b[0m");
net::tick(" measuring…");
}
let r = net::run();
if !args.quiet {
println!(" done");
print_net(&r);
}
r
};
let region = if args.no_net {
None
} else {
net::region_hint()
};
// --- the questions ----------------------------------------------------
let steam_present = !args.no_steam && steam::present();
let capable = sys.os == "linux"
&& sys
.gpus
.iter()
.any(|g| matches!(g.vendor.as_deref(), Some("AMD") | Some("Intel")));
// Do not ask questions that cannot be answered. `--quiet` promises a single
// parseable line, and a prompt written to stdout breaks that promise; a
// non-terminal stdin cannot answer at all, so prompting into it just prints
// the whole questionnaire and skips every item. Both cases used to print
// three questions and then "skipped" -- found by the CI smoke test, which
// is the only reason anything runs this way.
let interactive = !args.quiet && std::io::stdin().is_terminal();
let answers = if args.yes || !interactive {
ask::Answers {
// `--yes` is a deliberate consent; a pipe is not consent to read
// somebody's library.
steam_consent: args.yes && steam_present,
..Default::default()
}
} else {
ask::run(&ask::Ctx {
could_host: host.could_host,
capable,
is_linux: sys.os == "linux",
steam_present,
})
};
// --- Steam, only with a yes -------------------------------------------
let steamr = if answers.steam_consent {
let r = steam::read();
if !args.quiet {
print_steam(&r);
}
r
} else {
steam::SteamReport::default()
};
// --- verdict ----------------------------------------------------------
let v = report::verdict(&sys, &host, &netr);
if !args.quiet {
report::print_verdict(v, &netr);
}
let full = report::Full {
nesdoctor: report::VERSION,
sys: &sys,
host: &host,
net: &netr,
steam: &steamr,
answers: &answers,
verdict: v,
region_hint: region.clone(),
};
let line = report::summary_line(&full);
// --- the full report, locally -----------------------------------------
let wrote = serde_json::to_string_pretty(&full)
.ok()
.and_then(|j| std::fs::write(&args.json, j).ok().map(|_| ()))
.is_some();
if args.quiet {
println!("{line}");
return;
}
let url = report::submit_url(&args.submit_url, &full);
println!();
println!("\x1b[1m─── One keystroke and we are done ───────────────────────────────\x1b[0m");
println!();
println!("\x1b[2m Everything above goes to us through this link. It contains:\x1b[0m");
for item in report::submit_contents(&steamr, &answers) {
println!("\x1b[2m · {item}\x1b[0m");
}
println!();
println!("\x1b[2m {}\x1b[0m", args.submit_url);
println!();
let opened = if args.no_open || !interactive {
false
} else {
print!(
"\x1b[1;97;44m Press Enter to send it \x1b[0m\x1b[2m (or Ctrl-C to send nothing) \x1b[0m"
);
let _ = std::io::stdout().flush();
let mut s = String::new();
let _ = std::io::stdin().read_line(&mut s);
println!();
report::open_in_browser(&url)
};
if opened {
println!("\x1b[32m ✓ Opened in your browser. That is it — thank you.\x1b[0m");
println!(
"\x1b[2m If the page did not load, the link is below and it still works later.\x1b[0m"
);
} else {
println!("\x1b[1m Open this to send it:\x1b[0m");
}
println!();
println!("\x1b[4;36m{url}\x1b[0m");
println!();
// The clipboard line stays as the offline path: a headless host, a machine
// with no browser, or somebody who would rather paste into a channel than
// click a link we wrote.
let clip = report::to_clipboard(&line);
println!("\x1b[2m Prefer to paste it yourself? The short version:\x1b[0m");
println!();
println!(" {line}");
if let Some(tool) = clip {
println!("\x1b[2m (also on your clipboard, via {tool})\x1b[0m");
}
if wrote {
println!();
println!("\x1b[1m And if you feel like being properly helpful\x1b[0m");
println!(
"\x1b[2m {} has the long version — every check with its reason, the\x1b[0m",
args.json.display()
);
println!(
"\x1b[2m full latency series, and your installed titles with sizes and launch\x1b[0m"
);
println!(
"\x1b[2m times. It is more useful to us than anything above, because it is what\x1b[0m"
);
println!(
"\x1b[2m lets us size a real game library. Have a read and send it along if\x1b[0m"
);
println!("\x1b[2m nothing in there bothers you.\x1b[0m");
}
println!();
}
fn banner() {
println!();
println!("\x1b[1mnesdoctor {}\x1b[0m", report::VERSION);
println!("\x1b[2mChecks whether this machine can host a Nestri box, measures what your\x1b[0m");
println!("\x1b[2mconnection actually does under load, and asks at most five questions.\x1b[0m");
println!();
println!(
"\x1b[2mNothing is uploaded. There is no server to upload to — the output is a\x1b[0m"
);
println!("\x1b[2mline on your terminal that you may choose to paste somewhere.\x1b[0m");
println!();
}
fn print_sys(s: &sys::SysInfo) {
println!("\n\x1b[1mMachine\x1b[0m");
println!(
" {} {} · {}",
s.os,
s.arch,
s.release.clone().unwrap_or_else(|| "unknown".into())
);
if let Some(c) = &s.cpu_model {
println!(
" {c} · {} threads · {} RAM",
s.cpu_threads,
s.ram_gib.map_or("?".into(), |g| format!("{g:.0} GiB"))
);
}
for g in &s.gpus {
println!(
" {}{}",
g.name,
g.render_node
.as_ref()
.map(|r| format!(" · {r}"))
.unwrap_or_default()
);
}
for d in s.disks.iter().take(3) {
println!(
" {} · {} · {:.0} GiB free",
d.mount,
d.fs.clone().unwrap_or_else(|| "?".into()),
d.free_gib
);
}
match (s.powered_hours_per_day, s.powered_span_days) {
(Some(h), Some(days)) => println!(
" powered {h:.1} h/day, averaged over {days:.0} days of boot history\n \
\x1b[2m(measured, not asked — it counts powered rather than idle, so read it as \
'always on' vs 'evenings')\x1b[0m"
),
_ => println!(" \x1b[2mno boot history available, so hours-powered is unknown\x1b[0m"),
}
}
fn print_net(n: &net::NetReport) {
let f = |o: Option<f64>, unit: &str| {
o.map(|v| format!("{v:.0}{unit}"))
.unwrap_or_else(|| "—".into())
};
println!(" upstream {}", f(n.upstream_mbps, " Mbps"));
println!(" latency, idle {}", f(n.idle_rtt_ms, " ms"));
if n.idle_rtt_ms.is_some_and(|r| r > 60.0) {
println!(
" \x1b[2m That is the round trip to the *nearest* major network, so it is a\x1b[0m"
);
println!(" \x1b[2m floor on what any player sees. It is distance, not a fault.\x1b[0m");
}
println!(" latency, loaded {}", f(n.loaded_rtt_ms, " ms"));
println!(" latency, loaded p95 {}", f(n.loaded_rtt_p95_ms, " ms"));
match (n.bloat_ms, n.grade) {
(Some(b), Some(g)) => {
let colour = match g {
"A" => "32",
"B" => "32",
"C" => "33",
_ => "31",
};
println!(" \x1b[1madded under load \x1b[{colour}m+{b:.0} ms grade {g}\x1b[0m");
println!(
" \x1b[2m A/B is fine, C is marginal, F cannot carry an interactive stream.\x1b[0m"
);
println!(
" \x1b[2m The whole network allowance is about 40 ms, because render, encode,\x1b[0m"
);
println!(
" \x1b[2m decode, display and the jitter buffer have already spent ~58 ms.\x1b[0m"
);
}
_ => println!(" added under load —"),
}
}
fn print_steam(s: &steam::SteamReport) {
if !s.found {
return;
}
println!("\n\x1b[1mSteam\x1b[0m");
println!(
" {} titles installed · {:.0} GiB on disk",
s.titles,
steam::gib(s.bytes_on_disk)
);
for (name, bytes) in &s.largest {
println!(" {:>6.0} GiB {}", steam::gib(*bytes), name);
}
if s.profiles > 1 {
println!(
" \x1b[2m{} Steam profiles here — the hours below are the busiest one, not all of\x1b[0m",
s.profiles
);
println!(" \x1b[2mthem added together, which would be a histogram of nobody.\x1b[0m");
}
if s.launch_samples > 0 {
println!(
"\n When you launch games — {} launch records{}, local time:",
s.launch_samples,
if s.launches_uninstalled > 0 {
format!(
", {} of them games you no longer have installed",
s.launches_uninstalled
)
} else {
String::new()
}
);
println!(" {}", steam::sparkline(&s.launch_hours));
println!(" \x1b[2m0h 6h 12h 18h 23h\x1b[0m");
if let Some((a, b)) = s.peak_window {
println!(" Half of your launches fall between \x1b[1m{a:02}:00 and {b:02}:59\x1b[0m.");
let width = if b >= a { b - a + 1 } else { 24 - a + b + 1 };
if width <= 6 {
println!(
" \x1b[2mThat is a narrow window, which is what a peak looks like.\x1b[0m"
);
} else {
println!(" \x1b[2mThat is spread out — no strong peak.\x1b[0m");
}
}
}
let _ = std::io::stdout().flush();
}