Skip to content

feat(export): add cancellation and progress to exporters - #247

Merged
mahach666 merged 6 commits into
mainfrom
fix/export-cancellation
Nov 16, 2026
Merged

mahach666 merged 6 commits into
mainfrom
fix/export-cancellation

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Adds the export side of #111. Stacked on #244 (fix/reader-cancellation).

What changed

  • Added cancellation/progress overloads for document exports:
    • .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.
  • Added the same for assembly exports: GLB, IFC, OBJ, BCF (path/stream), viewpoints BCF/XML, JSON (path/stream), clash HTML and the HTML viewer.
  • Existing Save* signatures are unchanged; the new overloads check ThrowIfCancellationRequested before and after the exporter and report export-glb, export-ifc, export-obj, export-json, export-bcf, export-nwc, export-viewpoints-xml or export-html with 0/1 then 1/1.
  • Save*Async wrappers now pass the token into these overloads instead of only cancelling the outer Task.Run.
  • Added ExportCancellationTests: document GLB/JSON cancel, document progress, assembly cancel/progress, async cancellation.

Files

  • src/NwcIO/NwcDocument.cs
  • src/NwcIO/Model/NwcAssembly.cs
  • tests/NwcIO.Tests/ExportCancellationTests.cs
  • docs/public-api.md
  • CHANGELOG.md

