NextPDF Connect geliştirici kılavuzu

Bir bakışta

NextPDF Connect (nextpdf/server), çerçeveden bağımsız NextPDF PDF 2.0 motorunu bir hizmet olarak sarmalar. PDF üretimini yeniden uygulamaz. Motorun her yeteneğini şemalı, adlandırılmış bir araç olarak sunar; ardından bu kataloğu üç taşıyıcı üzerinden kullanıma açar: standart girdi ve çıktı üzerinden Model Context Protocol (MCP), Representational State Transfer (REST) Application Programming Interface (API) ve gRPC. Sunucuyla geliştirme yaparken, araç kümesini genişletirken ya da sunucuyu üretimde çalıştırırken bu kılavuzu kullanın.

Tasarımını üç kavram belirler: araç kayıt defteri, üç bağımsız taşıyıcı ve döngüde insan (HITL) onay geçidi. Bu sayfa, bunların birlikte nasıl çalıştığını ve güvenlik modelini zayıflatmadan onlarla nasıl çalışabileceğinizi açıklar. Tam araç, uzaktan yordam çağrısı (RPC) ve ileti simgeleri için API başvurusuna bakın.

Ön koşullar: PHP 8.4, Composer 2 ve ağ üzerinden çalışan taşıyıcılar için RoadRunner ikili dosyası ile en az bir API anahtarı. composer require nextpdf/server komutuyla kurun.

Mimari sınırlar

Her sorumluluğu sınırının doğru tarafında tutun. Bir araç, motor çağrısı çevresinde ince bir sarmalayıcıdır; yerleşim yorumlaması, belge anlamı veya dönüşüm mantığı içermemelidir.

Katman	Sahibi	Sorumluluk	Buraya koymayın
İstemci veya aracı	Tümleştirmeniz	Hangi aracın çağrılacağını seçmek; onay sınamalarını bir insana iletmek.	Motor mantığı veya katman algılama.
Taşıyıcı	`nextpdf/server`	İstekleri JSON-RPC, HTTP veya Protocol Buffers olarak çerçevelemek; kimlik doğrulamak ve araç yürütücüsüne yönlendirmek.	Belge anlamı.
Araç kayıt defteri	`nextpdf/server`	Katmanları keşfetmek, güvenlik izin listesine tabi olarak araçları kaydetmek, bir aracı ada göre aramak.	PDF üretimi.
Araç	`nextpdf/server`	Bağımsız değişkenleri girdi şemasına göre doğrulamak ve motoru çağırmak.	Yerleşim yorumlaması veya çok adımlı düzenleme.
Onay geçidi	`nextpdf/server`	Bir insan onaylayana kadar bir `ApprovalRequired` işlemini bekletmek.	Çağıranın kimlik doğrulaması.
Motor	`nextpdf/core` (ve `nextpdf/premium`)	PDF içeriği üretmek, incelemek ve dönüştürmek.	Taşıyıcı veya kimlik doğrulama konuları.

Çalışma zamanı yaşam döngüsü

Her taşıyıcının kendi giriş noktası ve başlatma fabrikası vardır. Her biri nesne grafiğini açıkça oluşturur. Kayda geçirilecek bir bağımlılık enjeksiyonu konteyneri yoktur.

Yapılandırmayı yükleyin. MCP sunucusu yapılandırmayı önce ortam değişkenlerinden (NEXTPDF_MCP_*), ardından YAML dosyasının nextpdf_mcp bölümünden, sonra da yerleşik varsayılanlardan çözümler ve bir readonlyMcpConfig oluşturur. REST ve gRPC sunucuları HttpConfig değerini NEXTPDF_* ortam değişkenlerinden okur. Yapılandırma bölümüne bakın.
Güvenlik ilkesini oluşturun. enabled_tools izin listesi kayıt defterinden önce oluşturulur, böylece ilk kayıttan itibaren keşfi kısıtlar.
Kayıt defterini oluşturun ve araçları keşfedin. ToolRegistry::registerDefaults() önce çekirdek katmanı, ardından sınıfları çözümlenebildiğinde Pro ve Enterprise sağlayıcılarını, sonra da ortam geçitlerine tabi paketlenmiş AST ve mutasyon sağlayıcılarını kaydeder.
Paylaşılan depoları ve geçidi oluşturun. Bellek içi belge deposu, yapılandırılan TTL ve kapasiteye göre oluşturulur; ConfirmationGate, tek kullanımlık belirteç deposuyla birlikte kurulur.
Taşıyıcıyı bağlayın. MCP, dosya sonuna kadar stdio üzerinde bir oku-işle-yaz döngüsüne girer. REST ve gRPC, algılanan katmanlardan yol veya hizmet tablolarını oluşturur, ardından istek döngüsünü RoadRunner’a devreder.

