ภาพรวม NextPDF bridge สำหรับการเรนเดอร์ที่ edge ของ Cloudflare

ภาพรวมโดยย่อ

nextpdf/cloudflare คือ bridge สำหรับการเรนเดอร์ที่ edge โดยแอปพลิเคชัน PHP ของคุณยังเก็บ Hypertext Markup Language (HTML) ไว้ ส่วน Cloudflare Worker เก็บ headless browser ไว้ bridge จะส่ง HTML ไปยัง Worker ผ่าน Hypertext Transfer Protocol Secure (HTTPS) และรับ bytes ของ Portable Document Format (PDF) ที่เรนเดอร์แล้วกลับมา จึงไม่มี headless browser ทำงานอยู่ภายในกระบวนการ PHP ของคุณ และ bridge ไม่จำเป็นต้องพึ่งไบนารี Chromium ในเครื่องบนเส้นทางที่ตนดูแล

แพ็กเกจนี้เป็นส่วนหนึ่งของ ecosystem ของ NextPDF และพึ่งพา nextpdf/core^3.0 โค้ดส่วนนี้ทำงานในระดับ wire-protocol คือสร้างคำขอแบบ JavaScript Object Notation (JSON) ตรวจสอบความถูกต้องของอินพุตและปลายทาง ส่งคำขอผ่านไคลเอนต์ที่เป็น PHP Standards Recommendation 18 (PSR-18) และแยกวิเคราะห์การตอบกลับให้เป็นอ็อบเจกต์ผลลัพธ์ที่มีชนิดข้อมูลกำกับ การพัฒนา Worker อยู่นอกขอบเขตของแพ็กเกจนี้ bridge นี้สื่อสารกับ Worker ที่คุณดีพลอย

ขอบเขตความเชื่อถือ

คุณลักษณะสำคัญของ bridge นี้คือ HTML จะข้ามขอบเขตเครือข่ายไปยังเอนจินเบราว์เซอร์ที่คุณไม่ได้ควบคุมโดยตรง มาตรการควบคุมความปลอดภัยทั้งหมดในแพ็กเกจนี้มีไว้เพื่อจัดการขอบเขตดังกล่าว

• HTML จะได้รับการตรวจสอบความถูกต้อง ก่อน ที่จะออกจากกระบวนการ PHP (CloudflareSecurityPolicy::validate())
• Uniform Resource Locator (URL) ปลายทางจะได้รับการตรวจสอบความถูกต้อง ก่อน ที่จะส่งคำขอ (CloudflareSecurityPolicy::validateWorkerUrl()) จากนั้นจะตรวจสอบซ้ำขณะส่งคำขอเพื่อปิดช่อง time-of-check/time-of-use (assertPinsStillValid())
• transport สามารถ pin ชุด Internet Protocol (IP) ที่ resolve แล้วและ public key ของใบรับรองเซิร์ฟเวอร์ (Transport\PinnedCurlTransport)

หากคุณกำลังประเมิน bridge นี้เพื่อใช้งานจริง ให้เริ่มจาก /integrations/cloudflare/security-and-operations/ ก่อน /integrations/cloudflare/quickstart/ โมเดลความปลอดภัยไม่ใช่ส่วนเสริม แต่เป็นสิ่งที่อธิบายว่าทำไมแพ็กเกจจึงถูกออกแบบในรูปแบบนี้

สิ่งที่ทำได้

