NextPDF Connect'te worker açısından güvenli oturum yaşam döngüsü

Bir bakışta

Uzun süre çalışan bir PHP worker’ında (RoadRunner, Swoole, Laravel Octane) istek kapsamına alınmış bir oturum yaşam döngüsü kullanın. Her istek kendi belge oturumunu oluşturur ve bu oturumu output_pdf sonrasında yok eder. Yazı tipi, sayfa ve tanıtıcı durumu worker’ın istek sınırı içinde kalır. Araçlar şunlardır: create_pdf, set_font, add_text ve output_pdf — tümü Core.

Kurulum

composer require nextpdf/server

Bir taşıma katmanı bağlayın. Bu desen her taşıma katmanıyla aynı şekilde çalışır.

Kavramsal genel bakış

Bir document_id, tek bir isteğin kapsamındaki opak bir tanıtıcıdır. Tek bir kurala uyun: her istekte oluşturun, her istekte yok edin, asla önbelleğe almayın veya paylaşmayın. Varsayılan destroy: true ile output_pdf, belgeyi tek bir atomik adımda işler ve oturumu serbest bırakır. Aynı worker’daki sonraki istek yeni ve bağımsız bir oturum alır. Önceki oturumun yazı tipi ve içeriği artık yoktur. Her araç sonucu normal bir taşıma yanıtıdır (PSR-18 §p2). Sunucu kodu otomatik yükleme sınırı tarafından yalıtılır (PSR-4 §3). Oturum deposu, istekler arasında kalan tek durumdur ve id’ye göre anahtarlanır.

API yüzeyi

Araç	Rol	Risk katmanı
`create_pdf`	İstek başına bir oturum açar	Güvenli
`set_font`	Etkin yazı tipini ayarlar (oturum başına)	Dikkat
`add_text`	İçerik yazar	Dikkat
`output_pdf`	Oturumu işler ve yok eder	Onay Gerekli / İnceleme (base64)

Tek doğruluk kaynağı araç kataloğudur. Kullanabileceğiniz araçlar kurulu katmana bağlıdır.

Kod örneği — hızlı başlangıç

İstek 1: create_pdf → set_font → add_text → output_pdf (destroy: true). Aynı worker’daki istek 2 yeni bir create_pdf oturumu başlatır. Eski id artık geçersizdir. Yazı tipini yeniden ayarlayın, çünkü bu ayar aktarılmaz.

Kod örneği — üretim

Temizleme işleminin her zaman yürütülmesi için yaşam döngüsünü sarmalayın:

İstek başladığında oturumu edinin.
İçerik oluşturun.
Bir finally eşdeğeri blokta, oturumu yok eden output_pdf çağrısını yapın. Çıktı sonrası inceleme akışı için destroy: false kullandıysanız, bunun yerine oturumu açıkça yok edin.

Bir document_id değerini asla worker genelinde, statik bir alanda veya paylaşılan bir kapsayıcıda saklamayın. Bunu asla coroutine’ler, fiber’lar veya istek işleyicileri arasında geçirmeyin.

Sınır durumları ve tuzaklar

Yok edildikten sonra yeniden kullanılan id. Bilinmeyen belge hatası döndürür. İstek başına yeni bir oturum oluşturun.
Unutulan output_pdf. Oturum TTL süresi dolana veya işlem yeniden başlatılana kadar bellek kullanımı sessizce artar. Her zaman sonlandırın.
Yük altında oturum sınırı. Deponun eşzamanlılık için bir üst sınırı vardır. Oturumu hızlı yok etmek, bu sınırın altında kalmanıza yardımcı olur.
Temizleme olmadan destroy: false. Bellek kullanımı kademeli olarak artar. Bunu yalnızca açık bir çıktı sonrası inceleme akışı için kullanın, ardından oturumu yok edin.
Eşzamanlı istekler arasında paylaşılan id. Bu, çıktıyı bozan bir yarış durumudur. Her istek kendi oturumuna sahiptir.

Performans

İstek başına çıktı birkaç KB’dir. Bunun sağladığı fayda, worker’ın yaşam süresi boyunca worker belleğinin sınırlı kalmasıdır. Profil structural türündedir.

Güvenlik notları

Oturum yalıtımı aynı zamanda bir gizlilik özelliğidir. Bir isteğin içeriği asla başka bir isteğe ulaşmaz, çünkü tanıtıcılar paylaşılmaz ve oturum çıktı alındığında yok edilir.

Uygunluk

İfade	Spesifikasyon	Madde	reference_id
Her araç sonucu, normal bir taşıma yanıtıdır.	PSR-18	§p2
Kod, otomatik yükleme sınıf→dosya eşlemesiyle yalıtılır.	PSR-4	§3

Ticari bağlam

Uygulanamaz — tüm araçlar Core’dur.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	Tipik olarak worker başına bir stdio işlemi kullanılır.
REST	Evet	HTTP istek sınırı oturum sınırına eşlenir.
gRPC	Evet	RPC dizisi başına bir oturum.

HITL risk katmanı

create_pdf Güvenli’dir. set_font ve add_text Dikkat’tir. output_pdf Onay Gerekli’dir; base64 modunda İnceleme’ye düşürülür. Bir worker’da base64 çıktısı yaygın kullanılan yoldur ve ek bir geçit getirmez (HITL risk katmanları).

Onay geçidi JSON zarfı

Base64 worker çıktısı:

{ "allowed": true }