From fba9a492f0436cf79b16d2bd0786f1f8392ef4ca Mon Sep 17 00:00:00 2001 From: Pjandro Date: Mon, 26 Oct 2026 09:40:50 +0000 Subject: [PATCH] =?UTF-8?q?fix(core):=20DependencyGuard=20=E2=80=94=20?= =?UTF-8?q?=D0=BF=D0=BE=D0=BD=D1=8F=D1=82=D0=BD=D0=B0=D1=8F=20=D0=BE=D1=88?= =?UTF-8?q?=D0=B8=D0=B1=D0=BA=D0=B0=20=D0=BF=D1=80=D0=B8=20=D1=81=D1=82?= =?UTF-8?q?=D0=B0=D1=80=D0=BE=D0=B9=20commons-compress=20=D1=83=20=D0=BF?= =?UTF-8?q?=D0=BE=D1=82=D1=80=D0=B5=D0=B1=D0=B8=D1=82=D0=B5=D0=BB=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docx4j 17.3.2 требует ковариантный ZipArchiveInputStream.getNextEntry() (>= 1.25.0); BOM/nearest-wins потребителя мог навязать старую версию — конвертация падала NoSuchMethodError внутри docx4j. Теперь шаг 0 convertToStream бросает ConversionException с инструкцией; commons-compress объявлена явной зависимостью ядра (1.28.0, версия docx4j); README — закрепление версии в Maven/Gradle. Регрессия — DependencyGuardTest, негативная ветка проверена подменой jar (1.21 → ConversionException). --- AGENTS.md | 4 +- README.md | 44 ++++++++++++ pom.xml | 10 +++ wordpdf-core/pom.xml | 7 ++ .../ru/pjandro/wordpdf/WordPdfConverter.java | 9 ++- .../wordpdf/internal/DependencyGuard.java | 69 +++++++++++++++++++ .../wordpdf/internal/DependencyGuardTest.java | 25 +++++++ 7 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DependencyGuard.java create mode 100644 wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java diff --git a/AGENTS.md b/AGENTS.md index a1a8763..58dbb8c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,7 +51,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |---|---| |`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)| -|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)| +|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка совместимости commons-compress, шаг 0 `convertToStream`) (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`/`DependencyGuard.check`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)| |`…/wordpdf/internal/chart/`|17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| |`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/test/resources/samples/`|13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py`| @@ -127,7 +127,7 @@ gateway). Кеш раннеров — сервер act_runner (серверна - Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения. - Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться). - Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`. -- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. +- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`. - Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`. ## Important Files diff --git a/README.md b/README.md index f37be19..9010d33 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,50 @@ Files.write(Path.of("out.pdf"), pdf); больше ста) бросают `ConversionException`. Работа с файлами — забота вызывающего: ядро пути не принимает. +#### Зависимость commons-compress (интеграция в чужой проект) + +Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`, +рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в +classpath потребителя — `NoSuchMethodError: +org.apache.commons.compress.archivers.zip.ZipArchiveEntry +org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`. +До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом, +объясняющим, какую версию закрепить. + +**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress, +а `dependencyManagement` потребителя перекрывает транзитивные версии +(«nearest wins») — закреплять нужно именно в нём: + +```xml + + + + org.apache.commons + commons-compress + 1.28.0 + + + +``` + +Диагностика: `mvn dependency:tree -Dincludes=org.apache.commons:commons-compress`. + +**Gradle.** По умолчанию Gradle выбирает максимальную версию и конфликт +разрешает сам — guard не сработает и не нужен. Понижает версию только явный +`constraints` / `platform` / `resolutionStrategy`: уберите понижение либо +закрепите нужную версию: + +```kotlin +dependencies { + constraints { + implementation("org.apache.commons:commons-compress:1.28.0") + } +} +``` + +(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`). +Диагностика: `gradle dependencies --configuration runtimeClasspath`. + ### Веб-интерфейс и контейнеры (podman) ```bash diff --git a/pom.xml b/pom.xml index b5a3b14..a1cfe86 100644 --- a/pom.xml +++ b/pom.xml @@ -23,6 +23,9 @@ 17.3.2 + + 1.28.0 2.0.20 @@ -74,6 +77,13 @@ docx4j-export-fo ${docx4j.version} + + + org.apache.commons + commons-compress + ${commons-compress.version} + org.slf4j diff --git a/wordpdf-core/pom.xml b/wordpdf-core/pom.xml index 3774bb6..5e0233f 100644 --- a/wordpdf-core/pom.xml +++ b/wordpdf-core/pom.xml @@ -49,6 +49,13 @@ org.slf4j jcl-over-slf4j + + + org.apache.commons + commons-compress + diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java index dd45259..45bf2fe 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -11,6 +11,7 @@ import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import ru.pjandro.wordpdf.fonts.BundledFontMapper; import ru.pjandro.wordpdf.fonts.BundledFonts; import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer; +import ru.pjandro.wordpdf.internal.DependencyGuard; import ru.pjandro.wordpdf.internal.DocxNormalizer; import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer; import ru.pjandro.wordpdf.internal.FieldNormalizer; @@ -116,10 +117,16 @@ public final class WordPdfConverter { } /** - * Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. + * Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. Шаг 0 — проверка + * совместимости commons-compress в classpath потребителя (DependencyGuard): + * без неё старая версия библиотеки дала бы мутный NoSuchMethodError внутри docx4j. */ private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options, OutputStream os) throws Exception { + // 0. Совместимость commons-compress: docx4j требует ковариантный + // ZipArchiveInputStream.getNextEntry() (>= 1.25.0); ниже — понятный + // ConversionException с инструкцией вместо NoSuchMethodError. + DependencyGuard.check(); // 1. Маппер шрифтов. Порядок важен: конструктор запускает // обнаружение системных шрифтов, затем бандл-шрифты из jar // регистрируются поверх них (имеют приоритет). diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DependencyGuard.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DependencyGuard.java new file mode 100644 index 0000000..61cfb66 --- /dev/null +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/DependencyGuard.java @@ -0,0 +1,69 @@ +package ru.pjandro.wordpdf.internal; + +import org.apache.commons.compress.archivers.zip.ZipArchiveEntry; +import org.apache.commons.compress.archivers.zip.ZipArchiveInputStream; +import ru.pjandro.wordpdf.ConversionException; + +import java.lang.reflect.Method; + +/** + * Проверка совместимости commons-compress в classpath потребителя. + * + *

