NextPDF Connect ile insan onaylı dosya çıktısı

Bir bakışta

İnsan onaylı (HITL) doğrulama kapısı, istenmeyen dosya sistemi yazma işlemlerini önlemeye yardımcı olur. output_pdf aracını bir file_path ile çağırdığınızda kapı çağrıyı duraklatır ve dosyayı yazmak yerine tek kullanımlık bir doğrulama isteği döndürür. Bir insan bunu onayladıktan sonra araç belirteçle birlikte yeniden çağrılır ve dosya ancak o zaman yazılır. Base64 çıktısı (file_path olmadan) kapıya tabi değildir.

Kurulum

composer require nextpdf/server

Bir taşıma katmanı bağlayın. Varsayılan olarak output_pdf aracı Onay Gerekli risk düzeyini kullanır.

Kavramsal genel bakış

Kapı, etkin risk düzeyini değerlendirir: bu düzey, yapılandırma veya çağıran kimliği geçersiz kılmaları uygulandıktan sonra kalan düzeydir. Onay Gerekli düzeyindeki bir araç için:

• base64 modu — output_pdf aracı file_path olmadan çağrıldığında İnceleme düzeyine düşürülür ve doğrulama olmadan izin verilir. Dosya sistemi üzerinde herhangi bir yan etkisi yoktur.
• dosya modu — output_pdf aracı bir file_path ile çağrıldığında Onay Gerekli düzeyinde kalır. Kapı, araç adına bağlı tek kullanımlık bir belirteç saklar ve ardından bir doğrulama isteği döndürür. Hedef dosya zaten varsa, doğrulama isteği metninde üzerine yazma uyarısı yer alır. Belirteç, sabit bir süre sonunda geçerliliğini yitirir.

Her taşıma katmanında kapı sonucu normal bir yanıttır. Bekleyen bir onay, taşıma katmanı hatası değil, iş akışındaki bir duraklamadır (PHP Standard Recommendation 18 (PSR-18) §3; PSR-18 §p2).

API yüzeyi

Araç	Rol	Risk düzeyi
create_pdf	Oturumu açar	Güvenli
set_font, add_text	İçeriği oluşturur	Dikkat
output_pdf (base64)	Satır içinde döndürür; kapı yok	İnceleme
output_pdf (dosya)	Diske yazar; kapıya tabidir	Onay Gerekli

İlgili araç kataloğu kayıt kaynağıdır ve kullanılabilir araçlar kurulu kademeye bağlıdır. HITL risk düzeyleri başvuru belgesi risk merdivenini ve kapıyı tanımlar.

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

1. create_pdf → içeriği set_font/add_text ile oluşturun.
2. output_pdf aracı bir file_path ile → kapı bir doğrulama isteği zarfı döndürür (dosya yazılmaz).
3. Doğrulama isteğini insana iletin.
4. Onaydan sonra, output_pdf aracını aynı argümanlar ve doğrulama isteğindeki belirtece ayarlanmış _confirmation_token ile yeniden çağırın → dosya yazılır ve oturum yok edilir.

Kod örneği — üretim

• Doğrulama isteğini her zaman bir duraklama olarak ele alın. Döngü içinde yeniden denemeyin ve bir belirteç uydurmayın.
• Belirteç tek kullanımlıktır ve araç adına bağlıdır. output_pdf için verilen bir belirteç, başka bir aracı yetkilendiremez.
• İnsan onayı reddederse, yeniden çağrı yapmayın. Baytları bir dosya yazmadan elde etmek için, bunun yerine output_pdf aracını base64 modunda çağırın. Bunun için oturumun hâlâ var olması gerekir; bu nedenle buna ihtiyaç duymayı bekliyorsanız, kapıya tabi denemede destroy: false kullanın.
• Belirteç onaydan önce geçerliliğini yitirirse, kapı yeni bir doğrulama isteği oluşturur. Yenisini iletin.

Uç durumlar ve dikkat edilecek noktalar