Bundan sonra bir istek şu yolu izler: kimlik doğrula (REST ve gRPC), aracı veya işlemi çözümle, ApprovalRequired işi için onay geçidini çalıştır, motor üzerinde yürüt ve sonucu döndür. Başlatma ve keşif bölümüne bakın.

Taşıyıcı modeli

Üç taşıyıcı; kayıt defteri, yapılandırma ve geçit kavramlarını paylaşır, ancak bağımsız süreçler olarak çalışır. Birini başlatmak diğerlerini başlatmaz.

Taşıyıcı	Giriş noktası	Ne zaman seçilmeli
MCP	`bin/nextpdf-mcp`	Sunucuyu güvenilir bir alt süreç olarak başlatan yerel bir yapay zeka (AI) istemcisi.
REST	`bin/nextpdf-server`	Ağ üzerinden HTTP istemcileri; bir OpenAPI 3.1 belgesiyle tanımlanır.
gRPC	`bin/nextpdf-grpc`	Türlendirilmiş, akış tabanlı istemciler; `nextpdf.connect.v1.NextPDFConnect` hizmeti.

Taşıyıcıları, çalıştırdığınız RoadRunner profiline göre seçin: .rr.yaml (yalnızca REST), .rr.grpc.yaml (yalnızca gRPC) veya .rr.full.yaml (her ikisi). MCP taşıyıcısı düz bir alt süreçtir ve bir gözetmene gerek duymaz. Bağlantı ayrıntıları için MCP taşıyıcısı, REST taşıyıcısı ve gRPC taşıyıcısı bölümlerine bakın.

Önerilen dağıtım yapısı

Ağ üzerinden çalışan taşıyıcıları, paylaşılan depolar ve gizli dizi olarak bağlanan anahtarlarla RoadRunner altında çalıştırın. Birleşik profil, REST ve gRPC’nin tek bir gözetmeni paylaşmasına olanak tanır.

Yol veya ayar	Amaç
`.rr.full.yaml`	Tek bir gözetmen altında birleşik REST ve gRPC profili.
`NEXTPDF_API_KEYS_FILE`	Gizli dizi olarak bağlanan, çalışırken yeniden yüklenen bir API anahtarı dosyasının yolu.
`NEXTPDF_REDIS_HOST`	Birden çok işçi havuzu için Redis destekli hız sınırlaması, idempotency ve belge depolarını etkinleştirir.
`NEXTPDF_WORKER_COUNT` / `NEXTPDF_GRPC_WORKER_COUNT`	HTTP ve gRPC havuzları için işçi havuzu boyutlandırması.
Çıktı temel dizini	Dosya çıktısı üreten araçlar için en düşük ayrıcalıklı dosya sistemi izinlerine sahip ayrılmış bir birim.

Aşağıdaki kabuk örneği, birleşik profili gizli dizi olarak bağlanan anahtarlar ve paylaşılan bir Redis deposuyla başlatır. Hiçbir gizli dizi içermez; anahtarlar /run/secrets/api-keys konumuna bağlanır.

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
export NEXTPDF_GRPC_WORKER_COUNT=4
export NEXTPDF_REDIS_HOST=redis
./vendor/bin/rr serve -c .rr.full.yaml

Birden çok işçi havuzu için Redis’i yapılandırın ve ext-redis uzantısının çalışan imajda bulunduğunu doğrulayın. Bu uzantı olmadan hız sınırlaması, idempotency ve belge depoları işçi başına ayrı olur. dağıtım bölümüne bakın.

Araç kayıt defteri ve katman çözümlemesi

NextPDF\Server\ToolRegistry (src/ToolRegistry.php), kataloğu başlatma sırasında oluşturur. Katman, beyan edilen bir değişmezdir: her araç kendi tier() ve riskLevel() değerini döndürür. Kayıt defteri katmanı asla ad alanından ya da paketlemeden çıkarsamaz.

