วงจรชีวิตเซสชันที่ปลอดภัยสำหรับ Worker บน NextPDF Connect

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

ใช้วงจรชีวิตเซสชันที่กำหนดขอบเขตตามคำขอสำหรับ PHP worker ที่ทำงานต่อเนื่องระยะยาว (RoadRunner, Swoole, Laravel Octane) แต่ละคำขอจะสร้างเซสชันเอกสารของตนเองและทำลายเซสชันนั้นหลังจาก output_pdf สถานะของฟอนต์ หน้า และ handle จะถูกจำกัดอยู่ภายในขอบเขตคำขอของ worker เครื่องมือที่เกี่ยวข้องได้แก่ create_pdf, set_font, add_text และ output_pdf — ทั้งหมดเป็น Core

การติดตั้ง

composer require nextpdf/server

เมื่อผูก transport แล้ว รูปแบบนี้จะทำงานเหมือนกันกับ transport ทุกแบบ

ภาพรวมเชิงแนวคิด

ตัวระบุ document_id คือ handle แบบทึบที่จำกัดขอบเขตไว้ที่คำขอเดียว ให้ยึดกฎเพียงข้อเดียว: สร้างต่อหนึ่งคำขอ ทำลายต่อหนึ่งคำขอ ห้ามแคชหรือใช้ร่วมกันเด็ดขาด เมื่อใช้ค่าเริ่มต้น destroy: true output_pdf จะเรนเดอร์เอกสารและปลดปล่อยเซสชันในขั้นตอนเดียวแบบ atomic คำขอถัดไปบน worker เดียวกันจะได้รับเซสชันใหม่ที่เป็นอิสระ ฟอนต์และเนื้อหาของเซสชันก่อนหน้าจะหายไป ผลลัพธ์ของเครื่องมือแต่ละรายการเป็นการตอบกลับของ transport ตามปกติ (PSR-18 §p2) โค้ดของเซิร์ฟเวอร์ถูกแยกอิสระโดยขอบเขตของ autoload (PSR-4 §3) session store เป็นสถานะข้ามคำขอเพียงอย่างเดียว โดยใช้ id เป็นคีย์

พื้นผิว API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชันต่อหนึ่งคำขอ	ปลอดภัย
`set_font`	กำหนดฟอนต์ที่ใช้งานอยู่ (ต่อหนึ่งเซสชัน)	ข้อควรระวัง
`add_text`	เขียนเนื้อหา	ข้อควรระวัง
`output_pdf`	เรนเดอร์และทำลายเซสชัน	ต้องอนุมัติ / ตรวจสอบ (base64)

หน้า แคตตาล็อกเครื่องมือ เป็นแหล่งอ้างอิงหลักที่ถือเป็นความจริง เครื่องมือที่ใช้ได้ขึ้นอยู่กับ tier ที่ติดตั้งไว้

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

คำขอที่ 1: create_pdf → set_font → add_text → output_pdf (destroy: true) คำขอที่ 2 บน worker เดียวกันจะเริ่มเซสชันใหม่ด้วย create_pdf id เดิมจะใช้ไม่ได้แล้ว ให้กำหนดฟอนต์อีกครั้งเนื่องจากฟอนต์ไม่ถูกส่งต่อไปด้วย

ตัวอย่างโค้ด — ระดับโปรดักชัน

ห่อหุ้มวงจรชีวิตไว้เพื่อให้การล้างทรัพยากรทำงานเสมอ:

เริ่มเซสชันเมื่อคำขอเริ่มต้น
สร้างเนื้อหา
ในบล็อกที่เทียบเท่ากับ finally ให้เรียก output_pdf ซึ่งจะทำลายเซสชัน หากใช้ destroy: false สำหรับโฟลว์การตรวจสอบหลังเอาต์พุต ให้ทำลายเซสชันอย่างชัดเจนแทน

ห้ามจัดเก็บ document_id ไว้ใน worker-global, static หรือคอนเทนเนอร์ที่ใช้ร่วมกันเด็ดขาด ห้ามส่งต่อ document_id ระหว่าง coroutine, fiber หรือตัวจัดการคำขอเด็ดขาด

กรณีขอบและจุดที่ต้องระวัง

การนำ id ที่ถูกทำลายแล้วกลับมาใช้ซ้ำ จะคืนค่าข้อผิดพลาด unknown-document สร้างเซสชันใหม่ต่อหนึ่งคำขอ
การลืมเรียก output_pdf หน่วยความจำจะเพิ่มขึ้นอย่างเงียบๆ จนกว่า TTL ของเซสชันจะหมดอายุหรือมีการเริ่มกระบวนการใหม่ ปิดวงจรชีวิตให้ครบเสมอ
ขีดจำกัดเซสชันภายใต้โหลด store มีเพดานสำหรับจำนวนเซสชันพร้อมกัน การทำลายอย่างทันท่วงทีช่วยให้อยู่ภายใต้เพดานนั้น
destroy: false โดยไม่ล้างทรัพยากร หน่วยความจำจะเพิ่มขึ้นทีละน้อย ใช้เฉพาะสำหรับโฟลว์การตรวจสอบหลังเอาต์พุตที่ชัดเจนเท่านั้น จากนั้นจึงทำลายเซสชัน
การใช้ id ร่วมกันข้ามคำขอที่ทำงานพร้อมกัน เป็น race condition ที่ทำให้เอาต์พุตเสียหาย แต่ละคำขอเป็นเจ้าของเซสชันของตนเอง

ประสิทธิภาพ

เอาต์พุตต่อหนึ่งคำขอมีขนาดเพียงไม่กี่ KB ประโยชน์คือหน่วยความจำของ worker ถูกจำกัดขอบเขตตลอดอายุการทำงานของ worker โปรไฟล์เป็นแบบ structural

หมายเหตุด้านความปลอดภัย

การแยกเซสชันออกจากกันยังเป็นคุณสมบัติด้านการรักษาความลับด้วย เนื้อหาจากคำขอหนึ่งจะไม่ไปถึงอีกคำขอหนึ่งเด็ดขาด เนื่องจาก handle ไม่ถูกใช้ร่วมกันและเซสชันถูกทำลายเมื่อสร้างเอาต์พุต

ความสอดคล้องตามมาตรฐาน

ข้อความ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
ผลลัพธ์ของเครื่องมือแต่ละรายการเป็นการตอบกลับของ transport ตามปกติ	PSR-18	§p2
โค้ดถูกแยกอิสระโดยการแมป class→file ของ autoload	PSR-4	§3

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — เครื่องมือทั้งหมดเป็น Core

ความพร้อมใช้งานของ transport

ช่องทางรับส่ง (Transport)	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	โดยทั่วไปมีกระบวนการ stdio หนึ่งกระบวนการต่อหนึ่ง worker
REST	ใช่	ขอบเขตของคำขอ HTTP สอดคล้องกับขอบเขตของเซสชัน
gRPC	ใช่	หนึ่งเซสชันต่อหนึ่งลำดับ RPC

ระดับความเสี่ยง HITL

create_pdf เป็นแบบ Safe set_font และ add_text เป็นแบบ Caution ส่วน output_pdf เป็นแบบ Approval Required และลดระดับลงเป็น Review ในโหมด base64 ใน worker นั้น เอาต์พุต base64 เป็นเส้นทางที่ใช้กันทั่วไปและไม่เพิ่ม gate ใดๆ (ระดับความเสี่ยง HITL)

ซอง JSON ของ confirmation gate

เอาต์พุต Base64 ของ worker:

{ "allowed": true }