Tests

  • 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

  • Cancellation is checked before and after each exporter, not inside the GLB/IFC/OBJ writers.
  • Export progress is a single 0/1 phase, not per mesh or per entity.
  • Save*Async still uses Task.Run; the underlying sync exporter is token-aware at its boundaries.
  • Stream variants are covered for GLB/IFC/OBJ/JSON/BCF, not every HTML/XML path combination.

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.
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — feat(export): add cancellation and progress to exporters (стек на #244)

Вердикт: approve-with-comments

Резюме ревьюеров

  • correctness: PR добавляет перегрузки Save*/Export* с IProgress и CancellationToken для NwcDocument и NwcAssembly. Каждая перегрузка проверяет токен до и после экспортёра и репортит одну фазу 0/1 → 1/1, а Save*Async для документа теперь передают токен внутрь. Механическая часть сделана аккуратно (старые сигнатуры делегируют новым, неоднозначности перегрузок нет). С точки зрения корректности есть три реальные проблемы: NwcAssembly.SaveJson(path, ..., ct) усекает существующий файл до проверки токена, экспорты по клэшам продолжают писать файл после отмены во время FindClashes, а единственный тест async-обёртки ничего не проверяет в рамках PR. Кроме того, документация перечисляет фазы неполно.
  • robustness: PR добавляет к экспортёрам документа и сборки перегрузки с IProgress и CancellationToken. Каждая перегрузка проверяет токен до и после вызова существующего экспортёра и репортит фазу 0/1 и 1/1, а Save*Async теперь передают токен внутрь. Старые сигнатуры сохранены, перегрузки только добавляются, так что обратная совместимость по API в порядке. С точки зрения устойчивости есть проблемы: проверка токена после экспорта сообщает об отмене при уже полностью записанном выводе, а assembly.SaveJson(path) обнуляет существующий файл до проверки токена. Токен не доходит до FindClashes() (самой дорогой части clash-экспортов). Тесты покрывают малую часть перегрузок, и тест async-отмены проходит и без изменений PR.
  • tests-claims: PR добавляет около 40 перегрузок Save*/SaveJson/SaveBcf/SaveHtmlViewer в NwcDocument и NwcAssembly с параметрами IProgress и CancellationToken. Перегрузка проверяет токен до и после экспортёра и шлёт одну пару отчётов 0/1 и 1/1; Save*Async у NwcDocument передают токен в эти перегрузки. Сами перегрузки механические и единообразные, но у линзы тестов и заявлений есть существенные проблемы. Перегрузка NwcAssembly.SaveJson(path) открывает файл с усечением до проверки токена и разрушает существующий файл. Единственный async-тест не проверяет заявленное поведение. Тесты закрывают малую часть заявленных перегрузок, а документация перечисляет не все фазы прогресса.

Подтверждённые замечания (4)

1. [СРЕДНЯЯ] NwcAssembly.SaveJson(path, ..., ct) усекает существующий файл до проверки токена отмены — src/NwcIO/Model/NwcAssembly.cs:808 (correctness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

В перегрузке с путём 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).

ArgumentException.ThrowIfNullOrEmpty(path);
using var fs = File.Create(path);
SaveJson(fs, options, progress, cancellationToken);

Исправление: Вызвать cancellationToken.ThrowIfCancellationRequested() в path-перегрузке до File.Create (или вынести общую проверку и репорт 0/1 перед созданием файла), и добавить тест на то, что существующий файл не усечён при уже отменённом токене.

Независимо нашли также: tests-claims, robustness

2. [НИЗКАЯ] Тест SaveJsonAsync_CanceledToken_IsCanceled проходит и без изменений PR, не проверяет проброс токена — tests/NwcIO.Tests/ExportCancellationTests.cs:59 (test-quality; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Токен отменён до вызова, а 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.

await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
    document.SaveJsonAsync(Path.GetTempFileName(), cancellationToken: cancellation.Token));

Исправление: Сделать тест, в котором токен отменяется уже после старта делегата (например, через IProgress, отменяющий CTS при репорте export-json 0/1, вызываемый из sync-перегрузки), либо вызывать sync-перегрузку с отменой изнутри Progress; добавить тесты хотя бы на по одной перегрузке IFC/OBJ/BCF/.nwc.

3. [НИЗКАЯ] Тест SaveJsonAsync_CanceledToken_IsCanceled проходит и без изменений PR (тавтология) — tests/NwcIO.Tests/ExportCancellationTests.cs:53 (test-quality; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Тест передаёт уже отменённый токен в 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) (то есть без передачи токена в перегрузки). Тест останется зелёным, хотя заявленное поведение 'токен проходит в экспортёр' пропало. Токен, отменённый после старта задачи (например, во время записи), не покрыт ни одним тестом.

cancellation.Cancel();

await Assert.ThrowsAnyAsync<OperationCanceledException>(() =>
    document.SaveJsonAsync(Path.GetTempFileName(), cancellationToken: cancellation.Token));

Исправление: Отменять токен уже после старта задачи, например через Stream-обёртку, чья Write вызывает cts.Cancel(), и ожидать OperationCanceledException из пост-проверки; или проверять, что делегат вызывается и бросает отмену, а не только Task.Run.

4. [НИЗКАЯ] Отмена во время FindClashes не прерывает экспорт: файл всё равно перезаписывается — src/NwcIO/Model/NwcAssembly.cs:563 (correctness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

В SaveBcf(path/stream) и SaveClashReportHtml(path) единственная долгая операция (FindClashes, перебор пар моделей с пространственными индексами) выполняется между проверкой «до» и проверкой «после» и сама токен не принимает. Между FindClashes() и записью проверки токена нет, поэтому после возврата из FindClashes экспортёр безусловно пишет файл и только потом бросает OperationCanceledException.

Уточнение проверяющего: При отмене во время FindClashes (он токен не принимает и не прерывается) SaveBcf(path/stream) и SaveClashReportHtml(path) всё равно выполняют запись: File.Create усекает целевой файл, а в stream попадают данные, и только затем бросается OperationCanceledException. Добавление cancellationToken.ThrowIfCancellationRequested() после clashes ??= FindClashes() не прервёт сам расчёт, но не даст перезаписать файл или поток после отмены.

Сценарий: Большая федерация, FindClashes занимает минуты. Пользователь отменяет через 5 секунд. Метод продолжает считать клэши до конца, затем BcfExporter.WriteFile через File.Create перезаписывает существующий report.bcf полностью новым содержимым и лишь после этого бросает OperationCanceledException. Отмена фактически не работает для самой дорогой части, а целевой файл всё равно изменён. То же в строках 580 (stream: данные уже записаны в поток вызывающего) и 661 (HTML-отчёт).

clashes ??= FindClashes();
BcfExporter.WriteFile(clashes, path, Name);
cancellationToken.ThrowIfCancellationRequested();

Исправление: Добавить cancellationToken.ThrowIfCancellationRequested() сразу после clashes ??= FindClashes() и до записи (во всех трёх местах).

sim added 2 commits November 16, 2026 12:38
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.
@mahach666
mahach666 changed the base branch from fix/reader-cancellation to main November 16, 2026 20:54
@mahach666
mahach666 merged commit 8556bae into main Nov 16, 2026
5 checks passed
@mahach666
mahach666 deleted the fix/export-cancellation branch November 17, 2026 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant