init

docs/TESTING.md

@@ -0,0 +1,200 @@
+# Testing
+
+## Offline
+
+Everything in `pstr-core` is offline and pure. That is deliberate: the filename
+parser, the config writer and the catalog migrations are exactly the things whose
+edge cases are painful to reproduce against a live share, so they are pinned by
+table-driven tests instead.
+
+```bash
+cargo test --workspace --locked
+cargo test -p pstr-core naming::            # just the parser
+```
+
+What is pinned today:
+
+- **`naming`** — the fansub, scene and cross conventions; dashes inside titles;
+  version suffixes; a bracketed resolution that must not read as a year; a word
+  starting with `s` that must not start a season; dotted titles vs. extensions;
+  and that an unrecognisable name still yields a usable title rather than being
+  dropped.
+- **`config`** — round trip, missing-is-`None`, **unparseable-is-an-error** (the
+  one that protects the share list from a read-modify-write wiping it), and no
+  temp file left behind.
+- **`catalog`** — schema version, refuse-to-open on a newer schema, share replace
+  semantics (drops removed rows, leaves other shares alone), and that **a recrawl
+  preserves watch state**.
+
+`pstr-stream` is offline too, and for the same reason: it runs against a
+`BlockSource` fake, so the caching, deduplication and read-ahead behaviour that
+is nearly impossible to provoke deliberately over a network is pinned exactly.
+
+- **`block`** — byte range → block mapping, including non-uniform sizes, a range
+  ending exactly on a boundary (which must not pull the next block), and splicing
+  into the right part of the output buffer.
+- **`ring`** — never exceeds its byte budget, evicts least-recently-*used*, a
+  containment check records no traffic and no recency, a block bigger than the
+  budget is not stored, reinserting does not double-count.
+- **`disk`** — round trip, a block disagreeing with its sidecar is rejected *and
+  removed*, a block with no sidecar is a miss, eviction deletes the files rather
+  than merely forgetting them, a reopened cache adopts the previous run's bytes,
+  and cache paths carry no names.
+- **`single_flight`** — N callers run the work once, a waiter sees the leader's
+  failure, a failed call leaves the key retryable, and a **cancelled** leader does
+  not wedge the key.
+- **`stream`** — reads across block boundaries, a seek fetches only the block it
+  lands in, a demand read joins an in-flight prefetch instead of refetching, a
+  failing prefetch never fails the read, **a seek cancels the read-ahead it
+  invalidates** while sequential playback cancels none, and streaming a file far
+  larger than the ring stays inside the budget.
+
+`pstr-player` is offline too, everywhere it can be. mpv itself needs a window and
+a codec, but nothing mpv's stream callbacks *decide* lives in the callbacks —
+they hand straight to `StreamCursor`, a plain safe type over a `BlockSource`
+fake, which is what the tests drive.
+
+- **`cursor`** — sequential reads walk the file and stop at EOF, a seek moves
+  where the next read starts, a read crossing a block boundary is allowed to come
+  up short but returns the right bytes, seeking exactly to EOF is allowed while
+  past it is an error, **mpv's post-open seekability probe to 0 succeeds** (fail
+  it and every seek bar is gone), and a cancelled stream fails its reads and
+  stays failed.
+- **`registry`** — a published stream is reachable through its URL, dropping the
+  handle revokes it, and **a token is never reused** after the stream behind it
+  is gone, so a stale URL cannot start playing whatever took the number over.
+  Only well-formed `pstr://` URLs parse.
+- **`player`** — every mpv end-file reason maps to something the UI can act on
+  (`Eof` means "next episode"; nothing else does), and an observed property
+  arriving in an unexpected format is *not* read as a position of zero.
+
+## Against a real share
+
+Needs a Proton Drive public link. Use a share you can afford to have indexed;
+nothing here writes, but the crawl reads every node's metadata.
+
+```bash
+cargo run -p pstr-cli -- add --name anime 'https://drive.proton.me/urls/TOKEN#fragment'
+cargo run -p pstr-cli -- add --name anime 'https://…' --custom-password   # prompts
+cargo run -p pstr-cli -- crawl
+cargo run -p pstr-cli -- list
+```
+
+Check: node count matches the folder, titles and episode numbers look right, and
+the crawl time is seconds rather than minutes (if it is minutes, the SDK's
+node-key cache is not doing its job).
+
+The reference run, against a real library: **354 nodes crawled, 310 playable, 22
+titles, ~25s**. Eleven files end up with no episode number and that is correct —
+they are films and OP/ED extras. Anything else unnumbered is a parser gap; add
+the filename to `naming`'s tests before fixing it.
+
+Useful for spotting gaps:
+
+```bash
+sqlite3 ~/.local/share/proton-stream/catalog.db \
+  "SELECT title, name FROM nodes WHERE is_folder=0 AND episode IS NULL;"
+```
+
+## Benchmarking playback, without a player
+
+`pstr bench` reads a catalogued file the way a demuxer would — 64 KiB at a time —
+and reports the three numbers that decide whether the app is usable: cold seek
+latency, sustained throughput, and peak resident memory.
+
+```bash
+cargo run -p pstr-cli -- bench --file Frieren --verify
+cargo run -p pstr-cli -- bench --file Frieren --readahead 0      # isolate read-ahead
+cargo run -p pstr-cli -- bench --file Frieren --disk-cache       # run twice
+```
+
+`--verify` cross-checks a mid-file read against the SDK's own `download_range`.
+Run it whenever anything in the block-mapping or caching path changes; it is the
+only check that catches bytes served from the wrong offset, which otherwise
+surfaces as video that decodes into garbage rather than as an error.
+
+Reference run, 761 MiB episode, 191 blocks, over a real public link:
+
+| | cold seek (worst) | sustained | peak resident |
+|---|---:|---:|---:|
+| read-ahead off | 572 ms | 7.2 MiB/s | 60 MiB |
+| read-ahead 6, no seek cancellation | **2895 ms** | 5.0 MiB/s | 128 MiB |
+| read-ahead 12, seek cancellation | 715 ms | 8.7 MiB/s | 128 MiB |
+| read-ahead 32 | 716 ms | 7.8 MiB/s | 128 MiB (evicting) |
+| warm disk cache | **14 ms** | 1039 MiB/s | 76 MiB |
+
+Two findings worth not rediscovering. Read-ahead left running from the position
+the viewer just left holds exactly the bandwidth the seek needs — 5x on
+worst-case latency. And a read-ahead window deeper than half the ring evicts its
+own blocks before the player reaches them, so throughput *falls*. Both are fixed
+in `pstr-stream::stream`; both are pinned by offline tests.
+
+Expect run-to-run spread of 15–20% on the throughput number. Treat a change under
+that as noise.
+
+Note that `bench`'s tuned read-ahead default (12) is **not** the right one for
+mpv, which brings its own — see `docs/BUGS.md` B8. A change that improves `bench`
+has not thereby improved playback; measure both.
+
+## Playing, with a player
+
+```bash
+cargo run --release -p pstr-cli -- play --file Frieren
+cargo run --release -p pstr-cli -- play --file Frieren --start 900       # cold mid-file seek
+cargo run --release -p pstr-cli -- play --file Frieren --disk-cache      # run twice
+cargo run --release -p pstr-cli -- play --file Frieren --headless --for-seconds 60
+```
+
+Use `--release`. A debug build is watchable but the numbers below are not
+reproducible from one.
+
+`--headless` decodes with no window and no sound, so the whole chain still runs
+somewhere there is no display; `--for-seconds` ends an unattended run without a
+window to close. Together they are the smoke test. Every run prints time to first
+frame, seek-resume latency, and what the block layer actually fetched.
+
+Reference run, same 761 MiB / 1560 s episode over a real public link, defaults:
+
+| | cold | warm disk cache |
+|---|---:|---:|
+| time to first frame | 2.3 s | **0.3 s** |
+| mid-file seek resumed in | 1.0–1.6 s | — |
+| blocks fetched for 38 s of playback | 16 (61 MiB) | **0** |
+| ring evictions | 0 | 0 |
+
+Sustained playback holds exactly realtime: 178 s of media in 180 s of wall clock,
+the 2 s deficit being the time to first frame, with no drift over the run. Check
+that: a deficit that *grows* is the block layer failing to keep up, and it is the
+one failure the smoke test can see but a short run cannot.
+
+`Cannot load libcuda.so.1` on stderr is mpv's `hwdec=auto-safe` probe declining a
+backend. Not an error.
+
+## SDK-side
+
+The streaming surface this app depends on is tested in `../proton-sdk-rs`:
+
+```bash
+cd ../proton-sdk-rs
+PROTON_TOTP_SECRET=... cargo test -p proton-drive-rs --test live_sharing \
+  -- --ignored --nocapture --test-threads=1
+```
+
+`a_visitor_can_seek_within_a_shared_multi_block_file` is the load-bearing one —
+it verifies that the `drive/unauth/` revision endpoint returns a usable `XAttr`,
+without which block boundaries cannot be placed and seeking is impossible.
+
+Live runs there must stay `--test-threads=1`: Proton throttles repeated logins
+and each fresh one burns a TOTP window.
+
+## Acceptance, once playback lands
+
+1. Add the share; the catalog populates with correct titles and seasons.
+2. Play a 1080p HEVC episode — first frame in a couple of seconds, not a full
+   download.
+3. Drag the seek bar to ~75%; playback resumes there within a block fetch.
+4. Close and reopen; the resume position is honoured.
+5. Leave it paused past the anonymous session's lifetime, then seek — the
+   session renews rather than erroring.
+6. Watch the same episode again; it comes from the disk block cache.
+7. Repeat on Windows with the bundled `libmpv-2.dll`.