Notification Service

Отказоустойчивый сервис уведомлений с поддержкой нескольких каналов и fallback-механизмом.

---

A fault-tolerant notification service with support for multiple channels and a fallback mechanism.

---

🇷🇺 Russian

Ключевые особенности

• Отказоустойчивость: Если один канал (например, Email) не срабатывает, сервис автоматически пытается отправить уведомление через следующий канал в цепочке (например, SMS).
• Расширяемость: Легко добавить новые каналы доставки (например, WhatsApp, Slack), реализовав простой интерфейс NotificationProvider.
• Асинхронность: Использует FastAPI и asyncio для неблокирующей обработки запросов. Отправка уведомлений происходит в фоновом режиме.
• Готовность к Production: Упакован в Docker-контейнер с использованием multi-stage builds и запускается от не-рутового пользователя.
• Конфигурация через окружение: Все настройки и секреты управляются через .env файл, следуя лучшим практикам.

Технологический стек

• Python 3.12
• FastAPI: Веб-фреймворк
• Uvicorn: ASGI-сервер
• Pydantic: Валидация данных и управление настройками
• uv: Менеджер пакетов
• Twilio: Для отправки SMS
• python-telegram-bot: Для отправки сообщений в Telegram
• Docker & Docker Compose: Контейнеризация

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

1. Требования

• Git
• Docker и Docker Compose
• Python 3.12+ и uv (для локального запуска)

2. Клонирование репозитория

git clone https://github.com/IvanFoksha/system_notifications.git
cd system_notifications

3. Настройка окружения

Все секретные ключи и настройки хранятся в файле .env.

1. Создайте копию файла-шаблона:

   cp .env.example .env

2. Откройте .env и заполните его вашими реальными данными.

   • EMAIL_*: Для Gmail вам понадобится Пароль приложения.
   • TWILIO_*: Данные можно найти в вашей консоли Twilio. Вам понадобятся Account SID, Auth Token и Messaging Service SID.
   • TELEGRAM_BOT_TOKEN: Получите токен у @BotFather в Telegram.

4. Запуск

Локальный запуск (без Docker)

# Создать виртуальное окружение и установить зависимости
make setup && source .venv/bin/activate && make install

# Запустить приложение в режиме разработки
make run

Сервис будет доступен по адресу http://127.0.0.1:8000.

Запуск через Docker (Рекомендуемый)

# Собрать образ и запустить контейнер в фоновом режиме
make docker-build && make docker-up

# Посмотреть логи
make docker-logs

# Остановить и удалить контейнер
make docker-down

Сервис будет доступен по адресу http://127.0.0.1:8000.

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

Сервис предоставляет один эндпоинт для отправки уведомлений. Документация Swagger UI доступна по адресу http://127.0.0.1:8000/docs.

POST /v1/send

Тело запроса:

{
  "recipient": "string",
  "message": "string"
}

Примеры curl запросов:

# Отправка Email
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "your.email@example.com",
  "message": "Это тестовое email-уведомление!"
}'

# Отправка SMS (номер в формате E.164)
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "+79123456789",
  "message": "Это тестовое SMS-уведомление!"
}'

# Отправка в Telegram (получатель - Chat ID)
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "123456789",
  "message": "Это тестовое уведомление в Telegram!"
}'

---

🇬🇧 English

Key Features

• Fault Tolerance: If one channel (e.g., Email) fails, the service automatically attempts to send the notification through the next channel in the chain (e.g., SMS).
• Extensibility: Easily add new delivery channels (e.g., WhatsApp, Slack) by implementing a simple NotificationProvider interface.
• Asynchronous: Uses FastAPI and asyncio for non-blocking request handling. Notifications are sent in the background.
• Production-Ready: Packaged in a Docker container using multi-stage builds and runs as a non-root user.
• Environment-based Configuration: All settings and secrets are managed via an .env file, following best practices.

Technology Stack

• Python 3.12
• FastAPI: Web framework
• Uvicorn: ASGI server
• Pydantic: Data validation and settings management
• uv: Package manager
• Twilio: For sending SMS
• python-telegram-bot: For sending Telegram messages
• Docker & Docker Compose: Containerization

Getting Started

1. Prerequisites

• Git
• Docker and Docker Compose
• Python 3.12+ and uv (for local development)

2. Clone the Repository

git clone https://github.com/IvanFoksha/system_notifications.git
cd system_notifications

3. Configure the Environment

All secret keys and settings are stored in an .env file.

1. Create a copy of the template file:

   cp .env.example .env

2. Open .env and fill it with your actual credentials.

   • EMAIL_*: For Gmail, you will need an App Password.
   • TWILIO_*: Credentials can be found in your Twilio Console. You'll need the Account SID, Auth Token, and Messaging Service SID.
   • TELEGRAM_BOT_TOKEN: Get your token from @BotFather in Telegram.

4. Running the Service

Local Development (without Docker)

# Create a virtual environment and install dependencies
make setup && source .venv/bin/activate && make install

# Run the application in development mode
make run

The service will be available at http://127.0.0.1:8000.

Using Docker (Recommended)

# Build the image and start the container in the background
make docker-build && make docker-up

# View logs
make docker-logs

# Stop and remove the container
make docker-down

The service will be available at http://127.0.0.1:8000.

API Usage

The service provides a single endpoint for sending notifications. Swagger UI documentation is available at http://127.0.0.1:8000/docs.

POST /v1/send

Request Body:

{
  "recipient": "string",
  "message": "string"
}

curl Examples:

# Send an Email
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "your.email@example.com",
  "message": "This is a test email notification!"
}'

# Send an SMS (recipient in E.164 format)
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "+15551234567",
  "message": "This is a test SMS notification!"
}'

# Send to Telegram (recipient is a Chat ID)
curl -X 'POST' \
  'http://127.0.0.1:8000/v1/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "recipient": "123456789",
  "message": "This is a test Telegram notification!"
}'