Accelerator: Spectrum yardımcı bileşen istemcisi

Bir bakışta

Accelerator modülü, isteğe bağlı süreç dışı hızlandırma yardımcı bileşeni Spectrum’un PHP tarafındaki istemcisidir. Sağlamlaştırılmış bir Hypertext Transfer Protocol (HTTP) istemcisi olarak devre kesici, JSON Web Token (JWT) yetenek belirteçleri, geçici arızalar için tek bir yeniden deneme ve akışlı iş ilerlemesi için sunucu tarafından gönderilen olay taşıması içerir. Motor, yardımcı bileşen olmadan da çalışır. Hızlandırmayı zorunlu tutmadan eklemek için bu modülü kullanın.

Kararlılık: deneysel. Spectrum, isteğe bağlı bir yardımcı bileşendir; dondurulmuş genel bir uygulama programlama arabirimi (API) değildir. Uyguladığı SpectrumInterface arabirimi, Contracts / Observability sayfasında deneysel olarak belgelenmiştir. Bu istemci, söz konusu katmanı takip eder. Taşıma, belirteç biçimi ve bütçe yapısı alt sürümler arasında değişebilir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Spectrum, donanım algılama, Portable Document Format (PDF) ayrıştırma ve görüntü sıkıştırma gibi işlemci yoğunluklu işleri yerel bir yardımcı sürece aktarır. SpectrumClient, dondurulmuş NextPDF\Contracts\SpectrumInterface arabirimini uygulayan bir PHP Standards Recommendation 18 (PSR-18) istemcisidir. Sabit kodlanmış bir Hypertext Transfer Protocol (HTTP) yığınına değil, bir ClientInterface, bir RequestFactoryInterface ve bir StreamFactoryInterface arabirimine bağlıdır.

İstemci, bağımlı olduğu bileşenin başarısız olabileceğini varsayar. Bir devre kesici, art arda üç başarısızlığın ardından açılır. Açık olduğu sürece isAvailable(), üstel geri çekilme penceresi boyunca false döndürür; böylece sık kullanılan bir kod yolu, kullanılamayan bir yardımcı bileşeni sürekli çağırmaz. Yoklama sonucu, bir geçerlilik süresiyle (TTL) önbelleğe alınır. Bir uygulama gizli anahtarı yapılandırdığınızda, giden her istek bir Request Capability Token taşır. Belirteç, uç noktanın gerektirdiği yeteneklerle kapsamı sınırlanmış, kısa ömürlü bir HS256 JWT belirtecidir. Ömrü 120 saniyedir; yüksek denetimli yetkilendirme modunda ise 30 saniyedir. Geçici 5xx ve zaman aşımı hataları bir kez yeniden denenir. Kimlik doğrulama ve ayrıştırma hataları asla yeniden denenmez.

SspectrumClient, durumu her örnekte ayrı saklar. Devre kesici durumu ve yoklama önbelleği paylaşılmaz. Her PHP FastCGI Process Manager (PHP-FPM) çalışanı kendi örneğini tutmalıdır. Toplu iş sonuçları türlendirilmiştir. BatchResult, bir BatchItem girdisinin durumunu belirten BatchItemStatus ile birlikte girdileri, başarı oranına sahip bir BatchSummary ve isteğe bağlı bir izleme kimliği taşır. HardwareReport ve HardwareCapabilities, algılanan donanım katmanını açıklar. HardwareCapabilities::satisfies(), bir katman gereksinimini programlı olarak denetler. Söz konusu DegradePolicy ve AuthorizationMode sabit listeleri, yetenek kaybı davranışını ve belirteç katılığını denetler. Modülün tamamı @since 2.1.0 kapsamındadır.

API yüzeyi

Tür	Temel üyeler	Rol
SpectrumClient	isAvailable(), probe(), getBudget(), request()	PSR-18 yardımcı istemcisi; uyguladığı arabirim: SpectrumInterface
BatchResult	getItems(), getSummary(), filterByStatus(), traceId()	Türlendirilmiş toplu iş sonucu
BatchItem / BatchItemStatus	isOk(), isSuccessful(), isRetryable()	Öğe başına sonuç ve durum sabit listesi
BatchSummary	isFullSuccess(), successRate()	Toplu iş özeti
HardwareReport	hasPro(), hasEnterprise(), isApiVersionCompatible()	Algılanan yardımcı bileşen yetenekleri
HardwareCapabilities	hasGpu(), satisfies(), bestAvailableTier()	Programlı yetenek dallanması
DegradePolicy / AuthorizationMode	sabit liste durumları	Bozunma davranışı ve belirteç katılığı

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Accelerator komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Yardımcı bileşene güvenmeden önce devre kesici üzerinden yoklayı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.';
}

Kod örneği — üretim

