notifications Package

Overview#

Package notifications provides a unified, multi-channel notification dispatch system for the incident management platform.

This package implements a sophisticated notification delivery system that intelligently routes notifications across multiple channels including real-time WebSocket connections, push notifications, email, SMS, and Slack integrations. It supports smart routing based on user presence, priority-based channel selection, and comprehensive delivery tracking for reliable incident communication.

Multi-Channel Architecture

The notification system follows a unified dispatcher pattern with intelligent channel routing:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Incident Events │───▶│ Unified          │───▶│ Channel         │
│ (SLA, Status)   │    │ Dispatcher       │    │ Selection       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                        │
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ User Presence   │    │ Priority &       │    │ Multi-Channel   │
│ Detection       │    │ Mode Routing     │    │ Delivery        │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Notification Modes

The dispatcher supports multiple delivery modes for flexible notification strategies:

• Realtime Only: WebSocket/SSE delivery for active users with immediate feedback
• Push Only: Mobile and browser push notifications for offline users
• Hybrid: Intelligent routing based on user presence and activity status
• Redundant: Simultaneous delivery via multiple channels for critical notifications

Smart Channel Selection

The system provides intelligent channel selection based on multiple factors:

• User presence and activity status for real-time vs offline delivery
• Notification priority levels (low, medium, high, critical) with channel mapping
• User preferences and quiet hours with timezone-aware scheduling
• Delivery success tracking with automatic fallback to alternative channels
• Historical delivery patterns for optimization and reliability improvements

Integration with Incident Management

The notification system integrates deeply with incident management workflows:

• Automatic incident notifications for status changes, assignments, and escalations
• SLA breach warnings with configurable thresholds and escalation chains
• Team-based notifications with role-based filtering and targeting
• Escalation notifications with critical priority and multi-channel delivery
• Timeline integration for comprehensive notification audit trails

Usage Examples

Basic unified dispatcher setup:

// Create notification dispatcher with real-time and push services
config := &notifications.Config{
	Mode:                    notifications.ModeHybrid,
	DefaultChannels:         []notifications.NotificationChannel{
		notifications.ChannelRealtime,
		notifications.ChannelPush,
	},
	RealtimeTimeoutDuration: 5 * time.Second,
	PushFallbackDelay:       2 * time.Second,
	EnableDeliveryTracking:  true,
}

dispatcher := notifications.NewUnifiedDispatcher(
	config,
	realtimeService,
	pushService,
	presenceChecker,
)

Sending incident notifications:

// Send incident creation notification
recipients := []notifications.Recipient{
	{
		UserID:   "user-123",
		Username: "john.doe",
		Email:    "john.doe@company.com",
		Roles:    []string{"incident_responder"},
		TeamIDs:  []string{"team-backend"},
	},
}

err := dispatcher.SendIncidentNotification(ctx, incident, "incident.created", recipients)
if err != nil {
	log.Printf("Failed to send incident notification: %v", err)
}

Custom notification with priority and channels:

notification := &notifications.UnifiedNotification{
	ID:       "notify-" + uuid.New().String(),
	Type:     "maintenance_alert",
	Title:    "Scheduled Maintenance Window",
	Message:  "System maintenance starting in 30 minutes",
	Priority: notifications.PriorityHigh,
	Data: map[string]interface{}{
		"maintenance_id": "maint-456",
		"start_time":     time.Now().Add(30 * time.Minute),
	},
	Recipients: recipients,
	Channels:   []notifications.NotificationChannel{
		notifications.ChannelRealtime,
		notifications.ChannelPush,
		notifications.ChannelEmail,
	},
	CreatedAt: time.Now(),
}

err := dispatcher.SendNotification(ctx, notification)

Performance and Reliability

The notification system is designed for high-performance, reliable operation:

• Concurrent delivery to multiple recipients with goroutine-based parallelism
• Delivery result tracking with success metrics and error handling
• Configurable retry policies with exponential backoff for failed deliveries
• Circuit breaker patterns for external service integration resilience
• Comprehensive logging and metrics for operational monitoring and optimization

