Chaos: 결정론적 복원력 시나리오 하니스

한눈에 보기

Chaos 모듈은 복원력 테스트를 위한 소형 하니스입니다. 단일 메서드 인터페이스를 구현하는 결함 주입 시나리오를 등록해 실행한 뒤, 구조화된 pass/fail 보고서를 수집합니다. 의도적으로 최소한의 구성, 즉 다섯 개의 클래스로 이루어져 있으며, 문서 생성 경로가 아니라 복원력 스위트와 chaos-day 훈련을 위한 것입니다.

안정성: 실험적(experimental). 이것은 테스트 및 복원력 도구 영역이며, 핵심 PDF API가 아닙니다. SPI는 작고 안정적인 형태이지만, 모듈의 범위와 번들로 제공되는 시나리오는 계속 발전합니다. 이를 기반으로 프로덕션 제어 흐름을 구축하지 마십시오.

설치

composer require nextpdf/core:^3

개념 개요

복원력 테스트가 던지는 질문은 이것입니다: 의존성이 실패할 때 엔진이 올바르게 성능 저하(degrade)되는가? Chaos 모듈은 그 테스트에 구조를 부여합니다. ChaosScenarioInterface는 시나리오가 구현하는 계약입니다 — name()와 ChaosOutcome를 반환하는 simulate()로 구성됩니다. 시나리오는 하나의 결함(네트워크 파티션, 검색 백엔드의 5xx 응답 폭주)을 캡슐화하고 무슨 일이 발생했는지 보고합니다.

ChaosScenarioRunner는 오케스트레이터입니다. 시나리오를 register()로 등록하고, run()을 호출해 등록 순서대로 순차 실행한 다음, 집계 결과를 읽습니다: outcomes(), allPassed(), passCount(), failCount(). 러너는 시나리오 실패만으로는 결코 예외를 던지지 않습니다 — 실패는 예외가 아니라 ChaosOutcome에 담긴 데이터입니다. 러너는 자체 인프라에 문제가 있을 때만 예외를 던집니다: 잘못된 시나리오 등록, 또는 보고서 파일을 쓸 수 없는 경우(ChaosReportWriteException). 테스트 대상 리소스에 도달할 수 없는 시나리오는 RetrievalUnavailableException을 발생시킵니다. 모듈 전체는 @since 3.2.0입니다.

ChaosOutcome은 시나리오별 결과를 나타냅니다: pass/fail, 소요 시간, 그리고 구조화된 보고서를 위한 toArray()로 구성됩니다. 결과는 벽시계 시간(wall-clock) 기준 소요 시간을 기록하므로, 보고서의 재현성 프로필은 bitwise가 아니라 structural입니다.

API 표면

유형	주요 멤버	역할
ChaosScenarioInterface	name(): string, simulate(): ChaosOutcome	시나리오 계약 (@since 3.2.0)
ChaosScenarioRunner	register(), run(), outcomes(), allPassed(), passCount(), failCount()	순차 시나리오 오케스트레이터 (@since 3.2.0)
ChaosOutcome	durationSeconds(), toArray()	시나리오별 pass/fail 결과 (@since 3.2.0)
RetrievalUnavailableException	—	테스트 대상 리소스에 도달할 수 없음
ChaosReportWriteException	—	보고서 파일을 쓸 수 없음

전체 PHPDoc 표는 composer docs:generate-api-php -- --module=Chaos를 실행하여 확인할 수 있습니다.

코드 샘플 — 빠른 시작

시나리오를 등록하고 스위트를 실행합니다.

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

코드 샘플 — 프로덕션

복원력 작업에서 하니스를 실행하고, 시나리오 실패가 예외로 빠져나가지 않도록 하면서 모든 실패를 0이 아닌 종료 코드로 처리합니다.

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

엣지 케이스 및 주의 사항

• run()은 시나리오가 실패했다는 이유로는 결코 예외를 던지지 않습니다. 실패는 ChaosOutcome 안에 존재합니다. run()을 try/catch로 감싸고 거기서 실패를 받을 것이라고 기대하면, 그 실패를 볼 수 없습니다 — 대신 failCount() / allPassed()를 읽으십시오.
• 러너는 인프라 결함에 대해서만 예외를 던집니다: 잘못된 등록, 또는 보고서 경로에 쓸 수 없을 때 발생하는 ChaosReportWriteException입니다. 이러한 경우는 시나리오 결과와 구분하여 처리하십시오.
• 시나리오는 등록 순서대로 순차적으로 실행됩니다. 병렬 처리는 없습니다. 시나리오가 외부 상태를 공유하는 경우 순서가 중요할 수 있습니다.
• 이 모듈은 복원력 테스트를 위한 것입니다. 러너를 제어 메커니즘으로 문서 생성 경로에 넣지 마십시오.

성능

러너의 오버헤드는 무시할 수 있을 정도입니다. 실제 비용은 시나리오가 수행하는 작업에 따라 결정됩니다. 시나리오는 결함을 주입하고 타임아웃을 기다릴 수 있으므로, chaos 실행은 설계상 느릴 수 있습니다. 여기서 performance_budget은 엔진의 참조 수치이며, 시나리오 소요 시간의 상한이 아닙니다. 재현성 프로필은 structural입니다: 보고서는 벽시계 시간(wall-clock) 기준 소요 시간을 기록하므로, 두 번의 실행에서는 해당 필드가 달라집니다.

보안 참고 사항

시나리오는 결함을 주입하고 의존성의 실패 경로를 실행할 수 있습니다. 하니스는 해당 환경으로만 범위가 제한된 자격 증명과 엔드포인트를 갖춘 테스트 또는 스테이징 환경에서만 실행하십시오 — 프로덕션 시스템에 대해서는 절대 실행하지 마십시오. 보고서에는 실패 모드의 진단 세부 정보가 포함될 수 있습니다. 이를 내부용으로 취급하고, 공유하기 전에 프로젝트의 로그 스크러빙 의무를 적용하십시오. 엔진 위협 모델은 /modules/core/security/에서 확인하십시오.

적합성

이 모듈은 PDF 사양에 대해 어떠한 규범적 주장도 하지 않습니다. 복원력 도구입니다. 조항을 인용해야 하는 표준화된 프로토콜을 구현하지 않습니다. 엔진 적합성은 /modules/core/conformance/에 설명된 오라클 및 골든 스위트로 검증됩니다.

함께 보기

• Observability 모듈 — 시나리오가 관찰하는 런타임 상태 영역입니다.
• Accelerator 모듈 — 의존성 실패 시나리오의 일반적인 대상입니다.
• 적합성 개요
• 엔진 보안 모델