From eb7c24a5d8b0108431568d39ef1e7740b3e51c24 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 04:33:51 -0800 Subject: [PATCH 1/4] chore(quest): claim quest/m1/mp4-repair-lock.md Quest-Claim: 50dcfde0d8f48542 From 1e0a12e1ef67b217289a41fa65da973291af46da Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 04:42:44 -0800 Subject: [PATCH 2/4] feat(cli): moq repair refuses a recording still being written export mp4 holds an exclusive file lock on its output while it records, and repair mp4 refuses a file it cannot lock. Neither runs on a filesystem without locks. Co-Authored-By: Claude Sonnet 5.5 --- doc/bin/cli.md | 5 +++ quest/m1/mp4-repair-lock.md | 22 --------- rs/moq-cli/src/repair.rs | 13 ++++++ rs/moq-cli/src/subscribe.rs | 15 ++++++- rs/moq-cli/tests/integration/export.rs | 62 ++++++++++++++++++++++---- 5 files changed, 84 insertions(+), 33 deletions(-) delete mode 100644 quest/m1/mp4-repair-lock.md diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 065d77330f0..1aa696e150c 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -162,6 +162,11 @@ joins mid-recording is kept, though only the finished file indexes it. fragmented, in place and the same way: it indexes every fragment written in full, late renditions included, and cuts a partial one at the end. +The recorder holds an exclusive file lock on its output while it records, and the +OS drops the lock with a killed recorder. `repair` refuses a file it can't lock, +since a recorder still has it open and repairing it would corrupt it. A filesystem +without file locks (some network mounts) is refused by both: the recorder won't start there. + ```bash moq ... export mp4 --output recording.mp4 moq repair mp4 recording.mp4 diff --git a/quest/m1/mp4-repair-lock.md b/quest/m1/mp4-repair-lock.md deleted file mode 100644 index dcd6210d162..00000000000 --- a/quest/m1/mp4-repair-lock.md +++ /dev/null @@ -1,22 +0,0 @@ -# [XS] moq repair refuses a recording still being written - -## Goal - -`moq export mp4 --output ` holds an advisory lock on its output while it records, and `moq repair mp4 ` refuses, with a message saying a recorder still has it open, when it can't take that lock. Neither side runs unlocked: where the filesystem can't lock, both refuse. Repairing a file mid-recording no longer corrupts it. - -## Plan - -Found by [moq-dev/moq#7560](https://github.com/moq-dev/moq/pull/7560), which adds `moq repair mp4`: it can't tell a running `export mp4` still writes the file, and repairing one corrupts it. #7560 merged 2026-11-02. - -Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-afk run): an advisory lock taken by the recorder and checked by repair, as #7560 suggested. - -- The CLI owns the lock, not moq-mux: `repair` in moq-mux takes `impl Read + Seek` and stays file-agnostic. Use an exclusive `flock`-style lock on the open file (`std::fs::File::try_lock` is stable in Rust 1.89), held for the recording's life and released by the OS if the recorder dies, so a crashed recording stays repairable. -- Supported or refused (`AGENTS.md`), on both sides. The recorder fails at startup if it can't take the lock, a filesystem without lock support included, since its recording could never be repaired safely. `repair` takes the same lock non-blocking before scanning and refuses if it can't: held means a recorder still has the file open, and any other lock error (no lock support) refuses with that error rather than repairing unlocked. -- Test: a held lock makes `moq repair mp4` refuse and leave the file untouched; #7560's nightly `export::a_killed_mp4_recording_is_repaired` still repairs after SIGKILL, since the lock dies with the process. -- Update `doc/bin/cli.md`'s `repair mp4` entry. - -Public API: none (CLI behavior only). Wire: none. - -## Related - -- [An interrupted mp4 recording keeps its last fragment](/doc/bin/cli.md#export) - the other half of recording durability diff --git a/rs/moq-cli/src/repair.rs b/rs/moq-cli/src/repair.rs index 8f2499ce2c7..151baaa3e81 100644 --- a/rs/moq-cli/src/repair.rs +++ b/rs/moq-cli/src/repair.rs @@ -46,6 +46,19 @@ impl Mp4 { .write(true) .open(&path) .with_context(|| format!("failed to open {}", path.display()))?; + // Held for the repair's life: an `export mp4` recording holds it until it closes the file, + // so a file we can't lock is still being written, and repairing it would corrupt it. + // A filesystem without locks refuses too, since the recorder refuses to start there. + match file.try_lock() { + Ok(()) => {} + Err(std::fs::TryLockError::WouldBlock) => anyhow::bail!( + "{} is still open by a recorder (or another repair); repair it once that finishes", + path.display() + ), + Err(std::fs::TryLockError::Error(err)) => { + return Err(err).with_context(|| format!("failed to lock {}", path.display())); + } + } let (file, finish) = tokio::task::spawn_blocking(move || { let mut file = file; let finish = moq_mux::container::mp4::repair(&mut file); diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index abf09dbe255..948ba056314 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -386,9 +386,20 @@ impl Subscribe { let mut mp4 = moq_mux::container::mp4::Export::new(self.source, stream) .with_delay(Delay::default().with_max(self.args.max_delay)) .with_fragment_duration(self.args.fragment_duration); - let mut file = tokio::fs::File::create_new(&path) + let file = tokio::fs::File::create_new(&path) .await - .with_context(|| format!("failed to create {}", path.display()))?; + .with_context(|| format!("failed to create {}", path.display()))? + .into_std() + .await; + // Held until the file closes, which `moq repair mp4` reads as a recorder still writing. + // The OS drops it with a killed recorder, so that recording stays repairable. A file that + // can't be locked could never be repaired safely, so it isn't recorded. + if let Err(err) = file.try_lock() { + drop(file); + tokio::fs::remove_file(&path).await?; + return Err(err).with_context(|| format!("failed to lock {}, so it could not be repaired", path.display())); + } + let mut file = tokio::fs::File::from_std(file); // A failed export still finishes what it recorded; a failed write leaves the file as is. let mut stopped = false; diff --git a/rs/moq-cli/tests/integration/export.rs b/rs/moq-cli/tests/integration/export.rs index 51ece221a0e..e5b096573db 100644 --- a/rs/moq-cli/tests/integration/export.rs +++ b/rs/moq-cli/tests/integration/export.rs @@ -1115,6 +1115,48 @@ async fn a_passthrough_export_ends_with_its_redundant_importer() { feeding.abort(); } +/// `repair mp4` refuses a file something else holds the lock on, as a recorder does while it +/// writes, and leaves it untouched. +#[tokio::test] +async fn repair_refuses_a_locked_recording() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("recording.mp4"); + std::fs::write(&path, b"not scanned: the lock refuses first").unwrap(); + let recorder = std::fs::File::open(&path).unwrap(); + recorder.try_lock().unwrap(); + + let output = moq_repair(&path).await; + assert!(!output.status.success(), "repaired a file a recorder holds"); + assert!( + String::from_utf8_lossy(&output.stderr).contains("still open by a recorder"), + "{}", + String::from_utf8_lossy(&output.stderr) + ); + assert_eq!(std::fs::read(&path).unwrap(), b"not scanned: the lock refuses first"); + + // Once the recorder lets go, the file is scanned instead. + drop(recorder); + let output = moq_repair(&path).await; + assert!( + !String::from_utf8_lossy(&output.stderr).contains("still open by a recorder"), + "{}", + String::from_utf8_lossy(&output.stderr) + ); +} + +/// Run `moq repair mp4` on the file. +async fn moq_repair(path: &std::path::Path) -> std::process::Output { + let output = tokio::process::Command::new(env!("CARGO_BIN_EXE_moq")) + .env_remove("KIO_DENY_HOST_TIMERS") + .args(["repair", "mp4"]) + .arg(path) + .output(); + kio::clock::timeout(TIMEOUT, output) + .await + .expect("repair never exited") + .unwrap() +} + /// `repair mp4` finishes a recording whose `export mp4` was killed as a regular MP4, and leaves /// it alone once finished. #[tokio::test] @@ -1137,6 +1179,16 @@ async fn a_killed_mp4_recording_is_repaired() { }) .await .expect("the recording never grew"); + // The recorder holds its lock while it writes, so repairing now would corrupt the file. + let mid = std::fs::read(&path).unwrap(); + let refused = moq_repair(&path).await; + assert!(!refused.status.success(), "repaired a recording still being written"); + assert!(String::from_utf8_lossy(&refused.stderr).contains("still open by a recorder")); + assert!( + std::fs::read(&path).unwrap().starts_with(&mid), + "a refused repair rewrote the file" + ); + recording.kill().await.unwrap(); let killed = std::fs::read(&path).unwrap(); assert_eq!( @@ -1146,15 +1198,7 @@ async fn a_killed_mp4_recording_is_repaired() { ); let repair = || async { - let output = tokio::process::Command::new(env!("CARGO_BIN_EXE_moq")) - .env_remove("KIO_DENY_HOST_TIMERS") - .args(["repair", "mp4"]) - .arg(&path) - .output(); - let output = kio::clock::timeout(TIMEOUT, output) - .await - .expect("repair never exited") - .unwrap(); + let output = moq_repair(&path).await; assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr)); std::fs::read(&path).unwrap() }; From 563dbaf74e0734b7f57db7698b3d6ceb48bee5de Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 15 Nov 2026 04:49:33 -0800 Subject: [PATCH 3/4] fix(cli): repair refuses on any lock failure instead of matching the error Co-Authored-By: Claude Sonnet 5.5 --- rs/moq-cli/src/repair.rs | 14 +++++--------- rs/moq-cli/tests/integration/export.rs | 6 +++--- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/rs/moq-cli/src/repair.rs b/rs/moq-cli/src/repair.rs index 151baaa3e81..44fba1995a7 100644 --- a/rs/moq-cli/src/repair.rs +++ b/rs/moq-cli/src/repair.rs @@ -49,16 +49,12 @@ impl Mp4 { // Held for the repair's life: an `export mp4` recording holds it until it closes the file, // so a file we can't lock is still being written, and repairing it would corrupt it. // A filesystem without locks refuses too, since the recorder refuses to start there. - match file.try_lock() { - Ok(()) => {} - Err(std::fs::TryLockError::WouldBlock) => anyhow::bail!( - "{} is still open by a recorder (or another repair); repair it once that finishes", + file.try_lock().with_context(|| { + format!( + "failed to lock {}, so it may still be open by a recorder", path.display() - ), - Err(std::fs::TryLockError::Error(err)) => { - return Err(err).with_context(|| format!("failed to lock {}", path.display())); - } - } + ) + })?; let (file, finish) = tokio::task::spawn_blocking(move || { let mut file = file; let finish = moq_mux::container::mp4::repair(&mut file); diff --git a/rs/moq-cli/tests/integration/export.rs b/rs/moq-cli/tests/integration/export.rs index e5b096573db..ed0893b6e31 100644 --- a/rs/moq-cli/tests/integration/export.rs +++ b/rs/moq-cli/tests/integration/export.rs @@ -1128,7 +1128,7 @@ async fn repair_refuses_a_locked_recording() { let output = moq_repair(&path).await; assert!(!output.status.success(), "repaired a file a recorder holds"); assert!( - String::from_utf8_lossy(&output.stderr).contains("still open by a recorder"), + String::from_utf8_lossy(&output.stderr).contains("may still be open by a recorder"), "{}", String::from_utf8_lossy(&output.stderr) ); @@ -1138,7 +1138,7 @@ async fn repair_refuses_a_locked_recording() { drop(recorder); let output = moq_repair(&path).await; assert!( - !String::from_utf8_lossy(&output.stderr).contains("still open by a recorder"), + !String::from_utf8_lossy(&output.stderr).contains("may still be open by a recorder"), "{}", String::from_utf8_lossy(&output.stderr) ); @@ -1183,7 +1183,7 @@ async fn a_killed_mp4_recording_is_repaired() { let mid = std::fs::read(&path).unwrap(); let refused = moq_repair(&path).await; assert!(!refused.status.success(), "repaired a recording still being written"); - assert!(String::from_utf8_lossy(&refused.stderr).contains("still open by a recorder")); + assert!(String::from_utf8_lossy(&refused.stderr).contains("may still be open by a recorder")); assert!( std::fs::read(&path).unwrap().starts_with(&mid), "a refused repair rewrote the file" From 27bd1c4c09d8e9ea5f11584a840786dd678fe873 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 04:55:33 -0800 Subject: [PATCH 4/4] docs(cli): say the recorder's lock blocks readers on Windows Co-Authored-By: Claude Opus 5.5 --- doc/bin/cli.md | 2 ++ rs/moq-cli/src/subscribe.rs | 2 ++ 2 files changed, 4 insertions(+) diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 1aa696e150c..51bf12f493a 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -166,6 +166,8 @@ The recorder holds an exclusive file lock on its output while it records, and th OS drops the lock with a killed recorder. `repair` refuses a file it can't lock, since a recorder still has it open and repairing it would corrupt it. A filesystem without file locks (some network mounts) is refused by both: the recorder won't start there. +On Windows the lock also blocks other programs from reading the file until the +recording finishes, so copy or preview it afterwards. ```bash moq ... export mp4 --output recording.mp4 diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index 948ba056314..c82f5feab71 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -394,6 +394,8 @@ impl Subscribe { // Held until the file closes, which `moq repair mp4` reads as a recorder still writing. // The OS drops it with a killed recorder, so that recording stays repairable. A file that // can't be locked could never be repaired safely, so it isn't recorded. + // On Windows the lock is mandatory and also blocks other readers; a shared lock wouldn't + // help, since it denies writes to the handle holding it too. if let Err(err) = file.try_lock() { drop(file); tokio::fs::remove_file(&path).await?;