Contracts / Observability

Sekilas

Domain observability mendefinisikan kontrak yang mengekspos status runtime mesin: ContextAwareExceptionInterface untuk konteks error terstruktur, SpectrumInterface untuk sidecar akselerasi opsional, JobNotificationInterface untuk progres job yang dialirkan, dan enum DegradationPolicy untuk perilaku ketika kapabilitas hilang.

Instalasi

composer require nextpdf/core:^3

Tinjauan konseptual

ContextAwareExceptionInterface adalah kontrak diagnostik. Setiap exception domain NextPDF mengimplementasikannya. Anda dapat melakukan cast setiap exception NextPDF yang tertangkap ke kontrak ini dan mengambil konteks terstruktur untuk alat Application Performance Monitoring (APM), pipeline logging, atau pelapor error. Konteks tersebut berupa array asosiatif dengan kunci snake_case dan hanya berisi nilai primitif. Konteks ini tidak memuat objek bersarang. Karena itu, konteks tersebut dapat diserialisasi secara terprediksi menjadi payload JavaScript Object Notation (JSON) atau payload APM. Anda tidak perlu mengurai pesan exception untuk memulihkan data diagnostik. Kontrak ini stable sejak 3.1.0.

SpectrumInterface adalah kontrak untuk sidecar akselerasi opsional. Spectrum menjalankan pekerjaan secara paralel pada central processing unit (CPU), dengan mengalihkan deteksi perangkat keras, penguraian Portable Document Format (PDF), dan kompresi gambar ke proses sidecar lokal. Kontrak ini melaporkan ketersediaan di balik circuit breaker, sehingga pemeriksaan kesehatan yang sering dilakukan tidak memperparah kegagalan saat sidecar mati. Kontrak ini memeriksa kapabilitas perangkat keras dan menyimpan hasilnya dalam cache. Kontrak ini mengekspos anggaran sumber daya yang sedang aktif. Kontrak ini juga menyediakan transport permintaan umum untuk modul tingkat lebih tinggi. Mesin tetap berfungsi tanpa sidecar. Kontrak ini menjadikan akselerasi sebagai opsi yang dapat diinjeksikan, bukan dependensi keras. JobNotificationInterface mengalirkan event job bertipe dari endpoint server-sent-events sidecar sebagai generator. Generator berhenti ketika event terminal tiba atau aliran ditutup.

DegradationPolicy adalah enum perilaku saat kapabilitas hilang. Ketika suatu kapabilitas terdegradasi, kebijakan ini memutuskan apakah akan melempar, memberi peringatan, atau mengumpulkan secara diam-diam, berdasarkan dampaknya. Strict melempar ketika dampaknya berupa risiko kepatuhan, kehilangan semantik, atau kondisi yang menghambat. Gunakan di lingkungan teregulasi ketika kebenaran keluaran bersifat wajib. Balanced, nilai standar, memancarkan peringatan terstruktur dan melanjutkan eksekusi untuk degradasi terbatas, serta hanya melempar pada dampak yang menghambat. Gunakan untuk sebagian besar penerapan produksi. Permissive mengumpulkan setiap event secara diam-diam dan tidak pernah melempar. Gunakan untuk mode pratinjau atau draf ketika keluaran upaya-terbaik dapat diterima. Tipe SpectrumInterface, JobNotificationInterface, dan DegradationPolicy bersifat experimental. Janji kompatibilitasnya lebih lemah daripada ContextAwareExceptionInterface.

Permukaan API

Tipe	Jenis	Anggota utama	Stabilitas	Sejak
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() hanya mengembalikan nilai primitif atau daftar nilai primitif. streamEvents() menghasilkan objek JobEvent hingga event terminal. SpectrumInterface::request() mengembalikan badan respons mentah sebagai string. probe() mengembalikan HardwareReport, dan getBudget() mengembalikan SpectrumBudget.

Contoh kode — Mulai cepat

examples/contracts/observability-quickstart.php

<?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());
}

Konteks terstruktur diteruskan ke catatan log tanpa perlu mengurai pesan.

Contoh kode — Produksi

examples/contracts/observability-production.php

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

