README-RU.md

web-soft-client

Пакет автогенерации функций для обращения к API, созданному с помощью пакета web-soft-server. Для передачи данных используется HTTP/S и WebSocket соединения. Поддерживается механизм подписки на события. Для взаимодействия с сервером используется протокол JSON-RPC 2.0.

Содержание

• Требования
• Установка
• Использование
  • Файл с объектом api
  • Файл с документацией в формате JSDoc
  • Построение и использование объекта api
    • Вызов метода
    • Подписка на событие
  • Обработка ошибок
• Классы
  • ConnectionError
    • new ConnectionError(meta[, id])
    • id
    • code
    • data
    • internal
• Функции
  • loadApi([config])
• Интерфейсы
  • ErrorMetaData
  • ApiConfig
• Список встроенных ошибок и кодов

Требования

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

Установка

npm i web-soft-client

Использование

Для быстрого старта в пакете предусмотрен простой интерфейс командной строки(cli).

Файл с объектом api

Команда api используется для генерации файла с объектом api, который затем необходимо импортировать непосредственно для вызовов методов сервера.

Принимаемые параметры:

• path: string - путь для расположения файла.

web-soft-client api --path ./src/api

Пример сгенерированного файла (может отличаться в зависиммости от версии пакета):

import { Api } from 'web-soft-client';

/**
 * @type {import('./api-types').API}
 */
export let api = {};

export const loadApi = async (config = {}) => {
  const loadedApi = new Api(config);
  await loadedApi.connect();
  await loadedApi.build();
  api = loadedApi;
};

В файл импортируется документация в формате JSDoc, которую можно сгенирировать командой описанной ниже.

В целях актуализации информации об имеющихся на сервере методах и их параметрах, построение объекта api происходит при каждой перезагрузке страницы, поэтому прежде чем вызывать функции сервера необходимо дождаться завершения выполнения асинхронной функции loadApi([config]).

Файл с документацией в формате JSDoc

Команда types используется для генерации файла с документацией к методам, доступным на сервере в момент вызова команды.

ВАЖНО: При изменении API, предоставляемого сервером, документацию необходимо обновить с помощью повторного использования команды. В противном случае отображаемая информация будет не совпадать с актуальной.

Принимаемые параметры:

• path: string - путь для расположения файла, должен совпадать с местонахождением файла с объектом api. Можно указать альтернативный путь, однако для корректной работы необходимо вручную прописать новый путь в файле с объектом api.
• port | p: number - порт, на котором работает API сервер.
• host | h: string - имя хоста, на котором работает API сервер.
• secure | s: boolean - использовать https соединение.

web-soft-client types --path ./src/api --port 80 --host localhost -s

Построение и использование объекта api

Ниже представлен простой пример использования объекта api.

'use strict';
import { api, loadApi } from './api/api';

