libfreemkv/docs/mux-disc.md

src/mux/disc.rs — internal notes

Overflow rationale for internal (non-pub) items in src/mux/disc.rs, relocated here by the comment-guard so the in-file comment can stay short. Each section is pointed to by a one-line // See docs/mux-disc.md — <topic> comment at the corresponding call site.

commit_read

Commits a SUCCESSFUL read_sectors into the read buffer and advances the extent cursor. got is the byte count the source reported (already clamped to bytes, the full span requested for sectors).

The full case (got == bytes) is the only one every in-tree SectorSource produces — they are all full-or-error — and it behaves exactly as before.

A SHORT read (got < bytes) used to be handled inconsistently: the returned count was trusted for buf_valid, but current_offset still advanced by the full requested sectors. The undelivered tail therefore vanished from the muxed title with no error, no SectorSkipped event and no lost_bytes — a silent hole, indistinguishable from clean output, in a single-pass path that has no later pass to recover it. It is handled here rather than trusted away because invisible data loss is the one outcome this stream must never produce.

The tail is NOT re-read from a smaller offset: current_offset must stay on an AACS unit boundary (unit_align), and resuming mid-unit desyncs the decrypt of everything after it — the same reason the failed-unit skip branch below advances by the whole unit. So the gap is either

• a hard [crate::error::Error::DiscRead] (E6000) when the caller has NOT opted into holes, or
• zero-filled and ACCOUNTED under skip_errors, identically to a failed unit: the stale buffer tail is cleared, errors / lost_bytes are charged, and a SectorSkipped event is emitted.

a_long_run_of_empty_extents_does_not_recurse_per_extent

Nothing filters sector_count == 0 out of a UDF/MPLS extent list, so a malformed disc can declare a long run of empty extents. fill_extents used to skip each one with a self-recursive call, costing a stack frame apiece; Rust does not guarantee tail-call elimination, so a few thousand of them overflowed the stack. A stack overflow aborts the process — it is not catchable and takes the whole autorip service down — where the iterative form just walks off the end and reports EOF.

Run on a deliberately small stack so the frame cost is unmissable: the recursive version dies here, the loop finishes in microseconds.

bad_sector_keeps_its_identity_across_the_prefetch_channel

REGRESSION (round-4 audit): an ordinary MEDIUM ERROR bad sector must keep its identity when it crosses the prefetch producer channel — the same DiscRead with its SCSI status, NOT a transport failure.

PrefetchedSectorSource::read_sectors re-wrapped every error that crossed the channel as Error::IoError, and is_scsi_transport_failure matches IoError (the wedged-USB-bridge arm). So a bad sector reached fill_extents looking like a dead bus and aborted the pass with a fabricated status 0xFF — the exact inverse of what that short-circuit exists for, and it told the user to power-cycle a healthy drive.

Asserted on the source, not on a fill_extents skip: the producer thread exits for good after sending an error, so nothing downstream of it can genuinely recover the rest of the title (see dead_prefetch_producer_does_not_silently_zero_fill_the_title). An assertion that the pass continues could only ever have been satisfied by fabricated zeros.

dead_prefetch_producer_does_not_silently_zero_fill_the_title

The prefetch producer thread terminates PERMANENTLY on its first read error, so once one bad sector has crossed the channel the source can never deliver another byte. Driving fill_extents to exhaustion after that must NOT look like a completed pass: every remaining sector would be fabricated zeros, and DATA LOSS MUST NEVER LOOK LIKE SUCCESS.

The expectation is the product rule, not the code: a source that is permanently out of data must report that, not answer Ok(0) forever — which commit_read legitimately reads as an ordinary short read and zero-fills.

errors_reports_frames_the_resync_gate_dropped_after_the_gap_resolves

Frames the B1 resync gate discards must reach errors(), including after the gap RESOLVES.

ResyncGate::dropped is zeroed the moment a keyframe disarms the gate, and the only EOF warning fires for gates STILL armed — so a mid-title gap that resolves left no trace anywhere. That is the common case: most gaps do resolve. A rip with several concealed gaps reported 0 errors and 0 lost bytes while whole GOPs were discarded.

This asserts the accessor, not the gate's own counter, because errors() is the only channel through which a caller learns anything went wrong.