Type Server Protocol: JSON-RPC Microsoft untuk Analisis Tipe Python

Type Server Protocol adalah protokol JSON-RPC yang dipakai untuk meminta data analisis Python dari sebuah type server, dan definisi resminya disimpan terbuka di repositori pylance-release milik Microsoft. Menurut dokumen protokolnya, sebuah type server memegang status analisis tipe untuk satu workspace dan menjawab permintaan soal versi protokol, snapshot, jalur pencarian Python, resolusi impor, serta kueri tipe.

TL;DR

• Type Server Protocol memakai JSON-RPC, dengan seluruh method memakai awalan typeServer/.
• Type server menyimpan status analisis tipe untuk satu workspace, bukan untuk satu berkas.
• Kueri tipe dibagi tiga: tipe hasil hitung, tipe yang dideklarasikan, dan tipe yang diharapkan.
• Protokolnya meminjam bentuk data Language Server Protocol, termasuk Position dan Range.
• Definisi protokolnya tersedia sebagai berkas TypeScript, model JSON, dan skema JSON.

Apa itu Type Server Protocol?

Type Server Protocol, disingkat TSP, adalah protokol JSON-RPC untuk meminta data analisis Python dari sebuah type server. Dokumentasinya menjelaskan bahwa type server memegang status analisis tipe untuk sebuah workspace dan menjawab permintaan yang berkaitan dengan versi protokol, snapshot, jalur pencarian Python, resolusi impor, dan kueri tipe.

Penamaan method-nya konsisten. Semua method protokol ini memakai awalan typeServer/, yang membuatnya mudah dibedakan dari method lain di jalur komunikasi yang sama. Untuk urusan representasi data, TSP mengambil bentuk dan konvensi Language Server Protocol ketika bentuk itu memang berguna, misalnya tipe Position dan Range, serta cara merepresentasikan URI sebagai string.

Yang membedakannya dari protokol editor biasa adalah pembagian tugas peran. Type server bertanggung jawab atas analisis, sementara klien bertanya. Pembagian itu menjelaskan kenapa kueri tipe dipisah menjadi tiga jenis: tipe hasil hitung, tipe yang dideklarasikan di kode, dan tipe yang diharapkan oleh konteks pemakaian.

Kenapa analisis tipe dipisahkan ke server sendiri?

Karena status analisis tipe bersifat per workspace dan bisa terus berubah, memisahkannya ke satu server membuat beberapa klien bisa bertanya ke sumber yang sama. Dokumentasinya menyebut type server menjawab permintaan soal snapshot dan jalur pencarian Python, yang keduanya adalah keadaan yang perlu dihitung sekali lalu dibagikan.

Pendekatan berbasis snapshot itu masuk akal untuk alat pengembangan. Kalau setiap klien menghitung ulang analisis dari nol, hasil antar klien bisa berbeda dan waktu tunggu bertambah. Dengan snapshot, klien yang sama-sama memakai workspace itu mendapat gambaran yang konsisten walaupun berkasnya sedang berubah.

Satu hal yang perlu ditegaskan: dokumen protokolnya tidak menyatakan janji kompatibilitas jangka panjang. Justru sebaliknya, dokumen itu mengatur urusan versi secara eksplisit, dan bagian itu akan dibahas di bawah karena berdampak langsung bagi siapa pun yang berniat membangun klien.

Data apa saja yang bisa diminta dari type server?

Ada lima kelompok permintaan yang disebut dokumen protokolnya: versi protokol, snapshot, jalur pencarian Python, resolusi impor, dan kueri tipe. Kelima kelompok itu menjelaskan pembagian kerja yang cukup rapi antara klien yang bertanya dan server yang menyimpan keadaan analisis.

Permintaan	Isi jawaban	Dipakai untuk
Versi protokol	Versi yang dilayani server	Memastikan klien dan server masih cocok sebelum bertukar data
Snapshot	Gambaran keadaan analisis pada satu waktu	Memberi klien dasar yang konsisten saat berkas sedang berubah
Jalur pencarian Python	Daftar lokasi yang dicari saat resolusi	Menjelaskan kenapa sebuah impor dianggap ada atau tidak ada
Resolusi impor	Hasil pemetaan nama impor ke sumbernya	Menelusuri asal sebuah modul di dalam workspace
Kueri tipe	Tipe hasil hitung, deklarasi, atau harapan konteks	Menampilkan tipe pada posisi tertentu di dalam kode

