diff --git a/doc/bin/cli.md b/doc/bin/cli.md index 647603af6c0..978768aad8d 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -162,6 +162,13 @@ 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. +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 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..44fba1995a7 100644 --- a/rs/moq-cli/src/repair.rs +++ b/rs/moq-cli/src/repair.rs @@ -46,6 +46,15 @@ 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. + file.try_lock().with_context(|| { + format!( + "failed to lock {}, so it may still be open by a recorder", + 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..c82f5feab71 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -386,9 +386,22 @@ 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. + // 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?; + 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 6088fdb167f..464dc59520f 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("may still be 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("may still be 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("may still be 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() };