Notifications: Difference between revisions

Latest revision as of 16:36, 17 January 2025

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

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

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

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

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

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

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

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

Цель – Определяет проект, ветку или маркер в отношении которого должно произойти событие, чтобы пользователь получил оповещение. Возможна подписка на все объекты (проекты, ветки и маркеры)
Класс события – Определяет один из трех классов события, описанных выше (кроме удаления контейнеров)
Флаг – Дополнительное условие к активации подписки. Возможны следующие значения:

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

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

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

enable – включает/исключает пользователя из механизма создания сообщений
use-mail – задает возможность получения сообщений по электронной почте
use-tg – задает возможность получения сообщений с помощью мессенджера telegram
mail – задает почтовый адрес для получения сообщений. Почтовый адрес можно задать также через редактирование параметров пользователя в веб интерфейсе 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*	Внешнее имя сервера, необходимое для формирования ссылок для работы в веб интерфейсе Svacer.
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 (см. подробнее ниже):

svacer subscription transport mail test --config mail.yaml

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

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

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

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

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

create – создание подписки
list – перечесление подписок пользователя
delete – удаление подписки
update – редактирование подписки

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

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

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

svacer subscription create [svacer_conn] [опции]

Опции:

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

При создании подписки важно указывать имена или ID одновременно во всех требуемых флагах. Например, команда:

svacer subscription create --project darpa --branch 1111-2222-333333333

не будет корректно обработана. При использовании ID цели можно не указывать родительские сущности (например, проект для ветки)

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

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

svacer subscription create --project MyProject --branch MyBranch --review

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

svacer subscription create --project MyProject --all-events

Подписаться на события COMMENT маркера 'b96f5681-d57e-448c-939e-10dc1ba04fac':

svacer subscription create --marker b96f5681-d57e-448c-939e-10dc1ba04fac --comment

Подписка на маркер возможна по его url ссылке (base64 строка после /marker в адресной строке браузера при разметке):

svacer subscription create --marker eyJtYXJrZXJJRCI6ImI0ZWYyNTFlLTJmYzUtNDhiMC1hYWU2LWM0YzIxNmUyN2IyNyIsImZpbGUiOiIvLmJ1aWxkL3N1cHBvcnQvbWtzaWduYW1lcy5jIn0=

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

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

svacer subscription list [svacer_conn] [опции]

Опции:

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

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

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

svacer subscription list --user user --password 1234

Вывести все подписки пользователя 'user' в удобном формате

svacer subscription list --user user --password 1234 --humanize

Вывести все подписки всех пользователей

svacer subscription list --user admin --password admin --all --humanize

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

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

svacer subscription delete [svacer_conn] [опции]

Опции:

all – удаление всех подписок пользователя
id – удаление конкретной подписки

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

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

svacer subscription delete --user user1 --password 1234 --id 1234

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

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

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

svacer subscription update [svacer_conn] [опции]

Опции:

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

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

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

svacer subscription update --id f1f2 --only-my-activities true

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

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

telegram
mail

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

svacer subscription transport telegram register [svacer_conn] [опции]

Опции:

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

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

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

svacer subscription transport telegram register --host svacer.host --port 9999 --user user77 --password 888 --timeout 60

Во время выполнения команды в консоль будет выведен одноразовый ключ регистрации, который необходимо использовать в Telegram-боте для завершения процесса регистрации. Для этого пользователю необходимо перейти в бот и набрать в нем команду /start <ключ>. После успешного ввода команды боту, команда register завершит свою работу, и бот будет иметь в своем распоряжении chatID, userID для взаимодействия с пользователем.

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

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

svacer subscription transport mail [опции]

Опции:

--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

svacer subscription transport mail test --config test.yaml --to admin@mail.org

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

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

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

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

svacer subscription admin service [svacer_conn] [опции]

Опции

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

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

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

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

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

svacer subscription profile [svacer_conn] [update] [опции]

Опции (актуальны для подкоманды update):

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

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

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

#!/bin/bash -x
#Общие параметры подключения к Svacer
HOST="--host 10.0.0.10 --port 8888"
#Тестовые проекты
PROJECT1="NET6"
PROJECT2="darpa"
PROJECT3="large"
PROJECT3_BRANCH1="master"
#Параметры аутентификации пользователей
USER1="--user admin_1 --password password"
USER2="--user admin_2 --password password"
USER3="--user admin_3 --password password"
USER4="--user admin_4 --password password"
USER5="--user admin_5 --password password"
USER6="--user admin_6 --password password"
USER7="--user admin_7 --password password"
#ID пользователя в Telegram
TG_USER_ID=721941843
TG_CHAT_ID=$TG_USER_ID

