Skip to content

feat(api): add cancellation, progress and async overloads for readers - #244

Merged
mahach666 merged 3 commits into
mainfrom
fix/reader-cancellation
Nov 16, 2026
Merged

mahach666 merged 3 commits into
mainfrom
fix/reader-cancellation

Conversation

@mahach666

Copy link
Copy Markdown
Collaborator

Completes the remaining #111 work: Open/assembly cancellation, progress and async I/O wrappers. Stacked on #236 (fix/clash-cancellation), which adds NwcProgress and clash cancellation.

What changed

  • NwcDocument.Open has cancellation/progress overloads for paths and streams; existing signatures are unchanged.
  • NwcAssembly.LoadFromDirectory and NwcAssembly.OpenNwf have cancellation/progress overloads; the reader checks the token between models and reports load-models completed/total.
  • NwcDocument.Open checks the token at the start, after the container read, before geometry parsing, before TimeLiner parsing and before returning. It reports read-container, read-geometry and open phases.
  • Added OpenAsync, LoadFromDirectoryAsync, OpenNwfAsync and document Save*Async wrappers for JSON, OBJ, GLB, IFC, BCF viewpoints, XML viewpoints, HTML viewer and the raw .nwc save.
  • Added six regression tests: cancelled document open, phase progress, cancelled folder load, per-model progress, cancelled .nwf open, and OpenAsync + SaveJsonAsync.

Files

  • src/NwcIO/NwcDocument.cs
  • src/NwcIO/Model/NwcAssembly.cs
  • tests/NwcIO.Tests/ReaderCancellationTests.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).
  • ReaderCancellationTests: 6 passed.

Remaining limitations

  • OpenAsync/Save*Async currently wrap the synchronous implementation in Task.Run; file I/O itself is not yet truly asynchronous.
  • Cancellation is checked at reader phase boundaries and between models, not inside a single zlib inflate or a long mesh stream.
  • Export operations do not report progress; only loading does.
  • Save wrappers cover NwcDocument; assembly BCF/clash/viewpoint exports have no async wrappers yet.

Add NwcProgress and cancellation/progress overloads for NwcClashDetector.Run and NwcDocument.RunClashDetection. The detector checks the token in the outer mesh loop and periodically in the inner pair loop, and reports completed/total meshes. Existing synchronous overloads are unchanged. Async I/O and assembly/open overloads remain a follow-up.
Add cancellation/progress overloads for NwcDocument.Open (path and stream), NwcAssembly.LoadFromDirectory and OpenNwf. Report read-container, read-geometry, open and per-model load-models progress and check the token at phase boundaries and between models. Add OpenAsync, LoadFromDirectoryAsync, OpenNwfAsync and Save*Async wrappers for document exports. Add six cancellation/progress/async regression tests.
@mahach666

Copy link
Copy Markdown
Collaborator Author

