JSON-RPC

JSON-RPC to protokół zdalnego wywoływania procedur wykorzystujący format JSON do przesyłania żądań i odpowiedzi.

Model komunikacji w JSON-RPC

JSON-RPC jest protokołem zdalnego wywoływania procedur, w którym komunikaty mają postać obiektów zapisanych w formacie JSON. Klient wysyła żądanie zawierające nazwę metody oraz opcjonalne parametry, a system po stronie serwera wykonuje powiązaną procedurę i zwraca wynik albo informację o błędzie. Protokół nie definiuje konkretnego języka programowania ani sposobu implementacji procedury. Ta sama metoda może więc być obsługiwana przez aplikację napisaną w innym języku niż program kliencki.

JSON-RPC nie jest samodzielnym protokołem transportowym. Komunikaty można przesyłać na przykład przez HTTP, WebSocket albo inne mechanizmy komunikacyjne, o ile aplikacja zapewnia sposób dostarczenia danych do właściwego odbiorcy. JSON odpowiada za strukturę komunikatu, natomiast transport odpowiada za jego przesłanie. Dzięki temu problemy z połączeniem, kodem HTTP lub zamknięciem sesji należy analizować osobno od błędów zapisanych w treści komunikatu JSON-RPC.

Elementy żądania i odpowiedzi w wersji 2.0

W JSON-RPC 2.0 żądanie zawiera pole jsonrpc z wartością "2.0", pole method określające nazwę procedury oraz opcjonalne pole params. Parametry mogą być przekazane jako tablica, gdy znaczenie zależy od kolejności argumentów, albo jako obiekt, gdy argumenty są identyfikowane nazwami. Pole id służy do powiązania odpowiedzi z konkretnym żądaniem. Może mieć wartość liczbową lub tekstową. W praktycznej implementacji identyfikator powinien być unikalny przynajmniej w zakresie aktywnych żądań danego klienta.

Odpowiedź zawiera pole jsonrpc, ten sam identyfikator id oraz dokładnie jedno z pól: result albo error. Pole result przechowuje dane zwrócone przez procedurę i może mieć dowolną poprawną strukturę JSON. Pole error jest obiektem zawierającym kod code, opis message oraz opcjonalne dane dodatkowe w polu data. Do standardowych kodów błędów JSON-RPC 2.0 należą między innymi -32700 dla niepoprawnego JSON, -32600 dla nieprawidłowego żądania, -32601 dla nieznanej metody oraz -32602 dla nieprawidłowych parametrów.

Możliwe jest również wysłanie powiadomienia, czyli żądania bez pola id. Odbiorca wykonuje wtedy metodę, ale nie odsyła odpowiedzi JSON-RPC. Powiadomienia nadają się do operacji, dla których klient nie potrzebuje potwierdzenia wyniku, lecz utrudniają wykrycie błędu wykonania. Wersja 2.0 dopuszcza także żądania wsadowe, w których przesyła się tablicę kilku komunikatów. Odpowiedź na taki zestaw również może być tablicą odpowiedzi, a kolejność odpowiedzi nie powinna być traktowana jako jedyny sposób dopasowania wyniku do żądania — służy do tego pole id.

Rozróżnianie błędów protokołu, aplikacji i transportu

Podczas diagnozowania komunikacji JSON-RPC trzeba ustalić, na którym poziomie występuje problem. Błąd połączenia, przekroczenie czasu oczekiwania albo odpowiedź HTTP z kodem wskazującym na niedostępność usługi dotyczy transportu lub serwera HTTP. Jeżeli treść odpowiedzi zawiera poprawny obiekt JSON-RPC z polem error, połączenie mogło działać prawidłowo, a problem wystąpił dopiero podczas walidacji żądania albo wykonywania metody.

Ważne jest sprawdzenie zgodności wersji protokołu. Komunikat JSON-RPC 2.0 powinien zawierać "jsonrpc":"2.0"; formaty nazywane JSON-RPC 1.0 i JSON-RPC 2.0 nie są automatycznie wymienne. Należy także porównać dokładną nazwę metody, typy parametrów, nazwy pól obiektu params oraz typ zwracanych danych. Błąd -32601 oznacza, że odbiorca nie rozpoznał metody, natomiast -32602 wskazuje na problem z argumentami. Nie wolno utożsamiać tych kodów z błędem składni JSON, który ma kod -32700.

Przy analizie logów przydatne jest zestawienie identyfikatora żądania z czasem wysłania, nazwą metody, rozmiarem komunikatu i otrzymaną odpowiedzią. Brak odpowiedzi przy żądaniu z identyfikatorem może wskazywać na przerwę transportową, zakończenie procesu, błąd po stronie implementacji albo nieprawidłowe traktowanie powiadomienia. Sam fakt, że dane wyglądają jak JSON, nie potwierdza jeszcze poprawności JSON-RPC. Konieczne jest sprawdzenie wymaganych pól, typów wartości oraz zasady występowania pola result albo error, lecz nie obu naraz.

JSON-RPC w diagnostyce aplikacji na komputerze

Na laptopie lub komputerze JSON-RPC może być używany przez aplikację kliencką komunikującą się z lokalnym albo zdalnym komponentem programu. Objawem problemu może być brak reakcji interfejsu, komunikat o nieudanej operacji, powtarzające się żądania w logach albo rozbieżność między identyfikatorem wysłanego żądania i odpowiedzi. Diagnostyka powinna obejmować logi aplikacji, konfigurację adresu połączenia, poprawność generowanego JSON, dostępność wybranego transportu oraz zgodność kontraktu metody po obu stronach komunikacji.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, w tym analizą problemów z oprogramowaniem oraz komunikacją aplikacji, gdy objawy występują na używanym sprzęcie. W praktyce przydatne może być odtworzenie błędu, zapisanie pełnej odpowiedzi JSON-RPC wraz z kodem błędu, sprawdzenie wersji programu i porównanie parametrów z wymaganiami dokumentacji konkretnej aplikacji. Takie dane pozwalają oddzielić usterkę komputera od błędnej konfiguracji, niezgodności wersji lub problemu występującego po stronie samej usługi.