Sağlıklıysa toplu işi yardımcı bileşen üzerinden gönderin; değilse bozunma ilkesi uyarınca yedeğe geçin.

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

Sınır durumları ve dikkat edilecek noktalar

• isAvailable(), belirli bir andaki devre kesici denetimli kontroldür. true sonucu, bir sonraki çağrıdan önce false olabilir. Çağrılar arasında devre dışı kalan bir yardımcı bileşeni ele alın.
• Devre kesici ve yoklama önbelleğinin durumu örnek başınadır. Tek bir SpectrumClient örneğini çalışanlar arasında paylaşmak kesicinin işlevini geçersiz kılar. Her çalışana kendi örneğini verin.
• Yetenek belirteçleri kısa ömürlüdür (120 sn, yüksek denetimli modda 30 sn). Uzun süren bir işlem, var olan bir belirteci yeniden kullanmak yerine yeni bir belirteç almalıdır.
• Kimlik doğrulama ve ayrıştırma hataları asla yeniden denenmez; yalnızca geçici 5xx yanıtları ve zaman aşımları yeniden denenir, o da yalnızca bir kez. Bunun ötesinde değişmez sonuçlu (idempotent) yeniden deneme varsaymayın.
• Bir SpectrumInterface değerinin null olması, bir hata değil, geçerli bir “hızlandırıcı yok” durumudur. Bunun ölümcül olup olmadığına bozunma ilkesi karar verir.

Performans

İstemci ihmal edilebilir düzeyde ek yük getirir; işi yardımcı bileşen yapar. Devre kesici, temel güvenilirlik denetimidir. Yardımcı bileşen kullanılamadığında boşa giden gidiş dönüşleri sınırlar. 1500 ms duvar saati süresi / 64 MB tepe değerindeki performance_budget, bir yardımcı bileşen hizmet düzeyi sözleşmesi (SLA) değil, motorun referans iş yüküdür. Yeniden üretilebilirlik profili structural şeklindedir. Bir toplu iş sonucu, bir izleme kimliği ve zaman damgaları taşır; bu nedenle iki çalıştırma bu alanlarda farklılık gösterir.

Güvenlik notları

Yardımcı bileşen sınırı bir güven sınırıdır. Bir uygulama gizli anahtarı yapılandırdığınızda, istekler uç noktaya göre kapsamı sınırlanmış HS256 yetenek belirteçleri taşır. Bu gizli anahtarı bir gizli anahtar yöneticisinden gelen kimlik bilgisi olarak değerlendirin ve asla commit’e dahil etmeyin. Yüksek denetimli yetkilendirme modu, hassas uç noktalar için belirteç ömrünü 30 saniyeye kısaltır. Operatör tarafından sağlanan yardımcı bileşen Tekdüzen Kaynak Konumlayıcısı (URL), ilk istekte değil, yapılandırma oluşturulurken doğrulanır: yalnızca boş olmayan bir ana bilgisayar adı içeren http:// ve https:// ya da boş olmayan bir soket yolu içeren unix:// kabul edilir; başka herhangi bir şema (gopher://, file://, ftp://, …) veya ana bilgisayar adı olmayan bir ağ URL’si oluşturma sırasında kapalı durumda başarısız olur. Bu, sunucu tarafı istek sahteciliğine (SSRF) ve beklenmeyen giden trafiğe karşı katmanlı bir savunmadır; böylece yanlış yapılandırılmış bir uç nokta HTTP istemcisine asla ulaşmaz. Yardımcı bileşen yanıtları dış verilerdir. Motora geri girmeden önce bunları doğrulayın ve güvenilmez olarak değerlendirin. Bu sayfadaki legal-review-required ihracat denetimi sınıfı, hızlandırma özelliğinin kriptografik taşıma içerdiğini ve bir ihracat denetimi incelemesinin beklendiğini yansıtır. Bu özelliği etkinleştiren bir derlemeyi yeniden dağıtmadan önce söz konusu incelemeye başvurun.

Uyumluluk

Bu modül, normatif bir PDF belirtimi iddiası taşımaz. Dahili bir hızlandırma protokolü için bir HTTP istemcisidir. Protokol standartlaştırılmamış, motor tarafından tanımlanmıştır; bu nedenle burada atıf yapılacak herhangi bir madde yoktur. Yardımcı bileşen işinin (PDF ayrıştırma, sıkıştırma) bir uyumluluk boyutu olduğu durumlarda, bu uyumluluk ilgili modül sayfasında belgelenir ve /modules/core/conformance/ içindeki oracle ve altın takımlarla doğrulanır.

Ayrıca bakınız

• Contracts / Observability — bu istemcinin uyguladığı SpectrumInterface.
• Observability module — hızlandırılmış işler için çalışma zamanı durumu yüzeyi.
• Performance module — hızlandırılmış işler için bütçeler.
• Motor güvenlik modeli