From f09b629270bfc22b0dfefd398a0bddc1d3ec93b8 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Mon, 19 Oct 2026 21:30:45 +0000 Subject: [PATCH 1/3] =?UTF-8?q?core:=20ValidationException=20=D0=B2=D0=BC?= =?UTF-8?q?=D0=B5=D1=81=D1=82=D0=BE=20ConversionException;=20=D1=83=D0=B4?= =?UTF-8?q?=D0=B0=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5=20pkg-API=20=D0=B8=20?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=B8=D0=BC=D0=B5=D0=BD=D0=BE=D0=B2?= =?UTF-8?q?=D0=B0=D0=BD=D0=B8=D0=B5=20checkPageCountLightweight=20=D0=B2?= =?UTF-8?q?=20checkPageCount?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../wordpdf/app/ApiExceptionHandler.java | 10 +- .../app/ConversionFailedException.java | 5 +- .../wordpdf/app/ConversionService.java | 29 +- .../wordpdf/app/ConvertController.java | 1 + .../wordpdf/app/ValidationException.java | 23 -- .../wordpdf/app/ConvertControllerTest.java | 6 +- .../pjandro/wordpdf/ValidationException.java | 22 ++ .../ru/pjandro/wordpdf/WordPdfConverter.java | 35 ++- .../ru/pjandro/wordpdf/WordPdfValidator.java | 253 +++--------------- .../pjandro/wordpdf/WordPdfConverterTest.java | 14 +- .../pjandro/wordpdf/WordPdfValidatorTest.java | 157 +++-------- 11 files changed, 153 insertions(+), 402 deletions(-) delete mode 100644 wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ValidationException.java create mode 100644 wordpdf-core/src/main/java/ru/pjandro/wordpdf/ValidationException.java diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java index 5f490cb..9e035bf 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiExceptionHandler.java @@ -10,14 +10,16 @@ import org.springframework.web.bind.annotation.RestControllerAdvice; import org.springframework.web.multipart.MaxUploadSizeExceededException; import org.springframework.web.multipart.support.MissingServletRequestPartException; import org.springframework.web.servlet.resource.NoResourceFoundException; +import ru.pjandro.wordpdf.ValidationException; /** * Единый перевод исключений в JSON {@code {"error": "..."}} с кодом по смыслу. * - *

Голый {@code ru.pjandro.wordpdf.ConversionException} ядра сюда не доходит: - * контроллер и {@link ConversionService} превращают его на границе в - * {@link ValidationException}/{@link ConversionFailedException}; случайная - * утечка попадёт в обработчик {@link Exception} (500).

+ *

{@link ValidationException} ядра доходит сюда напрямую — валидатор + * бросает его сам; в {@link ConversionFailedException} превращается только + * прочий {@code ru.pjandro.wordpdf.ConversionException} рендер-стадии. + * Случайная утечка прочего исключения попадёт в обработчик {@link Exception} + * (500).

*/ @RestControllerAdvice final class ApiExceptionHandler { diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionFailedException.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionFailedException.java index 63db834..e044e6c 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionFailedException.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionFailedException.java @@ -4,8 +4,9 @@ package ru.pjandro.wordpdf.app; * Ошибка преобразования: контейнер .docx принят валидацией, но упал сам * рендер (ядро, FOP, повреждённое содержимое внутри валидного zip). * - *

Смысл отличается от {@link ValidationException}: вход формально корректен, - * отказал движок конвертации. Маппится в HTTP 500 ({@link ApiExceptionHandler}).

+ *

Смысл отличается от {@code ru.pjandro.wordpdf.ValidationException}: + * вход формально корректен, отказал движок конвертации. + * Маппится в HTTP 500 ({@link ApiExceptionHandler}).

* *

Регрессия — ConvertControllerTest#junkInsideValidZip_conversionError.

*/ diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java index 34e1cd2..f5de6c2 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java @@ -8,6 +8,7 @@ import ru.pjandro.wordpdf.ConversionException; import ru.pjandro.wordpdf.DrawingFoundException; import ru.pjandro.wordpdf.WordPdfConverter; import ru.pjandro.wordpdf.WordPdfValidator; +import ru.pjandro.wordpdf.ValidationException; import java.time.Duration; import java.util.Locale; @@ -34,9 +35,10 @@ import java.util.concurrent.TimeoutException; * {@link ValidationException} (400), ошибка рендер-стадии → * {@link ConversionFailedException} (500). Граница: сломанный контейнер * (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный - * zip с мусором внутри (нет {@code word/document.xml}) — 500: lightweight- - * подсчёт страниц согласован с JAXB-путём ядра (может только завышать), - * поэтому уже принятый запрос внутренняя проверка ядра в ошибку не превратит.

+ * zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди и + * в конвейере ядра страницы проверяются одним и тем же lightweight-путём + * ({@link WordPdfValidator#checkPageCount}), поэтому уже принятый + * запрос внутренняя проверка ядра в ошибку не превратит.

*/ @Service final class ConversionService { @@ -111,7 +113,8 @@ final class ConversionService { } /** - * Валидация байтов переиспользует публичные byte-API ядра. Порядок значим: + * Валидация байтов переиспользует публичные byte-API ядра; ядро бросает + * {@link ValidationException} само — оборачивать нечего. Порядок значим: * размер (дешёвая) → magic bytes → lightweight-разбор zip. Лимиты * размера/страниц берутся из {@code options} (контроллер подставляет их * из конфигурации сервера: свойства {@code wordpdf.max-bytes}/ @@ -119,25 +122,17 @@ final class ConversionService { * *

Проверка zip-подписи отдельным шагом обязательна: * {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает - * {@code null} молча, и {@link WordPdfValidator#checkPageCountLightweight(byte[])} + * {@code null} молча, и {@link WordPdfValidator#checkPageCount(byte[])} * такой вход не отверг бы (0 страниц). Регрессия — * ConvertControllerTest#corruptNotAZip_rejected.

*/ void validate(byte[] docxBytes, ConvertOptions options) { - try { - WordPdfValidator.checkInput(docxBytes, options.maxBytes()); - } catch (ConversionException e) { - throw new ValidationException(e.getMessage(), e); - } + WordPdfValidator.checkInput(docxBytes, options.maxBytes()); if (docxBytes.length < 4 || docxBytes[0] != 'P' || docxBytes[1] != 'K' || (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)"); } - try { - WordPdfValidator.checkPageCountLightweight(docxBytes, options.maxPages()); - } catch (ConversionException e) { - throw new ValidationException(e.getMessage(), e); - } + WordPdfValidator.checkPageCount(docxBytes, options.maxPages()); } /** @@ -149,6 +144,10 @@ final class ConversionService { try { // заголовок PDF — санитизированный base исходного имени return WordPdfConverter.convert(docxBytes, safeBaseName(originalFilename), options); + } catch (ValidationException e) { + // отказ проверки страниц внутри конвейера ядра — некорректный + // вход (400), а не ошибка рендера: без этого утонул бы в 500 + throw e; } catch (DrawingFoundException e) { // отказ по настройке запроса (error-флаг) — не ошибка рендера: 422, // иначе утонет в общем catch ниже как 500 diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java index 63b5dba..b8197fd 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java @@ -13,6 +13,7 @@ import org.springframework.beans.factory.annotation.Value; import org.springframework.web.multipart.MultipartFile; import ru.pjandro.wordpdf.ConvertOptions; import ru.pjandro.wordpdf.WordPdfSettings; +import ru.pjandro.wordpdf.ValidationException; import java.io.IOException; import java.nio.charset.StandardCharsets; diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ValidationException.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ValidationException.java deleted file mode 100644 index 03b3c9a..0000000 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ValidationException.java +++ /dev/null @@ -1,23 +0,0 @@ -package ru.pjandro.wordpdf.app; - -/** - * Некорректный вход: пустой файл, не .docx, не zip-архив, размер или число - * страниц сверх переданных в запросе (или дефолтных) лимитов. - * - *

Отличается от {@link ConversionFailedException} смыслом: запрос - * некорректен сам по себе, повтор его же ничего не изменит. Маппится в HTTP 400 - * ({@link ApiExceptionHandler}).

- * - *

Регрессия — ConvertControllerTest#nonDocxFilename_rejected, - * #oversizedOverCoreLimit_rejected, #corruptNotAZip_rejected.

- */ -class ValidationException extends RuntimeException { - - ValidationException(String message) { - super(message); - } - - ValidationException(String message, Throwable cause) { - super(message, cause); - } -} diff --git a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java index 664ac0a..535337d 100644 --- a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java +++ b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ConvertControllerTest.java @@ -252,14 +252,14 @@ class ConvertControllerTest { @Test void oversizedOverCoreLimit_rejected() throws Exception { - // 20 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ) + // 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ) // и отсекается валидацией ядра до очереди (дефолт ядра цел — // лимит задаёт только конфигурация сервера) - byte[] big = new byte[20 * 1024 * 1024 + 1]; + byte[] big = new byte[5 * 1024 * 1024 + 1]; mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big))) .andExpect(status().isBadRequest()) .andExpect(jsonPath("$.error", - org.hamcrest.Matchers.containsString("больше 20 МБ"))); + org.hamcrest.Matchers.containsString("больше 5 МБ"))); } /** diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/ValidationException.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/ValidationException.java new file mode 100644 index 0000000..cdc466a --- /dev/null +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/ValidationException.java @@ -0,0 +1,22 @@ +package ru.pjandro.wordpdf; + +/** + * Некорректный вход: {@code null}-байты, размер или число страниц сверх + * лимитов, неразбираемый .docx-контейнер (не zip / битый XML). + * + *

Отличается от прочего {@link ConversionException} смыслом: вход плох сам + * по себе, повтор с теми же байтами ничего не изменит. Наследник + * {@code ConversionException} — наружу по-прежнему ловится только он + * (в т.ч. из {@link WordPdfConverter}, который вызывает валидатор сам). + * Регрессия — WordPdfValidatorTest, ConvertControllerTest#corruptNotAZip_rejected.

+ */ +public class ValidationException extends ConversionException { + + public ValidationException(String message) { + super(message); + } + + public ValidationException(String message, Throwable cause) { + super(message, cause); + } +} 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 e811631..a0c5398 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -59,14 +59,16 @@ public final class WordPdfConverter { * *

Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[])} * (null / больше {@link WordPdfSettings#MAX_INPUT_BYTES}), затем число страниц - * ({@link WordPdfSettings#MAX_PAGES}) — при отказе байтов результата нет. + * ({@link WordPdfValidator#checkPageCount(byte[])}, лимит + * {@link WordPdfSettings#MAX_PAGES}) — при отказе байтов результата нет. * * @param docxBytes байты .docx * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся * @return байты готового PDF - * @throws ConversionException при ошибке (битый .docx, размер больше - * {@link WordPdfSettings#MAX_INPUT_BYTES}, результат длиннее - * {@link WordPdfSettings#MAX_PAGES} страниц и т.п.) + * @throws ValidationException некорректный вход: {@code null}, размер больше + * {@link WordPdfSettings#MAX_INPUT_BYTES}, документ длиннее + * {@link WordPdfSettings#MAX_PAGES} страниц + * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) */ public static byte[] convert(byte[] docxBytes, String title) throws ConversionException { return convert(docxBytes, title, ConvertOptions.defaults()); @@ -78,16 +80,18 @@ public final class WordPdfConverter { * *

Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[], long)} * (null / больше {@code options.maxBytes()}), затем число страниц - * ({@code options.maxPages()}) — при отказе байтов результата нет. + * ({@link WordPdfValidator#checkPageCount(byte[], int)}, лимит + * {@code options.maxPages()}) — при отказе байтов результата нет. * * @param docxBytes байты .docx * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся * @param options рисование и лимиты входа на этот вызов; {@code null} — * дефолты (константы {@link WordPdfSettings}) * @return байты готового PDF - * @throws ConversionException при ошибке (битый .docx, размер больше - * {@code options.maxBytes()}, результат длиннее - * {@code options.maxPages()} страниц и т.п.) + * @throws ValidationException некорректный вход: {@code null}, размер больше + * {@code options.maxBytes()}, документ длиннее {@code options.maxPages()} + * страниц + * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) */ public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException { ConvertOptions opts = options == null ? ConvertOptions.defaults() : options; @@ -96,6 +100,8 @@ public final class WordPdfConverter { try { convertToStream(docxBytes, title, opts, bos); } catch (ConversionException e) { + // ValidationException (отказ валидации входа) — подтип, уходит + // вызывающему без обёртки throw e; } catch (Exception e) { throw new ConversionException("Не удалось конвертировать документ", e); @@ -139,12 +145,13 @@ public final class WordPdfConverter { WordprocessingMLPackage pkg = WordprocessingMLPackage.load( new ByteArrayInputStream(docxBytes)); try { - // 2.5 Проверка числа страниц по самому .docx: кэш Word - // (docProps/app.xml ) или нижняя оценка по явным - // разрывам. Делается до рендера, чтобы не тратить время на - // заведомо длинный документ; внутри try — чтобы и на отказе - // отработал finally с чисткой temp-файлов встроенных шрифтов. - WordPdfValidator.checkPageCount(pkg, options.maxPages()); + // 2.5 Проверка числа страниц по самому .docx: lightweight-оценка + // по zip (кэш docProps/app.xml , явные разрывы, маркеры + // w:lastRenderedPageBreak, включая колонтитулы) — без JAXB-модели. + // Делается до рендера, чтобы не тратить время на заведомо + // длинный документ; внутри try — чтобы и на отказе отработал + // finally с чисткой temp-файлов встроенных шрифтов. + WordPdfValidator.checkPageCount(docxBytes, options.maxPages()); // 3. Привязка маппера: docx4j сопоставляет шрифты документа // с физическими TTF (учитывая и шрифты, встроенные в docx) pkg.setFontMapper(mapper); diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java index 4225492..88d5908 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java @@ -1,15 +1,5 @@ package ru.pjandro.wordpdf; -import org.docx4j.openpackaging.packages.WordprocessingMLPackage; -import org.docx4j.wml.Br; -import org.docx4j.wml.ContentAccessor; -import org.docx4j.wml.P; -import org.docx4j.wml.R; -import org.docx4j.wml.SectPr; -import org.docx4j.wml.STBrType; - -import jakarta.xml.bind.JAXBElement; - import javax.xml.stream.XMLInputFactory; import javax.xml.stream.XMLStreamException; import javax.xml.stream.XMLStreamReader; @@ -27,9 +17,8 @@ import java.util.zip.ZipInputStream; * Валидатор ограничений на входной .docx: * размер входа и число страниц. * - *

Вход валидатора — только {@code byte[]} (или уже загруженный - * {@link WordprocessingMLPackage}): файловых проверок нет, работа с - * файлами — забота вызывающего (приложения). + *

Вход валидатора — только {@code byte[]}: файловых проверок нет, + * работа с файлами — забота вызывающего (приложения). * *

Конвертер {@link WordPdfConverter} вызывает валидатор автоматически, * но им можно пользоваться и напрямую — например, проверить байты @@ -55,7 +44,7 @@ import java.util.zip.ZipInputStream; *

Проверка делается до рендера — это позволяет отсекать слишком * длинные документы, не тратя время на конвертацию. * - *

Все ошибки — {@link ConversionException}. + *

Все ошибки — {@link ValidationException} (наследник {@link ConversionException}). */ public final class WordPdfValidator { @@ -65,9 +54,9 @@ public final class WordPdfValidator { /** * Проверяет размер байтов входа (для документа, полученного из сети/БД). * - * @throws ConversionException при {@code null} или превышении лимита + * @throws ValidationException при {@code null} или превышении лимита */ - public static void checkInput(byte[] docxBytes) throws ConversionException { + public static void checkInput(byte[] docxBytes) throws ValidationException { checkInput(docxBytes, WordPdfSettings.MAX_INPUT_BYTES); } @@ -75,18 +64,18 @@ public final class WordPdfValidator { * Проверяет размер байтов входа против явного лимита (переопределение * на вызов, см. {@link ConvertOptions#maxBytes()}). * - * @throws ConversionException при {@code null} или превышении {@code maxBytes} + * @throws ValidationException при {@code null} или превышении {@code maxBytes} */ - public static void checkInput(byte[] docxBytes, long maxBytes) throws ConversionException { + public static void checkInput(byte[] docxBytes, long maxBytes) throws ValidationException { if (docxBytes == null) { - throw new ConversionException("Не указаны байты входного файла"); + throw new ValidationException("Не указаны байты входного файла"); } if (docxBytes.length > maxBytes) { - // дефолтный лимит кратен MiB — сообщение остаётся «... 20 МБ ...» + // дефолтный лимит кратен MiB — сообщение остаётся «... 5 МБ ...» String limit = maxBytes % (1024 * 1024) == 0 ? (maxBytes / (1024 * 1024)) + " МБ" : maxBytes + " байт"; - throw new ConversionException("Файл больше " + limit + throw new ValidationException("Файл больше " + limit + ": " + docxBytes.length + " байт > " + maxBytes + " байт"); } } @@ -98,32 +87,41 @@ public final class WordPdfValidator { * {@code docProps/app.xml}). Дешёвый путь для проверки байтов из * сети/БД до любой работы с библиотекой. * - *

Оценка согласована с {@link #checkPageCount(WordprocessingMLPackage)} - * по всем источникам; на границе лимита оба пути дают одинаковый ответ - * (регрессия — {@code checkPageCountLightweight_agreesWithJaxbPath}, - * включая 99/100/101 разрывов). Lightweight-путь дополнительно считает - * разрывы в колонтитулах — он консервативнее, расхождение возможно + *

Оценка — максимум трёх нижних оценок: кэша Word в + * {@code docProps/app.xml} ({@code }; сам по себе недостоверен — + * в регрессной фикстуре {@code stale-cache.docx} равен 1 при 110 + * границах страниц), явных разрывов ({@code w:br type="page"}, + * {@code w:pageBreakBefore}, межсекционные {@code w:sectPr} — абзацы + * ищутся рекурсивно, включая ячейки таблиц и контентные контролы + * {@code w:sdt}) и маркеров {@code w:lastRenderedPageBreak} — границ + * страниц, которые Word записал при последнем рендере. Оценка нижняя: + * документ без явных разрывов и без маркеров (никогда не открывался в + * Word) оценивается в 1 страницу независимо от фактической длины — + * такие документы лимит не отсекают. На границе лимита оценка точна + * (регрессия — {@code checkPageCount_limitBoundary}, + * включая 99/100/101 разрывов); путь дополнительно считает разрывы в + * колонтитулах — консервативная нижняя оценка, расхождение возможно * только в сторону завышения. * *

Не-zip байты не отвергаются: {@code ZipInputStream} доходит до EOF * без единой записи — молча, оценка «1 страница». Корректность контейнера * проверяет вызывающий по zip-подписи ({@code ConversionService.validate} * в приложении; регрессия — {@code ConvertControllerTest#corruptNotAZip_rejected}). - * @throws ConversionException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES} + * @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES} */ - public static void checkPageCountLightweight(byte[] docxBytes) throws ConversionException { - checkPageCountLightweight(docxBytes, WordPdfSettings.MAX_PAGES); + public static void checkPageCount(byte[] docxBytes) throws ValidationException { + checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES); } /** - * То же, что {@link #checkPageCountLightweight(byte[])}, с явным лимитом + * То же, что {@link #checkPageCount(byte[])}, с явным лимитом * страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}). * - * @throws ConversionException при {@code null}, ошибке разбора zip или превышении {@code maxPages} + * @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages} */ - public static void checkPageCountLightweight(byte[] docxBytes, int maxPages) throws ConversionException { + public static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException { if (docxBytes == null) { - throw new ConversionException("Не указаны байты входного .docx"); + throw new ValidationException("Не указаны байты входного .docx"); } int pages; try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) { @@ -145,196 +143,14 @@ public final class WordPdfValidator { return b == null ? null : new ByteArrayInputStream(b); }, headerFooter); } catch (IOException | RuntimeException e) { - throw new ConversionException("Не удалось разобрать байты .docx", e); + throw new ValidationException("Не удалось разобрать байты .docx", e); } if (pages > maxPages) { - throw new ConversionException("Документ длиннее " + maxPages + throw new ValidationException("Документ длиннее " + maxPages + " страниц: получено не менее " + pages); } } - /** - * Считает страницы .docx в байтах и проверяет лимит. - * - * @throws ConversionException при {@code null}, ошибке загрузки или превышении лимита - */ - public static void checkPageCount(byte[] docxBytes) throws ConversionException { - checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES); - } - - /** - * То же, что {@link #checkPageCount(byte[])}, с явным лимитом страниц - * (переопределение на вызов, см. {@link ConvertOptions#maxPages()}). - * - * @throws ConversionException при {@code null}, ошибке загрузки или - * превышении {@code maxPages} - */ - public static void checkPageCount(byte[] docxBytes, int maxPages) throws ConversionException { - if (docxBytes == null) { - throw new ConversionException("Не указаны байты входного .docx"); - } - WordprocessingMLPackage pkg; - try { - pkg = WordprocessingMLPackage.load(new ByteArrayInputStream(docxBytes)); - } catch (Exception e) { - throw new ConversionException("Не удалось разобрать байты .docx", e); - } - checkPageCount(pkg, maxPages); - } - - /** - * Считает страницы уже загруженного .docx и проверяет лимит. - * - *

Число страниц — максимум трёх нижних оценок: - *

    - *
  1. Кэш Word в {@code docProps/app.xml} ({@code }). - * Сам по себе недостоверен: Word может сохранить устаревшее - * значение (в регрессной фикстуре {@code stale-cache.docx} - * кэш равен 1 при 110 границах страниц).
  2. - *
  3. Явные разрывы: {@code w:br[@w:type='page']}, - * {@code w:pageBreakBefore} и {@code w:sectPr} прямо в - * {@code w:body}. Абзацы ищутся не только прямо в {@code w:body}, - * но и внутри таблиц, контентных контролов {@code w:sdt} - * (Word держит нумерацию именно в контентном контроле) и - * прочего содержимого, реализующего {@link ContentAccessor}.
  4. - *
  5. Маркеры {@code w:lastRenderedPageBreak} — границы страниц, - * которые Word записал при последнем рендере. Единственный - * источник оценки для документов без явных разрывов, порванных - * по заполнению.
  6. - *
- * - *

Оценка остаётся нижней: документ без явных разрывов и без - * маркеров (никогда не открывался в Word) оценивается в 1 страницу - * независимо от фактической длины — такие документы лимит не отсекают. - * @throws ConversionException при превышении {@link WordPdfSettings#MAX_PAGES} - */ - public static void checkPageCount(WordprocessingMLPackage pkg) throws ConversionException { - checkPageCount(pkg, WordPdfSettings.MAX_PAGES); - } - - /** - * То же, что {@link #checkPageCount(WordprocessingMLPackage)}, с явным - * лимитом страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}). - * - * @throws ConversionException при превышении {@code maxPages} - */ - public static void checkPageCount(WordprocessingMLPackage pkg, int maxPages) throws ConversionException { - if (pkg == null) { - throw new ConversionException("Не указан загруженный .docx"); - } - int pages = pageCountOf(pkg); - if (pages > maxPages) { - throw new ConversionException("Документ длиннее " + maxPages - + " страниц: получено не менее " + pages); - } - } - - /** - * Возвращает число страниц: максимум кэша {@code }, оценки по - * явным разрывам и оценки по {@code w:lastRenderedPageBreak}. - * Виден только из тестов и пакета. - */ - static int pageCountOf(WordprocessingMLPackage pkg) { - int cached = 0; - try { - if (pkg.getDocPropsExtendedPart() != null) { - org.docx4j.docProps.extended.Properties ext = - pkg.getDocPropsExtendedPart().getContents(); - if (ext != null && ext.getPages() != null && ext.getPages() > 0) { - cached = ext.getPages(); - } - } - } catch (Exception ignored) { - // docPropsExtended может быть не полностью инициализирован — - // тогда остаётся оценка по разрывам. - } - // getJaxbElement() возвращает null, когда JAXB-разбор части провалился - // (docx4j пишет в лог «Problem with part» и «gives up») — без проверки - // здесь была бы NPE вместо внятной ошибки. - var document = pkg.getMainDocumentPart() == null - ? null : pkg.getMainDocumentPart().getJaxbElement(); - if (document == null || document.getBody() == null) { - throw new ConversionException("Не удалось разобрать word/document.xml"); - } - var body = document.getBody(); - var content = body.getContent(); - int explicit = 1; // сам документ — минимум одна страница - for (Object child : content) { - // В JAXB-модели в body.getContent() лежат только межсекционные - // sectPr; финальная секция — в body.getSectPr(), её здесь нет. - if (child instanceof SectPr sect && startsNewPage(sect)) { - explicit++; - } - } - explicit += walkForPageBreaks(content); - int lastRendered = countLastRendered(content); - return Math.max(Math.max(cached, explicit), lastRendered + 1); - } - - /** - * Обход содержимого на явные разрывы: абзацы ищутся рекурсивно — - * прямо в {@code w:body}, в ячейках таблиц, в контентных контролах - * {@code w:sdt} и прочем содержимом, реализующем {@link ContentAccessor}. - * Элементы модели приходят и напрямую, и обёрнутыми в - * {@link JAXBElement} (например {@code w:tbl} в {@code w:body}) — - * обёртка раскрывается через {@link #unwrap}. - * Считаются {@code w:br type="page"} и {@code pageBreakBefore} - * (по одному на абзац), как и в lightweight-пути. - */ - private static int walkForPageBreaks(List content) { - int count = 0; - for (Object raw : content) { - Object item = unwrap(raw); - if (item instanceof P p) { - if (p.getPPr() != null - && p.getPPr().getPageBreakBefore() != null - && p.getPPr().getPageBreakBefore().isVal()) { - count++; - } - for (Object runChild : p.getContent()) { - if (unwrap(runChild) instanceof org.docx4j.wml.R r) { - for (Object innerRaw : r.getContent()) { - if (unwrap(innerRaw) instanceof Br br - && br.getType() == STBrType.PAGE) { - count++; - } - } - } - } - } else if (item instanceof ContentAccessor ca) { - // w:tbl / w:tr / w:tc / w:sdt / w:sdtContent и т.п. - count += walkForPageBreaks(ca.getContent()); - } - } - return count; - } - - /** Подсчёт маркеров {@code w:lastRenderedPageBreak} в содержимом. */ - private static int countLastRendered(List content) { - int count = 0; - for (Object raw : content) { - Object item = unwrap(raw); - if (item instanceof R.LastRenderedPageBreak) { - count++; - } else if (item instanceof ContentAccessor ca) { - count += countLastRendered(ca.getContent()); - } - } - return count; - } - - /** Раскрывает обёртку {@link JAXBElement} (docx4j так отдаёт tbl и часть содержимого). */ - private static Object unwrap(Object item) { - return item instanceof JAXBElement je ? je.getValue() : item; - } - - /** Секция, начинающая новую страницу (continuous — нет). */ - private static boolean startsNewPage(SectPr sect) { - return sect.getType() == null - || sect.getType().getVal() == null - || !sect.getType().getVal().equals("continuous"); - } - /** Поставщик потока по имени части zip; null — части нет. */ private interface PartStream { InputStream open(String name) throws IOException; @@ -348,8 +164,7 @@ public final class WordPdfValidator { /** * Лёгкий расчёт числа страниц прямо по zip-пакету .docx, без docx4j. - * Та же логика, что у {@link #pageCountOf(WordprocessingMLPackage)}: - * максимум кэша {@code docProps/app.xml }, явных разрывов и + * Максимум кэша {@code docProps/app.xml }, явных разрывов и * {@code w:lastRenderedPageBreak}. Считаются все колонтитулы * ({@code word/header*.xml}, {@code word/footer*.xml}) — там Word тоже * держит {@code w:br type="page"}. diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java index dc9e6f5..ad35852 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -432,19 +432,19 @@ class WordPdfConverterTest { @Test void invalidInputRejected() { - assertThrows(ConversionException.class, () -> + assertThrows(ValidationException.class, () -> WordPdfConverter.convert(null, "x")); } /** - * Лимит на размер входа: больше 20 MiB — отказ до рендера. + * Лимит на размер входа: больше 5 MiB — отказ до рендера. */ @Test void inputTooLarge() { byte[] tooBig = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; - ConversionException ex = assertThrows(ConversionException.class, () -> + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfConverter.convert(tooBig, "too-big")); - assertTrue(ex.getMessage().contains("20 МБ"), + assertTrue(ex.getMessage().contains("5 МБ"), "сообщение должно упоминать лимит: " + ex.getMessage()); } @@ -455,7 +455,7 @@ class WordPdfConverterTest { */ @Test void limitsOverriddenByOptions() throws Exception { - ConversionException ex = assertThrows(ConversionException.class, () -> + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfConverter.convert(sampleBytes("ru-plain.docx"), "x", new ConvertOptions(true, true, false, false, 1000, WordPdfSettings.MAX_PAGES))); assertTrue(ex.getMessage().contains("1000 байт"), @@ -469,7 +469,7 @@ class WordPdfConverterTest { */ @Test void tooManyPages() { - ConversionException ex = assertThrows(ConversionException.class, () -> + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfConverter.convert( sampleBytes("too-many-pages.docx"), "too-many-pages", new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_BYTES, 100))); @@ -486,7 +486,7 @@ class WordPdfConverterTest { */ @Test void staleCachePageCountRejectedBeforeRender() { - ConversionException ex = assertThrows(ConversionException.class, () -> + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfConverter.convert(sampleBytes("stale-cache.docx"), "stale-cache", new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_BYTES, 100))); assertTrue(ex.getMessage().contains("100"), diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java index a009bbb..8ac59f8 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java @@ -4,7 +4,6 @@ import org.apache.poi.xwpf.usermodel.BreakType; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; import org.apache.poi.xwpf.usermodel.XWPFTable; -import org.docx4j.openpackaging.packages.WordprocessingMLPackage; import org.junit.jupiter.api.Test; import java.io.ByteArrayOutputStream; @@ -16,7 +15,7 @@ import static org.junit.jupiter.api.Assertions.*; /** * Юнит-тесты валидатора: размер и число страниц - * (byte[] и уже загруженный пакет). + * (byte[], lightweight-путь zip/StAX). */ class WordPdfValidatorTest { @@ -42,15 +41,15 @@ class WordPdfValidatorTest { @Test void checkInput_bytesOverLimit() { byte[] big = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; - ConversionException ex = assertThrows(ConversionException.class, + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfValidator.checkInput(big)); - assertTrue(ex.getMessage().contains("20 МБ"), + assertTrue(ex.getMessage().contains("5 МБ"), "сообщение должно упоминать лимит: " + ex.getMessage()); } @Test void checkInput_bytesNull() { - assertThrows(ConversionException.class, + assertThrows(ValidationException.class, () -> WordPdfValidator.checkInput((byte[]) null)); } @@ -61,119 +60,58 @@ class WordPdfValidatorTest { @Test void checkInput_customLimit() { assertDoesNotThrow(() -> WordPdfValidator.checkInput(new byte[10], 100)); - ConversionException ex = assertThrows(ConversionException.class, + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfValidator.checkInput(new byte[11], 10)); assertTrue(ex.getMessage().contains("10 байт"), "сообщение должно упоминать переданный лимит: " + ex.getMessage()); } - @Test - void checkPageCount_pkgWithinLimit() throws Exception { - byte[] bytes = docxWithPageBreaks(5); // 1 + 5 = 6 страниц по оценке - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(pkg)); - } + // ---- lightweight (zip/StAX, без docx4j) ---- @Test - void checkPageCount_pkgOverLimit() throws Exception { - byte[] bytes = docxWithPageBreaks(120); // 1 + 120 = 121 - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCount(pkg, 100)); - assertTrue(ex.getMessage().contains("100"), - "сообщение должно упоминать лимит: " + ex.getMessage()); + void checkPageCount_bytesWithinLimit() throws Exception { + byte[] bytes = docxWithPageBreaks(5); + assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(bytes)); } @Test void checkPageCount_bytesOverLimit() throws Exception { byte[] bytes = docxWithPageBreaks(120); - ConversionException ex = assertThrows(ConversionException.class, + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfValidator.checkPageCount(bytes, 100)); assertTrue(ex.getMessage().contains("100"), "сообщение должно упоминать лимит: " + ex.getMessage()); } - /** - * Явный лимит страниц для загруженного пакета: docx с 2 разрывами - * (оценка 3) отсекается maxPages=1 и проходит при maxPages=1000. - */ - @Test - void checkPageCount_pkg_customLimit() throws Exception { - byte[] bytes = docxWithPageBreaks(2); - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCount(pkg, 1)); - assertTrue(ex.getMessage().contains("длиннее 1 страниц"), - "сообщение должно упоминать переданный лимит: " + ex.getMessage()); - assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(pkg, 1000)); - } - - @Test - void checkPageCount_bytesNull() { - assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCount((byte[]) null)); - } - - @Test - void checkPageCount_pkgNull() { - assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCount((WordprocessingMLPackage) null)); - } - - // ---- lightweight (zip/StAX, без docx4j) ---- - - @Test - void checkPageCountLightweight_bytesWithinLimit() throws Exception { - byte[] bytes = docxWithPageBreaks(5); - assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(bytes)); - } - - @Test - void checkPageCountLightweight_bytesOverLimit() throws Exception { - byte[] bytes = docxWithPageBreaks(120); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(bytes, 100)); - assertTrue(ex.getMessage().contains("100"), - "сообщение должно упоминать лимит: " + ex.getMessage()); - } - /** * Явный лимит страниц lightweight-пути: те же 3 страницы * (2 разрыва) отсекаются maxPages=1 и проходят при maxPages=1000. */ @Test - void checkPageCountLightweight_customLimit() throws Exception { + void checkPageCount_customLimit() throws Exception { byte[] bytes = docxWithPageBreaks(2); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(bytes, 1)); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount(bytes, 1)); assertTrue(ex.getMessage().contains("длиннее 1 страниц"), "сообщение должно упоминать переданный лимит: " + ex.getMessage()); - assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(bytes, 1000)); + assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(bytes, 1000)); } + /** + * Точная граница лимита lightweight-пути: 99 разрывов = 100 страниц + * (проходит), 100/101 = 101/102 (отказ с оценкой «не менее 1+breaks»). + */ @Test - void checkPageCountLightweight_agreesWithJaxbPath() throws Exception { - // на фикстурах без кэша Pages оба пути обязаны совпадать, - // включая границу лимита: 99 разрывов = 100 страниц (проходит), - // 100/101 = 101/102 (отказ) + void checkPageCount_limitBoundary() throws Exception { for (int breaks : new int[]{0, 3, 99, 100, 101}) { byte[] bytes = docxWithPageBreaks(breaks); - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - int jaxb = WordPdfValidator.pageCountOf(pkg); - // lightweight-путь приватный; проверяем через границу лимита: - // 1+breaks совпадает с оценкой JAXB - assertEquals(1 + breaks, jaxb, "JAXB-оценка для " + breaks + " разрывов"); if (breaks < 100) { - assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(bytes, 100)); + assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(bytes, 100)); } else { - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(bytes, 100)); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount(bytes, 100)); assertTrue(ex.getMessage().contains("не менее " + (1 + breaks)), - "оценка lightweight должна совпадать с JAXB: " + ex.getMessage()); + "оценка = 1 + число разрывов: " + ex.getMessage()); } } } @@ -186,10 +124,9 @@ class WordPdfValidatorTest { * 101 страница, отказ (старый код считал «все минус одна» без * учёта типа: 101−1=100 и пропускал). Случай B: 101 * {@code continuous} + финальная {@code nextPage} — 1 страница, - * проходит (старый код раздувал до 102 и отвергал). В JAXB-модели - * body-direct sectPr не видны (docx4j оставляет только финальную - * в {@code body.getSectPr()}, {@code getContent()} пуст), поэтому - * расхождение lightweight здесь — допустимое завышение. + * проходит (старый код раздувал до 102 и отвергал); разрывы в + * колонтитулах только усиливают нижнюю оценку — расхождение с + * точным числом страниц здесь — допустимое завышение. * Регрессия — WordPdfValidator#scanDocument. */ @Test @@ -200,8 +137,8 @@ class WordPdfValidatorTest { } typesA.add("continuous"); // финальная секция — непрерывная byte[] overLimit = docxWithBodySections(typesA); - ConversionException exLwA = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(overLimit, 100)); + ValidationException exLwA = assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount(overLimit, 100)); assertTrue(exLwA.getMessage().contains("не менее 101"), "оценка = 1 + 100 межсекционных nextPage: " + exLwA.getMessage()); @@ -211,7 +148,7 @@ class WordPdfValidatorTest { } typesB.add("nextPage"); // финальная секция byte[] ok = docxWithBodySections(typesB); - assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(ok, 100), + assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(ok, 100), "continuous-границы не страницы"); } @@ -280,16 +217,10 @@ class WordPdfValidatorTest { @Test void pageCount_staleCacheLosesToLastRenderedMarkers() throws Exception { byte[] bytes = staleCacheFixture(); - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - assertEquals(111, WordPdfValidator.pageCountOf(pkg), - "оценка = max(кэш 1, разрывы 1, маркеры 110+1)"); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCount(pkg, 100)); - assertTrue(ex.getMessage().contains("100"), ex.getMessage()); - // lightweight-путь обязан согласовать тот же отказ - assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(bytes, 100)); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount(bytes, 100)); + assertTrue(ex.getMessage().contains("не менее 111"), + "оценка = max(кэш 1, разрывы 1, маркеры 110+1): " + ex.getMessage()); } /** @@ -311,20 +242,16 @@ class WordPdfValidatorTest { doc.write(bos); bytes = bos.toByteArray(); } - WordprocessingMLPackage pkg = WordprocessingMLPackage.load( - new java.io.ByteArrayInputStream(bytes)); - assertEquals(121, WordPdfValidator.pageCountOf(pkg), - "разрывы в ячейке таблицы должны считаться"); - assertThrows(ConversionException.class, + ValidationException ex = assertThrows(ValidationException.class, () -> WordPdfValidator.checkPageCount(bytes, 100)); - assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(bytes, 100)); + assertTrue(ex.getMessage().contains("не менее 121"), + "120 разрывов в ячейке таблицы + первая страница: " + ex.getMessage()); } @Test - void checkPageCountLightweight_bytesNull() { - assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight((byte[]) null)); + void checkPageCount_bytesNull() { + assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount((byte[]) null)); } /** @@ -354,9 +281,9 @@ class WordPdfValidatorTest { // 3 разрыва + первая страница = не менее 4; до фикса lightweight // не видел разрывы в strict-namespace и возвращал 1 - assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(docx, 4)); - ConversionException ex = assertThrows(ConversionException.class, - () -> WordPdfValidator.checkPageCountLightweight(docx, 3)); + assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(docx, 4)); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.checkPageCount(docx, 3)); assertTrue(ex.getMessage().contains("не менее 4"), ex.getMessage()); } } -- 2.56.1 From 45b78f7fc9aa13c130aeac889828c2d4f3e07867 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Mon, 19 Oct 2026 21:30:45 +0000 Subject: [PATCH 2/3] =?UTF-8?q?core,app,web:=20=D0=B4=D0=B5=D1=84=D0=BE?= =?UTF-8?q?=D0=BB=D1=82=D1=8B=20=D0=BB=D0=B8=D0=BC=D0=B8=D1=82=D0=BE=D0=B2?= =?UTF-8?q?=20=D0=B2=D1=85=D0=BE=D0=B4=D0=B0=205=20MiB=20/=20100=20=D1=81?= =?UTF-8?q?=D1=82=D1=80=D0=B0=D0=BD=D0=B8=D1=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 8 +++---- AGENTS.md | 22 +++++++++---------- compose.yml | 4 ++-- gateway/nginx.conf | 2 +- .../src/main/resources/application.properties | 4 ++-- .../ru/pjandro/wordpdf/WordPdfSettings.java | 6 ++--- wordpdf-web/src/components/App.tsx | 4 ++-- 7 files changed, 25 insertions(+), 25 deletions(-) diff --git a/.env.example b/.env.example index 452227f..501dae9 100644 --- a/.env.example +++ b/.env.example @@ -5,7 +5,7 @@ WORDPDF_API_KEY= # Лимиты входа (задаёт только сервер; параметрами запроса не переопределяются). # Либо закомментировано (тогда дефолт), либо конкретное число — пустое # значение ломает старт приложения. -# Максимальный размер .docx в байтах (дефолт 20971520 = 20 МБ) -#WORDPDF_MAX_BYTES=20971520 -# Максимальное число страниц (дефолт 1000) -#WORDPDF_MAX_PAGES=1000 +# Максимальный размер .docx в байтах (дефолт 5242880 = 5 МБ) +#WORDPDF_MAX_BYTES=5242880 +# Максимальное число страниц (дефолт 100) +#WORDPDF_MAX_PAGES=100 diff --git a/AGENTS.md b/AGENTS.md index a2c1af7..9f34153 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Project Overview -Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире секции про контейнеры: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл. +Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире секции про контейнеры: лимиты (пишет 5 МБ/100 стр. — совпадает с кодом; 6 МБ multipart — фактически 100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл. ## Architecture & Data Flow @@ -12,7 +12,7 @@ 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). 2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `StrictOoxmlNormalizer` (strict-OOXML → transitional-байт: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`, элементы и атрибуты `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml), значения `start`/`end` у `w:jc`/`w:tab`; в `mc-preprocessor.xslt` docx4j ветка `%` закомментирована, start/end не маппятся; namespaces и `pt`-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы ``; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»; покрытие — `java.awt.Font.canDisplay` + BitSet-кэш, НЕ docx4j `GlyphCheck` — тот плодит INFO-лог; для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (DejaVu Serif/Tinos/Caladea), затем в sans) → `WordprocessingMLPackage.load`. -3. `WordPdfValidator.checkPageCount(pkg, maxPages)` — **до** рендера. +3. `WordPdfValidator.checkPageCount(docxBytes, maxPages)` — **до** рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди. 4. `pkg.setFontMapper(mapper)` → `DrawingPreRenderer.run(pkg, options)` (шаг 3.5: `c:chart`/`dgm:relIds` docx2fo.xslt не умеет — свой Java2D-движок `internal/chart/*` рендерит в PNG 300 dpi и подменяет на `pic:pic`; объект, выключенный в `ConvertOptions`, пропускается до рендера и остаётся в docx; упавший рендер — объект **удаляется** из docx (`gd.getAny().clear()`) + warn, деградация не падение). 5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`. 6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет). @@ -21,9 +21,9 @@ - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). - Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. -- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). Четыре app-исключения (`ValidationException`, `ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 400/500/503/504. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCountLightweight` (порядок значим). +- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCount` (порядок значим). - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `/actuator/**` (HEALTHCHECK) и документация springdoc (`/swagger-ui*`, `/v3/api-docs*`) — матч по пути **без forwarded-contextPath** (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Springdoc в проде **включён**, документация открыта без ключа под `https://pjandro.ru/pdf-converter/swagger-ui.html` (server-URL/swagger-config собираются из `X-Forwarded-*`, `server.forward-headers-strategy=framework` — `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает). Регрессии — `ApiKeyFilterTest#forwardedPrefix_healthStaysOpen`, `ApiKeyFilterTest#docsOpenWithoutKey`. -- Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (20 MiB / 1000); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. +- Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 MiB / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401 от `ApiKeyFilter`) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). ### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`) @@ -35,7 +35,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр - `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`. - `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback. - FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.2 (пакеты `org.apache.fop.*`); `Fop.Renderers.getRenderer()` возвращает **список** (рендер выбирается по mime `application/pdf`). `docx2fo.xslt` в репозитории нет — он в jar `docx4j-export-fo`. -- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `sectPr` в body + `w:br type="page"` + `pageBreakBefore` (рекурсивно, включая таблицы и `w:sdt`). Lightweight-путь (StAX по zip, secure-ридер без DTD/external entities): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитулах — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy-значения `val`: `null|true|1|on`); на не-zip молчит — подпись проверяет вызывающий. Расхождение lightweight↔JAXB допустимо только в завышение. `pageCountOf` package-private намеренно (тесты); при провале JAXB-разбора (`getJaxbElement()` → null) бросает `ConversionException`, а не NPE. +- Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; JAXB-обход удалён — `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитулах — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy-значения `val`: `null|true|1|on`); на не-zip молчит — подпись проверяет вызывающий. Все отказы — `ValidationException`. - Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно). - Внимательно: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно). @@ -47,7 +47,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |Путь|Назначение| |---|---| -|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCountLightweight`/`checkPageCount` — `byte[]` или pkg, с лимитом/без), `ConversionException`, `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)| +|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`)| |`…/wordpdf/internal/`|5 байтовых нормализатора + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`)| |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| @@ -55,7 +55,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)| |`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key для springdoc) + 4 класса исключений| |`wordpdf-web/src/`|SPA (React 19 + TS + Vite + Tailwind): `api.ts` (вся сеть), `components/` (App, ApiKeyGate, PdfPreview, StatusMessage, DropZone, Logo)| -|корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-20971520`/`WORDPDF_MAX_PAGES:-1000`; podman-специфика обоих compose: `x-podman.name_separator_compat` (docker-style имена контейнеров), явные `healthcheck` app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет), зафиксированная подсеть `10.113.0.0/24` gw `10.113.0.1` под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)| +|корневые `Containerfile`, `compose.yml`, `compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-5242880`/`WORDPDF_MAX_PAGES:-100`; podman-специфика обоих compose: `x-podman.name_separator_compat` (docker-style имена контейнеров), явные `healthcheck` app/web (дубли Containerfile-HEALTHCHECK — OCI-выгрузка его теряет), зафиксированная подсеть `10.113.0.0/24` gw `10.113.0.1` под резолвер aardvark-dns; два repo-стенда одновременно не поднять (общая подсеть)| |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)| |`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| @@ -96,7 +96,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ## Important Files - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. -- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. +- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 5 MiB, `MAX_PAGES` 100, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. - `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=100MB`, держит файл в памяти; в тон gateway `client_max_body_size 100m`), `wordpdf.convert-timeout=2m`, пустой `wordpdf.api-key`, `server.forward-headers-strategy=framework` (префикс прод-прокси для springdoc) + `springdoc.swagger-ui.persist-authorization=true`; `wordpdf.max-bytes`/`max-pages` здесь намеренно нет. - `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core. - `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app). @@ -117,11 +117,11 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ## Testing & QA -- 14 тестовых классов / 126 `@Test` (core 11/104, app 3/22). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). +- 14 тестовых классов / 126 `@Test` (core 11/101, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). - Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). -- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `pageCountOf`, `ChartSpec.readTitle`). +- Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCountLightweight_agreesWithJaxbPath` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). diff --git a/compose.yml b/compose.yml index 46d2b0e..9605685 100644 --- a/compose.yml +++ b/compose.yml @@ -25,8 +25,8 @@ services: # лимиты входа (байты/страницы); значение из .env, иначе дефолты ядра; # интерполяция :- подставляет и на unset, и на пустое — пустая строка # сломала бы binding long/int - WORDPDF_MAX_BYTES: "${WORDPDF_MAX_BYTES:-20971520}" - WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-1000}" + WORDPDF_MAX_BYTES: "${WORDPDF_MAX_BYTES:-5242880}" + WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-100}" web: build: ./wordpdf-web restart: unless-stopped diff --git a/gateway/nginx.conf b/gateway/nginx.conf index beae4f8..a1735d6 100644 --- a/gateway/nginx.conf +++ b/gateway/nginx.conf @@ -4,7 +4,7 @@ server { listen 80; # потолок загрузки стека: больше не пропустит ни шлюз, ни Spring multipart; # авторитетный лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES, - # дефолт 20 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда. + # дефолт 5 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда. client_max_body_size 100m; # app/web резолвятся aardvark-dns, который сидит на шлюзе сети стека # (подсеть зафиксирована в compose.yml / compose.dev.yml, адрес стабилен). diff --git a/wordpdf-app/src/main/resources/application.properties b/wordpdf-app/src/main/resources/application.properties index 015f9df..7f69a76 100644 --- a/wordpdf-app/src/main/resources/application.properties +++ b/wordpdf-app/src/main/resources/application.properties @@ -2,9 +2,9 @@ spring.application.name=wordpdf-app # Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в # nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный # лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES), по умолчанию -# WordPdfSettings.MAX_INPUT_BYTES = 20 MiB; здесь только потолок загрузки. +# WordPdfSettings.MAX_INPUT_BYTES = 5 MiB; здесь только потолок загрузки. # Лимиты входа: env WORDPDF_MAX_BYTES (байты) / WORDPDF_MAX_PAGES (страницы), -# дефолты — константы ядра (20 MiB / 1000), задаются ConvertController. +# дефолты — константы ядра (5 MiB / 100), задаются ConvertController. # Значение <= 0 — падение на старте. Сами ключи здесь не объявлены: # пустое значение затенит SpEL-дефолт @Value. # file-size-threshold=100MB держит файл в памяти (ядро и так читает всё в RAM). diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java index dede785..8bc60bf 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java @@ -9,11 +9,11 @@ package ru.pjandro.wordpdf; */ public final class WordPdfSettings { - /** Максимальный размер входного .docx (дефолт). 20 MiB = 20 × 1024 × 1024. */ - public static final long MAX_INPUT_BYTES = 20L * 1024 * 1024; + /** Максимальный размер входного .docx (дефолт). 5 MiB = 5 × 1024 × 1024. */ + public static final long MAX_INPUT_BYTES = 5L * 1024 * 1024; /** Документ длиннее — ошибка (дефолт). */ - public static final int MAX_PAGES = 1000; + public static final int MAX_PAGES = 100; /** * Генерация диаграмм (c:chart → PNG, chart-движок). {@code false} — диаграммы diff --git a/wordpdf-web/src/components/App.tsx b/wordpdf-web/src/components/App.tsx index b22318c..d24e284 100644 --- a/wordpdf-web/src/components/App.tsx +++ b/wordpdf-web/src/components/App.tsx @@ -152,8 +152,8 @@ export default function App() {

Word → PDF

- docx → PDF на docx4j + Apache FOP. Лимиты (файл ≤ 20 МБ, - ≤ 1000 страниц) задаёт сервер; переопределение из формы убрано. + docx → PDF на docx4j + Apache FOP. Лимиты (файл ≤ 5 МБ, + ≤ 100 страниц) задаёт сервер; переопределение из формы убрано.

-- 2.56.1 From 5482bfac60c17b63bb96dee65aa374e5e6319ab1 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Mon, 19 Oct 2026 21:49:34 +0000 Subject: [PATCH 3/3] =?UTF-8?q?core:=20=D0=BF=D0=B5=D1=80=D0=B5=D0=BD?= =?UTF-8?q?=D0=BE=D1=81=20=D0=B2=D0=B0=D0=BB=D0=B8=D0=B4=D0=B0=D1=86=D0=B8?= =?UTF-8?q?=D0=B8=20=D0=B2=D1=85=D0=BE=D0=B4=D0=B0=20=D0=B8=D0=B7=20Conver?= =?UTF-8?q?sionService=20=D0=B2=20WordPdfValidator.validate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 10 ++-- .../wordpdf/app/ConversionService.java | 31 ++----------- .../ru/pjandro/wordpdf/WordPdfConverter.java | 24 +++++----- .../ru/pjandro/wordpdf/WordPdfValidator.java | 29 +++++++++++- .../pjandro/wordpdf/WordPdfConverterTest.java | 15 ++++++ .../pjandro/wordpdf/WordPdfValidatorTest.java | 46 +++++++++++++++++++ 6 files changed, 109 insertions(+), 46 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9f34153..55c15ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ ### Пайплайн `WordPdfConverter.convert(byte[], String[, ConvertOptions])` (порядок фиксирован, менять местами нельзя) -Наружу `checkInput(bytes, maxBytes)` вызывается **до** приватного `convertToStream`; внутри `convertToStream`: +Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`: 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). 2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим): `StrictOoxmlNormalizer` (strict-OOXML → transitional-байт: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`, элементы и атрибуты `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml), значения `start`/`end` у `w:jc`/`w:tab`; в `mc-preprocessor.xslt` docx4j ветка `%` закомментирована, start/end не маппятся; namespaces и `pt`-значения правит сам mc-preprocessor — собственный рерайт URI ломает его pt-конверсию) → `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`) → `SymbolFontNormalizer` (PUA U+F0xx Symbol/Wingdings/Webdings → Unicode + DejaVu Sans, переписывает и элементы ``; 5 карт по 256 слотов, таблица `SymbolMapper` сгенерирована из docx4j 17.x) → `FieldNormalizer` (`fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, вложенные/битые поля пропускает) → `GlyphCoverageNormalizer` (режет ран по покрытию глифов, пишет семейство в `w:rFonts`, иначе FOP рисует «#»; покрытие — `java.awt.Font.canDisplay` + BitSet-кэш, НЕ docx4j `GlyphCheck` — тот плодит INFO-лог; для serif-ран fallback ищется сначала в `SERIF_FAMILIES` (DejaVu Serif/Tinos/Caladea), затем в sans) → `WordprocessingMLPackage.load`. @@ -21,7 +21,7 @@ - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). - Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. -- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCount` (порядок значим). +- Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). `ValidationException` — тип ядра `ru.pjandro.wordpdf.ValidationException extends ConversionException` (публичный), валидатор бросает его сам, app-дубликата нет; три app-исключения (`ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 500/503/504. `doConvert` перехватывает `ValidationException` раньше `ConversionException` — отказ страницы-лимита из конвейера ядра даёт 400, а не 500. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCount`); тот же метод — вход ядра. - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `/actuator/**` (HEALTHCHECK) и документация springdoc (`/swagger-ui*`, `/v3/api-docs*`) — матч по пути **без forwarded-contextPath** (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Springdoc в проде **включён**, документация открыта без ключа под `https://pjandro.ru/pdf-converter/swagger-ui.html` (server-URL/swagger-config собираются из `X-Forwarded-*`, `server.forward-headers-strategy=framework` — `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает). Регрессии — `ApiKeyFilterTest#forwardedPrefix_healthStaysOpen`, `ApiKeyFilterTest#docsOpenWithoutKey`. - Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 MiB / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401 от `ApiKeyFilter`) подтвердил требование ключа — в dev без ключа форма открывается сразу; запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). @@ -47,7 +47,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |Путь|Назначение| |---|---| -|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)| +|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без, и `validate(byte[], ConvertOptions)` — полная цепочка размер → zip-подпись → страницы; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxBytes, maxPages)| |`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`)| |`…/wordpdf/internal/`|5 байтовых нормализатора + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`)| |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| @@ -117,11 +117,11 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ## Testing & QA -- 14 тестовых классов / 126 `@Test` (core 11/101, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). +- 14 тестовых классов / 132 `@Test` (core 11/107, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). - Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). - Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`↔`inputNotAZip_rejectedBeforeRender`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java index f5de6c2..770f525 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConversionService.java @@ -36,9 +36,9 @@ import java.util.concurrent.TimeoutException; * {@link ConversionFailedException} (500). Граница: сломанный контейнер * (не zip / битый zip / слишком большой / слишком длинный) — 400; валидный * zip с мусором внутри (нет {@code word/document.xml}) — 500: до очереди и - * в конвейере ядра страницы проверяются одним и тем же lightweight-путём - * ({@link WordPdfValidator#checkPageCount}), поэтому уже принятый - * запрос внутренняя проверка ядра в ошибку не превратит.

+ * в конвейере ядра вход проверяется тем же + * {@link WordPdfValidator#validate(byte[], ConvertOptions)}, поэтому уже + * принятый запрос внутренняя проверка ядра в ошибку не превратит.

*/ @Service final class ConversionService { @@ -70,7 +70,7 @@ final class ConversionService { * {@code null} не допускается (контроллер строит всегда).

*/ byte[] convert(byte[] docxBytes, String originalFilename, ConvertOptions options) { - validate(docxBytes, options); + WordPdfValidator.validate(docxBytes, options); Future future; try { future = workers.submit(() -> doConvert(docxBytes, originalFilename, options)); @@ -112,29 +112,6 @@ final class ConversionService { } } - /** - * Валидация байтов переиспользует публичные byte-API ядра; ядро бросает - * {@link ValidationException} само — оборачивать нечего. Порядок значим: - * размер (дешёвая) → magic bytes → lightweight-разбор zip. Лимиты - * размера/страниц берутся из {@code options} (контроллер подставляет их - * из конфигурации сервера: свойства {@code wordpdf.max-bytes}/ - * {@code wordpdf.max-pages}, дефолт — константы ядра). - * - *

Проверка zip-подписи отдельным шагом обязательна: - * {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает - * {@code null} молча, и {@link WordPdfValidator#checkPageCount(byte[])} - * такой вход не отверг бы (0 страниц). Регрессия — - * ConvertControllerTest#corruptNotAZip_rejected.

- */ - void validate(byte[] docxBytes, ConvertOptions options) { - WordPdfValidator.checkInput(docxBytes, options.maxBytes()); - if (docxBytes.length < 4 || docxBytes[0] != 'P' || docxBytes[1] != 'K' - || (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { - throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)"); - } - WordPdfValidator.checkPageCount(docxBytes, options.maxPages()); - } - /** * Тело задачи воркера. Ядро принимает байты — временные файлы не нужны; * имя влияет только на заголовок PDF (параметр {@code title}), потому 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 a0c5398..ec77581 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -57,16 +57,16 @@ public final class WordPdfConverter { * Конвертирует байты .docx в PDF. Работа с файлами — забота вызывающего * (файловое API было здесь раньше; ядро пути не принимает). * - *

Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[])} - * (null / больше {@link WordPdfSettings#MAX_INPUT_BYTES}), затем число страниц - * ({@link WordPdfValidator#checkPageCount(byte[])}, лимит - * {@link WordPdfSettings#MAX_PAGES}) — при отказе байтов результата нет. + *

Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера: + * {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_BYTES} / zip-подпись / + * число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет; + * страницы дополнительно перепроверяются по нормализованным байтам (шаг 2.5). * * @param docxBytes байты .docx * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся * @return байты готового PDF * @throws ValidationException некорректный вход: {@code null}, размер больше - * {@link WordPdfSettings#MAX_INPUT_BYTES}, документ длиннее + * {@link WordPdfSettings#MAX_INPUT_BYTES}, не zip-архив, документ длиннее * {@link WordPdfSettings#MAX_PAGES} страниц * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) */ @@ -78,10 +78,10 @@ public final class WordPdfConverter { * Конвертирует байты .docx в PDF с настройками на вызов: рисование * диаграмм/SmartArt и лимиты входа. * - *

Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[], long)} - * (null / больше {@code options.maxBytes()}), затем число страниц - * ({@link WordPdfValidator#checkPageCount(byte[], int)}, лимит - * {@code options.maxPages()}) — при отказе байтов результата нет. + *

Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера: + * {@code null} / размер больше {@code options.maxBytes()} / zip-подпись / число страниц + * больше {@code options.maxPages()} — при отказе байтов результата нет; страницы + * дополнительно перепроверяются по нормализованным байтам (шаг 2.5). * * @param docxBytes байты .docx * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся @@ -89,13 +89,13 @@ public final class WordPdfConverter { * дефолты (константы {@link WordPdfSettings}) * @return байты готового PDF * @throws ValidationException некорректный вход: {@code null}, размер больше - * {@code options.maxBytes()}, документ длиннее {@code options.maxPages()} - * страниц + * {@code options.maxBytes()}, не zip-архив, документ длиннее + * {@code options.maxPages()} страниц * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) */ public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException { ConvertOptions opts = options == null ? ConvertOptions.defaults() : options; - WordPdfValidator.checkInput(docxBytes, opts.maxBytes()); + WordPdfValidator.validate(docxBytes, opts); ByteArrayOutputStream bos = new ByteArrayOutputStream(); try { convertToStream(docxBytes, title, opts, bos); diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java index 88d5908..3b28b92 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java @@ -105,8 +105,8 @@ public final class WordPdfValidator { * *

Не-zip байты не отвергаются: {@code ZipInputStream} доходит до EOF * без единой записи — молча, оценка «1 страница». Корректность контейнера - * проверяет вызывающий по zip-подписи ({@code ConversionService.validate} - * в приложении; регрессия — {@code ConvertControllerTest#corruptNotAZip_rejected}). + * по zip-подписи проверяет {@link #validate(byte[], ConvertOptions)} + * (регрессия — {@code WordPdfValidatorTest#validate_notAZip}). * @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES} */ public static void checkPageCount(byte[] docxBytes) throws ValidationException { @@ -151,6 +151,31 @@ public final class WordPdfValidator { } } + /** + * Полная проверка входа: размер → zip-подпись → число страниц. Порядок + * значим: размер — дешёвая, разбор zip без подписи бессмысленен. Лимиты + * берутся из {@link ConvertOptions} (переопределение на вызов, см. + * {@link ConvertOptions#maxBytes()}, {@link ConvertOptions#maxPages()}). + * + *

Проверка zip-подписи отдельным шагом обязательна: + * {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает + * {@code null} молча, и {@link #checkPageCount(byte[], int)} такой вход + * не отверг бы (оценка «1 страница»). Регрессия — + * {@code WordPdfValidatorTest#validate_notAZip} (на HTTP-границе — + * {@code ConvertControllerTest#corruptNotAZip_rejected}).

+ * + * @throws ValidationException при {@code null}, превышении {@code options.maxBytes()}, + * отсутствии zip-подписи, ошибке разбора zip или превышении {@code options.maxPages()} + */ + public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException { + checkInput(docxBytes, options.maxBytes()); + if (docxBytes.length < 4 || docxBytes[0] != 'P' || docxBytes[1] != 'K' + || (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { + throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)"); + } + checkPageCount(docxBytes, options.maxPages()); + } + /** Поставщик потока по имени части zip; null — части нет. */ private interface PartStream { InputStream open(String name) throws IOException; diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java index ad35852..7547686 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -448,6 +448,21 @@ class WordPdfConverterTest { "сообщение должно упоминать лимит: " + ex.getMessage()); } + /** + * Вход без zip-подписи — отказ как некорректный вход (ValidationException), + * а не ошибка рендера: вход конвертера прогоняет тот же + * {@link WordPdfValidator#validate(byte[], ConvertOptions)}, что и приложение до очереди. + * Регрессия — WordPdfValidatorTest#validate_notAZip. + */ + @Test + void inputNotAZip_rejectedBeforeRender() { + byte[] junk = new byte[]{1, 2, 3, 4, 5, 6, 7, 8}; + ValidationException ex = assertThrows(ValidationException.class, () -> + WordPdfConverter.convert(junk, "junk")); + assertTrue(ex.getMessage().contains("не zip-архив"), + "сообщение должно упоминать zip-подпись: " + ex.getMessage()); + } + /** * Лимит размера переопределяется {@link ConvertOptions} на вызов: * maxBytes=1000 отсекает даже маленький документ до рендера, сообщение diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java index 8ac59f8..21374ab 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfValidatorTest.java @@ -254,6 +254,52 @@ class WordPdfValidatorTest { () -> WordPdfValidator.checkPageCount((byte[]) null)); } + // ===== validate(byte[], ConvertOptions) ===== + + private static ConvertOptions options(long maxBytes, int maxPages) { + return new ConvertOptions(true, true, false, false, maxBytes, maxPages); + } + + @Test + void validate_withinLimits() throws Exception { + assertDoesNotThrow(() -> WordPdfValidator.validate( + docxWithPageBreaks(5), ConvertOptions.defaults())); + } + + @Test + void validate_bytesOverLimit() { + byte[] big = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(big, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("5 МБ"), + "размер проверяется первым: " + ex.getMessage()); + } + + @Test + void validate_notAZip() { + byte[] junk = new byte[]{1, 2, 3, 4, 5}; + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(junk, ConvertOptions.defaults())); + assertTrue(ex.getMessage().contains("не zip-архив"), + "сообщение должно упоминать zip-подпись: " + ex.getMessage()); + } + + @Test + void validate_tooManyPages() throws Exception { + byte[] bytes = docxWithPageBreaks(120); + ValidationException ex = assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(bytes, + options(WordPdfSettings.MAX_INPUT_BYTES, 100))); + assertTrue(ex.getMessage().contains("не менее 121"), + "оценка = 1 + 120 разрывов: " + ex.getMessage()); + } + + @Test + void validate_nullBytes() { + assertThrows(ValidationException.class, + () -> WordPdfValidator.validate(null, ConvertOptions.defaults())); + } + /** * Lightweight-путь читает сырые байты до нормализации и обязан видеть * разрывы {@code w:br w:type="page"} в strict-namespace'ах -- 2.56.1