docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,52 @@
|
||||
# Аутентификация
|
||||
|
||||
## Ключ доступа
|
||||
|
||||
Все запросы, кроме открытых путей, требуют заголовок:
|
||||
|
||||
```
|
||||
X-API-Key: <ключ>
|
||||
```
|
||||
|
||||
Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`).
|
||||
Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство =
|
||||
аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011).
|
||||
|
||||
Без ключа или с неверным:
|
||||
|
||||
```
|
||||
HTTP 401
|
||||
{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}
|
||||
```
|
||||
|
||||
## Открытые пути
|
||||
|
||||
Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта
|
||||
forwarded-contextPath):
|
||||
|
||||
|Префикс|Что|
|
||||
|---|---|
|
||||
|`/actuator/`|health-checks Spring Boot|
|
||||
|`/swagger-ui`|Swagger UI|
|
||||
|`/v3/api-docs`|OpenAPI-спек|
|
||||
|
||||
!!! warning "Точечные сегменты обходят открытие"
|
||||
Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются
|
||||
открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на
|
||||
открытом префиксе. Это защита от обхода фильтра через нормализацию пути.
|
||||
|
||||
## Где задаётся ключ
|
||||
|
||||
|Среда|Как|
|
||||
|---|---|
|
||||
|`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`|
|
||||
|prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`|
|
||||
|прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)|
|
||||
|
||||
Сгенерировать ключ: `openssl rand -hex 32`.
|
||||
|
||||
## Как фронтенд узнаёт про ключ
|
||||
|
||||
SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 —
|
||||
сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу.
|
||||
Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Эндпоинт конвертации
|
||||
|
||||
```
|
||||
POST /api/v1/convert
|
||||
```
|
||||
|
||||
Тело запроса — `multipart/form-data` с обязательным полем **`file`**: файл `.docx`
|
||||
(OOXML) или `.doc` (Word 97–2003, переносится мостом в .docx в памяти). Файлы других
|
||||
расширений отклоняются 400.
|
||||
|
||||
## Факультативные query/form-параметры
|
||||
|
||||
Параметры можно передать в query-строке или как form-поля.
|
||||
|
||||
|Параметр|Тип|Дефолт|Действие|
|
||||
|---|---|---|---|
|
||||
|`errorOnCharts`|Boolean|`false`|при `true` диаграммы в документе отменяют конвертацию (422); диаграммы конвертируются в растры всегда|
|
||||
|`errorOnSmartArt`|Boolean|`false`|при `true` SmartArt отменяет конвертацию (422)|
|
||||
|`errorOnOle`|Boolean|`false`|при `true` OLE-объекты отменяют конвертацию (422); при `false` OLE-объекты тихо удаляются, картинка-плейсхолдер сохраняется|
|
||||
|`maxMb`|число|свойство сервера `wordpdf.max-mb` (5)|лимит размера входа в МБ; переопределяет серверный дефолт **в обе стороны**; `≤ 0` → 400|
|
||||
|`maxPages`|число|свойство сервера `wordpdf.max-pages` (100)|лимит числа страниц; переопределяет в обе стороны; `≤ 0` → 400|
|
||||
|
||||
!!! note "На `.doc` error-флаги не срабатывают"
|
||||
Плейсхолдеры диаграмм/SmartArt/OLE в бинарном формате — это BLIP-растры, мост
|
||||
вставляет их картинками; векторные EMF/WMF/PICT пропускаются с warn. Флаги
|
||||
работают только для `.docx`.
|
||||
|
||||
## Успешный ответ
|
||||
|
||||
```
|
||||
HTTP 200
|
||||
Content-Type: application/pdf
|
||||
Content-Disposition: attachment; filename*=UTF-8''Документ.pdf
|
||||
```
|
||||
|
||||
Имя файла берётся из `Content-Disposition` загруженного файла, санитизируется
|
||||
(разрешены буквы, цифры, пробел и `._-`; кириллица разрешена; пустое имя → `document`)
|
||||
и используется единожды для имени файла, заголовка ответа и заголовка PDF.
|
||||
|
||||
## Обработка
|
||||
|
||||
Задача ставится в однопоточную очередь воркеров (16 мест). Проверка размера —
|
||||
синхронно до очереди. Конвертация дольше `wordpdf.convert-timeout` (2m) → 504,
|
||||
очередь полна → 503. Полная таблица ответов — [Коды ошибок](errors.md),
|
||||
пороги — [Лимиты](limits.md).
|
||||
@@ -0,0 +1,55 @@
|
||||
# Коды ошибок
|
||||
|
||||
Ошибки — JSON вида `{"error": "..."}`.
|
||||
|
||||
## Полная таблица
|
||||
|
||||
|Код|Смысл|
|
||||
|---|---|
|
||||
|200|PDF в теле ответа|
|
||||
|400|некорректный вход (пустой / расширение не .docx/.doc / содержимое не zip и не CFB / зашифрованный .doc / больше лимита размера (`maxMb` или `wordpdf.max-mb`) / больше лимита страниц (`maxPages` или `wordpdf.max-pages`) / `maxMb`≤0 / `maxPages`≤0), отсутствующая часть `file`, некорректное значение error-флага|
|
||||
|401|нет или неверен `X-API-Key`|
|
||||
|404|неизвестный путь (в т.ч. `/v3/api-docs` при выключенном springdoc)|
|
||||
|405|не-POST|
|
||||
|413|тело запроса больше контейнерного лимита multipart (100 МБ; авторитетный лимит входа — `wordpdf.max-mb`, он даёт 400 раньше)|
|
||||
|415|не-multipart тело|
|
||||
|422|сработал error-флаг: в документе найдены диаграммы / SmartArt / OLE-объекты|
|
||||
|500|ошибка ядра/рендера|
|
||||
|503|очередь конвертации (16 мест) переполнена — повторить позже|
|
||||
|504|конвертация дольше `wordpdf.convert-timeout` (по умолчанию 2m)|
|
||||
|
||||
## Фиксированные тексты
|
||||
|
||||
Тексты ниже — контракт с фронтендом, они не меняются:
|
||||
|
||||
|Код|Тело|
|
||||
|---|---|
|
||||
|401|`{"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"}`|
|
||||
|404|`{"error":"Не найдено"}`|
|
||||
|405|`{"error":"Метод не поддерживается"}`|
|
||||
|415|`{"error":"Неподдерживаемый тип содержимого"}`|
|
||||
|422 (диаграммы)|`{"error":"Конвертация отменена: в документе найдены диаграммы"}`|
|
||||
|422 (SmartArt)|`{"error":"Конвертация отменена: в документе найден SmartArt"}`|
|
||||
|422 (OLE)|`{"error":"Конвертация отменена: в документе найдены OLE-объекты"}`|
|
||||
|500|`{"error":"Не удалось конвертировать документ"}`|
|
||||
|
||||
Другие 400-тексты параметризованы, например: `Файл не передан (multipart-поле «file»
|
||||
обязательно)`, `Поддерживаются только .docx и .doc: <имя>`, `Файл больше <N> МБ: …`,
|
||||
`Некорректное значение параметра «<имя>»`.
|
||||
|
||||
!!! info "500 — деталь только в лог"
|
||||
Сообщения ядра (`ConversionException` и др.) логируются на сервере, наружу
|
||||
всегда уходит фиксированный текст — внутренние детали не текут клиенту.
|
||||
|
||||
## Исключение → обработчик (для отладки)
|
||||
|
||||
|HTTP|Источник|
|
||||
|---|---|
|
||||
|400|`ValidationException`, `BadRequestException`, `MethodArgumentTypeMismatchException`, `MissingServletRequestPartException`|
|
||||
|401|`ApiKeyFilter` (пишет ответ сам, до диспетчера)|
|
||||
|404 / 405 / 415|`NoResourceFoundException` / `HttpRequestMethodNotSupportedException` / `HttpMediaTypeNotSupportedException`|
|
||||
|413|`MaxUploadSizeExceededException`|
|
||||
|422|`DrawingRejectedException`|
|
||||
|500|`ConversionFailedException`|
|
||||
|503|`ConversionRejectedException`|
|
||||
|504|`ConversionTimeoutException`|
|
||||
@@ -0,0 +1,74 @@
|
||||
# Примеры клиентов
|
||||
|
||||
Базовый адрес зависит от стенда: прод `https://pjandro.ru/pdf-converter/api/v1/convert`,
|
||||
prod-like локально `http://localhost:9010/api/v1/convert`, dev `http://<LAN-IP>:9011/api/v1/convert`,
|
||||
`java -jar` — `http://localhost:8080/api/v1/convert`.
|
||||
|
||||
## curl
|
||||
|
||||
Без ключа (сервер с выключенной аутентификацией):
|
||||
|
||||
```bash
|
||||
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||
```
|
||||
|
||||
С ключом и error-флагом:
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $WORDPDF_API_KEY" \
|
||||
-F "file=@Отчёт.docx" \
|
||||
"https://pjandro.ru/pdf-converter/api/v1/convert?errorOnOle=true&maxMb=10" \
|
||||
-o out.pdf
|
||||
```
|
||||
|
||||
## JavaScript (fetch)
|
||||
|
||||
```js
|
||||
const form = new FormData();
|
||||
form.append("file", fileInput.files[0], fileInput.files[0].name);
|
||||
|
||||
const resp = await fetch("/api/v1/convert", {
|
||||
method: "POST",
|
||||
headers: apiKey ? { "X-API-Key": apiKey } : {},
|
||||
body: form,
|
||||
});
|
||||
|
||||
if (!resp.ok) {
|
||||
const { error } = await resp.json().catch(() => ({ error: resp.statusText }));
|
||||
throw new Error(error);
|
||||
}
|
||||
|
||||
// имя файла из Content-Disposition: attachment; filename*=UTF-8''%D0%9E%D1%82%D1%87%D1%91%D1%82.pdf
|
||||
const cd = resp.headers.get("Content-Disposition") ?? "";
|
||||
const m = cd.match(/filename\*=UTF-8''([^;]+)/i);
|
||||
const name = m ? decodeURIComponent(m[1]) : "document.pdf";
|
||||
|
||||
const blobUrl = URL.createObjectURL(await resp.blob());
|
||||
const a = Object.assign(document.createElement("a"), { href: blobUrl, download: name });
|
||||
a.click();
|
||||
URL.revokeObjectURL(blobUrl);
|
||||
```
|
||||
|
||||
Обработка 401 — стереть сохранённый ключ и показать экран ввода; 422 — показать
|
||||
`error` из тела (документ содержит диаграммы/SmartArt/OLE).
|
||||
|
||||
## Python (requests)
|
||||
|
||||
Таймаут обязан быть больше серверных 2 минут на чтение:
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
resp = requests.post(
|
||||
"https://pjandro.ru/pdf-converter/api/v1/convert",
|
||||
headers={"X-API-Key": API_KEY} if API_KEY else {},
|
||||
files={"file": open("doc.docx", "rb")},
|
||||
params={"errorOnCharts": "false"},
|
||||
timeout=(10, 180), # connect 10 c, read 180 c — больше серверных 2m
|
||||
)
|
||||
resp.raise_for_status()
|
||||
with open("doc.pdf", "wb") as f:
|
||||
f.write(resp.content)
|
||||
```
|
||||
|
||||
Так же устроены прод-автотесты репозитория (`prod-autotests/`, pytest + requests).
|
||||
@@ -0,0 +1,53 @@
|
||||
# REST API
|
||||
|
||||
Базовый путь — корень сервера; единственный эндпоинт:
|
||||
|
||||
```
|
||||
POST /api/v1/convert
|
||||
```
|
||||
|
||||
Quickstart — конвертировать документ и сохранить PDF (ключ доступа, если сервер его
|
||||
требует, — в заголовке `X-API-Key`):
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $WORDPDF_API_KEY" -F "file=@doc.docx" \
|
||||
https://pjandro.ru/pdf-converter/api/v1/convert -o doc.pdf
|
||||
```
|
||||
|
||||
Локальный бэкенд (`java -jar`, порт 8080, ключ выключен):
|
||||
|
||||
```bash
|
||||
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
|
||||
curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf
|
||||
```
|
||||
|
||||
Успешный ответ — `200`, тело — байты PDF (`Content-Type: application/pdf`,
|
||||
`Content-Disposition: attachment; filename*=UTF-8''…`).
|
||||
|
||||
## Документация в самом сервисе
|
||||
|
||||
|Что|Путь|Когда доступно|
|
||||
|---|---|---|
|
||||
|Swagger UI|`/swagger-ui.html`|пока включён springdoc|
|
||||
|OpenAPI (JSON)|`/v3/api-docs`|пока включён springdoc|
|
||||
|
||||
На `java -jar` и dev-стенде (:9011) springdoc включён; на проде он также открыт
|
||||
(проверяется автотестом `test_swagger_ui_open_without_key`). В локальном prod-like
|
||||
compose-стеке springdoc выключен env-ами `SPRINGDOC_API_DOCS_ENABLED=false` и
|
||||
`SPRINGDOC_SWAGGER_UI_ENABLED=false` (в этом случае `/v3/api-docs` отвечает 404).
|
||||
|
||||
## Разделы
|
||||
|
||||
- [Аутентификация](authentication.md) — ключ `X-API-Key`.
|
||||
- [Эндпоинт конвертации](convert-endpoint.md) — параметры и ответ.
|
||||
- [Коды ошибок](errors.md) — полная таблица и тексты.
|
||||
- [Лимиты](limits.md) — размер, страницы, очередь, таймаут.
|
||||
- [Примеры клиентов](examples.md) — curl, JavaScript, Python.
|
||||
|
||||
## Как устроена обработка
|
||||
|
||||
Конвертации сериализуются **одним воркером**: ядро мутирует глобальный реестр шрифтов,
|
||||
поэтому все конвертации идут последовательно (очередь — 16 мест, переполнение → 503).
|
||||
Головой очереди на старте стоит `warmup()` — прогрев ядра (~1,5–2,5 с), чтобы первый
|
||||
запрос после деплоя не платил за инициализацию JAXB/XSLT/FOP. Проверка размера входа
|
||||
выполняется синхронно, до постановки в очередь.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Лимиты
|
||||
|
||||
## Лимиты входа
|
||||
|
||||
|Свойство|Env|Дефолт|Смысл|
|
||||
|---|---|---|---|
|
||||
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5|максимальный размер файла в МБ (MiB)|
|
||||
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100|максимальное число страниц|
|
||||
|
||||
Это **дефолт эндпоинта**: параметры запроса `maxMb`/`maxPages` переопределяют его
|
||||
в обе стороны (значения `≤ 0` → 400; верхнего серверного потолка нет — защитные
|
||||
пороги растут вместе с лимитами). Значение свойства сервера `≤ 0` — падение
|
||||
приложения на старте (`IllegalStateException`).
|
||||
|
||||
## Производные защитные пороги
|
||||
|
||||
Остальные пороги выводятся из лимитов входа (`WordPdfValidator`), проверяются
|
||||
до рендера, одним lightweight-сканом:
|
||||
|
||||
- распакованный размер архива;
|
||||
- суммарный распакованный размер XML-частей;
|
||||
- число записей zip и защита от дубликатов записей;
|
||||
- площади растровых изображений (пиксели);
|
||||
- размер `[Content_Types].xml` (жёсткие 8 МБ).
|
||||
|
||||
Превышение любого — `400` (в библиотеке — `ValidationException`).
|
||||
|
||||
## Потолок инфраструктуры — 100 МБ
|
||||
|
||||
`spring.servlet.multipart.max-file-size`/`max-request-size` = 100MB — потолок
|
||||
контейнера, зеркалит `client_max_body_size 100m` nginx-шлюза. Тело больше — 413.
|
||||
Логический лимит входа (`wordpdf.max-mb`, дефолт 5 МБ) отсекает раньше и даёт 400;
|
||||
413 возможен только когда серверный лимит поднят администратором выше дефолта.
|
||||
|
||||
Части загрузки больше 2 МБ (`file-size-threshold=2MB`) сбрасываются на диск Tomcat —
|
||||
heap держит только копию байтов одной сериализованной конвертации.
|
||||
|
||||
## Очередь и таймаут
|
||||
|
||||
|Параметр|Значение|Поведение|
|
||||
|---|---|---|
|
||||
|ёмкость очереди|16 мест|переполнение → **503** (повторить позже)|
|
||||
|`wordpdf.convert-timeout`|`2m` (env `WORDPDF_CONVERT_TIMEOUT`)|конвертация дольше → **504** (задача отменяется)|
|
||||
|
||||
Конвертации исполняются строго последовательно одним воркером (ядро мутирует
|
||||
глобальный реестр шрифтов); при таймауте `future.cancel(true)` не останавливает FOP
|
||||
мгновенно — текущая конвертация дожигается, следующий запрос ждёт её в очереди.
|
||||
Reference in New Issue
Block a user