NextPDF Gotenberg 부팅 및 디스커버리

한눈에 보기

이 브리지에는 자체 자동 디스커버리 메커니즘이 없습니다. 명시적인 생성자 주입으로 직접 생성하는 단순한 서비스이며, 구성 값 객체와 PSR HTTP 협력 객체를 받습니다. 이 패키지는 서비스 프로바이더, 번들, 컨테이너 확장을 제공하지 않고 환경 변수도 직접 읽지 않습니다. 여기서 “디스커버리”란 호스트 프레임워크가 협력 객체를 공급하는 방식을 뜻하며, 그 책임은 이 패키지가 아니라 프레임워크에 있습니다.

브리지가 디스커버리되는 방식

브리지는 자동으로 디스커버리되지 않습니다. 직접 생성해야 합니다. GotenbergBridge는 필수 인수 네 개와 선택적 인수 세 개를 받습니다:

필수: GotenbergConfig, PSR-18 클라이언트, PSR-17 요청 팩토리, PSR-17 스트림 팩토리.
선택: PSR-3 로거, HTML 보안 정책(NextPDF 코어 기본 정책으로 기본값 설정), PSR-17 응답 팩토리.

응답 팩토리는 cURL 고정 전송을 활성화하는 스위치입니다. 이를 공급하면 고정할 대상이 있을 때(확인된 주소 또는 구성된 SPKI 핀) 브리지는 고정 전송을 사용합니다. 이를 생략하면 주입된 PSR-18 클라이언트가 항상 사용됩니다. 전체 인수 계약은 /integrations/gotenberg/configuration/.에 있습니다.

부팅 시퀀스

등록 단계는 없습니다. 라이프사이클은 다음과 같습니다:

호스트가 PSR-18 클라이언트와 PSR-17 팩토리를 해석합니다. 이 작업은 패키지가 아니라 호스트 컨테이너가 수행합니다.
애플리케이션은 자체 구성 소스에서 GotenbergConfig를 빌드합니다. GotenbergConfig::fromArray()는 snake_case 배열을 받으며, 잘못된 값은 기본값으로 대체해 허용합니다. 부팅 경로에서 소스를 검증하여, 누락된 URL이 변환마다가 아니라 부팅 시점에 실패하도록 하십시오.
애플리케이션은 구성과 협력 객체로 GotenbergBridge를 생성합니다.
첫 번째 변환 호출이 URL 검증, SSRF 및 파일 이름 검사와 요청 실행을 수행합니다. 생성 시점에는 아무 작업도 일어나지 않으며, 브리지는 호출되기 전까지 비활성 상태로 유지됩니다.

컨테이너 바인딩

이 패키지는 컨테이너 바인딩을 제공하지 않습니다. 브리지를 주입할 수 있게 하려면, 호스트 애플리케이션의 컨테이너에 다음과 같이 등록하십시오:

구성 소스에서 GotenbergConfig를 바인딩합니다.
PSR-18 클라이언트와 PSR-17 팩토리를 선택한 구현체에 바인딩합니다.
GotenbergBridge를 위 항목들을 전달받는 서비스로 바인딩합니다.

프레임워크 네이티브 자동 연결, 구성 게시, 서비스 프로바이더 또는 번들 등록은 여기가 아니라 전용 프레임워크 통합 패키지에서 제공합니다. 이 패키지는 의도적으로 프레임워크에 비종속적으로 유지됩니다. PSR 인터페이스에만 의존하므로 어떤 컨테이너에서도 작동합니다.

구성 해석 순서

패키지는 자체적으로 어떤 구성도 읽지 않습니다. 해석 순서는 애플리케이션이 GotenbergConfig::fromArray() 또는 생성자를 호출하기 전에 구현한 방식이 됩니다. 일반적인 순서는 환경 변수, 그다음 게시된 구성 파일, 그다음 코드 기본값입니다. 이 순서는 패키지가 아니라 애플리케이션의 계약입니다. 패키지가 정의하는 것은 fromArray()에 전달된 배열에서 생략한 각 필드의 기본값입니다: 빈 API URL, 30 초 타임아웃, 50 MiB 크기 상한, 빈 API 키, 빈 핀 목록.

진단

두 가지 내장 신호로 연결을 확인합니다:

isAvailable()는 네트워크 트래픽 없이 URL을 검증한 다음, <apiUrl>/health로 HEAD 요청을 보내고, 상태가 500 미만일 때 사용 가능하다고 보고합니다. 어떤 실패에 대해서도 예외를 던지지 않고 false를 반환합니다. 준비 상태 점검에서 이를 호출하십시오.
정상으로 알려진 작은 문서의 스모크 변환은 전체 경로를 종단 간으로 확인합니다. 여기에는 <apiUrl>/forms/libreoffice/convert로 보내는 멀티파트 요청과 응답 검증이 포함됩니다.

함께 보기

/integrations/gotenberg/integration/ — 서비스를 통해 NextPDF 파이프라인을 구동합니다.
/integrations/gotenberg/install/ — 패키지와 서비스 설치.
/integrations/gotenberg/configuration/ — 전체 생성자와 구성 계약.
/integrations/gotenberg/overview/ — 변환 흐름과 의존성 모델.