Privacy and Security

The system implements security best practices for notification handling:

• User consent validation before sending notifications to external channels
• Data minimization with configurable field redaction for sensitive information
• Secure token handling for external service integration (FCM, email providers)
• Audit logging for compliance and security monitoring requirements
• Rate limiting and abuse prevention for notification flooding protection

Import Path: github.com/systmms/incidents/internal/notifications

Types#

Config#

Config holds configuration for the unified notification dispatcher

{<nil> 14578 type 0 [0x14000419080] 0}

Methods#

DefaultConfig#

DefaultConfig returns a default configuration

{<nil> <nil> DefaultConfig 0x1400044ee20 <nil>}

DeliveryResult#

DeliveryResult represents the result of a notification delivery attempt

{<nil> 13859 type 0 [0x14000418600] 0}

NotificationChannel#

NotificationChannel defines available delivery channels for notification routing.

Channels represent different communication pathways to reach users with varying characteristics in terms of delivery speed, reliability, user attention, and integration complexity. The dispatcher intelligently selects channels based on notification priority, user preferences, and presence status.

{<nil> 10151 type 0 [0x1400040b740] 0}

Constants#

const ChannelRealtime const ChannelPush const ChannelEmail const ChannelSMS const ChannelSlack

NotificationMode#

NotificationMode defines comprehensive delivery strategies for the unified notification dispatcher.

These modes control how notifications are routed across different delivery channels based on user presence, priority levels, and system configuration. The modes provide flexibility for different use cases from real-time collaboration to reliable offline delivery with intelligent fallback strategies.

{<nil> 6904 type 0 [0x1400040b180] 0}

Constants#

const ModeRealtimeOnly const ModePushOnly const ModeHybrid const ModeRedundant

NotificationPriority#

NotificationPriority defines urgency levels that control delivery behavior and channel selection.

Priority levels influence channel selection, delivery timing, user interface presentation, and escalation behavior. Higher priorities may override user preferences such as quiet hours and can trigger additional delivery channels for enhanced reliability.

{<nil> 8583 type 0 [0x1400040b540] 0}

Constants#

const PriorityLow const PriorityMedium const PriorityHigh const PriorityCritical

PushPublisher#

PushPublisher interface for push notifications

{<nil> 15939 type 0 [0x1400042e700] 0}

QuietHours#

QuietHours defines when not to send certain notifications

{<nil> 13501 type 0 [0x14000418380] 0}

RealtimePublisher#

RealtimePublisher interface for real-time notifications

{<nil> 15634 type 0 [0x1400042e180] 0}

Recipient#

Recipient represents a notification recipient

{<nil> 12433 type 0 [0x1400040bdc0] 0}

RecipientSettings#

RecipientSettings defines how a user wants to receive notifications

{<nil> 12874 type 0 [0x14000418100] 0}

UnifiedDispatcher#

UnifiedDispatcher manages notification delivery across multiple channels

{<nil> 15281 type 0 [0x14000419e80] 0}

Methods#

NewUnifiedDispatcher#

NewUnifiedDispatcher creates a new unified notification dispatcher

{<nil> <nil> NewUnifiedDispatcher 0x140003f8d80 <nil>}

UnifiedNotification#

UnifiedNotification represents a notification that can be sent via multiple channels

{<nil> 11641 type 0 [0x1400040b900] 0}

UserPresenceChecker#

UserPresenceChecker interface for checking if users are active

{<nil> 14349 type 0 [0x14000418d00] 0}

Functions#

errorString#

{<nil> <nil> errorString 0x1400044e780 <nil>}

getCategoryForPriority#

{<nil> <nil> getCategoryForPriority 0x14000437a40 <nil>}

getSoundForPriority#

{<nil> <nil> getSoundForPriority 0x14000437ca0 <nil>}

Generated automatically from Go source code. Last updated: 2025-08-25T07:51:05-04:00