#Команда создания подписки
CREATE_SN="./svacer subscription create"

#User1 - подписка на все, но с флагом myactivities
$CREATE_SN $HOST $USER1 --all-events --my-activities
#User2 - подписка на проект1, только снимки
$CREATE_SN $HOST $USER2 --project $PROJECT1 --snapshot
#User2 - подписка на проект2, только разметка
$CREATE_SN $HOST $USER2 --project $PROJECT2 --review
#User2 - подписка на проект3, только комментарии
$CREATE_SN $HOST $USER2 --project $PROJECT3 --comment
#User3 - подписка на проект3, исключая ветку1, все события
$CREATE_SN $HOST $USER3 --project $PROJECT3 --all-events
$CREATE_SN $HOST $USER3 --project $PROJECT3 --branch $PROJECT3_BRANCH1 --exclude
#User4 - подписка на проект2,  все события
$CREATE_SN $HOST $USER4 --project $PROJECT2 --all-events
#User5 - подписка на проект3,  все события
$CREATE_SN $HOST $USER5 --project $PROJECT3 --all-events
#User6 - подписка на все проекты, все события
$CREATE_SN $HOST $USER6  --all-events
#User7 - подписка на все проекты, все события
$CREATE_SN $HOST $USER7  --all-events

#Команда работы с профилем
ENABLE_NTFY_MAIL="./svacer subscription profile"
#User1, включить получение сообщений по почте, по Telegram, установить адрес электронной почты для сообщений, указать ID пользователя для получения сообщений в Telegram
$ENABLE_NTFY_MAIL $HOST $USER1  update --enable true --use-mail true --mail user1@mb1lo.ru --use-tg true --tg-user-id $TG_USER_ID --tg-chat-id $TG_CHAT_ID
#User2, отключить получение всех сообщений (подписки останутся)
$ENABLE_NTFY_MAIL $HOST $USER2  update --enable false
#User3, отключить получение собщений по Telegram
$ENABLE_NTFY_MAIL $HOST $USER3  update --use-tg false
#User4, изменить параметры канала Telegram
$ENABLE_NTFY_MAIL $HOST $USER4  update --tg-user-id $TG_USER_ID --tg-chat-id $TG_CHAT_ID

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

subscription:
 enabled: true
 telegram:
  enabled: true
  botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
 mail:
  enabled: true
  smtpAddress: "relay.ispras.ru"
  smtpPort: 25
  smtpUsername: ""
  smtpPassword: ""
  smtpAuth: "noauth"
  from: "relay@ispras.ru"

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

subscription:
 enabled: true
 telegram:
  enabled: true
  botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
 mail:
  enabled: true
  smtpAddress: "mail.ispras.ru"
  smtpPort: 25
  smtpUsername: "user@ispras.ru"
  smtpPassword: "abrakadabra"
  smtpAuth: "plain"
  from: "user@ispras.ru"

В следующем примере устанавливается соединение TLS с почтовым сервером

subscription:
 enabled: true
 telegram:
  enabled: true
  botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
 mail:
  enabled: true
  smtpAddress: "mail.ispras.ru"
  smtpPort: 465
  smtpUsername: "user@ispras.ru"
  smtpPassword: "abrakadabra"
  smtpAuth: "plain"
  from: "user@ispras.ru"
  tls: true

В следующем примере устанавливается соединение TLS с помощью команды STARTTLS с почтовым сервером (в консоль будут также выведены отладочные сообщения почтового клиента)

subscription:
 enabled: true
 telegram:
  enabled: true
  botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
 mail:
  enabled: true
  smtpAddress: "mail.ispras.ru"
  smtpPort: 587
  smtpUsername: "user@ispras.ru"
  smtpPassword: "abrakadabra"
  smtpAuth: "plain"
  from: "user@ispras.ru"
  tls: false
  debug: true

При этом сервер mail.ispras.ru работает на всех портах: на 465 принимаются только TLS соединения, на 587 — обычные соединения с переходом на TLS впоследствии, на 25 — обычные соединения (без TLS)

Пример конфигурации службы с запуском ее вручную через команду cli

subscription:
 enabled: false
 telegram:
  enabled: true
  botID: "7861931704:AAEHfp035U10pJk0lIjo1lYJj1e837qv7j4"
 mail:
  enabled: true
  smtpAddress: "mail.ispras.ru"
  smtpPort: 587
  smtpUsername: "user@ispras.ru"
  smtpPassword: "abrakadabra"
  smtpAuth: "plain"
  from: "user@ispras.ru"
  tls: false

После запуска сервера Svacer можно активировать службу с помощью команды

svacer subscription admin service --user admin --password admin --enable true