Chaos: harness skenario ketahanan deterministik

Sekilas pandang

Modul Chaos menyediakan harness ringkas untuk pengujian ketahanan. Anda mendaftarkan skenario injeksi kesalahan yang mengimplementasikan antarmuka bermetode tunggal, menjalankannya, lalu mengumpulkan laporan lulus/gagal (pass/fail) terstruktur. Modul ini sengaja dijaga tetap kecil dengan lima kelas dan ditujukan untuk suite ketahanan serta latihan chaos-day, bukan untuk jalur produksi dokumen.

Stabilitas: eksperimental. Ini adalah permukaan perkakas pengujian dan ketahanan, bukan API inti Portable Document Format (PDF). Antarmuka penyedia layanan (SPI) berukuran kecil dan bentuknya stabil, tetapi cakupan modul dan skenario bawaannya masih terus berkembang. Jangan membangun alur kendali produksi di atasnya.

Pemasangan

composer require nextpdf/core:^3

Tinjauan konseptual

Pengujian ketahanan menilai apakah mesin menurun dengan benar saat dependensi gagal. Modul Chaos memberi struktur pada pengujian itu. ChaosScenarioInterface adalah kontrak skenario: name() mengidentifikasi skenario, dan simulate() mengembalikan ChaosOutcome. Setiap skenario merepresentasikan satu kesalahan, seperti partisi jaringan atau lonjakan respons 5xx dari backend pengambilan, dan melaporkan apa yang terjadi.

ChaosScenarioRunner mengorkestrasi eksekusinya. Anda register() skenario, memanggil run() untuk menjalankannya secara berurutan sesuai urutan pendaftaran, lalu membaca agregasi hasilnya dengan outcomes(), allPassed(), passCount(), dan failCount(). Runner tidak pernah melempar eksepsi karena kegagalan skenario: kegagalan adalah data yang ditangkap di dalam ChaosOutcome, bukan eksepsi. Runner hanya melempar eksepsi saat infrastrukturnya sendiri rusak, seperti pendaftaran skenario yang tidak valid atau ketidakmampuan menulis berkas laporan (ChaosReportWriteException). Skenario yang tidak dapat menjangkau sumber daya yang sedang diuji akan memunculkan RetrievalUnavailableException. Modul ini @since 3.2.0.

ChaosOutcome menyimpan hasil per skenario: status pass/fail, durasi, dan keluaran toArray() untuk laporan terstruktur. Karena hasil mencatat durasi waktu nyata (wall-clock), profil reproduksibilitas laporan bersifat structural, bukan bitwise.

Permukaan API

Tipe	Anggota utama	Peran
ChaosScenarioInterface	name(): string, simulate(): ChaosOutcome	Kontrak skenario (@since 3.2.0)
ChaosScenarioRunner	register(), run(), outcomes(), allPassed(), passCount(), failCount()	Orkestrator skenario sekuensial (@since 3.2.0)
ChaosOutcome	durationSeconds(), toArray()	Hasil lulus/gagal (pass/fail) per skenario (@since 3.2.0)
RetrievalUnavailableException	—	Sumber daya yang diuji tidak dapat dijangkau
ChaosReportWriteException	—	Berkas laporan tidak dapat ditulis

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

Contoh kode — Mulai cepat

Daftarkan skenario, lalu jalankan suite-nya.

<?php

declare(strict_types=1);

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

use NextPDF\Chaos\ChaosOutcome;
use NextPDF\Chaos\ChaosScenarioInterface;
use NextPDF\Chaos\ChaosScenarioRunner;

final class TimeoutScenario implements ChaosScenarioInterface
{
    public function name(): string
    {
        return 'dependency-timeout';
    }

    public function simulate(): ChaosOutcome
    {
        // Inject the fault, observe the engine's degradation, return the verdict.
        return new ChaosOutcome(/* name, passed, durationSeconds, details */);
    }
}

$runner = new ChaosScenarioRunner();
$runner->register(new TimeoutScenario());
$runner->run();