ความสามารถ	รองรับโดย
เรนเดอร์ HTML เป็น PDF ผ่าน Cloudflare Worker	CloudflareHtmlRenderer::render()
การตรวจสอบความพร้อมใช้งาน (Hypertext Transfer Protocol (HTTP) HEAD)	CloudflareHtmlRenderer::isAvailable()
transport ที่ไม่ผูกกับผู้ให้บริการรายใด	การ inject ClientInterface แบบ PSR-18
การเสริมความปลอดภัยให้อินพุต (ขนาด base64 bomb meta-refresh)	CloudflareSecurityPolicy::validate()
การป้องกัน Server-side request forgery (SSRF) / Domain Name System (DNS)-rebinding	CloudflareSecurityPolicy::validateWorkerUrl() + assertPinsStillValid()
การ pin public key ของ Transport Layer Security (TLS) และการ pin DNS ที่ชั้น cURL	Transport\PinnedCurlTransport
การ fallback ไปยัง Chrome ในเครื่องเมื่อเข้าถึง Worker ไม่ได้	Contract\LocalRendererFactoryInterface
การแยกวิเคราะห์การตอบกลับแบบ binary และ JSON (base64)	CloudflareResponseParser
telemetry จาก edge (เวลาในการเรนเดอร์ ตำแหน่ง edge ความสูงของเนื้อหา)	CloudflareRenderResult
ฟอนต์กำหนดเองจาก R2 bucket	CloudflareRenderPayload (r2FontBucket, fontFiles)
ชั้นป้องกัน Application Programming Interface (API) (การยืนยันตัวตนด้วยคีย์ ขนาด payload การจำกัดอัตรา)	ApiProtection
การจัดเก็บ PDF ลง R2 ผ่าน API ที่เข้ากันได้กับ S3	R2ArchiveManager

ทุกแถวเชื่อมโยงกับคลาสหนึ่งใน namespace NextPDF\Cloudflare และได้รับการตรวจสอบเทียบกับพฤติกรรมและการทดสอบของคลาสนั้น ไม่ใช่เทียบกับเอกสารข้อกำหนด

สิ่งที่ทำไม่ได้

• bridge ไม่ได้รันเบราว์เซอร์เอง Worker เป็นผู้รันแทน
• bridge ไม่ได้ดีพลอยหรือกำหนดค่า Worker ของคุณ artifact นั้นเป็นความรับผิดชอบของคุณ
• bridge ไม่ได้ลงลายเซ็น PDF การลงลายเซ็นเป็นหน้าที่ของ nextpdf/core หรือรุ่นเชิงพาณิชย์ เมื่อต้องการลงลายเซ็น ให้เรนเดอร์ก่อน แล้วจึงลงลายเซ็น bytes ที่ได้รับกลับมาด้วยเอนจิน NextPDF Pro ให้บริการการลงลายเซ็นแบบ PAdES B-B ส่วนโปรไฟล์ long-term-validation เป็นความสามารถของรุ่น Enterprise
• bridge ไม่ได้ยืนยันความจุหรือขีดจำกัดใดๆ ของแพลตฟอร์ม Cloudflare ขีดจำกัดด้านขนาดและเวลาที่เอกสารนี้ระบุไว้มีเพียงขีดจำกัดที่แพ็กเกจนี้บังคับใช้ผ่านการกำหนดค่าของตนเอง (ดู /integrations/cloudflare/configuration/)

นโยบายความปลอดภัยสองชุด

bridge มีนโยบายความปลอดภัยสองชุดที่แตกต่างกันและเสริมกัน การนำทั้งสองชุดมาปะปนกันเป็นข้อผิดพลาดในการตรวจสอบที่พบบ่อยที่สุด รายละเอียดของแต่ละชุดมีดังนี้

• นโยบายความปลอดภัยของ HTML (HtmlSecurityPolicyInterface ค่าเริ่มต้นคือ NextPDF\Html\DefaultHtmlSecurityPolicy จัดหาโดย nextpdf/core) เป็นการกรองเนื้อหาที่ชั้น parse ซึ่งใช้ก่อนที่เนื้อหาจะไปถึง Worker เรียกใช้ได้ด้วย getHtmlSecurityPolicy()
• นโยบายความปลอดภัยของ Cloudflare (CloudflareSecurityPolicy เป็นแบบ static) ครอบคลุมประเด็นในชั้น transport ได้แก่ ขนาดอินพุต การตรวจจับ base64 decompression-bomb การบล็อก meta-refresh การบังคับใช้ HTTPS และการป้องกัน SSRF / DNS-rebinding สำหรับ URL ของ Worker

