Accelerator: trình khách sidecar Spectrum

Tổng quan nhanh

Mô-đun Accelerator là trình khách phía PHP cho Spectrum, một sidecar tăng tốc ngoài tiến trình và không bắt buộc. Đây là trình khách Hypertext Transfer Protocol (HTTP) được gia cố bằng circuit breaker, các token năng lực JSON Web Token (JWT), một lần thử lại cho lỗi thoáng qua và kênh server-sent events cho tiến trình công việc dạng luồng. Engine vẫn hoạt động khi không có sidecar. Hãy dùng mô-đun này để bổ sung khả năng tăng tốc mà không biến nó thành phụ thuộc bắt buộc.

Độ ổn định: thử nghiệm. Spectrum là một sidecar tùy chọn, không phải một application programming interface (API) công khai cố định. SpectrumInterface mà nó triển khai được ghi tài liệu là thử nghiệm trên Contracts / Observability. Trình khách này tuân theo cùng cấp ổn định đó. Kênh truyền, định dạng token và hình thái ngân sách có thể thay đổi giữa các phiên bản minor.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Spectrum chuyển các công việc nặng về bộ xử lý sang một tiến trình sidecar cục bộ, bao gồm phát hiện phần cứng, phân tích Portable Document Format (PDF) và nén ảnh. SpectrumClient là trình khách PHP Standards Recommendation 18 (PSR-18) triển khai NextPDF\Contracts\SpectrumInterface đã cố định. Nó phụ thuộc vào một ClientInterface, một RequestFactoryInterface và một StreamFactoryInterface, thay vì bị gắn cứng với một stack Hypertext Transfer Protocol (HTTP).

Trình khách giả định rằng phụ thuộc này có thể lỗi. Một circuit breaker sẽ mở sau ba lần lỗi liên tiếp. Khi đang mở, isAvailable() trả về false trong một khoảng backoff theo cấp số nhân, nhờ đó một đường dẫn nóng sẽ không liên tục gọi vào sidecar không khả dụng. Kết quả thăm dò được lưu vào bộ nhớ đệm với một time-to-live (TTL). Khi bạn cấu hình một app secret, mọi yêu cầu đi ra đều mang theo một Request Capability Token. Token là JWT HS256 tồn tại ngắn, được giới hạn phạm vi theo các năng lực mà endpoint yêu cầu. Thời gian sống của token là 120 giây, hoặc 30 giây ở chế độ ủy quyền kiểm soát cao. Các lỗi 5xx thoáng qua và lỗi hết thời gian chờ được thử lại một lần. Các lỗi xác thực và lỗi phân tích thì không bao giờ được thử lại.

SspectrumClient giữ trạng thái riêng cho từng thực thể. Trạng thái circuit breaker và bộ nhớ đệm thăm dò không được chia sẻ. Mỗi worker PHP FastCGI Process Manager (PHP-FPM) nên giữ thực thể riêng của mình. Kết quả theo lô có kiểu rõ ràng. BatchResult mang theo các mục BatchItem kèm một BatchItemStatus, một BatchSummary kèm tỷ lệ thành công, và một trace ID tùy chọn. HardwareReport và HardwareCapabilities mô tả cấp phần cứng đã phát hiện. HardwareCapabilities::satisfies() kiểm tra một yêu cầu về cấp bằng lập trình. Các enum DegradePolicy và AuthorizationMode kiểm soát hành vi khi mất năng lực và mức độ nghiêm ngặt của token. Toàn bộ mô-đun này là @since 2.1.0.

Bề mặt API

Kiểu	Thành viên chính	Vai trò
`SpectrumClient`	`isAvailable()`, `probe()`, `getBudget()`, `request()`	Trình khách sidecar PSR-18 triển khai `SpectrumInterface`
`BatchResult`	`getItems()`, `getSummary()`, `filterByStatus()`, `traceId()`	Kết quả theo lô có kiểu
`BatchItem` / `BatchItemStatus`	`isOk()`, `isSuccessful()`, `isRetryable()`	Kết quả từng mục và enum trạng thái
`BatchSummary`	`isFullSuccess()`, `successRate()`	Bản tóm tắt tổng hợp theo lô
`HardwareReport`	`hasPro()`, `hasEnterprise()`, `isApiVersionCompatible()`	Các năng lực sidecar đã phát hiện
`HardwareCapabilities`	`hasGpu()`, `satisfies()`, `bestAvailableTier()`	Rẽ nhánh theo năng lực bằng lập trình
`DegradePolicy` / `AuthorizationMode`	các case của enum	Hành vi suy giảm và mức độ nghiêm ngặt của token

Chạy composer docs:generate-api-php -- --module=Accelerator để tạo bảng PHPDoc đầy đủ.

Mẫu mã — bắt đầu nhanh