Çekirdek katman şunları koşulsuz olarak kaydeder: belge ve tanılama araçları, ayrıca çekirdek barkod kodlayıcı kayıt defteri mevcut olduğunda generate_barcode aracını ve yalnızca parse_pdf aracını NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED değeri true ya da 1 olduğunda kaydeder.
Pro ve Enterprise sağlayıcıları, sağlayıcı sınıfları çözümlenebildiğinde kayıt yapar; bu durum class_exists() ile yoklanır. Mevcut olmayan bir katman sessizce atlanır.
Paketlenmiş AST ve mutasyon sağlayıcıları, Pro katmanı altında kaydedilir; bunlar NEXTPDF_AST_TOOLS_ENABLED ve NEXTPDF_MUTATION_TOOLS_ENABLED ile geçit altına alınır (her ikisi de varsayılan olarak etkindir).
Güvenlik ilkesi filtresi, her kaydı enabled_tools izin listesiyle kesiştirir. İzin listesi çıkarır; asla eklemez. Katman başına sayaç yalnızca ilkenin kabul ettiği araçları sayar.

MCP initialize yanıtı ve REST GET /api/v1/capabilities uç noktası, ortaya çıkan katman başına sayıları ve toplamı bildirir. Metinde sabit belirtilen herhangi bir toplamı eskimiş kabul edin; çalışan sunucuyu sorgulayın. Araç kataloğu bölümüne bakın.

Risk katmanları ve onay geçidi

Her araç, RiskLevel enum’undan (src/Config/RiskLevel.php) dört risk düzeyinden birini bildirir: Safe (0), Caution (1), Review (2) ve ApprovalRequired (3). Denetim günlüğü Caution ve üzeri için uygulanır. Bir yapılandırma geçersiz kılması, bir aracın riskini yükseltebilir; tasarımı gereği ApprovalRequired olan bir aracı asla düşüremez. Yapılandırma yükleyicisi yükleme sırasında bir istisna fırlatır ve sunucu, zayıflatılmış bir geçitle çalışmak yerine başlatılmayı reddeder.

Geçerli bir belirteç olmadan bir ApprovalRequired aracı çağrıldığında, ConfirmationGate (src/Mcp/ConfirmationGate.php) tek kullanımlık bir sınama belirteci döndürür. Belirteç; araç adını, rastgele bir nonce’u ve 300 saniyelik bir yaşam süresini (TTL) bağlar, ancak bağımsız değişkenleri bağlamaz, çünkü istemciler yeniden denemede bağımsız değişkenleri farklı bir anahtar sıralamasıyla yeniden serileştirebilir. Çağıran taraf sınamayı bir insana iletir ve aynı aracı, belirteci _confirmation_token bağımsız değişkenine koyarak yeniden çağırır. Belirteç kullanıldığında tüketilir ve tam olarak bir geçitle korunan çağrıyı serbest bırakır.

Aşağıdaki PHP örneği, taşıyıcıdan bağımsız bir yardımcıdır. Bir MCP araç çağrısını yürütür ve bir onay sınaması geldiğinde, verilen belirteçle yeniden denemeden önce sınamayı bir insan onaylayıcıya gösterir. Strict types bildirir, bütünüyle tür ipuçlarıyla tanımlıdır ve her hatayı yutmak yerine en özgül istisnayı yakalar.

<?php

declare(strict_types=1);

namespace App\Connect;

use JsonException;

/**
 * Drives one tool call and resolves an ApprovalRequired confirmation
 * challenge through a human approver before retrying.
 */
final readonly class ConfirmingToolCaller
{
    public function __construct(
        private McpClientInterface $client,
        private HumanApproverInterface $approver,
    ) {}

    /**
     * @param non-empty-string     $toolName
     * @param array<string, mixed> $arguments
     *
     * @return array<string, mixed> The tool result content
     *
     * @throws JsonException         When a response cannot be decoded
     * @throws ApprovalDeniedException When the human declines the challenge
     */
    public function call(string $toolName, array $arguments): array
    {
        $response = $this->client->callTool($toolName, $arguments);

        if (!isset($response['challenge'], $response['token'])) {
            return $response;
        }

        $challenge = (string) $response['challenge'];
        $token = (string) $response['token'];

        if (!$this->approver->approve($toolName, $challenge)) {
            throw new ApprovalDeniedException($toolName);
        }

        $arguments['_confirmation_token'] = $token;

        return $this->client->callTool($toolName, $arguments);
    }
}

