fix(core): m-2 докрыт — переполнение maxMb на .doc-пути, правки AGENTS.md
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 2m50s
PR checks / macos-sim (pull_request) Successful in 5m8s

- WordPdfValidator.checkInput — multiplyExact и для порога растра maxMb×5_000_000: экстремальный maxMb на бинарном .doc (миновал бюджеты checkDocxContainer) давал сырой ArithmeticException на границе convert вместо ValidationException/400; регрессии checkInput_rasterCoefficientOverflow_rejected, validate_docExtremeMaxMb_rejectedNotArithmetic (фикстура too-many-pages.doc)
- AGENTS.md: убран устаревший маркер дрейфа «порядок в javadoc WordPdfConverter.normalizers устарел» (javadoc приведён к фактическому порядку в этом PR); счётчики 1023/975
This commit is contained in:
Pjandro
2026-11-23 00:12:42 +03:00
parent 7016df5434
commit e7005eb918
4 changed files with 28 additions and 3 deletions
+2 -2
View File
@@ -25,7 +25,7 @@
**Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`): **Слои ядра** (`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`):
- публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages` — порядок полей фиксирован), `ConversionException` + `ValidationException` + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев (никогда не бросает), решает вызывающий; - публичный API: `WordPdfConverter`, `WordPdfValidator`, `ConvertOptions` (record `errorOnCharts/errorOnSmartArt/errorOnOle/maxMb/maxPages` — порядок полей фиксирован), `ConversionException` + `ValidationException` + `Charts/SmartArt/OleFoundException`; `warmup()` — идемпотентный прогрев (никогда не бросает), решает вызывающий;
- `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby (порядок в javadoc `WordPdfConverter.normalizers` устарел — не доверять), `OleObjectNormalizer` — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`; - `internal/`: контракт нормализатора — `byte[] normalize(byte[])`, нечего менять → **тот же массив** (`assertSame`); правила 1–11 идут одним zip-проходом `DocxRewritePipeline.STEP` в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→MathFallback→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby, `OleObjectNormalizer` — 12-й, отдельным байтовым проходом (не zip); неизменённые записи копируются raw-сжатыми байтами; наружу только `DocxNormalizer`, `DocxRewritePipeline.STEP`, `OleObjectNormalizer`, `FopFallbackFonts`, `LayoutPostRenderer`, `DependencyGuard`;
- `internal/doc`: мост `.doc`→`.docx`, 18 top-level классов (17 package-private + `DocToDocx`) + вложенный `DocxBody`, наружу только `DocToDocx.convert/countPages`; любая бита/шифрованный/Word 6-95 входов → `ConversionException`; раскладки — `docs/agent/doc-bridge.md`; - `internal/doc`: мост `.doc`→`.docx`, 18 top-level классов (17 package-private + `DocToDocx`) + вложенный `DocxBody`, наружу только `DocToDocx.convert/countPages`; любая бита/шифрованный/Word 6-95 входов → `ConversionException`; раскладки — `docs/agent/doc-bridge.md`;
- `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — `fitDpi` понижает dpi; `MAX_POINTS` 100 000, бюджет chart/math-PNG на документ 128 MiB); формулы OMML — собственный растер `MathModel` (разбор §22.1 в дерево боксов, `SUPPORTED` — единый список конструкций) + `MathRenderer` (без AWT/JEuclid, только бандл через `GlyphFont`); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn; неподдерживаемая/битая формула → **текст** (конкатенация `m:t`) + warn; `wp:extent` вне диапазона/ноль → объект **остаётся** + warn (FOP молча потеряет); `OutOfMemoryError` — не деградация, а `ConversionException` (500); - `internal/chart`: Java2D → PNG (`ChartRenderer.DPI = 300`, `MAX_PIXELS` 4096² — `fitDpi` понижает dpi; `MAX_POINTS` 100 000, бюджет chart/math-PNG на документ 128 MiB); формулы OMML — собственный растер `MathModel` (разбор §22.1 в дерево боксов, `SUPPORTED` — единый список конструкций) + `MathRenderer` (без AWT/JEuclid, только бандл через `GlyphFont`); модель **деградации**: битая chart-часть/превышение бюджета → объект удалён + warn; неподдерживаемая/битая формула → **текст** (конкатенация `m:t`) + warn; `wp:extent` вне диапазона/ноль → объект **остаётся** + warn (FOP молча потеряет); `OutOfMemoryError` — не деградация, а `ConversionException` (500);
- `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен). - `fonts/GlyphFont`: метрика/глифы через fontbox напрямую, **без** `java.awt.Font` (fontconfig хосту не нужен).
@@ -126,5 +126,5 @@ python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources
- Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать** (все 12 `.doc` — эталоны заказчика, не вывод генераторов). - Фикстуры — только закоммиченные `samples/*.docx`/`*.doc`, в тестах не генерировать; XSD-невалидная фикстура правится, не код. Синтетика в памяти разрешена: docx — `ZipOutputStream` из литеральных XML, `.doc` — крафт `POIFSFileSystem`. Пересоздание — одноразовые `SampleDocxGenerator`/`ChartTypesDocxGenerator` (POI test-scope, команда — `docs/agent/repo-map.md`); `charts-smartart.docx` и `ole-embedded.docx` сделаны руками — **никогда не перезаписывать** (все 12 `.doc` — эталоны заказчика, не вывод генераторов).
- Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar). - Идиома загрузки (ловушка): **core** — classloader без ведущего слэша (`getResourceAsStream("samples/…")`); **app** — class-relative со слэшем (`"/samples/…"`, ресурсы из core test-jar).
- App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой `.env` в окружение задач — ambient `WORDPDF_API_KEY` взорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста. - App-тесты: 4 набора свойств = 4 Spring-контекста (`ConvertControllerTest` пинует пустой `wordpdf.api-key=`; `ApiKeyFilterTest`; `ConvertLimitsTest`; `ConversionTimeoutTest`); `ConversionServiceTest`/`ApiExceptionHandlerTest` — без Spring; проверяют только HTTP-код/заголовки/текст ошибки; core-юниты Spring не поднимают. Ловушка: mise инжектирует корневой `.env` в окружение задач — ambient `WORDPDF_API_KEY` взорвёт 401 все MockMvc-тесты, если ключ не запинен свойствами контекста.
- Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1021 тест (core 57/973, app 6/48); детали — `docs/agent/testing.md`. - Регрессивная конвенция: фикс = нормализатор/рендерер + юнит + конвертер-тест + javadoc-ссылка. Счётчики (2026-11): 63 класса / 1023 теста (core 57/975, app 6/48); детали — `docs/agent/testing.md`.
- Прод-автотесты: pytest 9.1.1 + requests 2.34.2 (timeout `(10,180)` — больше серверных 2m), конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key`-декоратор `skipif` (немаркированный marker — маркеры не регистрируются) даёт SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда 5/100, `WORDPDF_SAMPLES_DIR` — путь к фикстурам); запуск `./mise.sh run prod-tests` либо job `autotests` в CI. - Прод-автотесты: pytest 9.1.1 + requests 2.34.2 (timeout `(10,180)` — больше серверных 2m), конфигурация **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY` факультативен → `needs_key`-декоратор `skipif` (немаркированный marker — маркеры не регистрируются) даёт SKIP, `WORDPDF_MAX_MB`/`MAX_PAGES` — ожидаемые лимиты стенда 5/100, `WORDPDF_SAMPLES_DIR` — путь к фикстурам); запуск `./mise.sh run prod-tests` либо job `autotests` в CI.
+1 -1
View File
@@ -2,7 +2,7 @@
### Счётчики (2026-11) ### Счётчики (2026-11)
- 63 тестовых классов / 1021 тест: core 57/973 (`internal/doc/` 17/256, `internal/chart/` 18/311, `WordPdfConverterTest` 89), app 6/48 (ConvertController 26, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 3, ConversionTimeout 1). Обновлять при изменении набора. - 63 тестовых классов / 1023 теста: core 57/975 (`internal/doc/` 17/256, `internal/chart/` 18/311, `WordPdfConverterTest` 89), app 6/48 (ConvertController 26, ApiKeyFilter 8, ConversionService 5, ApiExceptionHandler 5, ConvertLimits 3, ConversionTimeout 1). Обновлять при изменении набора.
### Пиксели, метрики шрифтов, стенд без fontconfig ### Пиксели, метрики шрифтов, стенд без fontconfig
@@ -97,6 +97,11 @@ public final class WordPdfValidator {
long maxBytes; long maxBytes;
try { try {
maxBytes = Math.multiplyExact(maxMb, 1048576L); maxBytes = Math.multiplyExact(maxMb, 1048576L);
// .doc-путь (миновать бюджеты checkDocxContainer не даёт общая
// гейт-проверка): OfficeArt/DocToDocx считают порог растра только
// множителем maxMb×5_000_000 — при maxMb ≳ 1.8·10¹² переполнение
// бросало сырой ArithmeticException на границе convert.
Math.multiplyExact(maxMb, WordPdfConverter.IMAGE_PIXELS_PER_MAX_MB);
} catch (ArithmeticException e) { } catch (ArithmeticException e) {
throw new ValidationException("Лимит maxMb слишком велик: " + maxMb); throw new ValidationException("Лимит maxMb слишком велик: " + maxMb);
} }
@@ -714,6 +714,26 @@ class WordPdfValidatorTest {
"переполнение maxMb не отклонено"); "переполнение maxMb не отклонено");
} }
/**
* m-2 на .doc-пути: порог растра maxMb×5_000_000 переполняется раньше
* байтового лимита — гейт обязан отклонить до DocToDocx.convert.
*/
@Test
void checkInput_rasterCoefficientOverflow_rejected() {
assertThrows(ValidationException.class,
() -> WordPdfValidator.checkInput(new byte[] {1}, 2_000_000_000_000L),
"переполнение порога растра не отклонено");
}
/** Реальный .doc + maxMb=2·10¹² — ValidationException, не сырой ArithmeticException. */
@Test
void validate_docExtremeMaxMb_rejectedNotArithmetic() throws Exception {
assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(sample("too-many-pages.doc"),
new ConvertOptions(false, false, false, 2_000_000_000_000L, 100)),
"переполнение на .doc-пути ушло мимо ValidationException");
}
/** {@code null} options — отказ публичного API (m-7 ревью ядра). */ /** {@code null} options — отказ публичного API (m-7 ревью ядра). */
@Test @Test
void validate_nullOptions_rejected() { void validate_nullOptions_rejected() {