Contracts / gözlemlenebilirlik

Bir bakışta

Gözlemlenebilirlik etki alanı, motorun çalışma zamanı durumunu görünür kılan sözleşmeleri tanımlar: yapılandırılmış hata bağlamı için ContextAwareExceptionInterface, isteğe bağlı hızlandırma yardımcı bileşeni için SpectrumInterface, akıştaki iş ilerlemesi için JobNotificationInterface ve yetenek kaybı davranışı için DegradationPolicy enum’u.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

ContextAwareExceptionInterface, tanılama sözleşmesidir. Her NextPDF etki alanı istisnası bu sözleşmeyi uygular. Yakalanan herhangi bir NextPDF istisnasını bu sözleşmeye dönüştürebilir ve uygulama performansı izleme (APM) aracı, günlük kaydı işlem hattı veya hata raporlayıcı için yapılandırılmış bağlamı alabilirsiniz. Bağlam, snake_case anahtarlardan ve yalnızca ilkel değerlerden oluşan ilişkisel bir dizidir. İç içe nesne içermez. Bu nedenle, JavaScript Object Notation (JSON) yükü veya APM yükü olarak öngörülebilir biçimde serileştirilir. Tanılama verilerine erişmek için istisna iletisini ayrıştırmanız gerekmez. 3.1.0 sürümünden beri stable durumdadır.

SpectrumInterface, isteğe bağlı hızlandırma yardımcı bileşeninin sözleşmesidir. Spectrum, işi merkezi işlem birimi (CPU) üzerinde paralel yürütür; donanım algılamayı, Portable Document Format (PDF) ayrıştırmayı ve görüntü sıkıştırmayı yerel bir yardımcı bileşen sürecine devreder. Sözleşme, kullanılabilirliği bir devre kesicinin arkasından bildirir; böylece yardımcı bileşen kapalıyken sık yapılan durum denetimleri arızayı büyütmez. Donanım yeteneklerini yoklar ve sonucu önbelleğe alır. Etkin kaynak bütçesini görünür kılar. Ayrıca üst düzey modüller için genel bir istek taşıma kanalı sağlar. Motor, yardımcı bileşen olmadan da çalışır. Sözleşme, hızlandırmayı zorunlu bir bağımlılık olmaktan çıkarıp enjekte edilebilir bir seçenek haline getirir. JobNotificationInterface, yardımcı bileşenin server-sent-events uç noktasından türlenmiş iş olaylarını üreteç olarak akışa verir. Üreteç, sonlandırıcı olay geldiğinde veya akış kapandığında durur.

DegradationPolicy, yetenek kaybı davranışını belirleyen enum’dur. Bir yetenek düştüğünde ilke; etkiye göre istisna atmaya, uyarı yaymaya veya sessizce toplamaya karar verir. Strict, etki bir uyumluluk riski, anlamsal kayıp ya da engelleyici durum olduğunda istisna atar. Çıktı doğruluğunun zorunlu olduğu, düzenlemeye tabi ortamlarda bunu kullanın. Varsayılan Balanced, sınırlı düşürme durumunda yapılandırılmış uyarılar yayar ve devam eder; yalnızca engelleyici etki varsa istisna atar. Çoğu üretim dağıtımı için bunu kullanın. Permissive, her olayı sessizce toplar ve hiçbir zaman istisna atmaz. En iyi çaba çıktısının kabul edilebilir olduğu önizleme veya taslak modunda bunu kullanın. SpectrumInterface, JobNotificationInterface ve DegradationPolicy türleri experimental durumdadır. Uyumluluk vaatleri ContextAwareExceptionInterface türüne göre daha zayıftır.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Hangi sürümden beri
`ContextAwareExceptionInterface`	interface	`getContext(): array<string, mixed>`	stable	3.1.0
`SpectrumInterface`	interface	`isAvailable()`, `probe()`, `getBudget()`, `request()`	experimental	2.1.0
`JobNotificationInterface`	interface	`streamEvents(string): Generator<int, JobEvent>`	experimental	2.2.0
`DegradationPolicy`	enum (string)	`Strict`, `Balanced`, `Permissive`	experimental	2.3.0

getContext(), yalnızca ilkel değerler veya ilkel değer listeleri döndürür. streamEvents(), sonlandırıcı olaya kadar JobEvent nesneleri üretir. SpectrumInterface::request(), ham yanıt gövdesini string olarak döndürür. probe(), bir HardwareReport döndürür; getBudget() ise bir SpectrumBudget döndürür.

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\ContextAwareExceptionInterface;
use Psr\Log\LoggerInterface;

/**
 * Log a NextPDF exception with its structured context.
 *
 * @param \Throwable      $e      A caught exception.
 * @param LoggerInterface $logger A PSR-3 logger.
 */
function logWithContext(\Throwable $e, LoggerInterface $logger): void
{
    if ($e instanceof ContextAwareExceptionInterface) {
        $logger->error($e->getMessage(), $e->getContext());

        return;
    }

    $logger->error($e->getMessage());
}

Yapılandırılmış bağlam, ileti ayrıştırmaya gerek kalmadan günlük kaydına aktarılır.

Kod örneği — üretim

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\DegradationPolicy;
use NextPDF\Contracts\SpectrumInterface;
use Psr\Log\LoggerInterface;

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

    /**
     * Send a parse batch to the sidecar when healthy, otherwise fall back.
     *
     * @param list<array{id: string, data: string}> $documents PDF binaries with caller IDs.
     *
     * @return string Raw sidecar response body; decode with a batch-result parser.
     */
    public function parse(array $documents): string
    {
        if ($this->spectrum?->isAvailable() === true) {
            return $this->spectrum->request(
                'POST',
                '/v1/parse',
                json: ['documents' => $documents],
                scope: ['parse'],
            );
        }

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

        $this->logger->info('Accelerator unavailable; using PHP fallback.');

        return $this->phpFallback($documents);
    }

    /** @param list<array{id: string, data: string}> $documents @return string */
    private function phpFallback(array $documents): string
    {
        // Pure-PHP parse path omitted for brevity.
        return '';
    }
}