echo $runner->allPassed() ? "Resilient.\n" : "{$runner->failCount()} scenario(s) failed.\n";

Contoh kode — Produksi

Jalankan harness dari job ketahanan, lalu kembalikan kode keluar bukan nol untuk setiap kegagalan tanpa membiarkan kegagalan skenario muncul sebagai eksepsi.

<?php

declare(strict_types=1);

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

use NextPDF\Chaos\ChaosScenarioRunner;
use NextPDF\Chaos\Exception\ChaosReportWriteException;
use Psr\Log\LoggerInterface;

final readonly class ChaosJob
{
    /** @param list<\NextPDF\Chaos\ChaosScenarioInterface> $scenarios */
    public function __construct(
        private array $scenarios,
        private LoggerInterface $logger,
    ) {}

    public function run(string $reportPath): int
    {
        $runner = new ChaosScenarioRunner();

        foreach ($this->scenarios as $scenario) {
            $runner->register($scenario);
        }

        $runner->run(); // never throws on scenario failure

        try {
            $runner->writeReport($reportPath);
        } catch (ChaosReportWriteException $e) {
            $this->logger->error('Chaos report could not be written.', ['error' => $e->getMessage()]);

            return 2;
        }

        return $runner->allPassed() ? 0 : 1;
    }
}

Kasus tepi & jebakan

• run() tidak pernah melempar eksepsi karena skenario gagal. Kegagalan tersimpan di dalam ChaosOutcome. Jika Anda membungkus run() dengan try/catch dan berharap kegagalan muncul di sana, Anda tidak akan melihatnya. Sebagai gantinya, baca failCount() / allPassed().
• Runner hanya melempar eksepsi pada kesalahan infrastruktur: pendaftaran yang tidak valid, atau ChaosReportWriteException saat jalur laporan tidak dapat ditulis. Tangani kesalahan tersebut secara terpisah dari hasil skenario.
• Skenario dijalankan secara berurutan sesuai urutan pendaftaran. Tidak ada paralelisme. Urutan dapat berpengaruh saat skenario berbagi state eksternal.
• Modul ini ditujukan untuk pengujian ketahanan. Jangan mengimpor runner ke dalam jalur produksi dokumen sebagai mekanisme kendali.

Performa

Runner menambahkan overhead yang dapat diabaikan. Perilaku skenariolah yang menentukan biayanya. Karena skenario menyuntikkan kesalahan dan mungkin menunggu timeout, eksekusi chaos memang dapat berjalan lambat. performance_budget di sini adalah angka acuan mesin, bukan batas atas durasi skenario. Profil reproduksibilitasnya bersifat structural: laporan mencatat durasi waktu nyata (wall-clock), sehingga bidang-bidang tersebut berbeda di setiap eksekusi.

Catatan keamanan

Skenario menyuntikkan kesalahan dan dapat melatih jalur kegagalan dependensi. Jalankan harness hanya di lingkungan pengujian atau staging, dengan kredensial dan endpoint yang dibatasi pada lingkungan tersebut. Jangan pernah menjalankannya terhadap sistem produksi. Laporan dapat memuat detail diagnostik tentang mode kegagalan. Perlakukan laporan tersebut sebagai internal, dan terapkan kewajiban penyaringan log proyek sebelum Anda membagikannya. Lihat model ancaman mesin di /modules/core/security/.

Konformitas

Modul ini tidak membuat klaim normatif atas spesifikasi PDF. Ini adalah perkakas ketahanan. Modul ini tidak mengimplementasikan protokol terstandar yang klausanya harus dikutip. Suite oracle dan golden yang dijelaskan di /modules/core/conformance/ memvalidasi konformitas mesin.

Lihat juga

• Modul Observability — permukaan state runtime yang diamati oleh skenario.
• Modul Accelerator — target yang lazim untuk skenario kegagalan dependensi.
• Tinjauan konformitas
• Model keamanan mesin