From c7dec86b54d91d0128a78f96b3b16f3971cde43b Mon Sep 17 00:00:00 2001 From: Pjandro Date: Thu, 15 Oct 2026 21:13:42 +0000 Subject: [PATCH] =?UTF-8?q?Fix:=20Swagger=20UI/OpenAPI=20=D0=BF=D0=BE?= =?UTF-8?q?=D0=B4=20=D0=BF=D1=80=D0=B5=D1=84=D0=B8=D0=BA=D1=81=D0=BE=D0=BC?= =?UTF-8?q?=20/pdf-converter,=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BE=D1=82=D0=BA=D1=80=D1=8B?= =?UTF-8?q?=D1=82=D0=B0=20=D0=B1=D0=B5=D0=B7=20=D0=BA=D0=BB=D1=8E=D1=87?= =?UTF-8?q?=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Прод (наружный nginx срезает /pdf-converter/): springdoc генерировал абсолютные URL от корня хоста — пути до /v3/api-docs и swagger-ui битые. server.forward-headers-strategy=framework + X-Forwarded-* (добавляет наружный nginx) дают server https://pjandro.ru/pdf-converter и configUrl с префиксом; 'native'-клапан Tomcat X-Forwarded-Prefix не понимает. ApiKeyFilter: матч по пути без forwarded-contextPath (под префиксным заголовком getRequestURI() включает префикс — HEALTHCHECK получил бы 401) + открытые без ключа /swagger-ui* и /v3/api-docs* (браузер не может положить ключ в заголовок при загрузке UI; /api/** под ключом). OpenApiConfig: @SecurityScheme X-API-Key — кнопка Authorize в UI, @SecurityRequirement на convert — «Try it out» с ключом. springdoc.swagger-ui.persist-authorization=true. Регрессии: ApiKeyFilterTest#docsOpenWithoutKey, #forwardedPrefix_healthStaysOpen, #forwardedPrefix_docsOpenWithoutKey (вместо удалённого openApiRequiresKey). AGENTS.md синхронизирован. --- AGENTS.md | 14 ++++---- wordpdf-app/pom.xml | 2 +- .../ru/pjandro/wordpdf/app/ApiKeyFilter.java | 34 ++++++++++++++++--- .../wordpdf/app/ConvertController.java | 2 ++ .../ru/pjandro/wordpdf/app/OpenApiConfig.java | 22 ++++++++++++ .../src/main/resources/application.properties | 8 +++++ .../pjandro/wordpdf/app/ApiKeyFilterTest.java | 26 +++++++++++--- 7 files changed, 92 insertions(+), 16 deletions(-) create mode 100644 wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/OpenApiConfig.java diff --git a/AGENTS.md b/AGENTS.md index 5974557..4e52d21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Project Overview -Конвертер `.docx` → `.pdf` на чистом Java (docx4j 17.3.2 + форк Apache FOP, без LibreOffice/Aspose). Java 21, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-app` (Spring Boot 4.1.1 REST API); `wordpdf-web` — React SPA в nginx-контейнере (отдельный деп, вне Maven). Единственный гейт перед `git push` — `mvn clean verify` (CI нет; SPA гейтуется `npm run build` + `npm run lint`). Вход стека — контейнер `gateway` (nginx), НЕ 8080. README устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что прод заглушает springdoc env'ами, — авторитет этот файл. +Конвертер `.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 устарел шире Docker-секции: лимиты (пишет 5 МБ/100 стр./6 МБ multipart — фактически 20 MiB/1000/100 MB), порты («всё на :8080» — фактически gateway :9010/:9011), API-ключ вообще не упомянут; плюс «фикстуры генерируются POI» (они закоммичены, POI только в генераторе) и Swagger UI без оговорки, что в проде она открыта без ключа, — авторитет этот файл. ## Architecture & Data Flow @@ -22,7 +22,7 @@ - Единственный эндпоинт `POST /api/v1/convert` (multipart-поле `file`, факультативные `renderCharts`/`renderSmartArt` — query или form) → `application/pdf`, `Content-Disposition: attachment; filename*=UTF-8''…`. Проверка `.docx`-расширения — в `ConvertController`; `safeBaseName` в `ConversionService` — единый источник имени для файла, заголовка ответа и PDF-title (разрешены `[\p{L}\p{N} ._-]`, пустое → `document`). - Конвертации **сериализованы** однопоточным `ThreadPoolExecutor` (`ConversionService.QUEUE_CAPACITY = 16`, переполнение → 503): ядро мутирует глобальный реестр `PhysicalFonts`. `future.cancel(true)` при таймауте не останавливает FOP мгновенно — осознанный компромисс. - Ошибки (`ApiExceptionHandler`, тело `{"error": …}`): `ValidationException` → 400; `ConversionFailedException` → 500; `ConversionRejectedException` → 503; `ConversionTimeoutException` (`wordpdf.convert-timeout`, 2m) → 504; `MaxUploadSizeExceededException` → 413; `MissingServletRequestPartException`/`MissingServletRequestParameterException` → 400; `NoResourceFoundException` (неизвестный путь) → 404; catch-all → 500 (подробности только в лог). Четыре app-исключения (`ValidationException`, `ConversionFailedException`, `ConversionRejectedException`, `ConversionTimeoutException`) — package-private, несут семантику 400/500/503/504. Граница: сломанный контейнер (не zip / размер / страницы) → 400, валидный zip с мусором внутри → 500. Валидация до очереди: `checkInput` → zip-магик `PK\x03\x04` → `checkPageCountLightweight` (порядок значим). -- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). `/actuator/**` открыт (HEALTHCHECK). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Прод compose выключает springdoc env'ами — документация с валидным ключом даёт 404. +- **Ключ доступа**: `ApiKeyFilter` сверяет заголовок `X-API-Key` (`ApiKeyFilter.HEADER`) со свойством `wordpdf.api-key` (env `WORDPDF_API_KEY`, сравнение `MessageDigest.isEqual`). Пустое свойство = аутентификация выключена (dev `java -jar`, тесты). Без ключа открыты `/actuator/**` (HEALTHCHECK) и документация springdoc (`/swagger-ui*`, `/v3/api-docs*`) — матч по пути **без forwarded-contextPath** (`getRequestURI()` минус `getContextPath()`; иначе под `X-Forwarded-Prefix` HEALTHCHECK получил бы 401). 401 пишет сам фильтр (`ApiExceptionHandler` ошибок фильтров не видит). Springdoc в проде **включён**, документация открыта без ключа под `https://pjandro.ru/pdf-converter/swagger-ui.html` (server-URL/swagger-config собираются из `X-Forwarded-*`, `server.forward-headers-strategy=framework` — `native`-клапан Tomcat `X-Forwarded-Prefix` не понимает). Регрессии — `ApiKeyFilterTest#forwardedPrefix_healthStaysOpen`, `ApiKeyFilterTest#docsOpenWithoutKey`. - Лимиты входа задаёт **только конфигурация сервера**: `wordpdf.max-bytes`/`wordpdf.max-pages` (env `WORDPDF_MAX_BYTES`/`WORDPDF_MAX_PAGES`), `@Value` в `ConvertController` с дефолтом-SpEL из `WordPdfSettings` (20 MiB / 1000); значение ≤ 0 → `IllegalStateException` на старте; параметрами запроса не переопределяются. Ключи в `application.properties` **не объявлены** — пустое значение затенит SpEL-дефолт. - SPA: вся сеть в `src/api.ts` (компоненты `fetch` не вызывают); ключ в `localStorage` (`wordpdf.api.key`), при 401 очищается, экран `ApiKeyGate` (`UnauthorizedError` — наследник `ApiError`, проверяется раньше); запросы на `${import.meta.env.BASE_URL}api/...` (vite `base` из `VITE_BASE`, дефолт `/`) — CORS не нужен (dev: vite-proxy → :8080; prod: nginx с префиксом `/pdf-converter/`). @@ -53,7 +53,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр |`…/wordpdf/internal/chart/`|11 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)| |`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar| |`wordpdf-core/src/test/resources/samples/`|11 закоммиченных `.docx`-фикстур (единственные фикстуры)| -|`wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/`|REST API (9 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter` + 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)| |корневые `Dockerfile`, `docker-compose.yml`, `docker-compose.dev.yml`, `gateway/nginx.conf`|образ бэкенда (multi-stage maven:3.9-temurin-21 → temurin-21-jre, non-root, HEALTHCHECK actuator); compose app+web+gateway: web-образ со своим HEALTHCHECK (`wget /`), в обоих compose `depends_on web: condition: service_healthy` (без health web gateway не стартует); прод-compose интерполирует `WORDPDF_MAX_BYTES:-20971520`/`WORDPDF_MAX_PAGES:-1000`| |корневой `.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`, вне репо)| @@ -81,7 +81,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples ``` -Деплой. **Прод** — на пользовательском LAN-сервере; координаты сервера, каталог, 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` — рабочее дерево на сборку не влияет. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит `proxy_read_timeout 300s` — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). **Dev-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, `127.0.0.1:9011:80`, без env → ключ пуст, springdoc вкл). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Dockerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. +Деплой. **Прод** — на пользовательском LAN-сервере; координаты сервера, каталог, 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` — рабочее дерево на сборку не влияет. Наружный вход `https://pjandro.ru/pdf-converter/` (префикс срезает наружный nginx прод-хоста, не репозиторный gateway-конф; прод-копия gateway-конфа дополнительно содержит `proxy_read_timeout 300s` — в репо её нет, дефолтные 60s рвут 2-минутные конвертации). Тот же наружный 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-стенд** — из репо `docker-compose.dev.yml` (проект `wordpdf-dev`, `127.0.0.1:9011:80`, без env → ключ пуст, springdoc вкл). Репозиторный `docker-compose.yml` — третий вариант (проект `wordpdf`, `9010:80` на все интерфейсы, `WORDPDF_API_KEY` fail-closed без `.env` — `up` упадёт, `VITE_BASE` — build-arg `wordpdf-web/Dockerfile` — репо-compose НЕ передаёт: `compose build` без arg даёт base `/` и битые ассеты под префиксом, прод передаёт arg по DEPLOY.md). Запуск по просьбе пользователя = прод-стек; dev/`java -jar`/`npm run dev` — внутренняя отладка. ## Code Conventions & Common Patterns @@ -97,7 +97,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java` — точка входа библиотеки + static-блок `gsubFeatures`. - `wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfSettings.java` — все дефолты ядра (`MAX_INPUT_BYTES` 20 MiB, `MAX_PAGES` 1000, `RENDER_CHARTS/SMARTART`); рантайм-конфигурации в ядре нет. -- `wordpdf-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`; `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-bytes`/`max-pages` здесь намеренно нет. - `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен Docker 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). - Корневой `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`. @@ -117,11 +117,11 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ ## Testing & QA -- 14 тестовых классов / 124 `@Test` (core 11/104, app 3/20). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). +- 14 тестовых классов / 126 `@Test` (core 11/104, app 3/22). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). - Фикстуры — закоммиченные `samples/*.docx` (11; в тестах не генерировать): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject). - Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame` покрыт тестами только у zip-нормализаторов `DocxOnOff`/`SymbolFont`/`StrictOoxml`; у `Field`/`GlyphCoverage` — `rewrite`→`null`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `pageCountOf`, `ChartSpec.readTitle`). - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest` (`@TestPropertySource` с лимитами — отдельный класс, не `@Nested`). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCountLightweight_agreesWithJaxbPath` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal). +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight` — lightweight против strict), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCountLightweight_agreesWithJaxbPath` 99/100/101, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `ChartSpecTest`↔автозаголовки, chart-пейнтеры↔`chartsSmartArt_drawingsBecomeImages` (+`drawingToggles_offRemovesRasters`/`drawingToggles_chartsOffSmartArtOn`); `noLoggingWarningInPdf` — регрессия `slf4j-simple`, `pdfTitle_comesFromParameter` — регрессия PDF-title (юнит-партнёра нет). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed` (гонка реестра `PhysicalFonts`), `corruptNotAZip_rejected`, `junkInsideValidZip_conversionError`, `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `renderFlagsOff_convertsWithoutDrawings`, `cyrillicAndPathInFilename_sanitizedResponseName` (RFC 5987 + path-traversal), `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey` (открытая документация + матч фильтра без forwarded-contextPath). - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). diff --git a/wordpdf-app/pom.xml b/wordpdf-app/pom.xml index 893883b..48172fb 100644 --- a/wordpdf-app/pom.xml +++ b/wordpdf-app/pom.xml @@ -41,7 +41,7 @@ springdoc-openapi-starter-webmvc-ui - + org.springframework.boot spring-boot-starter-actuator diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java index 743abd9..1f9a9f2 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ApiKeyFilter.java @@ -15,17 +15,24 @@ import java.security.MessageDigest; /** * Единственная граница доступа: заголовок {@value #HEADER} обязан совпадать с * {@code wordpdf.api-key}. Пустое свойство = фильтрация выключена (dev/тесты). - * {@code /actuator/**} открыт — им дышит Docker HEALTHCHECK. Ответ 401 пишется - * здесь же, {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела — + * Наружу без ключа открыты {@code /actuator/**} (им дышит Docker HEALTHCHECK) + * и документация springdoc ({@code /swagger-ui*}, {@code /v3/api-docs*}) — + * браузер не может положить ключ в заголовок при загрузке UI; ключ обязателен + * для всего остального (фактически {@code /api/**}). Ответ 401 пишется здесь же, + * {@link ApiExceptionHandler} ошибок фильтров не видит; форма тела — * та же {@code {"error": …}}. * - *

