NextPDF Cloudflare 엣지 렌더링 브리지 — 개요

한눈에 보기

nextpdf/cloudflare는 엣지 렌더링 브리지입니다. PHP 애플리케이션은 HTML을 보유하고, Cloudflare Worker는 헤드리스 브라우저를 보유합니다. 브리지는 HTML을 HTTPS를 통해 Worker로 보내고 렌더링된 PDF 바이트를 돌려받습니다. PHP 프로세스 안에서는 헤드리스 브라우저가 실행되지 않으며, 브리지가 담당하는 경로에는 로컬 Chromium 바이너리가 필요하지 않습니다.

이 패키지는 NextPDF 생태계에 속하며 nextpdf/core^3.0에 의존합니다. 이 패키지는 와이어 프로토콜 코드로, JSON 요청을 구성하고, 입력과 목적지를 검증하며, PSR-18 클라이언트를 통해 요청을 보내고, 응답을 타입이 지정된 결과 객체로 파싱합니다. Worker 구현 자체는 이 패키지에 포함되지 않습니다. 이 브리지는 사용자가 배포한 Worker와 통신합니다.

신뢰 경계

이 브리지의 결정적 특징은 HTML이 네트워크 경계를 넘어 직접 제어하지 않는 브라우저 엔진에 도달한다는 점입니다. 패키지의 모든 보안 제어는 이 경계 때문에 존재합니다.

HTML은 PHP 프로세스를 떠나기 전에 검증됩니다 (CloudflareSecurityPolicy::validate()).
목적지 URL은 요청이 전송되기 전에 검증되고 (CloudflareSecurityPolicy::validateWorkerUrl()), time-of-check/time-of-use 창을 닫기 위해 요청 시점에 다시 검증됩니다 (assertPinsStillValid()).
전송 계층은 확인된 IP 집합과 서버 인증서의 공개 키를 고정할 수 있습니다 (Transport\PinnedCurlTransport).

이 브리지를 프로덕션용으로 평가하고 있다면, /integrations/cloudflare/quickstart/. 보다 먼저 /integrations/cloudflare/security-and-operations/를 읽으십시오. 보안 모델은 부가 기능이 아닙니다. 이 보안 모델이 패키지가 지금과 같은 형태를 갖춘 이유입니다.

하는 일

기능	담당 클래스
Cloudflare Worker를 통해 HTML을 PDF로 렌더링	`CloudflareHtmlRenderer::render()`
도달 가능성 프로브 (HTTP `HEAD`)	`CloudflareHtmlRenderer::isAvailable()`
벤더 비종속 전송 계층	PSR-18 `ClientInterface` 주입
입력 강화 (크기, base64 폭탄, meta-refresh)	`CloudflareSecurityPolicy::validate()`
SSRF / DNS 리바인딩 방어	`CloudflareSecurityPolicy::validateWorkerUrl()` + `assertPinsStillValid()`
TLS 공개 키 고정, cURL 계층에서의 고정 DNS	`Transport\PinnedCurlTransport`
Worker에 도달할 수 없을 때 로컬 Chrome 폴백	`Contract\LocalRendererFactoryInterface`
바이너리 및 JSON (base64) 응답 파싱	`CloudflareResponseParser`
엣지 텔레메트리 (렌더링 시간, 엣지 위치, 콘텐츠 높이)	`CloudflareRenderResult`
R2 버킷의 사용자 정의 폰트	`CloudflareRenderPayload` (`r2FontBucket`, `fontFiles`)
API 보호 계층 (키 인증, 페이로드 크기, 속도 제한)	`ApiProtection`
S3 호환 API를 통한 R2로의 PDF 아카이빙	`R2ArchiveManager`

각 행은 NextPDF\Cloudflare 네임스페이스의 클래스에 매핑됩니다. 검증 기준은 명세 문서가 아니라 해당 클래스의 동작과 테스트입니다.

하지 않는 일