document.addEventListener('DOMContentLoaded', async () => {
  //Подгружаем API, делать это обязательно, так как изначально api указывает на пустой объект.
  await loadApi();
  try {
    //Обычные запросы.
    const schema = await api.introspection.getModules();
    //Подписка на событие.
    api.example.subscriptionMethod({}, (error, data) => {//...//});
  } catch (error) {
    //В случае возврата ошибки сервером - она будет выброшена исключением.
    console.log(error);
  }
});

На данный момент поддерживается два типа взаимодействия с сервером:

• вызов метода
• подписка на событие

Вызов метода

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

Все параметры должны быть упаковыны в JavaScript объект. Данный объект будет использован в качестве значения поля params объекта запроса согласно спецификации JSON-RPC 2.0. Необходимый список параметров, можно получить из сгенирированной документации или из схемы API, полученной посредством вызова метода getModules() стандартного модуля Introspection.

Метод может возвращать значение, которое также может быть задокументировано.

Пример вызова метода:

const schema = await api.introspection.getModules();

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

api.auth.login({ username: 'user', password: 'password' })

Подписка на событие

Подписка на событие представляет из себя вызов метода с передачей вторым параметром функции обратного вызова.

Функция обратного вызова принимает два параметра:

• error: Error - объект ошибки, в случае если произошла ошибка.
• data: object - объект с данными передаваемыми от сервера при срабатывании события.

Пример подписки на событие:

const result = api.example.subscriptionMethod({}, (error, data) => {
  if (error && error.message === 'Connection reset.') {
    // Повторная подписка
  } else ...
});

ВАЖНО: Запросы, отправляемые с помощью HTTP/S протокола, сбрасывают текущее WebSocket соединение, для того чтобы обновить заголовки, которые могут быть установлены в рамках запроса, например cookie. В случае разрыва соединения в callback будет передана ошибка 'Connection reset.'. При возникновении подобной ошибки, можно подписаться на событие ещё раз.

ВАЖНО: По умолчанию все запросы отправляются с помощью WebSocket соединения, однако есть методы, для которых требуется именно HTTP/S запрос. В API схеме подобных методов значение поля transport установлено в 'http'.

Так как подписка на событие представляет из себя вызов метода, то в результате успешной подписки, сервер может вернуть значение. Возвращаемое значение метода отслеживается по документации или схемам API, полученной посредством вызова метода getModules() стандартного модуля Introspection.

Определить возможность подписки на событие также можно с помощью API схемы по наличию поля emit в схеме метода модуля.

Обработка ошибок

В случае, если ошибка произошла в результате вызова метода, она будет выброшена в виде исключения, и может быть поймана в блоке catch.

Если ошибка произошла во время срабатывания события, она будет передана первым параметром в функцию обратного вызова.

Все ошибки, возвращаемые сервером, а также некоторые ошибки пакета будут выбрасываться или передаваться с использованием типа ConnectionError.

Классы

ConnectionError

new ConnectionError(meta: ErrorMetaData[, id: number])

Класс расширяет стандартный тип Error.

id: number

Если ошибка произошла в результате выполнения метода на сервере, в поле помещается идентификатор запроса к серверу.

code: number

Код ошибки. Список встроенных ошибок и кодов.

data: any

В объект ошибки могут быть вложены дополнительные данные, необходимые для дальнейшего анализа этой ошибки. Тип данных может быть любым, так как не используется внутри пакета.

internal: string

Сообщение предназначенное исключительно для внутренних нужд сервера или анализа разработчиком.

Функции

async loadApi([config:ApiConfig]) : void

Функция выполняет построение и подготовку к использованию объекта api.

Интерфейсы

ErrorMetaData

Name	Type	Description
code	number	Код ошибки.
message	string	Стандартное сообщение об ошибке.
[internal]	string	Сообщение об ошибке для внутреннего использования.
[data]	any	Дополнительные данные, необходимые для дальнейшего анализа ошибки.

ApiConfig

Name	Type	Description
[host]	string	Адрес и порт сервера, к которому необходимо подключиться, если используется стандартный порт по типу 80 для HTTP и 443 для HTTPS, порт можно опустить. По умолчанию: localhost.
[secure]	boolean	Флаг отвечающий за использование безопасного соединения. По умолчанию: false.
[getModulesMethod]	string	Указывает какой метод необходимо вызывать для получения схемы API сервера. По умолчанию: introspection/getModules
[connectionResetTimeout]	number	Интервал времени, через который необходимо пытаться восстановить соединение с сервером после разрыва. По умолчанию: 1000
[serverResponseTimeout]	number	Интервал времени, который даётся серверу на ответ. По умолчанию: 5000
[onConnectionError]	function(event) : void;	Функция обратного вызова, которая будет вызвана в результате ошибки соединения.

Список встроенных ошибок и кодов

При добавление и определении иных типов ошибок необходимо свериться со спецификацией JSON-RPC 2.0.

Error	Code	Message
INTERNAL_API_ERROR	-50501	Internal client api error.
INVALID_SERVER_RESPONSE	-50600	Invalid server response.