Accelerator: ไคลเอนต์ไซด์คาร์สำหรับ Spectrum

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

โมดูล Accelerator คือไคลเอนต์ฝั่ง PHP สำหรับ Spectrum ซึ่งเป็นไซด์คาร์เร่งความเร็วแบบนอกกระบวนการที่เลือกใช้ได้ โมดูลนี้เป็นไคลเอนต์ Hypertext Transfer Protocol (HTTP) ที่เสริมความทนทาน พร้อม circuit breaker โทเคนความสามารถแบบ JSON Web Token (JWT) การลองใหม่หนึ่งครั้งสำหรับข้อผิดพลาดชั่วคราว และทรานสปอร์ตแบบ server-sent events สำหรับความคืบหน้าของงานแบบสตรีม เอนจินทำงานได้โดยไม่ต้องมีไซด์คาร์ ใช้โมดูลนี้เพื่อเพิ่มการเร่งความเร็วโดยไม่ทำให้ไซด์คาร์กลายเป็นข้อกำหนดบังคับ

ความเสถียร: ทดลอง (experimental) Spectrum เป็นไซด์คาร์ที่เป็นทางเลือก ไม่ใช่ application programming interface (API) สาธารณะที่ตรึงไว้ SpectrumInterface ที่โมดูลนี้ใช้งานถูกระบุว่าเป็นแบบ ทดลองใน Contracts / Observability ไคลเอนต์นี้เป็นไปตามระดับนั้น ทรานสปอร์ต รูปแบบของโทเคน และโครงสร้างของงบประมาณ อาจเปลี่ยนแปลงได้ระหว่างเวอร์ชันย่อย

การติดตั้ง

composer require nextpdf/core:^3

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

Spectrum ถ่ายโอนงานที่ใช้หน่วยประมวลผลสูงไปยังกระบวนการไซด์คาร์ในเครื่อง รวมถึงการตรวจหาฮาร์ดแวร์ การแยกวิเคราะห์ Portable Document Format (PDF) และการบีบอัดภาพ SpectrumClient เป็นไคลเอนต์ตามมาตรฐาน PHP Standards Recommendation 18 (PSR-18) ที่ใช้งาน NextPDF\Contracts\SpectrumInterface ซึ่งตรึงไว้แล้ว โมดูลนี้ขึ้นอยู่กับ ClientInterface RequestFactoryInterface และ StreamFactoryInterface ไม่ได้ผูกกับสแตก Hypertext Transfer Protocol (HTTP) ชุดใดชุดหนึ่งโดยเฉพาะ

ไคลเอนต์ถือว่าดีเพนเดนซีอาจล้มเหลวได้ circuit breaker จะเปิดหลังจากเกิดความล้มเหลวติดต่อกันสามครั้ง ขณะที่เปิดอยู่ isAvailable() จะคืนค่า false ตลอดช่วงเวลา exponential backoff เพื่อไม่ให้ hot path เรียกไซด์คาร์ที่ไม่พร้อมใช้งานซ้ำๆ ผลลัพธ์ของการตรวจสอบ (probe) จะถูกแคชไว้พร้อม time-to-live (TTL) เมื่อคุณกำหนดค่า app secret คำขอขาออกทุกรายการจะพา Request Capability Token ไปด้วย โทเคนเป็น HS256 JWT อายุสั้นที่จำกัดขอบเขตให้ตรงกับความสามารถที่ปลายทางต้องการ อายุการใช้งานคือ 120 วินาที หรือ 30 วินาทีในโหมดการอนุญาตแบบควบคุมสูง ข้อผิดพลาด 5xx ชั่วคราวและการหมดเวลาจะถูกลองใหม่หนึ่งครั้ง ข้อผิดพลาดด้านการพิสูจน์ตัวตนและการแยกวิเคราะห์จะไม่ถูกลองใหม่เลย

SspectrumClient เก็บสถานะแยกตามแต่ละอินสแตนซ์ สถานะของ circuit breaker และแคชของการตรวจสอบจะไม่ถูกใช้ร่วมกัน เวิร์กเกอร์ PHP FastCGI Process Manager (PHP-FPM) แต่ละตัวควรมีอินสแตนซ์ของตนเอง ผลลัพธ์แบบแบตช์มีชนิดข้อมูลชัดเจน BatchResult พารายการ BatchItem ที่มี BatchItemStatus มี BatchSummary พร้อมอัตราความสำเร็จ และ trace ID ที่เป็นทางเลือก HardwareReport และ HardwareCapabilities อธิบายระดับฮาร์ดแวร์ที่ตรวจพบ HardwareCapabilities::satisfies() ตรวจสอบข้อกำหนดของระดับด้วยโปรแกรม enum DegradePolicy และ AuthorizationMode ควบคุมพฤติกรรมเมื่อสูญเสียความสามารถและความเข้มงวดของโทเคน โมดูลทั้งหมดมีเครื่องหมาย @since 2.1.0 กำกับอยู่

