Accelerator: klien sidecar Spectrum

Sekilas pandang

Modul Accelerator adalah klien sisi PHP untuk Spectrum, sidecar akselerasi di luar proses yang bersifat opsional. Klien ini adalah klien Hypertext Transfer Protocol (HTTP) yang diperkuat dengan circuit breaker, token kapabilitas JSON Web Token (JWT), satu kali percobaan ulang untuk kegagalan sementara, dan transport server-sent events untuk progres pekerjaan yang di-stream. Mesin tetap berfungsi tanpa sidecar. Gunakan modul ini untuk mengintegrasikan akselerasi tanpa menjadikannya wajib.

Stabilitas: eksperimental. Spectrum adalah sidecar opsional, bukan API publik yang dibekukan. SpectrumInterface yang diimplementasikannya didokumentasikan sebagai eksperimental di Contracts / Observability. Klien ini mengikuti tingkat stabilitas tersebut. Transport, format token, dan bentuk anggaran dapat berubah antarversi minor.

Pemasangan

composer require nextpdf/core:^3

Gambaran konseptual

Spectrum mengalihkan pekerjaan yang berat bagi prosesor ke proses sidecar lokal, termasuk deteksi perangkat keras, penguraian Portable Document Format (PDF), dan kompresi gambar. SpectrumClient adalah klien PHP Standards Recommendation 18 (PSR-18) yang mengimplementasikan NextPDF\Contracts\SpectrumInterface yang telah dibekukan. Klien ini bergantung pada ClientInterface, RequestFactoryInterface, dan StreamFactoryInterface, bukan pada tumpukan Hypertext Transfer Protocol (HTTP) yang ditanam permanen.

Klien berasumsi bahwa dependensi dapat gagal. Circuit breaker terbuka setelah tiga kegagalan berturut-turut. Selama terbuka, isAvailable() mengembalikan false selama jendela backoff eksponensial, sehingga jalur panas tidak terus-menerus memanggil sidecar yang tidak tersedia. Hasil probe di-cache dengan time-to-live (TTL). Ketika Anda mengonfigurasi rahasia aplikasi, setiap permintaan keluar membawa Request Capability Token. Token tersebut adalah JWT HS256 berumur pendek yang dibatasi pada kapabilitas yang dibutuhkan oleh endpoint. Masa berlakunya adalah 120 detik, atau 30 detik dalam mode otorisasi kendali-tinggi. Kesalahan 5xx sementara dan timeout dicoba ulang satu kali. Kesalahan autentikasi dan penguraian tidak pernah dicoba ulang.

SspectrumClient menyimpan state per instans. State circuit-breaker dan cache probe tidak dibagikan. Setiap worker PHP FastCGI Process Manager (PHP-FPM) sebaiknya memiliki instansnya sendiri. Hasil batch bertipe. BatchResult membawa entri BatchItem dengan BatchItemStatus, sebuah BatchSummary dengan tingkat keberhasilan, dan ID jejak opsional. HardwareReport dan HardwareCapabilities menjelaskan tingkatan perangkat keras yang terdeteksi. HardwareCapabilities::satisfies() memeriksa persyaratan tingkatan secara programatis. Enum DegradePolicy dan AuthorizationMode mengontrol perilaku saat kapabilitas hilang dan ketegasan token. Seluruh modul ini adalah @since 2.1.0.

Permukaan API

Tipe	Anggota utama	Peran
SpectrumClient	isAvailable(), probe(), getBudget(), request()	Klien sidecar PSR-18 yang mengimplementasikan SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Hasil batch bertipe
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Hasil per-item dan enum status
BatchSummary	isFullSuccess(), successRate()	Ringkasan agregat batch
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Kapabilitas sidecar yang terdeteksi
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Percabangan programatis berdasarkan kapabilitas
DegradePolicy / AuthorizationMode	kasus enum	Perilaku degradasi dan ketegasan token

Jalankan composer docs:generate-api-php -- --module=Accelerator untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

Lakukan probe pada sidecar melalui circuit breaker sebelum Anda mengandalkannya.

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

Contoh kode — Produksi

