JSON-RPC masofaviy chaqiruv protokoli

JSON-RPC (inglizcha JSON Remote Procedure Call — «JSON yordamida protseduralarni masofadan chaqirish») — protokol bo‘lib, u protseduralarni masofadan chaqirish (RPC) uchun xizmat qiladi; unda xabarlar JSON formatida kodlanadi. U so‘rov va javoblarning tuzilishini, parametrlarni uzatish, xatolarni qayta ishlash va bildirishnomalarni yuborish usullarini belgilaydi. JSON-RPC spetsifikatsiyasi muayyan transport protokoliga bog‘liq emas: xabarlar, jumladan, HTTP orqali yoki tarmoq soketlari orqali uzatilishi mumkin.

Protokolning e’lon qilingan asosiy versiyalari JSON-RPC 1.0 va JSON-RPC 2.0 hisoblanadi. 2.0-versiyada nomlangan parametrlar, javob talab qilmaydigan bildirishnomalar va bir nechta so‘rovni paket shaklida yuborish imkoniyati mavjud.

Tarixi

JSON-RPC protokolini ishlab chiqish 2004 yilda protseduralarni masofadan chaqirishda XML o‘rniga JSON’dan foydalanish maqsadida boshlandi. Birinchi spetsifikatsiya — JSON-RPC 1.0 — 2005 yilda e’lon qilindi.

2006 yilda JSON-RPC 1.1 spetsifikatsiyasining ishchi loyihasi paydo bo‘ldi. Unda, jumladan, nomlangan parametrlar, xatolarni batafsilroq qayta ishlash va mavjud protseduralarni tavsiflash ko‘zda tutilgan edi. Keyinchalik 1.1-versiyaning muqobil loyihalari hamda JSON-RPC 1.2 taklifi muhokama qilindi.

JSON-RPC 2.0 spetsifikatsiyasi 26-mart 2010-yilda 24-may 2009-yildagi taklif asosida e’lon qilindi. Uning yangilangan tahriri 4-yanvar 2013-yil sanasi bilan qayd etilgan.

Ishlash prinsipi

Mijoz dastur metod nomi va zarur bo‘lsa, parametrlarni ko‘rsatgan holda so‘rov yuboradi. Server so‘rovni qayta ishlaydi va natija yoki xato haqidagi xabarni qaytaradi. So‘rovni tegishli javob bilan moslashtirish uchun id identifikatoridan foydalaniladi. Javob kutilmaydigan chaqiruv bildirishnoma deb ataladi (inglizcha notification).

JSON-RPC 2.0 da so‘rov quyidagi maydonlardan iborat JSON obyekti ko‘rinishida bo‘ladi:

  • jsonrpc — protokol versiyasini belgilovchi, qiymati "2.0" bo‘lgan majburiy satr;
  • method — chaqirilayotgan metod nomini saqlovchi majburiy satr;
  • params — pozitsion parametrlar massivi yoki nomlangan parametrlar obyektidan iborat ixtiyoriy maydon;
  • id — so‘rovni javob bilan moslashtirish uchun ishlatiladigan identifikator. U satr, son yoki null bo‘lishi mumkin; null qiymatidan foydalanish tavsiya etilmaydi. Agar bu maydon bo‘lmasa, xabar bildirishnoma hisoblanadi.

Nomi rpc. bilan boshlanadigan metodlar tizim kengaytmalari uchun zaxiralangan. Metod va parametr nomlarida katta-kichik harflar farqlanadi.

So‘rov muvaffaqiyatli bajarilganda javobda jsonrpc, result va id maydonlari bo‘ladi. Xato yuz berganda result o‘rniga error obyekti qaytariladi. 2.0 spetsifikatsiyasiga ko‘ra, result va error maydonlari bitta javobda bir vaqtning o‘zida mavjud bo‘lmasligi kerak.

Protokol versiyalari

JSON-RPC 1.0 va JSON-RPC 2.0 o‘rtasidagi asosiy farqlar jadvalda keltirilgan.

Xususiyat JSON-RPC 1.0 JSON-RPC 2.0
Versiyani ko‘rsatish Versiya uchun alohida maydon mavjud emas Majburiy maydon: "jsonrpc": "2.0"
Chaqiruv parametrlari Maydon: params — massivni o‘z ichiga oladi Ixtiyoriy params maydoni massiv yoki obyektni o‘z ichiga oladi
Bildirishnoma Maydon: id — qiymati null Maydon: id — mavjud emas
Javob formati Ikkala maydon ham mavjud: result va error; ishlatilmaydigan maydonning qiymati null Faqat bitta maydon mavjud: result yoki error
Paketli so‘rovlar Paketli chaqiruv uchun alohida format belgilanmagan Istalgan tartibda qayta ishlanishi mumkin bo‘lgan so‘rovlar massivi

Bildirishnomalar

Bildirishnoma — server javob qaytarmasligi kerak bo‘lgan so‘rov. JSON-RPC 2.0 da id maydoni bo‘lmagan so‘rov obyekti bildirishnoma hisoblanadi. Bunday xabarni qayta ishlashda xato yuz bersa ham javob yuborilmaydi. "id": null ko‘rsatilishining o‘zi, JSON-RPC 1.0 dan farqli ravishda, xabar bildirishnoma ekanini anglatmaydi.

Paketli so‘rovlar

JSON-RPC 2.0 bir nechta so‘rov va bildirishnomani bitta JSON massivida yuborish imkonini beradi. Server ularni istalgan tartibda, jumladan, parallel ravishda qayta ishlashi mumkin. Javoblar massiv ko‘rinishida qaytariladi va ularning tartibi so‘rovlar tartibiga mos kelishi shart emas: moslashtirish uchun id ishlatiladi. Bildirishnomalarga javoblar massivga kiritilmaydi. Bo‘sh massiv yaroqli paket hisoblanmaydi; paket faqat bildirishnomalardan iborat bo‘lsa, server javob qaytarmaydi.

