diff --git a/AGENTS.md b/AGENTS.md index 6044661..be3fabc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ - **Коды**: 400 — `ValidationException`/`BadRequestException`/битые параметры; 401 — `ApiKeyFilter`; 404/405/415 — путь/метод/content-type; 413 — multipart; **422** — `DrawingRejectedException` (core-`DrawingFoundException`, `Kind {CHARTS, SMARTART, OLE}`); 500/503/504 — `ConversionFailedException`/`ConversionRejectedException`/`ConversionTimeoutException`. Полная карта — `docs/agent/repo-map.md`. - **Текст 422** — контракт с фронтом: «Конвертация отменена: в документе найдены диаграммы/найден SmartArt/найдены OLE-объекты». - **Ключ**: `X-API-Key` ↔ `wordpdf.api-key` (пустое = выключено); без ключа открыты только `OPEN_PREFIXES` (`/actuator/`, `/swagger-ui`, `/v3/api-docs`), пути с точечными сегментами — никогда. -- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503) — ядро не потокобезопасно; головой очереди на старте стоит `warmup()`. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются). +- **Очередь и лимиты**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`QUEUE_CAPACITY = 16`, переполнение → 503): ядро дополнительно сериализует конвертации монитором `WordPdfConverter.class` (`convert()` безопасен из нескольких потоков); головой очереди на старте стоит `warmup()`. Лимиты входа — только конфигурация сервера (`wordpdf.max-mb`/`max-pages`, дефолты из `WordPdfSettings`; ≤ 0 → `IllegalStateException`; параметрами запроса не переопределяются). - **SPA**: вся сеть в `wordpdf-web/src/api.ts`; ключ в `localStorage` (`wordpdf.api.key`); `ApiKeyGate` — только если `probeApiKey()` подтвердил требование ключа (признак открытого сервера — **405**); base — `VITE_BASE`; DropZone `.docx,.doc`. ## Chart/SmartArt-движок (`internal/chart`, 18 классов) @@ -52,7 +52,7 @@ Java2D → PNG: `ChartRenderer.DPI = 300`, потолок `MAX_PIXELS = 16_777_2 - `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`); приложение исключает его — логи ведёт logback. - FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo`, в pom не пинится; пакеты `org.apache.fop.*`). `FopFallbackFonts` берёт `w:renderer` с mime `application/pdf`, иначе первый со шрифтами. - `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF в `wordpdf-fonts-*` (`deleteOnExit`); `dropNonBundled()` чистит `PhysicalFonts` от всего, что вне бандла. -- `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером; `warmup()` идёт тем же потоком. +- `PhysicalFonts` — глобальный и мутируемый → конвертации сериализуются монитором `WordPdfConverter.class` внутри ядра (общая `FopFactory` и сброс её image-кешей — под тем же монитором); приложение держит однопоточный воркер ради 503/timeout; `warmup()` идёт тем же потоком. - Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; правила StAX-подсчёта — `docs/agent/pipeline.md`. - Не чинить: `jc="distribute"`, `suff="tab"`/`lvlJc`, метрика «single», кернинг, `framePr`, `REF`/`SEQ`/`TOC`-кэш, руби-надстрочница, U+2188/U+218A — доказательства в `docs/agent/render-limitations.md`. - Комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно). diff --git a/docs/agent/repo-map.md b/docs/agent/repo-map.md index 113bcdb..05134f8 100644 --- a/docs/agent/repo-map.md +++ b/docs/agent/repo-map.md @@ -95,7 +95,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo | 504 | `ConversionTimeoutException` | - **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `OPEN_PREFIXES` = `/actuator/`, `/swagger-ui`, `/v3/api-docs` — матч по пути **без** forwarded-contextPath (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). Пути с точечными сегментами (`..`/`%2e`) открытыми не считаются никогда. -- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **не потокобезопасно**. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. +- **Очередь**: конвертации сериализованы однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts` и **сериализует конвертации монитором класса `WordPdfConverter.class`**; однопоточность воркера — ради 503/timeout. Головой очереди конструктор ставит `WordPdfConverter.warmup()` — прогрев ядра минимальным in-code docx + растром (~1,5–2,5 с, Future никто не забирает, warmup не бросает): первый реальный запрос после деплоя — за прогретым ядром (замер 2026-11: 0,13 с против 1,74 с на `main`), запросы периода прогрева ждут в очереди штатно. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. - **Лимиты входа** задаёт только конфигурация сервера: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (5 МБ / 100); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. - **SPA**: вся сеть в `wordpdf-web/src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); гейт показывается только когда `probeApiKey()` (GET /api/v1/convert → 401) подтвердил требование ключа. Запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx под префиксом `/pdf-converter/`). Три переключателя error-флагов в форме («Диаграммы», «SmartArt», «OLE-объекты», дефолт — все выключены). DropZone принимает `.docx,.doc` (`accept` + текст зоны). 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 d49b7d8..3be8a3a 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 @@ -23,13 +23,13 @@ import java.util.concurrent.TimeoutException; /** * Конвертация .docx-байтов в PDF-байты поверх {@code wordpdf-core}. * - *
Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом — не «на всякий - * случай»: каждая конвертация мутирует ГЛОБАЛЬНЫЙ реестр шрифтов docx4j - * ({@code new BundledFontMapper()} заново добавляет системные шрифты - * в {@code PhysicalFonts}, {@code BundledFonts.init()/restrictToBundled()} - * их вычищают — WordPdfConverter.convertToStream, шаг 1 пайплайна). Параллельные конвертации - * вырывают реестр друг у друга из-под рендера, ядро не потокобезопасно - * by design. Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.
+ *Конвертации СЕРИАЛИЗОВАНЫ однопоточным executor'ом: он держит очередь, + * 503 при переполнении и timeout-семантику (backpressure). Само ядро при этом + * сериализует конвертации внутренним монитором ({@code WordPdfConverter.class}: + * глобальный реестр {@code PhysicalFonts}, общая FopFactory с имиджевыми + * кешами и их сброс в finally мутируются под рендером), так что параллельные + * вызовы ядра не приводят к порче вывода. + * Регрессия — ConvertControllerTest#concurrentRequests_bothSucceed.
* *Ошибки разделены по смыслу (требование к API): некорректный вход → * {@link ValidationException} (400), ошибка рендер-стадии → @@ -55,8 +55,9 @@ final class ConversionService { new ArrayBlockingQueue<>(QUEUE_CAPACITY)); // Прогрев ядра — головой той же однопоточной очереди: первый реальный // запрос после деплоя становится за прогретым ядром (~50–300 мс вместо - // 1,4–1,9 с) и гарантированно сериализован с конвертациями (ядро не - // потокобезопасно). warmup() не бросает — Future никто не забирает; + // 1,4–1,9 с); сериализация прогрева с конвертациями — тем же воркером + // и монитором ядра (warmup() синхронизирован им же). warmup() не + // бросает — Future никто не забирает; // запросы, пришедшие во время прогрева, ждут в очереди (штатная // семантика, лимит convert-timeout с запасом). this.workers.submit(WordPdfConverter::warmup); 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 b238fd2..0f4bf33 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -55,9 +55,13 @@ import java.util.zip.ZipOutputStream; * подменяются метрически совместимыми open-source аналогами * (см. {@link BundledFontMapper}). * - * Класс stateless, все методы статические. Класс НЕ потокобезопасен: - * конвертации из нескольких потоков необходимо сериализовать (глобальный - * реестр {@code PhysicalFonts}, кэши шрифтов/покрытия). + * Класс stateless, все методы статические. Публичные {@code convert()} можно + * вызывать из нескольких потоков: сериализация обеспечена внутри ядра — + * конвертации выполняются по одной под монитором класса (глобальный реестр + * {@code PhysicalFonts}, общая FopFactory с имиджевыми кешами, сброс кеши в + * finally). {@link #warmup()} синхронизирован тем же монитором. + * {@link WordPdfValidator} stateless и выполняется до монитора — валидация + * параллельна и не блокируется. */ public final class WordPdfConverter { @@ -95,7 +99,8 @@ public final class WordPdfConverter { * файлы), поэтому кеш никогда не попадает и растёт на декодированный растр * каждого изображения (замер 2026-11: ~1,5 ГБ живых byte[] после 30 * конвертаций с картинками). Поэтому каждая конвертация обязана вызвать - * {@link #resetSharedImageCaches()} в finally. + * {@link #resetSharedImageCaches()} в finally. Вызывается только под локом + * конвертации (см. {@code convert}), сброс mid-render невозможен. * Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion. */ static FopFactory sharedFopFactory(final FOSettings foSettings) { @@ -121,6 +126,8 @@ public final class WordPdfConverter { * записи лежат в soft-ссылках, которые сборщик не трогает, пока свободная * куча велика (куча стенда фиксирована 2 ГБ). Сбросы публичные: * {@code ImageCache.clearCache()} и {@code ImageObjectCacheImpl.clearCache()}. + * Вызывается исключительно из finally конвертации под локом (см. + * {@code convert}) — параллельный рендер под сброс не попадает. * Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion. */ static void resetSharedImageCaches() { @@ -204,18 +211,26 @@ public final class WordPdfConverter { // .doc сбрасываются в кадре на этом же месте — детерминированно, до // рендера (точные liveness-карты HotSpot строит только для // скомпилированных кадров; отдельное присваивание null не нужно). - docxBytes = WordPdfValidator.isBinaryDoc(docxBytes) ? DocToDocx.convert(docxBytes) : docxBytes; - ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length)); - try { - convertToStream(docxBytes, title, opts, bos); - } catch (ConversionException e) { - // ValidationException (отказ валидации входа) — подтип, уходит - // вызывающему без обёртки - throw e; - } catch (Exception e) { - throw new ConversionException("Не удалось конвертировать документ", e); + // Единый лок ядра: реестр PhysicalFonts, общая FopFactory (per-render + // disableFontCache, имиджевые кеши) и её сброс в finally мутируются под + // рендером — параллельная конвертация обязана ждать, иначе чистит кеши + // посреди чужого рендера. Монитор класса тот же, что у warmup() + // (реентельно) и DCL в sharedFopFactory. Регрессия — + // WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed. + synchronized (WordPdfConverter.class) { + docxBytes = WordPdfValidator.isBinaryDoc(docxBytes) ? DocToDocx.convert(docxBytes) : docxBytes; + ByteArrayOutputStream bos = new ByteArrayOutputStream(Math.max(1 << 16, docxBytes.length)); + try { + convertToStream(docxBytes, title, opts, bos); + } catch (ConversionException e) { + // ValidationException (отказ валидации входа) — подтип, уходит + // вызывающему без обёртки + throw e; + } catch (Exception e) { + throw new ConversionException("Не удалось конвертировать документ", e); + } + return bos.toByteArray(); } - return bos.toByteArray(); } /** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */ @@ -228,9 +243,11 @@ public final class WordPdfConverter { * (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет * пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не * задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм. - * Идемпотентен, никогда не бросает (провал — только warn); вызывать нужно - * на том же потоке, на котором сериализованы конвертации (ядро не - * потокобезопасно, см. {@code PhysicalFonts}). Артефакты (PDF, растр) + * Идемпотентен, никогда не бросает (провал — только warn); метод + * синхронизирован монитором класса — тем же, что сериализует конвертации + * в {@code convert()}, так что прогрев гарантированно не пересекается с + * рендером; приложение дополнительно держит warmup головой очереди. + * Артефакты (PDF, растр) * отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева * решает вызывающее приложение. */ 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 3040db7..5d3f927 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -2792,4 +2792,42 @@ class WordPdfConverterTest { return ((Map, ?>) m.get(softCache)).size(); } + /** + * Две конвертации из разных потоков обязаны обе отработать корректно: + * ядро сериализует их монитором класса (PhysicalFonts, общая FopFactory, + * сброс image-кешей в finally). Регрессия — этот тест, + * фикстуры samples/ru-plain.docx и samples/chart-types.docx. + */ + @Test + void concurrentConversions_twoThreadsBothSucceed() throws Exception { + byte[] plain = sampleBytes("ru-plain.docx"); + byte[] chart = sampleBytes("chart-types.docx"); + byte[][] out = new byte[2][]; + Runnable[] jobs = { + () -> out[0] = WordPdfConverter.convert(plain, "ru-plain"), + () -> out[1] = WordPdfConverter.convert(chart, "chart-types"), + }; + Thread[] ts = new Thread[2]; + for (int i = 0; i < 2; i++) { + ts[i] = new Thread(jobs[i]); + ts[i].start(); + } + for (Thread t : ts) { + t.join(); + } + assertTrue(out[0] != null && "%PDF".equals(new String(out[0], 0, 4, StandardCharsets.US_ASCII)), + "поток 1 не вернул PDF"); + assertTrue(out[1] != null && "%PDF".equals(new String(out[1], 0, 4, StandardCharsets.US_ASCII)), + "поток 2 не вернул PDF"); + assertTrue(norm(pdfTextBytes(out[0])).contains("Привет, мир!"), "поток 1: текст потерян"); + assertTrue(norm(pdfTextBytes(out[1])).contains("Типы диаграмм"), "поток 2: текст потерян"); + } + + /** Текст PDF из байтов (PDFBox) — для результатов прямого convert(). */ + private static String pdfTextBytes(byte[] pdf) throws IOException { + try (PDDocument doc = Loader.loadPDF(pdf)) { + return new PDFTextStripper().getText(doc); + } + } + }