가속기: Spectrum 사이드카 클라이언트

한눈에 보기

Accelerator 모듈은 선택적 아웃오브프로세스 가속 사이드카인 Spectrum의 PHP 클라이언트입니다. 견고화된 HTTP 클라이언트로서 회로 차단기, JSON 웹 토큰(JWT) 기능 토큰, 일시적 오류에 대한 단발성 재시도, 그리고 스트리밍되는 작업 진행 상황을 위한 서버 전송 이벤트 기반 전송 계층을 제공합니다. 엔진은 이 모듈 없이도 동작합니다. 이 모듈은 가속을 필수 조건이 아니라 주입 가능한 의존성으로 만들기 위해 존재합니다.

안정성: 실험적. Spectrum은 고정된 공개 API가 아니라 선택적 사이드카입니다. 이 클라이언트가 구현하는 SpectrumInterface는 다음 문서인 Contracts / Observability에서 실험적이라고 설명되어 있습니다. 이 클라이언트는 그 등급을 따릅니다. 전송 계층, 토큰 형식, 예산 형태는 마이너 버전 간에 변경될 수 있습니다.

설치

composer require nextpdf/core:^3

개념 개요

Spectrum은 프로세서 부하가 높은 작업을 로컬 사이드카 프로세스로 오프로드합니다. 이러한 작업에는 하드웨어 감지, PDF 파싱, 이미지 압축이 포함됩니다. SpectrumClient는 고정된 NextPDF\Contracts\SpectrumInterface를 구현하는 PSR-18 클라이언트입니다. 이 클라이언트는 하드와이어링된 HTTP 스택이 아니라 ClientInterface, RequestFactoryInterface, StreamFactoryInterface에 의존합니다.

이 클라이언트는 신뢰할 수 없는 의존성을 다루도록 만들어졌습니다. 회로 차단기는 연속 세 번의 실패 후 열립니다. 열려 있는 동안 isAvailable()는 지수 백오프 구간 동안 false를 반환하므로, 핫 패스가 다운된 사이드카를 계속 호출하지 않습니다. 프로브 결과는 TTL(time-to-live)과 함께 캐시됩니다. 앱 시크릿이 구성되어 있으면, 모든 아웃바운드 요청에 요청 기능 토큰(Request Capability Token)이 함께 전달됩니다. 그 토큰은 엔드포인트가 요구하는 기능으로 범위가 지정된 단명 HS256 JWT입니다. 수명은 120 초이며, 고제어(high-control) 권한 모드에서는 30 초입니다. 일시적 5xx 및 타임아웃 오류는 한 번 재시도됩니다. 인증 오류와 파싱 오류는 결코 재시도되지 않습니다.

SspectrumClient는 인스턴스별 상태를 가집니다. 회로 차단기 상태와 프로브 캐시는 공유되지 않습니다. 각 PHP-FPM 워커는 자체 인스턴스를 보유해야 합니다. 배치 결과는 타입화되어 있습니다. BatchResult는 BatchItemStatus를 가진 BatchItem 항목, 성공률을 담은 BatchSummary, 그리고 선택적 트레이스 ID를 전달합니다. HardwareReport와 HardwareCapabilities는 감지된 하드웨어 등급을 설명합니다. HardwareCapabilities::satisfies()는 등급 요구 사항에 프로그래밍 방식으로 답합니다. DegradePolicy와 AuthorizationMode 열거형은 기능 손실과 토큰 엄격성이 어떻게 동작하는지를 결정합니다. 모듈 전체는 @since 2.1.0입니다.

API 표면

타입	주요 멤버	역할
`SpectrumClient`	`isAvailable()`, `probe()`, `getBudget()`, `request()`	`SpectrumInterface`를 구현하는 PSR-18 사이드카 클라이언트
`BatchResult`	`getItems()`, `getSummary()`, `filterByStatus()`, `traceId()`	타입화된 배치 결과
`BatchItem` / `BatchItemStatus`	`isOk()`, `isSuccessful()`, `isRetryable()`	항목별 결과 및 상태 열거형
`BatchSummary`	`isFullSuccess()`, `successRate()`	집계 배치 요약
`HardwareReport`	`hasPro()`, `hasEnterprise()`, `isApiVersionCompatible()`	감지된 사이드카 기능
`HardwareCapabilities`	`hasGpu()`, `satisfies()`, `bestAvailableTier()`	프로그래밍 방식의 기능 분기
`DegradePolicy` / `AuthorizationMode`	열거형 케이스	저하 동작 및 토큰 엄격성

전체 PHPDoc 표를 보려면 composer docs:generate-api-php -- --module=Accelerator를 실행하십시오.

코드 예제 — 빠른 시작

사이드카에 의존하기 전에 회로 차단기 보호 아래에서 사이드카를 프로브하십시오.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\SpectrumInterface;

function describeAccelerator(SpectrumInterface $spectrum): string
{
    if ($spectrum->isAvailable() !== true) {
        return 'Accelerator unavailable; engine runs in pure-PHP mode.';
    }

    $report = $spectrum->probe();

    return $report->hasEnterprise() ? 'Enterprise accelerator tier active.' : 'Standard accelerator tier active.';
}

코드 예제 — 프로덕션

