Обзор

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

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

1. API для создания приложений JSONRPC

   В этом сценарии новое приложение на основе JSONRPC выбирает конкретный подкласс jsonrpc-connection, обеспечивающий транспорт для обмена сообщениями JSONRPC между конечными точками.

   Приложение создаёт объекты этого подкласса с помощью make-instance. Чтобы установить связь с удалённой конечной точкой, приложение передаёт этот объект таким функциям, как jsonrpc-notify, jsonrpc-request или jsonrpc-async-request.

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

   Функция, переданная как :request-dispatcher, отвечает за обработку запросов удалённой конечной точки, для которых требуется ответ локальной конечной точки (в данном случае — создаваемого вами приложения). Внутри этой функции можно выполнить обычный возврат или нелокальный возврат (выбросить ошибку). При любом из этих способов выхода из диспетчера запросов удалённой конечной точке отправляется ответ на её запрос через транспорт.

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

   Параметры сопутствующего объекта JSONRPC error заполняются автоматически (в случае неожиданных ошибок) или значениями, переданными в jsonrpc-error (в случае явных вызовов).

   В исключительном случае явный вызов jsonrpc-error, задающий :code равным 32000 и :data равным любому объекту JSON, означает «ошибки нет» и инициирует обычный ответ удалённой конечной точке, в котором result присваивается значение :data. Это полезно, если приложение хочет считать некоторые нелокальные выходы, например выходы по команде пользователя, допустимыми.

   Библиотеку jsonrpc можно использовать для создания приложений на основе транспортных протоколов, которые можно назвать «квази-JSONRPC». Они похожи на JSONRPC, но не полностью ему соответствуют, например DAP (протокол адаптера отладки). Эти протоколы также определяют сообщения запросов, ответов и уведомлений, но их формат несколько отличается от JSONRPC. Универсальные функции jsonrpc-convert-to-endpoint и jsonrpc-convert-from-endpoint можно настроить для преобразования между внутренним представлением JSONRPC и форматом, принимаемым конечной точкой (см. раздел Универсальные функции).

2. API для создания транспортов JSONRPC

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

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

   Чтобы пользователи могли инициировать контакты JSONRPC (уведомления или запросы) или отвечать на запросы конечных точек, новая реализация транспорта должна предоставить специализацию универсальной функции jsonrpc-connection-send для нового подкласса (см. раздел Универсальные функции). Эта универсальная функция автоматически вызывается такими примитивами, как jsonrpc-request и jsonrpc-notify. Специализация должна обеспечивать отправку сообщения, описанного в списке аргументов, посредством базового механизма связи (также называемого «каналом»), используемого новым транспортом для взаимодействия с конечными точками. Таким «каналом» может быть сетевой сокет, последовательный интерфейс, HTTP-соединение и т. д.

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

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