From 2750486c91bdc69be9de8f14f8c92750cb8eafea Mon Sep 17 00:00:00 2001 From: Pjandro Date: Fri, 16 Oct 2026 22:11:53 +0000 Subject: [PATCH] =?UTF-8?q?dev-=D1=81=D1=82=D0=B5=D0=BD=D0=B4:=200.0.0.0:9?= =?UTF-8?q?011,=20vite=20host:true,=20=D0=B3=D0=B5=D0=B9=D1=82=20=D0=BA?= =?UTF-8?q?=D0=BB=D1=8E=D1=87=D0=B0=20=D1=82=D0=BE=D0=BB=D1=8C=D0=BA=D0=BE?= =?UTF-8?q?=20=D0=BF=D0=BE=20401-=D0=B7=D0=BE=D0=BD=D0=B4=D1=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docker-compose.dev.yml: ports 127.0.0.1:9011:80 → 9011:80 (вход по LAN-IP хоста) - vite.config.ts: server.host=true — dev-сервер тоже на все интерфейсы - api.ts: probeApiKey() — GET /api/v1/convert (POST-only эндпоинт): 401 от ApiKeyFilter ⟺ сервер требует ключ; при выключенной аутентификации не 401 - App.tsx: экран ApiKeyGate показывается только когда зонд вернул 'required'; 401 на конвертации возвращает к гейту (setGate('required')) - AGENTS.md: обновлены поведенческие строки (dev-вход, контракт гейта) --- AGENTS.md | 6 +++--- docker-compose.dev.yml | 4 ++-- wordpdf-web/src/api.ts | 22 ++++++++++++++++++++++ wordpdf-web/src/components/App.tsx | 24 ++++++++++++++++++------ wordpdf-web/vite.config.ts | 2 ++ 5 files changed, 47 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4e52d21..3b0fe11 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ - Ошибки (`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) и документация 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/`). +- 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`) @@ -70,7 +70,7 @@ mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotC mvn -pl wordpdf-app -am test -Dtest=ConvertControllerTest#convertSample_returnsPdf # -am обязателен (test-jar core) npm run dev # (wordpdf-web/) SPA :5173, vite-proxy /api → :8080 npm run build # (wordpdf-web/) tsc -b && vite build — гейт SPA; lint: npm run lint (oxlint) -docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: http://127.0.0.1:9011, без ключа, springdoc вкл +docker compose -f docker-compose.dev.yml up -d --build # dev-стенд: http://:9011 (0.0.0.0), без ключа, springdoc вкл ``` Пересоздать 10 фикстур (POI, test scope; `charts-smartart.docx` НЕ генерируется — создана вручную, не перезаписывать): @@ -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-минутные конвертации). Тот же наружный 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` — внутренняя отладка. +Деплой. **Прод** — на пользовательском 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`, `9011:80` на все интерфейсы — вход по LAN-IP хоста, без 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 diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 674078e..3c1208f 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -2,7 +2,7 @@ # → ApiKeyFilter прозрачен, springdoc включён. Проект wordpdf-dev — собственные # образы/контейнеры, с прод-запуском (wordpdf-prod, :9010) не конфликтует. # Запуск: docker compose -f docker-compose.dev.yml up --build -# Вход: http://127.0.0.1:9011 +# Вход: http://:9011 (доступен из локальной сети; hostname -I на хосте) name: wordpdf-dev services: app: @@ -15,7 +15,7 @@ services: image: nginx:alpine volumes: - ./gateway/nginx.conf:/etc/nginx/conf.d/default.conf:ro - ports: ["127.0.0.1:9011:80"] + ports: ["9011:80"] depends_on: app: condition: service_healthy diff --git a/wordpdf-web/src/api.ts b/wordpdf-web/src/api.ts index f4097ce..710e932 100644 --- a/wordpdf-web/src/api.ts +++ b/wordpdf-web/src/api.ts @@ -70,3 +70,25 @@ export async function convertDocx( const blob = await resp.blob() return { blob, filename } } + +/** + * Требует ли сервер ключ: GET /api/v1/convert (эндпоинт POST-only) — + * 401 пишет ApiKeyFilter при требуемом и непринятом ключе; при выключенной + * аутентификации (dev) до фильтра дело не доходит — 405 от Spring. + * Сетевая ошибка — 'open': не блокировать UI, конвертация сама покажет ошибку. + */ +export async function probeApiKey(): Promise<'open' | 'required'> { + const key = getApiKey() + try { + const resp = await fetch(`${import.meta.env.BASE_URL}api/v1/convert`, { + headers: key ? { 'X-API-Key': key } : undefined, + }) + if (resp.status === 401) { + clearApiKey() // ключ устарел/отозван — форма откроется пустой + return 'required' + } + return 'open' + } catch { + return 'open' + } +} diff --git a/wordpdf-web/src/components/App.tsx b/wordpdf-web/src/components/App.tsx index 688061e..b22318c 100644 --- a/wordpdf-web/src/components/App.tsx +++ b/wordpdf-web/src/components/App.tsx @@ -1,5 +1,5 @@ import { useEffect, useRef, useState } from 'react' -import { ApiError, convertDocx, getApiKey, setApiKey, UnauthorizedError } from '../api' +import { ApiError, convertDocx, probeApiKey, setApiKey, UnauthorizedError } from '../api' import ApiKeyGate from './ApiKeyGate' import DropZone from './DropZone' import Logo from './Logo' @@ -47,8 +47,11 @@ export default function App() { if (on) setRenderSmartArt(false) } - // ключ в localStorage: публичная статика, в бандл зашивать нельзя - const [apiKey, setApiKeyValue] = useState(() => getApiKey()) + // экран ключа показываем только когда сервер реально требует ключ: зонд + // probeApiKey (GET /api/v1/convert → 401) решает до загрузки файла; в dev + // без ключа форма открывается сразу. Ключ лежит в localStorage (публичная + // статика, в бандл зашивать нельзя), читает его api.ts сам. + const [gate, setGate] = useState<'checking' | 'open' | 'required'>('checking') const [keyError, setKeyError] = useState(null) // снимаем blob-URL предыдущего результата — иначе он течёт до закрытия вкладки @@ -90,7 +93,7 @@ export default function App() { // UnauthorizedError раньше ApiError: он её наследник; ключ уже // очищен в api.ts — форма откроется пустой if (e instanceof UnauthorizedError) { - setApiKeyValue(null) + setGate('required') setKeyError('Ключ доступа не принят — введите заново') setStatus('idle') return @@ -112,13 +115,22 @@ export default function App() { [], ) - if (!apiKey) + useEffect(() => { + probeApiKey().then(setGate) + }, []) + + // зонд — один быстрый same-origin запрос, спиннер не вводим + if (gate === 'checking') return null + + if (gate === 'required') return ( { setApiKey(k) - setApiKeyValue(k) + // повторный зонд не шлём: неверный ключ всплывёт 401 на первой + // конвертации (текущий контракт гейта) + setGate('open') setKeyError(null) // возврат после отзыва ключа не должен показать «Конвертация…»/старый результат setStatus('idle') diff --git a/wordpdf-web/vite.config.ts b/wordpdf-web/vite.config.ts index 1ba9a69..de6a198 100644 --- a/wordpdf-web/vite.config.ts +++ b/wordpdf-web/vite.config.ts @@ -9,6 +9,8 @@ export default defineConfig({ base: process.env.VITE_BASE ?? '/', plugins: [react(), tailwindcss()], server: { + // dev-сервер наружу: слушает все интерфейсы (LAN-доступ к стенду с других машин) + host: true, // dev без CORS: запросы /api и документация (/swagger-ui*, /v3/api-docs*) идут на бэкенд через прокси proxy: { '/api': 'http://localhost:8080',