NextPDF Connect — транспорт gRPC

Кратко

Транспорт gRPC запускает bin/nextpdf-grpc в пуле gRPC-воркеров RoadRunner. Он обслуживает службу nextpdf.connect.v1.NextPDFConnect, поддерживает серверную потоковую передачу результатов отрисовки, аутентифицирует каждый вызов по токену-носителю в метаданных и в объединённом профиле развёртывания настроен на взаимный TLS.

Установка

composer require nextpdf/server
./vendor/bin/rr get-binary

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

Служба gRPC использует те же прикладные сервисы, что и транспорт Representational State Transfer (REST): отрисовку, задания, сессии, возможности и операции. Вызовы обрабатывает gRPC-воркер Spiral RoadRunner. Сетевой контракт задаёт пакет Protocol Buffers nextpdf.connect.v1, определяемый файлами .proto, которые поставляются вместе с пакетом.

Аутентификация использует то же хранилище ключей и ту же логику проверки, что и REST. Аутентификатор gRPC считывает из метаданных ключ authorization, который gRPC передаёт как заголовки Hypertext Transfer Protocol version 2 (HTTP/2). Он разбирает токен Bearer npk_live_…, а затем проверяет идентификатор ключа (kid) и дайджест SHA-256 с помощью сравнения за постоянное время. Аутентификатор отклоняет вызов со статусом gRPC UNAUTHENTICATED, если ключ отсутствует, неверно отформатирован, неизвестен, отключён или просрочен. Некорректная реализация аутентификации относится к риску OWASP API2:2023 Broken Authentication; сравнение дайджеста за постоянное время снижает этот риск.

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

RPC службы

Служба nextpdf.connect.v1.NextPDFConnect предоставляет унарные и серверные потоковые RPC:

RPC	Форма	Назначение
`Render`	унарный	Синхронная отрисовка
`RenderStream`	серверный потоковый	Отрисовка, передаваемая потоком по фрагментам
`SubmitJob` / `GetJobStatus` / `GetJobResult` / `CancelJob`	унарный	Асинхронные задания
`GetJobResultStream`	серверный потоковый	Асинхронный результат, передаваемый потоком
`CreateSession` / `GetSession` / `DestroySession` / `SessionOperation` / `SessionRender`	унарный	Сессии с сохранением состояния
`SessionRenderStream`	серверный потоковый	Отрисовка сессии, передаваемая потоком
`ExecuteCapability` / `GetCapabilities`	унарный	Диспетчеризация и интроспекция возможностей
`HealthCheck` / `ReadinessCheck`	унарный	Работоспособность и готовность

ExecuteCapability диспетчеризирует те же операции с ограничением по уровню, что и маршруты операций REST. Операции Pro и Enterprise доступны только если установлены соответствующие пакеты. Для подписания при наличии Pro NextPDF Connect предоставляет только подпись Portable Document Format (PDF) Advanced Electronic Signatures (PAdES) уровня baseline-B (B-B).

Потоковая передача

Серверные потоковые RPC отправляют результат упорядоченным потоком фрагментов; это подходит для больших файлов PDF и инкрементной доставки. Унарные RPC возвращают полный результат одним сообщением.

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

Запустите профиль, в котором включён только gRPC:

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.grpc.yaml

Сгенерируйте клиент из поставляемых файлов .proto с помощью используемого вами набора инструментов gRPC:

# proto/nextpdf/connect/v1/*.proto — package nextpdf.connect.v1
protoc --proto_path=proto --<lang>_out=. proto/nextpdf/connect/v1/service.proto

При каждом вызове задавайте в метаданных учётных данных вызова authorization со значением Bearer npk_live_{kid}_{secret}.

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

Объединённый профиль запускает gRPC с взаимным TLS:

export NEXTPDF_GRPC_TLS_KEY=/run/secrets/grpc-server.key
export NEXTPDF_GRPC_TLS_CERT=/run/secrets/grpc-server.crt
export NEXTPDF_GRPC_TLS_CA=/run/secrets/grpc-client-ca.crt
./vendor/bin/rr serve -c .rr.full.yaml

