Repository navigation
fix(mux): a cut-short mp4 finish repairs, and only a verified index counts as finished - #9124
Conversation
Quest-Claim: a300c53756eb66bb
…ounts as finished repair read the reserved slot as a box, so a torn mdat header (8 of its 16 bytes) made it refuse a file whose media and moov were intact, and any mdat there counted as finished even with the trailing moov missing. It now reads the slot as bytes, rebuilds the index from the fragments, and reports a file finished only when the header and trailing moov are exactly what finishing writes. Finish::write durably makes the writes at the format layer, replacing the CLI's write_finish: cut and sync, append the moov, write the header's size before its type, then sync, so every crash point still plays and repairs to the same finish. Finish's fields are private now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iling moov A finish cut short after the header's size marker leaves the reserved box a 64-bit box that skips the fragmented moov, so cutting the trailing moov first left a repair interrupted there with no moov a player reaches. Finish now makes the box free again, synced, before the cut. The crash model also crashes each such repair. The export flushes before converting its tokio file, which otherwise drops the error of a write still in flight. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 19 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. |
There was a problem hiding this comment.
✅ No new issues found.
Approach: sound. The fix moves the durable write order into the format layer (Finish::write), so the CLI export and repair now share it. repair reads the reserved slot as raw bytes and accepts the file as finished only when it matches the rebuilt finish byte for byte. A torn header and a missing or altered trailing moov therefore both go through the same repair.
Reviewed changes. I read the whole diff, traced the write order against each torn-slot state, and ran cargo test -p moq-mux --lib container::mp4 locally. All 13 tests passed, including both new tests.
Finish::write/write_to: when needed it reopens the slot tofreeand syncs. It then cuts the file and syncs, appends themoov, writes the size into thefreebody and syncs, then writes00000001 mdatand syncs. Before that last write, the slot never reads as a 64-bitmdatwhose size has not reached the disk.repairslot check: a byte that matches neitherFREEnor the rebuiltmdatheader refuses the file.Nonenow requires the trailing bytes to equal the rebuiltmoovexactly and the slot to equal themdatheader.reopenis set wheneverslot[..8]is no longerfree's.Finishfields made private: I checked thatmp4.rsis absent fromrelease, so no published API breaks.- CLI:
run_mp4flushes the tokio file beforeinto_std, so an error from a write still in flight is returned rather than dropped.subscribe::write_finishis removed, andrepair.rscallsFinish::writeinsidespawn_blocking. - Crash model tests:
crashesbuilds every crash state: what was synced, plus each later call either lost or made, with writes torn inside their leading box header or trailing bytes. Every state must play, repair to the sameFinish, and come out byte-identical. Repairs of files whose slot is no longerfreeare crashed again.
claude-opus-5-5 | 𝕏
|
Merge pick (maintainer away, granted the coordinator merges it confidently recommends): ✅ /quest-merge, accepting the decisions listed in the PR body. (Written by Claude Opus 5.5 with high) |

