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

- WordPdfSettings удалён; ConvertOptions.defaults() удалён; 2-аргументный
  convert и безлимитные оверлоды валидатора сняты (options == null → 400)
- производные пороги (распаковка total/XML, пиксели растра, zip-записи)
  считаются из maxMb/maxPages формулами в WordPdfConverter/WordPdfValidator
- мост: DocToDocx.convert(+maxMb) → OfficeArt.read(+maxPixels)
- REST: свойства wordpdf.max-mb/max-pages — дефолт эндпоинта (литералы
  @Value 5/100), параметры запроса maxMb/maxPages переопределяют в обе
  стороны (≤ 0 → 400); верхний потолок отсутствует (решение пользователя)
- HTTP-контексты тестов пиныт wordpdf.api-key= (mise подмешивает .env)
- доки/README/autotests-формулировки синхронизированы
This commit is contained in:
Pjandro
2026-11-08 20:16:52 +00:00
parent 8a8e8a9f84
commit af5d09e001
23 changed files with 375 additions and 362 deletions
@@ -12,7 +12,6 @@ import org.springframework.web.bind.annotation.RestController;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.multipart.MultipartFile;
import ru.pjandro.wordpdf.ConvertOptions;
import ru.pjandro.wordpdf.WordPdfSettings;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
@@ -25,10 +24,11 @@ import java.util.Locale;
* <p>Здесь только HTTP-слой: проверка presence/расширения и формирование
* {@code Content-Disposition}; проверка содержимого (zip, размер, страницы) —
* зона {@link ConversionService}. Ошибки в JSON-ответ переводит
* {@link ApiExceptionHandler}. Лимиты входа — только конфигурация сервера
* (свойства {@code wordpdf.max-mb}/{@code wordpdf.max-pages}, env
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}); параметрами запроса
* они не переопределяются.</p>
* {@link ApiExceptionHandler}. Лимиты входа: свойства
* {@code wordpdf.max-mb}/{@code wordpdf.max-pages} (env
* {@code WORDPDF_MAX_MB}/{@code WORDPDF_MAX_PAGES}) — дефолт эндпоинта;
* параметры запроса {@code maxMb}/{@code maxPages} переопределяют его в обе
* стороны (значения ≤ 0 → 400).</p>
*/
@RestController
final class ConvertController {
@@ -38,14 +38,15 @@ final class ConvertController {
private final int maxPages;
/**
* Дефолт плейсхолдеров — константы ядра через SpEL: буквальное значение
* в свойствах не дублируется. Невалидное значение (<= 0) роняет
* Дефолт плейсхолдеров — буквенные литералы 5/100 (дефолтов лимитов в
* ядре нет); свойства/env переопределяют их, параметры запроса — см.
* {@link #convert}. Невалидное значение свойства (<= 0) роняет
* приложение на старте (fail-fast): «сервис поднят, но весь вход
* отсекается» — худший исход, чем не поднявшийся сервис.
*/
ConvertController(ConversionService conversionService,
@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-mb:5}") long maxMb,
@Value("${wordpdf.max-pages:100}") int maxPages) {
if (maxMb <= 0) {
throw new IllegalStateException("wordpdf.max-mb должен быть больше 0: " + maxMb);
}
@@ -60,10 +61,11 @@ final class ConvertController {
@Operation(summary = "Конвертировать .docx/.doc в PDF",
description = "Принимаются .docx (OOXML) и .doc (Word 97–2003, переносится в .docx "
+ "мостом: текст и прямое форматирование). errorOnCharts/errorOnSmartArt/errorOnOle — факультативно, по умолчанию "
+ "настройки ядра (ошибка не выбрасывается); диаграммы/SmartArt "
+ "ошибка не выбрасывается; диаграммы/SmartArt "
+ "конвертируются всегда, OLE-объекты при выключенном флаге тихо удаляются. "
+ "Лимиты входа (размер/страницы) задаёт только конфигурация сервера "
+ "(свойства wordpdf.max-mb/wordpdf.max-pages), параметрами запроса не переопределяются")
+ "Лимиты входа (размер/страницы): свойства wordpdf.max-mb/wordpdf.max-pages — "
+ "дефолт; параметры запроса maxMb/maxPages переопределяют его в обе стороны "
+ "(значения ≤ 0 → 400)")
@SecurityRequirement(name = OpenApiConfig.SCHEME)
@PostMapping(
path = "/api/v1/convert",
@@ -73,7 +75,9 @@ final class ConvertController {
@RequestParam("file") MultipartFile file,
@RequestParam(name = "errorOnCharts", required = false) Boolean errorOnCharts,
@RequestParam(name = "errorOnSmartArt", required = false) Boolean errorOnSmartArt,
@RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle) {
@RequestParam(name = "errorOnOle", required = false) Boolean errorOnOle,
@RequestParam(name = "maxMb", required = false) Long maxMbParam,
@RequestParam(name = "maxPages", required = false) Integer maxPagesParam) {
if (file == null || file.isEmpty()) {
throw new BadRequestException("Файл не передан (multipart-поле «file» обязательно)");
}
@@ -84,13 +88,24 @@ final class ConvertController {
// .doc (Word 97–2003) переносится в .docx мостом internal.doc
throw new BadRequestException("Поддерживаются только .docx и .doc: " + name);
}
// Лимиты входа: свойства сервера — дефолт, параметры запроса
// переопределяют в обе стороны (верхнего потолка нет — осознанное
// решение; остаточная защита от загрузки — multipart-лимит сервера).
if (maxMbParam != null && maxMbParam <= 0) {
throw new BadRequestException("maxMb должен быть больше 0: " + maxMbParam);
}
if (maxPagesParam != null && maxPagesParam <= 0) {
throw new BadRequestException("maxPages должен быть больше 0: " + maxPagesParam);
}
long effMaxMb = maxMbParam != null ? maxMbParam : maxMb;
int effMaxPages = maxPagesParam != null ? maxPagesParam : maxPages;
// Размер проверяется до getBytes(): multipart-лимит сервера (100 МБ)
// больше логического лимита входа (wordpdf.max-mb), и без этого гварда
// заведомо oversized-upload сначала материализовался бы в куче.
// больше логического лимита входа, и без этого гварда заведомо
// oversized-upload сначала материализовался бы в куче.
// Текст — тот же формат, что WordPdfValidator.checkInput.
long maxBytes = maxMb * 1024 * 1024;
long maxBytes = effMaxMb * 1024 * 1024;
if (file.getSize() > maxBytes) {
throw new BadRequestException("Файл больше " + maxMb + " МБ: "
throw new BadRequestException("Файл больше " + effMaxMb + " МБ: "
+ file.getSize() + " байт > " + maxBytes + " байт");
}
byte[] docxBytes;
@@ -100,10 +115,10 @@ final class ConvertController {
throw new BadRequestException("Не удалось прочитать загруженный файл", e);
}
ConvertOptions options = new ConvertOptions(
errorOnCharts != null ? errorOnCharts : WordPdfSettings.ERROR_ON_CHARTS,
errorOnSmartArt != null ? errorOnSmartArt : WordPdfSettings.ERROR_ON_SMARTART,
errorOnOle != null ? errorOnOle : WordPdfSettings.ERROR_ON_OLE,
maxMb, maxPages);
Boolean.TRUE.equals(errorOnCharts),
Boolean.TRUE.equals(errorOnSmartArt),
Boolean.TRUE.equals(errorOnOle),
effMaxMb, effMaxPages);
byte[] pdf = conversionService.convert(docxBytes, name, options);
ContentDisposition disposition = ContentDisposition.attachment()
.filename(ConversionService.safeBaseName(name) + ".pdf", StandardCharsets.UTF_8)
@@ -1,12 +1,12 @@
spring.application.name=wordpdf-app
# Потолок инфраструктуры — 100 МБ (совпадает с client_max_body_size в
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Авторитетный
# лимит — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ), по умолчанию
# WordPdfSettings.MAX_INPUT_MB = 5; здесь только потолок загрузки.
# Лимиты входа: env WORDPDF_MAX_MB (МБ) / WORDPDF_MAX_PAGES (страницы),
# дефолты — константы ядра (5 / 100), задаются ConvertController.
# Значение <= 0 — падение на старте. Сами ключи здесь не объявлены:
# пустое значение затенит SpEL-дефолт @Value.
# nginx-шлюзах): больше не пропустит ни шлюз, ни контейнер. Логический лимит
# входа — свойство wordpdf.max-mb (env WORDPDF_MAX_MB, МБ) /
# wordpdf.max-pages (env WORDPDF_MAX_PAGES): дефолты 5/100 — литералы @Value
# в ConvertController (дефолтов лимитов в ядре нет); параметрами запроса
# maxMb/maxPages дефолт переопределяется в обе стороны. Значение свойства
# <= 0 — падение на старте. Сами ключи здесь не объявлены: пустое значение
# затенит дефолт @Value.
# file-size-threshold=2MB: части больше 2 МБ сбрасываются на диск Tomcat, heap
# держит только копию getBytes() одной сериализованной конвертации (порог 100MB
# буферизовал в heap каждую параллельную загрузку до валидации размера — OOM-килл
@@ -92,7 +92,7 @@ class ConversionServiceTest {
byte[] sample = bytes("/samples/ru-plain.docx");
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
() -> svc.convert(sample, "queue.docx", ConvertOptions.defaults()));
() -> svc.convert(sample, "queue.docx", new ConvertOptions(false, false, false, 5, 100)));
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
} finally {
block.countDown();
@@ -115,7 +115,7 @@ class ConversionServiceTest {
try {
Thread.currentThread().interrupt();
ConversionRejectedException e = assertThrows(ConversionRejectedException.class,
() -> svc.convert(sample, "ru-plain.docx", ConvertOptions.defaults()));
() -> svc.convert(sample, "ru-plain.docx", new ConvertOptions(false, false, false, 5, 100)));
assertEquals("Сервис конвертации занят — повторите позже", e.getMessage());
assertTrue(Thread.currentThread().isInterrupted(),
"флаг прерывания обязан быть восстановлен");
@@ -125,7 +125,7 @@ class ConversionServiceTest {
// барьер: отменённая задача ещё домучивает рендер на воркере, а
// глобальный реестр шрифтов ядра не потокобезопасен — ждём освобождения
// воркера через успешную сериализованную конвертацию
byte[] pdf = svc.convert(sample, "barrier.docx", ConvertOptions.defaults());
byte[] pdf = svc.convert(sample, "barrier.docx", new ConvertOptions(false, false, false, 5, 100));
assertEquals("%PDF", new String(pdf, 0, 4, StandardCharsets.US_ASCII));
svc.shutdown();
}
@@ -30,7 +30,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/
@SpringBootTest
@AutoConfigureMockMvc
@TestPropertySource(properties = "wordpdf.convert-timeout=1ms")
@TestPropertySource(properties = {"wordpdf.convert-timeout=1ms",
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
// (mise подмешивает корневой .env в окружение тасок)
"wordpdf.api-key="})
class ConversionTimeoutTest {
private static final MediaType DOCX =
@@ -44,7 +44,8 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
* ядра, PDF разбирается PDFBox, текст нормализуется по пробелам — паттерны
* {@code WordPdfConverterTest} (norm/pdfText).
*/
@SpringBootTest
@SpringBootTest(properties = "wordpdf.api-key=") // пустой = фильтр выключен; пин от
// ambient WORDPDF_API_KEY (mise подмешивает корневой .env в окружение тасок)
@AutoConfigureMockMvc
class ConvertControllerTest {
@@ -311,8 +312,8 @@ class ConvertControllerTest {
@Test
void oversizedOverCoreLimit_rejected() throws Exception {
// 5 MiB + 1 байт: проходит контейнерный multipart-лимит (100 МБ)
// и отсекается валидацией ядра до очереди (дефолт ядра цел —
// лимит задаёт только конфигурация сервера)
// и отсекается валидацией ядра до очереди (дефолт эндпоинта 5 МБ —
// параметры запроса здесь не участвуют)
byte[] big = new byte[5 * 1024 * 1024 + 1];
mockMvc.perform(multipart("/api/v1/convert").file(docx("big.docx", big)))
.andExpect(status().isBadRequest())
@@ -321,20 +322,60 @@ class ConvertControllerTest {
}
/**
* Регрессия env-only: лимиты входа параметрами запроса не задаются.
* maxMb/maxPages в multipart-форме игнорируются — маленький
* документ проходит на серверных лимитах (дефолты ядра).
* Параметр запроса maxMb ужимает серверный дефолт: файл в пределах
* серверных 5 МБ отвергается по параметру 1 МБ (текст гварда — с
* числом из запроса).
*/
@Test
void requestLimitParams_areIgnored() throws Exception {
void requestLimit_maxMbTightens_rejected() throws Exception {
byte[] twoMb = new byte[2 * 1024 * 1024];
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("two.docx", twoMb))
.param("maxMb", "1"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("больше 1 МБ")));
}
/** Параметр maxMb поднимает серверный дефолт: обычный документ проходит. */
@Test
void requestLimit_maxMbRaises_smallOk() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxMb", "1000")
.param("maxPages", "1"))
.param("maxPages", "1000"))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_PDF));
}
/** Параметр maxPages ужимает дефолт: фикстура на 110 границ отвергается с числом из запроса. */
@Test
void requestLimit_maxPagesTightens_rejected() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("stale-cache.docx", bytes("/samples/stale-cache.docx")))
.param("maxPages", "1"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("длиннее 1 страниц")));
}
/** Нулевые лимиты в запросе — 400 до любой работы с файлом. */
@Test
void requestLimit_nonPositive_rejected() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxMb", "0"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("maxMb должен быть больше 0")));
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("ru-plain.docx", bytes("/samples/ru-plain.docx")))
.param("maxPages", "0"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("maxPages должен быть больше 0")));
}
/**
* Невалидные лимиты в конфигурации — падение на старте (fail-fast):
* «сервис поднят, но весь вход отсекается» хуже не поднявшегося.
@@ -480,7 +521,7 @@ class ConvertControllerTest {
ConvertController controller =
new ConvertController(new ConversionService(Duration.ofSeconds(5)), 5L, 100);
BadRequestException e = assertThrows(BadRequestException.class,
() -> controller.convert(broken, null, null, null));
() -> controller.convert(broken, null, null, null, null, null));
assertTrue(e.getMessage().contains("Не удалось прочитать"), e.getMessage());
}
}
@@ -35,7 +35,10 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.
*/
@SpringBootTest
@AutoConfigureMockMvc
@TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1"})
@TestPropertySource(properties = {"wordpdf.max-mb=1", "wordpdf.max-pages=1",
// пустой ключ = фильтр выключен; пин от ambient WORDPDF_API_KEY
// (mise подмешивает корневой .env в окружение тасок)
"wordpdf.api-key="})
class ConvertLimitsTest {
private static final MediaType DOCX =
@@ -90,4 +93,26 @@ class ConvertLimitsTest {
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("страниц")));
}
/**
* Параметры запроса ПОДНИМАЮТ configured-дефолты (свойство — дефолт, не
* потолок): maxMb=5 — и файл за 1 MiB проходит байтовый гейт (отказ уже
* по контейнеру, не по размеру); maxPages=2 — и текст отказа несёт
* двойку, а не configured единицу.
*/
@Test
void restParamAboveConfigured_applies() throws Exception {
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("big.docx", oversizedZip()))
.param("maxMb", "5"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("не является .docx")));
mockMvc.perform(multipart("/api/v1/convert")
.file(docx("too-many-pages.docx", bytes("/samples/too-many-pages.docx")))
.param("maxPages", "2"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.error",
org.hamcrest.Matchers.containsString("длиннее 2 страниц")));
}
}