Citeck WebAPI

Citeck WebAPI — основной низкоуровневый способ общения микросервисов между собой в пределах Citeck. Общение происходит по схеме Запрос → Ответ. Клиентский API предоставляет асинхронные методы с Promise и синхронные методы, ожидающие результат.

API для работы с WebAPI описано в ecos-webapp-api (репозиторий ecos-webapp-api).

Реализация API находится в ecos-webapp-lib (репозиторий ecos-webapp-commons).

Что обеспечивает Citeck WebAPI

№

Возможность

1

Единообразная обработка ошибок executor’а до начала записи ответа: WebAPI формирует ответ со статусом ERROR и данными EcosWebException, а клиент завершает Promise с ошибкой. Ошибки после начала записи ответа, сбои транспорта и раннего разбора запроса могут не позволить передать структурированное описание ошибки.

2

Потоковый доступ к телу запроса и ответа позволяет обрабатывать большие объёмы данных без загрузки всего тела в память. Для этого доступны getInputStream(), writeStream() и getOutputStream(). Методы readAsBytes() и readAsText() читают тело целиком; метаданные при отправке также собираются в памяти. Допустимый размер сообщения зависит от ресурсов приложения и ограничений транспорта.

3

WebAPI позволяет не ломать голову над отправкой структурированных данных вместе с бинарными — в одном запросе предусмотрены обе части.

4

WebAPI абстрагирует отправителя и получателя от способа доставки сообщений. Это позволяет независимо дорабатывать возможности транспорта, не изменяя прикладной код. К вопросам транспорта относятся, например, следующие аспекты системы:

  • Шифрование. Настройка TLS не должна никак влиять на работу прикладного кода.

  • Транзакционность. Идентификатор транзакции и «прилипание» к определённым инстансам микросервисов происходит на этом уровне.

  • Локаль из текущего контекста прокидывается на принимающую сторону.

  • Часовое смещение относительно UTC из текущего контекста прокидывается на принимающую сторону.

  • Информация о клиенте (IP-адрес) прокидывается из контекста на принимающую сторону.

  • Подготовка и отправка JWT-токена для аутентификации происходит на этом уровне.

5

WebAPI позволяет независимо настраивать сжатие всего сообщения, метаданных и тела. Сжатие может уменьшить объём передаваемых данных; выигрыш во времени зависит от данных, канала связи и затрат на сжатие. По умолчанию сжатие отключено.

6

WebAPI позволяет в библиотеках реализовывать клиент-серверное общение между приложениями без добавления тяжёлых зависимостей вроде Spring MVC или различных HTTP-клиентов.

7

Версионирование API позволяет ещё до выполнения запроса узнать, поддерживается ли он на принимающей стороне, включая диапазон поддерживаемых версий. Например, если клиент умеет общаться с эндпоинтом /content/upload используя версии 0-3, а сервер поддерживает версии 0-2, клиент отправит запрос в формате максимально поддерживаемой версии (2). Этот механизм позволяет развивать продукт, не ломая совместимость по API.

8

Асинхронность на уровне API. Методы execute() и executeJ() возвращают Promise. Вызов get() ожидает завершения и блокирует текущий поток. Методы executeSync() и executeSyncJ() возвращают результат после ожидания ответа.

Пример использования со стороны клиента:

Java:

EcosWebClientApi webClient;
int apiVersion = webClient.getApiVersion("emodel", "/custom/request", 2); // 2 — максимальная версия, поддерживаемая клиентом
if (apiVersion < 0) {
    throw new IllegalStateException("WebAPI endpoint is unavailable or incompatible: " + apiVersion);
}
// Здесь должен быть код, который в зависимости от apiVersion подготовит тело запроса
String result = webClient.newRequest()
    .targetApp("emodel") // целевое приложение
    .path("/custom/request") // целевой путь (эндпоинт) запроса
    .version(apiVersion) // если предполагается поддержка только нулевой версии, то эту строчку можно опустить
    .header("custom-1", "value-1") // произвольные структурированные данные, которые можно
    .header("custom-2", "value-2") // прочитать на принимающей стороне
    .bodyJ((writer) -> { writer.writeText("request-text"); })
    .executeJ((resp) -> { return resp.getBodyReader().readAsText(); })
    .get();