Problem
The pre-cut audit found two holes in
moq repair mp4and themoq export mp4finish:mdatheader (for example, only the first 8 bytes written,00000001 'mdat'plus zeros) left all the media and the finalmoovon disk, but repair read the reserved slot as a box, could not parse it, and refused the file.moovremoved or cut counted as "already finished", because anymdatin the reserved slot did. ffprobe could not open that file.The finish's durable write sequence also lived in the CLI (
write_finish), so no other file-backed caller could finish a recording safely.Approach
repairreads the reserved slot as bytes, always parses the fragmentedmoovright after it (a finish never moves it), and rebuilds the index from the fragments. It reports a file as finished only when the slot and the trailingmoovare exactly what finishing writes. Otherwise it returns the finish, so a torn header, a missing, cut, extended, or alteredmoov, and a never-finished recording all repair to the same result. A slot whose bytes are not each thefreebox's or themdatheader's is refused as not a recording.mp4::Finish::write(&self, &mut std::fs::File)makes the writes durably at the format layer, and the CLI's export and repair both use it:0. Repair only: if a cut-short finish left the slot's first 8 bytes a header (which skips the fragmented
moov), write them back tofree, then sync. Otherwise cutting the trailingmoovwould leave a crash with nomoova player reaches.moov.freebox body, then sync.mdattype), then sync.Until that last write, the slot reads as a box a player skips (
free, a 64-bitfree, or a kind it does not know), never a brokenmdatheader. So every crash point leaves a file that plays as-is, in a finish and in the repair of any crashed file. This takes three syncs instead of two, and a fourth when a repair reopens the slot.moq export mp4flushes its tokio file before converting it, sinceinto_stddrops the error of a write still in flight.Finish's fields are private now, so nothing can make the writes in an unsafe order.Validation
a_finish_interrupted_anywhere_plays_and_repairsrecords the callsFinish::writemakes through a privateDisktrait. It then builds every file a crash could leave: what was synced, plus each call since lost or made, with writes torn at every byte of their leading box header and trailing bytes. It does this for three starting files: a clean recording, one cut mid-fragment, and one cut mid-description, where the leftover tail is longer than themoov. Every crashed file must:moova box-walking reader reaches is the fragmented one or the final one;Finish;free, also survive a crash at any point of its own repair: every file that leaves must play and repair the same.mdattype before its size fails it ("crash 1106 left a file no player reads"). Dropping the sync after the cut fails it too: a moov-prefixed tail reads as afreebox holding neither a fragment nor a moov. Skipping the slot reopen fails it ("crash 347, 2 left a file no player reads"). Dropping the sync between themoovand the header size passes, correctly, since the size lands in thefreebox body, so that sync was removed.only_a_verified_index_counts_as_finishedcovers a header torn first-to-last (the old order) and last-to-first at every length. It also covers amoovremoved, cut at 1 byte, 8 bytes, and all but 1, extended with junk, or with a changed chunk offset. All repair to the same finish. Garbage in the slot and a plain fMP4 are refused.moq-relay,moq import tsofbbb5s_cbr.ts(HEVC and Opus) at about real time, andmoq export mp4 --outputproduced the clean file (ffmpeg 9 ffprobe: 120 video and 231 audio frames). Six damaged copies were run through the builtmoq repair mp4: header torn after 8 bytes, after 4 bytes, and with only its last 8 written;moovstripped;moovcut in half;moovstripped plus a torn header. Before repair, ffprobe failed on all but the last-8 state ("moov atom not found" / "error reading header"). After repair, every copy was byte-identical to the clean file with 120/231 frames, and a second repair logged "recording already finished".00000010 free,00000001 free,00000001 mree,mdee,mdae, each with the size already written) decodes all 120/231 frames without repair.just cipassed on the head (4892 tests).just rs cli-exportpassed (16 real-process export tests, includinga_killed_mp4_recording_is_repairedandan_interrupted_mp4_recording_is_finished).Impact
moq_mux::container::mp4::Finishgainswrite(&self, &mut std::fs::File) -> std::io::Result<()>, and its fieldsmoov_offset,moov,mdat_offset,mdatbecome private. The type is not onrelease, so no published API changes and the title takes no!. Amaincaller that made the writes itself callsfinish.write(&mut file)instead.repairnow returnsSomefor a regular MP4 that only looks finished, and refuses a file whose reserved slot is neitherfreenor itsmdatheader. Before, it returnedNonefor anymdatthere.moq repair mp4finishes torn or index-less files it used to refuse or skip.moq export mp4makes one more sync when it finishes. No flag changes. Wire: none.Decisions
moovis byte-identical to the rebuilt one. If a later build changes howIndex::finishencodes themoov, repairing a file finished by an older build rewrites itsmoov(and logs "repaired") instead of leaving it alone. That rewrite is harmless: same media, valid index. The rejected alternative was a structural check (themoovdecodes and its chunks lie inside themdat), which would accept a corrupted index that still decodes.free, since only those repairs write anything a finish does not (all nested crashes took 28s).Finish::writetakes&std::fs::File, not a generic writer. It needsset_lenand sync, and every file-backed caller has astd::fs::File(the tokio export converts withinto_std).Alternatives
Finish's fields public for non-file writers: no such consumer exists, and public fields let a caller reproduce the unsafe write order this PR fixes.writereturns only after its final sync.Caused by
repairparsed the reserved slot as a box, so it refused a tornmdatheader and counted anymdatthere as finished without checking the trailingmoov(found by check: the November 17-18 pre-cut audit)Follow-ups
None.
Models
Size: M
Implementer: Claude Code, claude-opus-5-5, high effort (arm A)
🤖 Generated with Claude Code
(Written by Claude Opus 5.5 with high)
Review
Rewritten by
quest reviewafter each round.Head: 7462f56
Base: origin/main at 1599097
Risk: high,
The change rewrites and truncates users’ recordings in place, so a regression could damage media that reverting the code cannot restore.Classified: medium by default
Reviewer: Codex, gpt-6.1-sol, high effort
Session:
01a1f0f5-76ba-7263-a645-77cbe8c2840a, round 2Score: 10/10,
Both earlier findings are fixed, and code review of the incremental changes found no new issues; builds and tests were not run.Raised the risk to high:
The change rewrites and truncates users’ recordings in place, so a regression could damage media that reverting the code cannot restore.Rounds: 2; first round 2 (medium 2); findings 2 (medium 2): fixed 2, refuted 0, open 0
Findings: none
The last round's findings, at 5775b28:
rs/moq-mux/src/container/mp4.rs:94:Expose the fragmented index before truncating during repair;repair sets Finish::reopen for a modified reserved header, and Finish::write_to restores and syncs its first eight bytes before truncating; the expanded test covers interrupted repairs of torn headers.rs/moq-cli/src/subscribe.rs:428:Flush pending media writes before converting the file;run_mp4 now calls file.flush().await? before into_std(), propagating any pending media-write failure before finalization.