Add: per-hop and rdns for probe trace
This commit is contained in:
DaZuo0122
267
docs/requirement_docs_v0.3.md
Normal file
267
docs/requirement_docs_v0.3.md
Normal file
@@ -0,0 +1,267 @@
|
||||
Below are **repo-ready v0.3.0 docs**.
|
||||
They’re written to match your **current implemented feature set** (v0.2 mostly done: sys/ports/neigh/certs/geoip/probe/dns/http/tls/discover/diag/calc).
|
||||
They also respect your decision to **NOT include** in v0.3.0:
|
||||
|
||||
* shell completions / man pages
|
||||
* the “smart one-shot doctor” command
|
||||
* extra output ergonomics for automation
|
||||
|
||||
And they target the **real gaps / next upgrades** you still have: **HTTP/3**, deeper **HTTP timing**, **TLS extras**, richer **trace**, **ports conns**, better **cert baseline/diff**, and optionally **LLMNR/NBNS discovery** (currently missing).
|
||||
|
||||
---
|
||||
|
||||
## 1) `docs/RELEASE_v0.3.0.md`
|
||||
|
||||
```markdown
|
||||
# WTFnet v0.3.0 — Release Plan
|
||||
|
||||
Binary name in examples: `wtfn` (current CLI examples use this form).
|
||||
Project scope: Linux (Debian/Ubuntu) + Windows first-class.
|
||||
|
||||
## 0. Summary
|
||||
|
||||
v0.3.0 focuses on improving **diagnostic depth and fidelity** of existing commands rather than adding a "smart doctor" workflow.
|
||||
|
||||
Major upgrades in this release:
|
||||
- richer traceroute output and per-hop statistics
|
||||
- HTTP timing breakdown accuracy (connect/tls stages)
|
||||
- optional HTTP/3 support (best-effort)
|
||||
- TLS diagnostics upgrades (OCSP stapling indicator, richer certificate parsing)
|
||||
- ports connections view and summaries
|
||||
- improved cert baseline/diff for system roots
|
||||
- optional discovery expansion (LLMNR/NBNS)
|
||||
|
||||
---
|
||||
|
||||
## 1. Goals
|
||||
|
||||
### G1. Make existing outputs more trustworthy
|
||||
- Replace placeholder timing fields with real measured values where feasible.
|
||||
- Improve trace reliability and readability.
|
||||
|
||||
### G2. Expand diagnostics depth, not workflow complexity
|
||||
- Keep subcommands explicit (no `doctor`, no guided flow).
|
||||
- Focus on "give me evidence" tools.
|
||||
|
||||
### G3. Keep v0.2 compatibility
|
||||
- Add flags and fields in an additive way.
|
||||
- Keep default behavior safe and bounded.
|
||||
|
||||
---
|
||||
|
||||
## 2. Non-goals (explicitly out of scope)
|
||||
|
||||
- No `wtfn doctor ...` / one-shot diagnosis command (move to v0.4+).
|
||||
- No shell completion scripts or man page generation.
|
||||
- No new output modes like JSONL streaming / schema negotiation changes (stay stable).
|
||||
- No OS-native TLS verifier in v0.3.0 (optional future enhancement).
|
||||
|
||||
---
|
||||
|
||||
## 3. Feature scope
|
||||
|
||||
### 3.1 probe trace: richer output (MUST)
|
||||
Current: trace exists best-effort.
|
||||
Target improvements:
|
||||
- `--rdns`: reverse DNS lookup per hop (best-effort; cached; time-bounded)
|
||||
- `--per-hop <n>`: send N probes per hop (default 3) to compute:
|
||||
- avg/min/max RTT per hop
|
||||
- loss % per hop
|
||||
- `--icmp` and `--udp` modes remain best-effort; document privilege requirements
|
||||
- Keep `--geoip` integration: hop IP → Country/ASN
|
||||
|
||||
Acceptance:
|
||||
- output includes per-hop loss and stable hop formatting
|
||||
- JSON output contains hop arrays with RTT series
|
||||
|
||||
---
|
||||
|
||||
### 3.2 HTTP timing breakdown accuracy (MUST)
|
||||
Current: `dns_ms` + `ttfb_ms` exist, but connect/tls are placeholders.
|
||||
Target:
|
||||
- implement `connect_ms` and `tls_ms` (best-effort) for HTTP/1.1 and HTTP/2
|
||||
- keep total duration correct and stable
|
||||
- when measurement unavailable (library limitation), report:
|
||||
- `null` + add warning, never fake numbers
|
||||
|
||||
Acceptance:
|
||||
- `wtfn http head|get` JSON contains:
|
||||
- `dns_ms`, `connect_ms`, `tls_ms`, `ttfb_ms`, `total_ms`
|
||||
- on timeout / failure, partial timing must still be meaningful.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 HTTP/3 (optional feature flag) (SHOULD)
|
||||
Current: HTTP/3 not implemented.
|
||||
Target:
|
||||
- add `--http3` support behind Cargo feature `http3`
|
||||
- behavior:
|
||||
- `--http3-only`: fail if HTTP/3 cannot be used
|
||||
- `--http3`: try HTTP/3, fallback to HTTP/2 unless `--http3-only`
|
||||
- provide clear error classes:
|
||||
- UDP blocked, QUIC handshake timeout, TLS/ALPN mismatch, etc.
|
||||
|
||||
Acceptance:
|
||||
- builds without `http3` feature still work
|
||||
- with feature enabled, HTTP/3 works on at least one known compatible endpoint
|
||||
|
||||
---
|
||||
|
||||
### 3.4 TLS extras: OCSP + richer cert parsing (MUST)
|
||||
Current: `tls handshake/verify/cert/alpn` exists.
|
||||
Target:
|
||||
- show OCSP stapling presence (if exposed by library)
|
||||
- richer certificate parsing for leaf and intermediates:
|
||||
- SANs (DNS/IP)
|
||||
- key usage / extended key usage (best-effort)
|
||||
- signature algorithm (best-effort)
|
||||
- new flags:
|
||||
- `--show-extensions` (prints richer X.509 info)
|
||||
- `--ocsp` (show stapling info if present)
|
||||
|
||||
Acceptance:
|
||||
- TLS output includes richer leaf cert details when requested
|
||||
- `--show-chain` remains fast and bounded
|
||||
|
||||
---
|
||||
|
||||
### 3.5 ports conns: active connection view + summaries (SHOULD)
|
||||
Current: `ports listen/who`.
|
||||
Target:
|
||||
- add `wtfn ports conns`
|
||||
- show active TCP connections with:
|
||||
- local addr:port
|
||||
- remote addr:port
|
||||
- state (ESTABLISHED/TIME_WAIT/etc)
|
||||
- PID/process name (best-effort)
|
||||
- add summary mode:
|
||||
- `--top <n>` show top remote IPs by count
|
||||
- `--by-process` group by process
|
||||
|
||||
Acceptance:
|
||||
- works on Linux + Windows best-effort
|
||||
- never requires admin by default; if needed, return partial with warnings
|
||||
|
||||
---
|
||||
|
||||
### 3.6 cert roots: stronger baseline/diff (MUST)
|
||||
Current: cert roots listing exists; baseline/diff exists.
|
||||
Target improvements:
|
||||
- normalize matching key: SHA256 fingerprint
|
||||
- diff categories:
|
||||
- added / removed
|
||||
- changed validity (newly expired)
|
||||
- subject/issuer changes
|
||||
- add stable JSON schema for baseline files (include schema version)
|
||||
|
||||
Acceptance:
|
||||
- baseline diff is stable across platforms (best-effort fields allowed)
|
||||
- diff output is human-friendly and JSON-friendly
|
||||
|
||||
---
|
||||
|
||||
### 3.7 discover: LLMNR/NBNS (optional) (NICE)
|
||||
Current: mDNS + SSDP exist; LLMNR/NBNS missing.
|
||||
Target:
|
||||
- add `wtfn discover llmnr --duration 3s`
|
||||
- add `wtfn discover nbns --duration 3s`
|
||||
- bounded, low-noise, rate-limited
|
||||
|
||||
Acceptance:
|
||||
- best-effort implementation on Windows-first networks
|
||||
- if unsupported on OS, show "not supported" error with exit code 5 (partial)
|
||||
|
||||
---
|
||||
|
||||
## 4. Compatibility & behavior rules
|
||||
|
||||
- Command names must remain stable.
|
||||
- Existing flags must retain meaning.
|
||||
- JSON output fields are additive only.
|
||||
- Logging remains stderr-only; JSON output remains clean stdout.
|
||||
|
||||
---
|
||||
|
||||
## 5. Deliverables checklist
|
||||
|
||||
MUST:
|
||||
- trace richer output + per-hop loss stats
|
||||
- HTTP connect/tls timing best-effort with warnings when unknown
|
||||
- TLS extras: OCSP indicator + richer x509 parsing
|
||||
- ports conns basic implementation
|
||||
- cert baseline/diff improvements
|
||||
|
||||
SHOULD:
|
||||
- HTTP/3 behind feature flag
|
||||
|
||||
NICE:
|
||||
- LLMNR/NBNS discovery
|
||||
|
||||
---
|
||||
|
||||
## 6. Definition of Done (v0.3.0)
|
||||
|
||||
- v0.3.0 builds on Linux (Debian/Ubuntu) + Windows.
|
||||
- `wtfn probe trace` provides per-hop loss and optional rdns.
|
||||
- `wtfn http head|get` reports accurate timing breakdown where possible.
|
||||
- `wtfn tls ...` provides OCSP + SAN/extensions when requested.
|
||||
- `wtfn ports conns` works best-effort and produces useful output.
|
||||
- cert baseline/diff is stable and readable.
|
||||
- No doctor command, no completions, no new output modes.
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) `docs/WORK_ITEMS_v0.3.0.md` (engineering task list)
|
||||
|
||||
```markdown
|
||||
# WTFnet v0.3.0 — Work Items
|
||||
|
||||
This is a practical checklist to execute v0.3.0.
|
||||
|
||||
## 1) probe/trace upgrades
|
||||
- [ ] add `--per-hop <n>` and store RTT samples per hop
|
||||
- [ ] compute loss% per hop
|
||||
- [ ] add `--rdns` best-effort reverse lookup (cached + time-bounded)
|
||||
- [ ] improve hop formatting + JSON schema
|
||||
|
||||
## 2) http timing improvements
|
||||
- [ ] implement `connect_ms` and `tls_ms` timing
|
||||
- [ ] report `null` + warning when measurement unavailable
|
||||
- [ ] keep current `dns_ms` and `ttfb_ms`
|
||||
|
||||
## 3) optional HTTP/3
|
||||
- [ ] add `http3` cargo feature + deps
|
||||
- [ ] implement `--http3` / `--http3-only`
|
||||
- [ ] define error classification for QUIC failures
|
||||
|
||||
## 4) tls extras
|
||||
- [ ] add OCSP stapling presence indicator (if available)
|
||||
- [ ] parse SANs and key usage / EKU best-effort
|
||||
- [ ] add `--show-extensions` and `--ocsp` flags
|
||||
|
||||
## 5) ports conns
|
||||
- [ ] implement `wtfn ports conns`
|
||||
- [ ] add `--top <n>` and `--by-process`
|
||||
- [ ] best-effort PID mapping with warnings
|
||||
|
||||
## 6) cert baseline/diff improvements
|
||||
- [ ] baseline schema version
|
||||
- [ ] match by SHA256 fingerprint
|
||||
- [ ] diff categories: add/remove/expired/changed
|
||||
|
||||
## 7) optional LLMNR/NBNS
|
||||
- [ ] implement `discover llmnr`
|
||||
- [ ] implement `discover nbns`
|
||||
- [ ] bounded collection, low-noise
|
||||
|
||||
## 8) docs updates
|
||||
- [ ] update README roadmap
|
||||
- [ ] update COMMANDS.md with new flags/commands
|
||||
- [ ] add RELEASE_v0.3.0.md
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user