TypedAPI: клиент-сервер для TypeScript

Предлагаю вашему вниманию TypedAPI: библиотеку API клиента-сервера для проектов, в которых фронт и бэк написаны на TypeScript. Акцент делается на максимальной простоте использования. Суть такая: вы пишете API как обычный TypeScript класс с некоторыми ограничениями, потом автоматом из класса строится интерфейс, которым будет пользоваться клиентское приложение. Также генерируется некоторая служебная информация. Остается только настроить коннекторы (доступны HTTP и WebSocket). Валидацию, хранение подключений, и др. берет на себя TypedAPI. Есть поддержка событий.

Чтобы поиграться, есть два простеньких демонстрационных приложения: Hello, world! и Демо-чат.

Установка

TypedAPI состоит из нескольких библиотек, которые подключаются в зависимости от типа использования.

• typedapi-core: ядро, подключается клиентом и сервером
• typedapi-server: ядро сервера, подключается на сервере, включает в себя функционал HTTP сервера
• typedapi-client: ядро клиента, подключается на клиенте
• typedapi-server-ws — WebSocket сервер
• typedapi-client-browser-http — HTTP клиент
• typedapi-client-browser-ws — WebSocket клиент
• typedapi-parser — Парсер для API класса и создания интерфейса. Подключается на сервере с флагом —dev
• typedapi-redis-signaling — для проксирования событий из микросервисов во входной API

Пример, если мы хотим использовать WebSocket соединение:

# на сервере npm install --save typedapi-core typedapi-server typedapi-server-ws npm install --save-dev typedapi-parser # на клиенте npm install --save typedapi-core typedapi-client typedapi-client-browser-ws 

Для HTTP соединения:

# for server npm install --save typedapi-core typedapi-server npm install --save-dev typedapi-parser # for client npm install --save typedapi-core typedapi-client typedapi-client-browser-http 

Требования к API классу

• Все методы должны возвращать Promise
• Есть ограничения по типу данных, которые могут принимать и возвращать методы (см. ниже)
• Класс может содержать дочерние свойства-объекты, построеные по тем же правилам

Дополнительно класс может содержать свойства типа Event и ParametricEvent для реализации событий, и есть заранее определенные инъекции для авторизации и хранения базовой информации о пользователе (см. ниже).
Пример класса для «Hello, world!»:

export class Api {     async hello(name: string): Promise<string> {         return `Hello, ${name}!`     } } 

Ограничения по типам данных

Методы могут возвращать/принимать следующие типы данных:

• Скалярные: number, string, boolean, Date, undefined, null
• Array, Tuple, Enum, Union. Могут содержать только описанные здесь типы.
• Объекты-структуры без методов
• Индексированные объекты типа { [key: string | number]: SomeOtherType }

Прием/передача any, unknown запрещена.

Генерация интерфейса

Генерация интерфейса производится путем использования команды typedapi-parse из пакета typedapi-parser:

typedapi-parse [sourceFilename] [sourceObjectName] [outFilename] [reflectionOutFileName] 

где:

• sourceFilename: Путь к файлу, где хранится ваш API
• sourceObjectName: Название класса в этом файле
• outFilename: Путь к файлу, в который будет записан интерфейс для клиента
• reflectionOutFileName: Путь к файлу, который будет хранить reflections для всех методов и данных. Он используется на сервере для валидации данных

Создание соединения

После того, как вы настроили API и сегенерировали интерфейсы, можно настраивать соединение. Пример как это может выглядеть для WebSocket:

Сервер

import { WebSocketServer } from "typedapi-server-ws" import { buildMap } from "typedapi-server" // файл, сгенерированный командой typedapi-parse для сервера import { reflection } from "./apiReflection" // Ваш API класс import { Api } from "./Api" new WebSocketServer({     apiMap: buildMap(reflection, new Api),     port: 8090 }) 

Клиент

