Среда выполнения контрактов NRPC

NRPC — это типизированный слой удалённых вызовов Converged. Он превращает контракт сервиса на TypeScript в совместимые клиенты и метаданные сервиса, благодаря чему браузер, микросервис, рабочий процесс или нативная среда выполнения могут вызывать одну и ту же возможность без необходимости поддерживать отдельные строковые определения API.

Зачем это нужно

Платформа состоит из независимо развёртываемых модулей. Прямой вызов одного модуля по адресу заставил бы его вызывающие стороны зависеть от места выполнения и используемого транспорта. NRPC разделяет эти аспекты: контракт задаёт имя сервиса и его методов, а среда выполнения доставляет вызов процессу, который в данный момент владеет запрошенной целью.

Это позволяет хранить соглашение между вызывающими сторонами и реализациями в одном месте. Параметры метода, возвращаемый тип, потоковое поведение и уровень доступа известны генерации кода и доступны каждому поддерживаемому клиенту.

От контракта к вызову

Контракты — это интерфейсы TypeScript в modules/types/<domain>. Запуск
bun run gen в core/tools/nrpc анализирует эти интерфейсы и создаёт пакет
modules/generated/g-<service>. Пакет содержит метаданные контракта,
интерфейс сервера и типобезопасные фабрики клиентов для каждой среды выполнения.

Интерфейс TypeScript
        |
        v
Генератор NRPC -> пакет g-<service>
        |                    |
        |                    +-> клиент браузера
        |                    +-> клиент кластера
        |                    +-> клиент RT рабочего процесса
        v
реализация сервиса -> серверная часть обмена сообщениями

Сервис регистрирует свою реализацию с помощью createMessagingBackend. NRPC
использует сгенерированные метаданные, чтобы найти запрошенный метод,
проверяет форму вызова на границе клиента, восстанавливает типизированные
значения и вызывает соответствующий метод реализации. Метод, возвращающий
AsyncIterable, доставляется как поток; обычные методы создают один ответ.

Пути доставки

NRPC сохраняет один и тот же контракт в нескольких средах выполнения:

Клиенты браузера используют общий канал WebSocket для отправки запросов в Fujin.
Клиенты сервисов и нативные клиенты используют кластерный транспорт через Fujin; адресация выполняется к логической цели процесса, а не к адресу хоста.
Клиенты рабочих процессов используют точку входа RT, которая вызывает транспорт хоста QuickJS/Zig и остаётся синхронной для одной оценки рабочего процесса.

Fujin направляет запрос к целевому соединению. Получающий процесс выбирает
сервис и метод NRPC по метаданным запроса; Fujin не нужно понимать доменные
сервисы платформы. createHttpBackend доступен там, где требуется HTTP-грань,
и может зарегистрировать ту же реализацию сервиса в среде выполнения обмена
сообщениями, сохраняя согласованность HTTP-вызовов и внутренних вызовов.

Контекст и доступ

В конверте вызова передаются данные корреляции, крайние сроки и доверенный
контекст рабочей области или области действия. Получающий сервис выполняется с
этим контекстом, что позволяет коду хранения и авторизации использовать ту же
границу арендатора, которая была установлена на границе системы. Сервисы не
должны выводить идентификатор рабочей области из бизнес-полезной нагрузки.

Декоратор @Access объявляет класс или метод как public, user или
internal. NRPC определяет наиболее специфичный объявленный уровень и
применяет настроенные правила разрешений перед вызовом реализации. Благодаря
этому политика доступа становится частью границы сервиса, а не непоследовательным соглашением на стороне клиента.

Граница ответственности

NRPC отвечает за метаданные контрактов, сгенерированные типизированные
клиенты, сериализацию значений, диспетчеризацию вызовов и адаптеры транспорта,
используемые этими вызовами. NRPC не отвечает за бизнес-правила, обнаружение
сервисов, размещение развёртываний, сохранение доменных данных или маршрутизацию
через шину сообщений. Эти обязанности соответственно остаются за сервисом,
плоскостью управления развёртываниями, уровнем хранения и Fujin.