Notifications

Механизм подписок на внутренние события Svacer

Общие принципы

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

• Электронная почта
• Индивидуальный чат пользователя мессенджера telegram с ботом

Существует три класса внутренний событий, на которые возможно получение оповещения:

• разметка маркера (ов), в том числе групповая (REVIEW)
• создание/редактирование и удаление комментария к маркеру (COMMENT)
• добавление/удаление снапшотов (SNAPSHOT)
• удаление контейнеров (веток, проектов)

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

• Цель
• Класс события
• Флаг
• Тип подписки

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

Класс события - Определяет один из 3 классов события, описанных выше (кроме удаления контейнеров)

Флаг - Дополнительное условие к активации подписки. Возможны следующие значения:

my-activities - подписка приведет к созданию собщения пользователю только в том случае, если в указанной цели есть какая-либо активность пользователя(разметка или комментарий), кому подписка принадлежит.

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

Пользователи могут настраивать каналы оповещения (почта или telegram) посредством изменения своего профиля подписок. Профиль подписок не включает в себя сами подписки, а позволяет контролировать только механизм доставки создаваемых подписками сообщений. Профиль имеет следующие редактируемые пользователем параметры:

• enable - Включает/Исключает пользователя из механизма создания сообщений
• use-mail - Задает возможность получения сообщений по электронной почте
• use-tg - Задает возможность получения сообщений с помощью мессенджера telegram
• mail - Задает почтовый адрес, для получения сообщений. Почтовый адрес можно задать также через редактирование параметров пользователя в GUI Svacer

Некоторые детали работы механизма подписок

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

• Обработка внутренних событий происходит 2 раза в минуту. В связи с этим возможны задержки в получении сообщении до 1 минуты. Длина очереди сообщений - 256, не поместившиеся в очередь сообщения отбрасываются с записью об ошибке в логах. Таким образом, подсистема позволяет обрабатывать до 512 сообщений в минуту
• Для каждого пользователя существует ограничение в 1 сообщение в секунду в среднем (усреднение по периодам в 30 секунд). Лишние сообщения отбрасываются с записью в логе об ошибке
• Реализована аггрегация сообщений. При использовании средств автоматизации возможно возникновение "шквала" сообщений о разметке и комментариях. В случае разметки для каждого пользователя происходит объединение сообщений имеющих один источник (проект, ветка). В этом случае отправляются менее информативные сообщения, чем в обычном случае, с указанием только снапшота, где возникли события. Для случая массового комментирования маркеров, также происходит объединение сообщений с указанием только комментария и снапшота. Аггрегатор работает 2 раза в минуту с очередью в 256 сообщений и не синхронизирован с обработчиком из пунтка 1

Для предотвращения создания большого количества соединений с почтовым сервером (при активной работе пользователей или средств автоматизации) возможно использование специального флага в конфигурации - saveConection, который позволяет переиспользовать уже созданное ранее соединение с почтовым сервером. Соединение закрывается автоматически через 10 секунд простоя.

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

Конфигурация

По умолчанию механизм подписок не активен. Для его активации необходимо подготовить секцию subscription в конфигурационном файле Svacer. Примерный конфигурационный файл указан ниже

subscription:
 enabled: true
 server: "http://svacer.local:8080"
 trace: false
 telegram:
  enabled: true
  botID: "7865.........."
 mail:
  enabled: true
  smtpAddress: "smtp.local"
  smtpPort: 25
  smtpUsername: ""
  smtpPassword: ""
  caCerts: ""
  smtpAuth: "noauth"
  from: "mailer@local"
  tls: true
  saveConnection: false
  debug: false

Описание параметров конфигурации

Название параметра	Описание
subscription.enabled	Состояние службы при старте сервера Svacer
subscription.server*	Внешнее имя сервера, необходимое для формирования ссылок для работы в GUI.
subscription.trace	Позволяет фиксировать работу службы в виде набора файлов, создаваемых во временной папке ОС (/tmp/ для ОС Linux)
telegram.enabled	Состояние канала доставки сообщений посредством мессенджера telegram при запуске сервера
telegram.botID	Идентификатор бота, который будет использован для отправки сообщений
mail.enabled	Состояние канала доставки сообщений с помощью электронной почты при запуске сервера
mail.smtpAddress	Адрес почтового сервера, который будет использован для отправки сообщений
mail.smtpPort	Параметр, задающий порт на котором работает почтовый сервер. По умолчанию используется значение - 25
mail.smtpAuth	Параметр, задающий тип аутентификации, используемой клиентом. Возможны варианты: noauth, plain, login
mail.smtpUsername (mail.smtpPassword)	Параметры, задающие учетную запись от имени которой будет происходить рассылка сообщений. В случае аутентификации noauth, должны быть указаны пустые значения
mail.caCerts	Параметр, задающий сертификаты CA. Значения поля аналогичны значениям соответствующего поля из конфигурации сервера для работы по протоколу TLS (нативный режим). Если указано пустое значение, то поддержка TLS будет сконфигурирована в небезопасном режиме с доверием любому сертификату сервера
mail.from	Поле, указывающее почтовый адрес, от имени которого будет осуществлять рассылка
mail.tls	Использовать или нет tls для соединения с сервером
mail.debug	Выводить отладочную информацию протокола взаимодействия с почтовым сервером
saveConnection	Сохранять уже установленное соединение с почтовым сервером (в течении 10 секунд после последней активности)