Hãy thăm dò sidecar qua circuit breaker trước khi dựa vào nó.

<?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.';
}

Mẫu mã — Production

Gửi một lô qua sidecar khi nó hoạt động bình thường, và quay về phương án dự phòng theo chính sách suy giảm khi nó không hoạt động bình thường.

<?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 '';
    }
}

Trường hợp đặc biệt & lưu ý

isAvailable() là phép kiểm tra tại một thời điểm, có circuit breaker. Một kết quả true có thể trở thành false trước lần gọi tiếp theo. Hãy xử lý trường hợp sidecar bị ngắt giữa các lần gọi.
Trạng thái circuit breaker và bộ nhớ đệm thăm dò là riêng cho mỗi thực thể. Dùng chung một SpectrumClient giữa nhiều worker sẽ vô hiệu hóa breaker. Hãy cấp cho mỗi worker một thực thể riêng.
Các token năng lực tồn tại ngắn (120 s, 30 s ở chế độ kiểm soát cao). Một thao tác chạy dài phải lấy một token mới, không tái sử dụng token cũ.
Các lỗi xác thực và lỗi phân tích không bao giờ được thử lại; chỉ các phản hồi 5xx thoáng qua và lỗi hết thời gian chờ mới được thử lại, và chỉ một lần. Đừng giả định rằng có thể thử lại theo kiểu idempotent ngoài phạm vi đó.
Một SpectrumInterface null là một trạng thái “không có accelerator” hợp lệ, không phải lỗi. Chính sách suy giảm quyết định liệu điều đó có nghiêm trọng hay không.

Hiệu năng

Trình khách chỉ thêm rất ít chi phí phụ; sidecar mới là nơi thực hiện công việc. Circuit breaker là cơ chế kiểm soát độ tin cậy chính. Nó hạn chế các lượt đi-về lãng phí khi sidecar không khả dụng. performance_budget 1500 ms thời gian thực / đỉnh 64 MB là khối lượng công việc tham chiếu của engine, không phải một service-level agreement (SLA) của sidecar. Hồ sơ khả năng tái lập là structural. Một kết quả theo lô mang theo một trace ID và các dấu thời gian, nên hai lần chạy sẽ khác nhau ở những trường đó.

Ghi chú bảo mật

Ranh giới sidecar là một ranh giới tin cậy. Khi bạn cấu hình một app secret, các yêu cầu sẽ mang theo các token năng lực HS256 được giới hạn phạm vi theo endpoint. Hãy coi secret đó như thông tin xác thực lấy từ trình quản lý secret, và không bao giờ commit nó. Chế độ ủy quyền kiểm soát cao rút ngắn thời gian sống của token xuống còn 30 giây cho các endpoint nhạy cảm. Uniform Resource Locator (URL) sidecar do người vận hành cung cấp được kiểm tra khi cấu hình được khởi tạo, chứ không phải ở yêu cầu đầu tiên: chỉ http:// và https:// với host không rỗng, hoặc unix:// với đường dẫn socket không rỗng, mới được chấp nhận; mọi scheme khác (gopher://, file://, ftp://, …) hoặc một URL mạng không có host sẽ fail closed ngay khi khởi tạo. Đây là lớp phòng thủ theo chiều sâu chống lại server-side request forgery (SSRF) và lưu lượng đi ra ngoài ý muốn, nên một endpoint bị cấu hình sai sẽ không bao giờ đến được trình khách HTTP. Các phản hồi từ sidecar là dữ liệu bên ngoài. Hãy kiểm tra chúng và coi chúng là không đáng tin cậy trước khi đưa chúng trở lại engine. Lớp kiểm soát xuất khẩu legal-review-required trên trang này phản ánh rằng tính năng tăng tốc có sử dụng truyền tải mã hóa và đang chờ một đợt rà soát kiểm soát xuất khẩu. Hãy tham khảo đợt rà soát đó trước khi bạn phân phối lại một bản dựng có bật tính năng này.

Tuân thủ

Mô-đun này không đưa ra tuyên bố quy chuẩn nào về đặc tả PDF. Đây là trình khách HTTP cho một giao thức tăng tốc nội bộ. Giao thức này do engine định nghĩa, không được chuẩn hóa, nên không có điều khoản nào để trích dẫn ở đây. Khi công việc của sidecar (phân tích PDF, nén) có khía cạnh tuân thủ, mức độ tuân thủ đó được ghi tài liệu trên trang mô-đun liên quan và được kiểm chứng bằng oracle cùng các bộ golden trong /modules/core/conformance/.

Xem thêm

Contracts / Observability — SpectrumInterface mà trình khách này triển khai.
Mô-đun Observability — bề mặt trạng thái lúc chạy cho công việc được tăng tốc.
Mô-đun Performance — ngân sách cho công việc được tăng tốc.
Mô hình bảo mật của engine