Null değer alabilen SpectrumInterface, hızlandırmayı isteğe bağlı kılar. Sözleşme, request() adlı tek bir taşıma yöntemini açığa çıkarır; bu yöntem ham yanıt gövdesini string olarak döndürür. Üst düzey bir ayrıştırıcı, bu gövdeyi bir NextPDF\Accelerator\BatchResult nesnesine dönüştürür. Somut SpectrumClient, parseBatch() gibi türlenmiş yardımcılar ekler; bu yardımcılar request() yöntemini sarar ve doğrudan BatchResult döndürür. Bu yardımcılar, dondurulmuş sözleşmenin parçası değildir. Düşürme ilkesi, eksik bir yardımcı bileşenin önemli olup olmadığına karar verir.

Uç durumlar ve tuzaklar

Her \Throwable bir NextPDF istisnası değildir. Önce instanceof ContextAwareExceptionInterface ile koruma uygulayın, ardından getContext() yöntemini çağırın.
getContext(), sözleşme gereği yalnızca ilkel değerler döndürür. İç içe nesneler bekliyorsanız bu varsayım yanlıştır; sözleşme JSON açısından güvenli değerleri garanti eder.
SpectrumInterface::isAvailable(), bir devre kesicinin arkasında çalışır ve sık çağrılması güvenlidir; ancak true sonucu, belirli bir andaki denetimdir. Denetim ile çağrı arasında düşen bir yardımcı bileşeni ele alın.
JobNotificationInterface::streamEvents(), bir üreteçtir. Üzerinde iki kez yinelemek olayları yeniden oynatmaz. Akışı bir kez tüketin.
DegradationPolicy::Permissive hiçbir zaman istisna atmaz. Bu modda, uyumluluğu etkileyen bir düşürme sessizce geçer. Düzenlemeye tabi çıktılar için bunu kullanmayın.

Performans

Gözlemlenebilirlik sözleşmeleri ihmal edilebilir düzeyde maliyet ekler. getContext(), önceden oluşturulmuş bir dizi döndürür. isAvailable(), önbelleğe alınmış ve devre kesiciyle korunan bir durum yoklamasıdır. Sözleşme, uygulamaların yoklama sonucunu en az 30 saniye önbelleğe almasını gerektirir; böylece sık çalışan bir kod yolu yardımcı bileşeni tekrar tekrar çağırmaz. streamEvents(), motorla değil, yardımcı bileşenin olay hızıyla sınırlıdır. 1500 ms duvar süresi ve 64 MB tepe değerindeki performance_budget, sözleşmelerin kendisinden değil, sözleşmelerin gözlemlediği temel işten kaynaklanır. Yeniden üretilebilirlik profili structural şeklindedir. Olay akışları ve istisna bağlamları zaman damgaları içerir. İki çalıştırmada yapı aynı kalırken bu alanlar farklılık gösterebilir.

Güvenlik notları

Yapılandırılmış istisna bağlamı, gizli bilgiler taşıyorsa veri sızdırma yüzeyidir. Sözleşme, bağlamı ilkel değerlerle sınırlar; bu, kazara nesne sızıntısını kısıtlar. Bağlam günlük havuzuna ulaşmadan önce hassas değerleri yine de temizlemeniz gerekir. Bu, projenin günlük kaydı ilkesindeki güvenli telemetri yükümlülüğüdür. Hızlandırma yardımcı bileşeni, bir taşıma üzerinden erişilen ayrı bir süreçtir. İstek yöntemi, yetkilendirme için kapsam talepleri taşır. Yardımcı bileşen sınırını güven sınırı olarak ele almanız gerekir. Permissive olarak ayarlanmış bir düşürme ilkesi, güvenlikle ilgili bir yetenek kaybını maskeleyebilir. Çıktı doğruluğunun denetim konusu olduğu durumlarda Strict kullanın. İstisna bağlamını, iş olaylarını ve yardımcı bileşen yanıtlarını günlüğe kaydedilebilecek veriler olarak ele alın ve buna göre temizleyin.

Uygunluk

Bu sayfa doğrudan normatif bir iddiada bulunmaz. Gözlemlenebilirlik sözleşmeleri motor durumunu görünür kılar ve maddelere atıf gerektiren standartlaştırılmış bir protokol uygulamaz. Yukarıda atıfta bulunulan güvenli telemetri ve günlük temizleme yükümlülükleri, harici bir standarttan değil, projenin dahili günlük kaydı ilkesinden kaynaklanır. Gözlemlenen işlemin kendisi standartlaştırıldığında — bir imza, bir PDF/A belgesi — uygunluk imzalama veya ayıklama sayfasında belgelenir.

Ayrıca bakınız

Contracts: 41 genel arabirim (SPI) — SPI genel bakışı ve kararlılık katmanları.
Gözlemlenebilirlik — bu sözleşmelerin görünür kıldığı çalışma zamanı durumu modülü.
Accelerator — SpectrumInterface arkasındaki Spectrum yardımcı bileşen istemcisi.
Exception — ContextAwareExceptionInterface arabirimini uygulayan istisnalar.
Performance — gözlemlenen işin tabi olduğu bütçeler.