SpectrumInterface nullable menjadikan akselerasi opsional. Kontrak ini mengekspos satu metode transport, request(), yang mengembalikan badan respons mentah sebagai string. Parser tingkat lebih tinggi mengubah badan tersebut menjadi NextPDF\Accelerator\BatchResult. Implementasi konkret SpectrumClient menambahkan helper bertipe seperti parseBatch() yang membungkus request() dan langsung mengembalikan BatchResult. Helper tersebut bukan bagian dari kontrak yang dibekukan. Kebijakan degradasi menentukan apakah ketiadaan sidecar bersifat fatal.

Kasus tepi & jebakan

• Tidak setiap \Throwable adalah exception NextPDF. Gunakan guard dengan instanceof ContextAwareExceptionInterface sebelum Anda memanggil getContext().
• getContext() hanya mengembalikan nilai primitif sesuai kontrak. Jika Anda mengharapkan objek bersarang, asumsi itu keliru; kontrak menjamin nilai yang aman untuk JSON.
• SpectrumInterface::isAvailable() berjalan di balik circuit breaker dan aman untuk sering dipanggil, tetapi hasil true hanya mencerminkan pemeriksaan pada satu titik waktu. Tangani kemungkinan sidecar terputus di antara pemeriksaan dan panggilan.
• JobNotificationInterface::streamEvents() adalah generator. Mengiterasikannya dua kali tidak memutar ulang event. Konsumsi hanya sekali.
• DegradationPolicy::Permissive tidak pernah melempar. Dalam mode itu, degradasi yang memengaruhi kepatuhan lolos secara diam-diam. Jangan menggunakannya untuk keluaran teregulasi.

Performa

Kontrak observability menambahkan overhead yang dapat diabaikan. getContext() mengembalikan array yang sudah dibangun sebelumnya. isAvailable() adalah probe kesehatan yang di-cache dan dilindungi circuit breaker. Kontrak mewajibkan implementasi menyimpan hasil probe dalam cache selama setidaknya 30 detik, sehingga jalur panas tidak memanggil sidecar berulang kali. streamEvents() dibatasi oleh laju event sidecar, bukan oleh mesin. Nilai performance_budget sebesar 1500 ms wall dan 64 MB puncak ditentukan oleh pekerjaan dasar yang diamati kontrak, bukan oleh kontrak itu sendiri. Profil reproducibility-nya adalah structural. Aliran event dan konteks exception menyertakan stempel waktu. Dua eksekusi akan berbeda pada bidang-bidang tersebut, sementara strukturnya tetap identik.

Catatan keamanan

Konteks exception terstruktur dapat menjadi permukaan eksfiltrasi data jika membawa rahasia. Kontrak membatasi konteks pada nilai primitif saja, sehingga membatasi kebocoran objek secara tidak sengaja. Anda tetap harus membersihkan nilai sensitif sebelum konteks mencapai sink log. Ini adalah kewajiban telemetri-aman dalam kebijakan logging proyek. Sidecar akselerasi adalah proses terpisah yang dijangkau melalui transport. Metode request membawa klaim scope untuk otorisasi. Anda harus memperlakukan batas sidecar sebagai batas kepercayaan. Kebijakan degradasi yang disetel ke Permissive dapat menutupi kehilangan kapabilitas yang relevan dengan keamanan. Gunakan Strict ketika kebenaran keluaran menjadi kontrol. Perlakukan konteks exception, event job, dan respons sidecar sebagai data yang mungkin tercatat, lalu bersihkan sesuai kebutuhan.

Konformansi

Halaman ini tidak menyatakan klaim normatif langsung apa pun. Kontrak observability mengekspos status mesin dan tidak mengimplementasikan protokol terstandarisasi yang klausanya perlu dikutip oleh mesin. Kewajiban telemetri-aman dan pembersihan log yang dirujuk di atas berasal dari kebijakan logging internal proyek, bukan dari standar eksternal. Ketika operasi yang diamati itu sendiri terstandarisasi — seperti tanda tangan atau dokumen PDF/A — konformansinya didokumentasikan pada halaman penandatanganan atau ekstraksi.

Lihat juga

• Contracts: 41 antarmuka publik (SPI) — gambaran SPI dan tingkat stabilitas.
• Observability — modul status runtime yang diekspos kontrak ini.
• Accelerator — klien sidecar Spectrum di balik SpectrumInterface.
• Exception — exception yang mengimplementasikan ContextAwareExceptionInterface.
• Performance — anggaran yang menjadi acuan bagi pekerjaan yang diamati.