Kendi taşıyıcınıza ve onay kanalınıza McpClientInterface, HumanApproverInterface ve ApprovalDeniedException öğelerini bağlayın. Yeniden deneme, özgün bağımsız değişkenleri ve verilen belirteci yeniden kullanır; bir insan kararı olmadan bir sınamayı asla otomatik onaylamayın. Ayrıntılar için HITL risk katmanları bölümüne bakın.

Genişletme noktaları

Sunucuyu, kayıt defterini düzenleyerek değil, araçlar ekleyerek ve sağlayıcılar sunarak genişletin.

Genişletme noktası	Ne için kullanılır	Kısıt
Şu arabirimi uygulayan bir sınıf: `ToolInterface`	Araç olarak sunulan yeni bir motor yeteneği.	Şu değerleri bildirin: `tier()`, `riskLevel()`, `category()` ve bir JSON Schema `inputSchema()`; sınıfı ince bir motor sarmalayıcısı olarak tutun.
Bir `ToolProviderInterface` sağlayıcısı	Bir katman için bir araç kümesini kaydetmek.	Pro ve Enterprise sağlayıcıları `class_exists()` ile keşfedilir; özel paketi sunucu için zorunlu kılmayın.
`enabled_tools` izin listesi	Sunulan kataloğu en düşük ayrıcalıkla sınırlandırmak.	İzin listesi yalnızca çıkarır; mevcut olmayan bir aracı kaydedemez.
`risk_level_overrides`	Bir aracın riskini yükselterek bir dağıtımı sertleştirmek.	Yalnızca yükseltir; bir `ApprovalRequired` aracının düşürülmesi başlatmayı başarısız kılar.
Enjekte edilebilir taşıyıcı ve işçi bağlantı noktaları	Sunucuyu yalıtılmış olarak test etmek.	Bu sınırlar testler içindir, uygulamayı bağlamak için değil.

İşletim iş akışı

Bir profil seçin. Sunduğunuz taşıyıcılar için .rr.yaml, .rr.grpc.yaml ya da .rr.full.yaml çalıştırın.
Anahtarları bir gizli diziden bağlayın. NEXTPDF_API_KEYS_FILE değerini bir gizli dizi dosyasına yönlendirin; anahtar döndürmenin yeniden başlatma gerektirmemesi için çalışırken yeniden yüklenen dosya anahtar deposunu tercih edin.
Paylaşılan depoları yapılandırın. Birden fazla işçisi olan her havuz için NEXTPDF_REDIS_HOST değerini ayarlayın ve ext-redis uzantısını doğrulayın; SQLite iş deposunu tüm işçilerin yazabileceği bir birime koyun.
TLS’i sonlandırın. REST’i bir Transport Layer Security (TLS) sonlandırıcısının arkasında çalıştırın; gRPC’yi güvenilmeyen herhangi bir ağda karşılıklı TLS ile çalıştırın; sunucu anahtarı, sunucu sertifikası ve istemci sertifika yetkilisini dağıtım gizli dizileri olarak sağlayın.
Sağlığı yoklayın. Düzenleyici yoklamaları için anonim /healthz ve /readyz uç noktalarını (REST) ya da HealthCheck ve ReadinessCheck RPC’lerini (gRPC) kullanın.
Kataloğun kapsamını daraltın. enabled_tools öğesini bir tümleştirmenin gereksinim duyduğu en küçük kümeyle sınırlayın.

Redis sağlığını varsaymak yerine doğrulayın. Yapılandırılmış bir Redis bağlantısı başarısız olduğunda REST sunucusu bellek içi depolara geri döner. dağıtım ve Güvenlik ve işletim bölümlerine bakın.

Hata işleme

Hata	Nerede ortaya çıkar	Önerilen yanıt
Bilinmeyen `document_id`	Araç yürütme	Çağıran tarafa tanımlı bir hata döndürün; önce `create_pdf` aracını çağırması için yönlendirin.
Bir mutasyonda eskimiş ETag	AST mutasyon aracı	Belgeyi `get_document_ast` ile yeniden okuyun ve güncel ETag ile yeniden deneyin.
Eksik ya da geçersiz API anahtarı (REST)	Kimlik doğrulama ara katmanı	Bir `401` ile birlikte bir `WWW-Authenticate: Bearer` sınaması döndürün; hangi kısmın yanlış olduğunu sızdırmayın.
Katman yetkisi yok (REST)	Yetkilendirme	Bir `403` döndürün; anahtarın katmanı, işlemin katmanının altındadır.
Katman yolu yok (REST)	Yönlendirici	Bir `404` döndürün; paket kurulu değildir. Bu, bir arıza değil, beklenen bir durumdur.
Hatalı belirteç (gRPC)	gRPC kimlik doğrulayıcısı	Çağrıyı `UNAUTHENTICATED` ile başarısız kılın.
Redis’e erişilemiyor	Başlatma ya da çalışma zamanı	Bellek içi depolara geri dönün; operatörleri uyarın ve Redis sağlığını doğrulayın.
Temel dizinin dışındaki çıktı yolu	Dosya çıktısı aracı	Kapalı biçimde başarısız olun; yol kanonikleştirilir ve dizin gezinmesi reddedilir.