이 패키지는 브라우저를 실행하지 않습니다. Worker가 실행합니다.
이 패키지는 Worker를 배포하거나 구성하지 않습니다. 그 아티팩트는 사용자가 소유합니다.
이 패키지는 PDF에 서명하지 않습니다. 서명은 nextpdf/core 또는 상용 에디션의 영역입니다. 서명이 필요할 때는 먼저 렌더링한 다음, 엔진이 반환한 바이트에 서명하십시오. NextPDF Pro는 PAdES B-B 서명을 제공합니다. 장기 검증(long-term-validation) 프로파일은 Enterprise 기능입니다.
이 패키지는 어떠한 Cloudflare 플랫폼 용량이나 한도도 단언하지 않습니다. 이 문서가 명시하는 크기 및 시간 한도는 이 패키지가 자체 구성에서 적용하는 것들뿐입니다 (/integrations/cloudflare/configuration/ 참조).

두 가지 보안 정책

이 브리지는 서로 구별되면서도 상호 보완적인 두 가지 정책을 갖고 있으며, 이 둘을 혼동하는 것이 가장 흔한 검토 오류입니다. 각각은 다음과 같습니다.

HTML 보안 정책 (HtmlSecurityPolicyInterface, 기본값 NextPDF\Html\DefaultHtmlSecurityPolicy, nextpdf/core가 제공): 파싱 계층의 콘텐츠 필터링으로, 콘텐츠가 Worker에 도달하기 전에 적용됩니다. getHtmlSecurityPolicy()로 가져옵니다.
Cloudflare 보안 정책 (CloudflareSecurityPolicy, 정적): 전송 계층 사안으로, 입력 크기, base64 압축 해제 폭탄 탐지, meta-refresh 차단, HTTPS 강제, 그리고 Worker URL에 대한 SSRF / DNS 리바인딩 방어를 다룹니다.

렌더러 자체의 docblock은 이 분리를 명시합니다. 이 페이지에서는 프로덕션 검토자가 두 이름을 한 화면에서 함께 봐야 하므로 이를 다시 설명합니다.

엣지 렌더링 모델

단일 render() 호출은 관찰 가능한 다음 시퀀스를 수행합니다. 이 시퀀스는 CloudflareHtmlRenderer::render()에서 직접 확인한 것입니다.

구성 완전성 확인 (workerUrl과 apiToken이 비어 있지 않은지). 실패하면 브리지는 로컬 렌더러로 폴백하거나 CloudflareNotAvailableException을 던집니다.
구성된 최대 크기, base64 URI 상한, meta-refresh 금지 기준에 따라 HTML을 검증합니다.
Worker URL을 검증하여 호스트를 확인하고 검증된 IP 집합을 반환합니다.
페이로드를 구성합니다 (CloudflareRenderPayload).
호스트의 DNS 응답이 3단계 이후로 변경되지 않았는지 time-of-use를 재확인합니다.
HTTP POST가 전송됩니다 — IP 집합 또는 SPKI 핀 집합이 존재하고 PSR-17 ResponseFactory가 제공된 경우에는 고정된 cURL 전송을 통해, 그렇지 않으면 주입된 PSR-18 클라이언트를 통해 전송됩니다.
응답은 CloudflareRenderResult로 파싱됩니다.

CloudflareRenderException 이외의 모든 throwable은 폴백 경로를 트리거합니다. CloudflareRenderException(HTTP 오류 또는 Worker의 형식이 잘못된 응답)은 변경 없이 다시 던져집니다. 이는 도달 가능성 실패가 아니라 Worker 측 실패이므로 폴백하지 않습니다.

참고 항목

/integrations/cloudflare/install/ — 패키지와 PSR-18 클라이언트를 설치합니다.
/integrations/cloudflare/configuration/ — 소스로 검증된 기본값을 포함해 모든 구성 필드를 다룹니다.
/integrations/cloudflare/quickstart/ — 처음 실행 가능한 렌더링.
/integrations/cloudflare/production-usage/ — 폴백, 텔레메트리, R2 아카이빙, API 보호.
/integrations/cloudflare/security-and-operations/ — 운영 관점에서 신뢰 경계를 자세히 설명합니다.
/integrations/cloudflare/troubleshooting/ — 예외에 매핑된 실패 모드.
/integrations/cloudflare/boot-and-discovery/ — 브리지가 호스트 프레임워크에 연결되는 방식.
/integrations/cloudflare/integration/ — Cloudflare 서비스를 통해 NextPDF를 구동하기.