Регрессия — ApiKeyFilterTest.

+ *

Регрессии — ApiKeyFilterTest#forwardedPrefix_healthStaysOpen, + * ApiKeyFilterTest#docsOpenWithoutKey.

*/ @Component final class ApiKeyFilter extends OncePerRequestFilter { static final String HEADER = "X-API-Key"; + /** Открытые пути без ключа: actuator (Docker HEALTHCHECK) и springdoc-документация. */ + private static final String[] OPEN_PREFIXES = {"/actuator/", "/swagger-ui", "/v3/api-docs"}; + /** null — аутентификация выключена. */ private final byte[] expected; @@ -37,7 +44,7 @@ final class ApiKeyFilter extends OncePerRequestFilter { @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { - if (expected == null || request.getRequestURI().startsWith("/actuator/")) { + if (expected == null || isOpen(path(request))) { chain.doFilter(request, response); return; } @@ -54,4 +61,23 @@ final class ApiKeyFilter extends OncePerRequestFilter { response.getWriter().write( "{\"error\":\"Ключ доступа не передан или неверен (заголовок X-API-Key)\"}"); } + + /** + * Путь приложения без forwarded-префикса: при + * server.forward-headers-strategy=framework заголовок X-Forwarded-Prefix + * становится contextPath, и getRequestURI() возвращает URI уже с ним — + * матч по сырому URI теряет /actuator/ (Docker HEALTHCHECK получил бы 401). + */ + private static String path(HttpServletRequest request) { + return request.getRequestURI().substring(request.getContextPath().length()); + } + + private static boolean isOpen(String path) { + for (String prefix : OPEN_PREFIXES) { + if (path.startsWith(prefix)) { + return true; + } + } + return false; + } } diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java index c21bb8d..8bff5ae 100644 --- a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/ConvertController.java @@ -1,6 +1,7 @@ package ru.pjandro.wordpdf.app; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.security.SecurityRequirement; import org.springframework.http.ContentDisposition; import org.springframework.http.HttpHeaders; import org.springframework.http.MediaType; @@ -60,6 +61,7 @@ final class ConvertController { description = "renderCharts/renderSmartArt — факультативно, по умолчанию настройки ядра; " + "лимиты входа (размер/страницы) задаёт только конфигурация сервера " + "(свойства wordpdf.max-bytes/wordpdf.max-pages), параметрами запроса не переопределяются") + @SecurityRequirement(name = OpenApiConfig.SCHEME) @PostMapping( path = "/api/v1/convert", consumes = MediaType.MULTIPART_FORM_DATA_VALUE, diff --git a/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/OpenApiConfig.java b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/OpenApiConfig.java new file mode 100644 index 0000000..f4e219c --- /dev/null +++ b/wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/OpenApiConfig.java @@ -0,0 +1,22 @@ +package ru.pjandro.wordpdf.app; + +import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn; +import io.swagger.v3.oas.annotations.enums.SecuritySchemeType; +import io.swagger.v3.oas.annotations.security.SecurityScheme; +import org.springframework.context.annotation.Configuration; + +/** + * Схема доступа X-API-Key для springdoc: без неё Swagger UI не показывает + * Authorize и «Try it out» слал бы запросы без ключа (401). Документация + * наружу открыта (ApiKeyFilter), секрет — сам ключ, он в спеке не хранится. + */ +@Configuration(proxyBeanMethods = false) +@SecurityScheme( + name = OpenApiConfig.SCHEME, + type = SecuritySchemeType.APIKEY, + paramName = ApiKeyFilter.HEADER, + description = "Ключ доступа (свойство сервера wordpdf.api-key, прод — env WORDPDF_API_KEY)") +class OpenApiConfig { + + static final String SCHEME = "ApiKey"; +} diff --git a/wordpdf-app/src/main/resources/application.properties b/wordpdf-app/src/main/resources/application.properties index ccb5f1c..fa30cb6 100644 --- a/wordpdf-app/src/main/resources/application.properties +++ b/wordpdf-app/src/main/resources/application.properties @@ -17,3 +17,11 @@ wordpdf.convert-timeout=2m # Ключ доступа (заголовок X-API-Key). Пусто = аутентификация выключена # (dev: java -jar / тесты). В docker-compose задан ${WORDPDF_API_KEY:?} — fail-closed. wordpdf.api-key= + +# Работа за префикс-срезающим прокси (прод: наружный nginx срезает +# /pdf-converter/): ForwardedHeaderFilter восстанавливает схему/хост/префикс из +# X-Forwarded-*, springdoc генерирует swagger-config и server спека с префиксом. +# 'native' (клапан Tomcat) X-Forwarded-Prefix не понимает — только 'framework'. +server.forward-headers-strategy=framework +# Swagger UI: не требовать ключ заново после перезагрузки страницы +springdoc.swagger-ui.persist-authorization=true diff --git a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ApiKeyFilterTest.java b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ApiKeyFilterTest.java index a6ce102..3f03e41 100644 --- a/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ApiKeyFilterTest.java +++ b/wordpdf-app/src/test/java/ru/pjandro/wordpdf/app/ApiKeyFilterTest.java @@ -88,10 +88,28 @@ class ApiKeyFilterTest { } @Test - void openApiRequiresKey() throws Exception { - // в тестах springdoc включён; в проде выключен env'ом — фильтр - // накрывает документацию, когда она активна + void docsOpenWithoutKey() throws Exception { + // документация наружу открыта без ключа (браузер не может положить + // ключ в заголовок при загрузке UI); в тестах springdoc включён mockMvc.perform(get("/v3/api-docs")) - .andExpect(status().isUnauthorized()); + .andExpect(status().isOk()) + .andExpect(jsonPath("$.components.securitySchemes.ApiKey.type").value("apiKey")) + .andExpect(jsonPath("$.components.securitySchemes.ApiKey.name").value("X-API-Key")); + mockMvc.perform(get("/swagger-ui/index.html")) + .andExpect(status().isOk()); + } + + @Test + void forwardedPrefix_healthStaysOpen() throws Exception { + // X-Forwarded-Prefix переезжает в contextPath, getRequestURI() — с префиксом; + // без отсечения contextPath в фильтре HEALTHCHECK получил бы 401 + mockMvc.perform(get("/actuator/health").header("X-Forwarded-Prefix", "/pdf-converter")) + .andExpect(status().isOk()); + } + + @Test + void forwardedPrefix_docsOpenWithoutKey() throws Exception { + mockMvc.perform(get("/v3/api-docs").header("X-Forwarded-Prefix", "/pdf-converter")) + .andExpect(status().isOk()); } }