사이드카가 정상일 때는 사이드카를 통해 배치를 전송하고, 정상이 아닐 때는 저하 정책에 따라 폴백하십시오.

<?php

declare(strict_types=1);

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

use NextPDF\Accelerator\DegradePolicy;
use NextPDF\Contracts\SpectrumInterface;
use Psr\Log\LoggerInterface;

final readonly class AcceleratedCompressor
{
    public function __construct(
        private ?SpectrumInterface $spectrum,
        private DegradePolicy $policy,
        private LoggerInterface $logger,
    ) {}

    /** @param list<array{id: string, data: string}> $images @return string Raw sidecar body. */
    public function compress(array $images): string
    {
        if ($this->spectrum?->isAvailable() === true) {
            return $this->spectrum->request('POST', '/v1/compress', json: ['images' => $images], scope: ['compress']);
        }

        if ($this->policy === DegradePolicy::Strict) {
            throw new \RuntimeException('Accelerator required under the strict degrade policy.');
        }

        $this->logger->info('Spectrum unavailable; using PHP image path.');

        return '';
    }
}

엣지 케이스 및 함정

isAvailable()는 특정 시점에 수행되는 회로 차단 검사입니다. true 결과는 다음 호출 전에 false가 될 수 있습니다. 그 사이에 사라질 수 있는 사이드카를 처리하십시오.
회로 차단기와 프로브 캐시 상태는 인스턴스별입니다. 하나의 SpectrumClient를 워커 간에 공유하면 차단기가 무력화됩니다. 각 워커에 자체 인스턴스를 부여하십시오.
기능 토큰은 단명합니다(120 초, 고제어 모드에서는 30 초). 오래 걸리는 작업은 토큰을 재사용하지 말고 새 토큰을 획득해야 합니다.
인증 오류와 파싱 오류는 결코 재시도되지 않으며, 일시적 5xx와 타임아웃만, 그것도 단 한 번만 재시도됩니다. 그보다 많은 멱등 재시도를 가정하지 마십시오.
null인 SpectrumInterface는 오류가 아니라 유효한 “가속기 없음” 상태입니다. 그 상태가 치명적인지는 저하 정책이 결정합니다.

성능

클라이언트 자체의 오버헤드는 무시할 만한 수준입니다. 작업은 사이드카에서 일어납니다. 회로 차단기가 주된 신뢰성 레버입니다. 이는 사이드카가 다운되었을 때 낭비되는 왕복을 제한합니다. 1500ms 벽시계 / 64MB 피크의 performance_budget는 사이드카 서비스 수준 협약(SLA)이 아니라 엔진의 참조 워크로드에 대한 것입니다. 재현성 프로필은 structural입니다. 배치 결과는 트레이스 ID와 타임스탬프를 전달하므로, 두 실행은 해당 필드에서 차이가 납니다.

보안 참고 사항

사이드카 경계는 신뢰 경계입니다. 앱 시크릿이 구성되어 있으면, 요청에는 엔드포인트로 범위가 지정된 HS256 기능 토큰이 함께 전달됩니다. 해당 시크릿은 시크릿 관리자에서 가져온 자격 증명으로 취급하고, 결코 커밋하지 마십시오. 고제어 권한 모드는 민감한 엔드포인트에 대해 토큰 수명을 30 초로 단축합니다. 운영자가 제공한 사이드카 URL은 첫 요청이 아니라 구성이 생성될 때 검증됩니다. 비어 있지 않은 호스트를 가진 http://와 https://, 또는 비어 있지 않은 소켓 경로를 가진 unix://만 허용되며, 그 외의 모든 스킴(gopher://, file://, ftp://, …) 또는 호스트가 없는 네트워크 URL은 생성 시점에 실패-차단(fail closed)됩니다. 이는 SSRF 및 예상치 못한 이그레스에 대한 심층 방어이므로, 잘못 구성된 엔드포인트는 결코 HTTP 클라이언트에 도달하지 않습니다. 사이드카 응답은 외부 데이터입니다. 엔진에 다시 진입하기 전에 이를 검증하고 신뢰할 수 없는 것으로 취급하십시오. 이 페이지의 legal-review-required 수출 통제 분류는 가속 기능이 암호화 전송을 수반하며 수출 통제 검토를 기다리고 있음을 반영합니다. 이를 활성화하는 빌드를 재배포하기 전에 그 검토를 참조하십시오.

준수

이 모듈은 PDF 사양상의 규범적 주장을 하지 않습니다. 이는 내부 가속 프로토콜을 위한 HTTP 클라이언트입니다. 이 프로토콜은 엔진이 정의한 것이며, 조항을 인용할 수 있는 표준화된 프로토콜이 아닙니다. 사이드카가 수행하는 작업(PDF 파싱, 압축)에 준수 측면이 있는 경우, 그 준수는 해당 모듈 페이지에 문서화되고 /modules/core/conformance/의 오라클 및 골든 스위트로 검증됩니다.

함께 보기

Contracts / Observability — 이 클라이언트가 구현하는 SpectrumInterface.
Observability 모듈 — 가속된 작업을 관측하기 위한 런타임 상태 표면.
Performance 모듈 — 가속된 작업이 목표로 삼는 예산.
엔진 보안 모델