Код-ревью — feat(api): add cancellation, progress and async overloads for readers (стек на #236)

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

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

  • correctness: PR добавляет перегрузки NwcDocument.Open, NwcAssembly.LoadFromDirectory и OpenNwf с CancellationToken и IProgress, а также Task.Run-обёртки OpenAsync, LoadFromDirectoryAsync, OpenNwfAsync и SaveAsync. Старые сигнатуры сохранены, и проверок токена достаточно для заявленного. Прогресс OpenNwf считает total по всем XRef-ам, поэтому до total не доходит, если часть ссылок не загружается. Токен в SaveAsync после старта не действует. Тесты проверяют только заранее отменённый токен и не ловят ни одной внутренней проверки.
  • robustness: PR добавляет перегрузки NwcDocument.Open, NwcAssembly.LoadFromDirectory и NwcAssembly.OpenNwf с IProgress и CancellationToken, а также обёртки OpenAsync и Save*Async на Task.Run. Старые сигнатуры сохранены, перегрузки не создают неоднозначности, молчаливых catch нет, а ограничения честно названы в описании PR. Минусы с точки зрения надёжности: тесты не проверяют заявленные проверки токена (они прошли бы и без них), прогресс OpenNwf не доходит до total при нерезолвленных или дублирующих xref, а отмена не прерывает дорогое чтение контейнера и экспорты, и это не отражено в CHANGELOG, public-api.md и XML-документации.
  • tests-claims: PR добавляет перегрузки Open/LoadFromDirectory/OpenNwf с CancellationToken и IProgress, а также Task.Run-обёртки OpenAsync, LoadFromDirectoryAsync, OpenNwfAsync и SaveAsync (по issue Add cancellation and progress reporting (and async I/O overloads) for Open, exports, assembly loading and clash detection #111). Старые сигнатуры сохранены, поведение синхронного пути не меняется. Код чистый, но с точки зрения тестов и заявлений есть проблемы. Все три теста отмены используют уже отменённый токен и не проверяют заявленные промежуточные проверки. Прогресс OpenNwf считает total неверно и никем не тестируется. Токен в SaveAsync после старта игнорируется. docs/public-api.md не описывает новые перегрузки, хотя это критерий приёмки Add cancellation and progress reporting (and async I/O overloads) for Open, exports, assembly loading and clash detection #111.

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

1. [СРЕДНЯЯ] Тесты отмены не проверяют заявленные точки проверки токена — tests/NwcIO.Tests/ReaderCancellationTests.cs:42 (tests-do-not-test-claim; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Все тесты отмены используют токен, отменённый ДО вызова. Такой токен перехватывает самая первая проверка в NwcDocument.Open(string, ...) (строка 135 в NwcDocument.cs) или в Open(Stream, ...) (строка 160). Заявленные в PR проверки между моделями в LoadFromDirectory/OpenNwf, после чтения контейнера, перед геометрией и перед TimeLiner ни одним тестом не покрыты. OpenNwf_CanceledToken вообще пишет пустой файл и не отличает собственную проверку OpenNwf от проверки внутри Open. Прогресс для OpenNwf, отмена в OpenAsync/LoadFromDirectoryAsync/OpenNwfAsync и все Save*Async, кроме SaveJsonAsync, не тестируются. Единственный async-тест проверяет только File.Exists(json).

Уточнение проверяющего: Тесты отмены используют только токен, отменённый до вызова, поэтому проверяют лишь первую проверку в NwcDocument.Open. Проверки между моделями в LoadFromDirectory/OpenNwf, после чтения контейнера, перед геометрией и в местах NwcDocument.cs:163, 182, 208, 242 не покрыты. Нет тестов отмены в процессе работы (например, из IProgress.Report), прогресса OpenNwf, отмены async-перегрузок и Save*Async. Это пробел в тестовом покрытии (medium), а не дефект поведения.

Сценарий: Удалить все cancellationToken.ThrowIfCancellationRequested() из NwcAssembly.LoadFromDirectory и OpenNwf, а в NwcDocument.Open(Stream, ...) оставить только первую проверку (строка 160). LoadFromDirectory_CanceledToken_ThrowsOperationCanceled и OpenNwf_CanceledToken_ThrowsOperationCanceled останутся зелёными, потому что NwcDocument.Open(path, ...) сам бросает исключение на уже отменённом токене. Регрессия «отмена между моделями не работает» или «токен не доходит до Open» пройдёт CI незамеченной. Нет и теста, где отмена происходит посреди операции, например из IProgress.Report после первой модели.

cancellation.Cancel();

Assert.Throws<OperationCanceledException>(() =>
    NwcAssembly.LoadFromDirectory(directory, "*.nwc", null, null, cancellation.Token));

Исправление: Добавить тесты, где токен отменяется из callback прогресса: после первого load-models в папке из 2-3 файлов ожидать OperationCanceledException и ровно один отчёт; после read-container в Open. Для OpenNwf собрать .nwf с несколькими xref. Для async-перегрузок проверять Task.IsCanceled. Для OpenNwf и LoadFromDirectory дополнительно проверять порядок и значения Completed/Total.

2. [СРЕДНЯЯ] Тесты отмены используют заранее отменённый токен и не проверяют заявленные промежуточные точки проверки — tests/NwcIO.Tests/ReaderCancellationTests.cs:15 (tests; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Описание PR заявляет проверки токена "between models", после чтения контейнера, перед парсингом геометрии, перед парсингом TimeLiner и перед возвратом. Три теста отмены (Open, LoadFromDirectory, OpenNwf) создают токен с уже выставленной отменой. Они срабатывают на самой первой проверке (NwcDocument.cs:160, NwcAssembly.cs:188 и :224) и никогда не доходят до остальных. Промежуточные проверки (NwcDocument.cs:163, 182, 208, 242, 284, 299; NwcAssembly.cs:193, 241) ни одним тестом не затрагиваются. Для сравнения, #236 тестирует то же самое только pre-cancelled, так что механизма отмены посреди операции в наборе тестов нет вообще.

Уточнение проверяющего: Тесты отмены проверяют только предотменённый токен и не защищают регрессионно проверки между моделями (NwcAssembly.cs:193, 241) и между фазами Open (NwcDocument.cs:163, 182, 208, 242, 284, 299). Это пробел в тестах, а не баг в продуктовом коде. Рекомендуется отменять токен из IProgress-колбэка, например на "read-container" для Open и на "load-models" 1/2 для LoadFromDirectory.

Сценарий: Удаляем все ThrowIfCancellationRequested, кроме первого в Open(Stream), в LoadFromDirectory оставляем только проверку на строке 188 (перед циклом) и убираем проверки в цикле OpenNwf. Все три теста остаются зелёными, хотя пользователь, нажавший Cancel во время загрузки второй модели из папки, получит полную загрузку вместо OperationCanceledException. Заявленное поведение "между моделями" и "между фазами" не защищено регрессионно.

cancellation.Cancel();

Assert.Throws<OperationCanceledException>(() =>
    NwcDocument.Open(stream, null, null, null, cancellation.Token));

Исправление: Отменять токен из IProgress-колбэка: на отчёте read-container для Open (и проверять, что отчёт open не пришёл), на отчёте load-models 1/2 для LoadFromDirectory (ожидать OCE и что вторая модель не открыта).

3. [НИЗКАЯ] Прогресс OpenNwf считает total по всем XRef, но отчитывается только о загруженных моделях — src/NwcIO/Model/NwcAssembly.cs:234 (correctness; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

total = 1 + References.Count включает ссылки, которые затем пропускаются через continue без Report: нерезолвленные (unresolved), дубликаты по полному пути и файлы не .nwc/.nwd (skipped). Report вызывается только после успешной загрузки модели, поэтому Completed никогда не достигает Total, если хотя бы одна ссылка не загрузилась.

Уточнение проверяющего: Прогресс OpenNwf объявляет total = 1 + число XRef, но Report вызывается только для реально загруженных моделей. При unresolved, дубликатах и пропущенных (не .nwc/.nwd) ссылках итоговый Completed остаётся меньше Total, и финального Report нет. Прогресс-бар не доходит до 100%, и завершение нельзя отличить от обрыва по одному только payload. Это неточность прогресса, а не функциональный сбой: результат сборки корректен, UnresolvedXRefs и SkippedXRefs заполняются.

Сценарий: В .nwf три XRef: a.nwc существует, b.nwc отсутствует (unresolved), c.rvt (skipped). total = 4. Приходят отчёты (1,4) и (2,4), после чего метод возвращает сборку. Прогресс-бар остаётся на 50%, а код вида 'Completed == Total' не срабатывает. Из-за этого нельзя отличить завершение от обрыва. Ни одна ветка continue не увеличивает Completed.

int total = 1 + (primaryDoc.XRefs?.References.Count ?? 0);
progress?.Report(new NwcProgress("load-models", 1, total));

Исправление: Либо вызывать Report и в ветках unresolved/duplicate/skipped (увеличивая Completed), либо считать total только по ссылкам, которые будут загружены, либо отдавать финальный Report(n, n) перед возвратом.

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

4. [НИЗКАЯ] Все тесты отмены передают заранее отменённый токен и проходят на первой же проверке — tests/NwcIO.Tests/ReaderCancellationTests.cs:15 (test-coverage; уверенность high; проверка: trace:подтвердил, intent:подтвердил)

Open_CanceledToken, LoadFromDirectory_CanceledToken и OpenNwf_CanceledToken вызывают Cancel() до старта. Выбрасывается самая первая проверка (NwcDocument.cs:160, NwcAssembly.cs:188 и 224). Заявленные в PR проверки между фазами и между моделями (NwcDocument.cs:163, 182, 208, 242, 284, 299; NwcAssembly.cs:193 и 241) не исполняются ни одним тестом. Если удалить любую из них, все шесть тестов останутся зелёными. Прогресс OpenNwf (включая ветки unresolved/skipped из предыдущего замечания) не покрыт вовсе. Из 16 Save*Async проверен один, SaveJsonAsync, и только через File.Exists, без чтения содержимого. Путь отмены через Task.Run (TaskCanceledException, Task.IsCanceled) тоже не проверен.

Уточнение проверяющего: Тесты отмены используют только заранее отменённый токен, поэтому проверяют лишь первую проверку в каждом методе. Не покрыты: отмена между фазами NwcDocument.Open, отмена внутри цикла LoadFromDirectory и OpenNwf (через колбэк IProgress), прогресс OpenNwf с unresolved/skipped XRef, отмена через Task в Async и содержимое результата SaveAsync (проверен лишь File.Exists для SaveJsonAsync). Прогресс фаз Open и load-models для LoadFromDirectory покрыт отдельными тестами. Это пробел в тестах, а не функциональный дефект.

Сценарий: Регрессия: из цикла LoadFromDirectory убрана cancellationToken.ThrowIfCancellationRequested() (NwcAssembly.cs:193), либо в OpenNwf нарушена нумерация progress. Токен, отменённый на второй модели, больше не прерывает загрузку, но CI остаётся зелёным. Тест OpenNwf_CanceledToken к тому же пишет в .nwf пустой файл и зависит только от проверки на строке 224. Нужны тесты с отменой изнутри IProgress.Report (например, отмена в отчёте первой модели) и тест OpenNwf с unresolved XRef.

cancellation.Cancel();

Assert.Throws<OperationCanceledException>(() =>
    NwcDocument.Open(stream, null, null, null, cancellation.Token));

Исправление: Добавить тесты, где токен отменяется из колбэка IProgress после первой модели или фазы и проверяется, что вторая модель не загружается. Добавить тест OpenNwf с нерезолвленным XRef, сверяющий последовательность Completed/Total, и тест OpenAsync с отменой через Task.

@mahach666
mahach666 changed the base branch from fix/clash-cancellation to main November 16, 2026 20:16
Drop the clash-detector cancellation from the closed #236 and the Save*Async
wrappers of the frozen exporters; keep reader cancellation, progress and
SaveAsync (.nwc). OpenNwf progress now counts every reference; OpenManifest
gets the same token and progress overload; tests cancel mid-operation.
@mahach666
mahach666 merged commit f4217aa into main Nov 16, 2026
5 checks passed
@mahach666
mahach666 deleted the fix/reader-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