• Belirteç hiç sağlanmadı. İşlem beklemede kalır. İnsan onayı alınmalı, ardından doğrulama isteği iletilip yeniden çağrı yapılmalıdır.
• Süresi dolmuş belirteç. Yeni bir doğrulama isteği oluşturulur. Bunu yeniden iletin.
• Yanlış araç. Belirteçler araca bağlıdır. Farklı bir araç için yeniden kullanım başarısız olur ve yeni bir doğrulama isteği oluşturulur.
• Mutlak olmayan yol. Geçersiz bir yol olarak kapıdan önce reddedilir.
• Yazma izni yok / disk dolu. Bu, onaydan sonra gerçekleşen bir dosya yazma hatasıdır. Bunu görünür kılın. Körü körüne yeniden denemeyin.
• Yeniden çağrıdan önce yok edilen oturum. Daha önceki bir output_pdf çağrısı destroy: true kullandıysa, oturum yok olmuştur. Onay için gidiş-dönüş bekliyorsanız destroy: false kullanın.

Performans

Kapı, bir belirteç deposu araması ve insan onayı için bir gidiş-dönüş ekler. Geçen süreyi sunucu değil, insan belirler. Profil structural türündedir.

Güvenlik notları

Kapı, bir aracı ile sunucunun dosya sistemi arasındaki sınırdır. Bir dosya yazma işlemi, insanın yetkilendirmesi gereken geri alınamaz bir yan etki olduğu için vardır. Belirteç tek kullanımlık, araca bağlı ve süre sınırlıdır. Argümanlar bilinçli olarak belirtece katılmaz; çünkü istemciler JSON’u farklı bir anahtar sırasıyla yeniden seri hâle getirebilir. Bu nedenle bağlama, argümana birebir bağlı değil, araç + nonce + TTL şeklindedir. Belirteci günlüğe kaydetmeyin. Bunu tek kullanımlık bir sır olarak ele alın.

Uyumluluk

İfade	Belirtim	Madde	reference_id
Bekleyen bir onay, bir hata değil, normal bir yanıttır.	PSR-18	§3
Taşıma katmanı, sonuçtan bağımsız olarak bir yanıt döndürür.	PSR-18	§p2

Bu tarif, kapı mekanizmasını açıklar. Kapının herhangi bir işlemi “güvenli” hâle getirdiğini ileri sürmez. Kapı, bir yan etkiyi insan tarafından yetkilendirilmiş hâle getirir.

Ticari bağlam

Geçerli değil — kapı ve output_pdf Core kapsamındadır.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	Doğrulama isteği, insanın onaylaması için bir araç sonucu olarak ana makineye gösterilir.
REST	Evet	Doğrulama isteği yanıt gövdesinde döndürülür; belirteçle yeniden çağrı yapın.
gRPC	Evet	Tekli (unary); doğrulama isteği yanıt iletisidir; belirteçle yeniden çağrı yapın.

HITL risk düzeyi

Risk merdiveni şöyledir: Güvenli (0) → Dikkat (1) → İnceleme (2) → Onay Gerekli (3). Yalnızca Onay Gerekli araçlar insan doğrulaması ister. output_pdf Onay Gerekli düzeyindedir. Base64 modu, bunu İnceleme düzeyine düşürür ve kapıyı atlar. Dosya modu, Onay Gerekli düzeyini korur ve çağrıyı kapıya tabi tutar. Standart merdiven ve ilke çözümlemesi, HITL risk düzeyleri başvuru belgesi içinde yer alır.

Doğrulama kapısı JSON zarfı

Sunucunun doğrulama kapısının sunduğu kapı sonucunun tam olarak iki biçimi vardır:

İzin verildi (Güvenli/Dikkat/İnceleme ya da geçerli bir belirteç tüketildi):

{ "allowed": true }

Doğrulama isteği (geçerli bir belirteç olmadan Onay Gerekli):

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: output_pdf\nDescription: <tool description>\n\nTo proceed, call output_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

Hedef dosya zaten varsa, challenge metni ayrıca üzerine yazma uyarısı satırı içerir. Aynı aracı, _confirmation_token değeri token değerine ayarlanmış olarak yeniden çağırmak { "allowed": true } döndürür ve işlem devam eder. Belirteç tek kullanımlıktır ve doğrulama isteğinde belirtilen süre sonunda geçerliliğini yitirir.

Ayrıca bkz.

• Merhaba dünya
• Hata işleme
• HITL risk düzeyleri
• Araç kataloğu