import { WebSocketTransport } from "typedapi-client-browser-ws" // файл, сгенерированный командой typedapi-parse для клиента import { createClient } from "./apiReflection" const api = createClient({ transport }) // теперь можно вызывать методы API let result = await api.hello(name) 

Настройка HTTP соединения происходит аналогичным способом, можно посмотреть в документации.

События

TypedAPI поддерживает события. При WebSocket соединении оповещение происходит обычным образом, отправкой данных через сокет. При HTTP соединении используется HTTP polling.

Пример cоздания события на сервере:

import { Event } from "typedapi-server" export class Api {     someEvent = new Event<string>() }  // отправляем событие всем продписчикам api.someEvent.fire(data) // отправляем событие одному пользователю api.someEvent.fireForUser(data, userId) // Отправляем группе пользователей api.someEvent.fireForGroup(data, groupName) // отправляем конкретной сессии api.someEvent.fireForSession(data, sessionId) // Отправялем конкретному соединению api.someEvent.fireForConnection(data, connectionId) 

Обработка на клиенте:

// Подписываемся на событие const subscription = await api.someEvent.subscribe(data => {     // обработка события }) // Отписка await subscription.unsubscribe() 

Параметрические события

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

Авторизация

Для того, чтобы реализовать авторизацию в вашем API, надо:

• Реализовать SessionProviderInterface и передать его в конструктор сервиса. По умолчанию используется MemorySessionProvider, который будет сбрасываться при каждой перезагрузке сервера.
• Реализовать методы, которые возвращают AuthDataResponse. Это специальный ответ метода, который обрабатывается по другому, нежели другие ответы.

Интерфейс AuthDataResponse выглядит так:

type AuthDataResponse = {     newAuthData: {         id?: string | number         groups?: string[]         name?: string         email?: string         phone?: string     }     // ответ, который будет отправлен пользователю     // newAuthData используется только для внутренних нужд     response: boolean } 

пример реализации API с авторизацией:

import { AuthDataResponse } from "typedapi-server"  export class ClientApi {     /**      * Проверяем логин и пароль, если подходит авторизуем     **/     async login(username: string, password: string): Promise<AuthDataResponse> {         let user = await usersRepository.login(username, password)         if(!user) {             return {                 response: false,                 newAuthData: {}             }         } else {             return {                 response: true,                 newAuthData: {                     id: user.id,                     groups: user.groups                 }             }         }     }     /**     * Logout     **/     async logout(): Promise<AuthDataResponse> {         return {             response: true,             newAuthData: {}         }     }     /**     * в apiUserID будет автоматически добавлен идентификатор пользователя.     * Если пользватель не авторизован, он получит NotAuthorizedError     **/     async getUserData(apiUserId: number): Promise<SomeUserData> {         let userData = await usersRespotory.getUserData(apiUserId)         return userData     } } 

Также помимо apiUserId можно получать и другие данные о пользователе, подробнее в документации.

Микросервисы

Для разбиения API на микросервисы используется следующая идея: на каждом микросервисе поднимается экземпляр API, и с помощью для каждого экземпляра устанавливается, какой сервис будет отвественен за обработку определенных методов. Для этого есть следующие инструменты:

• HttpProxyClient —
  Это объект проксирует вызовы методов со входного API на внутренний сервис
• HttpTrustServer —
  Этот объект принимает вызов от HttpProxyClient и вызывает запрашиваемый метод
• RedisPublisher —
  Присоединяется к API, слушает события, и перенаправляет их в Redis. Используется во внутренних сервисах.
• RedisSubscriber —
  Слушает события из Редиса, и запускает их на входном API

Архитектура может выглядеть примерно так:

Примеры кода можно найти в документации.

Заключение

Я описал ключевые особенности TypedAPI, для дополнительной информации можно почитать документацию. Я уже использую эту библиотеку в паре своих проектов, но пока она все же находится в режиме беты. Я активно ее развиваю, и надеюсь, что она будет полезна людям. Буду рад любой конструктивной критике.

Спасибо за внимание.