NextPDF Connect의 워커에 안전한 세션 수명 주기

한눈에 보기

장기 실행되는 PHP 워커(RoadRunner, Swoole, Laravel Octane)에서는 올바른 세션 수명 주기를 사용합니다. 각 요청은 자체 문서 세션을 생성하고 output_pdf 이후 이를 폐기합니다. 폰트, 페이지 또는 핸들 상태는 워커의 요청 경계를 넘어 누출되지 않습니다. 도구는 create_pdf, set_font, add_text 및 output_pdf이며 — 모두 Core입니다.

설치

composer require nextpdf/server

전송을 바인딩합니다. 이 패턴은 모든 전송에서 동일하게 작동합니다.

개념 개요

document_id는 하나의 요청 범위에 한정된 불투명 핸들입니다. 규칙은 요청마다 생성하고, 요청마다 폐기하며, 절대 캐싱하거나 공유하지 않는 것입니다. 기본값 destroy: true를 사용하면 output_pdf가 문서를 렌더링하고 원자적인 단일 단계로 세션을 해제합니다. 동일한 워커의 다음 요청은 새로운 독립 세션을 받습니다. 이전 세션의 폰트와 콘텐츠는 사라집니다. 각 도구 결과는 일반적인 전송 응답입니다(PSR-18 §p2). 서버 코드 자체는 오토로드 경계에 의해 격리됩니다(PSR-4 §3). 세션 스토어는 유일한 요청 간 상태이며, id로 키가 지정됩니다.

API 표면

도구	역할	위험 등급
`create_pdf`	요청별 세션 열기	안전
`set_font`	활성 폰트 설정(세션별)	주의
`add_text`	콘텐츠 작성	주의
`output_pdf`	세션 렌더링 및 폐기	승인 필요 / 검토(base64)

도구 카탈로그가 공식 카탈로그입니다. 사용 가능한 도구는 설치된 등급에 따라 달라집니다.

코드 샘플 — 빠른 시작

요청 1: create_pdf → set_font → add_text → output_pdf (destroy: true). 동일한 워커의 요청 2는 완전히 새로운 create_pdf 세션을 시작합니다. 이전 id는 더 이상 유효하지 않습니다. 폰트는 이월되지 않으므로 다시 설정합니다.

코드 샘플 — 프로덕션

정리가 항상 실행되도록 수명 주기를 래핑합니다:

요청 시작 시 세션을 획득합니다.
콘텐츠를 빌드합니다.
finally에 해당하는 블록에서 output_pdf를 호출해 세션을 폐기합니다. 출력 후 검사 흐름을 위해 destroy: false를 사용한 경우, 대신 세션을 명시적으로 폐기합니다.

document_id를 워커 전역, 정적 변수 또는 공유 컨테이너에 절대 저장하지 않아야 합니다. 코루틴, 파이버 또는 요청 핸들러 간에 절대 전달하지 않아야 합니다.

엣지 케이스 및 주의 사항

폐기 후 재사용된 id. 알 수 없는 문서 오류를 반환합니다. 요청마다 새 세션을 생성합니다.
누락된 output_pdf. 세션 TTL이 만료되거나 프로세스가 재시작될 때까지 메모리가 눈에 띄지 않게 증가합니다. 항상 마무리합니다.
부하 시 세션 한도. 스토어에는 동시 상한이 있습니다. 신속히 폐기하면 한도 이하로 유지됩니다.
정리 없는 destroy: false. 메모리가 점진적으로 증가합니다. 명시적인 출력 후 검사 흐름에만 사용하고, 이후 세션을 폐기합니다.
동시 요청 간 공유된 id. 출력을 손상시키는 경쟁 상태가 발생합니다. 각 요청은 자체 세션을 소유합니다.

성능

요청별 출력은 수 KB입니다. 이점은 워커의 수명 전체에 걸쳐 워커 메모리가 제한된다는 점입니다. 프로파일은 structural입니다.

보안 참고 사항

세션 격리는 기밀성 속성이기도 합니다. 핸들이 공유되지 않고 출력 시 세션이 폐기되므로, 한 요청의 콘텐츠는 다른 요청에 절대 도달하지 않습니다.

적합성

진술	사양	절	reference_id
각 도구 결과는 일반적인 전송 응답입니다.	PSR-18	§p2
코드는 오토로드 클래스→파일 매핑에 의해 격리됩니다.	PSR-4	§3

상업적 맥락

해당 없음 — 모든 도구가 Core입니다.

전송 가용성

전송	사용 가능	참고
MCP (stdio)	예	워커당 하나의 stdio 프로세스가 일반적입니다.
REST	예	HTTP 요청 경계는 세션 경계에 매핑됩니다.
gRPC	예	RPC 시퀀스당 하나의 세션.

HITL 위험 등급

create_pdf는 안전입니다. set_font과 add_text는 주의입니다. output_pdf는 승인 필요이며, base64 모드에서는 검토로 강등됩니다. 워커에서 base64 출력은 일반적인 경로이며 어떤 작업도 게이트 처리하지 않습니다(HITL 위험 등급).

확인 게이트 JSON 엔벨로프

Base64 워커 출력:

{ "allowed": true }