Cykl życia sesji bezpieczny dla workerów w NextPDF Connect

W skrócie

W długo działającym workerze PHP (RoadRunner, Swoole, Laravel Octane) stosuj cykl życia sesji ograniczony do zakresu żądania. Każde żądanie tworzy własną sesję dokumentu i niszczy ją po output_pdf. Stan czcionki, strony i uchwytu pozostaje w granicach żądania obsługiwanego przez workera. Narzędzia to create_pdf, set_font, add_text oraz output_pdf — wszystkie dostępne w wersji Core.

Instalacja

composer require nextpdf/server

Powiąż transport. Ten wzorzec działa identycznie z dowolnym transportem.

Omówienie koncepcyjne

Identyfikator document_id jest nieprzezroczystym uchwytem ograniczonym do jednego żądania. Przestrzegaj jednej zasady: twórz dla każdego żądania, niszcz dla każdego żądania, nigdy nie buforuj ani nie udostępniaj. Przy domyślnym ustawieniu destroy: true output_pdf renderuje dokument i zwalnia sesję w jednym niepodzielnym kroku. Następne żądanie w tym samym workerze otrzymuje świeżą, niezależną sesję. Czcionka i treść poprzedniej sesji przestają istnieć. Każdy wynik narzędzia jest zwykłą odpowiedzią transportu (PSR-18 §p2). Kod serwera jest izolowany przez granicę automatycznego ładowania (PSR-4 §3). Magazyn sesji jest jedynym stanem współdzielonym między żądaniami i jest indeksowany według identyfikatora.

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwiera sesję dla pojedynczego żądania	Bezpieczne
`set_font`	Ustawia aktywną czcionkę (dla danej sesji)	Uwaga
`add_text`	Zapisuje treść	Uwaga
`output_pdf`	Renderuje i niszczy sesję	Wymagane zatwierdzenie / Przegląd (base64)

Katalog narzędzi jest źródłem prawdy. Dostępne narzędzia zależą od zainstalowanej wersji.

Przykład kodu — szybki start

Żądanie 1: create_pdf → set_font → add_text → output_pdf (destroy: true). Żądanie 2 w tym samym workerze rozpoczyna nową sesję create_pdf. Stary identyfikator jest teraz nieprawidłowy. Ustaw czcionkę ponownie, ponieważ nie jest przenoszona.

Przykład kodu — środowisko produkcyjne

Obsłuż cykl życia tak, aby czyszczenie zawsze zostało wykonane:

Uzyskaj sesję na początku żądania.
Zbuduj treść.
W odpowiedniku bloku finally wywołaj output_pdf, które niszczy sesję. Jeśli użyto destroy: false w przepływie z inspekcją po wygenerowaniu danych wyjściowych, zniszcz sesję jawnie.

Nigdy nie przechowuj document_id w kontenerze globalnym dla workera, statycznym ani współdzielonym. Nigdy nie przekazuj go między korutynami, fibrami ani procedurami obsługi żądań.

Przypadki brzegowe i pułapki

Ponowne użycie identyfikatora po zniszczeniu. Powoduje zwrócenie błędu nieznanego dokumentu. Twórz nową sesję dla każdego żądania.
Pominięte output_pdf. Zużycie pamięci po cichu rośnie, dopóki nie wygaśnie TTL sesji albo proces nie zostanie zrestartowany. Zawsze finalizuj.
Limit sesji pod obciążeniem. W magazynie obowiązuje limit jednoczesnych sesji. Szybkie niszczenie pomaga utrzymać się poniżej tego limitu.
destroy: false bez czyszczenia. Zużycie pamięci rośnie stopniowo. Stosuj tę opcję tylko dla jawnego przepływu z inspekcją po wygenerowaniu danych wyjściowych, a następnie zniszcz sesję.
Współdzielony identyfikator między jednoczesnymi żądaniami. Prowadzi do wyścigu, który uszkadza dane wyjściowe. Każde żądanie ma własną sesję.

Wydajność

Dane wyjściowe dla żądania mają rozmiar kilku KB. Korzyścią jest ograniczone zużycie pamięci workera przez cały czas jego życia. Profil jest structural.

Uwagi dotyczące bezpieczeństwa

Izolacja sesji to także właściwość poufności. Treść jednego żądania nigdy nie trafia do innego żądania, ponieważ uchwyty nie są współdzielone, a sesja jest niszczona w momencie generowania danych wyjściowych.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Każdy wynik narzędzia jest zwykłą odpowiedzią transportu.	PSR-18	§p2
Kod jest izolowany przez mapowanie klasy na plik w mechanizmie automatycznego ładowania.	PSR-4	§3

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia są dostępne w wersji Core.

Dostępność transportu

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Typowo na worker przypada jeden proces stdio.
REST	Tak	Granica żądania HTTP odpowiada granicy sesji.
gRPC	Tak	Jedna sesja na sekwencję RPC.

Poziom ryzyka HITL

create_pdf ma poziom Bezpieczne. set_font i add_text wymagają Uwagi. output_pdf wymaga zatwierdzenia (Approval Required), z obniżeniem do Przeglądu w trybie base64. W workerze dane wyjściowe w formacie base64 są typową ścieżką i nie dodają żadnej bramki (poziomy ryzyka HITL).

Koperta JSON dla bramki potwierdzenia

Dane wyjściowe workera w formacie base64:

{ "allowed": true }