В этом профиле сервер предъявляет свой сертификат, требует и проверяет клиентский сертификат (require_and_verify_client_cert). Если после разрыва соединения повторить идемпотентную унарную отправку задания, это безопасно: повторение идемпотентного запроса даёт тот же предполагаемый эффект, что и однократный запрос (RFC 9110 §9.2.2).

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

UNAUTHENTICATED, а не статус HTTP. При неверном или отсутствующем токене RPC отклоняется со статус-кодом gRPC UNAUTHENTICATED, а не 401. Схема bearer и формат npk_live_ идентичны REST.
RESOURCE_EXHAUSTED при слишком большом числе попыток до аутентификации. Повторные попытки до завершения аутентификации от одного клиентского удостоверения ограничиваются и завершаются отказом со статусом gRPC RESOURCE_EXHAUSTED. Этот статус соответствует HTTP 429 в gRPC; механизм применяет ту же защиту от автоматизации, что и REST. Механизм активен по умолчанию, поэтому клиентам следует сделать паузу, а не повторять запрос немедленно. См. описание подхода к ограничению частоты HTTP в /connect/production-usage/.
Взаимный TLS — это конфигурация развёртывания, а не значение по умолчанию. Прослушивателю gRPC нужны правильно подготовленные секреты: серверный ключ, серверный сертификат и CA клиентских сертификатов. Без них объединённый профиль не будет обслуживать запросы; это сделано намеренно. Создавайте и ротируйте их по отдельному (внеполосному) каналу.
Ограничение по уровню по-прежнему действует. ExecuteCapability для операции Pro или Enterprise требует установленного пакета и ключа с соответствующими правами.
Операции с высоким риском по-прежнему проходят через шлюз. Операции, которые задействуют инструмент ApprovalRequired, используют тот же шлюз с участием человека. См. /connect/hitl-risk-tiers/.

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

Каждый gRPC-воркер обрабатывает по одному вызову за раз. Размер пула задаётся независимо от пула HTTP (по умолчанию два воркера) и обычно меньше, поскольку gRPC-клиентов меньше, а их соединения сохраняются дольше. Для больших результатов используйте серверные потоковые RPC, чтобы не буферизовать весь PDF в одном сообщении.

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

Запускайте транспорт gRPC с взаимным TLS в любой недоверенной сети; никогда не используйте прослушиватель без шифрования. Рассматривайте клиентский CA, серверный ключ и серверный сертификат как секреты, монтируемые во время выполнения, и никогда не встраивайте их в образ. Аутентификация bearer применяется в дополнение к сертификату, а не вместо него. Такой подход требует корректной конфигурации развёртывания. См. /connect/security-and-operations/ и /connect/deployment/.

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

Утверждение	Источник	`reference_id`
Нарушенная аутентификация компрометирует безопасность API	OWASP API Security Top 10, API2:2023 (рейтинг рисков безопасности API)
Идемпотентные запросы можно повторять после сбоя	RFC 9110 §9.2.2

Сам протокол gRPC — внешняя спецификация за пределами проверяемого корпуса стандартов. Поставляемые определения Protocol Buffers nextpdf.connect.v1 являются эталонным сетевым контрактом.

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

ExecuteCapability предоставляет доступ к операциям Pro и Enterprise только если рядом с сервером установлен nextpdf/premium. Наличие установленных уровней не изменяет конфигурацию транспорта, аутентификации или TLS.

См. также

/connect/security-and-operations/ — аутентификация, взаимный TLS, модель угроз
/connect/deployment/ — объединённый профиль RoadRunner и секреты TLS
/transports/mcp/ · /transports/rest/ — другие транспорты
/connect/tool-catalog/ — как ExecuteCapability сопоставляется с каталогом
/connect/production-usage/ — задания и идемпотентный повтор