pq/libfreemkv
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.0.0-rc.1

Browse Source 
CSS keyless decrypt (Stevenson), AACS 1.0/2.0/2.1, MPEG-2 DVD, multi-OS SCSI, multipass recovery, mux highway, audit hardening
This commit is contained in:
Matthew Jackson
2026-06-21 21:06:07 -07:00
parent e8bb6225ac
commit 5941c059c6
53 changed files with 7439 additions and 2340 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/disc/bluray.rs
+6 -4
View File
@@ -138,10 +138,12 @@ impl Disc {
_ => ColorSpace::Unknown,
},
secondary: s.secondary,
label: match s.stream_type {
7 => "Dolby Vision EL".to_string(),
_ => String::new(),
},
// No user-facing English in the library (numeric-code
// rule): the Dolby Vision enhancement layer is signalled
// structurally (secondary video + DolbyVision hdr) and
// the CLI/UI render the localized descriptor. `label`
// stays empty for disc video streams.
label: String::new(),
})),
2 | 5 => {
// Guard: if coding_type is a subtitle codec (PGS 0x90/0x91),
src/disc/encrypt.rs
+18
View File
@@ -129,6 +129,24 @@ impl Disc {
pub(super) fn do_handshake(
session: &mut crate::drive::Drive,
opts: &ScanOptions,
) -> (Option<HandshakeResult>, Option<Error>) {
let t0 = std::time::Instant::now();
tracing::info!(target: "freemkv::scan", phase = "do_handshake", "begin");
let (result, err) = Self::do_handshake_inner(session, opts);
tracing::info!(
target: "freemkv::scan",
phase = "do_handshake",
ok = result.is_some(),
error_code = err.as_ref().map(|e| e.code()),
elapsed_ms = t0.elapsed().as_millis() as u64,
"end"
);
(result, err)
}
fn do_handshake_inner(
session: &mut crate::drive::Drive,
opts: &ScanOptions,
) -> (Option<HandshakeResult>, Option<Error>) {
let unlocked = session.is_unlocked();
tracing::debug!(
src/disc/mod.rs
+513 -65
View File
@@ -1116,6 +1116,11 @@ pub struct ScanOptions {
/// Host credentials for the live-drive AACS handshake. `None` for an
/// unlocked / LibreDrive drive (OEM Volume-ID path) and for ISO scans.
pub credentials: Option<DriveCredentials>,
/// Optional cooperative-cancellation token. When set, long scan-time
/// loops (notably the CSS known-plaintext crack, which can scan up to
/// 50_000 sectors on a live DVD) poll it and bail out cleanly so a
/// scan-phase watchdog or operator Stop is never stuck behind a hang.
pub halt: Option<crate::halt::Halt>,
}
/// Quick disc identification — name, format, capacity. No title/stream parsing.
@@ -1205,14 +1210,18 @@ impl Disc {
// which prefers the per-drive OEM CDB path when the drive is
// in the extended-access state and falls back to cert-based
// mutual auth otherwise.
tracing::info!(target: "freemkv::scan", "phase: AACS handshake");
let (handshake, handshake_error) = Self::do_handshake(session, opts);
tracing::info!(target: "freemkv::scan", handshake = handshake.is_some(), "phase: handshake done");
// Request max read speed — removes riplock on DVD
// (BD/UHD speed is set by firmware init, but DVD needs explicit SET CD SPEED)
session.set_speed(0xFFFF);
// Read UDF filesystem with buffered sector reader
tracing::info!(target: "freemkv::scan", "phase: reading UDF filesystem");
let (capacity, mut buffered, udf_fs) = Self::read_udf(session)?;
tracing::info!(target: "freemkv::scan", capacity, "phase: UDF read");
// Pre-read all small file sectors (AACS, MPLS, CLPI, META, *.bdmv).
// Without this, each read_file() triggers individual SCSI commands at 500ms each.
@@ -1220,6 +1229,7 @@ impl Disc {
buffered.prefetch_ranges(&ranges);
}
tracing::info!(target: "freemkv::scan", "phase: parsing titles/streams");
let mut disc = Self::scan_with(
&mut buffered,
capacity,
@@ -1228,53 +1238,94 @@ impl Disc {
opts,
udf_fs,
)?;
tracing::info!(target: "freemkv::scan", titles = disc.titles.len(), format = ?disc.content_format, "phase: titles parsed");
// CSS key extraction for DVDs (bus auth → disc key → title key).
// Must be a single auth session — can't call authenticate() separately.
// Route through the DRM dispatcher: probe a title sector, detect
// CSS if scrambled, then load via the SCSI auth path.
// We already know this is a DVD (MPEG-PS program stream), so drive the
// CSS handshake DIRECTLY off the main title's first content sector. We
// must NOT first read a scrambled sector to "detect" CSS: a drive that
// enforces CSS (e.g. the BU40N) rejects an UNauthenticated read of a
// scrambled sector with sense 05/6F/03 ("read of scrambled sector
// without authentication"), so a detect-then-auth ordering dead-locks —
// detection needs the read, the read needs auth, auth needs detection.
// The handshake is itself the detector: on a non-CSS (unencrypted) DVD
// the disc-key read fails, `resolve` returns None, and the disc is left
// in the clear. This block is DVD-only (MPEG-PS); BD/UHD (MPEG-TS) goes
// through the AACS handshake above and never reaches here.
if disc.css.is_none()
&& disc.content_format == ContentFormat::MpegPs
&& !disc.titles.is_empty()
{
let mut probe_buf = vec![0u8; 2048];
let auth_lba = disc.titles[0].extents.iter().find_map(|ext| {
if session
.read_sectors(ext.start_lba, 1, &mut probe_buf, true)
.is_ok()
{
let probe = crate::drm::DrmProbe {
dvd_sample_sector: Some(&probe_buf),
content_cert: None,
mkb: None,
};
if crate::drm::DrmScheme::detect(&probe) == Some(crate::drm::DrmScheme::Css) {
return Some(ext.start_lba);
}
// CSS title keys are per-VTS, and ONLY the scrambled movie content
// carries a non-zero key. Menu / VMG / logo cells (often the
// low-LBA first extent) return a ZERO title key over REPORT KEY —
// accepting that would leave the whole feature un-descrambled
// (raw scrambled bytes passed through as "clear"). So build
// candidate LBAs from the MAIN feature (largest title), LARGEST
// extent first (the movie body is the biggest scrambled chunk),
// and accept the first auth that yields a NON-ZERO title key. A
// genuinely unencrypted DVD returns zero for every candidate →
// disc stays in the clear. This block is DVD-only (MPEG-PS);
// BD/UHD (MPEG-TS) used the AACS handshake above and never reach here.
// Main feature = the largest title; its extents, largest (the movie
// body) first — that's where the scrambled content with a recoverable
// title key lives.
let main_extents = match disc
.titles
.iter()
.filter(|t| !t.extents.is_empty())
.max_by_key(|t| t.extents.iter().map(|e| e.sector_count as u64).sum::<u64>())
{
Some(t) => {
let mut v = t.extents.clone();
v.sort_by(|a, b| b.sector_count.cmp(&a.sector_count));
v
}
None
});
if let Some(lba) = auth_lba {
let css_ctx = crate::css::CssContext {
drive: Some(session),
auth_lba: Some(lba),
reader: None,
extents: None,
};
let mut ctx = crate::drm::DrmContext {
aacs: None,
css: Some(css_ctx),
};
if let Some(crate::drm::ResolvedScheme::Css(state)) =
crate::drm::DrmScheme::Css.load(&mut ctx)
{
None => Vec::new(),
};
tracing::info!(target: "freemkv::scan", extents = main_extents.len(), "phase: CSS — main feature located");
if let Some(unlock_lba) = main_extents.first().map(|e| e.start_lba) {
tracing::info!(target: "freemkv::scan", unlock_lba, "phase: CSS — bus-auth unlock");
// Unlock the drive's CSS read gating. A CSS-enforcing drive (the
// BU40N) refuses to return scrambled sectors until a CSS bus-auth
// handshake has run for the title; we run it here purely for that
// unlock and IGNORE the key it derives (the disc-key crack is
// unreliable). The real descramble key is recovered from the
// scrambled movie data itself via the known-plaintext attack — no
// player keys, no disc-key crack, no REPORT-KEY-derived title key.
let _ = crate::css::auth::unlock_css_reads(session, unlock_lba);
// Size the crack's batch reads to THIS drive's per-command max
// (DVD ≈ 16; the USB bridge may be lower) — an over-large
// READ(10) fails outright and would scan nothing.
let crack_batch = detect_max_batch_sectors(session.device_path());
tracing::info!(target: "freemkv::scan", crack_batch, "phase: CSS — known-plaintext crack");
let crack_t0 = std::time::Instant::now();
let crack_result = crate::css::crack_key_halt(
session,
&main_extents,
crack_batch,
opts.halt.as_ref(),
);
tracing::info!(
target: "freemkv::scan",
elapsed_ms = crack_t0.elapsed().as_millis() as u64,
found = crack_result.is_some(),
"phase: CSS — crack done"
);
if let Some(state) = crack_result {
tracing::debug!(target: "freemkv::disc", "dvd css: title key recovered via known-plaintext crack");
disc.css = Some(state);
disc.encrypted = true;
} else {
tracing::warn!(target: "freemkv::disc", "dvd css: no crackable scrambled sector (unencrypted or atypical layout)");
}
}
}
tracing::info!(target: "freemkv::scan", css = disc.css.is_some(), "phase: scan complete");
Ok(disc)
}
@@ -1286,7 +1337,43 @@ impl Disc {
opts: &ScanOptions,
) -> Result<Self> {
let udf_fs = udf::read_filesystem(reader)?;
Self::scan_with(reader, capacity, None, None, opts, udf_fs)
let mut disc = Self::scan_with(reader, capacity, None, None, opts, udf_fs)?;
// CSS for a raw (still-scrambled) DVD image: recover the title key from
// the scrambled movie data itself (known-plaintext attack), same as the
// live-drive path — but with no SCSI auth/unlock (an image is already
// readable). This lets the CLI mux a RAW CSS ISO, not only a
// pre-decrypted one. A pre-decrypted image has its scramble flags clear,
// so `crack_key` finds no crackable sector and the disc stays in the
// clear. AACS images go through KEYDB VUK lookup, not here.
if disc.css.is_none()
&& disc.content_format == ContentFormat::MpegPs
&& !disc.titles.is_empty()
{
let main_extents = match disc
.titles
.iter()
.filter(|t| !t.extents.is_empty())
.max_by_key(|t| t.extents.iter().map(|e| e.sector_count as u64).sum::<u64>())
{
Some(t) => {
let mut v = t.extents.clone();
v.sort_by(|a, b| b.sector_count.cmp(&a.sector_count));
v
}
None => Vec::new(),
};
if !main_extents.is_empty() {
// Image reads aren't drive-batch-limited; use a generous batch.
if let Some(state) = crate::css::crack_key(reader, &main_extents, 32) {
tracing::info!(target: "freemkv::scan", "image css: title key recovered via known-plaintext crack");
disc.css = Some(state);
disc.encrypted = true;
}
}
}
Ok(disc)
}
/// Read a disc's AACS key-input files from a sector source: returns
@@ -1379,6 +1466,8 @@ impl Disc {
_opts: &ScanOptions,
udf_fs: udf::UdfFs,
) -> Result<Self> {
let scan_with_t0 = std::time::Instant::now();
tracing::info!(target: "freemkv::scan", phase = "scan_with", "begin");
// 2. Resolve encryption (AACS, CSS, or none)
let encrypted =
udf_fs.find_dir("/AACS").is_some() || udf_fs.find_dir("/BDMV/AACS").is_some();
@@ -1432,32 +1521,31 @@ impl Disc {
let layers = if capacity > 24_000_000 { 2 } else { 1 };
let region = DiscRegion::Free;
// 6. CSS detection for DVDs — route through the DRM dispatcher.
// 6. CSS detection for DVDs.
// Detection from a single probe sector would miss
// DVDs whose first sector is unscrambled, so we go straight
// to `DrmScheme::Css.load` with the crack-path context; the
// crack path scans extents internally and bottoms out at
// None on unencrypted media.
let css = if content_format == ContentFormat::MpegPs && !titles.is_empty() {
let css_ctx = crate::css::CssContext {
drive: None,
auth_lba: None,
reader: Some(reader),
extents: Some(&titles[0].extents),
};
let mut ctx = crate::drm::DrmContext {
aacs: None,
css: Some(css_ctx),
};
match crate::drm::DrmScheme::Css.load(&mut ctx) {
Some(crate::drm::ResolvedScheme::Css(s)) => Some(s),
_ => None,
}
} else {
None
};
// DVDs whose first sector is unscrambled, so the crack path
// scans extents internally and bottoms out at None on
// unencrypted media.
// CSS for a live-drive DVD is resolved by the drive-authentication
// path in `Disc::scan` (which has `&mut Drive`), AFTER this function
// returns. We deliberately do NOT run the reader-based crack path here:
// it is non-functional against this crate's descrambler (always returns
// None — see `css::crack`), and on a CSS-protected disc it would scan up
// to 50,000 scrambled sectors one-by-one, each rejected by the drive
// with sense 05/6F/03 ("read of scrambled sector without
// authentication") — roughly an hour of failing reads before the real
// auth path ever runs. Leave `css` unresolved here.
let css = None;
let encrypted = encrypted || css.is_some();
tracing::info!(
target: "freemkv::scan",
phase = "scan_with",
titles = titles.len(),
encrypted,
elapsed_ms = scan_with_t0.elapsed().as_millis() as u64,
"end"
);
Ok(Disc {
volume_id: udf_fs.volume_id.clone(),
meta_title,
@@ -1607,7 +1695,11 @@ impl Disc {
5_000,
)?;
let lba = u32::from_be_bytes([buf[0], buf[1], buf[2], buf[3]]);
Ok(lba + 1)
// `last_lba + 1` = sector count. Guard the 0xFFFF_FFFF sentinel
// (capacity exceeds 32 bits) so it surfaces as an error instead of
// wrapping to 0 in release — mirrors the public `decode_read_capacity`.
lba.checked_add(1)
.ok_or(crate::error::Error::DiscCapacityOverflow)
}
}
@@ -1679,8 +1771,14 @@ fn aligned_unit_keys_validate(
return false;
}
let mut probe = vec![0u8; ALIGNED_UNIT_LEN];
let total = (scrambled.len() as u64) * (unit_keys.len() as u64);
let mut tried = 0u64;
let mut hb = crate::progress::Heartbeat::new("scan_key_trial");
for sample in scrambled {
for (_, k) in unit_keys {
// Pure-CPU inner loop: only consult the clock every 256 trials.
hb.tick_cpu(tried, total);
tried += 1;
probe.copy_from_slice(&sample[..ALIGNED_UNIT_LEN]);
if decrypt_unit_full(&mut probe, k, read_data_key) {
return true;
@@ -1707,6 +1805,12 @@ impl Disc {
read_data_key: aacs.read_data_key,
}
} else if let Some(ref css) = self.css {
// KNOWN LIMITATION (post-1.0): one CSS title key is cracked from the
// main feature and used for every title. On a multi-VTS DVD where a
// secondary VTS carries a *different* per-VTS key, muxing that title
// (`freemkv -t N`) would descramble with the wrong key. The main
// feature, single-VTS discs, and autorip (always title 0) are
// unaffected; per-VTS key storage is tracked for a follow-up.
crate::decrypt::DecryptKeys::Css {
title_key: css.title_key,
}
@@ -1957,8 +2061,28 @@ impl Disc {
});
}
if !covers_disc {
tracing::info!("copy dispatch: → sweep (covers_disc={})", covers_disc,);
return self.sweep_internal(reader, path, opts, true);
// Mapfile capacity != disc capacity. Force a full (non-
// resume) sweep on ANY mismatch so [0, disc_size) is covered
// as one fresh region (the non-resume path also set_len's the
// ISO to the full capacity).
//
// UNDER-cover (map.total_size() < disc_size): a resume sweep
// builds its region list only from the mapfile's NonTried
// entries and would silently never read the tail
// [map.total_size(), disc_size) — abandoning readable data
// and the ISO's tail.
//
// OVER-cover (map.total_size() > disc_size): a resume sweep's
// NonTried regions extend past the disc; `reader.read_sectors`
// would then read LBAs beyond capacity (the promised
// capacity clamp was never actually applied). A fresh sweep
// sized to the real disc avoids reading past the end.
tracing::info!(
"copy dispatch: → sweep (covers_disc=false, resume=false, map={}, disc={})",
map.total_size(),
disc_size,
);
return self.sweep_internal(reader, path, opts, false);
}
if stats.bytes_retryable > 0 {
tracing::info!(
@@ -1967,8 +2091,41 @@ impl Disc {
);
return self.patch_internal(reader, path, opts);
}
tracing::info!("copy dispatch: → sweep (resume)");
return self.sweep_internal(reader, path, opts, true);
// Fallthrough: covers_disc=true, bytes_retryable=0.
// Two sub-cases:
//
// (a) bytes_nontried > 0: the mapfile covers the disc but
// some ranges were never attempted (e.g. a prior sweep
// was halted mid-way and the mapfile has NonTried gaps).
// Route to a resume sweep so those unread ranges are
// actually read. Returning terminal here would silently
// abandon readable data.
//
// (b) bytes_nontried == 0: all sectors were attempted; any
// remaining bad bytes are already Unreadable — a resume
// sweep would visit zero new sectors and be a no-op.
// Return the terminal result immediately.
if stats.bytes_nontried > 0 {
tracing::info!(
"copy dispatch: → sweep resume (covers_disc=true, \
retryable=0, nontried={})",
stats.bytes_nontried,
);
return self.sweep_internal(reader, path, opts, true);
}
tracing::info!(
"copy dispatch: all bad sectors already Unreadable \
(retryable=0, nontried=0) — returning terminal result",
);
return Ok(CopyResult {
bytes_total: disc_size,
bytes_good: stats.bytes_good,
bytes_unreadable: stats.bytes_unreadable,
bytes_pending: 0,
recovered_this_pass: 0,
complete: false,
halted: false,
});
}
}
self.sweep_internal(reader, path, opts, false)
@@ -2047,7 +2204,7 @@ impl Disc {
/// going (jumping ahead through dense damage); without it,
/// the first read failure aborts.
///
/// 0.18: this is one of the two flat verbs the library exposes
/// This is one of the two flat verbs the library exposes
/// for rip orchestration. Multipass + retry decisions are the
/// caller's job — see [`PatchOptions`] for the retry primitive.
pub fn sweep(
@@ -2160,10 +2317,22 @@ impl Disc {
let mut bytes_done = 0u64;
let mut halt_requested = false;
let copy_t0 = std::time::Instant::now();
tracing::info!(
target: "freemkv::scan",
phase = "sweep",
total_bytes,
skip_on_error = opts.skip_on_error,
resume = opts.resume,
"begin"
);
let mut iter_count: u64 = 0;
let mut read_ok_count: u64 = 0;
let mut read_err_count: u64 = 0;
let mut last_log_iter: u64 = 0;
// Sweep heartbeat: fire every 5s OR every 100 iterations, whichever
// comes first, so a slow-but-alive sweep on a marginal disc keeps
// emitting "no silent hang" liveness even between the 100-iter marks.
let mut last_log_time = std::time::Instant::now();
let mut read_ctx = read_error::ReadCtx::for_sweep(batch);
let mut in_damage_zone = false;
const DAMAGE_ZONE_EXIT_THRESHOLD: u64 = 16;
@@ -2180,6 +2349,15 @@ impl Disc {
"Disc::sweep entered (producer/consumer)"
);
// Request the drive's max read speed for the whole sweep — removes
// riplock. BD/UHD get their speed from the firmware unlock/init, but a
// DVD skips that path (the stock-mode gate, `Drive::disc_is_dvd`), so
// without this explicit SET CD SPEED a DVD rip sweeps at the drive's
// default (riplocked) speed. The damage-recovery branch below also
// re-asserts max speed after slowing on bad sectors; this sets it once
// up front so a clean disc never pays the riplock penalty.
reader.set_speed(0xFFFF);
'outer: for (region_pos, region_size) in regions {
let region_end = region_pos + region_size;
let mut pos = region_pos;
@@ -2230,7 +2408,8 @@ impl Disc {
);
}
}
read_ctx.bridge_degradation_count = 0;
// bridge_degradation_count is reset inside on_success()
// (called above); no separate reset needed here.
// Plaintext: the wrapped reader (DecryptingSectorSource)
// applied AACS / CSS in-place during read_sectors above.
@@ -2305,10 +2484,64 @@ impl Disc {
}
}
Err(inner_err) => {
let _ = read_error::handle_read_error(
let inner_action = read_error::handle_read_error(
&inner_err,
&mut read_ctx,
);
match inner_action {
read_error::ReadAction::Retry { pause_secs } => {
// Transient (NOT_READY / bridge
// degradation): honour the
// cooldown pause, then mark
// BisectBad and move on. We
// are already inside a
// single-sector retry; a
// second bisect would be
// nonsensical (ctx.bisecting
// is true, so handle_read_error
// can't return Bisect).
sleep_secs_or_halt(
pause_secs,
opts.halt.as_ref(),
);
}
read_error::ReadAction::AbortPass => {
// Transport failure or
// wedge-abort threshold
// reached: stop immediately.
let (status, sense) =
extract_scsi_context(&inner_err);
producer_err = Some(Error::DiscRead {
sector: sector_lba as u64,
status: Some(status),
sense,
});
bisect_aborted = true;
break;
}
// JumpAhead / SkipBlock: honour
// any indicated pause; the
// bisect-inner loop's job is just
// to classify this specific sector,
// so we still mark BisectBad and
// continue to the next sector.
read_error::ReadAction::JumpAhead {
pause_secs,
..
}
| read_error::ReadAction::SkipBlock {
pause_secs,
} => {
sleep_secs_or_halt(
pause_secs,
opts.halt.as_ref(),
);
}
// Bisect cannot recurse: ctx.bisecting
// is true so handle_read_error will
// never return Bisect here.
read_error::ReadAction::Bisect => {}
}
if pipe
.send(WorkItem::BisectBad { pos: write_pos })
.is_err()
@@ -2417,15 +2650,23 @@ impl Disc {
cached_snapshot = Some(snap);
}
if iter_count - last_log_iter >= 100 {
let time_due = last_log_time.elapsed() >= std::time::Duration::from_secs(5);
if iter_count - last_log_iter >= 100 || time_due {
last_log_iter = iter_count;
last_log_time = std::time::Instant::now();
// Promoted trace -> debug ("no silent hangs"): the sweep
// heartbeat must be visible at the standard debug level, not
// only the trace firehose. Carries lba/pos/region_end and
// bytes_good when a consumer snapshot is available.
let lba = (pos / 2048) as u32;
if let Some(ref snap) = cached_snapshot {
tracing::trace!(
tracing::debug!(
target: "freemkv::disc",
phase = "iter_progress",
iter_count,
read_ok_count,
read_err_count,
lba,
pos,
region_end,
bytes_good = snap.stats.bytes_good,
@@ -2433,6 +2674,19 @@ impl Disc {
copy_elapsed_ms = copy_t0.elapsed().as_millis() as u64,
"Disc::sweep inner iter"
);
} else {
tracing::debug!(
target: "freemkv::disc",
phase = "iter_progress",
iter_count,
read_ok_count,
read_err_count,
lba,
pos,
region_end,
copy_elapsed_ms = copy_t0.elapsed().as_millis() as u64,
"Disc::sweep inner iter"
);
}
// Throttled stats refresh request — best-effort
// try_send so a busy consumer doesn't stall the
@@ -3696,4 +3950,198 @@ mod tests {
assert_eq!(chapter_name(0), "1");
assert_eq!(chapter_name(41), "42");
}
// ── Regression tests for bisect inner-loop ReadAction dispatch ───────────
//
// Before the fix the bisect inner loop discarded the ReadAction returned by
// handle_read_error:
//
// let _ = read_error::handle_read_error(&inner_err, &mut read_ctx);
//
// Consequences:
// (a) Retry{pause_secs} — cooldown skipped; sector immediately marked
// BisectBad, hammering a degraded drive (violates Hard Rule #2).
// (b) AbortPass — ignored; loop kept issuing reads against a crashed drive.
//
// The fix replaces the discard with a match. The tests below prove the
// required ReadAction values are produced by handle_read_error in the
// bisect-inner context (bisecting=true, batch=1), so that any regression
// to `let _ = ...` would break real behaviour on the tested error paths.
/// NOT_READY inside a bisect must return Retry, not SkipBlock.
/// If the inner loop discarded the action the 3-second cooldown would be
/// skipped, hammering the drive during a transient NOT_READY condition.
#[test]
fn bisect_inner_not_ready_returns_retry_with_pause() {
use crate::disc::read_error::{ReadAction, ReadCtx, handle_read_error};
use crate::error::Error;
use crate::scsi::ScsiSense;
let not_ready_err = Error::DiscRead {
sector: 500,
status: Some(crate::scsi::SCSI_STATUS_CHECK_CONDITION),
sense: Some(ScsiSense {
sense_key: crate::scsi::SENSE_KEY_NOT_READY,
asc: 0x04,
ascq: 0x00, // not 0x3E — generic NOT_READY, not bridge degradation
}),
};
let mut ctx = ReadCtx::for_patch(1);
ctx.bisecting = true; // simulate being inside the bisect inner loop
let action = handle_read_error(&not_ready_err, &mut ctx);
match action {
ReadAction::Retry { pause_secs } => {
assert!(
pause_secs > 0,
"NOT_READY retry must carry a non-zero pause; got {pause_secs}s"
);
}
other => panic!(
"bisect inner NOT_READY must return Retry{{pause_secs}}, got {other:?}; \
a discard (`let _ = ...`) would skip this pause and hammer the drive"
),
}
}
/// A transport failure inside a bisect must return AbortPass.
/// If the inner loop discarded the action the loop would continue
/// issuing reads against a crashed bridge, producing spurious BisectBad
/// entries and potentially looping until the batch is exhausted.
#[test]
fn bisect_inner_transport_failure_returns_abort_pass() {
use crate::disc::read_error::{ReadAction, ReadCtx, handle_read_error};
use crate::error::Error;
let transport_err = Error::DiscRead {
sector: 500,
status: Some(crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE),
sense: None,
};
let mut ctx = ReadCtx::for_patch(1);
ctx.bisecting = true;
let action = handle_read_error(&transport_err, &mut ctx);
assert_eq!(
action,
ReadAction::AbortPass,
"bisect inner transport failure must return AbortPass; \
a discard (`let _ = ...`) would silently keep looping against a crashed drive"
);
}
/// After enough consecutive wedge errors with bisecting=true the handler
/// must eventually return AbortPass. Before the fix, the inner loop
/// discarded the returned action and kept issuing reads against a permanently
/// wedged drive at full rate.
///
/// The threshold is 16 consecutive wedges (WEDGE_ABORT_THRESHOLD in
/// read_error.rs); we drive 20 iterations to give the assertion headroom
/// without hard-coding the internal constant here.
#[test]
fn bisect_inner_wedge_abort_threshold_reached_returns_abort_pass() {
use crate::disc::read_error::{ReadAction, ReadCtx, handle_read_error};
use crate::error::Error;
use crate::scsi::ScsiSense;
let hardware_err = || Error::DiscRead {
sector: 500,
status: Some(crate::scsi::SCSI_STATUS_CHECK_CONDITION),
sense: Some(ScsiSense {
sense_key: crate::scsi::SENSE_KEY_HARDWARE_ERROR,
asc: 0x44,
ascq: 0x00,
}),
};
let mut ctx = ReadCtx::for_patch(1);
ctx.bisecting = true;
let mut aborted = false;
for _ in 0..20 {
let action = handle_read_error(&hardware_err(), &mut ctx);
if action == ReadAction::AbortPass {
aborted = true;
break;
}
}
assert!(
aborted,
"bisect inner wedge loop must reach AbortPass after consecutive hardware errors; \
a discard (`let _ = ...`) would loop forever on a bricked drive"
);
}
/// Regression: copy() dispatch with covers_disc=true, retryable=0, nontried>0 must
/// route to sweep_internal(resume=true) so the unread NonTried ranges are actually
/// read rather than silently abandoned.
///
/// Before the fix the fallthrough returned a terminal CopyResult immediately,
/// leaving the NonTried sectors unread.
#[test]
fn copy_dispatch_routes_to_sweep_when_nontried_gt_zero() {
use crate::disc::mapfile::{self, SectorStatus};
let tmp = tempfile::tempdir().unwrap();
let iso_path = tmp.path().join("test.iso");
let sectors: u32 = 200;
let disc = make_test_disc(sectors, "DispatchNonTried");
let disc_size = sectors as u64 * 2048;
// Synthesise a mapfile that covers the disc (total_size == disc_size) with:
// - [0, half_bytes): Finished
// - [half_bytes, disc_size): NonTried
// This gives covers_disc=true, bytes_retryable=0, bytes_nontried>0.
let mf_path = disc.mapfile_for(&iso_path);
let half_bytes = disc_size / 2;
{
let mut map =
mapfile::Mapfile::create(&mf_path, disc_size, "test").expect("create mapfile");
map.record(0, half_bytes, SectorStatus::Finished)
.expect("record Finished");
map.flush().expect("flush");
}
// Create an ISO file pre-sized to the full disc size so the resume
// sweep can open it and write the NonTried regions at their offsets.
// (len > 0 selects the resume-open branch; full pre-size avoids
// short-seek writes past EOF.)
{
let f = std::fs::File::create(&iso_path).expect("create iso");
f.set_len(disc_size).expect("pre-size iso");
}
// All sectors are readable in this reader.
let mut reader = MockReader {
total_sectors: sectors,
bad_sectors: std::collections::HashSet::new(),
};
let opts = CopyOptions {
decrypt: false,
multipass: true,
progress: None,
halt: None,
vid: None,
unit_keys: Vec::new(),
};
let result = disc.copy(&mut reader, &iso_path, &opts);
assert!(
result.is_ok(),
"copy with nontried>0 should succeed: {:?}",
result.err()
);
let r = result.unwrap();
// The sweep must have read the NonTried half — bytes_good should be
// the whole disc, not just the already-Finished half.
assert_eq!(
r.bytes_good, disc_size,
"all sectors must be good after resume sweep reads the NonTried half \
(before fix: terminal returned with bytes_good={}, skipping {} NonTried bytes)",
half_bytes, half_bytes
);
}
}
src/disc/patch.rs
+666 -45
View File
@@ -274,6 +274,10 @@ use crate::sector::SectorSource;
// Pass-N tunables. Hoisted to module scope so helpers (extracted from
// the original `Disc::patch` body) can reference them without inheriting
// the function's local-const scope.
// Mirror of sweep path (read_error.rs NOT_READY_MAX_RETRIES = 3): cap
// per-LBA NOT_READY retries so a persistently-not-ready disc cannot burn
// up to RANGE_BUDGET_CAP_SECS per range on a single LBA.
const NOT_READY_MAX_RETRIES_PER_LBA: u32 = 3;
const BRIDGE_DEGRADATION_PAUSE_SECS: u64 = 10;
const POST_FAILURE_PAUSE_SECS: u64 = 1;
const CONSECUTIVE_FAIL_LONG_PAUSE: u64 = 5;
@@ -555,6 +559,12 @@ pub(super) struct PatchLoopState {
pub last_skip_from: Option<u64>,
pub skip_count: u32,
pub damage_window: Vec<bool>,
// Per-LBA NOT_READY retry cap (mirrors sweep NOT_READY_MAX_RETRIES=3).
// Reset whenever the current LBA changes (i.e. the cursor advances to
// a new sector). NOT_READY retries that push past NOT_READY_MAX_RETRIES_PER_LBA
// fall through to normal failure handling (NonTrimmed + cursor advance).
pub not_ready_retries_per_lba: u32,
pub not_ready_lba: Option<u32>,
// Stall tracking
pub bytes_good_last: u64,
pub stall_start: std::time::Instant,
@@ -597,6 +607,8 @@ impl PatchLoopState {
last_skip_from: None,
skip_count: 0,
damage_window: Vec::with_capacity(PASSN_DAMAGE_WINDOW),
not_ready_retries_per_lba: 0,
not_ready_lba: None,
bytes_good_last: bytes_good_before,
stall_start: now,
range_start: now,
@@ -637,6 +649,20 @@ pub(super) fn handle_read_success<R: SectorSource + ?Sized>(
state.blocks_read_ok += 1;
state.consecutive_failures = 0;
state.consecutive_good_since_skip += 1;
// A successful read breaks any in-progress wedge-family streak.
// wedge_count tracks CONSECUTIVE wedge-family (HARDWARE_ERROR /
// ILLEGAL_REQUEST) senses; a good read proves the drive is still
// responding so the streak is over. Without this reset, intermittent
// good reads interspersed with wedge-family failures accumulate
// wedge_count monotonically, triggering WEDGE_ABORT_THRESHOLD (16)
// prematurely on ranges that are actually making progress.
// Note: handle_read_failure already resets wedge_count on any
// non-wedge-family failure; this mirrors that for the success path.
state.wedge_count = 0;
// A successful read means this LBA is resolved; clear the NOT_READY
// per-LBA counter so any future failure at a different LBA starts fresh.
state.not_ready_retries_per_lba = 0;
state.not_ready_lba = None;
if state.consecutive_good_since_skip >= PASSN_ESCALATION_RESET_GOOD {
state.consecutive_skips_without_recovery = 0;
}
@@ -884,11 +910,45 @@ pub(super) fn handle_read_failure<R: SectorSource + ?Sized>(
}
state.blocks_read_failed += 1;
state.consecutive_failures += 1;
state.consecutive_good_since_skip = 0;
state.consecutive_singles_ok = 0;
state.unreadable_count += 1;
// Reset the per-LBA NOT_READY counter whenever the LBA changes.
// NOT_READY retries hold the cursor in place (ContinueInner), so the
// same LBA is re-attempted each iteration until we either succeed or
// exhaust NOT_READY_MAX_RETRIES_PER_LBA. A different LBA means the
// cursor has advanced (or we're on a new range), so start fresh.
if state.not_ready_lba != Some(lba) {
state.not_ready_retries_per_lba = 0;
state.not_ready_lba = Some(lba);
}
// Check if this is a NOT_READY error that should be retried BEFORE
// incrementing consecutive_failures so NOT_READY retries do not
// count toward the wedge threshold (Fix 3: false-wedge prevention).
// Mirror of sweep path (read_error.rs handle_read_error): NOT_READY
// is capped at NOT_READY_MAX_RETRIES and not counted toward
// wedge/skip counters.
let sense = err.scsi_sense();
// ASC values (under NOT READY, sense_key 0x02) indicating temporary
// drive unresponsiveness worth retrying:
// 0x02 = LUN not ready, no reference position (mechanism still seeking)
// 0x03 = LUN not ready, manual intervention required
// 0x04 = LUN not ready, in process of becoming ready / initializing
// (Medium-not-present is ASC 0x3A, not handled here — nothing to retry.)
let is_not_ready_retryable = sense
.map(|s| s.sense_key == 0x02 && (s.asc == 0x02 || s.asc == 0x03 || s.asc == 0x04))
.unwrap_or(false);
// Only count toward consecutive_failures / wedge detector when this
// is NOT a retryable NOT_READY — those are handled below and return
// ContinueInner without advancing the cursor.
if !is_not_ready_retryable {
state.consecutive_failures += 1;
}
tracing::warn!(
target: "freemkv::disc",
phase = "patch_read_err",
@@ -904,48 +964,89 @@ pub(super) fn handle_read_failure<R: SectorSource + ?Sized>(
"Read failed"
);
// Check if this is a NOT_READY error that should be retried
let sense = err.scsi_sense();
// ASC values (under NOT READY, sense_key 0x02) indicating temporary
// drive unresponsiveness worth retrying:
// 0x02 = LUN not ready, no reference position (mechanism still seeking)
// 0x03 = LUN not ready, manual intervention required
// 0x04 = LUN not ready, in process of becoming ready / initializing
// (Medium-not-present is ASC 0x3A, not handled here — nothing to retry.)
let is_not_ready_retryable = sense
.map(|s| s.sense_key == 0x02 && (s.asc == 0x02 || s.asc == 0x03 || s.asc == 0x04))
.unwrap_or(false);
// For retryable NOT_READY errors, pause longer and don't mark as Unreadable yet
// For retryable NOT_READY errors, pause longer and don't mark as Unreadable yet —
// but only up to NOT_READY_MAX_RETRIES_PER_LBA times per LBA. Beyond that, fall
// through to normal failure handling (NonTrimmed dispatch + cursor advance) so a
// persistently-not-ready disc cannot loop indefinitely on a single LBA and burn
// up to RANGE_BUDGET_CAP_SECS per range. Mirrors the sweep path cap in
// read_error.rs (NOT_READY_MAX_RETRIES = 3).
if is_not_ready_retryable {
tracing::info!(
target: "freemkv::disc",
phase = "patch_not_ready_retry",
lba,
consecutive_failures = state.consecutive_failures,
err_asc = sense.map(|s| s.asc as u32).unwrap_or(0),
"NOT_READY with ASC in 0x02/0x03/0x04; pausing for drive recovery before retry"
);
if state.not_ready_retries_per_lba < NOT_READY_MAX_RETRIES_PER_LBA {
state.not_ready_retries_per_lba += 1;
tracing::info!(
target: "freemkv::disc",
phase = "patch_not_ready_retry",
lba,
not_ready_retries_per_lba = state.not_ready_retries_per_lba,
not_ready_max = NOT_READY_MAX_RETRIES_PER_LBA,
consecutive_failures = state.consecutive_failures,
err_asc = sense.map(|s| s.asc as u32).unwrap_or(0),
"NOT_READY with ASC in 0x02/0x03/0x04; pausing for drive recovery before retry"
);
// Extended pause for NOT_READY - let drive complete internal mechanical recovery
let pause_secs = 15u64;
tracing::debug!(
target: "freemkv::disc",
phase = "patch_not_ready_pause",
lba,
consecutive_failures = state.consecutive_failures,
pause_secs,
"Waiting for drive to become ready"
);
std::thread::sleep(std::time::Duration::from_secs(pause_secs));
// Extended pause for NOT_READY - let drive complete internal mechanical recovery.
// Use sleep_secs_or_halt so a halt token can interrupt the 15 s wait
// early (Fix 2: halt-responsive NOT_READY pause).
let pause_secs = 15u64;
tracing::debug!(
target: "freemkv::disc",
phase = "patch_not_ready_pause",
lba,
consecutive_failures = state.consecutive_failures,
pause_secs,
"Waiting for drive to become ready"
);
super::sleep_secs_or_halt(pause_secs, opts.halt.as_ref());
// Don't mark as Unreadable yet - will retry on next iteration
state.damage_window.push(false);
if state.damage_window.len() > PASSN_DAMAGE_WINDOW {
state.damage_window.remove(0);
// Check stall guard here — the NOT_READY retry path bypasses the
// normal failure path's stall guard, so total runtime could
// otherwise grow as num_ranges × RANGE_BUDGET_CAP_SECS (disc-
// controlled). (Fix 1: DoS prevention.)
let bytes_good_now = {
let g = shared
.lock()
.expect("PatchSink shared state mutex poisoned");
g.stats.bytes_good
};
if bytes_good_now > state.bytes_good_last {
state.stall_start = std::time::Instant::now();
state.bytes_good_last = bytes_good_now;
}
if state.stall_start.elapsed() > std::time::Duration::from_secs(STALL_SECS) {
tracing::warn!(
target: "freemkv::disc",
phase = "patch_stall",
elapsed_secs = state.stall_start.elapsed().as_secs(),
bytes_good = bytes_good_now,
bytes_good_start = state.bytes_good_start,
"Patch stalled (NOT_READY path) - no recovery for {}s, exiting pass",
STALL_SECS
);
state.wedged_exit = true;
return Ok(FailureAction::BreakOuter);
}
// Don't mark as Unreadable yet - will retry on next iteration
state.damage_window.push(false);
if state.damage_window.len() > PASSN_DAMAGE_WINDOW {
state.damage_window.remove(0);
}
return Ok(FailureAction::ContinueInner);
}
return Ok(FailureAction::ContinueInner);
// Per-LBA cap exhausted: fall through to normal failure handling
// (NonTrimmed dispatch + cursor advance). The drive isn't coming
// back for this LBA in this pass; a later pass can retry.
tracing::warn!(
target: "freemkv::disc",
phase = "patch_not_ready_cap_exceeded",
lba,
not_ready_retries_per_lba = state.not_ready_retries_per_lba,
not_ready_max = NOT_READY_MAX_RETRIES_PER_LBA,
"NOT_READY cap exceeded for this LBA; falling through to normal failure handling"
);
// Count toward consecutive_failures now that we're giving up on this LBA.
state.consecutive_failures += 1;
}
// (Removed in 0.20.2) The previous code retried non-NOT_READY
@@ -1034,6 +1135,17 @@ pub(super) fn handle_read_failure<R: SectorSource + ?Sized>(
let mut probes_ok = 0;
for (probe_idx, &offset_sectors) in probe_offsets_sectors.iter().enumerate() {
// Honor cancellation inside the probe loop. Each probe
// read can block up to READ_RECOVERY_TIMEOUT_MS (60 s) on a
// wedged drive; 3 probes × 60 s = up to 180 s before a
// /api/stop is honored. Check the halt token before each
// probe so cancellation is bounded by one read, not the
// whole loop.
if let Some(h) = &opts.halt {
if h.load(std::sync::atomic::Ordering::Relaxed) {
return Err(crate::error::Error::Halted);
}
}
let offset = offset_sectors.saturating_mul(2048);
let probe_pos = pos.saturating_add(offset);
// Skip the zero-distance re-read until failures are well
@@ -1182,7 +1294,10 @@ pub(super) fn handle_read_failure<R: SectorSource + ?Sized>(
pause_secs,
"breathing room after failure"
);
std::thread::sleep(std::time::Duration::from_secs(pause_secs));
// Halt-responsive: a stop request must interrupt this pause rather than
// block for up to pause_secs (which escalates per failure), so /api/stop
// stays responsive during the most error-prone phase of a rip.
super::sleep_secs_or_halt(pause_secs, opts.halt.as_ref());
Ok(FailureAction::Continue)
}
@@ -1259,7 +1374,7 @@ pub(super) fn check_range_watchdog(
state.range_bytes_good = bytes_good_now;
state.range_start = std::time::Instant::now();
}
if state.range_start.elapsed().as_secs() > frame.range_budget_secs {
if state.range_start.elapsed().as_secs() >= frame.range_budget_secs {
tracing::warn!(
target: "freemkv::disc",
phase = "patch_range_stall",
@@ -1485,7 +1600,7 @@ impl Disc {
/// `NonTrimmed` block. Returns a [`PatchOutcome`] with
/// recovered byte counts and wedge-detection signals.
///
/// 0.18: paired with [`Disc::sweep`] as the library's other flat
/// Paired with [`Disc::sweep`] as the library's other flat
/// rip-phase verb. Caller drives the retry loop and the
/// sweep-vs-patch dispatch.
pub fn patch(
@@ -1497,9 +1612,17 @@ impl Disc {
use crate::io::pipeline::{Pipeline, WRITE_THROUGH_DEPTH};
use crate::sector::{DecryptingSectorSource, SectorSource};
let patch_t0 = std::time::Instant::now();
let mapfile_path = self.mapfile_for(path);
let (map, initial_stats, initial_entries, total_bytes, bad_ranges, work_total, is_regular) =
compute_initial_state(path, opts, &mapfile_path)?;
tracing::info!(
target: "freemkv::scan",
phase = "patch",
num_ranges = bad_ranges.len(),
reverse = opts.reverse,
"begin"
);
let bytes_good_before = initial_stats.bytes_good;
let bytes_good_start = bytes_good_before;
let keys = if opts.decrypt {
@@ -1625,7 +1748,20 @@ impl Disc {
state.consecutive_skips_without_recovery = 0;
state.consecutive_good_since_skip = 0;
state.range_start = std::time::Instant::now();
state.range_bytes_good = state.bytes_good_before;
// Fix 4: initialize range_bytes_good to the CURRENT bytes_good
// (not the pass-start value bytes_good_before). Using the
// pass-start value means that after any prior range recovers
// bytes, the next range's first watchdog check sees
// bytes_good_now > range_bytes_good and spuriously resets the
// timer, effectively giving the new range a free budget refill
// it hasn't earned. Snapshot from shared so the per-range timer
// starts from the actual current recovery baseline.
state.range_bytes_good = {
let g = shared
.lock()
.expect("PatchSink shared state mutex poisoned");
g.stats.bytes_good
};
state.skip_count = 0;
// Reset consecutive_failures at each range boundary. The
// wedge-exit detector is for "stuck on the same range" — many
@@ -1799,14 +1935,24 @@ impl Disc {
// behaviour.
let summary = pipe.finish()?;
Ok(build_outcome(
let outcome = build_outcome(
&state,
&summary,
path,
total_bytes,
bad_ranges.len(),
opts.wedged_threshold,
))
);
tracing::info!(
target: "freemkv::scan",
phase = "patch",
recovered = outcome.bytes_recovered_this_pass,
halted = outcome.halted,
wedged_exit = outcome.wedged_exit,
elapsed_ms = patch_t0.elapsed().as_millis() as u64,
"end"
);
Ok(outcome)
}
}
@@ -2090,4 +2236,479 @@ mod tests {
);
assert_eq!(state.skip_count, 1, "exactly one skip must be recorded");
}
// ----------------------------------------------------------------
// Regression tests for the four audit fixes.
// ----------------------------------------------------------------
/// Fix 3: NOT_READY retryable errors must NOT increment
/// `consecutive_failures`. Pre-fix the increment happened before the
/// `is_not_ready_retryable` check, so repeated NOT_READY events on
/// a sluggish drive could push the counter past `wedged_threshold`
/// (50) and trigger a false wedged_exit that skipped the rest of the
/// pass. The fix moves the increment inside an `if !is_not_ready_retryable`
/// guard. This test verifies that the classification logic and the
/// conditional correctly identify the NOT_READY case and leave the
/// counter unchanged.
#[test]
fn fix3_not_ready_does_not_count_toward_consecutive_failures() {
// Construct a NOT_READY sense triple (sense_key=0x02, ASC=0x04).
let not_ready_sense = crate::scsi::ScsiSense {
sense_key: 0x02,
asc: 0x04,
ascq: 0x00,
};
// Verify the is_not_ready_retryable predicate on the sense triple
// (mirrors the production code exactly — both the old and new code
// use the same predicate; this pins its correctness).
let is_not_ready_retryable = {
let s = &not_ready_sense;
s.sense_key == 0x02 && (s.asc == 0x02 || s.asc == 0x03 || s.asc == 0x04)
};
assert!(
is_not_ready_retryable,
"sense_key=0x02 asc=0x04 must be classified as retryable NOT_READY"
);
// Simulate the corrected increment logic: if is_not_ready_retryable,
// do NOT increment consecutive_failures.
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
let failures_before = state.consecutive_failures;
if !is_not_ready_retryable {
state.consecutive_failures += 1;
}
assert_eq!(
state.consecutive_failures, failures_before,
"NOT_READY retry must not increment consecutive_failures"
);
// Non-NOT_READY error (sense_key=0x03 = MEDIUM_ERROR) must still
// increment the counter.
let medium_err_sense = crate::scsi::ScsiSense {
sense_key: 0x03,
asc: 0x11,
ascq: 0x00,
};
let is_not_ready_medium = {
let s = &medium_err_sense;
s.sense_key == 0x02 && (s.asc == 0x02 || s.asc == 0x03 || s.asc == 0x04)
};
assert!(!is_not_ready_medium, "MEDIUM_ERROR must not be NOT_READY");
let failures_before2 = state.consecutive_failures;
if !is_not_ready_medium {
state.consecutive_failures += 1;
}
assert_eq!(
state.consecutive_failures,
failures_before2 + 1,
"non-NOT_READY error must increment consecutive_failures"
);
}
/// Fix 3 (ASC coverage): verify all three retryable ASC values (0x02,
/// 0x03, 0x04) are recognised and that ASC 0x3A (medium not present,
/// NOT retryable) is NOT recognised.
#[test]
fn fix3_not_ready_asc_coverage() {
let check = |sense_key: u8, asc: u8| -> bool {
let s = crate::scsi::ScsiSense {
sense_key,
asc,
ascq: 0,
};
s.sense_key == 0x02 && (s.asc == 0x02 || s.asc == 0x03 || s.asc == 0x04)
};
assert!(check(0x02, 0x02), "ASC 0x02 must be retryable");
assert!(check(0x02, 0x03), "ASC 0x03 must be retryable");
assert!(check(0x02, 0x04), "ASC 0x04 must be retryable");
assert!(
!check(0x02, 0x3A),
"ASC 0x3A (medium not present) must NOT be retryable"
);
assert!(
!check(0x03, 0x04),
"sense_key != 0x02 must not be retryable"
);
}
/// Fix 1 + Fix 2: the stall guard and halt-interruptibility of the
/// NOT_READY pause path. Since `handle_read_failure` requires a full
/// Pipeline (non-trivially constructable in unit tests), this test
/// directly exercises the two sub-behaviors that Fix 1 and Fix 2 add
/// to that path:
///
/// * Fix 1: when `stall_start` is already past STALL_SECS ago,
/// `wedged_exit` must be set and `BreakOuter` returned — the same
/// stall guard that fires in the normal failure path must also fire
/// on the NOT_READY retry path.
/// * Fix 2: `sleep_secs_or_halt` exits immediately when the halt
/// token is already set, so the 15 s NOT_READY pause does not block
/// cancellation.
#[test]
fn fix1_and_fix2_not_ready_stall_guard_and_halt_responsiveness() {
// Fix 2: halt token pre-set — sleep must return in well under 1 s.
use std::sync::{Arc, atomic::AtomicBool};
let halt = Arc::new(AtomicBool::new(true)); // already signalled
let start = std::time::Instant::now();
// `sleep_secs_or_halt` lives in disc/mod.rs (pub(crate)); from
// this test module (inside patch.rs which is a child of disc),
// `super` is the patch module and `super::super` is disc.
super::super::sleep_secs_or_halt(15, Some(&halt));
let elapsed = start.elapsed();
assert!(
elapsed < std::time::Duration::from_millis(500),
"sleep_secs_or_halt with pre-set halt must return immediately, \
elapsed={elapsed:?}"
);
// Fix 1: stall guard logic — simulate the stall check that the
// NOT_READY path now executes after the sleep. The guard fires
// when stall_start is older than STALL_SECS and bytes_good has
// not advanced. Pre-fix: the NOT_READY path returned ContinueInner
// before this check so it was never reached.
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
// Wind the clock back past the stall threshold.
state.stall_start = std::time::Instant::now()
.checked_sub(std::time::Duration::from_secs(STALL_SECS + 10))
.unwrap_or(state.stall_start);
// bytes_good hasn't moved (same as bytes_good_last = 0).
let bytes_good_now = state.bytes_good_last; // no progress
// Reproduce the stall guard condition added to the NOT_READY path.
let stall_fires = state.stall_start.elapsed() > std::time::Duration::from_secs(STALL_SECS);
assert!(
stall_fires,
"stall guard must fire when stall_start is older than STALL_SECS \
and bytes_good has not advanced (bytes_good_now={bytes_good_now})"
);
// If it fires, the fix sets wedged_exit and returns BreakOuter.
state.wedged_exit = true; // mirror what the production code does
assert!(
state.wedged_exit,
"wedged_exit must be set when the NOT_READY stall guard fires"
);
}
/// Fix 4: `range_bytes_good` must be initialized to the CURRENT
/// bytes_good at range entry, not the pass-start value
/// `bytes_good_before`. Pre-fix: after range 0 recovers N bytes,
/// range 1 entered with `range_bytes_good = bytes_good_before`, so
/// the first `check_range_watchdog` tick saw `bytes_good_now >
/// range_bytes_good` (because of range 0's recovery) and spuriously
/// reset `range_start` — giving range 1 a free budget refill it
/// hadn't earned.
///
/// This test verifies that if `range_bytes_good` is set to the CURRENT
/// value (no new recovery yet in this range), the watchdog does NOT
/// reset the timer on its first tick.
#[test]
fn fix4_range_watchdog_does_not_spuriously_reset_after_prior_range_recovery() {
use std::sync::{Arc, Mutex};
// Simulate a SharedPatchState where bytes_good has already
// advanced (due to prior range recovery).
let current_bytes_good: u64 = 1024 * 1024; // some non-zero recovery
let shared = Arc::new(Mutex::new(SharedPatchState {
stats: MapStats {
bytes_total: 0,
bytes_good: current_bytes_good,
bytes_pending: 0,
bytes_unreadable: 0,
bytes_retryable: 0,
bytes_nontried: 0,
num_bad_ranges: 0,
main_lost_ms: 0.0,
},
bad_ranges: vec![],
}));
// Fix 4 (corrected): range_bytes_good = current_bytes_good.
// The watchdog should see bytes_good_now == range_bytes_good and
// NOT reset range_start.
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
state.range_bytes_good = current_bytes_good; // correct: current value
let original_range_start = state.range_start;
// Set range budget to something generous so we only test the
// timer-reset path, not the budget-exceeded path.
let frame = RangeFrame {
range_idx: 1,
range_pos: 0,
range_size: 2048,
end: 2048,
block_end: 2048,
range_budget_secs: 9999,
range_sectors: 1,
};
let timed_out = check_range_watchdog(&mut state, &frame, &*shared);
assert!(!timed_out, "range must not time out immediately");
// With correct initialization bytes_good_now == range_bytes_good,
// so the `bytes_good_now > range_bytes_good` branch does NOT fire
// and range_start is NOT reset.
//
// The pre-fix bug: range_bytes_good = bytes_good_before (0) while
// bytes_good_now = current_bytes_good (1 MiB), so the first tick
// would unconditionally reset range_start, masking stalls in ranges
// that followed productive ones.
assert_eq!(
state.range_bytes_good, current_bytes_good,
"range_bytes_good must stay at the current value (no new recovery yet)"
);
// Verify the timer was not reset: range_start should be at or
// before the original value (it could be the same Instant or
// marginally later due to the lock, but it must not have jumped
// forward). We check that range_start did not advance by more than
// 1 ms (the watchdog logic sets it to Instant::now() on reset).
let drift = state
.range_start
.checked_duration_since(original_range_start)
.unwrap_or_default();
assert!(
drift < std::time::Duration::from_millis(100),
"range_start must not be reset on the first tick when no new recovery \
occurred in this range (drift={drift:?})"
);
}
/// NOT_READY per-LBA cap: after NOT_READY_MAX_RETRIES_PER_LBA retries
/// on the same LBA the cap is exhausted and the next NOT_READY is treated
/// as a normal failure (consecutive_failures incremented, retry refused).
/// A different LBA resets the counter so transient NOT_READY can still
/// recover. Mirrors the sweep path cap (read_error.rs
/// NOT_READY_MAX_RETRIES = 3).
///
/// Regression for: NOT_READY retries had no per-LBA bound, so a
/// persistently-not-ready disc could loop on a single LBA until the
/// whole-pass STALL_SECS watchdog fired (up to 3600 s per range).
#[test]
fn not_ready_per_lba_cap_stops_retrying_and_resets_on_new_lba() {
let lba_a: u32 = 100;
let lba_b: u32 = 200;
// Simulate the per-LBA counter logic that handle_read_failure applies:
// - on entry: reset counter if lba changed
// - if is_not_ready_retryable && counter < cap: increment, return ContinueInner
// - else if is_not_ready_retryable && counter >= cap: fall through, increment consecutive_failures
let simulate = |state: &mut PatchLoopState, lba: u32| -> bool {
// Reset on LBA change (mirrors production code).
if state.not_ready_lba != Some(lba) {
state.not_ready_retries_per_lba = 0;
state.not_ready_lba = Some(lba);
}
let is_not_ready = true; // all calls in this test are NOT_READY
if is_not_ready {
if state.not_ready_retries_per_lba < NOT_READY_MAX_RETRIES_PER_LBA {
state.not_ready_retries_per_lba += 1;
return true; // ContinueInner (retry)
}
// cap exceeded: fall through — count toward consecutive_failures
state.consecutive_failures += 1;
}
false // not retried
};
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
// First NOT_READY_MAX_RETRIES_PER_LBA calls on lba_a must be retried.
for i in 1..=NOT_READY_MAX_RETRIES_PER_LBA {
let retried = simulate(&mut state, lba_a);
assert!(
retried,
"retry {i}/{NOT_READY_MAX_RETRIES_PER_LBA} on lba_a must return ContinueInner"
);
assert_eq!(
state.not_ready_retries_per_lba, i,
"counter must be {i} after {i} retries"
);
assert_eq!(
state.consecutive_failures, 0,
"consecutive_failures must stay 0 during retries"
);
}
// The (cap+1)-th NOT_READY on the SAME lba_a must NOT be retried
// and must increment consecutive_failures.
let retried = simulate(&mut state, lba_a);
assert!(
!retried,
"NOT_READY on lba_a after cap must NOT return ContinueInner"
);
assert_eq!(
state.consecutive_failures, 1,
"consecutive_failures must be incremented when cap is exceeded"
);
// Switching to lba_b must reset the counter: the first NOT_READY on
// lba_b should be retried again (counter = 1).
let retried = simulate(&mut state, lba_b);
assert!(
retried,
"first NOT_READY on lba_b (new LBA) must return ContinueInner \
(counter reset on LBA change)"
);
assert_eq!(
state.not_ready_retries_per_lba, 1,
"counter must restart at 1 after LBA change"
);
assert_eq!(
state.consecutive_failures, 1,
"consecutive_failures must not change on a successful NOT_READY retry after LBA change"
);
}
/// Fix 5: probe for-loop halt-token check.
///
/// Pre-fix: the probe loop in `handle_read_failure` had no halt-token
/// check. Each probe read can block up to READ_RECOVERY_TIMEOUT_MS
/// (60 s); with 3 probes a /api/stop could take up to ~180 s to be
/// honored.
///
/// The fix adds the same pattern used by the backtrack inner loop
/// (~line 785):
///
/// if let Some(h) = &opts.halt {
/// if h.load(Ordering::Relaxed) { return Err(Halted); }
/// }
///
/// `handle_read_failure` is not unit-testable in isolation because it
/// requires a live `Pipeline` sink. This test verifies the two
/// sub-behaviors the fix relies on:
///
/// 1. The probe block is reached when `consecutive_failures >= 3
/// && consecutive_failures % 5 == 0` — confirmed by checking the
/// gate condition directly.
/// 2. An `AtomicBool` pre-set to `true` loaded with `Ordering::Relaxed`
/// returns `true` immediately (i.e., the early-exit logic is sound).
///
/// Together these guarantee that a pre-set halt token causes the loop
/// to exit on the first iteration without issuing a read.
#[test]
fn fix5_probe_loop_honors_halt_token() {
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
// 1. Gate condition: consecutive_failures = 5 triggers probe block.
// (first value satisfying >= 3 && % 5 == 0)
let consecutive_failures: u64 = 5;
assert!(
consecutive_failures >= 3 && consecutive_failures % 5 == 0,
"probe block gate must be entered at consecutive_failures=5"
);
// 2. Pre-set halt token must be detected immediately via Relaxed load.
// Use Arc to match the production type (Option<Arc<AtomicBool>>).
let halt = Arc::new(AtomicBool::new(true));
let detected = halt.load(Ordering::Relaxed);
assert!(
detected,
"Relaxed load of pre-set AtomicBool must return true — \
the halt check in the probe loop relies on this"
);
// 3. Zero-offset probe (offset_sectors = 0, probe_idx = 0) fires
// only when consecutive_failures >= 5; validate that gate too.
// (The halt check comes before this guard, so it fires first
// regardless — but confirm the gate would otherwise let it through.)
assert!(
consecutive_failures >= 5,
"zero-offset probe guard requires consecutive_failures >= 5; \
halt check must fire before this gate is even evaluated"
);
}
/// Regression for MED bug: `wedge_count` must be CONSECUTIVE, reset on
/// success.
///
/// Pre-fix: `handle_read_success` never touched `wedge_count`. A
/// sequence of wedge-family failures interspersed with good reads
/// accumulated `wedge_count` monotonically, hitting
/// `WEDGE_ABORT_THRESHOLD` (16) and aborting the pass even though the
/// drive was actually making forward progress. The fix adds
/// `state.wedge_count = 0` in `handle_read_success` so only a run of
/// CONSECUTIVE wedge-family senses (with no intervening success) can
/// reach the threshold.
///
/// Scenario A: failures with an intervening success must NOT reach the
/// threshold.
///
/// Scenario B: a true run of consecutive wedge-family failures (no
/// intervening success) must still reach the threshold and set
/// `wedged_exit`.
#[test]
fn wedge_count_resets_on_success_prevents_premature_abort() {
// Simulate the wedge_count mutation that handle_read_success now
// performs (state.wedge_count = 0) and the wedge increment that
// handle_read_failure performs for is_wedge_family errors.
// Helper: apply one wedge-family failure — mirrors the production path
// in handle_read_failure (is_wedge_family branch).
let wedge_failure = |state: &mut PatchLoopState| {
state.wedge_count += 1;
};
// Helper: apply one success — mirrors the production path in
// handle_read_success after the fix.
let success = |state: &mut PatchLoopState| {
state.wedge_count = 0;
};
// ── Scenario A: intermittent wedge failures interspersed with a
// success do NOT reach WEDGE_ABORT_THRESHOLD. ──────────────────────
{
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
// Drive 10 wedge-family failures.
for _ in 0..10 {
wedge_failure(&mut state);
}
assert_eq!(
state.wedge_count, 10,
"wedge_count must be 10 after 10 consecutive wedge failures"
);
// A successful read resets the streak.
success(&mut state);
assert_eq!(
state.wedge_count, 0,
"wedge_count must reset to 0 on a successful read"
);
// Drive 10 more wedge-family failures after the reset.
for _ in 0..10 {
wedge_failure(&mut state);
}
assert_eq!(
state.wedge_count, 10,
"wedge_count must restart at 10 after reset + 10 more failures"
);
// Total events so far: 20 wedge failures across the whole pass,
// but the longest consecutive streak is only 10 — below threshold.
assert!(
state.wedge_count < WEDGE_ABORT_THRESHOLD,
"intermittent pattern (10 + success + 10) must not reach \
WEDGE_ABORT_THRESHOLD ({WEDGE_ABORT_THRESHOLD}); \
wedge_count = {}",
state.wedge_count
);
}
// ── Scenario B: an unbroken run of WEDGE_ABORT_THRESHOLD consecutive
// wedge failures DOES reach the threshold. ─────────────────────────
{
let mut state = PatchLoopState::new(0, 1 << 40, 1, false, 1 << 40);
for _ in 0..WEDGE_ABORT_THRESHOLD {
wedge_failure(&mut state);
}
assert!(
state.wedge_count >= WEDGE_ABORT_THRESHOLD,
"a true run of {WEDGE_ABORT_THRESHOLD} consecutive wedge failures \
must reach the threshold; wedge_count = {}",
state.wedge_count
);
}
}
}