Chaos: khung kịch bản phục hồi tất định

Tổng quan nhanh

Module Chaos là một khung gọn nhẹ để kiểm thử khả năng phục hồi. Bạn đăng ký các kịch bản tiêm lỗi triển khai một interface chỉ có một phương thức, chạy chúng, rồi thu thập báo cáo pass/fail có cấu trúc. Module này được chủ ý giữ nhỏ, chỉ gồm năm class, và phù hợp với các bộ kiểm thử phục hồi cùng bài tập chaos-day, chứ không thuộc luồng tạo tài liệu.

Độ ổn định: thử nghiệm. Đây là bề mặt công cụ dành cho kiểm thử và phục hồi, không phải là một giao diện lập trình ứng dụng (application programming interface) Portable Document Format (PDF) cốt lõi (API). Giao diện nhà cung cấp dịch vụ (service provider interface, SPI) nhỏ và có hình dạng ổn định, nhưng phạm vi của module và các kịch bản đi kèm sẽ thay đổi. Đừng xây dựng luồng điều khiển sản xuất dựa trên nó.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Một bài kiểm thử khả năng phục hồi đặt câu hỏi liệu engine có suy giảm đúng cách khi một phụ thuộc gặp sự cố hay không. Module Chaos cung cấp cấu trúc cho bài kiểm thử đó. ChaosScenarioInterface là hợp đồng của kịch bản: name() xác định kịch bản, còn simulate() trả về một ChaosOutcome. Mỗi kịch bản đóng gói một lỗi, chẳng hạn như sự cố phân vùng mạng hoặc một loạt phản hồi 5xx dồn dập từ backend truy xuất, và báo cáo những gì đã xảy ra.

ChaosScenarioRunner điều phối lượt chạy. Bạn register() các kịch bản, gọi run() để thực thi tuần tự theo thứ tự đăng ký, rồi đọc kết quả tổng hợp bằng outcomes(), allPassed(), passCount(), và failCount(). Runner không bao giờ ném ngoại lệ khi một kịch bản thất bại: thất bại là dữ liệu được ghi lại trong một ChaosOutcome, không phải ngoại lệ. Nó chỉ ném ngoại lệ khi chính hạ tầng của nó bị hỏng, chẳng hạn như đăng ký kịch bản không hợp lệ hoặc không thể ghi tệp báo cáo (ChaosReportWriteException). Một kịch bản không thể tiếp cận tài nguyên đang được kiểm thử sẽ phát sinh một RetrievalUnavailableException. Module này có @since 3.2.0.

ChaosOutcome lưu trữ kết quả của từng kịch bản: trạng thái pass/fail, thời lượng và đầu ra toArray() cho báo cáo có cấu trúc. Vì một kết quả ghi lại thời lượng theo đồng hồ thực, hồ sơ khả năng tái lập của báo cáo là structural, không phải bitwise.

Bề mặt API

Kiểu	Thành viên chính	Vai trò
ChaosScenarioInterface	name(): string, simulate(): ChaosOutcome	Hợp đồng của kịch bản (@since 3.2.0)
ChaosScenarioRunner	register(), run(), outcomes(), allPassed(), passCount(), failCount()	Bộ điều phối kịch bản tuần tự (@since 3.2.0)
ChaosOutcome	durationSeconds(), toArray()	Kết quả pass/fail của từng kịch bản (@since 3.2.0)
RetrievalUnavailableException	—	Không thể tiếp cận một tài nguyên đang được kiểm thử
ChaosReportWriteException	—	Không thể ghi tệp báo cáo

Chạy composer docs:generate-api-php -- --module=Chaos để tạo bảng PHPDoc đầy đủ.

Mã mẫu — Bắt đầu nhanh

Đăng ký một kịch bản, rồi chạy bộ kiểm thử.

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

Mã mẫu — Production

Điều khiển khung này từ một tác vụ phục hồi, và trả về mã thoát khác không cho bất kỳ thất bại nào mà không để thất bại của kịch bản thoát ra dưới dạng ngoại lệ.

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

Trường hợp biên & điểm cần lưu ý

• run() không bao giờ ném ngoại lệ vì một kịch bản thất bại. Thất bại nằm trong ChaosOutcome. Nếu bạn bọc run() trong một try/catch với kỳ vọng bắt được các thất bại ở đó, bạn sẽ không thấy chúng. Thay vào đó hãy đọc failCount() / allPassed().
• Runner chỉ ném ngoại lệ khi gặp lỗi hạ tầng: đăng ký sai, hoặc một ChaosReportWriteException khi không thể ghi vào đường dẫn báo cáo. Hãy xử lý những lỗi đó tách biệt với kết quả của kịch bản.
• Các kịch bản chạy tuần tự theo thứ tự đăng ký. Không có sự song song. Thứ tự có thể quan trọng khi các kịch bản chia sẻ trạng thái bên ngoài.
• Module này dành cho việc kiểm thử khả năng phục hồi. Đừng đưa runner vào luồng tạo tài liệu để dùng như một cơ chế điều khiển.

Hiệu năng

Runner thêm lượng chi phí không đáng kể. Hành vi của kịch bản mới quyết định chi phí. Vì các kịch bản tiêm lỗi và có thể chờ hết thời gian, một lần chạy chaos có thể chậm theo thiết kế. performance_budget ở đây là con số tham chiếu của engine, không phải giới hạn về thời lượng của kịch bản. Hồ sơ khả năng tái lập là structural: báo cáo ghi lại thời lượng theo đồng hồ thực, nên các trường đó khác nhau giữa các lần chạy.

Ghi chú bảo mật

Các kịch bản tiêm lỗi và có thể kích hoạt các nhánh xử lý lỗi trong những phụ thuộc. Chỉ chạy khung này trong môi trường kiểm thử hoặc staging, với thông tin xác thực và endpoint được giới hạn trong môi trường đó. Đừng bao giờ chạy nó trên các hệ thống production. Báo cáo có thể chứa chi tiết chẩn đoán về các kiểu lỗi. Hãy coi báo cáo là dữ liệu nội bộ, và áp dụng nghĩa vụ làm sạch nhật ký của dự án trước khi chia sẻ. Xem mô hình mối đe dọa của engine trong /modules/core/security/.

Tuân thủ

Module này không đưa ra tuyên bố quy phạm nào theo đặc tả PDF. Đây là công cụ phục hồi. Nó không triển khai giao thức tiêu chuẩn hóa nào cần trích dẫn điều khoản. Các bộ oracle và golden được mô tả trong /modules/core/conformance/ kiểm chứng sự tuân thủ của engine.

Xem thêm

• Module Observability — bề mặt trạng thái runtime mà một kịch bản quan sát.
• Module Accelerator — một mục tiêu phổ biến cho các kịch bản phụ thuộc gặp sự cố.
• Tổng quan về tuân thủ
• Mô hình bảo mật của engine