docx4j читает zip-контейнер docx через + * {@code org.docx4j.openpackaging.io3.stores.ZipPartStore}, который вызывает + * ковариантный {@code ZipArchiveInputStream.getNextEntry(): ZipArchiveEntry} + * — он появился только в commons-compress 1.25.0. Если у потребителя старая + * версия (BOM, например Spring Boot 3.x, или nearest-wins в Maven навязали + * понижение), конвертация падала мутным {@code NoSuchMethodError} внутри + * docx4j. Guard бросает {@link ConversionException} с текстом-инструкцией + * до входа в docx4j.

+ * + *

Порог определяется API-пробой (возврат {@code getMethod("getNextEntry")}), + * а не разбором строки версии: {@code getImplementationVersion()} бывает + * {@code null} в shaded/uber-jar сборках, а проба ловит ровно тот бинарный + * контракт, который реально ломается.

+ */ +public final class DependencyGuard { + + private DependencyGuard() { + } + + /** + * Бросает {@link ConversionException}, если commons-compress в classpath + * несовместим с docx4j 17.3.2 (нет ковариантного {@code getNextEntry}, + * т.е. версия ниже 1.25.0, либо библиотека отсутствует). + */ + public static void check() { + String reason = incompatibleReason(); + if (reason != null) { + throw new ConversionException(reason); + } + } + + /** + * Причина отказа или {@code null}, если classpath совместим. + * Package-private хук для юнит-теста (негативную ветку surefire покрыть + * нельзя — одна версия jar на тестовом classpath, см. DependencyGuardTest). + */ + static String incompatibleReason() { + String found; + try { + Method m = ZipArchiveInputStream.class.getMethod("getNextEntry"); + if (ZipArchiveEntry.class.equals(m.getReturnType())) { + return null; // >= 1.25.0: ковариантный getNextEntry на месте + } + String v = ZipArchiveInputStream.class.getPackage().getImplementationVersion(); + found = v == null ? "версия не определена" : v; + } catch (NoSuchMethodException e) { + found = "версия не определена"; // нет даже getNextEntry — доисторическая сборка + } catch (NoClassDefFoundError e) { + return "В classpath отсутствует org.apache.commons:commons-compress — " + + "docx4j требует версию 1.28.0 (минимум 1.25.0)."; + } + return "Несовместимая версия commons-compress в classpath (найдена: " + found + + "): docx4j требует >= 1.25.0, рекомендована 1.28.0. Старую версию обычно" + + " навязывает BOM или nearest-wins. Закрепите org.apache.commons:commons-compress" + + " версии 1.28.0: Maven — запись в dependencyManagement, Gradle — constraints" + + " или resolutionStrategy.force (см. README, раздел «Библиотека»)."; + } +} diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java new file mode 100644 index 0000000..3ea6ad1 --- /dev/null +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java @@ -0,0 +1,25 @@ +package ru.pjandro.wordpdf.internal; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; +import static org.junit.jupiter.api.Assertions.assertNull; + +/** + * Guard на тестовом classpath (commons-compress 1.28.0) — no-op. + * Негативная ветка (старая версия jar) surefire-покрытию недоступна — одна + * версия jar на classpath; проверена эмпирически подменой jar в classpath + * прогона (1.21 → ConversionException, 1.25.0/1.28.0 → OK). + */ +class DependencyGuardTest { + + @Test + void checkPassesOnCurrentClasspath() { + assertDoesNotThrow(DependencyGuard::check); + } + + @Test + void reasonNullOnCurrentClasspath() { + assertNull(DependencyGuard.incompatibleReason()); + } +} -- 2.56.1