Enterprise รุ่น

Output Pipeline — เอกสารอ้างอิงเชิงลึก

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

NextPDF\Enterprise\OutputPipeline รันหลาย manifest ของไปป์ไลน์ Pro เป็น batch เดียว BatchPipelineOrchestrator ห่อ Pro PipelineExecutor ด้วยการประสานงาน batch ได้แก่ การ์ด bounded-resource ที่จำกัดขนาด batch, timeout ของ batch ทั่วโลกที่เป็นทางเลือก, การฉีด variable ต่อ manifest และการบัญชีแบบรวม การตรวจสอบ compliance ปลาย batch ที่เป็นทางเลือกจะตรวจสอบเอาต์พุตที่เสร็จสมบูรณ์ทุกไฟล์ซ้ำผ่านเกตเวย์ compliance ของ Enterprise และล้มเหลวแบบปิด (fail closed) การรันแต่ละครั้งคืนค่า BatchPipelineResult ที่บรรจุผลลัพธ์ต่อ manifest, จำนวนที่เสร็จสมบูรณ์และล้มเหลว, เวลา และรายงาน compliance ที่เป็นทางเลือก

ความพร้อมใช้งานและการอนุญาต

ความสามารถนี้จัดส่งใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

รุ่น	พื้นผิว output-pipeline
Core	ไม่มีพื้นผิว output-pipeline
Pro	ไปป์ไลน์ single-manifest (ความสามารถ `pro.output.pipeline`)
Enterprise	การประสานงาน batch, ขอบเขตขนาด batch, timeout ของ batch, การส่งต่อ compliance

พื้นผิว batch ของ Enterprise ไม่มีรหัสความสามารถต่อฟีเจอร์แยกต่างหาก ขอบเขตของแพ็กเกจเป็นตัวจำกัดสิทธิ์ ความสามารถ single-manifest ของ Pro pro.output.pipeline เป็นเงื่อนไขเบื้องต้น ไม่ใช่เกต ใบอนุญาต Pro เพียงอย่างเดียวปลดล็อกเฉพาะไปป์ไลน์ single-manifest ที่อยู่ภายใต้เท่านั้น ไม่ใช่พื้นผิว batch นี้

composer require nextpdf/enterprise:^3

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	ยกข้อยกเว้นหรือล้มเหลวด้วย	หมายเหตุ
`BatchPipelineOrchestrator::__construct()`	`PipelineExecutor $executor`, `BatchPipelineConfig $config`, `?ComplianceGateway $complianceGateway`, `ComplianceProfile $complianceProfile`	config เริ่มต้น; ไม่มีเกตเวย์; โปรไฟล์ `ComplianceProfile::PdfA4`	—	ไม่มี	ฉีดเกตเวย์เมื่อเปิดใช้การตรวจสอบ compliance; หากไม่มี ทุก manifest ที่ถูกตรวจสอบจะถูกรายงานว่าล้มเหลว
`BatchPipelineOrchestrator::executeBatch()`	`list<PipelineManifest> $manifests`, `array<string, array<string, mixed>> $variablesMap = []`	รัน manifest ตามลำดับการส่ง; variable แปลค่าตาม manifest ID	`BatchPipelineResult`	`OverflowException` เมื่อ batch เกิน 10,000 manifest; ข้อยกเว้นเกตเวย์เมื่อเปิดใช้การตรวจสอบ compliance (ดูกรณีขอบและโหมดความล้มเหลว)	`Throwable` จาก resolver ไม่เคยหลุดออก; ตัวรัน Pro ลดระดับให้เป็นผลลัพธ์ขั้นตอนที่ล้มเหลว
`BatchPipelineConfig::__construct()`	`int $maxConcurrency = 4`, `int $timeoutMs = 0`, `bool $complianceCheckOnComplete = false`	Concurrency 4; ไม่มี timeout; ไม่มีการตรวจสอบ compliance	—	ไม่มี	Value object แบบ readonly `timeoutMs = 0` ปิดใช้ timeout ของ batch
`BatchPipelineResult::__construct()`	`list<PipelineResult> $results`, `int $totalManifests`, `int $completedCount`, `int $failedCount`, `float $durationMs`, `?array $complianceReport = null`	รวมค่า `PipelineResult` ต่อ manifest	—	ไม่มี	Readonly `complianceReport` คงเป็น `null` เว้นแต่การตรวจสอบทำงาน
`BatchPipelineResult::allSucceeded()`	—	ทดสอบ `failedCount === 0`	`bool`	ไม่มี	คืนค่า true สำหรับ batch ที่ถูกตัดเพราะ timeout ที่มีศูนย์ความล้มเหลว; ดูกรณีขอบและโหมดความล้มเหลว
`BatchPipelineResult::successRate()`	—	`completedCount / totalManifests`	`float`	ไม่มี	คืนค่า `1.0` สำหรับ batch ว่าง
`BatchPipelineResult::hasComplianceReport()`	—	ทดสอบ `complianceReport !== null`	`bool`	ไม่มี	—

