gnr-async-notification-service

Authors: Softwell S.r.l. - Giovanni Porcari
License: MIT

Asynchronous notification dispatcher microservice supporting SMS and Push notifications across multiple platforms and providers.

Features

• 🚀 Multi-channel: SMS and Push notifications in one service
• 🔌 Multi-provider: Pluggable provider architecture (SNS, Twilio, OneSignal, etc.)
• ⚡ Async & Fast: Non-blocking operations, connection pooling
• 🔄 Never lose messages: Automatic retry, guaranteed persistence
• 📊 Centralized monitoring: Prometheus metrics
• 🛡️ Built-in rate limiting: Per-provider limits, shared across instances
• 🎛️ Priority queuing: immediate/high/medium/low with automatic ordering
• 📱 Multi-platform push: iOS (APNs), Android (FCM), Desktop (Electron)
• 📢 Broadcast support: Topic-based push for mass notifications

Architecture

The service follows the same proven architecture as gnr-async-mail-service:

• REST API (FastAPI) for control and message submission
• SQLite persistence with automatic retry and reporting
• Background loops for dispatch and client reporting
• Provider abstraction allowing easy integration of new providers

Quick Start

# Install dependencies
pip install -r requirements.txt

# Configure your provider
# Example: config.ini
[notification]
db_path = /data/notifications.db
api_token = your-secret-token

[default_account]
provider = mock
simulate_delay = 0.1

# Run the service
python main.py

Supported Providers

• Mock (built-in) - For development and testing
• AWS SNS (planned) - SMS + Push (iOS/Android)
• Twilio (planned) - SMS
• OneSignal (planned) - Push notifications

API Examples

Send SMS

curl -X POST http://localhost:8002/commands/add-notifications \
  -H "X-API-Token: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [{
      "id": "sms-001",
      "type": "sms",
      "priority": "high",
      "payload": {
        "phone": "+393331234567",
        "message": "Your OTP code is: 123456"
      }
    }]
  }'

Send Push Notification

curl -X POST http://localhost:8002/commands/add-notifications \
  -H "X-API-Token: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [{
      "id": "push-001",
      "type": "push",
      "priority": "medium",
      "payload": {
        "device_tokens": ["token1", "token2"],
        "title": "New Update!",
        "body": "Version 2.0 is available"
      }
    }]
  }'

Broadcast to Topic

curl -X POST http://localhost:8002/commands/add-notifications \
  -H "X-API-Token: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications": [{
      "id": "broadcast-001",
      "type": "push",
      "priority": "low",
      "payload": {
        "topic": "all-users",
        "title": "Maintenance Notice",
        "body": "Service will be offline tomorrow at 10:00"
      }
    }]
  }'

Configuration

The service uses an INI configuration file similar to gnr-async-mail-service.

See example_config.ini for a complete configuration example.

Development Status

• Base architecture and provider abstraction
• SQLite persistence layer
• Mock provider for testing
• Core notification logic (in progress)
• FastAPI endpoints
• Rate limiting
• Prometheus metrics
• AWS SNS provider
• Documentation
• Tests

Provider Development

To add a new provider, implement the NotificationProvider interface:

from async_notification_service.providers import NotificationProvider, NotificationResult

class MyProvider(NotificationProvider):
    @property
    def provider_name(self) -> str:
        return "myprovider"
    
    async def send_sms(self, phone: str, message: str, **kwargs) -> NotificationResult:
        # Your implementation
        pass
    
    async def send_push(self, device_tokens, topic, title, body, data, **kwargs) -> NotificationResult:
        # Your implementation
        pass
    
    # ... implement other abstract methods

License

MIT License - see LICENSE file for details