[bezzad]

Fixes #259.

Problem

To save a DownloadPackage for resume while it downloads, the safe order is: serialize the package, flush, then save the bytes. But ConcurrentStream.FlushAsync could not do this:

1. It waited until the write queue was empty. While chunks write faster than the disk, the queue is never empty, so the flush did not end.
2. On a FileStream it called Flush(false): the bytes stayed in the OS cache, not on the disk.
3. When the stream was closed with blocks still in the queue, it returned with no error, but those blocks were dropped.
4. The flush ran on the caller's thread, while the writer task could write to the same stream.

Fix

• FlushAsync adds a small flush marker (a Packet with no bytes and a TaskCompletionSource) to the write queue and waits only for it. The queue is FIFO with one writer, so every block given before the call is written first.
• The writer task flushes the base stream when it takes the marker (FileStream.Flush(true), else FlushAsync), so a flush never runs at the same time as a write.
• A marker is not data: no progress, no buffer size.
• If the writer fails, FlushAsync throws the writer's error. If the stream is closed first, it throws ObjectDisposedException. It never hangs.
• The 20 ms Task.Delay in DownloadPackage.FlushInternalAsync is removed (it is not needed now).
• XML docs on DownloadPackage.FlushAsync and ConcurrentStream.FlushAsync show the safe order.
• No public API change. AbstractDownloadService.UpdatePackage needs no change: its metadata goes through the same FIFO queue after the blocks it counts.

Tests

New file UnitTests/ConcurrentStreamFlushTest.cs. The first commit has only the tests; these 5 fail on the old code:

• FlushAsyncEndsWhileOtherWritesKeepComing
• FlushAsyncWritesEveryBlockGivenBeforeIt
• PackageFlushAsyncEndsWhileChunksKeepWriting
• FlushAsyncOnAFileStreamWritesToTheDisk
• FlushAsyncDoesNotReportSuccessWhenTheStreamIsClosedBeforeTheBytesAreWritten

The guard test FlushAsyncThrowsTheWriterErrorWhenTheWriterFailsDuringTheFlush keeps the error path working.

Local run (net10.0): build has 0 warnings, and all 714 tests pass.

Notes

• OpenSpec change: openspec/changes/reliable-flush.
• This is related to Fix the critical and high issues of the 7.0.1 review #258: there, writer-queue-accounting (M1) plans "count pending blocks and wait for zero". That would also never end during a running download. The marker here fixes M1 as well. ConcurrentPacketBuffer.WaitToComplete is not used by the stream any more; I left it in place to avoid a conflict with Fix the critical and high issues of the 7.0.1 review #258, and it can be removed after that PR is merged.

---

Generated by Claude Code