Этот пример синхронно ожидает результат в get() и читает тело ответа целиком. В текущей реализации writeText() автоматически выбирает формат TEXT_UTF8, если запись тела ещё не началась. При использовании writeStream() закрывать переданный входной поток должен вызывающий код.

Пример использования со стороны сервера:

Java:

import kotlin.Pair;

class CustomExecutor implements EcosWebExecutor {

    @Override
    public void execute(@NotNull EcosWebExecutorReq req, @NotNull EcosWebExecutorResp resp) {
        int apiVer = req.getApiVersion();
        // тут может быть логика для обработки разных версий API
        String requestText = req.getBodyReader().readAsText();
        resp.setHeader("custom-header", "custom-value"); // хидеры можно использовать для любых данных
        resp.getBodyWriter().writeText(requestText + "-response");
    }
    @NotNull
    @Override
    public Pair<Integer, Integer> getApiVersion() {
        return new Pair<>(0, 2); // поддерживаются версии от 0 до 2
    }
    @NotNull
    @Override
    public String getPath() {
        return "/custom/request";
    }
    @Override
    public boolean isReadOnly() {
        return false;
    }
}
...
EcosWebExecutorsApi executorsApi;
executorsApi.register(new CustomExecutor());

Версионирование API

Микросервис публикует сведения о зарегистрированных executor’ах и диапазонах их версий через discovery-сервис. В текущей реализации сведения хранятся в ZooKeeper и доступны через кеш discovery-сервиса.

Метод getApiVersion(targetApp, path, maxVersion) использует эти сведения и возвращает максимальную совместимую версию executor’а, не превышающую maxVersion. Перед отправкой запроса необходимо обработать отрицательные результаты:

Значение

Константа EcosWebClientApi

Описание

-1

AV_APP_NOT_AVAILABLE

Приложение недоступно.

-2

AV_PATH_NOT_SUPPORTED

Путь не поддерживается приложением.

-3

AV_VERSION_NOT_SUPPORTED

Минимальная версия executor’а выше максимальной версии клиента.

Версия запроса в клиентском builder’е по умолчанию равна 0; диапазон executor’а по умолчанию — от 0 до 0. Метод version() можно опустить, если используется нулевая версия.

Версия executor’а и версия транспортного протокола Citeck WebAPI — разные значения. Транспорт поддерживает версии 0 и 1; клиент выбирает меньшую из текущей версии протокола (1) и версии, опубликованной целевым приложением.

Описание запроса и ответа

Запрос формируется по следующему паттерну:

  1. Версия транспортного протокола Citeck WebAPI (целое число);

  2. Тип сжатия всего последующего содержимого (целое число);

  3. Размер сжатых метаданных в байтах включая тип метаданных и тип сжатия (целое число);

  4. Тип метаданных (целое число);

  5. Тип сжатия метаданных (целое число);

  6. Метаданные (зависит от типа метаданных (4))

  7. Тип тела запроса (целое число)

  8. Тип сжатия тела запроса (целое число; отсутствует, если тип тела — NONE)

  9. Тело запроса (зависит от типа тела запроса (7); отсутствует при NONE)

Ответ формируется по тем же принципам, что и запрос, но без указания версии транспортного протокола (1).

Структура метаданных запроса:

Примечание

В формате CBOR-массива поля определяются по позиции. Порядок строк таблицы ниже соответствует порядку элементов массива. Типы в таблице — типы Kotlin; особенности представления в потоке указаны в описаниях.

Поле

Тип

Описание

jwt

String

JWT-токен с информацией о текущей аутентификации.

path

String

Путь для обращения к нужному executor’у.

version

Int

Версия запроса для executor’а.

headers

DataValue

Заголовки запроса (произвольные структурированные данные).

routes

Map<String, String>

Роуты, которые следует использовать для внешних запросов. Ключ — имя приложения, значение — идентификатор инстанса приложения.

tenant

String

Поле тенанта. В текущей реализации клиент передаёт пустую строку; перенос тенанта из контекста не реализован.

tzUtcOffset

Duration

Часовое смещение относительно UTC. В потоке передаётся целым числом минут.