Tabel di atas juga menjelaskan kenapa urutan permintaan itu biasanya seperti itu. Klien memeriksa versi lebih dulu, mengambil snapshot, lalu bertanya soal jalur pencarian dan resolusi impor, dan baru setelah itu mengajukan kueri tipe pada posisi yang diinginkan.

Bagaimana versi protokol ini diperlakukan?

Dengan versi semantik, sebagaimana dijelaskan di bagian riwayat versi dokumennya. Selama protokol ini masih di jalur 0.x, perubahan versi minor bisa merusak kompatibilitas, sementara perubahan versi patch tetap kompatibel selama masih di jalur minor yang sama.

Konsekuensi praktisnya penting bagi siapa pun yang membangun klien. Menargetkan jalur 0.x berarti Anda harus membaca catatan perubahan setiap kali nomor minor naik, bukan hanya setiap kali nomor mayor naik. Sebaliknya, naik dari satu patch ke patch lain di jalur minor yang sama relatif lebih aman.

Pola itu bukan kebetulan. Penomoran 0.x biasanya dipakai ketika spesifikasi masih bergerak cepat dan penulisnya ingin ruang untuk memperbaiki desain tanpa harus mengumumkan versi mayor. Jadi perlakukan dokumen ini sebagai spesifikasi hidup: periksa versinya, cocokkan dengan yang dilayani server, dan jangan menganggap bahwa klien yang bekerja bulan ini akan otomatis bekerja setelah nomor minor berubah.

Di mana definisi resmi protokolnya disimpan?

Di dalam repositori pylance-release, tepatnya pada folder dokumentasi protokol tipe. Dokumen protokolnya menyebut tiga artefak sebagai definisi otoritatif: berkas TypeScript yang memuat interface dan tipe permintaan, berkas model protokol dalam format JSON, serta berkas skema JSON untuk model tersebut.

Memakai tiga artefak itu bersama-sama lebih kuat daripada membaca dokumentasi naratif saja. Berkas TypeScript menjelaskan bentuk tipe, berkas model JSON memberi gambaran mesin-terbaca tentang method dan muatannya, dan skema JSON dipakai untuk memvalidasi muatan tersebut. Kalau ada perbedaan antara narasi dan artefak, artefak yang berlaku.

Apa hubungannya dengan Language Server Protocol?

Hubungan yang paling jelas ada di dua tempat: protokol transport dan bentuk data. TSP adalah protokol JSON-RPC, sama seperti protokol editor lain yang memakai JSON-RPC sebagai jalur komunikasi. Untuk bentuk data, dokumen TSP menyatakan dirinya memakai tipe dan konvensi Language Server Protocol saat bentuk itu berguna, misalnya Position dan Range.

Aspek	Language Server Protocol	Type Server Protocol
Fokus	Fitur editor: lengkapi otomatis, lompat definisi, diagnostik	Analisis tipe: snapshot, resolusi impor, kueri tipe
Awalan method	Method per area fitur	Seluruh method memakai awalan typeServer/
Bentuk data	Position, Range, URI sebagai string	Memakai bentuk dan konvensi LSP saat berguna
Cakupan keadaan	Berorientasi berkas dan workspace	Status analisis tipe untuk satu workspace

Bedanya bukan soal mana yang lebih baik, tapi soal cakupan. LSP didesain untuk melayani beragam bahasa dan fitur editor, sehingga permukaannya lebar. TSP lebih sempit dan lebih dalam: ia hanya mengurus analisis tipe Python, tapi mengurusnya sampai ke level snapshot dan jenis tipe.

Karena meminjam bentuk data yang sama, sebuah klien yang sudah terbiasa membaca LSP tidak perlu mempelajari konsep posisi dan rentang dari nol. Yang perlu dipelajari justru bagian analisisnya: kapan snapshot diambil, bagaimana jalur pencarian dibaca, dan bagaimana tiga jenis kueri tipe dibedakan.

Bagaimana memulai implementasi klien?