public function __construct(
    private readonly PipelineExecutor $executor,
    private readonly BatchPipelineConfig $config = new BatchPipelineConfig(),
    private readonly ?ComplianceGateway $complianceGateway = null,
    private readonly ComplianceProfile $complianceProfile = ComplianceProfile::PdfA4,
) {}

public function executeBatch(
    array $manifests,
    array $variablesMap = [],
): BatchPipelineResult

public function __construct(
    public int $maxConcurrency = 4,
    public int $timeoutMs = 0,
    public bool $complianceCheckOnComplete = false,
) {}

สัญญาพฤติกรรม

executeBatch() ก่อนอื่นจะตรวจสอบขนาด batch เทียบกับขีดจำกัดที่ 10,000 manifest batch ที่เกินขีดจำกัดจะยก OverflowException ก่อนที่ manifest ใดจะรัน ไม่มีสิ่งใดเสื่อมลงแบบเงียบ ๆ

จากนั้น manifest จะรันตามลำดับการส่งผ่าน Pro PipelineExecutor แต่ละ manifest รับรายการ variable ที่คีย์ด้วย ID ของมันใน $variablesMap; manifest ที่ไม่มีรายการจะได้รับแมป variable ว่าง manifest นับว่าเสร็จสมบูรณ์เมื่อสถานะ PipelineResult ของมันเป็น Completed; สถานะปลายทางอื่นใดนับว่าล้มเหลว ข้อยกเว้นจาก resolver ไม่หลุดออก: ตัวรัน Pro แปลง Throwable ทุกตัวจาก resolver ให้เป็นผลลัพธ์ขั้นตอนที่ล้มเหลว ดังนั้น executeBatch() จะรวมผลลัพธ์เสมอ แทนที่จะยกเลิกกลางคัน batch เมื่อเกิดข้อผิดพลาดขั้นตอน

เมื่อ timeoutMs มากกว่าศูนย์ เวลาที่ผ่านไปจะถูกตรวจสอบก่อนที่แต่ละ manifest จะเริ่ม เมื่องบประมาณหมดลง manifest ที่เหลือจะถูกข้าม: มันไม่สร้าง PipelineResult และไม่นับว่าเสร็จสมบูรณ์หรือล้มเหลว totalManifests รายงานจำนวนที่ส่งเข้ามาเสมอ

เมื่อเปิดใช้ complianceCheckOnComplete ตัวประสานงานจะตรวจสอบ PDF สุดท้ายของทุก manifest ที่เสร็จสมบูรณ์เทียบกับ ComplianceProfile ที่กำหนดค่าไว้ผ่าน ComplianceGateway ที่ฉีดเข้ามา การตรวจสอบล้มเหลวแบบปิด (fail closed):

ไม่ได้ฉีดเกตเวย์: ทุก manifest ที่ถูกตรวจสอบจะถูกรายงานว่าล้มเหลว เนื่องจาก compliance ไม่เคยถูกตรวจสอบ
ไม่มีเอาต์พุต PDF ที่แปลค่าได้จากเอาต์พุตขั้นตอนของ manifest: ล้มเหลว
เกตเวย์ไม่คืนผลลัพธ์ (ความไม่พร้อมของ sidecar ในโหมดทางเลือก): ล้มเหลว การไม่มีผลลัพธ์เชิงบวกไม่ถือเป็นการผ่าน
เกตเวย์รายงานความไม่สอดคล้องใด ๆ: ล้มเหลว

PDF สุดท้ายถูกแปลค่าโดยการสแกนเอาต์พุตขั้นตอนของ manifest ที่เสร็จสมบูรณ์ จากขั้นตอนสุดท้ายก่อน เพื่อหาค่า string โดยตรงที่ขึ้นต้นด้วยส่วนหัว %PDF เอาต์พุตขั้นตอนไม่เคยฝัง PDF byte-string ไว้ในซับอาร์เรย์; ตรวจสอบเฉพาะค่าเอาต์พุตโดยตรงเท่านั้น manifest ที่ไม่เสร็จสมบูรณ์จะถูกข้าม ไม่ถูกตรวจสอบ

รายงาน compliance เป็นอาร์เรย์ที่มีคีย์ profile, checked, passed, failed และ failures; แต่ละรายการความล้มเหลวบรรจุ manifestId และ reason รายงานแนบกับ BatchPipelineResult::$complianceReport และเข้าถึงได้ผ่าน hasComplianceReport()

การส่งต่อ compliance เป็นตัวช่วยตรวจสอบซ้ำ ไม่ใช่การควบคุมการอนุญาต มันรายงานเฉพาะข้อค้นพบเท่านั้น

กรณีขอบและโหมดความล้มเหลว

