Compare commits

...

11 Commits

Author SHA1 Message Date
Pjandro 2747f99970 fix(doc): отключить кэш шрифтов FOP — .doc падал 500 в контейнере (кэш .fop в текущем каталоге)
PR checks / java (pull_request) Successful in 1m13s
PR checks / web (pull_request) Successful in 39s
2026-10-20 20:51:42 +00:00
Pjandro 9cd9e688b3 feat: конвертация бинарного .doc (Word 97-2003) в PDF (POI HWPF + FOP) 2026-10-20 20:51:42 +00:00
pjandro 903eb71210 Merge pull request 'Единый источник лимитов прода: Gitea Variables для deploy и autotests' (#18) from fix/prod-limits-single-source into main
Main: tests, deploy, autotests / java (push) Successful in 1m12s
Main: tests, deploy, autotests / web (push) Successful in 39s
Main: tests, deploy, autotests / images (push) Successful in 2m15s
Main: tests, deploy, autotests / deploy (push) Successful in 1m3s
Main: tests, deploy, autotests / autotests (push) Successful in 46s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Reviewed-on: #18
2026-10-20 23:45:17 +03:00
Pjandro 1e20949a98 refactor: лимит размера входа во всех слоях — MAX_MB (МБ=MiB), байты вычисляются в checkInput
PR checks / java (pull_request) Successful in 1m7s
PR checks / web (pull_request) Successful in 43s
Ядро: WordPdfSettings.MAX_INPUT_MB=5, ConvertOptions.maxMb,
WordPdfValidator.checkInput(byte[], long maxMb) — единственная точка
пересчёта МБ→байты, сообщение «Файл больше N МБ: X байт > Y байт».
Приложение: свойство wordpdf.max-mb (env WORDPDF_MAX_MB, relaxed binding).
CI/конфиг/автотесты/доки: WORDPDF_MAX_BYTES → WORDPDF_MAX_MB (значение 5).
2026-10-20 20:34:01 +00:00
Pjandro 33a014c307 ci: единый источник лимитов прода — Gitea Variables WORDPDF_MAX_PAGES/WORDPDF_MAX_BYTES
PR checks / java (pull_request) Successful in 1m12s
PR checks / web (pull_request) Successful in 43s
deploy/rollback экспортируют обе Variables в окружение прод-compose (app
пересоздаётся с лимитами), autotests сверяют проверки с ними же (fail-closed
без обеих). Новый автотест test_oversized_vs_limit ловит расхождение
байтового лимита сервера и ожидания; fixture max_bytes (дефолт 5242880).
GITEA-vars.md/AGENTS.md приведены к фактическим лимитам 100 стр./5 MiB.
2026-10-20 20:21:56 +00:00
pjandro 8f45238afa Merge pull request 'docs: AGENTS.md — без деталей конфига act_runner (инфра вне репо, DEPLOY.md)' (#17) from docs/runner-options-key into main
Main: tests, deploy, autotests / java (push) Successful in 1m8s
Main: tests, deploy, autotests / web (push) Successful in 42s
Main: tests, deploy, autotests / images (push) Successful in 2m10s
Main: tests, deploy, autotests / deploy (push) Successful in 57s
Main: tests, deploy, autotests / autotests (push) Failing after 50s
Main: tests, deploy, autotests / rollback (push) Successful in 52s
Reviewed-on: #17
2026-10-20 22:48:10 +03:00
Pjandro e9d84f2889 docs: AGENTS.md — детали конфига act_runner убраны из репо (инфра вне репо, DEPLOY.md)
PR checks / java (pull_request) Successful in 1m7s
PR checks / web (pull_request) Successful in 42s
2026-10-20 19:04:02 +00:00
ai f94ad29c62 Merge pull request 'ci: образы собирает CI и пушит в Nexus-реестр, прод-деплой = pull' (#16) from ci/registry-docker-deploy into main
Main: tests, deploy, autotests / java (push) Successful in 3m5s
Main: tests, deploy, autotests / web (push) Successful in 46s
Main: tests, deploy, autotests / images (push) Successful in 5m36s
Main: tests, deploy, autotests / deploy (push) Successful in 1m3s
Main: tests, deploy, autotests / autotests (push) Failing after 51s
Main: tests, deploy, autotests / rollback (push) Successful in 53s
2026-10-20 21:40:54 +03:00
Pjandro c75e8894a5 ci: образы собирает CI и пушит в Nexus-реестр, прод-деплой = pull
PR checks / java (pull_request) Successful in 3m29s
PR checks / web (pull_request) Successful in 45s
- main.yml: новый job images (docker build + push, теги prod + sha-<7>,
  DOCKER_BUILDKIT=0 — daemon за раннером podman); deploy: needs images,
  restart.sh --deploy, .rollback.env без PREV_COMMIT (git-клон src на проде
  больше не нужен); rollback: retag image ID на реестровые :prod
- GITEA-vars.md: Secrets REGISTRY_USER/REGISTRY_PASSWORD, Variable REGISTRY
- AGENTS.md: CI/CD и Деплой переписаны под pull-поток
2026-10-20 18:27:43 +00:00
pjandro 6e2ac77133 Merge pull request 'ci: Gitea workflows (PR checks, main deploy+rollback), GITEA-vars guide' (#15) from ci/gitea-workflows into main
Main: tests, deploy, autotests / java (push) Successful in 1m13s
Main: tests, deploy, autotests / web (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 7m15s
Main: tests, deploy, autotests / autotests (push) Failing after 56s
Main: tests, deploy, autotests / rollback (push) Successful in 54s
Reviewed-on: #15
2026-10-20 20:41:04 +03:00
Pjandro fadaee76cf ci: Gitea workflows (PR checks, main deploy+rollback), GITEA-vars guide; координаты стенда — в Gitea Variables/Secrets
PR checks / java (pull_request) Successful in 1m8s
PR checks / web (pull_request) Successful in 48s
2026-10-20 17:38:41 +00:00
29 changed files with 1743 additions and 144 deletions
+2 -2
View File
@@ -5,7 +5,7 @@ WORDPDF_API_KEY=
# Лимиты входа (задаёт только сервер; параметрами запроса не переопределяются). # Лимиты входа (задаёт только сервер; параметрами запроса не переопределяются).
# Либо закомментировано (тогда дефолт), либо конкретное число — пустое # Либо закомментировано (тогда дефолт), либо конкретное число — пустое
# значение ломает старт приложения. # значение ломает старт приложения.
# Максимальный размер .docx в байтах (дефолт 5242880 = 5 МБ) # Максимальный размер .docx в МБ (MiB, дефолт 5)
#WORDPDF_MAX_BYTES=5242880 #WORDPDF_MAX_MB=5
# Максимальное число страниц (дефолт 100) # Максимальное число страниц (дефолт 100)
#WORDPDF_MAX_PAGES=100 #WORDPDF_MAX_PAGES=100
+209
View File
@@ -0,0 +1,209 @@
name: "Main: tests, deploy, autotests"
on:
push:
branches: [main]
workflow_dispatch:
jobs:
java:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Setup JDK 21
uses: actions/setup-java@v5
with:
java-version: '21'
distribution: 'temurin'
- name: Cache Maven repository
uses: actions/cache@v4
with:
path: ~/.m2/repository
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
restore-keys: maven-
- name: Setup Maven 3.9.16
run: |
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
run: mvn -B clean verify
web:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Cache npm
uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ hashFiles('wordpdf-web/package-lock.json') }}
restore-keys: npm-
- name: Install dependencies
working-directory: wordpdf-web
run: npm ci
- name: Build SPA
working-directory: wordpdf-web
run: npm run build
- name: Lint SPA
working-directory: wordpdf-web
run: npm run lint
images:
runs-on: ubuntu-latest
needs: [java, web]
steps:
- uses: actions/checkout@v5
- name: Check registry vars and secret
env:
REGISTRY: ${{ vars.REGISTRY }}
REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
run: |
[ -n "$REGISTRY" ] && [ -n "$REGISTRY_USER" ] && [ -n "$REGISTRY_PASSWORD" ] || {
echo "Задайте Actions Variable REGISTRY и Secrets REGISTRY_USER/REGISTRY_PASSWORD — см. GITEA-vars.md" >&2
exit 1
}
- name: Docker auth
env:
REGISTRY: ${{ vars.REGISTRY }}
REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
run: |
mkdir -p ~/.docker
printf '{"auths":{"%s":{"auth":"%s"}}}' "$REGISTRY" \
"$(printf '%s:%s' "$REGISTRY_USER" "$REGISTRY_PASSWORD" | base64 -w0)" > ~/.docker/config.json
- name: Build and push app image
env:
REGISTRY: ${{ vars.REGISTRY }}
run: |
sha="${GITHUB_SHA:0:7}"
# DOCKER_BUILDKIT=0: daemon за раннером — podman, BuildKit-сессий нет,
# только classic /build (buildah).
DOCKER_BUILDKIT=0 docker build -f Containerfile \
-t "$REGISTRY/wordpdf-app:prod" -t "$REGISTRY/wordpdf-app:sha-$sha" .
docker push "$REGISTRY/wordpdf-app:prod"
docker push "$REGISTRY/wordpdf-app:sha-$sha"
- name: Build and push web image
env:
REGISTRY: ${{ vars.REGISTRY }}
run: |
sha="${GITHUB_SHA:0:7}"
# VITE_BASE прод-префикса пёкся раньше build-аргом в прод-compose;
# теперь он здесь — образ из реестра едет на прод как есть.
DOCKER_BUILDKIT=0 docker build -f wordpdf-web/Containerfile \
--build-arg VITE_BASE=/pdf-converter/ \
-t "$REGISTRY/wordpdf-web:prod" -t "$REGISTRY/wordpdf-web:sha-$sha" wordpdf-web
docker push "$REGISTRY/wordpdf-web:prod"
docker push "$REGISTRY/wordpdf-web:sha-$sha"
deploy:
runs-on: ubuntu-latest
needs: images
steps:
- name: Check deploy vars and secret
env:
DEPLOY_HOST: ${{ vars.DEPLOY_HOST }}
DEPLOY_USER: ${{ vars.DEPLOY_USER }}
DEPLOY_DIR: ${{ vars.DEPLOY_DIR }}
REGISTRY: ${{ vars.REGISTRY }}
WORDPDF_MAX_MB: ${{ vars.WORDPDF_MAX_MB }}
WORDPDF_MAX_PAGES: ${{ vars.WORDPDF_MAX_PAGES }}
DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
run: |
[ -n "$DEPLOY_HOST" ] && [ -n "$DEPLOY_USER" ] && [ -n "$DEPLOY_DIR" ] && [ -n "$REGISTRY" ] && [ -n "$WORDPDF_MAX_MB" ] && [ -n "$WORDPDF_MAX_PAGES" ] && [ -n "$DEPLOY_SSH_KEY" ] || {
echo "Задайте Actions Variables DEPLOY_HOST/DEPLOY_USER/DEPLOY_DIR/REGISTRY/WORDPDF_MAX_MB/WORDPDF_MAX_PAGES и Secret DEPLOY_SSH_KEY — см. GITEA-vars.md" >&2
exit 1
}
- name: Save rollback state and deploy
uses: appleboy/ssh-action@v1.0.3
with:
host: ${{ vars.DEPLOY_HOST }}
username: ${{ vars.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
script_stop: true
script: |
set -euo pipefail
cd "${{ vars.DEPLOY_DIR }}"
export WORDPDF_MAX_MB="${{ vars.WORDPDF_MAX_MB }}" WORDPDF_MAX_PAGES="${{ vars.WORDPDF_MAX_PAGES }}"
umask 077
{
echo "PREV_APP=$(podman inspect -f '{{.Image}}' wordpdf-prod-app-1)"
echo "PREV_WEB=$(podman inspect -f '{{.Image}}' wordpdf-prod-web-1)"
} > .rollback.env
./restart.sh --deploy
autotests:
runs-on: ubuntu-latest
needs: deploy
steps:
- uses: actions/checkout@v5
- name: Setup venv
run: |
python3 -m venv .venv
.venv/bin/pip install -q -r prod-autotests/requirements.txt
- name: Check autotest vars and secret
env:
WORDPDF_BASE_URL: ${{ vars.WORDPDF_BASE_URL }}
WORDPDF_MAX_PAGES: ${{ vars.WORDPDF_MAX_PAGES }}
WORDPDF_MAX_MB: ${{ vars.WORDPDF_MAX_MB }}
WORDPDF_API_KEY: ${{ secrets.WORDPDF_API_KEY }}
run: |
[ -n "$WORDPDF_BASE_URL" ] && [ -n "$WORDPDF_MAX_PAGES" ] && [ -n "$WORDPDF_MAX_MB" ] && [ -n "$WORDPDF_API_KEY" ] || {
echo "Задайте Actions Variables WORDPDF_BASE_URL/WORDPDF_MAX_PAGES/WORDPDF_MAX_MB и Secret WORDPDF_API_KEY — см. GITEA-vars.md" >&2
exit 1
}
- name: Run prod autotests
env:
WORDPDF_BASE_URL: ${{ vars.WORDPDF_BASE_URL }}
WORDPDF_MAX_PAGES: ${{ vars.WORDPDF_MAX_PAGES }}
WORDPDF_MAX_MB: ${{ vars.WORDPDF_MAX_MB }}
WORDPDF_API_KEY: ${{ secrets.WORDPDF_API_KEY }}
run: cd prod-autotests && ../.venv/bin/python -m pytest -q .
rollback:
runs-on: ubuntu-latest
needs: [deploy, autotests]
if: failure()
steps:
- name: Roll back prod to previous images
uses: appleboy/ssh-action@v1.0.3
with:
host: ${{ vars.DEPLOY_HOST }}
username: ${{ vars.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
script_stop: true
script: |
set -euo pipefail
cd "${{ vars.DEPLOY_DIR }}"
export WORDPDF_MAX_MB="${{ vars.WORDPDF_MAX_MB }}" WORDPDF_MAX_PAGES="${{ vars.WORDPDF_MAX_PAGES }}"
if [ ! -f .rollback.env ]; then
echo "НЕТ .rollback.env — АВТОМАТИЧЕСКИЙ ОТКАТ НЕВОЗМОЖЕН" >&2
exit 1
fi
. ./.rollback.env
podman tag "$PREV_APP" "${{ vars.REGISTRY }}/wordpdf-app:prod"
podman tag "$PREV_WEB" "${{ vars.REGISTRY }}/wordpdf-web:prod"
podman-compose up -d --force-recreate app web
for _ in $(seq 1 60); do
[ "$(podman inspect -f '{{.State.Health.Status}}' wordpdf-prod-app-1)" = healthy ] && break
sleep 2
done
[ "$(podman inspect -f '{{.State.Health.Status}}' wordpdf-prod-app-1)" = healthy ] || { echo "app НЕ healthy после отката" >&2; exit 1; }
podman-compose restart gateway
curl -fsS http://127.0.0.1:9010/actuator/health
+56
View File
@@ -0,0 +1,56 @@
name: PR checks
on:
pull_request:
workflow_dispatch:
jobs:
java:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Setup JDK 21
uses: actions/setup-java@v5
with:
java-version: '21'
distribution: 'temurin'
- name: Cache Maven repository
uses: actions/cache@v4
with:
path: ~/.m2/repository
key: maven-${{ hashFiles('pom.xml', 'wordpdf-core/pom.xml', 'wordpdf-app/pom.xml') }}
restore-keys: maven-
- name: Setup Maven 3.9.16
run: |
curl -fsSL https://dlcdn.apache.org/maven/maven-3/3.9.16/binaries/apache-maven-3.9.16-bin.tar.gz | tar xz -C /opt
echo "/opt/apache-maven-3.9.16/bin" >> "$GITHUB_PATH"
- name: Build and test (PMD gate included)
run: mvn -B clean verify
web:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Cache npm
uses: actions/cache@v4
with:
path: ~/.npm
key: npm-${{ hashFiles('wordpdf-web/package-lock.json') }}
restore-keys: npm-
- name: Install dependencies
working-directory: wordpdf-web
run: npm ci
- name: Build SPA
working-directory: wordpdf-web
run: npm run build
- name: Lint SPA
working-directory: wordpdf-web
run: npm run lint
+57 -19
View File
@@ -2,7 +2,7 @@
## Project Overview ## 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 — фактически 100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл. Конвертер `.docx`/`.doc` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP; бинарный `.doc` Word 97-2003 — через POI HWPF, без 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 ## Architecture & Data Flow
@@ -10,6 +10,8 @@
Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`: Наружу `WordPdfValidator.validate(docxBytes, options)` (размер → zip-подпись `PK\x03\x04` → страницы) вызывается **до** приватного `convertToStream`; внутри `convertToStream`:
**Шаг 0**: вход с OLE2-магиком `D0 CF 11 E0 A1 B1 1A E1` (бинарный `.doc`) уходит в `internal.DocToPdfRenderer.render` **до** создания `BundledFontMapper` — docx4j-машинерия и все нормализаторы (zip-путь) для него бессмысленны; см. «Ветка .doc» ниже.
1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз добавляет системные шрифты в реестр `PhysicalFonts`; ключ реестра — имя из name-таблицы TTF, `addPhysicalFont(URI)` не перезаписывает занятый → `init()` вызывает `dropNonBundled()` **до** регистрации и `load()` (иначе системный Calibri ломает em-dash-fallback). 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, переписывает и элементы `<w:sym>`; 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`. 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, переписывает и элементы `<w:sym>`; 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(docxBytes, maxPages)` — **до** рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди. 3. `WordPdfValidator.checkPageCount(docxBytes, maxPages)` — **до** рендера, lightweight (zip/StAX) по нормализованным байтам — тот же путь, что у приложения до очереди.
@@ -17,13 +19,17 @@
5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`. 5. `new FOSettings(pkg)` + `FopFallbackFonts.declare` (декларирует **все** бандл-семейства — FOP встраивает только задекларированные) → `FORendererApacheFOP`/`FOUserAgent` (непустой `title` → заголовок PDF) → `Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL)`.
6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет). 6. `finally`: `deleteEmbeddedFontTempFiles()` (в 17.x `OpcPackage.close()` нет).
### Ветка `.doc` (`internal/DocToPdfRenderer`, public только `render`)
POI `WordToFoConverter` (HWPF→XSL-FO) → тот же FOP-форк. Порядок: `BundledFonts.init()` (без `restrictToBundled` — FOP-конфиг строится строкой с `auto-detect="false"`, системные шрифты в рендер не попадают) → `POIFSFileSystem`/`HWPFDocument` → `FontReplacer` (имя = name-таблица TTF через `BundledFontMapper.bundledFamily`) → `PicturesManager` во временный каталог (без него POI **молча пропускает** картинки; пустые картинки — `null`, иначе FOP падает EOFException) → `processDocument` → пост-обработка FO-DOM: `applyDefaultFont` (инлайны POI без `font-family` — иначе базовый Helvetica) и `injectHeadersAndFooters` (POI колонтитулы не пишет): `HeaderStories` odd/even/first × header/footer, чанки по `\u000c`; в мастер — `region-before`/`region-after` (`extent` = top/bottom margin из `margin`-шортхэнда `region-body`, **margin'ы `region-body` сохраняются** — форк FOP не вычитает extent'ы регионов из body-области, единственная защита от наезда текста на колонтитулы — собственные margin'ы body; порядок детей body→before→after — требование валидации форка; зазор — маргинами блоков, padding регионов FOP валит), в `page-sequence` — `fo:static-content` перед `fo:flow`; first/even — эвристика «непустая история ⇒ вариант» (флаги titlePg/evenAndOdd POI не отдаёт) через `fo:page-sequence-master` + `conditional-page-master-reference` first/even/rest. Поля в текстах историй — управляющие символы `\u0013/\u0014/\u0015`: `PAGE` → `fo:page-number`, `NUMPAGES`/`SECTIONPAGES` → `fo:page-number-citation-last` по последнему мастеру; `fo:page-number` без `font-family` блока рисуется Helvetica — блок получает семейство первого рана. Свойство `tabs` FOP-форк не знает — табы = пробелы до дефолтной остановки 1,25 см. Принятая деградация против Word: дрейф вёрстки (18 стр. против 12 на фикстуре), экзотические глифы остаются `.notdef` (аналога `GlyphCoverageNormalizer` нет), first/even-варианты эвристикой. Флаги `renderCharts`/`renderSmartArt`/`errorOn*` — no-op.
### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`) ### REST API (`wordpdf-app`, всё package-private кроме `WordPdfApplication`)
- Единственный эндпоинт `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`). - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка расширений `.docx`/`.doc` — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). Для `.doc` ответ несёт `X-Wordpdf-Degraded: headers-footers-exotic-glyphs` (деградация вёрстки/колонтитулов/экзотических глифов).
- Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. - Конвертации **сериализованы** однопоточным `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. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `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 / не OLE2 / размер / страницы) → 400, валидный контейнер с мусором внутри → 500. Валидация до очереди: `WordPdfValidator.validate(docxBytes, options)` (внутри порядок значим: `checkInput` → подпись контейнера (zip `PK\x03\x04` **или** OLE2 `D0 CF 11 E0`) → страницы); тот же метод — вход ядра.
- **Ключ доступа**: `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`. - **Ключ доступа**: `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-дефолт. - Лимиты входа задаёт **только конфигурация сервера**: `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: вся сеть в `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/`). - 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`) ### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
@@ -35,7 +41,9 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
- `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`. - `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам (без них нет колонок) → FOP падает на `docx4j-baseline`.
- `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback. - `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`. - 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`.
- Форк FOP вырезал `PageMaster.setupRegions` (в jar нет `layoutmgr/PageMaster*`/`RegionXY`): `area.Page` строит viewport `region-body` как page-area минус **собственные** margin'ы body, `extent` у `region-before`/`region-after` body-регион не уменьшает — в `.doc`-ветке разводка body и колонтитулов только margin'ами `region-body` (регрессия `DocToPdfTest#legacyDoc_bodyClearsHeaderFooterRegions`). Docx-ветку не касается: docx4j сам закладывает высоты колонтитулов в margin'ы мастера.
- Страницы в валидаторе = `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`. - Страницы в валидаторе = `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`.
- `.doc`: `checkDocPageCountLightweight` = кэш `SummaryInformation.getPacket().getPageCount()` (Word 97-2003 писал число страниц в OLE2-метаданные; явных разрывов из FIB не извлечь) — тот же stale-cache риск, что и `docProps/app.xml`; `0`/отсутствие пакета → молча. FOP-конфиг `.doc`-ветки — строка с `auto-detect="false"` + `resource://fonts/...` (классы `FOPFontProvider`/`FopConfParser` package-private, JAXB-обход `rendererFonts` к ним не применим). Кэш шрифтов отключён (`FOUserAgent.getFontManager().disableFontCache()` в `renderFo`): дефолт форка — `<user.home>/.fop/fop-fonts.cache`, а при непригодном `user.home` (null/несуществующий каталог — non-root контейнер без HOME) файл `.fop` в текущем каталоге, `/app` в образе не пишется → 500 на `.doc` (регрессия `DocToPdfTest#legacyDoc_fontCacheNotWrittenToWorkingDir`).
- Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно). - Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно).
- Внимательно: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно). - Внимательно: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно).
@@ -47,17 +55,19 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|Путь|Назначение| |Путь|Назначение|
|---|---| |---|---|
|`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-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` — `byte[]`, с лимитом/без, `checkDocPageCountLightweight` — OLE2-`.doc`, и `validate(byte[], ConvertOptions)` — полная цепочка размер → подпись контейнера (zip/OLE2) → страницы; без зависимости от docx4j — только POI для `.doc`), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `WordPdfSettings` (константы-дефолты), `ConvertOptions` (record: renderCharts, renderSmartArt, maxMb, maxPages)|
|`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`)| |`…/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/`|5 байтовых нормализатора + `FopFallbackFonts` + `DocToPdfRenderer` (ветка `.doc`; классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`declare`/`render`)|
|`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)|
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)| |`wordpdf-core/src/test/resources/samples/`|12 закоммиченных фикстур: 11 `.docx` + `legacy-doc.doc` (OLE2, ветка `.doc`)|
|`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-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)| |`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:-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-стенда одновременно не поднять (общая подсеть)| |корневые `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_MB:-5`/`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`, вне репо)| |корневой `.env.example`|шаблон env: `WORDPDF_API_KEY` (`openssl rand -hex 32`), закомментированные `WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES`; реальный прод `.env` — на прод-сервере (координаты: `/home/pjandro/prod/java-word-pdf/DEPLOY.md`, вне репо)|
|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 18 проверок): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`, в venv от uv pip досеивается `ensurepip`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh` (знает прод-настройки: base URL, лимит 1000 стр., ключ из соседнего `.env`)| |`.gitea/workflows/`|Gitea Actions: `pr.yml` (PR checks), `main.yml` (тесты → `images` (docker build + push в Nexus) → deploy (pull) → autotests → rollback)|
|корневой `GITEA-vars.md`|инструкция владельца: Secrets/Variables, защита ветки, перезапуск — только имена переменных, без значений|
|корневой `prod-autotests/`|прод-автотесты API (pytest + requests, 19 проверок): конфигурация стенда **только env** (`WORDPDF_BASE_URL` обязателен, `WORDPDF_API_KEY`/`WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB`/`WORDPDF_SAMPLES_DIR` факультативны) — прод-хостов/ключей в коде нет; окружение — mise (`mise.toml`: python 3.15 + автосоздаваемый `.venv`, в venv от uv pip досеивается `ensurepip`); прод-раннер вне git — `/home/pjandro/prod/java-word-pdf/run-prod-tests.sh` (знает прод-настройки: base URL, лимит 100 стр. (= Gitea Variable `WORDPDF_MAX_PAGES`), ключ из соседнего `.env`)|
|`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать| |`develop/` (вне git)|рабочие материалы и эталоны Word 365 (`word.docx`+`word.pdf`, `word-export.*`, `convert.pdf`, `1212.pdf`, `diff/`) — **ручное сравнение, не фикстуры**, в тесты/jar не подключать|
## Development Commands ## Development Commands
@@ -74,7 +84,7 @@ npm run build # (wordpdf-web/) tsc -b && vite build
podman-compose -f compose.dev.yml up -d --build # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл podman-compose -f compose.dev.yml up -d --build # dev-стенд: http://<LAN-IP хоста>:9011 (0.0.0.0), без ключа, springdoc вкл
``` ```
Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать): Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` и `legacy-doc.doc` НЕ генерируются — созданы вручную, не перезаписывать):
```bash ```bash
mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
@@ -82,7 +92,35 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples
``` ```
Деплой. **Прод** — на пользовательском LAN-сервере (podman 5.8.2 + podman-compose 1.6.0, бинарников `docker`/`docker-compose` на сервере нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--build` — пересборка образов из `origin/main` + перезапуск; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только запушенное в `main` — рабочее дерево на сборку не влияет. Прод-compose `/opt/wordpdf/docker-compose.yml` (вне git) содержит podman-специфику: `x-podman.name_separator_compat` (имена `wordpdf-prod-app-1`, от них зависит `restart.sh`), явные healthcheck app/web и фиксированную подсеть `10.112.0.0/24` gw `10.112.0.1`. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа отличается от репо только резолвером `10.112.0.1` — под свою подсеть — и `proxy_read_timeout 300s` — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + `proxy_pass` через переменную есть и там и там). Тот же наружный nginx в `location /pdf-converter/` добавляет `X-Forwarded-Host: $host` и `X-Forwarded-Prefix: /pdf-converter` — из них springdoc собирает server-URL спека и swagger-config под префиксом (без `X-Forwarded-Host` server = `https://app:8080`, gateway шлёт приложению `Host: app:8080`); канонический URL документации `https://pjandro.ru/pdf-converter/swagger-ui.html` — открыт без ключа. **Dev-стенд** — из репо `compose.dev.yml` (проект `wordpdf-dev`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без env → ключ пуст, springdoc вкл). Репозиторный `compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Containerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. Деплой. **Прод** — на пользовательском LAN-сервере (podman 5.8.2 + podman-compose 1.6.0, бинарников `docker`/`docker-compose` на сервере нет); координаты сервера, каталог, restart-секвенция, ключ и гейты успешности — вне репо: `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (обязательно прочитать перед любым деплоем/перезапуском; в том каталоге лежат архивные файлы старого стека 88.14 — `restart.sh.old-88.14`, старый compose/nginx — **не поднимать**). Единая точка входа с dev-машины — `/home/pjandro/prod/java-word-pdf/restart.sh` (пробрасывает флаги удалённому скрипту: `--deploy` — pull образов `wordpdf-{app,web}:prod` из Nexus-реестра (их собирает CI, job `images`) и пересоздание app/web; без флага — restart контейнеров; предупреждает о не запушенном в `main`). В прод попадает только собранное CI из `main` — рабочее дерево на сборку не влияет; прод не собирает код и git-клона на проде нет (insecure-запись реестра в `/etc/containers/registries.conf.d/`, креды `REGISTRY_USER`/`REGISTRY_PASSWORD` в прод `.env`). Прод-compose `/opt/wordpdf/docker-compose.yml` (вне git) содержит podman-специфику: `x-podman.name_separator_compat` (имена `wordpdf-prod-app-1`, от них зависит `restart.sh`), явные healthcheck app/web и фиксированную подсеть `10.112.0.0/24` gw `10.112.0.1`. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа отличается от репо только резолвером `10.112.0.1` — под свою подсеть — и `proxy_read_timeout 300s` — в репо его нет, дефолтные 60s рвут 2-минутные конвертации; resolver + `proxy_pass` через переменную есть и там и там). Тот же наружный nginx в `location /pdf-converter/` добавляет `X-Forwarded-Host: $host` и `X-Forwarded-Prefix: /pdf-converter` — из них springdoc собирает server-URL спека и swagger-config под префиксом (без `X-Forwarded-Host` server = `https://app:8080`, gateway шлёт приложению `Host: app:8080`); канонический URL документации `https://pjandro.ru/pdf-converter/swagger-ui.html` — открыт без ключа. **Dev-стенд** — из репо `compose.dev.yml` (проект `wordpdf-dev`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без env → ключ пуст, springdoc вкл). Репозиторный `compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Containerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом; на прод-путь не влияет — там `VITE_BASE=/pdf-converter/` запекает CI в job `images`). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка.
## CI/CD (Gitea Actions)
Два workflow. `.gitea/workflows/pr.yml` — `PR checks` (`pull_request` + `workflow_dispatch`):
job `java` (temurin 21, кеш `~/.m2` через `actions/cache`, Maven 3.9.16, `mvn -B clean verify`)
и `web` (кеш `~/.npm`, `npm ci`/`build`/`lint`). `.gitea/workflows/main.yml` — `Main: tests,
deploy, autotests` (`push` в `main` + `workflow_dispatch`): те же `java`/`web` (байт-в-байт
дубль — файлы самодостаточны, reusable-workflow не вводить), затем `images` (`docker build`
обоих Containerfile + `docker push` в Nexus-реестр `${{ vars.REGISTRY }}`, теги `prod` +
immovable `sha-<7 символов GITHUB_SHA>`; `DOCKER_BUILDKIT=0` обязателен — daemon за
раннером podman, BuildKit-сессий нет; job-контейнеры видят podman-сокет хоста — настройка
раннера вне репо, см. DEPLOY.md), `deploy` (SSH на прод:
сохранить `.rollback.env` — image ID контейнеров app/web — затем
`restart.sh --deploy` в директории деплоя (Variable `DEPLOY_DIR`): login в реестр +
`podman-compose pull` + `--force-recreate app web`; export Variables
`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` в окружение compose — лимиты прода задаются
ими, `autotests`/`rollback` используют те же), `autotests` (venv +
`prod-autotests/` против прода),
`rollback` (`if: failure()` — retag прежних image ID на `${{ vars.REGISTRY }}/wordpdf-app:prod`
и `…/wordpdf-web:prod`, `--force-recreate app web`, рестарт gateway). Кеш раннеров —
сервер act_runner, хранилище на ZFS tank (серверная часть, вне репо).
**Правило: координаты прода и креды в коммитимые файлы не попадают** — ни внутренние IP, ни
SSH-пользователи/логины, ни хосты, ни директория деплоя, ни ключи/токены/пароли. Координаты
стенда — Gitea Actions **Variables** (`DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_DIR`,
`WORDPDF_BASE_URL`, `WORDPDF_MAX_PAGES`, `WORDPDF_MAX_MB`, `REGISTRY`), креды — **Secrets** (`DEPLOY_SSH_KEY`,
`WORDPDF_API_KEY`, `REGISTRY_USER`, `REGISTRY_PASSWORD`); workflow-файлы ссылаются на них только `${{ vars.* }}`/`${{ secrets.* }}`.
Инструкция владельца — корневой `GITEA-vars.md` (только имена, без значений).
## Code Conventions & Common Patterns ## Code Conventions & Common Patterns
@@ -97,11 +135,11 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
## Important Files ## Important Files
- `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. - `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` 5 MiB, `MAX_PAGES` 100, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_MB` 5, `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/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-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. - `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). - `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app).
- Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`. - Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (compile в core — `poi-scratchpad`, ветка `.doc`; test — `poi-ooxml`, генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`.
- Корневой `pmd-ruleset.xml` — ruleset PMD (см. Testing & QA): `category/java/codestyle.xml` минус opinionated-правила, `MethodNamingConventions` с `junit5TestPattern` под underscore-имена регрессий, `TooManyStaticImports` до 12, XPath-правило `LiteralFirstInEquals`, unused-правила из `bestpractices.xml`. - Корневой `pmd-ruleset.xml` — ruleset PMD (см. Testing & QA): `category/java/codestyle.xml` минус opinionated-правила, `MethodNamingConventions` с `junit5TestPattern` под underscore-имена регрессий, `TooManyStaticImports` до 12, XPath-правило `LiteralFirstInEquals`, unused-правила из `bestpractices.xml`.
- `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. - `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF.
- `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). `wordpdf-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует. - `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). `wordpdf-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует.
@@ -120,11 +158,11 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
## Testing & QA ## Testing & QA
- Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `verify` для обоих модулей, ruleset `pmd-ruleset.xml` (codestyle без opinionated-правил + unused-правила + XPath `LiteralFirstInEquals` — строковый литерал слева в `equals`/`equalsIgnoreCase`; `junit5TestPattern` разрешает underscore-имена регрессий; `includeTests=true` — тесты сканируются). - Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `verify` для обоих модулей, ruleset `pmd-ruleset.xml` (codestyle без opinionated-правил + unused-правила + XPath `LiteralFirstInEquals` — строковый литерал слева в `equals`/`equalsIgnoreCase`; `junit5TestPattern` разрешает underscore-имена регрессий; `includeTests=true` — тесты сканируются).
- 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`). - 15 тестовых классов / 145 `@Test` (core 12/116, app 3/29). 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 таблицах). - **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 таблицах). В `DocToPdfTest` маркер `#` НЕ проверяется: в `.doc`-ветке нет `GlyphCoverageNormalizer`, экзотические глифы легально остаются `.notdef`, а PDFBox «ремонтирует» подмножества установленных в системе шрифтов и извлекает `#` — текст/assertions только по Tinos/Carlito-ранам.
- Пиксели (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]). - Пиксели (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` (кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). - Фикстуры — закоммиченные `samples/*` (12: 11 `.docx` + `legacy-doc.doc`; в тестах не генерировать): 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` (кэш `<Pages>1</Pages>` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `legacy-doc.doc` (реальный Word 97-2003: 43 картинки, колонтитулы с PAGE-полем, кэш `Pages=12`).
- Юниты нормализаторов работают строками (`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`). - Юниты нормализаторов работают строками (`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`). - 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`, `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). - Регрессивные пары (фикс = нормализатор/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_neitherDocxNorDoc`↔`inputNotAZip_rejectedBeforeRender`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`), `DocToPdfTest`↔`DocToPdfRenderer` (`legacyDoc_convertsToPdf` — Tinos/Carlito без Helvetica + 43 картинки; `legacyDoc_footersCarryPageNumbers` — инъекция колонтитулов + PAGE; `ole2Junk_rejected`; `legacyDoc_fontCacheNotWrittenToWorkingDir` — кэш шрифтов не в CWD (контейнер: /app не пишется)); `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), `legacyDoc_convertsToPdf` (OLE2-развилка валидации ядра + заголовок `X-Wordpdf-Degraded`).
- UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn).
+52
View File
@@ -0,0 +1,52 @@
# Настройка Gitea для CI/CD этого репо
Секреты, переменные и защиту ветки заводит **владелец репо** в Web UI — у CI-токена прав
admin нет. Workflow-файлы уже в репо; прогоны main-пайплайна без Variables/Secrets падают на
job'ах `deploy`/`autotests` с внятным сообщением, чего не хватает, — это ожидаемо. После
заполнения перезапустите упавший run («Re-run jobs» на странице run'а) или запустите
`Main: tests, deploy, autotests` вручную (Actions → Run workflow, branch `main`).
**Правило: координаты прода и креды в файлы репо не попадают** — ни в workflow'ы, ни в этот
гайд: здесь только имена Variables/Secrets, значения живут только в Gitea.
## Секреты (Settings → Actions → Secrets)
|Имя|Значение|Где взять|
|---|---|---|
|`DEPLOY_SSH_KEY`|Приватный SSH-ключ деплоя на прод (целиком, PEM)|CI-ключ `wordpdf-ci-deploy` на dev-машине; публичная половина уже добавлена в `authorized_keys` деплой-пользователя прод-сервера|
|`WORDPDF_API_KEY`|Прод-ключ API wordpdf|`.env` в директории деплоя на прод-сервере (значение `WORDPDF_API_KEY`)|
|`REGISTRY_USER`|Логин docker-реестра для CI-пуша (`ci-deploy`)|Nexus: Security → Users (роль `ci-deploy-role`, права на docker-hosted репозиторий)|
|`REGISTRY_PASSWORD`|Пароль этого пользователя|Тот же, что в `.env` директории деплоя на прод-сервере (значение `REGISTRY_PASSWORD`)|
## Переменные (Settings → Actions → Variables)
|Имя|Значение|
|---|---|
|`DEPLOY_HOST`|Адрес прод-сервера (туда Actions ходит по SSH)|
|`DEPLOY_USER`|SSH-пользователь прод-сервера с правами на podman|
|`DEPLOY_DIR`|Абсолютный путь директории деплоя на прод-сервере (compose, `restart.sh`, `.rollback.env`, `.env`)|
|`WORDPDF_BASE_URL`|Базовый URL прод-API для автотестов (вида `https://<домен-прода>/pdf-converter`)|
|`WORDPDF_MAX_PAGES`|Лимит страниц на проде (сейчас `100`)|
|`WORDPDF_MAX_MB`|Лимит размера входного .docx, МБ (сейчас `5`)|
|`REGISTRY`|Адрес docker-реестра `host:port` без схемы (Nexus docker-registry на прод-сервере, коннектор `:5000`)|
При смене лимитов прода — править `WORDPDF_MAX_PAGES`/`WORDPDF_MAX_MB` в Variables, PR не нужен: job `deploy` прокидывает их в прод-stack (app пересоздаётся с новыми лимитами), job `autotests` сверяет проверки с ними же. Без обеих Variables job'ы `deploy`/`autotests` падают на проверке — fail-closed.
## Защита ветки main (блокировка мержа до зелёных проверок)
Settings → Branches → Branch Protection → Add protection:
- Branch name: `main`
- включить **Enable Status Check on Merge**
- **Status checks on merge**: `PR checks / java (pull_request), PR checks / web (pull_request)`
Контексты — фактические строки статуса, которые Gitea 1.26 публикует для job'ов Actions
(формат `<workflow> / <job> (<event>)`, проверено на первом PR-ране), а не голые имена
job'ов. `deploy`/`autotests` в список НЕ включать: на PR они не запускаются,
мерж блокировался бы навсегда.
## Ручной перезапуск проверок
- Упавший run: страница run'а → **Re-run jobs** (можно только упавшие job'ы).
- Новый прогон main-пайплайна без нового коммита: Actions → `Main: tests, deploy, autotests`
→ **Run workflow** (branch `main`) — триггер `workflow_dispatch`.
- PR-проверки без нового коммита: Actions → `PR checks` → Run workflow (branch PR-ветки).
+2 -2
View File
@@ -22,10 +22,10 @@ services:
# документация в прод-интернете не нужна (в dev/java -jar остаётся включена) # документация в прод-интернете не нужна (в dev/java -jar остаётся включена)
SPRINGDOC_API_DOCS_ENABLED: "false" SPRINGDOC_API_DOCS_ENABLED: "false"
SPRINGDOC_SWAGGER_UI_ENABLED: "false" SPRINGDOC_SWAGGER_UI_ENABLED: "false"
# лимиты входа (байты/страницы); значение из .env, иначе дефолты ядра; # лимиты входа (МБ/страницы); значение из .env, иначе дефолты ядра;
# интерполяция :- подставляет и на unset, и на пустое — пустая строка # интерполяция :- подставляет и на unset, и на пустое — пустая строка
# сломала бы binding long/int # сломала бы binding long/int
WORDPDF_MAX_BYTES: "${WORDPDF_MAX_BYTES:-5242880}" WORDPDF_MAX_MB: "${WORDPDF_MAX_MB:-5}"
WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-100}" WORDPDF_MAX_PAGES: "${WORDPDF_MAX_PAGES:-100}"
web: web:
build: ./wordpdf-web build: ./wordpdf-web
+1 -1
View File
@@ -3,7 +3,7 @@
server { server {
listen 80; listen 80;
# потолок загрузки стека: больше не пропустит ни шлюз, ни Spring multipart; # потолок загрузки стека: больше не пропустит ни шлюз, ни Spring multipart;
# авторитетный лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES, # авторитетный лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB,
# дефолт 5 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда. # дефолт 5 MiB). Без директивы upload режется HTML-413 от шлюза до бэкенда.
client_max_body_size 100m; client_max_body_size 100m;
# app/web резолвятся aardvark-dns, который сидит на шлюзе сети стека # app/web резолвятся aardvark-dns, который сидит на шлюзе сети стека
+6
View File
@@ -85,6 +85,12 @@
<artifactId>pdfbox</artifactId> <artifactId>pdfbox</artifactId>
<version>${pdfbox.version}</version> <version>${pdfbox.version}</version>
</dependency> </dependency>
<!-- Чтение бинарных .doc (HWPF) и экспорт HWPF->XSL-FO (WordToFoConverter) -->
<dependency>
<groupId>org.apache.poi</groupId>
<artifactId>poi-scratchpad</artifactId>
<version>${poi.version}</version>
</dependency>
<!-- Только для генерации тестовых .docx (одноразово), в рантайм не используется --> <!-- Только для генерации тестовых .docx (одноразово), в рантайм не используется -->
<dependency> <dependency>
<groupId>org.apache.poi</groupId> <groupId>org.apache.poi</groupId>
+8 -1
View File
@@ -9,7 +9,8 @@ WORDPDF_BASE_URL обязателен: без него все проверки
где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа где есть заголовок ключа или ожидается 401, пропускаются (без локального ключа
нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый нельзя знать, включена ли аутентификация на стенде). WORDPDF_MAX_PAGES — ожидаемый
лимит страниц стенда (конфигурация сервера, не константа набора; дефолт 100 = лимит страниц стенда (конфигурация сервера, не константа набора; дефолт 100 =
дефолт ядра). .docx-фикстуры — из wordpdf-core/src/test/resources/samples, дефолт ядра). WORDPDF_MAX_MB — ожидаемый лимит размера .docx стенда в МБ (MiB; дефолт
5 = дефолт ядра). .docx-фикстуры — из wordpdf-core/src/test/resources/samples,
либо из WORDPDF_SAMPLES_DIR. либо из WORDPDF_SAMPLES_DIR.
""" """
@@ -55,6 +56,12 @@ def max_pages():
return int(os.environ.get("WORDPDF_MAX_PAGES", "100")) return int(os.environ.get("WORDPDF_MAX_PAGES", "100"))
@pytest.fixture(scope="session")
def max_mb():
"""Ожидаемый лимит размера входа стенда, МБ (MiB): серверная конфигурация, не константа набора."""
return int(os.environ.get("WORDPDF_MAX_MB", "5"))
@pytest.fixture(scope="session") @pytest.fixture(scope="session")
def api_key(): def api_key():
return os.environ.get("WORDPDF_API_KEY", "").strip() return os.environ.get("WORDPDF_API_KEY", "").strip()
+33 -1
View File
@@ -5,6 +5,9 @@ ConvertController на main. Флаги конвертации передают
(контроллер принимает и form, но query детерминированнее). (контроллер принимает и form, но query детерминированнее).
""" """
import io
import zipfile
import requests import requests
from conftest import TIMEOUT, needs_key from conftest import TIMEOUT, needs_key
@@ -113,7 +116,8 @@ def test_too_many_pages_vs_limit(url, samples, key_header, max_pages):
"""too-many-pages.docx (151 стр.): сверх лимита стенда — 400 до рендера; ниже лимита — конвертится. """too-many-pages.docx (151 стр.): сверх лимита стенда — 400 до рендера; ниже лимита — конвертится.
Лимит страниц — конфигурация сервера (env WORDPDF_MAX_PAGES), не константа Лимит страниц — конфигурация сервера (env WORDPDF_MAX_PAGES), не константа
набора: прод идёт со 1000, там фикстура — валидный вход; 400-ветка покрыта набора: лимит стенда приходит переменной `WORDPDF_MAX_PAGES` (на проде —
Gitea Variable, сейчас 100), там фикстура — отказ; 400-ветка покрыта
Java-регрессией WordPdfConverterTest#staleCachePageCountRejectedBeforeRender. Java-регрессией WordPdfConverterTest#staleCachePageCountRejectedBeforeRender.
""" """
r = requests.post( r = requests.post(
@@ -151,6 +155,34 @@ def test_stale_cache_vs_limit(url, samples, key_header, max_pages):
assert r.content[:4] == b"%PDF" assert r.content[:4] == b"%PDF"
@needs_key
def test_oversized_vs_limit(url, samples, key_header, max_mb):
"""Граница размера: валидный zip-docx больше WORDPDF_MAX_MB стенда (МБ) — 400 от checkInput до рендера.
Раздутый нулями ZIP_STORED-филлер остаётся валидным zip, так что 400
может дать только проверка размера (не подпись zip). Если лимит сервера
расходится с WORDPDF_MAX_MB в большую сторону — сервер вернёт не 400
и тест это поймает.
"""
max_bytes = max_mb * 1024 * 1024
buf = io.BytesIO()
with zipfile.ZipFile(samples / "en-plain.docx") as src, \
zipfile.ZipFile(buf, "w", zipfile.ZIP_STORED) as out:
for item in src.infolist():
out.writestr(item, src.read(item.filename))
out.writestr("filler.bin", b"\0" * (max_bytes + 1))
payload = buf.getvalue()
assert len(payload) > max_bytes
r = requests.post(
url(CONVERT),
headers=key_header,
files={"file": ("oversized.docx", payload)},
timeout=TIMEOUT,
)
assert r.status_code == 400
assert "error" in r.json()
@needs_key @needs_key
def test_not_a_zip_rejected(url, notzip_docx, key_header): def test_not_a_zip_rejected(url, notzip_docx, key_header):
"""Граница «сломанный контейнер → 400, а не 500»: .docx-суффикс, содержимое — мусор.""" """Граница «сломанный контейнер → 400, а не 500»: .docx-суффикс, содержимое — мусор."""
@@ -67,7 +67,7 @@ final class ApiExceptionHandler {
/** /**
* Контейнерный потолок multipart (100 МБ в application.properties) * Контейнерный потолок multipart (100 МБ в application.properties)
* сработал раньше ядра: срабатывает только на инфраструктурный лимит, * сработал раньше ядра: срабатывает только на инфраструктурный лимит,
* авторитетный (свойство {@code wordpdf.max-bytes}/env {@code WORDPDF_MAX_BYTES}) * авторитетный (свойство {@code wordpdf.max-mb}/env {@code WORDPDF_MAX_MB})
* проверяет {@code WordPdfValidator} и отвечает 400 своим текстом. * проверяет {@code WordPdfValidator} и отвечает 400 своим текстом.
*/ */
@ExceptionHandler(MaxUploadSizeExceededException.class) @ExceptionHandler(MaxUploadSizeExceededException.class)
@@ -113,6 +113,7 @@ final class ConversionService {
} }
/** /**
* Тело задачи воркера. Ядро принимает байты — временные файлы не нужны; * Тело задачи воркера. Ядро принимает байты — временные файлы не нужны;
* имя влияет только на заголовок PDF (параметр {@code title}), потому * имя влияет только на заголовок PDF (параметр {@code title}), потому
* санитизировано. * санитизировано.
@@ -139,7 +140,7 @@ final class ConversionService {
/** /**
* Санитизация имени (единый источник для имени файла и Content-Disposition): * Санитизация имени (единый источник для имени файла и Content-Disposition):
* без каталога, только буквы/цифры/пробел/ {@code . _ -}, без суффикса * без каталога, только буквы/цифры/пробел/ {@code . _ -}, без суффикса
* .docx; пустое после очистки → {@code document}. Кириллица разрешена — * .docx/.doc; пустое после очистки → {@code document}. Кириллица разрешена —
* на Linux это валидное имя файла, и заголовок PDF остаётся читаемым. * на Linux это валидное имя файла, и заголовок PDF остаётся читаемым.
*/ */
static String safeBaseName(String original) { static String safeBaseName(String original) {
@@ -147,8 +148,11 @@ final class ConversionService {
: original.substring(Math.max(original.lastIndexOf('/'), : original.substring(Math.max(original.lastIndexOf('/'),
original.lastIndexOf('\\')) + 1); original.lastIndexOf('\\')) + 1);
base = base.replaceAll("[^\\p{L}\\p{N} ._-]", ""); base = base.replaceAll("[^\\p{L}\\p{N} ._-]", "");
if (base.toLowerCase(Locale.ROOT).endsWith(".docx")) { String lower = base.toLowerCase(Locale.ROOT);
base = base.substring(0, base.length() - ".docx".length()); String suffix = lower.endsWith(".docx") ? ".docx"
: lower.endsWith(".doc") ? ".doc" : null;
if (suffix != null) {
base = base.substring(0, base.length() - suffix.length());
} }
if (base.isBlank()) { if (base.isBlank()) {
base = "document"; base = "document";
@@ -12,6 +12,7 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value; import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.multipart.MultipartFile; import org.springframework.web.multipart.MultipartFile;
import ru.pjandro.wordpdf.ConvertOptions; import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.WordPdfValidator;
import ru.pjandro.wordpdf.WordPdfSettings; import ru.pjandro.wordpdf.WordPdfSettings;
import ru.pjandro.wordpdf.ValidationException; import ru.pjandro.wordpdf.ValidationException;
@@ -21,21 +22,22 @@ import java.util.Locale;
/** /**
* Единственный эндпоинт API: {@code POST /api/v1/convert} — multipart-поле * Единственный эндпоинт API: {@code POST /api/v1/convert} — multipart-поле
* {@code file} (.docx) → синхронный ответ байтами PDF. * {@code file} (.docx или бинарный .doc) → синхронный ответ байтами PDF.
* *
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование * <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) — * {@code Content-Disposition}; проверка содержимого (подпись контейнера
* зона {@link ConversionService#validate}. Ошибки в JSON-ответ переводит * zip/OLE2, размер, страницы) — зона {@link WordPdfValidator#validate(byte[], ConvertOptions)}.
* Ошибки в JSON-ответ переводит
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера * {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера
* (свойства {@code wordpdf.max-bytes}/{@code wordpdf.max-pages}, env * (свойства {@code wordpdf.max-mb}/{@code wordpdf.max-pages}, env
* {@code WORDPDF_MAX_BYTES}/{@code WORDPDF_MAX_PAGES}); параметрами запроса * {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}); параметрами запроса
* они не переопределяются.</p> * они не переопределяются.</p>
*/ */
@RestController @RestController
final class ConvertController { final class ConvertController {
private final ConversionService conversionService; private final ConversionService conversionService;
private final long maxBytes; private final long maxMb;
private final int maxPages; private final int maxPages;
/** /**
@@ -45,24 +47,27 @@ final class ConvertController {
* отсекается» — худший исход, чем не поднявшийся сервис. * отсекается» — худший исход, чем не поднявшийся сервис.
*/ */
ConvertController(ConversionService conversionService, ConvertController(ConversionService conversionService,
@Value("${wordpdf.max-bytes:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_INPUT_BYTES}}") long maxBytes, @Value("${wordpdf.max-mb:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_INPUT_MB}}") long maxMb,
@Value("${wordpdf.max-pages:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_PAGES}}") int maxPages) { @Value("${wordpdf.max-pages:#{T(ru.pjandro.wordpdf.WordPdfSettings).MAX_PAGES}}") int maxPages) {
if (maxBytes <= 0) { if (maxMb <= 0) {
throw new IllegalStateException("wordpdf.max-bytes должен быть больше 0: " + maxBytes); throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
} }
if (maxPages <= 0) { if (maxPages <= 0) {
throw new IllegalStateException("wordpdf.max-pages должен быть больше 0: " + maxPages); throw new IllegalStateException("wordpdf.max-pages должен быть больше 0: " + maxPages);
} }
this.conversionService = conversionService; this.conversionService = conversionService;
this.maxBytes = maxBytes; this.maxMb = maxMb;
this.maxPages = maxPages; this.maxPages = maxPages;
} }
@Operation(summary = "Конвертировать .docx в PDF", @Operation(summary = "Конвертировать .docx или .doc в PDF",
description = "renderCharts/renderSmartArt/errorOnCharts/errorOnSmartArt — факультативно, " description = "renderCharts/renderSmartArt/errorOnCharts/errorOnSmartArt — факультативно, "
+ "по умолчанию настройки ядра; render-флаг приоритетнее error-флага. " + "по умолчанию настройки ядра; render-флаг приоритетнее error-флага. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера " + "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются") + "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются. "
+ ".doc (Word 97-2003) конвертируется с деградацией вёрстки: шрифты — аналоги из бандла, "
+ "колонтитулы переносятся, диаграммы — как встроенные превью-изображения; "
+ "renderCharts/renderSmartArt/errorOn* на .doc не влияют")
@SecurityRequirement(name = OpenApiConfig.SCHEME) @SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping( @PostMapping(
path = "/api/v1/convert", path = "/api/v1/convert",
@@ -78,9 +83,10 @@ final class ConvertController {
throw new ValidationException("Файл не передан (multipart-поле «file» обязательно)"); throw new ValidationException("Файл не передан (multipart-поле «file» обязательно)");
} }
String name = file.getOriginalFilename(); String name = file.getOriginalFilename();
if (name == null || !name.toLowerCase(Locale.ROOT).endsWith(".docx")) { if (name == null || !(name.toLowerCase(Locale.ROOT).endsWith(".docx")
|| name.toLowerCase(Locale.ROOT).endsWith(".doc"))) {
// расширение проверяется здесь: ядро с байтов его не видит // расширение проверяется здесь: ядро с байтов его не видит
throw new ValidationException("Поддерживается только .docx (без .doc): " + name); throw new ValidationException("Поддерживаются только .docx и .doc: " + name);
} }
byte[] docxBytes; byte[] docxBytes;
try { try {
@@ -93,14 +99,20 @@ final class ConvertController {
renderSmartArt != null ? renderSmartArt : WordPdfSettings.RENDER_SMARTART, renderSmartArt != null ? renderSmartArt : WordPdfSettings.RENDER_SMARTART,
errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS, errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS,
errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART, errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART,
maxBytes, maxPages); maxMb, maxPages);
byte[] pdf = conversionService.convert(docxBytes, name, options); byte[] pdf = conversionService.convert(docxBytes, name, options);
ContentDisposition disposition = ContentDisposition.attachment() ContentDisposition disposition = ContentDisposition.attachment()
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8) .filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
.build(); .build();
return ResponseEntity.ok() ResponseEntity.BodyBuilder response = ResponseEntity.ok()
.contentType(MediaType.APPLICATION_PDF) .contentType(MediaType.APPLICATION_PDF)
.header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString()) .header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString());
.body(pdf); if (name.toLowerCase(Locale.ROOT).endsWith(".doc")) {
// .doc (не .docx): POI HWPF даёт дрейф вёрстки, колонтитулы —
// инъекция в FO-DOM, экзотические глифы остаются .notdef —
// клиент обязан знать о деградации (см. internal.DocToPdfRenderer).
response = response.header("X-Wordpdf-Degraded", "headers-footers-exotic-glyphs");
}
return response.body(pdf);
} }
} }
@@ -1,10 +1,10 @@
spring.application.name=wordpdf-app spring.application.name=wordpdf-app
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в # Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный # nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный
# лимит — свойство wordpdf.max-bytes (env WORDPDF_MAX_BYTES), по умолчанию # лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ), по умолчанию
# WordPdfSettings.MAX_INPUT_BYTES = 5 MiB; здесь только потолок загрузки. # WordPdfSettings.MAX_INPUT_MB = 5; здесь только потолок загрузки.
# Лимиты входа: env WORDPDF_MAX_BYTES (байты) / WORDPDF_MAX_PAGES (страницы), # Лимиты входа: env WORDPDF_MAX_MB (МБ) / WORDPDF_MAX_PAGES (страницы),
# дефолты — константы ядра (5 MiB / 100), задаются ConvertController. # дефолты — константы ядра (5 / 100), задаются ConvertController.
# Значение <= 0 — падение на старте. Сами ключи здесь не объявлены: # Значение <= 0 — падение на старте. Сами ключи здесь не объявлены:
# пустое значение затенит SpEL-дефолт @Value. # пустое значение затенит SpEL-дефолт @Value.
# file-size-threshold=100MB держит файл в памяти (ядро и так читает всё в RAM). # file-size-threshold=100MB держит файл в памяти (ядро и так читает всё в RAM).
@@ -113,6 +113,7 @@ class ConvertControllerTest {
.andExpect(content().contentType(MediaType.APPLICATION_PDF)) .andExpect(content().contentType(MediaType.APPLICATION_PDF))
.andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION, .andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION,
org.hamcrest.Matchers.containsString("filename*=UTF-8''ru-plain.pdf"))) org.hamcrest.Matchers.containsString("filename*=UTF-8''ru-plain.pdf")))
.andExpect(header().doesNotExist("X-Wordpdf-Degraded"))
.andReturn(); .andReturn();
byte[] pdf = result.getResponse().getContentAsByteArray(); byte[] pdf = result.getResponse().getContentAsByteArray();
assertTrue("%PDF".equals(new String(pdf, 0, 4, StandardCharsets.US_ASCII)), assertTrue("%PDF".equals(new String(pdf, 0, 4, StandardCharsets.US_ASCII)),
@@ -264,14 +265,14 @@ class ConvertControllerTest {
/** /**
* Регрессия env-only: лимиты входа параметрами запроса не задаются. * Регрессия env-only: лимиты входа параметрами запроса не задаются.
* maxBytes/maxPages в multipart-форме игнорируются — маленький * maxMb/maxPages в multipart-форме игнорируются — маленький
* документ проходит на серверных лимитах (дефолты ядра). * документ проходит на серверных лимитах (дефолты ядра).
*/ */
@Test @Test
void requestLimitParams_areIgnored() throws Exception { void requestLimitParams_areIgnored() throws Exception {
mockMvc.perform(multipart("/api/v1/convert") mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx"))) .file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxBytes", "1000") .param("maxMb", "1000")
.param("maxPages", "1")) .param("maxPages", "1"))
.andExpect(status().isOk()) .andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF)); .andExpect(content().contentType(MediaType.APPLICATION_PDF));
@@ -326,14 +327,40 @@ class ConvertControllerTest {
@Test @Test
void corruptNotAZip_rejected() throws Exception { void corruptNotAZip_rejected() throws Exception {
// без zip-подписи ZipInputStream молча даёт 0 записей — отсекает // без подписи контейнера (zip для .docx, OLE2 для .doc) лёгкий
// отдельная проверка magic bytes // счётчик страниц молчит — отсекает отдельная проверка magic bytes
mockMvc.perform(multipart("/api/v1/convert") mockMvc.perform(multipart("/api/v1/convert")
.file(docx("broken.docx", "это просто текст, не архив" .file(docx("broken.docx", "это просто текст, не архив"
.getBytes(StandardCharsets.UTF_8)))) .getBytes(StandardCharsets.UTF_8))))
.andExpect(status().isBadRequest()) .andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error", .andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("не zip-архив"))); org.hamcrest.Matchers.containsString("не похоже на .docx или .doc")));
}
/**
* Бинарный .doc проходит тот же эндпоинт: расширение принято, ядро
* выбирает POI-ветку по OLE2-магику, ответ несёт заголовок деградации
* X-Wordpdf-Degraded (контракт AGENTS.md); у .docx его нет.
* Регрессия — ConvertController (расширения + заголовок) +
* ConversionService#validate (магик), фикстура /samples/legacy-doc.doc
* (test-jar core).
*/
@Test
void legacyDoc_convertsToPdf() throws Exception {
MvcResult result = mockMvc.perform(multipart("/api/v1/convert")
.file(docx("testDoc.doc", bytes("/samples/legacy-doc.doc"))))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF))
.andExpect(header().string(HttpHeaders.CONTENT_DISPOSITION,
org.hamcrest.Matchers.containsString("filename*=UTF-8''testDoc.pdf")))
.andExpect(header().string("X-Wordpdf-Degraded",
"headers-footers-exotic-glyphs"))
.andReturn();
byte[] pdf = result.getResponse().getContentAsByteArray();
assertTrue("%PDF".equals(new String(pdf, 0, 4, StandardCharsets.US_ASCII)),
"тело не начинается с %PDF");
String text = norm(pdfText(pdf));
assertTrue(text.contains("Нижний колонтитул"), "нет колонтитула: " + text);
} }
@Test @Test
@@ -22,20 +22,20 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
/** /**
* Лимиты входа из конфигурации сервера (свойства {@code wordpdf.max-bytes}/ * Лимиты входа из конфигурации сервера (свойства {@code wordpdf.max-mb}/
* {@code wordpdf.max-pages}) применяются сквозь HTTP: отдельный контекст с * {@code wordpdf.max-pages}) применяются сквозь HTTP: отдельный контекст с
* {@code @TestPropertySource} доказывает, что {@code ConvertController} * {@code @TestPropertySource} доказывает, что {@code ConvertController}
* читает их из окружения Spring, а не живёт на константах ядра. * читает их из окружения Spring, а не живёт на константах ядра.
* Отдельный класс, а не {@code @Nested}: {@code @Nested} + * Отдельный класс, а не {@code @Nested}: {@code @Nested} +
* {@code @TestPropertySource} не даёт отдельного контекста. * {@code @TestPropertySource} не даёт отдельного контекста.
* *
* <p>Пара свойств согласована с фикстурами: {@code max-bytes=20000} выше * <p>Пара свойств согласована с фикстурами: {@code max-mb=1} (1 MiB) выше
* обеих (2612 и 2887 байт), так что page-отсечка на {@code max-pages=1} * обеих (2612 и 2887 байт), так что page-отсечка на {@code max-pages=1}
* достижима; для byte-отсечки берётся файл заведомо больше 20000.</p> * достижима; для byte-отсечки берётся файл заведомо больше 1 MiB.</p>
*/ */
@SpringBootTest @SpringBootTest
@AutoConfigureMockMvc @AutoConfigureMockMvc
@TestPropertySource(properties = {"wordpdf.max-bytes=20000", "wordpdf.max-pages=1"}) @TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1"})
class ConvertLimitsTest { class ConvertLimitsTest {
private static final MediaType DOCX = private static final MediaType DOCX =
@@ -55,9 +55,9 @@ class ConvertLimitsTest {
return new MockMultipartFile("file", filename, DOCX.toString(), content); return new MockMultipartFile("file", filename, DOCX.toString(), content);
} }
/** Zip с ~40 КБ псевдослучайных байтов: больше лимита 20000, не жмётся. */ /** Zip с ~1.5 МБ псевдослучайных байтов: больше лимита 1 MiB, не жмётся. */
private static byte[] oversizedZip() throws IOException { private static byte[] oversizedZip() throws IOException {
byte[] payload = new byte[40_000]; byte[] payload = new byte[1_500_000];
new Random(1).nextBytes(payload); new Random(1).nextBytes(payload);
ByteArrayOutputStream bos = new ByteArrayOutputStream(); ByteArrayOutputStream bos = new ByteArrayOutputStream();
try (ZipOutputStream zout = new ZipOutputStream(bos)) { try (ZipOutputStream zout = new ZipOutputStream(bos)) {
@@ -68,14 +68,14 @@ class ConvertLimitsTest {
return bos.toByteArray(); return bos.toByteArray();
} }
/** Свойство wordpdf.max-bytes отсекает файл до любой другой проверки. */ /** Свойство wordpdf.max-mb отсекает файл до любой другой проверки. */
@Test @Test
void configuredMaxBytes_applies() throws Exception { void configuredMaxMb_applies() throws Exception {
mockMvc.perform(multipart("/api/v1/convert") mockMvc.perform(multipart("/api/v1/convert")
.file(docx("big.docx", oversizedZip()))) .file(docx("big.docx", oversizedZip())))
.andExpect(status().isBadRequest()) .andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error", .andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("20000 байт"))); org.hamcrest.Matchers.containsString("1048576 байт")));
} }
/** /**
+7
View File
@@ -37,6 +37,13 @@
<artifactId>slf4j-simple</artifactId> <artifactId>slf4j-simple</artifactId>
</dependency> </dependency>
<!-- Apache POI HWPF: чтение бинарных .doc (Word 97-2003) и экспорт
HWPF->XSL-FO (WordToFoConverter) для ветки .doc. -->
<dependency>
<groupId>org.apache.poi</groupId>
<artifactId>poi-scratchpad</artifactId>
</dependency>
<!-- ============ Тесты ============ --> <!-- ============ Тесты ============ -->
<dependency> <dependency>
<groupId>org.junit.jupiter</groupId> <groupId>org.junit.jupiter</groupId>
@@ -15,19 +15,19 @@ package ru.pjandro.wordpdf;
* @param errorOnSmartArt бросать {@link DrawingFoundException} при находке * @param errorOnSmartArt бросать {@link DrawingFoundException} при находке
* SmartArt, **только если** {@code renderSmartArt} * SmartArt, **только если** {@code renderSmartArt}
* выключен (рендер приоритетнее error-флага) * выключен (рендер приоритетнее error-флага)
* @param maxBytes лимит размера входных байтов на этот вызов; * @param maxMb лимит размера входа в МБ (MiB) на этот вызов;
* дефолт — {@link WordPdfSettings#MAX_INPUT_BYTES} * дефолт — {@link WordPdfSettings#MAX_INPUT_MB}
* @param maxPages лимит числа страниц на этот вызов; * @param maxPages лимит числа страниц на этот вызов;
* дефолт — {@link WordPdfSettings#MAX_PAGES} * дефолт — {@link WordPdfSettings#MAX_PAGES}
*/ */
public record ConvertOptions(boolean renderCharts, boolean renderSmartArt, public record ConvertOptions(boolean renderCharts, boolean renderSmartArt,
boolean errorOnCharts, boolean errorOnSmartArt, boolean errorOnCharts, boolean errorOnSmartArt,
long maxBytes, int maxPages) { long maxMb, int maxPages) {
/** Дефолты ядра из {@link WordPdfSettings}. */ /** Дефолты ядра из {@link WordPdfSettings}. */
public static ConvertOptions defaults() { public static ConvertOptions defaults() {
return new ConvertOptions(WordPdfSettings.RENDER_CHARTS, WordPdfSettings.RENDER_SMARTART, return new ConvertOptions(WordPdfSettings.RENDER_CHARTS, WordPdfSettings.RENDER_SMARTART,
WordPdfSettings.ERROR_ON_CHARTS, WordPdfSettings.ERROR_ON_SMARTART, WordPdfSettings.ERROR_ON_CHARTS, WordPdfSettings.ERROR_ON_SMARTART,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES);
} }
} }
@@ -16,6 +16,7 @@ import ru.pjandro.wordpdf.internal.FieldNormalizer;
import ru.pjandro.wordpdf.internal.GlyphCoverageNormalizer; import ru.pjandro.wordpdf.internal.GlyphCoverageNormalizer;
import ru.pjandro.wordpdf.internal.FopFallbackFonts; import ru.pjandro.wordpdf.internal.FopFallbackFonts;
import ru.pjandro.wordpdf.internal.StrictOoxmlNormalizer; import ru.pjandro.wordpdf.internal.StrictOoxmlNormalizer;
import ru.pjandro.wordpdf.internal.DocToPdfRenderer;
import ru.pjandro.wordpdf.internal.SymbolFontNormalizer; import ru.pjandro.wordpdf.internal.SymbolFontNormalizer;
import java.io.ByteArrayInputStream; import java.io.ByteArrayInputStream;
@@ -54,11 +55,12 @@ public final class WordPdfConverter {
} }
/** /**
* Конвертирует байты .docx в PDF. Работа с файлами — забота вызывающего * Конвертирует байты .docx (или бинарного .doc Word 97-2003 — ветка
* (файловое API было здесь раньше; ядро пути не принимает). * выбирается по магическому байту контейнера) в PDF. Работа с файлами — забота
* вызывающего (файловое API было здесь раньше; ядро пути не принимает).
* *
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера: * <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера:
* {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_BYTES} / zip-подпись / * {@code null} / размер больше {@link WordPdfSettings#MAX_INPUT_MB} (МБ) / zip-подпись /
* число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет; * число страниц больше {@link WordPdfSettings#MAX_PAGES} — при отказе байтов результата нет;
* страницы дополнительно перепроверяются по нормализованным байтам (шаг 2.5). * страницы дополнительно перепроверяются по нормализованным байтам (шаг 2.5).
* *
@@ -66,7 +68,7 @@ public final class WordPdfConverter {
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся * @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @return байты готового PDF * @return байты готового PDF
* @throws ValidationException некорректный вход: {@code null}, размер больше * @throws ValidationException некорректный вход: {@code null}, размер больше
* {@link WordPdfSettings#MAX_INPUT_BYTES}, не zip-архив, документ длиннее * {@link WordPdfSettings#MAX_INPUT_MB} (МБ), не zip-архив, документ длиннее
* {@link WordPdfSettings#MAX_PAGES} страниц * {@link WordPdfSettings#MAX_PAGES} страниц
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/ */
@@ -79,7 +81,7 @@ public final class WordPdfConverter {
* диаграмм/SmartArt и лимиты входа. * диаграмм/SmartArt и лимиты входа.
* *
* <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера: * <p>Вход проверяется {@link WordPdfValidator#validate(byte[], ConvertOptions)} до рендера:
* {@code null} / размер больше {@code options.maxBytes()} / zip-подпись / число страниц * {@code null} / размер больше {@code options.maxMb()} (МБ) / zip-подпись / число страниц
* больше {@code options.maxPages()} — при отказе байтов результата нет; страницы * больше {@code options.maxPages()} — при отказе байтов результата нет; страницы
* дополнительно перепроверяются по нормализованным байтам (шаг 2.5). * дополнительно перепроверяются по нормализованным байтам (шаг 2.5).
* *
@@ -89,7 +91,7 @@ public final class WordPdfConverter {
* дефолты (константы {@link WordPdfSettings}) * дефолты (константы {@link WordPdfSettings})
* @return байты готового PDF * @return байты готового PDF
* @throws ValidationException некорректный вход: {@code null}, размер больше * @throws ValidationException некорректный вход: {@code null}, размер больше
* {@code options.maxBytes()}, не zip-архив, документ длиннее * {@code options.maxMb()} (МБ), не zip-архив, документ длиннее
* {@code options.maxPages()} страниц * {@code options.maxPages()} страниц
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера) * @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/ */
@@ -114,6 +116,16 @@ public final class WordPdfConverter {
*/ */
private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options, private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options,
OutputStream os) throws Exception { OutputStream os) throws Exception {
// 0. Бинарный .doc (Word 97-2003, OLE2-контейнер) — отдельная
// ветка: docx4j его не читает, нормализаторы (все — по zip-частям
// docx) тут бессмысленны. Флаги renderCharts/renderSmartArt/
// errorOn* для .doc — no-op: диаграмм как c:chart в .doc нет,
// превью встраиваемых объектов приходят картинками через
// PicturesManager (см. internal/DocToPdfRenderer).
if (isOle2(rawDocxBytes)) {
DocToPdfRenderer.render(rawDocxBytes, title, options, os);
return;
}
// 1. Маппер шрифтов. Порядок важен: конструктор запускает // 1. Маппер шрифтов. Порядок важен: конструктор запускает
// обнаружение системных шрифтов, затем бандл-шрифты из jar // обнаружение системных шрифтов, затем бандл-шрифты из jar
// регистрируются поверх них (имеют приоритет). // регистрируются поверх них (имеют приоритет).
@@ -188,4 +200,13 @@ public final class WordPdfConverter {
// пакет загружается в память и ничего не закрывает. // пакет загружается в память и ничего не закрывает.
} }
} }
/** Магик OLE2 (CFB): {@code D0 CF 11 E0 A1 B1 1A E1} — контейнер .doc. */
private static boolean isOle2(byte[] bytes) {
return bytes != null && bytes.length >= 8
&& (bytes[0] & 0xFF) == 0xD0 && (bytes[1] & 0xFF) == 0xCF
&& (bytes[2] & 0xFF) == 0x11 && (bytes[3] & 0xFF) == 0xE0
&& (bytes[4] & 0xFF) == 0xA1 && (bytes[5] & 0xFF) == 0xB1
&& (bytes[6] & 0xFF) == 0x1A && (bytes[7] & 0xFF) == 0xE1;
}
} }
@@ -3,14 +3,14 @@ package ru.pjandro.wordpdf;
/** /**
* Единая точка конфигурации ядра: все настройки-дефолты — константы здесь. * Единая точка конфигурации ядра: все настройки-дефолты — константы здесь.
* Рантайм-конфигурации нет: изменение значения = правка этого файла и пересборка. * Рантайм-конфигурации нет: изменение значения = правка этого файла и пересборка.
* Лимиты входа ({@link #MAX_INPUT_BYTES}, {@link #MAX_PAGES}) — дефолты: * Лимиты входа ({@link #MAX_INPUT_MB}, {@link #MAX_PAGES}) — дефолты:
* вызывающий может переопределить их на конкретный вызов через * вызывающий может переопределить их на конкретный вызов через
* {@link ConvertOptions}. * {@link ConvertOptions}.
*/ */
public final class WordPdfSettings { public final class WordPdfSettings {
/** Максимальный размер входного .docx (дефолт). 5 MiB = 5 × 1024 × 1024. */ /** Максимальный размер входного .docx в МБ (дефолт). МБ = MiB = 1024 × 1024 байт. */
public static final long MAX_INPUT_BYTES = 5L * 1024 * 1024; public static final long MAX_INPUT_MB = 5;
/** Документ длиннее — ошибка (дефолт). */ /** Документ длиннее — ошибка (дефолт). */
public static final int MAX_PAGES = 100; public static final int MAX_PAGES = 100;
@@ -1,5 +1,7 @@
package ru.pjandro.wordpdf; package ru.pjandro.wordpdf;
import org.apache.poi.hwpf.HWPFDocument;
import org.apache.poi.poifs.filesystem.POIFSFileSystem;
import javax.xml.stream.XMLInputFactory; import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamException; import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader; import javax.xml.stream.XMLStreamReader;
@@ -26,7 +28,7 @@ import java.util.zip.ZipInputStream;
* *
* <p>Лимиты по умолчанию: * <p>Лимиты по умолчанию:
* <ul> * <ul>
* <li>{@link WordPdfSettings#MAX_INPUT_BYTES} — максимальный размер входного .docx;</li> * <li>{@link WordPdfSettings#MAX_INPUT_MB} — максимальный размер входного .docx (МБ);</li>
* <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц.</li> * <li>{@link WordPdfSettings#MAX_PAGES} — максимально допустимое число страниц.</li>
* </ul> * </ul>
* Оба переопределяются на вызов: перегрузками с явным лимитом или * Оба переопределяются на вызов: перегрузками с явным лимитом или
@@ -54,29 +56,26 @@ public final class WordPdfValidator {
/** /**
* Проверяет размер байтов входа (для документа, полученного из сети/БД). * Проверяет размер байтов входа (для документа, полученного из сети/БД).
* *
* @throws ValidationException при {@code null} или превышении лимита * @throws ValidationException при {@code null} или превышении лимита (МБ)
*/ */
public static void checkInput(byte[] docxBytes) throws ValidationException { public static void checkInput(byte[] docxBytes) throws ValidationException {
checkInput(docxBytes, WordPdfSettings.MAX_INPUT_BYTES); checkInput(docxBytes, WordPdfSettings.MAX_INPUT_MB);
} }
/** /**
* Проверяет размер байтов входа против явного лимита (переопределение * Проверяет размер байтов входа против явного лимита в МБ (переопределение
* на вызов, см. {@link ConvertOptions#maxBytes()}). * на вызов, см. {@link ConvertOptions#maxMb()}). МБ = MiB = 1024 × 1024 байт.
* *
* @throws ValidationException при {@code null} или превышении {@code maxBytes} * @throws ValidationException при {@code null} или превышении {@code maxMb} (МБ)
*/ */
public static void checkInput(byte[] docxBytes, long maxBytes) throws ValidationException { public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException {
if (docxBytes == null) { if (docxBytes == null) {
throw new ValidationException("Не указаны байты входного файла"); throw new ValidationException("Не указаны байты входного файла");
} }
long maxBytes = maxMb * 1024 * 1024;
if (docxBytes.length > maxBytes) { if (docxBytes.length > maxBytes) {
// дефолтный лимит кратен MiB — сообщение остаётся «... 5 МБ ...» throw new ValidationException("Файл больше " + maxMb + " МБ: "
String limit = maxBytes % (1024 * 1024) == 0 + docxBytes.length + " байт > " + maxBytes + " байт");
? (maxBytes / (1024 * 1024)) + " МБ"
: maxBytes + " байт";
throw new ValidationException("Файл больше " + limit
+ ": " + docxBytes.length + " байт > " + maxBytes + " байт");
} }
} }
@@ -152,28 +151,85 @@ public final class WordPdfValidator {
} }
/** /**
* Полная проверка входа: размер → zip-подпись → число страниц. Порядок * Полная проверка входа: размер → подпись контейнера (zip или OLE2) →
* значим: размер — дешёвая, разбор zip без подписи бессмысленен. Лимиты * число страниц. Порядок значим: размер — дешёвая, разбор контейнера без
* берутся из {@link ConvertOptions} (переопределение на вызов, см. * подписи бессмысленен. Лимиты берутся из {@link ConvertOptions}
* {@link ConvertOptions#maxBytes()}, {@link ConvertOptions#maxPages()}). * (переопределение на вызов, см. {@link ConvertOptions#maxMb()},
* {@link ConvertOptions#maxPages()}).
* *
* <p>Проверка zip-подписи отдельным шагом обязательна: * <p>Проверка подписи отдельным шагом обязательна:
* {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает * {@code ZipInputStream.getNextEntry()} на не-zip-потоке возвращает
* {@code null} молча, и {@link #checkPageCount(byte[], int)} такой вход * {@code null} молча, и {@link #checkPageCount(byte[], int)} такой вход
* не отверг бы (оценка «1 страница»). Регрессия — * не отверг бы (оценка «1 страница»). Бинарный .doc — не zip, а OLE2
* {@code WordPdfValidatorTest#validate_notAZip} (на HTTP-границе — * (CFB): для него свой магик и свой счётчик страниц
* ({@link #checkDocPageCountLightweight(byte[], int)}). Регрессия —
* {@code WordPdfValidatorTest#validate_neitherDocxNorDoc} (на HTTP-границе —
* {@code ConvertControllerTest#corruptNotAZip_rejected}).</p> * {@code ConvertControllerTest#corruptNotAZip_rejected}).</p>
* *
* @throws ValidationException при {@code null}, превышении {@code options.maxBytes()}, * @throws ValidationException при {@code null}, превышении {@code options.maxMb()},
* отсутствии zip-подписи, ошибке разбора zip или превышении {@code options.maxPages()} * отсутствии подписи контейнера (ни zip, ни OLE2), ошибке разбора
* контейнера или превышении {@code options.maxPages()}
*/ */
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException { public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException {
checkInput(docxBytes, options.maxBytes()); checkInput(docxBytes, options.maxMb());
if (docxBytes.length < 4 || docxBytes[0] != 'P' || docxBytes[1] != 'K' boolean zip = docxBytes.length >= 4 && docxBytes[0] == 'P' && docxBytes[1] == 'K'
|| (docxBytes[2] & 0xFF) != 0x03 || (docxBytes[3] & 0xFF) != 0x04) { && (docxBytes[2] & 0xFF) == 0x03 && (docxBytes[3] & 0xFF) == 0x04;
throw new ValidationException("Содержимое не похоже на .docx (не zip-архив)"); boolean ole2 = docxBytes.length >= 8
&& (docxBytes[0] & 0xFF) == 0xD0 && (docxBytes[1] & 0xFF) == 0xCF
&& (docxBytes[2] & 0xFF) == 0x11 && (docxBytes[3] & 0xFF) == 0xE0
&& (docxBytes[4] & 0xFF) == 0xA1 && (docxBytes[5] & 0xFF) == 0xB1
&& (docxBytes[6] & 0xFF) == 0x1A && (docxBytes[7] & 0xFF) == 0xE1;
if (!zip && !ole2) {
throw new ValidationException("Содержимое не похоже на .docx или .doc (ни zip, ни OLE2)");
}
try {
if (zip) {
checkPageCount(docxBytes, options.maxPages());
} else {
checkDocPageCountLightweight(docxBytes, options.maxPages());
}
} catch (ConversionException e) {
// сломанный OLE2-контейнер — некорректный вход (400), как не-zip в zip-ветке
throw new ValidationException(e.getMessage(), e);
}
}
/**
* Проверяет число страниц бинарного .doc (Word 97-2003) по кэшу
* {@code SummaryInformation.PageCount} — аналогу {@code docProps/app.xml}
* в docx-пути: Word переписывает его при сохранении, пост-рендерной
* проверки нет осознанно (как в docx-ветке — доверяем кэшу до рендера).
* Кэш пуст или ноль — проверка пропускается (посчитать дёшево нельзя,
* отвергать валидный документ по отсутствию кэша неправильно).
*
* @throws ConversionException при {@code null}, ошибке разбора OLE2 или превышении {@link WordPdfSettings#MAX_PAGES}
*/
public static void checkDocPageCountLightweight(byte[] docBytes) throws ConversionException {
checkDocPageCountLightweight(docBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkDocPageCountLightweight(byte[])}, с явным
* лимитом страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
*
* @throws ConversionException при {@code null}, ошибке разбора OLE2 или превышении {@code maxPages}
*/
public static void checkDocPageCountLightweight(byte[] docBytes, int maxPages) throws ConversionException {
if (docBytes == null) {
throw new ConversionException("Не указаны байты входного .doc");
}
int pages;
try (POIFSFileSystem fs = new POIFSFileSystem(new ByteArrayInputStream(docBytes));
HWPFDocument hwpf = new HWPFDocument(fs)) {
org.apache.poi.hpsf.SummaryInformation si = hwpf.getSummaryInformation();
pages = si == null ? 0 : si.getPageCount();
} catch (IOException | RuntimeException e) {
throw new ConversionException("Не удалось разобрать байты .doc", e);
}
if (pages > maxPages) {
throw new ConversionException("Документ длиннее " + maxPages
+ " страниц: получено не менее " + pages);
} }
checkPageCount(docxBytes, options.maxPages());
} }
/** Поставщик потока по имени части zip; null — части нет. */ /** Поставщик потока по имени части zip; null — части нет. */
@@ -0,0 +1,764 @@
package ru.pjandro.wordpdf.internal;
import org.apache.fop.apps.FOUserAgent;
import org.apache.fop.apps.Fop;
import org.apache.fop.apps.FopFactory;
import org.apache.fop.apps.MimeConstants;
import org.apache.poi.hwpf.HWPFDocument;
import org.apache.poi.hwpf.converter.FontReplacer;
import org.apache.poi.hwpf.converter.PicturesManager;
import org.apache.poi.hwpf.converter.WordToFoConverter;
import org.apache.poi.hwpf.usermodel.CharacterRun;
import org.apache.poi.hwpf.usermodel.HeaderStories;
import org.apache.poi.hwpf.usermodel.Paragraph;
import org.apache.poi.hwpf.usermodel.PictureType;
import org.apache.poi.hwpf.usermodel.Range;
import org.apache.poi.poifs.filesystem.POIFSFileSystem;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
import ru.pjandro.wordpdf.ConversionException;
import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
import ru.pjandro.wordpdf.fonts.BundledFonts;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.sax.SAXResult;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;
import java.util.stream.Stream;
/**
* Рендер бинарного .doc (Word 97-2003, OLE2) в PDF: POI HWPF -> XSL-FO ->
* Apache FOP (тот же форк, что в docx-ветке).
*
* <p>docx4j бинарный формат не читает, HWPF->XWPF конвертера в POI нет —
* поэтому для .doc отдельная ветка: {@link WordToFoConverter} строит FO
* из HWPF-модели напрямую, а колонтитулы (которые POI в FO не пишет)
* дописываются в FO-DOM по {@link HeaderStories}.
*
* <p>Известная деградация против Word (принята): дрейф вёрстки (FO POI
* беднее docx4j-экспорта), шрифты — бандл-аналоги, колонтитулы — по
* одной (odd) истории на секцию, first/even-варианты — эвристикой
* «непустая история => вариант» (флаги titlePg/evenAndOdd POI не отдаёт).
* Флаги {@code renderCharts}/{@code renderSmartArt} для .doc — no-op:
* диаграмм как {@code c:chart} в .doc нет, превью встраиваемых объектов
* приходят картинками через {@link PicturesManager}.
*/
public final class DocToPdfRenderer {
private DocToPdfRenderer() {
}
private static final String FO_NS = "http://www.w3.org/1999/XSL/Format";
/** Маркеры полей Word в тексте HWPF-ранов. */
private static final char FIELD_BEGIN = '\u0013';
private static final char FIELD_SEPARATOR = '\u0014';
private static final char FIELD_END = '\u0015';
/** Маркер конца секции в историях колонтитулов. */
private static final char SECTION_END = '\u000c';
/** Конец абзаца / конец ячейки таблицы в тексте HWPF. */
private static final char PARA_END = '\r';
private static final char CELL_END = '\u0007';
/** Зазор между текстом колонтитула и областью контента. */
private static final double REGION_GAP_IN = 0.15;
/**
* Полный путь .doc -> PDF в поток. Все ошибки — {@link ConversionException}.
*
* @param docBytes байты OLE2 (.doc)
* @param title заголовок PDF (метаданные); {@code null}/пустая — не задаётся
* @param options настройки вызова (для .doc флаги рисования — no-op)
* @param out приёмник байтов PDF
*/
public static void render(byte[] docBytes, String title, ConvertOptions options,
OutputStream out) throws ConversionException {
Path workDir = null;
try {
// init() идемпотентен; restrictToBundled() не нужен — FOP-конфиг
// строится явно (auto-detect="false"), системные шрифты в него не попадают.
BundledFonts.init();
workDir = Files.createTempDirectory("wordpdf-doc-");
Path picsDir = Files.createDirectory(workDir.resolve("pics"));
Document foDoc;
try (POIFSFileSystem fs = new POIFSFileSystem(new ByteArrayInputStream(docBytes));
HWPFDocument hwpf = new HWPFDocument(fs)) {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
Document dom = dbf.newDocumentBuilder().newDocument();
WordToFoConverter converter = new WordToFoConverter(dom);
converter.setFontReplacer(DocToPdfRenderer::replaceFont);
converter.setPicturesManager(new TempPictures(picsDir));
converter.processDocument(hwpf);
foDoc = converter.getDocument();
applyDefaultFont(foDoc);
injectHeadersAndFooters(foDoc, hwpf);
}
renderFo(foDoc, title, workDir, out);
} catch (ConversionException e) {
throw e;
} catch (Exception e) {
throw new ConversionException("Не удалось конвертировать документ .doc", e);
} finally {
if (workDir != null) {
deleteRecursively(workDir);
}
}
}
// ==================== Шрифты ====================
/**
* Замена шрифта ранa на бандл-аналог: имя из name-таблицы TTF
* regular-варианта (тот же механизм triplet-имён, что в
* {@link FopFallbackFonts}) — FO запрашивает именно его.
*/
private static FontReplacer.Triplet replaceFont(FontReplacer.Triplet t) {
String family = BundledFontMapper.bundledFamily(
t.fontName == null ? "" : t.fontName);
var regular = BundledFonts.regular(family);
if (regular != null) {
t.fontName = regular.getName();
}
return t;
}
/** Картинки во временный каталог; FO ссылается на них file:-URI. */
private static final class TempPictures implements PicturesManager {
private final Path dir;
TempPictures(Path dir) {
this.dir = dir;
}
@Override
public String savePicture(byte[] content, PictureType pictureType,
String suggestedName, float widthInches, float heightInches) {
try {
if (content == null || content.length == 0) {
// пустой объект (напр. превью удалённого рисунка) — FOP
// падает на нём с EOFException, ссылка не нужна
return null;
}
String name = suggestedName == null ? "" :
suggestedName.replaceAll("[^A-Za-z0-9._-]", "_");
if (name.isEmpty()) {
String ext = pictureType == null
? PictureType.UNKNOWN.getExtension()
: pictureType.getExtension();
name = "pic-" + java.util.Arrays.hashCode(content) + "." + ext;
}
Path file = dir.resolve(name);
Files.write(file, content);
return file.toUri().toString();
} catch (IOException e) {
// деградация вместо падения: картинка без ссылки просто исчезнет
return null;
}
}
}
// ==================== Колонтитулы ====================
/**
* POI не пишет колонтитулы в FO. Достаём их из {@link HeaderStories},
* разбиваем на чанки по секциям (маркер конца секции {@code \u000c}) и
* вставляем в FO-DOM: {@code fo:region-before}/{@code fo:region-after}
* в мастер + {@code fo:static-content} в page-sequence.
*/
private static void injectHeadersAndFooters(Document foDoc, HWPFDocument hwpf) {
NodeList sequences = foDoc.getElementsByTagNameNS(FO_NS, "page-sequence");
if (sequences.getLength() == 0) {
return;
}
HeaderStories hs = new HeaderStories(hwpf);
// Императивный список: javac 21 не выводит T для List.of/Arrays.asList
// из вложенных дженерик-аргументов (varargs inference).
List<List<List<Paragraph>>> stories = new ArrayList<>();
stories.add(chunkBySection(hs.getOddHeaderSubrange(), sequences.getLength()));
stories.add(chunkBySection(hs.getEvenHeaderSubrange(), sequences.getLength()));
stories.add(chunkBySection(hs.getFirstHeaderSubrange(), sequences.getLength()));
stories.add(chunkBySection(hs.getOddFooterSubrange(), sequences.getLength()));
stories.add(chunkBySection(hs.getEvenFooterSubrange(), sequences.getLength()));
stories.add(chunkBySection(hs.getFirstFooterSubrange(), sequences.getLength()));
// NUMPAGES/SECTIONPAGES -> citation-last по ПОСЛЕДНЕМУ мастеру
// документа: нумерация FOP между page-sequence непрерывна.
String lastMaster = ((Element) sequences.item(sequences.getLength() - 1))
.getAttribute("master-reference");
for (int i = 0; i < sequences.getLength(); i++) {
Element seq = (Element) sequences.item(i);
String masterName = seq.getAttribute("master-reference");
Element master = findMaster(foDoc, masterName);
if (master == null) {
continue;
}
String[] margins = parseMarginShorthand(master);
if (margins == null) {
continue;
}
// Форк FOP (docx4j-fo-renderer) вырезал PageMaster.setupRegions:
// viewport region-body = page-area минус СОБСТВЕННЫЕ margin'ы
// body, extent'ы region-before/after body не вычитаются. Поэтому
// margin'ы region-body (шортхэнд POI = Word-поля) сохраняются —
// единственная защита от наезда текста на колонтитулы; extent'ы
// регионов только размещают сами колонтитулы.
// Порядок детей simple-page-master: body -> before -> after
// (требование валидации форка).
if (hasText(stories.get(0).get(i))) {
appendRegion(master, "region-before", margins[0], "after");
insertStaticContent(seq, "xsl-region-before",
blocks(foDoc, stories.get(0).get(i), lastMaster), "margin-bottom");
}
if (hasText(stories.get(3).get(i))) {
appendRegion(master, "region-after", margins[2], "before");
insertStaticContent(seq, "xsl-region-after",
blocks(foDoc, stories.get(3).get(i), lastMaster), "margin-top");
}
// first/even — эвристика: непустая история => вариант существует.
boolean hasFirst = hasText(stories.get(2).get(i)) || hasText(stories.get(5).get(i));
boolean hasEven = hasText(stories.get(1).get(i)) || hasText(stories.get(4).get(i));
if (!hasFirst && !hasEven) {
continue;
}
List<Element> variants = new ArrayList<>();
if (hasFirst) {
Element clone = (Element) master.cloneNode(true);
String name = masterName + "-first";
clone.setAttribute("master-name", name);
renameRegionFlows(clone, "-first");
foDoc.getDocumentElement().insertBefore(clone, master.getNextSibling());
if (hasText(stories.get(2).get(i))) {
insertStaticContent(seq, "xsl-region-before-first",
blocks(foDoc, stories.get(2).get(i), lastMaster), "margin-bottom");
}
if (hasText(stories.get(5).get(i))) {
insertStaticContent(seq, "xsl-region-after-first",
blocks(foDoc, stories.get(5).get(i), lastMaster), "margin-top");
}
variants.add(clone);
}
if (hasEven) {
Element clone = (Element) master.cloneNode(true);
String name = masterName + "-even";
clone.setAttribute("master-name", name);
renameRegionFlows(clone, "-even");
foDoc.getDocumentElement().insertBefore(clone, master.getNextSibling());
if (hasText(stories.get(1).get(i))) {
insertStaticContent(seq, "xsl-region-before-even",
blocks(foDoc, stories.get(1).get(i), lastMaster), "margin-bottom");
}
if (hasText(stories.get(4).get(i))) {
insertStaticContent(seq, "xsl-region-after-even",
blocks(foDoc, stories.get(4).get(i), lastMaster), "margin-top");
}
variants.add(clone);
}
wrapInPageSequenceMaster(foDoc, master, variants);
}
}
/**
* История колонтитулов — конкатенация одноимённых историй всех секций;
* конец секции помечен {@code \u000c} в последнем параграфе. Чанков не
* столько, сколько секций — деградация: один чанк раздаётся всем.
*/
private static List<List<Paragraph>> chunkBySection(Range story, int sectionCount) {
List<List<Paragraph>> chunks = new ArrayList<>();
if (story != null && story.numParagraphs() > 0) {
List<Paragraph> current = new ArrayList<>();
for (int i = 0; i < story.numParagraphs(); i++) {
Paragraph p;
String text;
try {
p = story.getParagraph(i);
text = p.text();
} catch (RuntimeException e) {
continue;
}
current.add(p);
if (text != null && text.indexOf(SECTION_END) >= 0) {
chunks.add(current);
current = new ArrayList<>();
}
}
if (!current.isEmpty()) {
chunks.add(current);
}
}
if (chunks.isEmpty()) {
for (int i = 0; i < sectionCount; i++) {
chunks.add(null);
}
} else if (chunks.size() != sectionCount) {
List<Paragraph> first = chunks.get(0);
chunks = new ArrayList<>();
for (int i = 0; i < sectionCount; i++) {
chunks.add(first);
}
}
return chunks;
}
private static Element findMaster(Document foDoc, String masterName) {
NodeList masters = foDoc.getElementsByTagNameNS(FO_NS, "simple-page-master");
for (int i = 0; i < masters.getLength(); i++) {
Element m = (Element) masters.item(i);
if (masterName.equals(m.getAttribute("master-name"))) {
return m;
}
}
return null;
}
/** {@code margin="T R B L"} region-body мастера (шортхэнд POI). */
private static String[] parseMarginShorthand(Element master) {
Element body = child(master, "region-body");
if (body == null) {
return null;
}
String margin = body.getAttribute("margin");
if (margin == null) {
return null;
}
String[] parts = margin.trim().split("\\s+");
return parts.length == 4 ? parts : null;
}
/**
* Регион колонтитула: extent = поле страницы, текст прижат к body
* (низ заголовка / верх футера); зазор — маргинами блоков.
*/
private static Element appendRegion(Element master, String kind, String extent,
String displayAlign) {
Element region = master.getOwnerDocument().createElementNS(FO_NS, "fo:" + kind);
region.setAttribute("extent", extent);
region.setAttribute("display-align", displayAlign);
master.appendChild(region);
return region;
}
/** В master-клоне варианта колонтитулы берутся из своего потока. */
private static void renameRegionFlows(Element clone, String suffix) {
for (String kind : new String[]{"region-before", "region-after"}) {
Element region = child(clone, kind);
if (region != null) {
region.setAttribute("flow-name", "xsl-" + kind + suffix);
}
}
}
/**
* Мастер с first/even-вариантами оборачивается в
* {@code fo:page-sequence-master} (на месте); {@code master-reference}
* page-sequence не меняется — он указывает на имя обёртки.
*/
private static void wrapInPageSequenceMaster(Document foDoc, Element master,
List<Element> variants) {
String masterName = master.getAttribute("master-name");
Element psm = foDoc.createElementNS(FO_NS, "fo:page-sequence-master");
psm.setAttribute("master-name", masterName);
Element alternatives = foDoc.createElementNS(FO_NS,
"fo:repeatable-page-master-alternatives");
psm.appendChild(alternatives);
for (Element variant : variants) {
String position = variant.getAttribute("master-name").endsWith("-first")
? "first" : "even";
alternatives.appendChild(conditionalRef(foDoc, position,
variant.getAttribute("master-name")));
}
alternatives.appendChild(conditionalRef(foDoc, "rest", masterName));
master.getParentNode().replaceChild(psm, master);
}
private static Element conditionalRef(Document foDoc, String position, String masterRef) {
Element ref = foDoc.createElementNS(FO_NS, "fo:conditional-page-master-reference");
ref.setAttribute("master-reference", masterRef);
ref.setAttribute("page-position", position);
return ref;
}
/**
* static-content вставляется в page-sequence перед fo:flow; каждый блок
* получает зазор {@code gapAttribute} к области контента (в самих
* регионах padding запрещён XSL 1.1 — FOP валидирует).
*/
private static void insertStaticContent(Element sequence, String flowName,
List<Element> content, String gapAttribute) {
if (content.isEmpty()) {
return;
}
Document doc = sequence.getOwnerDocument();
Element staticContent = doc.createElementNS(FO_NS, "fo:static-content");
staticContent.setAttribute("flow-name", flowName);
for (Element block : content) {
block.setAttribute(gapAttribute, REGION_GAP_IN + "in");
staticContent.appendChild(block);
}
Element flow = child(sequence, "flow");
if (flow == null) {
sequence.appendChild(staticContent);
} else {
sequence.insertBefore(staticContent, flow);
}
}
// ==================== История -> блоки FO ====================
/** Параграфы чанка истории как {@code fo:block}-и; пустой чанк — пустой список. */
private static List<Element> blocks(Document foDoc, List<Paragraph> chunk,
String lastMasterName) {
List<Element> result = new ArrayList<>();
if (chunk == null) {
return result;
}
for (Paragraph p : chunk) {
Element block = paragraphBlock(foDoc, p, lastMasterName);
if (block != null && blockHasVisibleContent(block)) {
result.add(block);
}
}
return result;
}
/**
* Параграф истории как {@code fo:block}: выравнивание, табуляции, раны с
* форматированием и поля (PAGE/NUMPAGES/SECTIONPAGES) из управляющих
* символов текста ранов ({@code \u0013}\u2026{@code \u0014}\u2026{@code \u0015}).
*/
private static Element paragraphBlock(Document doc, Paragraph p,
String lastMasterName) {
Element block = doc.createElementNS(FO_NS, "fo:block");
block.setAttribute("text-align", switch (p.getJustification()) {
case 1 -> "center";
case 2 -> "end";
case 3 -> "justify";
default -> "start";
});
// Наследуемый шрифт блока: fo:page-number — пустой элемент, без
// font-family блока FOP рисует его базовым Helvetica.
var blockFont = firstRunFont(p);
block.setAttribute("font-family", blockFont != null
? blockFont.getName()
: BundledFonts.regular(BundledFonts.FALLBACK_FAMILY).getName());
// state-machine полей: 0 — обычный текст, 1 — инструкция, 2 — кэш-результат
StringBuilder instr = new StringBuilder();
StringBuilder cached = new StringBuilder();
StringBuilder plain = new StringBuilder();
int column = 0;
int mode = 0;
for (int j = 0; j < p.numCharacterRuns(); j++) {
CharacterRun cr;
String text;
try {
cr = p.getCharacterRun(j);
text = cr.text();
} catch (RuntimeException e) {
continue;
}
if (text == null) {
continue;
}
for (int k = 0; k < text.length(); k++) {
char c = text.charAt(k);
if (c == FIELD_BEGIN) {
mode = 1;
instr.setLength(0);
cached.setLength(0);
} else if (c == FIELD_SEPARATOR && mode == 1) {
mode = 2;
} else if (c == FIELD_END && (mode == 1 || mode == 2)) {
emitField(doc, block, instr.toString(), cached.toString(), lastMasterName);
mode = 0;
} else if (mode == 1) {
instr.append(c);
} else if (mode == 2) {
cached.append(c);
} else if (c == '\t') {
column = appendTab(doc, block, plain, column, cr);
} else {
plain.append(c);
}
}
}
if (mode != 0) {
// незакрытое поле: выводим накопленное как обычный текст
plain.append(instr).append(cached);
}
flushText(doc, block, plain.toString(), null);
return block;
}
/** Распознанные поля — живые FO-элементы; прочие — кэш-текст как есть. */
private static void emitField(Document doc, Element block, String instruction,
String cachedResult, String lastMasterName) {
String code = instruction.trim().toUpperCase(Locale.ROOT);
if (code.startsWith("PAGE")) {
Element pn = doc.createElementNS(FO_NS, "fo:page-number");
block.appendChild(pn);
} else if ((code.startsWith("NUMPAGES") || code.startsWith("SECTIONPAGES"))
&& lastMasterName != null) {
// нумерация FOP между page-sequence непрерывна — citation-last
// по последнему мастеру = общее число страниц
Element pn = doc.createElementNS(FO_NS, "fo:page-number-citation-last");
pn.setAttribute("ref-name", lastMasterName);
block.appendChild(pn);
} else {
flushText(doc, block, cachedResult, null);
}
}
/**
* {@code \t}: FOP-форк не поддерживает свойство {@code tabs}, поэтому
* таб — пробелы до следующей дефолтной Word-остановки (1,25 см).
* Возвращает новую «колонку» (символы до курсора).
*/
private static int appendTab(Document doc, Element block, StringBuilder plain,
int column, CharacterRun cr) {
flushText(doc, block, plain.toString(), null);
plain.setLength(0);
double charIn = charWidthIn(cr);
double step = 1.25 / 2.54;
double x = (column + 1) * charIn;
double target = (Math.floor(x / step) + 1) * step;
int spaces = (int) Math.max(1, Math.ceil((target - x) / charIn));
flushText(doc, block, " ".repeat(spaces), cr);
return column + 1 + spaces;
}
/** Приблизительная ширина символа (полширины кегля) в дюймах. */
private static double charWidthIn(CharacterRun cr) {
double pt = 10.0;
try {
if (cr != null && cr.getFontSize() > 0) {
pt = cr.getFontSize() / 2.0;
}
} catch (RuntimeException e) {
// наследование из стиля — остаётся дефолт
}
return Math.max(0.03, pt * 0.5 / 72.0);
}
private static void flushText(Document doc, Element block, String text,
CharacterRun cr) {
String cleaned = cleanText(text);
if (cleaned.isEmpty()) {
return;
}
if (cr == null) {
block.appendChild(doc.createTextNode(cleaned));
return;
}
Element inline = doc.createElementNS(FO_NS, "fo:inline");
var font = runFont(cr);
if (font != null) {
inline.setAttribute("font-family", font.getName());
}
int halfPoints = cr.getFontSize();
inline.setAttribute("font-size", (halfPoints > 0 ? halfPoints / 2.0 : 10.0) + "pt");
if (cr.isBold()) {
inline.setAttribute("font-weight", "bold");
}
if (cr.isItalic()) {
inline.setAttribute("font-style", "italic");
}
if (cr.getUnderlineCode() != 0) {
inline.setAttribute("text-decoration", "underline");
}
inline.appendChild(doc.createTextNode(cleaned));
block.appendChild(inline);
}
/** Шрифт рана -> бандл-аналог (тот же маппинг, что у основного текста). */
private static org.docx4j.fonts.PhysicalFont runFont(CharacterRun cr) {
String name;
try {
name = cr.getFontName();
} catch (RuntimeException e) {
return null;
}
String family = BundledFontMapper.bundledFamily(name == null ? "" : name);
return BundledFonts.regular(family);
}
/** Шрифт первого читаемого рана параграфа (для наследуемого font-family блока). */
private static org.docx4j.fonts.PhysicalFont firstRunFont(Paragraph p) {
try {
for (int j = 0; j < p.numCharacterRuns(); j++) {
var font = runFont(p.getCharacterRun(j));
if (font != null) {
return font;
}
}
} catch (RuntimeException e) {
// повреждённый параграф — на fallback вызывающего
}
return null;
}
/**
* POI пишет маркеры списков {@code fo:inline} без font-family — FOP
* рисует их базовым Helvetica. Проставляем фолбэк-семейство всем
* инлайнам без семейства.
*/
private static void applyDefaultFont(Document foDoc) {
String fallback = BundledFonts.regular(BundledFonts.FALLBACK_FAMILY).getName();
NodeList inlines = foDoc.getElementsByTagNameNS(FO_NS, "inline");
for (int i = 0; i < inlines.getLength(); i++) {
Element inline = (Element) inlines.item(i);
if (inline.getAttribute("font-family").isEmpty()) {
inline.setAttribute("font-family", fallback);
}
}
}
// ==================== FOP ====================
private static void renderFo(Document foDoc, String title, Path baseDir,
OutputStream out) throws Exception {
byte[] config = fopConfig().getBytes(StandardCharsets.UTF_8);
FopFactory fopFactory = FopFactory.newInstance(baseDir.toUri(),
new ByteArrayInputStream(config));
FOUserAgent ua = fopFactory.newFOUserAgent();
// Дефолт кэша шрифтов форка — <user.home>/.fop/fop-fonts.cache, а при
// непригодном user.home (контейнер без HOME) — файл ".fop" в текущем
// каталоге; в образе /app не пишется non-root'ом -> 500 на каждом .doc.
// Кэш бесполезен: auto-detect="false", шрифты объявлены из classpath.
ua.getFontManager().disableFontCache();
if (title != null && !title.isBlank()) {
ua.setTitle(title);
}
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, ua, out);
javax.xml.transform.Transformer transformer =
javax.xml.transform.TransformerFactory.newInstance().newTransformer();
transformer.transform(new DOMSource(foDoc), new SAXResult(fop.getDefaultHandler()));
}
/**
* FOP-конфиг: только шрифты бандла (auto-detect="false" — системные в
* рендер не попадают). Triplet-имена — из name-таблиц regular-вариантов,
* как в {@link FopFallbackFonts}; {@code simulate-style="false"} — стили
* настоящие TTF, а не синтез FOP.
*/
private static String fopConfig() {
StringBuilder sb = new StringBuilder(
"<fop version=\"1.0\"><renderers>"
+ "<renderer mime=\"application/pdf\"><fonts auto-detect=\"false\">");
for (String family : BundledFonts.families()) {
var regular = BundledFonts.regular(family);
if (regular == null) {
continue;
}
String tripletName = regular.getName();
appendFont(sb, regular, "regular", tripletName, "normal", "normal");
appendFont(sb, BundledFonts.bold(family), "bold", tripletName, "normal", "bold");
appendFont(sb, BundledFonts.italic(family), "italic", tripletName, "italic", "normal");
appendFont(sb, BundledFonts.boldItalic(family), "boldItalic",
tripletName, "italic", "bold");
}
sb.append("</fonts></renderer></renderers></fop>");
return sb.toString();
}
private static void appendFont(StringBuilder sb, org.docx4j.fonts.PhysicalFont pf,
String embedMode, String tripletName,
String style, String weight) {
if (pf == null) {
return;
}
sb.append("<font embed-url=\"").append(pf.getEmbeddedURI())
.append("\" embed-mode=\"").append(embedMode)
.append("\" simulate-style=\"false\"><font-triplet name=\"")
.append(tripletName).append("\" style=\"").append(style)
.append("\" weight=\"").append(weight)
.append("\"/></font>");
}
// ==================== Утилиты DOM ====================
private static Element child(Element parent, String localName) {
NodeList children = parent.getChildNodes();
for (int i = 0; i < children.getLength(); i++) {
Node n = children.item(i);
if (n instanceof Element e && FO_NS.equals(e.getNamespaceURI())
&& localName.equals(e.getLocalName())) {
return e;
}
}
return null;
}
private static boolean blockHasVisibleContent(Element block) {
if (block.getTextContent() != null && !block.getTextContent().isBlank()) {
return true;
}
return block.getElementsByTagNameNS(FO_NS, "page-number").getLength() > 0
|| block.getElementsByTagNameNS(FO_NS, "page-number-citation-last").getLength() > 0
|| block.getElementsByTagNameNS(FO_NS, "leader").getLength() > 0;
}
/** Есть ли в чанке хоть один параграф с видимым содержимым. */
private static boolean hasText(List<Paragraph> chunk) {
if (chunk == null) {
return false;
}
for (Paragraph p : chunk) {
try {
for (int j = 0; j < p.numCharacterRuns(); j++) {
String t = p.getCharacterRun(j).text();
if (t != null && !cleanText(t).isEmpty()) {
return true;
}
}
} catch (RuntimeException e) {
// повреждённый ран — не содержимое
}
}
return false;
}
private static String cleanText(String t) {
StringBuilder sb = new StringBuilder(t.length());
for (int i = 0; i < t.length(); i++) {
char c = t.charAt(i);
if (c != PARA_END && c != CELL_END && c != SECTION_END) {
sb.append(c);
}
}
return sb.toString();
}
private static void deleteRecursively(Path dir) {
try (Stream<Path> walk = Files.walk(dir)) {
walk.sorted(Comparator.reverseOrder()).forEach(p -> {
try {
Files.deleteIfExists(p);
} catch (IOException ignored) {
// temp-файлы: нечего делать при отказе удаления
}
});
} catch (IOException ignored) {
}
}
}
@@ -0,0 +1,259 @@
package ru.pjandro.wordpdf;
import org.apache.pdfbox.Loader;
import org.apache.pdfbox.cos.COSName;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDResources;
import org.apache.pdfbox.pdmodel.font.PDFont;
import org.apache.pdfbox.pdmodel.graphics.PDXObject;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
import org.apache.pdfbox.text.PDFTextStripper;
import org.apache.pdfbox.text.TextPosition;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.IdentityHashMap;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;
import static org.junit.jupiter.api.Assertions.*;
/**
* Конвертация бинарного .doc (Word 97-2003, OLE2) через ветку
* {@code internal.DocToPdfRenderer} (POI HWPF -> XSL-FO -> FOP).
* Фикстура — закоммиченный samples/legacy-doc.doc (создан Word'ом,
* POI .doc не пишет — не перезагенерировать).
*
* <p>Ассерты только на фактическое содержимое фикстуры и на раны,
* ушедшие в Tinos (аналог Times New Roman): текст ран, ушедших в
* DejaVu-fallback, PDFBox на машинах с установленным DejaVu «чинит»
* по системному шрифту и извлекает «#» — такие строки не ассертятся
* (экзотические глифы фикстуры — принятая деградация .doc-ветки:
* аналога GlyphCoverageNormalizer здесь нет).
*/
class DocToPdfTest {
private static byte[] sampleBytes(String name) throws IOException {
try (InputStream in = DocToPdfTest.class.getClassLoader()
.getResourceAsStream("samples/" + name)) {
assertNotNull(in, "Нет тестового документа: samples/" + name);
return in.readAllBytes();
}
}
private static Path convertPdf(byte[] docBytes, String title) throws IOException {
Path out = Files.createTempFile("converted-doc-", ".pdf");
Files.write(out, WordPdfConverter.convert(docBytes, title));
return out;
}
private static String norm(String s) {
return s.replaceAll("\\s+", "");
}
private static String pdfPageText(Path pdf, int page) throws IOException {
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
PDFTextStripper stripper = new PDFTextStripper();
stripper.setStartPage(page);
stripper.setEndPage(page);
return stripper.getText(doc);
}
}
/** Строка страницы: базовая линия y (от верха страницы, PDFBox YDirAdj) и текст. */
private record Line(float y, String text) {
}
/** Непустые строки страницы с базовыми линиями (порядок по позиции). */
private static List<Line> pageLines(Path pdf, int page) throws IOException {
List<Line> lines = new ArrayList<>();
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
PDFTextStripper stripper = new PDFTextStripper() {
@Override
protected void writeString(String text, List<TextPosition> textPositions)
throws IOException {
super.writeString(text, textPositions);
if (!textPositions.isEmpty() && !norm(text).isEmpty()) {
lines.add(new Line(textPositions.get(0).getYDirAdj(), text));
}
}
};
stripper.setStartPage(page);
stripper.setEndPage(page);
stripper.setSortByPosition(true);
stripper.getText(doc);
}
return lines;
}
/** y базовой линии первой строки, содержащей needle (после norm); null если нет. */
private static Float lineY(Path pdf, int page, String needle) throws IOException {
String n = norm(needle);
for (Line l : pageLines(pdf, page)) {
if (norm(l.text()).contains(n)) {
return l.y();
}
}
return null;
}
/** Максимум y по всем непустым строкам страницы (самая нижняя базовая линия). */
private static float maxLineY(Path pdf, int page) throws IOException {
float max = Float.MIN_VALUE;
for (Line l : pageLines(pdf, page)) {
max = Math.max(max, l.y());
}
return max;
}
/** BaseFont-имена вшитых шрифтов PDF (например "EAAAAA+Tinos-Bold"). */
private static Set<String> embeddedFontNames(Path pdf) throws IOException {
Set<String> names = new TreeSet<>();
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
for (PDPage page : doc.getPages()) {
PDResources res = page.getResources();
for (COSName name : res.getFontNames()) {
PDFont font = res.getFont(name);
if (font != null) {
names.add(font.getName());
}
}
}
}
return names;
}
/** Число уникальных Image XObject в PDF (наследованные ресурсы — один объект). */
private static int imageCount(Path pdf) throws IOException {
Set<PDXObject> seen = java.util.Collections.newSetFromMap(new IdentityHashMap<>());
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
for (PDPage page : doc.getPages()) {
PDResources res = page.getResources();
for (COSName name : res.getXObjectNames()) {
PDXObject xo = res.getXObject(name);
if (xo instanceof PDImageXObject) {
seen.add(xo);
}
}
}
}
return seen.size();
}
/**
* .doc конвертируется в PDF: текст кириллический, таблицы и картинки
* на месте, шрифт — встроенный Tinos (аналог Times New Roman),
* базовый Helvetica не используется.
* Регрессия — WordPdfConverter#isOle2 + internal.DocToPdfRenderer,
* фикстура samples/legacy-doc.doc.
*/
@Test
void legacyDoc_convertsToPdf() throws Exception {
Path pdf = convertPdf(sampleBytes("legacy-doc.doc"), "testDoc");
String text;
int pages;
try (PDDocument doc = Loader.loadPDF(pdf.toFile())) {
pages = doc.getNumberOfPages();
text = norm(new PDFTextStripper().getText(doc));
}
assertTrue(pages >= 10, "страниц меньше ожидаемого: " + pages);
assertTrue(text.contains("Предметдоговора"), "нет заголовка раздела");
assertTrue(text.contains("Договорарендыпомещения"), "нет заголовка");
for (String font : embeddedFontNames(pdf)) {
assertFalse(font.contains("Helvetica"), "базовый шрифт в PDF: " + font);
}
assertTrue(embeddedFontNames(pdf).stream().anyMatch(n -> n.contains("Tinos")),
"нет Tinos (аналога Times New Roman): " + embeddedFontNames(pdf));
assertTrue(imageCount(pdf) >= 1, "картинок нет");
}
/**
* Колонтитулы, которых POI в FO не пишет, дописываются в FO-DOM:
* текст odd-footer («Нижний колонтитул») и номер страницы из PAGE-поля
* на каждой странице.
* Регрессия — DocToPdfRenderer#injectHeadersAndFooters,
* фикстура samples/legacy-doc.doc.
*/
@Test
void legacyDoc_footersCarryPageNumbers() throws Exception {
Path pdf = convertPdf(sampleBytes("legacy-doc.doc"), "testDoc");
String page1 = norm(pdfPageText(pdf, 1));
String page5 = norm(pdfPageText(pdf, 5));
assertTrue(page5.contains("Нижнийколонтитул"), "нет текста футера на стр. 5");
assertTrue(page1.startsWith("1"), "нет номера страницы на стр. 1: "
+ page1.substring(0, Math.min(20, page1.length())));
assertTrue(page5.contains("5"), "нет номера страницы на стр. 5");
}
/**
* Текст body не наезжает на области колонтитулов: заголовок первой
* строки лежит ниже header-региона (extent = верхнее поле 0.7875in =
* 56.7pt), под строкой футера ничего нет. Форк FOP не вычитает
* extent'ы регионов из body-области (area.Page = page-area минус
* собственные margin'ы region-body), поэтому разводка body и
* колонтитулов — только margin'ами region-body; их обнуление
* растягивает body на всю страницу, и текст лезет в колонтитулы.
* Регрессия — DocToPdfRenderer#injectHeadersAndFooters,
* фикстура samples/legacy-doc.doc.
*/
@Test
void legacyDoc_bodyClearsHeaderFooterRegions() throws Exception {
Path pdf = convertPdf(sampleBytes("legacy-doc.doc"), "testDoc");
Float titleY = lineY(pdf, 1, "Договор аренды");
assertNotNull(titleY, "нет заголовка на стр. 1");
assertTrue(titleY > 50f, "заголовок внутри header-региона: y=" + titleY);
Float footerY = lineY(pdf, 1, "Нижний колонтитул");
assertNotNull(footerY, "нет футера на стр. 1");
float lowest = maxLineY(pdf, 1);
assertTrue(lowest <= footerY + 1f,
"строка ниже футера: y=" + lowest + " > y футера " + footerY);
}
/**
* Кэш шрифтов FOP не пишется в текущий каталог: при непригодном user.home
* (контейнер без HOME) дефолт форка — файл ".fop" в CWD, а в образе /app
* не пишется non-root'ом => 500 на каждом .doc. Кэш отключён в renderFo.
* Регрессия — DocToPdfRenderer#renderFo, фикстура samples/legacy-doc.doc.
*/
@Test
void legacyDoc_fontCacheNotWrittenToWorkingDir() throws Exception {
String savedHome = System.getProperty("user.home");
Path stray = Path.of(".fop");
Files.deleteIfExists(stray);
System.setProperty("user.home", "/no-such-home-" + System.nanoTime());
try {
convertPdf(sampleBytes("legacy-doc.doc"), "testDoc");
assertFalse(Files.exists(stray), "FOP записал кэш шрифтов .fop в рабочий каталог");
} finally {
if (savedHome == null) {
System.clearProperty("user.home");
} else {
System.setProperty("user.home", savedHome);
}
Files.deleteIfExists(stray);
}
}
/**
* OLE2-магик + мусор: и валидатор, и конвертер обязаны отвергнуть
* документ (не молча отдать пустой PDF).
* Регрессия — DocToPdfRenderer#render, WordPdfValidator#checkDocPageCountLightweight.
*/
@Test
void ole2Junk_rejected() {
byte[] junk = new byte[1024];
byte[] magic = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
System.arraycopy(magic, 0, junk, 0, magic.length);
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkDocPageCountLightweight(junk));
assertThrows(ConversionException.class,
() -> WordPdfConverter.convert(junk, "junk"));
}
}
@@ -156,7 +156,7 @@ class WordPdfConverterTest {
void drawingToggles_offRemovesRasters() throws Exception { void drawingToggles_offRemovesRasters() throws Exception {
Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart", Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart",
new ConvertOptions(false, false, false, false, new ConvertOptions(false, false, false, false,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES)); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES));
String text = norm(pdfText(pdf)); String text = norm(pdfText(pdf));
assertTrue(text.contains("Диаграммы"), "пропал текст вокруг диаграмм: " + text); assertTrue(text.contains("Диаграммы"), "пропал текст вокруг диаграмм: " + text);
@@ -173,7 +173,7 @@ class WordPdfConverterTest {
void drawingToggles_chartsOffSmartArtOn() throws Exception { void drawingToggles_chartsOffSmartArtOn() throws Exception {
Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart", Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart",
new ConvertOptions(false, true, false, false, new ConvertOptions(false, true, false, false,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES)); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES));
String text = norm(pdfText(pdf)); String text = norm(pdfText(pdf));
assertTrue(text.contains("Диаграммы"), "пропал текст вокруг диаграмм: " + text); assertTrue(text.contains("Диаграммы"), "пропал текст вокруг диаграмм: " + text);
@@ -192,7 +192,7 @@ class WordPdfConverterTest {
ConversionException ex = assertThrows(ConversionException.class, () -> ConversionException ex = assertThrows(ConversionException.class, () ->
convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart", convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart",
new ConvertOptions(false, true, true, false, new ConvertOptions(false, true, true, false,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES))); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES)));
assertTrue(ex instanceof DrawingFoundException dfe assertTrue(ex instanceof DrawingFoundException dfe
&& dfe.kind() == DrawingFoundException.Kind.CHARTS, && dfe.kind() == DrawingFoundException.Kind.CHARTS,
@@ -210,7 +210,7 @@ class WordPdfConverterTest {
ConversionException ex = assertThrows(ConversionException.class, () -> ConversionException ex = assertThrows(ConversionException.class, () ->
convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart", convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart",
new ConvertOptions(true, false, false, true, new ConvertOptions(true, false, false, true,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES))); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES)));
assertTrue(ex instanceof DrawingFoundException dfe assertTrue(ex instanceof DrawingFoundException dfe
&& dfe.kind() == DrawingFoundException.Kind.SMARTART, && dfe.kind() == DrawingFoundException.Kind.SMARTART,
@@ -227,7 +227,7 @@ class WordPdfConverterTest {
void drawingErrors_renderFlagWins() throws Exception { void drawingErrors_renderFlagWins() throws Exception {
Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart", Path pdf = convertPdf(sampleBytes("charts-smartart.docx"), "charts-smartart",
new ConvertOptions(true, true, true, true, new ConvertOptions(true, true, true, true,
WordPdfSettings.MAX_INPUT_BYTES, WordPdfSettings.MAX_PAGES)); WordPdfSettings.MAX_INPUT_MB, WordPdfSettings.MAX_PAGES));
assertTrue(imageCount(pdf) >= 4, assertTrue(imageCount(pdf) >= 4,
"рендер должен победить error-флаг, найдено растров: " + imageCount(pdf)); "рендер должен победить error-флаг, найдено растров: " + imageCount(pdf));
@@ -441,7 +441,7 @@ class WordPdfConverterTest {
*/ */
@Test @Test
void inputTooLarge() { void inputTooLarge() {
byte[] tooBig = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; byte[] tooBig = new byte[(int) (WordPdfSettings.MAX_INPUT_MB * 1024 * 1024) + 1];
ValidationException ex = assertThrows(ValidationException.class, () -> ValidationException ex = assertThrows(ValidationException.class, () ->
WordPdfConverter.convert(tooBig, "too-big")); WordPdfConverter.convert(tooBig, "too-big"));
assertTrue(ex.getMessage().contains("5 МБ"), assertTrue(ex.getMessage().contains("5 МБ"),
@@ -449,32 +449,36 @@ class WordPdfConverterTest {
} }
/** /**
* Вход без zip-подписи — отказ как некорректный вход (ValidationException), * Вход без подписи контейнера (ни zip, ни OLE2) — отказ как некорректный
* а не ошибка рендера: вход конвертера прогоняет тот же * вход (ValidationException), а не ошибка рендера: вход конвертера
* {@link WordPdfValidator#validate(byte[], ConvertOptions)}, что и приложение до очереди. * прогоняет тот же {@link WordPdfValidator#validate(byte[], ConvertOptions)},
* Регрессия — WordPdfValidatorTest#validate_notAZip. * что и приложение до очереди. Регрессия —
* WordPdfValidatorTest#validate_neitherDocxNorDoc.
*/ */
@Test @Test
void inputNotAZip_rejectedBeforeRender() { void inputNotAZip_rejectedBeforeRender() {
byte[] junk = {1, 2, 3, 4, 5, 6, 7, 8}; byte[] junk = {1, 2, 3, 4, 5, 6, 7, 8};
ValidationException ex = assertThrows(ValidationException.class, () -> ValidationException ex = assertThrows(ValidationException.class, () ->
WordPdfConverter.convert(junk, "junk")); WordPdfConverter.convert(junk, "junk"));
assertTrue(ex.getMessage().contains("не zip-архив"), assertTrue(ex.getMessage().contains("не похоже на .docx или .doc"),
"сообщение должно упоминать zip-подпись: " + ex.getMessage()); "сообщение должно упоминать подписи контейнера: " + ex.getMessage());
} }
/** /**
* Лимит размера переопределяется {@link ConvertOptions} на вызов: * Лимит размера переопределяется {@link ConvertOptions} на вызов:
* maxBytes=1000 отсекает даже маленький документ до рендера, сообщение * maxMb=1 отсекает вход больше 1 MiB до рендера, сообщение содержит
* содержит переданное значение в байтах. * переданное значение в МБ и байтах.
*/ */
@Test @Test
void limitsOverriddenByOptions() throws Exception { void limitsOverriddenByOptions() {
byte[] big = new byte[1024 * 1024 + 1];
ValidationException ex = assertThrows(ValidationException.class, () -> ValidationException ex = assertThrows(ValidationException.class, () ->
WordPdfConverter.convert(sampleBytes("ru-plain.docx"), "x", WordPdfConverter.convert(big, "x",
new ConvertOptions(true, true, false, false, 1000, WordPdfSettings.MAX_PAGES))); new ConvertOptions(true, true, false, false, 1, WordPdfSettings.MAX_PAGES)));
assertTrue(ex.getMessage().contains("1000 байт"), assertTrue(ex.getMessage().contains("1 МБ"),
"сообщение должно упоминать переданный лимит: " + ex.getMessage()); "сообщение должно упоминать переданный лимит: " + ex.getMessage());
assertTrue(ex.getMessage().contains("1048576 байт"),
"сообщение должно упоминать лимит в байтах: " + ex.getMessage());
} }
/** /**
@@ -487,7 +491,7 @@ class WordPdfConverterTest {
ValidationException ex = assertThrows(ValidationException.class, () -> ValidationException ex = assertThrows(ValidationException.class, () ->
WordPdfConverter.convert( WordPdfConverter.convert(
sampleBytes("too-many-pages.docx"), "too-many-pages", sampleBytes("too-many-pages.docx"), "too-many-pages",
new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_BYTES, 100))); new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_MB, 100)));
assertTrue(ex.getMessage().contains("100"), assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage()); "сообщение должно упоминать лимит: " + ex.getMessage());
} }
@@ -503,7 +507,7 @@ class WordPdfConverterTest {
void staleCachePageCountRejectedBeforeRender() { void staleCachePageCountRejectedBeforeRender() {
ValidationException ex = assertThrows(ValidationException.class, () -> ValidationException ex = assertThrows(ValidationException.class, () ->
WordPdfConverter.convert(sampleBytes("stale-cache.docx"), "stale-cache", WordPdfConverter.convert(sampleBytes("stale-cache.docx"), "stale-cache",
new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_BYTES, 100))); new ConvertOptions(true, true, false, false, WordPdfSettings.MAX_INPUT_MB, 100)));
assertTrue(ex.getMessage().contains("100"), assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage()); "сообщение должно упоминать лимит: " + ex.getMessage());
} }
@@ -40,7 +40,7 @@ class WordPdfValidatorTest {
@Test @Test
void checkInput_bytesOverLimit() { void checkInput_bytesOverLimit() {
byte[] big = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; byte[] big = new byte[(int) (WordPdfSettings.MAX_INPUT_MB * 1024 * 1024) + 1];
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.checkInput(big)); () -> WordPdfValidator.checkInput(big));
assertTrue(ex.getMessage().contains("5 МБ"), assertTrue(ex.getMessage().contains("5 МБ"),
@@ -54,15 +54,15 @@ class WordPdfValidatorTest {
} }
/** /**
* Явный лимит размера (переопределение на вызов): меньше — проходит, * Явный лимит размера в МБ (переопределение на вызов): меньше 1 MiB —
* больше — отказ с не-МБ формулировкой «N байт». * проходит, больше — отказ с лимитом в МБ и байтах.
*/ */
@Test @Test
void checkInput_customLimit() { void checkInput_customLimit() {
assertDoesNotThrow(() -> WordPdfValidator.checkInput(new byte[10], 100)); assertDoesNotThrow(() -> WordPdfValidator.checkInput(new byte[10], 1));
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.checkInput(new byte[11], 10)); () -> WordPdfValidator.checkInput(new byte[1024 * 1024 + 1], 1));
assertTrue(ex.getMessage().contains("10 байт"), assertTrue(ex.getMessage().contains("1 МБ"),
"сообщение должно упоминать переданный лимит: " + ex.getMessage()); "сообщение должно упоминать переданный лимит: " + ex.getMessage());
} }
@@ -256,8 +256,8 @@ class WordPdfValidatorTest {
// ===== validate(byte[], ConvertOptions) ===== // ===== validate(byte[], ConvertOptions) =====
private static ConvertOptions options(long maxBytes, int maxPages) { private static ConvertOptions options(long maxMb, int maxPages) {
return new ConvertOptions(true, true, false, false, maxBytes, maxPages); return new ConvertOptions(true, true, false, false, maxMb, maxPages);
} }
@Test @Test
@@ -268,7 +268,7 @@ class WordPdfValidatorTest {
@Test @Test
void validate_bytesOverLimit() { void validate_bytesOverLimit() {
byte[] big = new byte[(int) WordPdfSettings.MAX_INPUT_BYTES + 1]; byte[] big = new byte[(int) (WordPdfSettings.MAX_INPUT_MB * 1024 * 1024) + 1];
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(big, ConvertOptions.defaults())); () -> WordPdfValidator.validate(big, ConvertOptions.defaults()));
assertTrue(ex.getMessage().contains("5 МБ"), assertTrue(ex.getMessage().contains("5 МБ"),
@@ -276,12 +276,12 @@ class WordPdfValidatorTest {
} }
@Test @Test
void validate_notAZip() { void validate_neitherDocxNorDoc() {
byte[] junk = {1, 2, 3, 4, 5}; byte[] junk = {1, 2, 3, 4, 5};
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(junk, ConvertOptions.defaults())); () -> WordPdfValidator.validate(junk, ConvertOptions.defaults()));
assertTrue(ex.getMessage().contains("не zip-архив"), assertTrue(ex.getMessage().contains("не похоже на .docx или .doc"),
"сообщение должно упоминать zip-подпись: " + ex.getMessage()); "сообщение должно упоминать обе подписи контейнера: " + ex.getMessage());
} }
@Test @Test
@@ -289,7 +289,7 @@ class WordPdfValidatorTest {
byte[] bytes = docxWithPageBreaks(120); byte[] bytes = docxWithPageBreaks(120);
ValidationException ex = assertThrows(ValidationException.class, ValidationException ex = assertThrows(ValidationException.class,
() -> WordPdfValidator.validate(bytes, () -> WordPdfValidator.validate(bytes,
options(WordPdfSettings.MAX_INPUT_BYTES, 100))); options(WordPdfSettings.MAX_INPUT_MB, 100)));
assertTrue(ex.getMessage().contains("не менее 121"), assertTrue(ex.getMessage().contains("не менее 121"),
"оценка = 1 + 120 разрывов: " + ex.getMessage()); "оценка = 1 + 120 разрывов: " + ex.getMessage());
} }
@@ -332,4 +332,49 @@ class WordPdfValidatorTest {
() -> WordPdfValidator.checkPageCount(docx, 3)); () -> WordPdfValidator.checkPageCount(docx, 3));
assertTrue(ex.getMessage().contains("не менее 4"), ex.getMessage()); assertTrue(ex.getMessage().contains("не менее 4"), ex.getMessage());
} }
/** Фикстура бинарного .doc (закоммичена, создана Word'ом — POI .doc не пишет). */
private static byte[] legacyDocBytes() throws Exception {
try (var in = WordPdfValidatorTest.class.getClassLoader()
.getResourceAsStream("samples/legacy-doc.doc")) {
assertNotNull(in, "Нет тестового документа: samples/legacy-doc.doc");
return in.readAllBytes();
}
}
/**
* Число страниц .doc — кэш SummaryInformation (для фикстуры 11):
* лимит 10 должен отвергать, 20 — пропускать.
* Регрессия — WordPdfValidator#checkDocPageCountLightweight,
* фикстура samples/legacy-doc.doc.
*/
@Test
void checkDocPageCountLightweight_overLimitRejected() throws Exception {
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkDocPageCountLightweight(legacyDocBytes(), 10));
assertTrue(ex.getMessage().contains("не менее 11"), ex.getMessage());
}
@Test
void checkDocPageCountLightweight_underLimitPasses() throws Exception {
byte[] doc = legacyDocBytes();
assertDoesNotThrow(() -> WordPdfValidator.checkDocPageCountLightweight(doc, 20));
assertDoesNotThrow(() -> WordPdfValidator.checkDocPageCountLightweight(doc));
}
@Test
void checkDocPageCountLightweight_junkRejected() {
byte[] junk = new byte[1024];
byte[] magic = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0,
(byte) 0xA1, (byte) 0xB1, 0x1A, (byte) 0xE1};
System.arraycopy(magic, 0, junk, 0, magic.length);
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkDocPageCountLightweight(junk));
}
@Test
void checkDocPageCountLightweight_bytesNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkDocPageCountLightweight((byte[]) null));
}
} }
+1 -1
View File
@@ -66,7 +66,7 @@ export async function convertDocx(
// флаг i обязателен; фолбэк — имя исходника с заменой расширения // флаг i обязателен; фолбэк — имя исходника с заменой расширения
const cd = resp.headers.get('Content-Disposition') ?? '' const cd = resp.headers.get('Content-Disposition') ?? ''
const m = /filename\*=utf-8''([^;]+)/i.exec(cd) const m = /filename\*=utf-8''([^;]+)/i.exec(cd)
const filename = m ? decodeURIComponent(m[1]) : file.name.replace(/\.docx$/i, '') + '.pdf' const filename = m ? decodeURIComponent(m[1]) : file.name.replace(/\.docx?$/i, '') + '.pdf'
const blob = await resp.blob() const blob = await resp.blob()
return { blob, filename } return { blob, filename }
} }
+1 -1
View File
@@ -152,7 +152,7 @@ export default function App() {
<div> <div>
<h1 className="text-2xl font-semibold">Word → PDF</h1> <h1 className="text-2xl font-semibold">Word → PDF</h1>
<p className="mt-1 text-sm text-muted"> <p className="mt-1 text-sm text-muted">
docx → PDF на docx4j + Apache FOP. Лимиты (файл ≤ 5 МБ, docx/doc → PDF на docx4j + Apache FOP. Лимиты (файл ≤ 5 МБ,
≤ 100 страниц) задаёт сервер; переопределение из формы убрано. ≤ 100 страниц) задаёт сервер; переопределение из формы убрано.
</p> </p>
</div> </div>
+3 -3
View File
@@ -8,7 +8,7 @@ interface Props {
} }
/** /**
* Зона drag&drop + клик для выбора .docx. Скрытый input[type=file] — * Зона drag&drop + клик для выбора .docx/.doc. Скрытый input[type=file] —
* единственный источник выбора; drop берёт первый файл. * единственный источник выбора; drop берёт первый файл.
*/ */
export default function DropZone({ file, disabled, onSelect }: Props) { export default function DropZone({ file, disabled, onSelect }: Props) {
@@ -53,7 +53,7 @@ export default function DropZone({ file, disabled, onSelect }: Props) {
<path d="M12 16V4m0 0-4 4m4-4 4 4" /> <path d="M12 16V4m0 0-4 4m4-4 4 4" />
<path d="M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" /> <path d="M4 16v3a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-3" />
</svg> </svg>
<span>Перетащите .docx сюда или нажмите для выбора</span> <span>Перетащите .docx или .doc сюда или нажмите для выбора</span>
{file && ( {file && (
<span className="text-sm text-muted"> <span className="text-sm text-muted">
{file.name} · {(file.size / 1024).toFixed(0)} КБ {file.name} · {(file.size / 1024).toFixed(0)} КБ
@@ -62,7 +62,7 @@ export default function DropZone({ file, disabled, onSelect }: Props) {
<input <input
ref={inputRef} ref={inputRef}
type="file" type="file"
accept=".docx" accept=".docx,.doc"
className="sr-only" className="sr-only"
disabled={disabled} disabled={disabled}
onChange={(e) => { onChange={(e) => {