Xatolarni qayta ishlash

Xato yuz berganda server error obyektini qaytaradi. Unda butun sonli code kodi, satr ko‘rinishidagi message tavsifi va ixtiyoriy data maydoni orqali qo‘shimcha ma’lumotlar beriladi. JSON-RPC 2.0 spetsifikatsiyasida quyidagi standart xato kodlari belgilangan.

Kod Spetsifikatsiyadagi nomi Ma’nosi
-32700 Parse error Olingan ma’lumotlar yaroqli JSON emas
-32600 Invalid Request JSON-RPC so‘rovining tuzilishi noto‘g‘ri
-32601 Method not found So‘ralgan metod mavjud emas yoki undan foydalanib bo‘lmaydi
-32602 Invalid params Metod parametrlari noto‘g‘ri
-32603 Internal error JSON-RPC ichki xatosi
-32099 — -32000 Server error Amalga oshirilgan dastur tomonidan belgilanadigan server xatolari uchun ajratilgan kodlar oralig‘i

Kodlarning -32768 dan -32000 gacha bo‘lgan oralig‘i spetsifikatsiyada oldindan belgilangan xatolar va kelgusida foydalanish uchun zaxiralangan.

Misollar

JSON-RPC 1.0 da so‘rov va javob

Ikki sonni ayirish uchun subtract metodini chaqirish:

{"method": "subtract", "params": [42, 23], "id": 1}

Javob:

{"result": 19, "error": null, "id": 1}

JSON-RPC 2.0 da so‘rov va javob

Nomlangan parametrlar bilan ayni chaqiruv:

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": {"minuend": 42, "subtrahend": 23},
  "id": 1
}

Server javobi:

{"jsonrpc": "2.0", "result": 19, "id": 1}

Bildirishnoma

Javob talab qilinmaydigan xabar namunasi:

{"jsonrpc": "2.0", "method": "update", "params": [1, 2, 3]}

Xato

Mavjud bo‘lmagan metodni chaqirishga javob:

{
  "jsonrpc": "2.0",
  "error": {"code": -32601, "message": "Method not found"},
  "id": 7
}

Paketli chaqiruv

Ikkita so‘rov va bitta bildirishnomadan iborat paket namunasi:

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2], "id": 1},
  {"jsonrpc": "2.0", "method": "notify", "params": ["done"]},
  {"jsonrpc": "2.0", "method": "subtract", "params": [8, 3], "id": 2}
]

Natijalar tartibi so‘rovlar tartibidan farq qiladigan ehtimoliy javob:

[
  {"jsonrpc": "2.0", "result": 5, "id": 2},
  {"jsonrpc": "2.0", "result": 3, "id": 1}
]

Keltirilgan barcha misollar xabarlar formatini ko‘rsatadi; mavjud metodlar majmuasi protokolning o‘zi emas, balki muayyan xizmat tomonidan belgilanadi.

Ma’lumotlarni uzatish va xavfsizlik

JSON-RPC 2.0 spetsifikatsiyasi xabarlar formatini uzatish mexanizmidan mustaqil ravishda belgilaydi. Jumladan, JSON-RPC HTTP, WebSocket va kiritish-chiqarish oqimlari orqali xabar almashishda ishlatiladi. Ulanishni tashkil etish hamda uzatish oqimida xabarlar chegarasini ajratish usuli muayyan dasturiy amalga oshirishga bog‘liq.

JSON-RPC ning o‘zi autentifikatsiya, avtorizatsiya yoki transport ulanishini himoyalash mexanizmlarini taqdim etmaydi. Bu vazifalar ishlatilayotgan transport va ilova vositalari orqali hal qilinishi kerak.

Qo‘llanilishi

JSON-RPC, jumladan, quyidagi texnologiyalarda qo‘llaniladi:

  • Language Server Protocol (LSP) — kod muharrirlari va integratsiyalashgan dasturlash muhitlarining til serverlari bilan o‘zaro ishlash protokoli. Bunday serverlar kodni avtomatik to‘ldirish, ta’riflarni topish va boshqa imkoniyatlarni taqdim etadi.
  • Ethereum — JSON-RPC interfeysi dasturlarning tarmoq tugunlari bilan ishlashi, blokcheyn ma’lumotlarini olishi va tranzaksiyalar yuborishi uchun qo‘llaniladi.
  • Model Context Protocol (MCP) — sun’iy intellekt tizimlarida ilovalarning vositalar va ma’lumot manbalari bilan o‘zaro ishlash protokoli; u JSON-RPC 2.0 xabar formatidan foydalanadi.

Dasturiy amalga oshirishlar

JSON-RPC uchun turli dasturlash tillarida mijoz va server kutubxonalari mavjud. Ularning ayrimlari:

  • .NET — StreamJsonRpc, oqimlar, kanallar va WebSocket orqali JSON-RPC 2.0 xabarlarini almashish kutubxonasi;
  • JavaScript va TypeScript — vscode-jsonrpc, Language Server Protocol ni amalga oshirishda ishlatiladigan kutubxona;
  • Python — jsonrpcserver, JSON-RPC 2.0 so‘rovlarini qayta ishlash kutubxonasi;
  • Rust — jsonrpsee, HTTP va WebSocket ni qo‘llab-quvvatlaydigan asinxron mijoz va server kutubxonasi;
  • Go — standart kutubxonaning net/rpc/jsonrpc paketi bo‘lib, u JSON-RPC 1.0 ni amalga oshiradi, ammo 2.0 ni emas.

Havolalar