การบูตและการค้นพบของ NextPDF Gotenberg

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

bridge ไม่มีกลไกการค้นพบอัตโนมัติ คุณต้องสร้าง bridge เป็น service ปกติ โดยฉีด configuration value object และ collaborator แบบ Hypertext Transfer Protocol (HTTP) ที่กำหนดโดย PHP Standard Recommendation (PSR) ผ่าน constructor อย่างชัดเจน แพ็กเกจนี้ไม่ได้มาพร้อม service provider bundle หรือ container extension และไม่ได้อ่านตัวแปรสภาพแวดล้อมด้วยตนเอง ในที่นี้ “discovery” หมายถึงวิธีที่ host framework จัดเตรียม collaborator เหล่านั้น ความรับผิดชอบนี้เป็นของ framework ไม่ใช่ของแพ็กเกจนี้

bridge ถูกค้นพบได้อย่างไร

bridge จะไม่ถูกค้นพบโดยอัตโนมัติ คุณต้องสร้าง bridge เอง GotenbergBridge ต้องใช้อาร์กิวเมนต์สี่ตัว และรับอาร์กิวเมนต์เสริมได้อีกสามตัว:

จำเป็น: GotenbergConfig หนึ่งตัว, PSR-18 client หนึ่งตัว, PSR-17 request factory หนึ่งตัว และ PSR-17 stream factory หนึ่งตัว
ไม่บังคับ: PSR-3 logger หนึ่งตัว, นโยบายความปลอดภัยแบบ Hypertext Markup Language (HTML) หนึ่งรายการ (ค่าเริ่มต้นเป็นนโยบายเริ่มต้นของ NextPDF core) และ PSR-17 response factory หนึ่งตัว

response factory จะเปิดใช้ transport แบบ cURL-pinned เมื่อคุณจัดเตรียม response factory ไว้ หาก bridge มีสิ่งที่ต้อง pin (แอดเดรสที่ resolve แล้ว หรือ SubjectPublicKeyInfo (SPKI) pin ที่กำหนดค่าไว้) bridge จะใช้ transport แบบ pinning หากละเว้น response factory ไว้ จะใช้ PSR-18 client ที่ฉีดเข้ามาเสมอ contract ของอาร์กิวเมนต์ทั้งหมดอยู่ที่ /integrations/gotenberg/configuration/

ลำดับการบูต

ไม่มีขั้นตอนการลงทะเบียน วงจรชีวิตเป็นดังนี้:

host จะ resolve PSR-18 client และ PSR-17 factory โดย host container เป็นผู้ดำเนินการ ไม่ใช่แพ็กเกจนี้
แอปพลิเคชันจะสร้าง GotenbergConfig จากแหล่งกำหนดค่าของแอปพลิเคชัน GotenbergConfig::fromArray() รับอาร์เรย์แบบ snake_case และแทนที่ค่าที่ผิดรูปแบบด้วยค่าเริ่มต้น คุณควรตรวจสอบความถูกต้องของแหล่งข้อมูลใน boot path ของคุณ เพื่อให้ค่า Uniform Resource Locator (URL) ที่ขาดหายล้มเหลวตั้งแต่ช่วงบูต ไม่ใช่ระหว่างการแปลงแต่ละครั้ง
แอปพลิเคชันจะสร้าง GotenbergBridge ด้วย config และ collaborator
การเรียกแปลงครั้งแรกจะตรวจสอบความถูกต้องของ URL คัดกรอง server-side request forgery (SSRF) คัดกรองชื่อไฟล์ และส่งคำขอ ไม่มีงานใดเกิดขึ้นในช่วงสร้าง bridge เพราะ bridge จะอยู่นิ่งจนกว่าคุณจะเรียกใช้

การ binding ใน container

แพ็กเกจนี้ไม่ได้มาพร้อม container binding ใดๆ หากต้องการให้ฉีด bridge ได้ ให้ลงทะเบียน bridge ใน container ของ host application ของคุณดังนี้:

bind GotenbergConfig จากแหล่งกำหนดค่าของคุณ
bind PSR-18 client และ PSR-17 factory เข้ากับ implementation ที่คุณเลือก
bind GotenbergBridge เป็น service ที่รับ dependency เหล่านั้น

auto-wiring แบบ framework-native, การ publish config และการลงทะเบียน service-provider หรือ bundle เป็นหน้าที่ของแพ็กเกจ framework integration เฉพาะทาง ไม่ใช่ของแพ็กเกจนี้ แพ็กเกจนี้ออกแบบมาให้เป็น framework-agnostic และขึ้นกับ PSR interface เท่านั้น จึงทำงานได้ภายใต้ container ใดก็ได้

ลำดับการ resolve ค่ากำหนด

แพ็กเกจไม่ได้อ่านการกำหนดค่าใดๆ ด้วยตนเอง ลำดับการ resolve คือสิ่งที่แอปพลิเคชันของคุณนำไปใช้ก่อนเรียก GotenbergConfig::fromArray() หรือ constructor ลำดับที่พบบ่อยคือ ตัวแปรสภาพแวดล้อม ตามด้วยไฟล์ config ที่ publish แล้ว แล้วจึงเป็นค่าเริ่มต้นในโค้ด ลำดับนั้นเป็น contract ของแอปพลิเคชันของคุณ ไม่ใช่ของแพ็กเกจนี้ สิ่งที่แพ็กเกจกำหนดไว้คือ ค่าเริ่มต้น สำหรับแต่ละฟิลด์ที่อาร์เรย์ซึ่งส่งให้ fromArray() ละไว้ ได้แก่ application programming interface (API) URL ว่าง ค่า timeout 30 วินาที ขีดจำกัดขนาด 50 MiB คีย์ API ว่าง และรายการ pin ว่าง

การวินิจฉัย

มีสัญญาณในตัวสองอย่างที่ใช้ยืนยันการ wiring:

isAvailable() จะตรวจสอบความถูกต้องของ URL โดยไม่มีการรับส่งข้อมูลผ่านเครือข่าย จากนั้นส่งคำขอ HEAD ไปยัง <apiUrl>/health และรายงานว่าพร้อมใช้งานเมื่อสถานะต่ำกว่า 500 เมธอดนี้จะคืนค่า false แทนการ throw เมื่อเกิดความล้มเหลวใดๆ ให้เรียกเมธอดนี้จาก readiness check
การแปลงทดสอบ (smoke conversion) ของเอกสารขนาดเล็กที่ทราบว่าใช้งานได้ดีจะยืนยันเส้นทางทั้งหมดตั้งแต่ต้นจนจบ ซึ่งรวมถึงคำขอแบบ multipart ไปยัง <apiUrl>/forms/libreoffice/convert และการตรวจสอบความถูกต้องของ response

ดูเพิ่มเติม

/integrations/gotenberg/integration/ — การขับเคลื่อน pipeline ของ NextPDF ผ่าน service
/integrations/gotenberg/install/ — การติดตั้งแพ็กเกจและ service
/integrations/gotenberg/configuration/ — contract ของ constructor และ config ทั้งหมด
/integrations/gotenberg/overview/ — flow การแปลงและโมเดล dependency