NextPDF Connect в продакшене

Кратко

Развёртывание NextPDF Connect в продакшене предоставляет несколько средств для эксплуатации: пробы работоспособности и готовности, синхронный и асинхронный режимы отрисовки, идемпотентность, ограничения частоты запросов для каждого клиента и каждого адреса Internet Protocol (IP), а также необязательные сессии с сохранением состояния. На этой странице описано, как использовать их предсказуемо.

Установка

composer require nextpdf/server

Концептуальный обзор

Транспорт Representational State Transfer (REST) реализован как конвейер промежуточного ПО PHP Standards Recommendation (PSR)-15. Каждый запрос последовательно проходит через промежуточное ПО: назначение request-id, ограничение размера тела, Cross-Origin Resource Sharing (CORS), аутентификацию, авторизацию возможностей, ограничение частоты запросов, идемпотентность и тайм-аут. Затем запрос попадает к обработчику. Транспорт gRPC повторно использует те же сервисы приложения в воркере gRPC RoadRunner.

Отрисовку можно выполнять двумя способами. Синхронный POST /api/v1/render выполняет операции и возвращает файл Portable Document Format (PDF) в ответе. Для асинхронного задания используется POST /api/v1/jobs. Оно сразу возвращает идентификатор задания, а результат вы получаете позже через GET /api/v1/jobs/{id}/result. Задания сохраняются в общем хранилище SQLite, поэтому на запрос статуса или результата может ответить любой воркер.

Поверхность API

Работоспособность и готовность

Конечная точка	Аутентификация	Значение
`GET /healthz`	нет	Процесс выполняется
`GET /readyz`	нет	Сервер готов принимать запросы

Привяжите /healthz к пробе работоспособности, а /readyz — к пробе готовности. Обе конечные точки анонимны, поэтому оркестраторам не нужны учётные данные.

Асинхронные задания

Конечная точка	Метод	Назначение
`/api/v1/jobs`	`POST`	Отправить задание на отрисовку
`/api/v1/jobs/{id}`	`GET`	Статус задания
`/api/v1/jobs/{id}/result`	`GET`	Результат задания (PDF)
`/api/v1/jobs/{id}`	`DELETE`	Отменить задание

Сессии (по выбору)

Когда NEXTPDF_SESSIONS_ENABLED равно true и инструменты доступны, конечные точки сессий позволяют вести сборку с сохранением состояния. Вы создаёте сессию, добавляете страницы, текст, изображения, таблицы и HyperText Markup Language (HTML), задаёте шрифт, а затем выполняете отрисовку. Для сессий действуют ограничение на каждого клиента и тайм-аут простоя. По умолчанию они отключены.

Пример кода — быстрый старт

Отправьте асинхронное задание и опрашивайте результат:

JOB=$(curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"async render"}]}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -sS "http://localhost:8080/api/v1/jobs/$JOB/result" \
  -H "Authorization: Bearer $NEXTPDF_KEY" --output out.pdf

Пример кода — продакшен

Чтобы отправку можно было безопасно повторять, передайте ключ идемпотентности:

curl -sS -X POST http://localhost:8080/api/v1/jobs \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Idempotency-Key: 7b1c2d3e-…' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"safe retry"}]}'

Запрос, повторённый с тем же ключом идемпотентности, возвращает исходный результат вместо создания второго задания. Благодаря этому отправку можно безопасно повторить после сбоя связи. Так работает свойство идемпотентного метода: повторная отправка того же запроса имеет тот же предполагаемый эффект, что и однократная отправка (RFC 9110 §9.2.2). Поэтому запрос можно автоматически повторить, если соединение разрывается до того, как клиент прочитает ответ (RFC 9110 §9.2.2).

Граничные случаи и подводные камни

Для корректного ограничения частоты запросов между воркерами нужен Redis. Ограничители для каждого клиента и каждого IP используют настроенное хранилище. Если используется хранилище в памяти и больше одного воркера, каждый воркер считает запросы независимо, и фактический предел умножается на число воркеров. Для любого пула с несколькими воркерами используйте хранилище Redis.
Запрос, попавший под ограничение, возвращает 429. При превышении предела сервер отвечает 429 Too Many Requests с заголовком Retry-After, следуя семантике статуса ограничения частоты запросов (RFC 6585 §4). Соблюдайте Retry-After; не повторяйте запрос немедленно.
Результаты заданий не хранятся бесконечно. Хранилище заданий удаляет старые записи по истечении NEXTPDF_JOB_GC_MAX_AGE_SECONDS. Получайте результаты до того, как они устареют.
Сессии расходуют память. Сессия хранит документ во время сборки. Ограничение числа сессий на каждого клиента и тайм-аут простоя сдерживают этот расход. Не повышайте их без расчёта памяти на худший случай.

Производительность

Синхронный путь занимает воркер на всё время отрисовки. Для крупных или медленных задач отрисовки используйте путь асинхронных заданий. Он немедленно освобождает воркер, а клиент опрашивает результат. Подбирайте размер пула воркеров исходя из наблюдаемой задержки отрисовки и параллелизма. Следите за конечной точкой метрик RoadRunner.

Замечания по безопасности

Для каждой конечной точки, кроме проб работоспособности, требуется действительный ключ application programming interface (API). Тариф клиента определяет, какие операции и размеры полезной нагрузки разрешены. Ключи идемпотентности предоставляют клиенты. Рассматривайте каждый ключ как непрозрачное значение, уникальное для одной логической операции. См. /connect/security-and-operations/.

Соответствие

Утверждение	Источник	`reference_id`
Идемпотентность: повторные запросы = один эффект	RFC 9110 §9.2.2
Идемпотентные запросы можно повторить после сбоя	RFC 9110 §9.2.2
`429` + `Retry-After` для ограничения частоты запросов	RFC 6585 §4

Коммерческий контекст

Для ключей Pro и Enterprise действуют более высокие верхние пределы полезной нагрузки и тайм-аута по тарифу, когда эти инструменты установлены. Развёртывание по умолчанию использует пределы тарифа core.

См. также

/connect/deployment/ — пулы воркеров, Redis, профили RoadRunner
/transports/rest/ — полный конвейер промежуточного ПО и контракт OpenAPI
/connect/troubleshooting/ — диагностика 401/403/413/429/5xx и сбоев хранилища
/connect/security-and-operations/ — аутентификация и политика ограничения частоты запросов