Обзор NextPDF Gotenberg

Краткий обзор

NextPDF Gotenberg — это небольшой мост между NextPDF и внешним сервисом Gotenberg. Используйте его, когда NextPDF не может самостоятельно отрисовать Office-документ. Мост отправляет документ в экземпляр Gotenberg по HTTP, получает на выходе PDF и передаёт его вашему приложению. Всю дальнейшую постобработку выполняет NextPDF.

Пакет небольшой и прозрачно устроен. Он не встраивает движок отрисовки, не запускает LibreOffice и не запускает браузер. Каждое преобразование выполняется одним составным (multipart) HTTP-запросом к конечной точке Gotenberg. Вы управляете этой конечной точкой и указываете её мосту в конфигурации.

Используйте этот мост, когда у вас есть исходные файлы .docx, .xlsx, .pptx, .odt, .ods или .odp и нужен PDF на выходе в конвейере NextPDF. После создания PDF подписание, преобразование в PDF/A, нанесение водяных знаков и объединение выполняет NextPDF или nextpdf/premium.

От чего зависит мост

У моста есть одна зависимость времени выполнения, которая не является PHP-пакетом: работающий сервис Gotenberg, доступный мосту по HTTPS.

Мост не устанавливает Gotenberg, не управляет им и не контролирует его. Вы развёртываете Gotenberg самостоятельно; upstream-проект публикует образ контейнера. Вы отвечаете за его доступность, пропускную способность и сетевой доступ к нему.
Мост обращается к маршруту преобразования LibreOffice в Gotenberg. URL запроса формируется как <apiUrl>/forms/libreoffice/convert, где <apiUrl> — базовый URL, который вы настраиваете. Этот маршрут определяет набор форматов, поддерживаемых мостом.
Проверка работоспособности отправляет HTTP-запрос HEAD на <apiUrl>/health и считает сервис доступным при любом статусе ниже 500.

Поскольку преобразование выполняет сервис, которым управляете вы, поведение зависит от используемой версии Gotenberg. Мост отправляет фиксированный составной (multipart) запрос и рассчитывает только на два пути Gotenberg: путь маршрута (/forms/libreoffice/convert) и путь проверки работоспособности (/health). Базовый сценарий развёртывания см. в /integrations/gotenberg/install/, а усиление защиты сервиса — в /integrations/gotenberg/security-and-operations/.

Поддерживаемые форматы документов

Мост преобразует только те форматы, которые перечислены в его типе OfficeFormat. Каждый формат определяется по расширению файла. Сопоставление не зависит от регистра; начальная точка допускается. Затем мост отправляет каждый файл в Gotenberg с фиксированным MIME-типом:

Формат	Расширение	MIME-тип, отправляемый в Gotenberg
Документ Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Таблица Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
Презентация PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
Текст OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
Таблица OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
Презентация OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Этот список исчерпывающий. Расширение вне этого набора вызывает ValueError ещё до отправки какого-либо сетевого запроса, поэтому мост никогда не пытается выполнить преобразование, которое не может описать. Мост не заявляет о поддержке “любого файла Office” или “всех форматов документов”. Он поддерживает только шесть перечисленных выше форматов, потому что код распознаёт только эти шесть, и набор тестов проверяет только эти шесть.

Устаревшие двоичные форматы (.doc, .xls, .ppt), форматированный текст (.rtf), простой текст, значения, разделённые запятыми (CSV), и форматы изображений не входят в набор, распознаваемый мостом. Собственный маршрут LibreOffice в Gotenberg может принимать более широкий набор входных данных. Мост намеренно ограничивается перечисленным набором, чтобы определение формата, MIME-тип и метаданные результата оставались согласованными и проверяемыми.

Как выполняется преобразование

Преобразование — это один линейный проход. Мост проверяет каждый шаг до того, как хоть один байт покинет процесс:

Проверяется конфигурация. Пустой URL API сразу же приводит к исключению преобразования.
Проверяется URL API. Требуется HTTPS, а хост разрешается и проверяется, чтобы он не мог указывать на частный или зарезервированный адрес. Полученный набор адресов сохраняется для последующей фиксации.
Считываются входные данные (при преобразовании файлов путь сначала приводится к каноническому виду, чтобы заблокировать обход каталогов), а их расширение сопоставляется с OfficeFormat.
Мост сверяет длину в байтах с настроенным максимумом и проверяет имя файла на наличие последовательностей обхода каталогов, косых черт, нулевых байтов и управляющих символов.
Набор адресов проверяется ещё раз непосредственно перед запросом, чтобы закрыть окно между проверкой и подключением.
Мост формирует тело multipart/form-data и отправляет его методом POST на маршрут LibreOffice, с bearer-токеном, если он настроен.
Мост разбирает ответ. Статус должен быть 200, Content-Type должен содержать application/pdf, а тело должно начинаться с сигнатуры %PDF. Только после этого мост возвращает результат.

Любой сбой на шагах 1–7 вызывает типизированное исключение. Мост не возвращает частичный или непроверенный результат. Точные исключения и их триггеры перечислены в /integrations/gotenberg/troubleshooting/.

Что вы получаете в ответ

Успешное преобразование возвращает объект результата. Объект включает необработанные байты PDF, преобразованный исходный формат и необязательное время отрисовки. Он также предоставляет проверку валидности (непустое тело, начинающееся с %PDF) и метод доступа к размеру в байтах. Эти байты представляют собой обычный поток PDF, поэтому вы можете записать их на диск, отдать клиенту потоком или передать в документ NextPDF для дальнейшей обработки.

Границы ответственности моста

Мост преобразует и проверяет. Он не:

Подписывает, шифрует, линеаризует результат или преобразует его в PDF/A. Эти задачи постобработки решает ядро NextPDF или nextpdf/premium.
Повторяет неуспешные запросы, ставит работу в очередь или кэширует результаты. Это задачи уровня приложения. В /integrations/gotenberg/production-usage/ показано, как добавить их поверх моста.
Управляет жизненным циклом сервиса Gotenberg. Вопросы развёртывания и эксплуатации рассмотрены в /integrations/gotenberg/security-and-operations/.

Редакции и постобработка

Ядро с открытым исходным кодом (OSS) может записать преобразованный PDF как есть. Если вам нужно подписать преобразованный документ, создать архивный профиль PDF/A или нанести водяной знак, эти возможности добавляет пакет nextpdf/premium. Сам мост не зависит от редакции: он создаёт PDF. Нужна ли вам коммерческая редакция, зависит от того, что вы делаете с этим PDF.

Базовый профиль усовершенствованных электронных подписей PDF (PAdES), доступный в редакции Pro, — это только B-B. Профили долгосрочной проверки (LTV) (B-T, B-LT, B-LTA) не входят в редакцию Pro и не предоставляются этим мостом. Не делайте вывод о наличии возможностей меток времени или LTV исходя из наличия этого пакета.

См. также

/integrations/gotenberg/install/ — установка пакета и развёртывание базового сценария Gotenberg.
/integrations/gotenberg/configuration/ — каждый параметр конфигурации, его тип, значение по умолчанию и эффект.
/integrations/gotenberg/quickstart/ — первое преобразование.
/integrations/gotenberg/production-usage/ — встраивание моста в реальное приложение.
/integrations/gotenberg/troubleshooting/ — каталог исключений и значение каждого из них.
/integrations/gotenberg/security-and-operations/ — модель безопасности и безопасная эксплуатация зависимого сервиса.
/integrations/gotenberg/boot-and-discovery/ — как хост-фреймворки обнаруживают и подключают мост.
/integrations/gotenberg/integration/ — управление отрисовкой NextPDF через сервис.