Chaos: deterministik dayanıklılık senaryoları çatısı

Bir bakışta

Chaos modülü, dayanıklılık testleri için yalın bir çatıdır. Tek metotlu bir arabirimi uygulayan hata enjeksiyonu senaryolarını kaydedip çalıştırır ve yapılandırılmış bir pass/fail raporu toplarsınız. Bilinçli olarak beş sınıfla sınırlı tutulmuştur; belge üretim yolunda değil, dayanıklılık test paketlerinde ve chaos-day alıştırmalarında kullanılmalıdır.

Kararlılık: deneysel. Bu, bir test ve dayanıklılık araç yüzeyidir; çekirdek bir PDF API’si değildir. Hizmet sağlayıcı arabirimi (SPI) küçüktür ve kararlı bir biçime sahiptir, ancak modülün kapsamı ve birlikte gelen senaryolar gelişmeye devam eder. Bunun üzerine üretim denetim akışı kurmayın.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Bir dayanıklılık testi, bir bağımlılık başarısız olduğunda motorun uygun geri dönüş yolunu kullanıp kullanmadığını sorgular. Chaos modülü bu teste yapı kazandırır. ChaosScenarioInterface, senaryo sözleşmesidir: name() senaryoyu tanımlar ve simulate() bir ChaosOutcome döndürür. Her senaryo, ağ bölünmesi ya da alma arka ucundan gelen bir dizi 5xx yanıtı gibi tek bir hatayı kapsüller ve gerçekleşenleri raporlar.

ChaosScenarioRunner çalıştırmayı düzenler. Senaryoları register() ile kaydeder, bunları kayıt sırasına göre sırayla yürütmek için run() çağırır ve ardından toplamı outcomes(), allPassed(), passCount() ve failCount() ile okursunuz. Çalıştırıcı, bir senaryo başarısız olduğunda asla istisna fırlatmaz: başarısızlık, istisna değil, bir ChaosOutcome içinde yakalanmış veridir. Yalnızca kendi altyapısında hata oluştuğunda istisna fırlatır; örneğin geçersiz bir senaryo kaydı ya da rapor dosyasının yazılamaması (ChaosReportWriteException) durumlarında. Test ettiği kaynağa ulaşamayan bir senaryo, bir RetrievalUnavailableException fırlatır. Modül @since 3.2.0’dir.

ChaosOutcome, senaryo başına sonucu saklar: pass/fail durumu, süre ve yapılandırılmış rapor için toArray() çıktısı. Sonuç, duvar saati süresini kaydettiği için raporun yeniden üretilebilirlik profili structural’dır, bitwise değildir.

API yüzeyi

Tür	Temel üyeler	Rol
ChaosScenarioInterface	name(): string, simulate(): ChaosOutcome	Senaryo sözleşmesi (@since 3.2.0)
ChaosScenarioRunner	register(), run(), outcomes(), allPassed(), passCount(), failCount()	Sıralı senaryo düzenleyicisi (@since 3.2.0)
ChaosOutcome	durationSeconds(), toArray()	Senaryo başına pass/fail sonucu (@since 3.2.0)
RetrievalUnavailableException	—	Test edilen kaynağa ulaşılamadı
ChaosReportWriteException	—	Rapor dosyası yazılamadı

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

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

Bir senaryo kaydedin, ardından senaryo setini çalıştırın.

<?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";

Kod örneği — üretim

Çatıyı bir dayanıklılık işi içinden yönetin ve senaryo başarısızlığının istisna olarak dışarı sızmasına izin vermeden, herhangi bir başarısızlık için sıfır olmayan bir çıkış kodu döndürün.

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

Uç durumlar ve dikkat noktaları

• run(), bir senaryo başarısız olduğu için asla istisna fırlatmaz. Başarısızlık, ChaosOutcome içinde yer alır. run() çağrısını, başarısızlıkları burada yakalamayı bekleyerek bir try/catch bloğuna alırsanız, bunları görmezsiniz. Bunun yerine failCount() / allPassed() değerini okuyun.
• Çalıştırıcı yalnızca altyapı hatalarında istisna fırlatır: hatalı bir kayıt olduğunda ya da rapor yolu yazılabilir olmadığında bir ChaosReportWriteException. Bu hataları, senaryo sonuçlarından ayrı olarak ele alın.
• Senaryolar, kayıt sırasına göre sırayla çalışır. Paralellik yoktur. Senaryolar harici durumu paylaştığında sıralama önem kazanabilir.
• Bu modül, dayanıklılık testi içindir. Çalıştırıcıyı, bir denetim mekanizması olarak belge üretim yoluna dahil etmeyin.

Performans

Çalıştırıcı, ihmal edilebilir bir ek yük getirir. Maliyetini senaryo davranışı belirler. Senaryolar hata enjekte ettiği ve zaman aşımlarını bekleyebileceği için bir chaos çalıştırması, tasarım gereği yavaş olabilir. Buradaki performance_budget, senaryo süresine ilişkin bir sınır değil, motorun referans değeridir. Yeniden üretilebilirlik profili structural’dır: rapor, duvar saati sürelerini kaydeder; dolayısıyla bu alanlar çalıştırmalar arasında farklılık gösterir.

Güvenlik notları

Senaryolar hata enjekte eder ve bağımlılıklardaki başarısızlık yollarını tetikleyebilir. Çatıyı yalnızca bir test ya da hazırlık ortamında, kimlik bilgileri ve uç noktalar o ortamla sınırlandırılmış olarak çalıştırın. Bunu asla üretim sistemlerine karşı çalıştırmayın. Rapor, başarısızlık biçimlerine ilişkin tanılama ayrıntıları içerebilir. Raporu dahili olarak değerlendirin ve paylaşmadan önce projenin log temizleme yükümlülüğünü uygulayın. Motor tehdit modeli için /modules/core/security/ bölümüne bakın.

Uyumluluk

Bu modül, hiçbir PDF belirtimine ilişkin normatif iddiada bulunmaz. Bu, bir dayanıklılık aracıdır. Madde alıntısı gerektiren standartlaştırılmış hiçbir protokol uygulamaz. /modules/core/conformance/ bölümünde anlatılan oracle ve golden test paketleri, motor uyumluluğunu doğrular.

Ayrıca bakınız

• Observability modülü — bir senaryonun gözlemlediği çalışma zamanı durum yüzeyi.
• Accelerator modülü — bağımlılık başarısızlığı senaryoları için yaygın bir hedef.
• Uyumluluk genel bakışı
• Motor güvenlik modeli