📬 Notification Service

📖 О проекте

Notification Service — это высокопроизводительный микросервис для централизованной отправки уведомлений через Email и Telegram, построенный на архитектуре событийно-ориентированного взаимодействия (Event-Driven) с использованием Apache Kafka.

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

✨ Функциональность

• Асинхронная обработка (Async Processing): Высокая пропускная способность благодаря получению сообщений через Kafka Consumer Group.
• Отказоустойчивость (Resilience): Встроенный механизм Retry с экспоненциальной задержкой (Exponential Backoff) для обработки временных сбоев внешних API.
• Умная маршрутизация: Динамическое определение провайдера отправки на основе полей project и channel в сообщении.
• Мульти-теннантность: Поддержка множества конфигураций SMTP и Telegram-ботов для различных проектов в рамках одного инстанса.
• Graceful Shutdown: Безопасное завершение работы без потери сообщений, находящихся в процессе обработки.
• Безопасное логирование: Автоматическое маскирование чувствительных данных (паролей, токенов) в логах приложения.

🏗️ Архитектура

Система действует как Consumer, который вычитывает события из Kafka, валидирует их и маршрутизирует соответствующему отправителю (Sender).

graph TD
    subgraph "External Ecosystem"
        S1[Service A]
        S2[Service B]
    end

    subgraph "Infrastructure"
        Kafka{{Apache Kafka}}
    end

    subgraph "Notification Service"
        Consumer[Kafka Consumer]
        Valid[Validator]
        Router{Router}
        Retry[Retry Logic]

        subgraph "Senders"
            Email[Email Sender]
            TG[Telegram Sender]
        end
    end

    S1 -->|JSON Event| Kafka
    S2 -->|JSON Event| Kafka
    Kafka --> Consumer
    Consumer --> Valid
    Valid --> Router
    Router --> Retry
    Retry --> Email
    Retry --> TG

    Email -->|SMTP| SMTP_Srv((SMTP Server))
    TG -->|HTTP| TG_API((Telegram API))

Loading

🛠️ Стек технологий

• Язык: Go (Golang) 1.24
• Брокер сообщений: Apache Kafka (github.com/segmentio/kafka-go)
• Email: gopkg.in/gomail.v2
• Конфигурация: YAML + Env variables (gopkg.in/yaml.v3)
• Контейнеризация: Docker, Docker Compose

🚀 Начало работы

Предварительные требования

• Go 1.24+ (для локальной сборки)
• Docker & Docker Compose (для запуска полного стека)
• Make (опционально)

Установка и запуск

Проект полностью контейнеризирован. Для запуска инфраструктуры выполните:

1. Клонируйте репозиторий и создайте конфиг окружения:

   git clone https://github.com/BOBAvov/notification-service.git
   cd notification-service

2. Настройте переменные окружения: Создайте файл .env в корне проекта (см. .env.example, если есть, или используйте структуру ниже):

   # SMTP Credentials
   EMAIL_PASSWORD=secret_smtp_password
   SENDGRID_API_KEY=secret_api_key
   
   # Telegram Bots
   TG_BOT_TOKEN=123456:ABC-DEF  # Основной бот
   TG_ALERTS_BOT_TOKEN=...      # Бот для алертов

3. Запустите через Docker Compose:

   docker-compose up -d --build

   Эта команда поднимет Kafka, Zookeeper, Kafka UI и сам сервис.

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

Основные настройки находятся в configs/config.yaml. Сервис поддерживает интерполяцию переменных окружения (например, ${EMAIL_PASSWORD}).

Переменная	Описание
kafka.brokers	Список адресов брокеров Kafka
kafka.topic	Топик для подписки (по умолчанию notifications)
retry.max_attempts	Максимальное к-во попыток отправки
email.senders	Настройки SMTP для разных проектов
telegram.bots	Токены ботов для разных проектов

💻 Использование

Для отправки уведомления любой сервис вашей системы должен отправить JSON-сообщение в топик Kafka (notifications).

Пример Payload (JSON)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "channel": "telegram",
  "project": "default",
  "recipient": "123456789",
  "body": "<b>Ваш заказ #42 готов!</b>",
  "metadata": {
    "order_id": "42"
  }
}

Тестирование из командной строки

Вы можете отправить тестовое сообщение, используя утилиты Kafka внутри Docker контейнера (или через make test-telegram):

Telegram уведомление:

echo '{"id":"test-1", "channel":"telegram", "project":"default", "recipient":"YOUR_CHAT_ID", "body":"Hello from Go!"}' | \
docker-compose exec -T kafka kafka-console-producer \
  --broker-list localhost:9092 \
  --topic notifications

Email уведомление:

echo '{"id":"test-2", "channel":"email", "project":"default", "recipient":"user@example.com", "subject":"Test", "body":"<h1>Hi!</h1>"}' | \
docker-compose exec -T kafka kafka-console-producer \
  --broker-list localhost:9092 \
  --topic notifications

🗺️ Планы (Roadmap)

1. Dead Letter Queue (DLQ): Реализация механизма складирования сообщений, которые не удалось доставить после всех попыток Retry, в отдельный топик Kafka для ручного разбора.
2. Метрики (Prometheus): Добавление эндпоинта /metrics для мониторинга количества отправленных сообщений, ошибок и латентности (RPS, Error Rate).
3. Шаблонизация: Внедрение движка шаблонов (Go html/template), чтобы продюсеры отправляли только данные (metadata), а сервис сам рендерил красивые HTML-письма.