Обзор

Цитируя спецификацию spec, JSONRPC «независим от транспорта, так как концепции могут быть использованы в одном процессе, по сокетам, по HTTP или во многих различных средах обмена сообщениями».

Для моделирования этой независимости библиотека jsonrpc использует объекты класса jsonrpc-connection, которые представляют собой подключение к удалённому JSON-точке (подробнее о системе объектов Emacs см. EIEIO в EIEIO). Современным языком объектно-ориентированного программирования, этот класс является «абстрактным», т. е. фактический класс полезного объекта подключения всегда является подклассом jsonrpc-connection. Тем не менее, мы можем определить два различных API вокруг класса jsonrpc-connection:

1. Пользовательский интерфейс для построения приложений JSONRPC

   В этом случае приложение JSONRPC выбирает конкретный подкласс jsonrpc-connection, и приступает к созданию объектов этого подкласса с помощью make-instance. Для инициирования контакта с удалённой точкой приложения JSONRPC передаёт этот объект функциям jsonrpc-notify, jsonrpc-request, и/или jsonrpc-async-request. Для обработки удалённо инициированных контактов, которые обычно поступают асинхронно, создание экземпляра должно включать :request-dispatcher и :notification-dispatcher initargs, которые являются функциями от 3 аргументов: объект подключения; символ, обозначающий вызываемый удалённо метод JSONRPC; и объект JSONRPC params.

   Функция, переданная как :request-dispatcher, отвечает за обработку запросов удалённой точки, которые ожидают ответа от локальной точки (в этом случае — программы, которую вы создаёте). Внутри этой функции вы можете либо вернуть локально (нормальное возвращение), либо не локально (возвращение ошибки). Локальное возвращаемое значение должно быть объектом Lisp, который может быть сериализован как JSON (см. Парсинг JSON). Это определяет успешный ответ, и объект пересылается серверу как объект JSONRPC result. Нелокальное возвращение, достигаемое вызовом функции jsonrpc-error, приводит к отправке серверу ответа об ошибке. Подробности сопроводительного объекта JSONRPC error заполняются тем, что было передано в jsonrpc-error. Нелокальное возвращение, вызванное непредвиденной ошибкой любого другого типа, также вызывает отправку ответа об ошибке (если вы не установили debug-on-error, в этом случае это вызовет отладчик Lisp, см. Отладка ошибок).

2. Интерфейс наследования для создания реализаций транспорта JSONRPC

   В этом случае jsonrpc-connection подклассифицируется для реализации другой стратегии базового транспорта (подробнее о том, как подклассифицировать, см. (eieio)Наследование.). Пользователи интерфейса построения приложений могут затем создать экземпляры этого конкретного класса (с помощью функции make-instance) и подключиться к точкам JSONRPC, используя эту стратегию.

   Этот API имеет обязательные и необязательные части.

   Чтобы позволить своим пользователям инициировать контакты JSONRPC (уведомления или запросы) или отвечать на запросы точки, подкласс должен иметь реализацию метода jsonrpc-connection-send.

   Аналогично, для обработки трёх типов удалённых контактов (запросы, уведомления и ответы на локальные запросы), реализация транспорта должна организовать вызов функции jsonrpc-connection-receive после обнаружения нового сообщения JSONRPC в канале связи (каким бы «каналом» он ни был).

   Наконец, и необязательно, подкласс jsonrpc-connection должен реализовать методы jsonrpc-shutdown и jsonrpc-running-p, если эти концепции применимы к транспорту. Если это так, то все системные ресурсы (например, процессы, таймеры и т. д.), используемые для прослушивания сообщений в канале связи, должны быть освобождены в jsonrpc-shutdown, т. е. они должны потребоваться только, когда jsonrpc-running-p не равно нулю.