มากกว่า 10,000 manifest: OverflowException ก่อนที่การรันใด ๆ จะเริ่ม
timeoutMs = 0 หมายถึงไม่มี timeout ของ batch ตั้งค่าจำกัดในการใช้งานจริง
การตัดเพราะ timeout: manifest ที่ถูกข้ามไม่ปรากฏในจำนวนใด ดังนั้น completedCount + failedCount อาจน้อยกว่า totalManifests allSucceeded() ทดสอบเฉพาะ failedCount === 0 และอาจคืนค่า true สำหรับ batch ที่ถูกตัด เปรียบเทียบ count($result->results) กับ totalManifests เพื่อตรวจจับการตัด
successRate() คืนค่า 1.0 สำหรับ batch ว่าง (ส่ง manifest ศูนย์ตัว)
ID ของ manifest ไม่ถูกลบซ้ำที่ระดับ batch manifest สองตัวที่ใช้ ID ร่วมกันจะรันทั้งคู่และแปลค่ารายการ variable เดียวกัน
ข้อผิดพลาดเชิงโครงสร้างของ manifest (รายการขั้นตอนว่าง, ID ขั้นตอนซ้ำ, dependency ที่ไม่รู้จัก, วงจร dependency, ประเภทเอาต์พุตไม่ตรงกัน, ขาดขั้นตอน resume) จะยก InvalidArgumentException ตอนสร้าง manifest ก่อนที่ executeBatch() จะถูกเรียกด้วยซ้ำ
เมื่อเปิดใช้การตรวจสอบ compliance ComplianceGateway::validate() สามารถยก ComplianceSidecarUnavailableException (sidecar ไม่พร้อมในโหมดบังคับ) หรือ InvalidArgumentException (ไม่มี validator ที่ลงทะเบียนสำหรับเครื่องมือของโปรไฟล์) ข้อยกเว้นใดข้อหนึ่งจะหลุดออกจาก executeBatch() หลังการรันแต่ก่อนที่ผลลัพธ์จะถูกสร้าง ดังนั้นผลลัพธ์ต่อ manifest จะสูญหายต่อผู้เรียก ในโหมดทางเลือก เกตเวย์คืนค่า null แทน และ manifest จะถูกบันทึกเป็นความล้มเหลว compliance
ขั้นตอนการส่งต่อ compliance ภายในไปป์ไลน์จะล้มเหลวเมื่อไม่มีเอาต์พุตขั้นตอนต้นทางใดมี PDF byte ที่รู้จำได้; มันไม่เคยผ่านแบบเงียบ ๆ
โมดูลนี้ไม่ทำการดำเนินการเชิงการเข้ารหัสลับใด ๆ โหมด FIPS จึงไม่นำมาใช้

ความสอดคล้อง

ไม่มีการกล่าวอ้างความสอดคล้องตามมาตรฐานสำหรับโมดูลนี้ มันเป็นชั้นการประสานงาน การตรวจสอบ compliance ที่เป็นทางเลือกอ้างอิงเกตเวย์ compliance ของ Enterprise และ validator ภายนอกของมัน ซึ่งถือการอ้างอิงของตนเอง โปรไฟล์เริ่มต้นคือ ComplianceProfile::PdfA4; โปรไฟล์เกตเวย์อื่นครอบคลุมเป้าหมาย PDF/A, PDF/UA และ PAdES เพิ่มเติม

รายงาน compliance ระบุข้อค้นพบของ validator เทียบกับโปรไฟล์ที่เลือก มันไม่รับรองเอกสาร ไม่รับประกันความเพียงพอทางการกำกับดูแล และไม่ถือเป็นคำแนะนำทางกฎหมาย การตัดสินว่าเอาต์พุตเป็นไปตามภาระหน้าที่ของคุณหรือไม่เป็นความรับผิดชอบของคุณ

บันทึกการพัฒนา

ในการปรับใช้จริง การ dispatch worker แบบขนานและ backpressure ถูกจัดการโดย execution sidecar แยกต่างหาก ตัวประสานงาน PHP ให้การประสานงาน batch และตรรกะ compliance-handoff และถูกเรียกโดย job worker ไม่ใช่โดยตัวจัดการคำขอโดยตรง
เส้นทาง fallback ของ PHP รัน manifest ตามลำดับ maxConcurrency จำกัด worker callback ที่ทำงานพร้อมกันในการปรับใช้ที่ขับเคลื่อนด้วย sidecar การกำหนดขนาดเทียบกับ PHP worker pool เป็นความรับผิดชอบของผู้ปฏิบัติการ
ตัว resolver ขั้นตอนการส่งต่อ compliance ภายในไปป์ไลน์เป็นประเภทภายในที่ลงทะเบียนสำหรับขั้นตอนประเภท inspect เปิดใช้การตรวจสอบปลาย batch ผ่าน BatchPipelineConfig แทนที่จะสร้างขั้นตอนไปป์ไลน์สำหรับมันโดยตรง
สร้างอินสแตนซ์ PipelineManifest แต่เนิ่น ๆ การตรวจสอบเชิงโครงสร้างของมันทำงานในคอนสตรัคเตอร์ ดังนั้นกราฟที่ไม่ถูกต้องจะล้มเหลวเร็วและไม่เคยใช้งบประมาณ batch

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น internal namespace paths, คลาสตัวช่วย, ตารางกลไก, ชื่อไฟล์ runbook และ ticket prefixes อยู่นอกขอบเขต