clientData

ClientData

Информация о клиенте (IP-адрес).

txnId

TxnId

Идентификатор транзакции. В потоке передаётся строкой.

locales

List<Locale>

Список локалей. В потоке передаётся массивом языковых тегов.

micrometerScope

Map<String, String>

Данные контекста наблюдаемости Micrometer.

sourceApp

String

Источник запроса в формате appName:appInstanceId.

txnNesting

TxnNesting?

Данные вложенности транзакции: массив [parentId, depth], где идентификатор родительской транзакции передаётся строкой, глубина — целым числом. При null элемент не записывается.

Массив содержит 12 элементов без txnNesting или 13 элементов при его наличии.

Структура метаданных ответа:

Примечание

Имена полей не играют роли, если тип метаданных — массив.

Поле

Тип

Описание

headers

DataValue

Заголовки ответа (произвольные структурированные данные).

status

EcosWebRespStatus

Статус выполнения запроса. Поддерживается SUCCESS и ERROR.

routes

Map<String, String>

Роуты, которые следует использовать для внешних запросов. Ключ — имя приложения, значение — идентификатор инстанса приложения.

txnData

TxnRespData

Транзакционные данные (структура — ниже).

Структура TxnRespData:

Поле

Тип

Описание

actions

Map<TxnActionType, List<TxnActionRef>>

Транзакционные действия, сгруппированные по типу. Клиент добавляет их в текущую транзакцию; порядок исполнения определяется механизмом транзакций.

remoteTxnApps

List<String>

Устаревшее поле для совместимости: список приложений — участников транзакции. Сервер продолжает заполнять его вместе с txnApps. Если ответ содержит только это поле, клиент преобразует список в txnApps с пустыми наборами XID.

txnApps

Map<String, Set<EcosXid>>

Соответствие приложений наборам идентификаторов транзакционных ветвей (XID). Клиент регистрирует их в текущей транзакции.

Поддерживаемые типы сжатия:

ID типа сжатия

Тип сжатия

0

Без сжатия

1

ZSTD (Zstandard)

2

LZ4

LZ4 используется начиная с версии 1 транспортного протокола. Если в настройках выбран LZ4, а используется протокол версии 0, применяется режим без сжатия. Это ограничение относится к версии протокола, а не к версии executor’а.

Поддерживаемые типы метаданных:

ID типа метаданных

Тип метаданных

0

CBOR массив с данными, где имя поля определяется по порядковому индексу.

Поддерживаемые типы тела:

ID типа тела

Тип тела

0

NONE — тело отсутствует

1

BINARY - бинарные данные

2

CBOR - структурированные данные в формате CBOR

3

JSON - структурированные данные в формате JSON

4

TEXT_UTF8 - текстовые данные

Бинарное представление целого числа в Citeck WebAPI:

Если число в диапазоне от 0 до 127 включительно, то мы его записываем как есть в виде одного байта.

Если число не в диапазоне от 0 до 127, то мы первый байт формируем следующим образом (по битам):

Биты

Значение

0–2

Кодируют количество байт, в которых закодировано число. Для кодирования берётся количество байт (например, 2) и вычитается единица (получаем 1). Таким образом, 001 означает, что число закодировано двумя байтами.

3–5

Не используются.

6

Определяет знак «минус». Если равен 1, число отрицательное. Особый случай Int.MIN_VALUE описан ниже.

7

Определяет, что число не входит в диапазон от 0 до 127.

Далее на основе битов 0–2 определяется количество байт полезной части. Байты записываются от старшего к младшему (big-endian); реализация для Int допускает от 1 до 4 байт. Если бит 6 выставлен в 1, результат умножается на -1.

Особый случай — Int.MIN_VALUE (-2147483648): бит знака в заголовке не устанавливается, а полезная часть содержит четыре байта 80 00 00 00. При чтении в 32-битный накопитель они восстанавливают отрицательное значение.

Транспорт

В качестве транспорта для Citeck WebAPI на данный момент используется HTTP, но в будущем возможны и другие протоколы.

FAQ

Как связан Records API и Citeck WebAPI?

RecordsAPI использует Citeck WebAPI в качестве транспорта для общения между микросервисами.