ขอบเขตของ API

ชนิด	สมาชิกสำคัญ	บทบาท
SpectrumClient	isAvailable(), probe(), getBudget(), request()	ไคลเอนต์ไซด์คาร์ PSR-18 ที่ใช้งาน SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	ผลลัพธ์แบบแบตช์ที่กำหนดชนิด
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	ผลลัพธ์รายรายการและ enum สถานะ
BatchSummary	isFullSuccess(), successRate()	สรุปแบตช์แบบรวม
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	ความสามารถของไซด์คาร์ที่ตรวจพบ
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	การแยกสาขาตามความสามารถด้วยโปรแกรม
DegradePolicy / AuthorizationMode	เคสของ enum	พฤติกรรมการลดระดับการทำงานและความเข้มงวดของโทเคน

เรียกใช้ composer docs:generate-api-php -- --module=Accelerator เพื่อสร้างตาราง PHPDoc ฉบับเต็ม

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

ตรวจสอบไซด์คาร์ผ่าน circuit breaker ก่อนพึ่งพาการทำงานของไซด์คาร์

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Contracts\SpectrumInterface;

function describeAccelerator(SpectrumInterface $spectrum): string
{
    if ($spectrum->isAvailable() !== true) {
        return 'Accelerator unavailable; engine runs in pure-PHP mode.';
    }

    $report = $spectrum->probe();

    return $report->hasEnterprise() ? 'Enterprise accelerator tier active.' : 'Standard accelerator tier active.';
}

ตัวอย่างโค้ด — การใช้งานจริง

ส่งแบตช์ผ่านไซด์คาร์เมื่อไซด์คาร์ทำงานปกติ และถอยกลับไปทำงานตามนโยบายการลดระดับการทำงานเมื่อไซด์คาร์ผิดปกติ

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Accelerator\DegradePolicy;
use NextPDF\Contracts\SpectrumInterface;
use Psr\Log\LoggerInterface;

final readonly class AcceleratedCompressor
{
    public function __construct(
        private ?SpectrumInterface $spectrum,
        private DegradePolicy $policy,
        private LoggerInterface $logger,
    ) {}

    /** @param list<array{id: string, data: string}> $images @return string Raw sidecar body. */
    public function compress(array $images): string
    {
        if ($this->spectrum?->isAvailable() === true) {
            return $this->spectrum->request('POST', '/v1/compress', json: ['images' => $images], scope: ['compress']);
        }

        if ($this->policy === DegradePolicy::Strict) {
            throw new \RuntimeException('Accelerator required under the strict degrade policy.');
        }

        $this->logger->info('Spectrum unavailable; using PHP image path.');

        return '';
    }
}

กรณีขอบและข้อควรระวัง

• isAvailable() เป็นการตรวจสอบ ณ ช่วงเวลาหนึ่งและผ่าน circuit breaker ผลลัพธ์ true อาจกลายเป็น false ได้ก่อนการเรียกครั้งถัดไป ต้องจัดการกรณีที่ไซด์คาร์หลุดระหว่างการเรียก
• สถานะของ circuit breaker และแคชของการตรวจสอบแยกตามแต่ละอินสแตนซ์ การใช้ SpectrumClient ตัวเดียวร่วมกันข้ามเวิร์กเกอร์จะทำให้ breaker ทำงานได้ไม่ถูกต้อง ให้เวิร์กเกอร์แต่ละตัวมีอินสแตนซ์ของตนเอง
• โทเคนความสามารถมีอายุสั้น (120 วินาที 30 วินาทีในโหมดควบคุมสูง) การดำเนินงานที่ใช้เวลานานต้องขอโทเคนใหม่ ไม่ใช่นำโทเคนเดิมกลับมาใช้ซ้ำ
• ข้อผิดพลาดด้านการพิสูจน์ตัวตนและการแยกวิเคราะห์จะไม่ถูกลองใหม่เลย มีเพียงการตอบกลับ 5xx ชั่วคราวและการหมดเวลาเท่านั้นที่ถูกลองใหม่ และลองใหม่เพียงครั้งเดียว อย่าสันนิษฐานว่ามีการลองใหม่แบบ idempotent เพิ่มเติมจากนั้น
• ค่า null ของ SpectrumInterface คือสถานะ “ไม่มี accelerator” ที่ถูกต้อง ไม่ใช่ข้อผิดพลาด นโยบายการลดระดับการทำงานจะตัดสินว่าสถานะนั้นร้ายแรงถึงขั้นหยุดทำงานหรือไม่