Urutan yang paling hemat waktu: baca berkas TypeScript definisi protokolnya lebih dulu, lalu cocokkan dengan model JSON, baru validasi pemahaman Anda dengan skema JSON. Setelah bentuk pesannya jelas, baru siapkan lapisan transport JSON-RPC dan penanganan kesalahan versi.

Perhatikan juga lingkungan Python yang jadi sasaran analisis. Jalur pencarian Python yang dilaporkan server dipengaruhi oleh lingkungan yang dipakai saat server dijalankan, jadi jangan heran kalau hasil resolusi impor berbeda antara dua lingkungan yang berbeda. Ini termasuk hal yang paling sering membingungkan saat pertama kali menguji klien.

Terakhir, siapkan strategi menghadapi perubahan versi sejak awal. Karena protokolnya masih di jalur 0.x, perubahan minor bisa merusak kompatibilitas. Praktik yang masuk akal adalah menolak bertukar data ketika versi klien dan server tidak cocok, lalu melaporkan perbedaannya dengan jelas, bukan memaksa jalan dan menghasilkan jawaban yang menyesatkan.

FAQ

Apakah Type Server Protocol menggantikan Language Server Protocol?

Tidak disebutkan begitu. Dokumennya menjelaskan TSP sebagai protokol tersendiri untuk analisis tipe, dan justru memakai kembali bentuk serta konvensi Language Server Protocol di tempat yang berguna, bukan menyatakannya sebagai pengganti.

Di mana dokumentasi resmi protokolnya bisa dibaca?

Di repositori pylance-release, pada folder dokumentasi protokol tipe. Untuk memahami bentuk data yang dipinjamnya, rujukan resminya ada di situs Language Server Protocol.

Protokol transport apa yang dipakai?

JSON-RPC. Spesifikasinya dijelaskan di jsonrpc.org, dan muatannya berupa objek JSON yang mengikuti bentuk permintaan dan jawaban yang sudah ditentukan di dalam protokolnya.

Apakah ini khusus Python?

Ya, fokusnya Python. Contoh kueri yang disebut dokumennya menyangkut analisis tipe pada kode Python, dan artefak protokolnya dipelihara di repositori alat Python milik Microsoft. Untuk bahasa lain, padanannya perlu dicari di masing-masing ekosistem.

Di mana saya bisa membaca referensi bahasa Python-nya?

Untuk urusan sintaks dan perilaku bahasa yang jadi dasar analisis, rujukan utamanya adalah dokumentasi resmi Python 3. Protokolnya sendiri tidak menggantikan dokumentasi bahasa, hanya menyediakan cara bertanya soal tipe.

Apa yang membedakan tiga jenis kueri tipe?

Dokumen protokolnya membedakan tiga jenis kueri tipe: tipe yang dihitung dari kode, tipe yang dideklarasikan secara eksplisit, dan tipe yang diharapkan oleh konteks pemakaian. Perbedaan itu bukan detail istilah, karena ketiganya bisa memberi jawaban yang berbeda untuk posisi yang sama di dalam kode.

Jenis kueri	Sumber jawaban	Contoh pertanyaan yang dijawab
Tipe hitung	Hasil inferensi dari kode di sekitarnya	Apa tipe variabel ini menurut analisis?
Tipe deklarasi	Anotasi yang ditulis di kode	Apa tipe yang dituliskan penulis kode di sini?
Tipe harapan	Konteks tempat nilai itu dipakai	Tipe apa yang sebenarnya dibutuhkan di posisi ini?

Pemisahan ini berguna ketika kode tidak sepenuhnya konsisten. Sebuah fungsi bisa dianotasi menerima satu tipe, sementara pemanggilnya mengirim tipe lain, atau inferensi menyimpulkan tipe yang berbeda dari anotasinya. Dengan tiga kueri terpisah, alat bisa menampilkan ketidakcocokan itu sebagai informasi, bukan menyembunyikannya di balik satu jawaban saja.

Bagian analisisnya memang lebih sempit dibanding Language Server Protocol pada umumnya, tapi justru di situ nilai tambahnya. Klien yang butuh penjelasan soal tipe pada satu posisi tidak perlu menebak dari fitur editor yang lebih umum.