refactor(core,app): WordPdfSettings упразднён — лимиты входа обязательны в ConvertOptions, пороги производные, REST-параметры maxMb/maxPages
PR checks / web (pull_request) Successful in 33s
PR checks / java (pull_request) Successful in 1m18s

- WordPdfSettings удалён; ConvertOptions.defaults() удалён; 2-аргументный
  convert и безлимитные оверлоды валидатора сняты (options == null → 400)
- производные пороги (распаковка total/XML, пиксели растра, zip-записи)
  считаются из maxMb/maxPages формулами в WordPdfConverter/WordPdfValidator
- мост: DocToDocx.convert(+maxMb) → OfficeArt.read(+maxPixels)
- REST: свойства wordpdf.max-mb/max-pages — дефолт эндпоинта (литералы
  @Value 5/100), параметры запроса maxMb/maxPages переопределяют в обе
  стороны (≤ 0 → 400); верхний потолок отсутствует (решение пользователя)
- HTTP-контексты тестов пиныт wordpdf.api-key= (mise подмешивает .env)
- доки/README/autotests-формулировки синхронизированы
This commit is contained in:
Pjandro
2026-11-08 20:16:52 +00:00
parent 8a8e8a9f84
commit af5d09e001
23 changed files with 375 additions and 362 deletions
+4 -4
View File
@@ -4,7 +4,7 @@
| Путь | Назначение |
|---|---|
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String[,ConvertOptions])`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `WordPdfSettings` (`MAX_INPUT_MB=5`, `MAX_PAGES=100`, крышки автобюджетов распаковки `MAX_DECOMPRESSED_MB=64`/`MAX_DECOMPRESSED_XML_MB=32` — сами бюджеты считает `WordPdfValidator.maxDecompressed*` из `maxMb`/`maxPages`, коэффициенты в `WordPdfConverter.DECOMPRESS_*`; защитные `MAX_IMAGE_PIXELS=25_000_000`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_*=false`), `ConvertOptions` (record) |
| `wordpdf-core/src/main/java/ru/pjandro/wordpdf/` | Публичный API: `WordPdfConverter` (`convert(byte[],String,ConvertOptions)`), `WordPdfValidator` (`checkInput`/`checkPageCount`/`checkPageCountDoc`/`validate` — без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}`), `ConvertOptions` (record; дефолтов в ядре нет). Пороги защиты — производные от лимитов входа: `WordPdfValidator.maxDecompressedBytes`/`maxDecompressedXmlBytes` (`max(MIN_*×MiB, maxMb×10/4MiB + maxPages×64/32KiB)`, крышек нет), `maxZipEntries` (`max(2048, maxMb×512 + maxPages×32)`), `maxImagePixels` (`maxMb×5_000_000`); коэффициенты и полы — package-private литералы `WordPdfConverter` (`DECOMPRESS_*`, `MIN_DECOMPRESSED_*`, `IMAGE_PIXELS_PER_MAX_MB`, `ZIP_ENTRIES_*`, javac их инлайнит — валидатор не инициализирует конвертер) |
| `…/wordpdf/fonts/` | `BundledFonts` (реестр/выгрузка TTF), `BundledFontMapper` (алиасы, self-map, `DISPLAY_NAMES`, `bundledFamily`), `GlyphFont` (глиф-движок fontbox) |
| `…/wordpdf/internal/` | 11 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–10, raw-копия неизменённых записей) + `LayoutPostRenderer` (кастомный `FORenderer`, post-FO padding-компенсация таблиц, шаг 4.25) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`/`LayoutPostRenderer.register`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` |
| `…/wordpdf/internal/doc/` | Мост `.doc` → `.docx`: 18 классов (детали — `docs/agent/doc-bridge.md`) — `CfbReader`, `FibHeader`, `PieceTable`, `Grpprl`, `ChpxIndex`, `PapxIndex`, `Styles`, `Tables`, `Lists`, `Sections`, `FontTable`, `SummaryInfo`, `Headers`, `OfficeArt`, `PrcData`, `DocFile`, `DocxWriter`, `DocToDocx` (публичные `convert`/`countPages`; вложенный `DocxBody` — рендер текста и табличного автомата в XML) |
@@ -29,7 +29,7 @@
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures` + `normalizers(options)` (порядок цепочки).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfValidator.java` — валидация входа и lightweight-подсчёт страниц (StAX, без docx4j).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB = 5`, `MAX_PAGES = 100`, `ERROR_ON_* = false`); рантайм-конфигурации в ядре нет.
- Дефолтов лимитов в ядре нет (`WordPdfSettings` упразднён): лимиты входа всегда приходят с вызовом через `ConvertOptions`, производные пороги считает `WordPdfValidator.max*` (см. таблицу выше).
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/chart/DrawingPreRenderer.java` — замена диаграмм/SmartArt на PNG; владеет `MAX_EXTENT_EMU` и деградацией при падении рендера.
- `wordpdf-app/src/main/resources/application.properties` — multipart 100MB (`max-file-size`/`max-request-size` + `file-size-threshold=2MB` — части крупнее 2 МБ на диск, не в память; в тон 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-mb`/`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.
@@ -80,7 +80,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
## REST API (детали bullet'ов)
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `WordPdfSettings.ERROR_ON_*`). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
Единственный эндпоинт `POST /api/v1/convert`: multipart-поле `file` + факультативные query/form-параметры `errorOnCharts`/`errorOnSmartArt`/`errorOnOle` (дефолт каждого — `false`) и `maxMb`/`maxPages` (лимиты входа, см. «Лимиты входа» ниже). Ответ — `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`/`.doc`-расширения — в `ConvertController` (ошибочный текст 400 — контракт с фронтом); `ConversionService.safeBaseName` — единый источник имени для файла, заголовка ответа и PDF-title (срезает оба расширения; разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Error-флаги диаграмм/SmartArt/OLE на `.doc` не срабатывают (BLIP-плейсхолдеры → картинки, см. «Мост») — описано в `@Operation`.
Полная карта ответов:
@@ -97,7 +97,7 @@ unzip -p ~/.m2/repository/org/docx4j/docx4j-export-fo/<версия>/docx4j-expo
- **Ключ доступа**: `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.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-дефолт.
- **Лимиты входа**: `wordpdf.max-mb`/`wordpdf.max-pages` (env `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`) — дефолт эндпоинта, `@Value` в `ConvertController` с литеральными дефолтами 5/100; значение свойства ≤ 0 → `IllegalStateException` на старте. Параметры запроса `maxMb`/`maxPages` переопределяют дефолт в обе стороны (значения ≤ 0 → 400), верхнего серверного потолка нет — пороги распаковки/записей/растров растут вместе с ними. Ключи в `application.properties` **не объявлены** — пустое значение затенит дефолт `@Value`.
- **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` + текст зоны).