• Вместо параметра susbcription.server можно использовать флаг public-url при запуске svacer (см справку по cli svacer-server)

Особенности работы почтового клиента, используемого Svacer

Поддержка TLS. Если флаг mail.tls установлен, то соединение с сервером изначально будет установлено по протоколу TLS. В противном случае, изначально будет установлено обычное TCP соединение, и уже после команды STARTTLS стороны перейдут на протокол TLS. В случае если TLS соединение не сможет быть установлено, клиент будет пытаться работать без TLS соединения.

Для облегчения проверки конфигурации сервера Svacer для отправки почтовых сообщений можно использовать команду cli (см. подробнее ниже):

<source lang="bash">svacer subscription transport mail test -- config mail.yaml </source>

Команды CLI для работы с механизмом подписок

Все команды собраны в группу svacer subscription. Доступны следующие подкоманды:

• transport: Управление доступными каналами доставки сообщений (email, tg)
• profile: Управление профилем подписки подльзователя
• admin: Управление подсистемой подписок (службой)
• create: Создание новой подписки
• list: Просмотр списка подписок
• delete: Удаление подписок
• update: Обновление существующей подписки

Команды управления подписками

Для управления подписками пользователя используются следующие команды:

• create. Создание подписки
• list. Перечесление подписок пользователя
• delete. Удаление подписки
• update. Редактирование подписки

Во всех командах присутствуют флаги стандартные для CLI Svacer флаги подключения к серверу (--host, --port, --grpc, --user, --password, --ssl и другие). Группа этиъ флагов в дальнейшем будет обозначаться как [svacer_conn]

Создание подписки (команда 'create')

Общий формат команды:

<source lang="bash">svacer subscription create [svacer_conn] [Опции]</source> Опции:

• --project: Имя или ID проекта
• --branch: Имя или ID ветки
• --marker: ID маркера
• --exclude: Подписка имеет исключающий характер (по умолчанию false)
• --my-activities: Оповещение только в случае событий на маркерах, где была собственная активность (разметка, комментарий) (по умолчанию false)
• --review: Подписаться на события REVIEW
• --snapshot: Подписаться на события SNAPSHOT
• --comment: Подписаться на события COMMENT
• --all-events: Подписаться на все классы событий

При создании подписки важно указывать имена или ID одновременно во всех требуемых флагах. Например, команда: <source lang="bash">svacer subscription create --project darpa --branch 1111-2222-333333333</source> не будет корректно обработана. При использовании ID цели можно не указывать родительские сущности (например, проект для ветки).

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

Подписаться на события REVIEW в проекте "MyProject" и ветке "MyBranch":

<source lang="bash">svacer subscription create --project MyProject --branch MyBranch --review</source> Подписаться на все события в проекте "MyProject":

<source lang="bash">svacer subscription create --project MyProject --all-events</source> Подписаться на события COMMENT маркера 'b96f5681-d57e-448c-939e-10dc1ba04fac':

<source lang="bash">svacer subscription create --marker b96f5681-d57e-448c-939e-10dc1ba04fac --comment</source>

Подписка на маркер возможна по его url ссылке (base64 строка после /marker в адресной строке браузера при разметке): <source lang="bash">svacer subscription create --marker eyJtYXJrZXJJRCI6ImI0ZWYyNTFlLTJmYzUtNDhiMC1hYWU2LWM0YzIxNmUyN2IyNyIsImZpbGUiOiIvLmJ1aWxkL3N1cHBvcnQvbWtzaWduYW1lcy5jIn0=</source>

Получение списка подписок (команда list)

Общий формат команды:

<source lang="bash">svacer subscription list [svacer_conn] [Опции]</source> Опции:

• --all: Вывести все подписки всех пользователей (требуется роль admin)
• --humanize: Вывести в удобном для чтения виде

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

Вывести все подписки пользователя 'user' в формате JSON (по умолчанию):