Motor hatalarını sessiz başarılar olarak değil, tanımlı hata nesneleri olarak ortaya çıkarın. API başvurusu, her taşıyıcı için hata modelini ayrıntılandırır.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
`parse_pdf`	Devre dışı (`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED` ile etkinleştirme).	Yalnızca bir tümleştirme yapısal inceleme gerektiriyorsa etkinleştirin.
`enabled_tools`	Boş (keşfedilen tüm araçlara izin verilir).	En düşük ayrıcalıkla çalışan dağıtımlar için açık bir izin listesi ayarlayın.
Risk geçersiz kılmaları	Yok.	Sertleştirilmiş bir dağıtım için riski yükseltin; asla bir düşürme girişiminde bulunmayın.
`document_ttl` / `max_documents`	1800 saniye / 50 belge.	Veri yerleşimine duyarlı ya da bellek sınırlı dağıtımlar için düşürün.
`allow_file_output`	Etkin.	Durumsuz, veri yerleşimine duyarlı dağıtımlar için `false` olarak ayarlayın.
İşçi sayısı	Dört (HTTP), iki (gRPC).	Gözlemlenen gecikme ve kullanılabilir çekirdeklere göre boyutlandırın.
REST dinleyicisi	Bir TLS sonlandırıcısının arkasında düz metin HTTP.	TLS’i her zaman yukarı akışta sonlandırın; güvenilmeyen bir ağda düz metin HTTP’yi asla açığa çıkarmayın.
Güvenilmeyen ağlarda gRPC	Karşılıklı TLS.	Zorunlu; güvenilmeyen bir ağda asla düz metin bir gRPC dinleyicisi çalıştırmayın.

Test denetim listesi

Kayıt defteri testleri, mevcut olmayan bir Pro veya Enterprise katmanının sessizce atlandığını ve çekirdek kataloğunun yine de kaydedildiğini doğrular.
İzin listesi testleri, enabled_tools öğesinin yalnızca çıkardığını ve kayıt defterinin keşfetmediği bir aracı asla eklemediğini doğrular.
Onay geçidi testleri, bir ApprovalRequired aracının ilk çağrıda bir sınama döndürdüğünü, geçerli tek kullanımlık bir belirteçle bir kez çalıştığını ve belirtecin TTL’sinden sonra süresinin dolduğunu doğrular.
Düşürme testleri, bir risk_level_overrides girdisinin bir ApprovalRequired aracını zayıflatmasının başlatmayı başarısız kıldığını doğrular.
Kimlik doğrulama testleri REST’te (401, WWW-Authenticate ile) ve gRPC’de (UNAUTHENTICATED) eksik, hatalı biçimli, devre dışı ve süresi dolmuş anahtarları, ayrıca katman yetkisi reddini (403) kapsar.
Eşzamanlılık testleri, eskimiş bir ETag’in bir mutasyonu başarısız kıldığını ve yinelenen bir idempotency_key öğesinin önbelleğe alınmış sonucu yeniden oynattığını doğrular.
Yol kapsama testleri, temel dizinin dışına çözümlenen bir dosya çıktı yolunun reddedildiğini doğrular.
Test düzeneklerini küçük ve duyarlı olmayan içerikle tutun; gerçek bir API anahtarını veya belge içeriğini asla bu düzeneklere eklemeyin.

Ayrıca bakın

API başvurusu — tam araç, RPC ve ileti simgeleri
Araç kataloğu — doğrulanmış çekirdek küme ve çalışma zamanı sayısı
HITL risk katmanları — risk modeli ve onay zarfı
Yapılandırma — çözümleme sırası ve yalnızca yükseltme yapan geçersiz kılma
dağıtım — RoadRunner profilleri, Redis ve karşılıklı TLS
Güvenlik ve işletim — kimlik doğrulama, taşıyıcı güvenliği ve tehdit modeli