libfreemkv/docs/session.md

session.rs — rationale and design notes

Moved here from doc comments in src/session.rs to stay under the comment-guard's per-item prose cap. See the pointers in that file for which section applies to which item.

Module overview

Lifecycle is intentionally SPLIT — open does transport mechanics only, identify / scan are separate — so a consumer can fetch a poster off a fast identify and update its UI before committing to a full scan.

libfreemkv resolves no keys and reads no keydb: the consumer builds the host credentials / key-source layer (from freemkv_keysources) and hands them in via KeySpec; the session merely forwards them into ScanOptions at scan time. No cert derivation happens here.

resolve_keys_for

Steps, identical to what the consumers did inline:

1. Take the disc's public AACS inputs (Disc::inputs); a non-AACS disc has none, so this is a no-op returning an empty trace and no fetch.
2. Sample up to MIN_SAMPLE_UNITS encrypted content units from the largest title via reader (read_encrypted_units) so a candidate key is validated against real ciphertext. Skipped (no wasted read) when the factory yields no sources — resolution is then a guaranteed miss anyway.
3. Run the ordered sources first-valid-wins (resolve_and_apply_traced), which banks the winning unit keys onto disc's AACS state.
4. Build the read-time KeyFetch from the disc's inputs (its per-call samples are swapped in by the closure) using the same source factory.

The reader is whatever the disc lives behind — a live Drive or a file-backed SectorSource from scan_iso; both implement SectorSource.

DiscSession::into_drive

Error::DeviceNotReady is returned when the drive is no longer held — the public stage_drive_as_reader moves it into the reader slot, and calling this twice moves it out, so an empty slot is reachable through ordinary use rather than being a caller error. A library must not panic from public API, and a precondition that normal flow violates is a trap rather than a contract.

DiscSession::from_parts_for_test

Test-only constructor: build a session over an injected reader plus an already-scanned disc without opening a live Drive. DiscSession::open needs real hardware, so this is the only way to exercise the MuxInput::Session mux arm (take_reader → resolve_inline_base_map → DiscStream → with_key_map) and resolve_keys's title-sampling branch against a synthetic reader.

The drive slot stays None (a MuxInput::Session mux never touches it — it reads through the staged reader); device carries a sentinel path so the driver's missing-reader error still has a name.

disc is an Option so a test can construct a session that has not been scanned (None) to exercise the resolve_keys "called before scan" guard.

scan_iso

This is the file-backed counterpart to DiscSession::scan: it is the one place that opens a FileSectorSource, reads its capacity, and runs Disc::scan_image, so consumers (CLI, autorip) stop hand-rolling that triple and stop constructing the low-level reader themselves. No SCSI, no handshake, no key resolution — AACS resolution during the scan uses only whatever opts already carries (mirroring how Disc::scan_image forwards ScanOptions).

The returned reader is a fresh handle positioned at the start of the image; callers that need to sample ciphertext (key resolution) or feed a mux can reuse it directly rather than re-opening the file. Disc::scan_image reads only through the same reader, and all reads are LBA-addressed, so the handle is fully reusable afterward.

scan_dir

The extra step over scan_iso is the encryption verdict. Disc::scan_with decides encrypted structurally, from the presence of an /AACS or /BDMV/AACS directory (see disc::aacs_dir_present). For the common case — a typical disc backup, which strips AACS/ — that already gives the right answer, and DecryptKeys::None is a pass-through. But a folder copied verbatim from a decrypted disc keeps AACS/, and the tree shape then claims encryption over content that is already in the clear: the rip would fail asking for a key it does not need.

So for a folder, tree shape is not the evidence — content is. Several aligned units at the largest title's start are sampled and judged by aacs_unit_needs_decrypt, the same authority the mux read path uses:

• none need decryption → the folder is decrypted; encrypted is forced false and the reason is logged.
• any unit does → the folder is a raw encrypted copy, which dir:// does not support; Error::DirImageEncrypted.

This lives here and not in Disc::scan_image, which is shared with the ISO and drive paths: an ISO that carries AACS/ and clear content is a different situation (it may be mid-decrypt, or --raw output), and the verdict must not change underneath those callers.

apply_folder_encryption_verdict

Shared by scan_dir and by the dir:// PES input path in mux::resolve. It lives in one place because the two disagreed: a folder that ripped through scan_dir failed through input(), which is the exact failure this probe was written to prevent, reachable by the other door.