Repository navigation
feat(export): add cancellation and progress to exporters - #247
Conversation
Add token/progress overloads for document and assembly exports: nwc, GLB, IFC, OBJ, JSON, BCF, viewpoints XML, clash HTML and the HTML viewer. Existing Save* signatures are unchanged. The overloads check cancellation before and after the exporter and report export-* 0/1 progress; async wrappers now pass the token into them. Add four regression tests.
Код-ревью — feat(export): add cancellation and progress to exporters (стек на #244)Вердикт: approve-with-comments Резюме ревьюеров
Подтверждённые замечания (4)1. [СРЕДНЯЯ] NwcAssembly.SaveJson(path, ..., ct) усекает существующий файл до проверки токена отмены — В перегрузке с путём File.Create(path) выполняется до вызова SaveJson(Stream, ..., ct), где находится первая проверка ThrowIfCancellationRequested. Файл создаётся/усекается до нуля байт, затем бросается OperationCanceledException. Все остальные path-перегрузки в PR (GLB, OBJ, IFC, BCF, HTML, документный SaveJson) вызывают проверку до того, как экспортёр создаёт файл; NwcWriter.Write специально сериализует до File.Create, чтобы не усекать файл при сбое. Здесь это правило нарушено. Уточнение проверяющего: Путь SaveJson(string path, ..., ct) создаёт и усекает файл (File.Create, строка 808) до первой проверки отмены в SaveJson(Stream, ...) (строка 738). Если токен уже отменён, прежний валидный файл теряется и остаётся пустой, хотя вызывающий ожидает отсутствия побочных эффектов. Исправление: добавить cancellationToken.ThrowIfCancellationRequested() перед File.Create и тест на то, что существующий файл не усечён. Сценарий: На диске лежит корректный summary.json от прошлого экспорта. Пользователь вызывает assembly.SaveJson("summary.json", null, progress, token) с уже отменённым токеном (например, в цикле пакетного экспорта токен отменили между итерациями). File.Create обнуляет файл, затем SaveJson(fs, ...) бросает OperationCanceledException. Прежний валидный файл потерян, остался пустой файл размером 0 байт, хотя вызывающий код считает, что отмена не оставила побочных эффектов. Теста на это нет: отмена для assembly.SaveJson в ExportCancellationTests не проверяется (проверяется только прогресс на MemoryStream). Исправление: Вызвать cancellationToken.ThrowIfCancellationRequested() в path-перегрузке до File.Create (или вынести общую проверку и репорт 0/1 перед созданием файла), и добавить тест на то, что существующий файл не усечён при уже отменённом токене. Независимо нашли также: tests-claims, robustness 2. [НИЗКАЯ] Тест SaveJsonAsync_CanceledToken_IsCanceled проходит и без изменений PR, не проверяет проброс токена — Токен отменён до вызова, а SaveAsync — это Task.Run(delegate, token). Для уже отменённого токена Task.Run возвращает Canceled-задачу, не запуская делегат вообще, поэтому ThrowsAnyAsync выполняется независимо от того, передан ли токен внутрь SaveJson. Этот же тест проходил бы на базовой ветке (#244), где токен в SaveJson не передавался. Заявленное в PR поведение «SaveAsync wrappers now pass the token into these overloads» тестом не подтверждается. Уточнение проверяющего: Тест SaveJsonAsync_CanceledToken_IsCanceled не отличает старую реализацию от новой, потому что проверяет только предотменённый токен, который Task.Run обрабатывает сам. Проброс токена в sync-перегрузки и отмену после старта делегата он не проверяет. Это пробел в тестах, а не дефект продакшен-кода, поэтому severity снижена до medium. Синхронные перегрузки SaveGlb/SaveJson с токеном покрыты первым тестом. Сценарий: Если убрать из SaveJsonAsync передачу токена (вернуть Task.Run(() => SaveJson(path, options), cancellationToken)) или сломать любую из остальных 13 async-обёрток, тест останется зелёным. Регрессию проброса токена и отмену после старта делегата (проверка внутри экспортёра) тест не поймает. Остальные три теста покрывают лишь предпроверку для GLB/JSON и конечный репорт прогресса; IFC, OBJ, BCF, viewpoints XML/BCF, HTML, .nwc и post-check не тестируются вообще, хотя описание PR утверждает покрытие stream-вариантов GLB/IFC/OBJ/JSON/BCF. Исправление: Сделать тест, в котором токен отменяется уже после старта делегата (например, через IProgress, отменяющий CTS при репорте export-json 0/1, вызываемый из sync-перегрузки), либо вызывать sync-перегрузку с отменой изнутри Progress; добавить тесты хотя бы на по одной перегрузке IFC/OBJ/BCF/.nwc. 3. [НИЗКАЯ] Тест SaveJsonAsync_CanceledToken_IsCanceled проходит и без изменений PR (тавтология) — Тест передаёт уже отменённый токен в SaveJsonAsync. До PR обёртка уже была Task.Run(() => SaveJson(path, options), cancellationToken), а Task.Run с предварительно отменённым токеном возвращает отменённую задачу, не запуская делегат вообще. Поэтому тест проходит и на базе (#244), и не доказывает заявленное в PR и CHANGELOG: 'SaveAsync wrappers now pass the token into these overloads'. Внутренние ThrowIfCancellationRequested в новых перегрузках в этом тесте не достигаются. Нет теста ни на одну другую SaveAsync обёртку. Уточнение проверяющего: Тест на Async-обёртку проходит и без передачи токена в перегрузки: предотменённый токен отменяет сам Task.Run, делегат не вызывается. Проброс токена в SaveAsync и отмена после старта задачи не покрыты. Остальные SaveAsync обёртки тестами не покрыты вообще. Это пробел в тестах, дефекта в продакшн-коде нет. Сценарий: Откатить изменения всех строк Save*Async в NwcDocument.cs до Task.Run(() => SaveJson(path, options), cancellationToken) (то есть без передачи токена в перегрузки). Тест останется зелёным, хотя заявленное поведение 'токен проходит в экспортёр' пропало. Токен, отменённый после старта задачи (например, во время записи), не покрыт ни одним тестом. Исправление: Отменять токен уже после старта задачи, например через Stream-обёртку, чья Write вызывает cts.Cancel(), и ожидать OperationCanceledException из пост-проверки; или проверять, что делегат вызывается и бросает отмену, а не только Task.Run. 4. [НИЗКАЯ] Отмена во время FindClashes не прерывает экспорт: файл всё равно перезаписывается — В SaveBcf(path/stream) и SaveClashReportHtml(path) единственная долгая операция (FindClashes, перебор пар моделей с пространственными индексами) выполняется между проверкой «до» и проверкой «после» и сама токен не принимает. Между FindClashes() и записью проверки токена нет, поэтому после возврата из FindClashes экспортёр безусловно пишет файл и только потом бросает OperationCanceledException. Уточнение проверяющего: При отмене во время FindClashes (он токен не принимает и не прерывается) SaveBcf(path/stream) и SaveClashReportHtml(path) всё равно выполняют запись: File.Create усекает целевой файл, а в stream попадают данные, и только затем бросается OperationCanceledException. Добавление cancellationToken.ThrowIfCancellationRequested() после Сценарий: Большая федерация, FindClashes занимает минуты. Пользователь отменяет через 5 секунд. Метод продолжает считать клэши до конца, затем BcfExporter.WriteFile через File.Create перезаписывает существующий report.bcf полностью новым содержимым и лишь после этого бросает OperationCanceledException. Отмена фактически не работает для самой дорогой части, а целевой файл всё равно изменён. То же в строках 580 (stream: данные уже записаны в поток вызывающего) и 661 (HTML-отчёт). Исправление: Добавить cancellationToken.ThrowIfCancellationRequested() сразу после clashes ??= FindClashes() и до записи (во всех трёх местах). |
Assembly SaveJson checks the token before File.Create, JSON exports honour a cancel requested from the 0/1 progress report, and clash BCF/HTML exports check again after FindClashes before touching the destination.
Assembly SaveJson writes to a sibling temporary file and moves it over the target only after success; mid-export cancellation no longer truncates the old file, and the progress test asserts the file content.
Adds the export side of #111. Stacked on #244 (
fix/reader-cancellation).What changed
.nwc(path and stream), GLB (path/stream), IFC (path/writer), OBJ (path/writer), JSON (path/stream), viewpoints BCF (path/stream), viewpoints XML and the HTML viewer.Save*signatures are unchanged; the new overloads checkThrowIfCancellationRequestedbefore and after the exporter and reportexport-glb,export-ifc,export-obj,export-json,export-bcf,export-nwc,export-viewpoints-xmlorexport-htmlwith0/1then1/1.Save*Asyncwrappers now pass the token into these overloads instead of only cancelling the outerTask.Run.ExportCancellationTests: document GLB/JSON cancel, document progress, assembly cancel/progress, async cancellation.Files
src/NwcIO/NwcDocument.cssrc/NwcIO/Model/NwcAssembly.cstests/NwcIO.Tests/ExportCancellationTests.csdocs/public-api.mdCHANGELOG.mdTests
dotnet build NwcIO.slnx -c Release— success, 0 warnings, 0 errors.dotnet test NwcIO.slnx -c Release --no-build— full suite passes (exit 0).ExportCancellationTests: 4 passed.Remaining limitations
Save*Asyncstill usesTask.Run; the underlying sync exporter is token-aware at its boundaries.