Kirim batch melalui sidecar ketika sidecar sehat, lalu beralih ke cadangan sesuai kebijakan degradasi saat tidak sehat.

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

Kasus tepi & jebakan

• isAvailable() adalah pemeriksaan pada satu titik waktu yang dijaga oleh circuit breaker. Hasil true dapat menjadi false sebelum panggilan berikutnya. Tangani sidecar yang terputus di antara panggilan.
• State untuk circuit breaker dan cache probe bersifat per instans. Berbagi satu SpectrumClient di antara worker membuat breaker tidak efektif. Berikan setiap worker instansnya sendiri.
• Token kapabilitas berumur pendek (120 s, 30 s dalam mode kendali-tinggi). Operasi yang berjalan lama harus memperoleh token baru, bukan menggunakan kembali token lama.
• Kesalahan autentikasi dan penguraian tidak pernah dicoba ulang; hanya respons 5xx sementara dan timeout yang dicoba ulang, dan hanya satu kali. Jangan berasumsi ada percobaan ulang idempoten di luar itu.
• SpectrumInterface yang null adalah state “tanpa akselerator” yang sah, bukan kesalahan. Kebijakan degradasi menentukan apakah hal itu fatal.

Performa

Klien hanya menambahkan overhead yang dapat diabaikan; pekerjaan sebenarnya dilakukan oleh sidecar. Circuit breaker adalah kontrol keandalan utama. Ia membatasi perjalanan bolak-balik yang sia-sia ketika sidecar tidak tersedia. performance_budget sebesar 1500 ms wall / 64 MB peak adalah beban kerja acuan mesin, bukan service-level agreement (SLA) sidecar. Profil reproduktibilitasnya adalah structural. Hasil batch membawa ID jejak dan stempel waktu, sehingga dua eksekusi berbeda pada field tersebut.

Catatan keamanan

Batas sidecar adalah batas kepercayaan. Ketika Anda mengonfigurasi rahasia aplikasi, permintaan membawa token kapabilitas HS256 yang dibatasi pada endpoint. Perlakukan rahasia tersebut sebagai kredensial dari secret manager, dan jangan pernah meng-commit-nya. Mode otorisasi kendali-tinggi memperpendek masa berlaku token menjadi 30 detik untuk endpoint sensitif. Uniform Resource Locator (URL) sidecar yang disediakan operator divalidasi saat konfigurasi dibangun, bukan pada permintaan pertama: hanya http:// dan https:// dengan host yang tidak kosong, atau unix:// dengan jalur soket yang tidak kosong, yang diterima; skema lain apa pun (gopher://, file://, ftp://, …) atau URL jaringan tanpa host gagal-tertutup saat konstruksi. Ini adalah pertahanan berlapis terhadap server-side request forgery (SSRF) dan egress yang tak terduga, sehingga endpoint yang salah konfigurasi tidak pernah mencapai klien HTTP. Respons sidecar adalah data eksternal. Validasi dan perlakukan sebagai tidak tepercaya sebelum respons itu masuk kembali ke mesin. Kelas kontrol-ekspor legal-review-required pada halaman ini mencerminkan bahwa fitur akselerasi membawa transport kriptografis dan sedang menunggu tinjauan kontrol-ekspor. Rujuk tinjauan tersebut sebelum Anda mendistribusikan ulang build yang mengaktifkannya.

Konformitas

Modul ini tidak membuat klaim normatif terhadap spesifikasi PDF. Ia adalah klien HTTP untuk protokol akselerasi internal. Protokol ini didefinisikan oleh mesin, bukan distandardisasi, sehingga tidak ada klausa untuk dikutip di sini. Bila pekerjaan sidecar (penguraian PDF, kompresi) memiliki aspek konformitas, konformitas tersebut didokumentasikan pada halaman modul yang relevan dan divalidasi oleh oracle serta golden suite di /modules/core/conformance/.

Lihat juga

• Contracts / Observability — SpectrumInterface yang diimplementasikan oleh klien ini.
• Modul Observability — permukaan state runtime untuk pekerjaan yang diakselerasi.
• Modul Performance — anggaran untuk pekerjaan yang diakselerasi.
• Model keamanan mesin