docblock ของ renderer ระบุการแยกส่วนนี้ไว้ หน้านี้จึงกล่าวย้ำอีกครั้ง เพราะผู้ตรวจสอบสำหรับการใช้งานจริงจำเป็นต้องเห็นชื่อทั้งสองบนหน้าจอเดียวกัน

โมเดลการเรนเดอร์ที่ edge

การเรียก render() เพียงครั้งเดียวจะดำเนินตามลำดับที่สังเกตได้ดังนี้ ลำดับนี้อ่านได้โดยตรงจาก CloudflareHtmlRenderer::render()

1. การตรวจสอบความครบถ้วนของการกำหนดค่า (workerUrl และ apiToken ต้องไม่ว่าง) หากการตรวจสอบล้มเหลว bridge จะ fallback ไปยัง renderer ในเครื่อง หรือไม่เช่นนั้นจะ throw CloudflareNotAvailableException
2. การตรวจสอบความถูกต้องของ HTML เทียบกับขนาดสูงสุดที่กำหนดค่าไว้ เพดานของ base64 URI และการห้าม meta-refresh
3. การตรวจสอบความถูกต้องของ URL ของ Worker ซึ่ง resolve โฮสต์และคืนค่าชุด IP ที่ผ่านการตรวจสอบแล้ว
4. การสร้าง payload (CloudflareRenderPayload)
5. การตรวจสอบซ้ำในช่วงใช้งาน (time-of-use) เพื่อยืนยันว่าคำตอบ DNS ของโฮสต์ไม่เปลี่ยนแปลงตั้งแต่ขั้นตอนที่ 3
6. HTTP POST จะถูกส่งผ่าน transport แบบ cURL ที่ pinned เมื่อมีชุด IP หรือชุด pin ของ Subject Public Key Info (SPKI) อยู่ และมีการจัดหา ResponseFactory แบบ PSR-17 มิฉะนั้นจะส่งผ่านไคลเอนต์ PSR-18 ที่ inject เข้ามา
7. การตอบกลับจะถูกแยกวิเคราะห์ให้เป็น CloudflareRenderResult

throwable ใดๆ นอกเหนือจาก CloudflareRenderException จะเข้าสู่เส้นทาง fallback CloudflareRenderException (ข้อผิดพลาด HTTP หรือการตอบกลับที่ผิดรูปแบบจาก Worker) จะถูก rethrow โดยไม่เปลี่ยนแปลง นี่เป็นความล้มเหลวฝั่ง Worker ไม่ใช่ความล้มเหลวด้านการเข้าถึง bridge จึงไม่ fallback

ดูเพิ่มเติม

• /integrations/cloudflare/install/ — ติดตั้งแพ็กเกจและไคลเอนต์ PSR-18
• /integrations/cloudflare/configuration/ — ฟิลด์การกำหนดค่าทั้งหมด พร้อมค่าเริ่มต้นที่ตรวจสอบจากซอร์สแล้ว
• /integrations/cloudflare/quickstart/ — ตัวอย่างการเรนเดอร์แรกที่รันได้ของคุณ
• /integrations/cloudflare/production-usage/ — fallback telemetry การจัดเก็บ R2 และการป้องกัน API
• /integrations/cloudflare/security-and-operations/ — รายละเอียดด้านการปฏิบัติงานสำหรับขอบเขตความเชื่อถือ
• /integrations/cloudflare/troubleshooting/ — รูปแบบความล้มเหลวที่จับคู่กับ exception
• /integrations/cloudflare/boot-and-discovery/ — วิธีที่ bridge เชื่อมต่อเข้ากับเฟรมเวิร์กโฮสต์
• /integrations/cloudflare/integration/ — การขับเคลื่อน NextPDF ผ่านบริการของ Cloudflare