docs: спецификация настраиваемых каналов уведомлений (Telegram/Pachca/Email)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Vladimir V Maksimov
@@ -0,0 +1,198 @@
|
||||
# Настраиваемые каналы уведомлений
|
||||
|
||||
Дата: 2026-06-14
|
||||
|
||||
## Цель
|
||||
|
||||
Сейчас `http_logger` умеет отправлять входящие HTTP-запросы только в Telegram —
|
||||
канал жёстко зашит в `main.go`. Нужно дать возможность настраивать каналы
|
||||
получения уведомлений через конфиг и добавить два новых: **Pachca (Пачка)** и
|
||||
**Email**, используя библиотеку `gitea.mediatoday.ru/mt/notify`.
|
||||
|
||||
## Решения (согласованы с пользователем)
|
||||
|
||||
1. **Путь = канал.** Первый сегмент пути URL выбирает канал: `/telegram`,
|
||||
`/pachca`, `/email`. Каждый путь шлёт ровно в свой канал. Сохраняет текущую
|
||||
логику маршрутизации.
|
||||
2. **Один экземпляр на тип.** В конфиге по одной секции на каждый тип канала.
|
||||
3. **Форматирование под каждый канал.** Извлечение данных запроса — общее,
|
||||
форматирование — на стороне канала (Telegram — markdown-блок, Email — HTML).
|
||||
4. **Канал не сконфигурирован → `404`.**
|
||||
5. Поднять модуль `notify` на актуальную версию по новому пути
|
||||
`gitea.mediatoday.ru/mt/notify` (в старой версии нет Pachca/Email).
|
||||
|
||||
## Архитектура
|
||||
|
||||
### Структура данных запроса
|
||||
|
||||
`BuildMessage` разделяется на две части: извлечение данных и форматирование.
|
||||
|
||||
```go
|
||||
// RequestData — извлечённые данные входящего запроса
|
||||
type RequestData struct {
|
||||
Time time.Time
|
||||
Method string
|
||||
Host string
|
||||
URL string
|
||||
RemoteAddr string
|
||||
Header http.Header
|
||||
Body string
|
||||
}
|
||||
|
||||
// ExtractRequest читает запрос один раз (тело с лимитом 1024 байт, как сейчас)
|
||||
func ExtractRequest(r *http.Request) RequestData
|
||||
```
|
||||
|
||||
Логика `GetRemoteAddr` и лимит тела (`> 1024` → `"too long"`) сохраняются.
|
||||
|
||||
### Интерфейс канала
|
||||
|
||||
```go
|
||||
// Notifier — канал отправки уведомлений
|
||||
type Notifier interface {
|
||||
Send(data RequestData) error
|
||||
}
|
||||
```
|
||||
|
||||
### Реализации
|
||||
|
||||
Каждая реализация сама форматирует `RequestData` в свой формат.
|
||||
|
||||
- **`telegramNotifier{bot *notify.Bot, chatID int64}`**
|
||||
Форматирует тело в ` ``` `-блок (как сейчас), отправляет `bot.SendTextMessage`
|
||||
(ParseMode Markdown).
|
||||
- **`pachcaNotifier{client *notify.Pachca, chatID int64}`**
|
||||
Форматирует в markdown ` ``` `-блок, отправляет `client.SendMessage(chatID, text)`.
|
||||
- **`emailNotifier{auth notify.SmtpAuth, from mail.Address, to []mail.Address, subject string}`**
|
||||
Форматирует тело в `<pre>…</pre>` с HTML-экранированием содержимого, отправляет
|
||||
`notify.SendEmailHTML(auth, body, subject, from, to...)`.
|
||||
|
||||
Каждая реализация выносится в отдельный файл (`telegram.go`, `pachca.go`,
|
||||
`email.go`) либо группируется в `notifiers.go` — детали на этапе плана. Цель —
|
||||
не раздувать `main.go`.
|
||||
|
||||
### Конфиг
|
||||
|
||||
Любую секцию можно опустить — тогда соответствующий путь даёт `404`.
|
||||
|
||||
```yaml
|
||||
listen_addresses:
|
||||
- ":8080"
|
||||
- "127.0.0.1:9090"
|
||||
|
||||
log_dir: "logs"
|
||||
|
||||
telegram:
|
||||
token: "*****"
|
||||
group_id: -10012345
|
||||
disable_ipv6: true # опционально, по умолчанию true
|
||||
|
||||
pachca:
|
||||
token: "*****"
|
||||
chat_id: 12345
|
||||
|
||||
email:
|
||||
smtp_addr: "smtp.example.com:587"
|
||||
username: "user@example.com"
|
||||
password: "*****"
|
||||
from: "logger@example.com"
|
||||
to:
|
||||
- "alert@example.com"
|
||||
subject: "HTTP Logger" # опционально, по умолчанию "HTTP Logger"
|
||||
```
|
||||
|
||||
Структуры Go:
|
||||
|
||||
```go
|
||||
type Config struct {
|
||||
ListenAddresses []string `yaml:"listen_addresses"`
|
||||
LogDir string `yaml:"log_dir"`
|
||||
Telegram *ConfigTelegram `yaml:"telegram"`
|
||||
Pachca *ConfigPachca `yaml:"pachca"`
|
||||
Email *ConfigEmail `yaml:"email"`
|
||||
}
|
||||
|
||||
type ConfigTelegram struct {
|
||||
Token string `yaml:"token"`
|
||||
GroupID int64 `yaml:"group_id"`
|
||||
DisableIPV6 *bool `yaml:"disable_ipv6"` // nil → true
|
||||
}
|
||||
|
||||
type ConfigPachca struct {
|
||||
Token string `yaml:"token"`
|
||||
ChatID int64 `yaml:"chat_id"`
|
||||
}
|
||||
|
||||
type ConfigEmail struct {
|
||||
SMTPAddr string `yaml:"smtp_addr"`
|
||||
Username string `yaml:"username"`
|
||||
Password string `yaml:"password"`
|
||||
From string `yaml:"from"`
|
||||
To []string `yaml:"to"`
|
||||
Subject string `yaml:"subject"` // "" → "HTTP Logger"
|
||||
}
|
||||
```
|
||||
|
||||
Замечание: исходный конфиг содержал опечатку `token:"*****"` (без пробела) и
|
||||
имя типа `ConfigTelegraam` — исправляются в рамках работы.
|
||||
|
||||
### Сборка каналов на старте
|
||||
|
||||
```go
|
||||
notifiers := map[string]Notifier{}
|
||||
```
|
||||
|
||||
- Для каждой заданной секции конфига строим соответствующий `Notifier` и кладём
|
||||
в map под ключом-именем пути (`"telegram"`, `"pachca"`, `"email"`).
|
||||
- Для email: хост для `smtp.PlainAuth` извлекается из `smtp_addr` через
|
||||
`net.SplitHostPort`; `auth = smtp.PlainAuth("", username, password, host)`.
|
||||
- Если ни одна секция не задана → `log.Fatal("не сконфигурирован ни один канал")`.
|
||||
- Ошибка инициализации конкретного канала (например, `NewTelegram`) → `log.Fatal`.
|
||||
|
||||
### Маршрутизация в хендлере
|
||||
|
||||
```go
|
||||
paths := strings.Split(r.URL.Path, "/") // "/telegram" → ["", "telegram"]
|
||||
if len(paths) < 2 { 404 }
|
||||
n, ok := notifiers[paths[1]]
|
||||
if !ok { 404 } // неизвестный или несконфигурированный канал
|
||||
data := ExtractRequest(r)
|
||||
if err := n.Send(data); err != nil {
|
||||
log.Println(err); 502 + err.Error()
|
||||
} else {
|
||||
200 + "OK"
|
||||
}
|
||||
```
|
||||
|
||||
Поведение кодов ответа (`404` / `502` / `200`) сохраняется как в текущей версии.
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
- Несконфигурированный/неизвестный путь → `404`.
|
||||
- Ошибка отправки в канал → `502` + текст ошибки в теле (как сейчас).
|
||||
- Ошибки конфигурации/инициализации каналов → `log.Fatal` на старте.
|
||||
|
||||
## Зависимости
|
||||
|
||||
- `go.mod`: заменить `git.gm6.ru/icewind/notify` на
|
||||
`gitea.mediatoday.ru/mt/notify v0.0.0-20260405185738-6f5db00fcb34`
|
||||
(доступна в module cache). Обновить `go.sum` через `go mod tidy`.
|
||||
- Новые импорты: `net/mail`, `net/smtp`, `html` (для экранирования HTML email).
|
||||
|
||||
## Тестирование
|
||||
|
||||
- `ExtractRequest` — модульный тест: корректный разбор метода/хоста/URL/заголовков,
|
||||
`GetRemoteAddr` (X-Forwarded-For → X-Real-IP → RemoteAddr), лимит тела `> 1024`.
|
||||
- Форматирование каждого канала — тест, проверяющий обёртку (` ``` `-блок для
|
||||
Telegram/Pachca, `<pre>` + экранирование для Email).
|
||||
- Маршрутизация хендлера — тест через `httptest`: неизвестный путь → `404`,
|
||||
известный канал с моком `Notifier` → `200`, ошибка `Send` → `502`. Интерфейс
|
||||
`Notifier` позволяет подменить реальные каналы моком.
|
||||
- Реальная отправка в Telegram/Pachca/Email не тестируется (внешние сервисы).
|
||||
|
||||
## Вне рамок (YAGNI)
|
||||
|
||||
- Broadcast «один запрос → все каналы».
|
||||
- Несколько экземпляров одного типа канала.
|
||||
- Именованные маршруты с произвольным набором каналов.
|
||||
- Вложения/фото (библиотека умеет, но текущая задача — текст запроса).
|
||||
Reference in New Issue
Block a user