diff --git a/README b/README deleted file mode 100644 index 4ac0006..0000000 --- a/README +++ /dev/null @@ -1,111 +0,0 @@ -aleesa-misc-go ------------------------------------------------------------------------------------------------------------------------ -Основной роутер команд для aleesa-bot. Все протокольные плагины шлют команды сюда, а отсюда команды разлетаются в -модули-исполнители и ответ от исполнителей идёт обратно заказчику. -Работает по протоколу Redis pubsub. - - -Механика работы ------------------------------------------------------------------------------------------------------------------------ -Роутер подписан на канал misc (тот, который указан в поле channel конфига). - -Модули, реализующие "клиентские протоколы" - telegram, irc, jabber и проч, подписаны на канал своего протокола. -Входящие сообщения они получают только через этот канал. - -Модули, реализующие иную функциональность также подписаны каждый на свой канал. Кроме того, для реализации -дополнительных синхронных возможностей, они могут слушать например http запросы на отдельных - ip:портах. Но это уже -модуль-специфичная настройка. - -Формат протокола - это json с полями: -from - модуль (по сути, redis-канал), в который надо ответить -chatid - чат, из которого прилетело сообщение -userid - пользователь, на чью фразу мы отвечаем, или пользователь, для которого предназначается ответ -message - текст сообщения -plugin - первоначальный источник (по сути, redis-канал) сообщения. -mode - public или private - -misc - объект с дополнительными полями: - -misc->answer - 0 если ответ не требуется и 1 если ответ требуется (использован в модуле craniac), значение - по-умолчанию 1, если поля нет. - -misc->bot_nick - ник бота. Типа как, для разных чятов он может быть разный. (Использовано в модуле craniac.) Если - поле отсутствует, проверка на обращение к боту по нику не происходит. - -misc->csign - command sign - значок, которым предваряется команда в чятике. Исторически сложилось так, что для - разных ботов этот символ был разный, например, eggdrop использовал точку, а sulci - восклицательный - знак. По-умолчанию, aleesa-bot вездепроставляет восклицательный знак, если во входящем сообщении - такой настройки нету. Изначально настройка задаётся в конфиге чат-модуля (aleesa-telegram, - например). - -misc->fwd_cnt - количество пересылок сообщения. Значение по-умолчанию 1. Предполагается, что при пересылке - сообщения, модуль будет инкрементировать это значение и заодно проверять, что оно не превышает - настройку forwards_max в конфиге или 5, если в конфиге такой настройки нету. - -misc->good_morning - флажок признака сообщения-фразы дня, которая по идее осылается в ~8 часов по мск. Используется в - модуле phrases. - -misc->msg_format - Использовать форматирование в сообщении. На текущий момент этот флажок выставляется в модуле - telegram и благополучно проходит через модуль misc, далее попадает в модуль phrases, и, наконец, - возвращается в модуль telegram, чтобы выходное сообщение было отослано как отформатированное. - -misc->username - имя пользователя, по которому к нему надо обратиться в ответе (используется в модуле games). Для - telegram это фактически ссылка на пользователя, как правило с его firstname и lastname (или - @username, если firstname и lastname у него нету), чтобы его можно было захайлатить. - - -Как это собрать? ------------------------------------------------------------------------------------------------------------------------ -Понадобится golang версии 1.19 или более новая. - -Сам процесс сборки простой, достаточно запустить: -make - -и через некоторое время мы получаем бинарник aleesa-misc-go. Это и есть наше приложение. - - -Как это запустить? ------------------------------------------------------------------------------------------------------------------------ -Приложение тестировалось на alpine linux x86_64 3.16, но должно работать на любом (более свежем) linux-е. - -После создания data/config.json из data/config_sample.json, можно запускать приложение. - -Предполагается, что конфиг написан в формате human json (https://hjson.github.io), который допускает коментарии и -некоторые другие вольности в форматировании json-а. Конфиг ищется последовательно по следующим путям по принципу "кто -первый того и тапки": -~/.aleesa-misc-go.json -~/aleesa-misc-go.json -/etc/aleesa-misc-go.json -data/config.json - -В каталоге contrib находится скрипт для alpine linux, системы инициализации openrc. Этот скрипт достаточно положить в -/etc/init.d/aleesa-misc-go. После чего скопировать бинарник в каталог /var/lib/aleesa-misc-go, положить конфиг в одну -из дефолтных локаций (тестировалась /var/lib/aleesa-misc-go/data/config.json) и после этого сервис запускается -командой: -service aleesa-misc-go start - -В автозагрузку его можно прописать через команду: -rc-update add aleesa-misc-go default - - -Nota Bene ------------------------------------------------------------------------------------------------------------------------ -По механике, в процессе работы мы форкаем горутинки на каждое входящее сообщение, особо не контроллируя этот процесс. -Предполагается, что на этот роутер не будет большой нагрузки, даже если будет несколько ботов на входе - ограничения -телеграма и других мессенджеров не должны дать возможности развить достаточно большой message rate, чтобы об это -споткнуться. - -Формально, более удачным было бы иметь автоматический пул воркеров-горутинок и раскидывать им через channel-ы -сообщения. Внутри каждой горутинки можно было бы повиcнуть в бесконечном цикле на канале входящих сообщений и так и -работать. Но на практике оно того не стОит. - - -Nota Bene #2 ------------------------------------------------------------------------------------------------------------------------ -Go не поддерживает системный вызов fork() из-за чего демонизация программ на гошке средствами самой гошки - это в -некотором роде проблема. Решается она с помощью утилиты daemonize (https://github.com/bmc/daemonize). - -Соответствено, если для запуска этой программы предполагается использовать возможности демонизации, то можно -воспользоваться этой программой. - -В alpine linux есть средства openrc для супервайзинга foreground-сервисов. diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd86a4c --- /dev/null +++ b/README.md @@ -0,0 +1,73 @@ +# aleesa-misc-go + +Основной роутер команд для aleesa-bot. Все протокольные плагины шлют команды сюда, а отсюда команды разлетаются в +модули-исполнители и ответ от исполнителей идёт обратно заказчику. + +Работает по протоколу Redis pubsub. + +## Механика работы + +Роутер подписан на канал misc (тот, который указан в поле channel конфига). + +Модули, реализующие "клиентские протоколы" - telegram, irc, jabber и проч, подписаны на канал своего протокола. +Входящие сообщения они получают только через этот канал. + +Модули, реализующие иную функциональность также подписаны каждый на свой канал. Роутер распознаёт команду и направляет +её в канал соответствующего бэкэнд-сервиса, который уже дальше работает в соответствии со своей бизнес-логикой. + +## Как это собрать? + +Понадобится компилятор go версии 1.22 или более новый. + +Сам процесс сборки простой, достаточно запустить: + +```bash +make +``` + +и через некоторое время мы получаем бинарник **aleesa-misc-go**. Это и есть наше приложение. + +## Как это запустить? + +Приложение тестировалось на Alpine linux x86_64 3.16, но должно работать на любом (более свежем) linux-е. + +После создания **data/config.json** из **data/config_sample.json**, можно запускать приложение. + +Предполагается, что конфиг написан в формате [human json](https://hjson.github.io), который допускает коментарии и +некоторые другие вольности в форматировании json-а. Конфиг ищется последовательно по следующим путям по принципу "кто +первый того и тапки": + +``` +~/.aleesa-misc-go.json +~/aleesa-misc-go.json +/etc/aleesa-misc-go.json +data/config.json +``` + +В каталоге contrib находится скрипт для alpine linux, системы инициализации openrc. Этот скрипт достаточно положить в +**/etc/init.d/aleesa-misc-go**. После чего скопировать бинарник в каталог **/var/lib/aleesa-misc-go**, положить конфиг в +одну из дефолтных локаций (тестировалась **/var/lib/aleesa-misc-go/data/config.json**) и после этого сервис запускается +командой: + +```bash +service aleesa-misc-go start +``` + +В автозагрузку его можно прописать через команду: + +```bash +rc-update add aleesa-misc-go default +``` + +## Nota Bene #1 + +Go не поддерживает системный вызов fork() из-за чего демонизация программ на гошке средствами самой гошки - это в +некотором роде проблема. Решается она с помощью утилиты [daemonize](https://github.com/bmc/daemonize). + +Соответствено, если для запуска этой программы предполагается использовать возможности демонизации, то можно +воспользоваться этой программой. + +В alpine linux есть средства openrc для супервайзинга foreground-сервисов. + +Технически, можно было бы решить эту проблему fork()-а с помощью "github.com/sevlyar/go-daemon", но на текущий момент +она не стоит остро, поэтому решения не требуется.