NextPDF Connect — gRPC 전송

한눈에 보기

gRPC 전송은 RoadRunner gRPC 워커 풀에서 bin/nextpdf-grpc를 실행합니다. 이 전송은 nextpdf.connect.v1.NextPDFConnect 서비스를 제공하고, 서버 스트리밍 렌더링을 지원하며, 호출 메타데이터에 담긴 bearer 토큰으로 인증하고, 결합 배포 프로필에서 상호 TLS로 구성됩니다.

설치

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

개념 개요

gRPC 서비스는 Spiral RoadRunner gRPC 워커를 통해 렌더링, 작업, 세션, 기능, 연산 등 REST 전송과 동일한 애플리케이션 서비스를 공유합니다. 와이어 계약은 Protocol Buffers 패키지 nextpdf.connect.v1이며, 패키지에 포함되어 배포되는 .proto 파일에서 정의됩니다.

인증은 REST 키 저장소와 검증을 재사용합니다. gRPC 인증자는 authorization 메타데이터 키를 읽고 — gRPC 호출 메타데이터는 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는 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

사용 중인 gRPC 툴체인으로 배포된 proto에서 클라이언트를 생성합니다.

# 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}로 설정합니다.

코드 예제 — 프로덕션

결합 프로필은 상호 TLS로 gRPC를 실행합니다.

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 상태가 아닙니다. 잘못되었거나 누락된 토큰은 gRPC UNAUTHENTICATED 상태 코드로 RPC를 실패 처리하며, 401이 아닙니다. bearer 스킴과 npk_live_ 형식은 REST와 동일합니다.

• 과도한 사전 인증 시도 시 RESOURCE_EXHAUSTED 발생. 하나의 클라이언트 ID에서 반복되는 사전 인증 시도는 스로틀링되어 gRPC RESOURCE_EXHAUSTED 상태로 실패합니다. 이는 HTTP 429의 gRPC 대응물이며, REST 표면이 적용하는 것과 동일한 자동화 방지 태세입니다. 이 제어는 기본적으로 활성화되어 있으므로, 클라이언트는 즉시 재시도하기보다 백오프해야 합니다. HTTP 속도 제한 태세는 /connect/production-usage/에서 확인할 수 있습니다.

• 상호 TLS는 기본값이 아니라 배포 구성입니다. gRPC 리스너는 올바르게 프로비저닝된 서버 키, 서버 인증서, 클라이언트 CA 시크릿을 요구합니다. 이들이 없으면 결합 프로필은 서비스를 제공하지 않으며, 이는 의도된 동작입니다. 이들은 대역 외에서 생성하고 교체합니다.

• 등급 게이팅은 여전히 적용됩니다. Pro 또는 Enterprise 연산에 대한 ExecuteCapability는 설치된 패키지와 권한이 부여된 키를 요구합니다.

• 고위험 연산은 여전히 게이트를 거칩니다. ApprovalRequired 도구를 구동하는 연산은 동일한 사람 개입(human-in-the-loop) 게이트를 거칩니다. /connect/hitl-risk-tiers/에서 확인할 수 있습니다.

성능

각 gRPC 워커는 한 번에 하나의 호출을 처리합니다. 풀 크기는 HTTP 풀과 독립적으로 지정되며(기본값은 워커 2 개), gRPC 클라이언트는 보통 수가 적고 수명이 길어 풀 크기도 일반적으로 더 작게 잡습니다. 대용량 출력의 경우 전체 PDF를 하나의 메시지에 버퍼링하지 않도록 서버 스트리밍 RPC를 사용합니다.

보안 참고사항

신뢰할 수 없는 네트워크에서는 gRPC 전송을 상호 TLS로 실행합니다 — 평문 리스너는 절대 사용하지 않습니다. 클라이언트 CA, 서버 키, 서버 인증서는 이미지에 포함하지 말고 런타임에 마운트되는 시크릿으로 취급합니다. Bearer 인증은 인증서를 대체하는 것이 아니라 인증서에 추가로 적용됩니다. 이는 올바른 배포 구성을 요구하는 보안 태세입니다. /connect/security-and-operations/ 및 /connect/deployment/에서 확인할 수 있습니다.

적합성

주장	출처	reference_id
취약한 인증은 API 보안을 손상시킵니다	OWASP API 보안 Top 10, API2:2023
멱등 요청은 실패 후 재시도 가능	RFC 9110 §9.2.2

gRPC 프로토콜 자체는 게이트된 표준 코퍼스에 포함되지 않은 외부 사양입니다. 공식 와이어 계약은 배포된 nextpdf.connect.v1 Protocol Buffers 정의입니다.

상업적 맥락

ExecuteCapability는 nextpdf/premium이 서버와 함께 설치된 경우에만 Pro 및 Enterprise 연산에 도달합니다. 전송, 인증, TLS 구성은 설치된 등급에 따라 달라지지 않습니다.

함께 보기

• /connect/security-and-operations/ — 인증, 상호 TLS, 위협 모델
• /connect/deployment/ — 결합 RoadRunner 프로필과 TLS 시크릿
• /transports/mcp/ · /transports/rest/ — 다른 전송
• /connect/tool-catalog/ — ExecuteCapability가 카탈로그에 매핑되는 방식
• /connect/production-usage/ — 작업과 멱등 재시도