rusty-pv 0.1.0

Pipe viewer — a Rust port of Andrew Wood's `pv(1)` with progress bar, ETA, rate display, token-bucket rate limiting, IEC/SI unit math, SIGWINCH-aware terminal redraw, SIGUSR1 size refresh, multi-instance cursor coordination, and a typed library API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# rusty-pv — Design Notes

Authoritative spec/plan: [`specs/00007-pv-port/`](../../rusty/specs/00007-pv-port/) in the umbrella repo.

## Upstream Dependency Status

E003 (reusable `port-ci.yml` workflow) is not yet shipped in the umbrella repo at v0.1.0 time. Inline workflows (`ci.yml`, `release.yml`) are duplicated from `rusty-detox` (post-fix versions including the `taiki-e/install-action@v2` audit replacement and the `rustup target add --toolchain 1.85` cross-target fix) as a pragmatic-path solution. When E003 v1.0.0 lands, these files are replaced by thin callers pinned to that tag.

## Throttle Math (AD-005, HINT-001)

Per-iteration token-bucket throttle: after each `write_all`, compute `expected_bytes = (Instant::now() - start) * RATE`. If `bytes_done > expected_bytes`, sleep `(bytes_done - expected_bytes) / RATE` via `std::thread::sleep`. 10 ms minimum sleep floor; finer granularity is unreliable on Windows.

All timing uses `std::time::Instant` (monotonic) — never `SystemTime`. This is immune to wall-clock jumps (NTP, sleep/wake) and is the documented contract for `-L` rate limiting and `-t` elapsed display alike.

## EMA Smoothing (AD-006, FR-005, HINT-002)

`EMA_new = 0.3 · sample + 0.7 · EMA_old`. The α = 0.3 constant is **locked at v0.1.0** to preserve byte-equal Strict-mode compatibility with upstream's display cadence. The first non-zero sample seeds the EMA (no startup ramp).

Future revisions MAY expose α via an additive `PvBuilder::ema_alpha(f64)` method without a MAJOR semver bump — this would be a library-only escape hatch; the CLI surface remains locked.

## SemVer Bump Policy

- **MAJOR**: change the EMA α constant; change the default-mode display layout; remove/rename a public API symbol; change `Filter`/`PvError` variant payload; change Strict-mode byte-exact output format.
- **MINOR**: add a new `PvError` or `Progress` field (via `#[non_exhaustive]`); add a new public method on `PvBuilder`; add a new CLI flag; add EMA α configurability via additive library method.
- **PATCH**: bug fixes that do not alter documented behavior; performance improvements; doc-only changes.

## Build / Feature Matrix

| Feature combination | Binary | Library deps |
|---|---|---|
| `default = ["cli"]` | `rusty-pv` | clap, clap_complete, anyhow, crossterm, signal-hook (Unix), fd-lock |
| `default-features = false` | none | thiserror only |

Verified by `tests/library_api.rs::default_features_off_dep_tree`.