Boot dan penemuan di NextPDF Connect

Sekilas pandang

Setiap transport memiliki titik masuk dan urutan boot sendiri. Secara konseptual, transport berbagi registri, konfigurasi, dan gerbang. Masing-masing berjalan sebagai proses independen, sehingga menjalankan satu transport tidak ikut menjalankan transport lainnya.

Pemasangan

composer require nextpdf/server

Gambaran konseptual

Urutan boot MCP

McpServer::create() merangkai server Model Context Protocol (MCP) dengan urutan tetap. Pertama, ia memuat konfigurasi, membangun kebijakan keamanan dari konfigurasi tersebut, menyusun registri alat, dan menjalankan penemuan tingkatan. Selanjutnya, ia membangun penyimpanan dokumen in-memory berdasarkan time to live (TTL) dan kapasitas yang dikonfigurasi, membuat transport stdio, serta menyusun penangan protokol JSON-RPC bersama gerbang konfirmasi dan pencatat audit. Kemudian, server memasuki loop baca-tangani-tulis dan berjalan hingga standard input mencapai end of file.

Urutan boot REST

HttpServer::create() membaca HttpConfig dari lingkungan dan menerapkan penggantian command-line interface (CLI). Selanjutnya, ia menyelesaikan penyimpanan kunci API (application programming interface) dalam urutan preferensi berikut: penyimpanan berkas yang mendukung hot-reloading terlebih dahulu, lalu berkas statis, kemudian lingkungan. Setelah itu, ia menyelesaikan penyimpanan rate-limit dan idempotensi. Keduanya menggunakan Redis ketika Redis dikonfigurasi dan dapat dijangkau, lalu beralih ke penyimpanan in-memory jika tidak. Dari sana, server membuka penyimpanan tugas SQLite bersama, membangun layanan aplikasi, dan menyusun tabel rute. Karena tabel rute dibangun dari tingkatan yang terdeteksi, tabel ini mencerminkan paket yang terpasang. RoadRunner kemudian menggerakkan loop permintaan worker.

Urutan boot gRPC

GrpcServer::create() menyelesaikan penyimpanan kunci yang sama, membangun layanan aplikasi yang sama, dan mendaftarkan layanan nextpdf.connect.v1 dengan worker gRPC Spiral. Ketika dependensi mesin tidak tersedia, server gRPC tetap berjalan dan melayani kueri kesehatan serta kapabilitas. Dalam kondisi tersebut, proses tidak menolak boot; sebaliknya, remote procedure call (RPC) yang membawa data gagal dengan bersih.

Penemuan alat

Penemuan adalah langkah pendaftaran standar pada registri. Tingkatan core mendaftar terlebih dahulu. Penyedia Pro dan Enterprise mendaftar berikutnya, jika kelas-kelasnya dapat ditemukan melalui class_exists(). Penyedia Abstract Syntax Tree (AST) dan mutasi yang disertakan kemudian mendaftar di bawah tingkatan Pro, bergantung pada gerbang lingkungannya. Setiap pendaftaran disaring melalui daftar-izin keamanan enabled_tools, dan respons initialize MCP melaporkan jumlah per tingkatan yang dihasilkan. Lihat /connect/tool-catalog/.

Penemuan transport

Tidak ada satu pun setelan konfigurasi yang “mengaktifkan transport.” Setiap transport adalah titik masuk yang terpisah. REST dan gRPC masing-masing memiliki profil RoadRunner tersendiri. Deployment memilih transport berdasarkan profil yang dijalankannya: .rr.yaml untuk REST, .rr.grpc.yaml untuk gRPC, atau .rr.full.yaml untuk keduanya. Transport berjalan sebagai proses independen. Ketiadaan klien MCP tidak pernah memblokir server REST, dan ketiadaan klien REST tidak pernah memblokir MCP. Lihat /connect/deployment/.

Urutan penyelesaian konfigurasi

Server MCP menyelesaikan konfigurasi menurut urutan prioritas berikut: lingkungan (NEXTPDF_MCP_*) lebih diutamakan daripada bagian nextpdf_mcp pada berkas YAML, yang lebih diutamakan daripada nilai standar bawaan. Server REST dan gRPC membaca HttpConfig dari variabel lingkungan NEXTPDF_* dengan nilai standar yang aman. Keduanya tidak membaca berkas YAML MCP. Lihat /connect/configuration/.

Pengikatan kontainer

Tidak ada kontainer dependency-injection atau penyedia layanan yang perlu didaftarkan. Setiap factory create() menyusun grafik objeknya sendiri secara eksplisit dan deterministik. Tersedia dua titik penyuntikan (injectable seam) — transport dan factory worker — dan keduanya ditujukan untuk pengujian, bukan untuk perakitan aplikasi.

Contoh kode — Mulai cepat

Periksa hasil penemuan tanpa melayani lalu lintas:

./vendor/bin/generate-skills --dry-run --list-tools

Contoh kode — Produksi

Lakukan boot transport gabungan di bawah satu supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Kasus tepi dan hal yang perlu diwaspadai

• Tingkatan yang tidak ada tidak menggagalkan boot. Penemuan tingkatan secara diam-diam mengabaikan paket Pro atau Enterprise yang tidak ada. Server melakukan boot dengan katalog core.

• Penggantian yang menurunkan tingkat menggagalkan boot. Entri risk_level_overrides yang melemahkan alat approval_required akan menghasilkan galat selama pemuatan konfigurasi; server menolak untuk dimulai. Ini disengaja.

• Kegagalan Redis menurunkan kinerja, bukan menyebabkan crash. Jika Redis dikonfigurasi tetapi tidak dapat dijangkau saat boot, server REST beralih ke penyimpanan in-memory. Verifikasi kesehatan Redis alih-alih berasumsi bahwa Redis sedang digunakan.

Kinerja

Biaya boot berasal dari penguraian konfigurasi, pemindaian registri, dan pendeteksian tingkatan. performance_budget pada halaman ini membatasi biaya tersebut. Biaya ini ditanggung sekali pada awal proses, bukan per permintaan.

Catatan keamanan

Kebijakan keamanan dibangun sebelum registri, sehingga daftar-izin enabled_tools membatasi penemuan sejak pendaftaran pertama. Kunci API tidak pernah dibaca dari berkas YAML MCP; transport berjaringan menyelesaikan kunci dari berkas rahasia atau lingkungan. Lihat /connect/security-and-operations/.

Kesesuaian

Halaman ini menjelaskan mekanika boot. Rujukan protokol dan keamanan dicantumkan pada /transports/mcp/, /transports/rest/, /transports/grpc/, dan /connect/security-and-operations/.

Konteks komersial

Deteksi tingkatan saat boot adalah satu-satunya titik di mana nextpdf/premium menyumbangkan alat Pro dan Enterprise-nya ke katalog, ketika nextpdf/premium terpasang bersama server.

Lihat juga

• /connect/tool-catalog/ — apa saja yang didaftarkan oleh penemuan dan mengapa jumlahnya bervariasi
• /connect/configuration/ — urutan penyelesaian secara terperinci
• /connect/deployment/ — memilih transport melalui profil RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — detail per transport