Notifications: Difference between revisions

From Svacer Wiki
VisualWikitext
m (minor fixes)
mNo edit summary
 
(2 intermediate revisions by 2 users not shown)
Line 22: Line 22:
* Тип подписки
* Тип подписки


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

Latest revision as of 16:18, 16 May 2025

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

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

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

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

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

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

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

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

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

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

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

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

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

Механизм подписок может удерживать некоторые сообщения, накапливая их в очереди, для минимизации числа соединений с сервером (почтовым или telegram). Отправка сообщений происходит 1 раз в 30 секунд, в связи с чем могут быть задержки с получением сообщений.

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

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

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

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

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

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

subscription:
 enabled: true
 trace: false
 advanced: 
  transport_queue_len: 256
  transport_worker_period: 30
  trace_dir: /tmp
 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.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 секунд после последней активности)
advanced.transport_queue_len Значение по умолчанию — 256. Определяет максимальный размер буфера накапливаемых сообщений. Если буфер полный, новые сообщения будут игнорироваться (о чем будет сообщение в логах сервера)
advanced.transport_worker_period Значение по умолчанию — 30. Определяет период срабатывания очереди сообщения в секундах
advanced.trace_dir Значение по умолчанию определяется типом системы (Для Linux — /tmp). Позволяет указать папку, в которой будут размещаться отладочные файлы работы службы оповещений
Для работы службы необходимо запускать Svacer с опцией public-url. Без указания этой опции служба не будет активирована, так как создаваемые в процессе ее работы ссылки должны содержать правильные URL

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

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

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

svacer subscription transport mail test --config mail.yaml

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

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

  • transport – функции по работе (конфигурации) используемых механизмов доставки сообщений (mail, 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 – подписаться на все классы событий

Note  При создании подписки важно указывать имена или 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':

Получение списка подписок (команда 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

  • mail

Подкоманда '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: "mail-server.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
Retrieved from "https://svacer.ispras.ru/mediawiki/index.php?title=Notifications&oldid=2927"