<source lang="bash">svacer subscription list --user user --password 1234</source> Вывести все подписки пользователя 'user' в удобном формате

<source lang="bash">svacer subscription list --user user --password 1234 --humanize</source> Вывести все подписки всех пользователей

<source lang="bash">svacer subscription list --user admin --password admin --all --humanize</source>

Удаление подписки (команда delete)

Общий формат команды:

<source lang="bash">svacer subscription delete [svacer_conn] [Опции]</source> Опции:

• --all: Удаление всех подписок пользователя
• --id: Удаление конкретной подписки

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

Удалить подписку пользователя user1

<source lang="bash">svacer subscription delete --user user1 --password 1234 --id 1234</source>

Полный ID можно не указывать, достаточно указать несколько первых символов идентификатора, достаточных для однозначной идентификации подписки

Обновление подписки (команда update)

Общий формат команды:

<source lang="bash">svacer subscription update [svacer_conn] [Опции]</source> Опции:

• --id: ID подписки для обновления
• --only-my-activities: Установка флага my-activities для подписки (по умолчанию false)

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

Установить флаг my-activities для подписки, ID которой начинается с символов f1f2

<source lang="bash">svacer subscription update --id f1f2 --only-my-activities true</source>

Команды настройки и управления каналами доставки сообщений

В Svacer поддерживаются два канала доставки сообщений - электронная почта и мессенджер Telegram. Для облегчения конфигурации данных каналов используются подкоманды команды svacer subscription transport:

• telegram
• mail

Подкоманда 'telegram'

Позволяет добавить пользователю в его профиль подписки идентификаторы пользователя и чата в мессенджере Telegram (далее TG). Общий смысл данной команды заключается в том, чтобы привязать аутентификационную информацию, передаваемую пользователем на svacer сервер (через параметры SVACER_CONN), с сообщением от пользователя TG, которое получает сконфигурированный бот. Для регистрации канала TG, пользователь может использовать команду:

<source lang="bash">svacer subscription transport telegram register [svacer_conn] [Опции]</source> Опции:

• --timeout: Время ожидания завершения регистрации в секундах

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

Регистрация пользователем user77 канала получения сообщений через Telegram:

<source lang="bash">svacer subscription transport telegram register --host svacer.host --port 9999 --user user77 --password 888 --timeout 60</source> Во время выполнения команды в консоль будет выведен одноразовый ключ регистрации, который необходимо использовать в Telegram-боте для завершения процесса регистрации. Для этого пользователю необходимо перейти в бот и набрать в нем команду /start <ключ>. После успешного ввода команды боту, команда register завершит свою работу, и бот будет иметь в своем распоряжении chatID, userID для взаимодействия с пользователем.

Подкоманда 'mail'

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

<source lang="bash">svacer subscription transport mail [Опции]</source> Опции:

• --to: Почтовый адрес для отправки тестового сообщения
• --config: Секция mail конфигурационного файла в формате YAML

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

  enabled: true
  smtpAddress: "smtp.mail.local"
  smtpPort: 25
  smtpUsername: ""
  smtpPassword: ""
  smtpAuth: "noauth"
  from: "sender@mail.local"
  debug: true

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

Отправить тестовое письмо на адрес admin@mail.org, используя конфигурацию test.yaml:

<source lang="bash">svacer subscription transport mail test --config test.yaml --to admin@mail.org</source>

Группа команд администрирования службы (admin)

Данные команды требуют роль admin и предназначены для управления некоторыми параметрами самой службы. Доступные подкоманды:

• service: Управление службой подписок

Общий формат команды:

<source lang="bash">svacer subscription admin service [svacer_conn] [Опции]</source> Опции

• enable - Включение/Выключение службы
• use-mail - Включение/Выключение канала передачи сообщений через электронную почту
• use-tg - Включение/Выключение канала передачи сообщений через Telegram

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

При использовании флагов use-mail, use-tg не происходит повторное считывание конфигурационного файла. Для того, чтобы флаги use-mail и use-tg корректно применились их необходимо запускать одновременно с флагом --enable true, предварительно отключив службу с помощью флага --enable false.

Группа команд управления профилем пользователя (profile)

Команда предназначена для управление профилем пользователя и имеет следующий формат:

<source lang="bash">svacer subscription profile [svacer_conn] [update] [Опции]</source> Опции (актуальны для подкоманды update):

• use-mail - использовать канал передачи сообщений через электронную почту
• use-tg - использовать канал передачи сообщений через Telegram
• mail - изменить почтовый адрес
• tg-chat-id - установить ID чата для сообщений Telegram
• tg-user-id - установить ID пользователя для сообщений Telegram
• enable - включение/отключение механизма оповещения для конкретного пользователя

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