Перейти к содержанию

Вебсокеты

Описание

В приложение добавлены механизмы нотификации об изменениях через websocket.

WS-сервер работает в режиме read-only, т.е. только для получения нотификаций, изменение состояния через websocket невозможно.

Подключение: 

  URL для соединения:   
  ws://<controller_ip>/ws/?token=<jwt token>

   Пример URL для соединения:
   ws://<controller_ip>/ws/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJlbWFpbCI6ImFkbWluQGxvY2FsaG9zdCIsInVzZXJuYW1lIjoiYWRtaW4iLCJleHAiOjE1MTY3MDM3OTl9.daJM1j3bmV6fZ7plq_jYGayIsy9KyZo3gM7pcYteNuw

Возможные ошибки подключения: "jwt token must be send as query param" - проверьте, что передан jwt токен и формат URL правильный.

Структура

Типы сообщений сервера: От ws-сервера может быть получено два типа сообщений: data и control. Сообщения имеют разную структуру.

Структура control сообщения: 

{
  "resource": "/domains/", // ресурс, к которому имеет отношение это сообщение
  "close": false, // если close true, то соединение, через которое получено такое сообщение не может быть больше использовано клиентом, сервер закрывает соединение.
  "error": false, // является ли сообщение ошибкой
  "msg_type": "control", // тип сообщения, может быть data или control
  "msg": "add" // текст сообщения
}

Структура data сообщения: 

{
  "resource": "/domains/", // ресурс к которому имеет отношение это сообщение
  "event": "UPDATED", // тип изменения ресурса, может быть CREATED, UPDATED, DELETED
  "msg_type": "data", // тип сообщения, может быть data или control
  "id": "252abe60-d266-4d3c-9f00-4d6d1e14b77f", // id ресурса, например задачи или домена
  "object": { ... } // сериализованный ресурс, набор полей соответствует GET запросу на данный тип ресурса, сообщения с типом "event": "DELETED" всегда содержат {} в поле object
}

Управление подпиской

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

Добавить list подписку: 

add /domains/

Ответ: 

{
  "resource": "/domains/",
  "close": false,
  "error": false,
  "msg_type": "control",
  "msg": "add"
}

list нотификация: 

{
  "resource": "/domains/",
  "event": "UPDATED",
  "msg_type": "data",
  "id": "252abe60-d266-4d3c-9f00-4d6d1e14b77f",
  "object": { ... }
}

Добавить entity подписку: 

add /domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/

Ответ: 

{
  "resource": "/domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/",
  "close": false,
  "error": false,
  "msg_type": "control",
  "msg": "add"
}

entity нотификация: 

{
  "resource": "/domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/",
  "event": "UPDATED",
  "msg_type": "data",
  "id": "252abe60-d266-4d3c-9f00-4d6d1e14b77f",
  "object": { ... }
}

Типы подписок

Подписки на list и entity абсолютно независимы. В рамках одного соединения может быть оформлена подписка на /domains/ и /domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/, тогда при изменении состояния домена с id 252abe60-d266-4d3c-9f00-4d6d1e14b77f будет получена как list, так и entity нотификация.

Удаление подписки

Удалить list подписку: 

delete /domains/

Ответ: 

{
  "resource": "/domains/",
  "close": false,
  "error": false,
  "msg_type": "control",
  "msg": "delete"
}

Удалить entity подписку: 

delete /domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/

Ответ: 

{
  "resource": "/domains/252abe60-d266-4d3c-9f00-4d6d1e14b77f/",
  "close": false,
  "error": false,
  "msg_type": "control",
  "msg": "delete"
}

Ошибки

Ошибка подписки 1: 

{
  "resource": "add foo/bar",
  "close": false,
  "error": true,
  "msg_type": "control",
  "msg": "bad request format"
}

Ошибка подписки 2: 

{
  "resource": "/domains/",
  "close": false,
  "error": true,
  "msg_type": "control",
  "msg": "bad permissions"
}

Ошибки токена: Любая ошибка валидации токена приведет к закрытию ws-соединения со стороны сервера.

{
  "resource": "",
  "close": true, // любая ошибка токена приведет к закрытию соединения сервером
  "error": true,
  "msg_type": "control",
  "msg": "token error: Error decoding signature." // или другое сообщение в формате token error: ...
}

Ограничения

На текущий момент в сервисе явно заданы следующие ограничения:

MAX_CONNECTIONS_PER_USER = 50 - максимальное число ws-соединений под учетной записью одного пользователя.

MAX_ID_SUBSCRIPTION_COUNT = 500 - максимальное число entity подписок на одно соединение.

Проверка статуса сервера через ws-соединение

  1. Клинт отправляет текстовое сообщение "ping". Если сервер и сеть работают в штатном режиме, то клиент получит ответ "pong".
  2. Сервер сам отправляет сообщение с периодом в 90с подключенным клиентам. Данный тип проверки связи по-умолчанию выключен. Настройка WEBSOCKETS_HEARTBIT. Пример сообщения:
{
"resource": "",
"close": false,
"error": false,
"msg_type": "ping",
"msg": "ping"
}