ประสิทธิภาพ

ไคลเอนต์เพิ่มภาระเพียงเล็กน้อยจนแทบไม่มีนัยสำคัญ ไซด์คาร์เป็นผู้ทำงานหลัก circuit breaker คือกลไกควบคุมความน่าเชื่อถือหลัก circuit breaker จำกัดการเดินทางไป-กลับที่สูญเปล่าเมื่อไซด์คาร์ไม่พร้อมใช้งาน performance_budget ที่ 1500 ms wall / 64 MB peak คือเวิร์กโหลดอ้างอิงของเอนจิน ไม่ใช่ service-level agreement (SLA) ของไซด์คาร์ โปรไฟล์ความสามารถในการทำซ้ำเป็นแบบ structural ผลลัพธ์แบตช์พา trace ID และ timestamp มาด้วย ดังนั้นการรันสองครั้งจะต่างกันในฟิลด์เหล่านั้น

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

ขอบเขตของไซด์คาร์เป็นขอบเขตความเชื่อถือ เมื่อคุณกำหนดค่า app secret คำขอจะพาโทเคนความสามารถ HS256 ที่จำกัดขอบเขตให้ตรงกับปลายทางไปด้วย ปฏิบัติต่อ secret นั้นเสมือนข้อมูลรับรองจาก secret manager และห้าม commit ลงในโค้ดเด็ดขาด โหมดการอนุญาตแบบควบคุมสูงลดอายุของโทเคนลงเหลือ 30 วินาทีสำหรับปลายทางที่มีความอ่อนไหว Uniform Resource Locator (URL) ของไซด์คาร์ที่ผู้ดำเนินการกำหนดให้จะถูกตรวจสอบความถูกต้องเมื่อสร้างคอนฟิกูเรชัน ไม่ใช่ตอนส่งคำขอครั้งแรก โดยจะรับเฉพาะ http:// และ https:// ที่มีโฮสต์ไม่ว่างเปล่า หรือ unix:// ที่มีพาธของซ็อกเก็ตไม่ว่างเปล่า สคีมาอื่นใด (gopher://, file://, ftp://, …) หรือ URL เครือข่ายที่ไม่มีโฮสต์จะล้มเหลวแบบ fail closed ตอนสร้าง นี่คือการป้องกันแบบเป็นชั้น (defense-in-depth) ต่อ server-side request forgery (SSRF) และการส่งออกที่ไม่คาดคิด เพื่อให้ปลายทางที่กำหนดค่าผิดไม่ไปถึงไคลเอนต์ HTTP เลย การตอบกลับจากไซด์คาร์เป็นข้อมูลภายนอก ต้องตรวจสอบความถูกต้องและปฏิบัติต่อข้อมูลเหล่านั้นเสมือนเป็นข้อมูลที่ไม่น่าเชื่อถือก่อนนำกลับเข้าสู่เอนจิน คลาสการควบคุมการส่งออก legal-review-required บนหน้านี้สะท้อนว่าฟีเจอร์การเร่งความเร็วมีการรับส่งข้อมูลแบบเข้ารหัสลับและกำลังรอการตรวจสอบด้านการควบคุมการส่งออก โปรดปรึกษาผลการตรวจสอบนั้นก่อนแจกจ่ายบิลด์ที่เปิดใช้งานฟีเจอร์ดังกล่าวต่อ

ความสอดคล้องตามข้อกำหนด

โมดูลนี้ไม่ได้อ้างความสอดคล้องเชิงบรรทัดฐานต่อข้อกำหนด PDF ใดๆ โมดูลนี้เป็นไคลเอนต์ HTTP สำหรับโปรโตคอลการเร่งความเร็วภายใน โปรโตคอลนี้กำหนดโดยเอนจิน ไม่ได้เป็นมาตรฐาน จึงไม่มีข้ออ้างอิงบรรทัดฐานให้กล่าวถึงที่นี่ ในกรณีที่งานของไซด์คาร์ (การแยกวิเคราะห์ PDF การบีบอัด) มีมิติด้านความสอดคล้องตามข้อกำหนด ความสอดคล้องนั้นจะถูกบันทึกไว้ในหน้าโมดูลที่เกี่ยวข้อง และตรวจสอบความถูกต้องโดยชุดทดสอบ oracle และ golden ใน /modules/core/conformance/

ดูเพิ่มเติม

• Contracts / Observability — SpectrumInterface ที่ไคลเอนต์นี้ใช้งาน
• Observability module — ขอบเขตสถานะขณะรันสำหรับงานที่เร่งความเร็ว
• Performance module — งบประมาณสำหรับงานที่เร่งความเร็ว
• โมเดลความปลอดภัยของเอนจิน