push Package

Overview#

Package push provides comprehensive push notification services for the incident management platform.

This package implements a flexible, multi-provider push notification system that delivers real-time incident alerts to mobile devices through APNS (iOS) and FCM (Android). It supports multiple delivery modes, user preferences, device management, and comprehensive notification customization for effective incident response coordination.

Key Features:

• Multi-platform push notification delivery (iOS APNS, Android FCM)
• Multiple delivery modes: direct APNS/FCM, Gorush service integration, or disabled
• Comprehensive user preference management with severity and status filtering
• Device registration and lifecycle management across platforms
• Quiet hours and do-not-disturb functionality for work-life balance
• Notification batching and rate limiting for optimal performance
• Detailed analytics and delivery tracking for operational visibility

Architecture:

The push notification system follows a provider-based architecture with unified configuration:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Incident Events │───►│ Push Notification│───►│ Mobile Devices  │
│ (Timeline)      │    │ Service          │    │ (iOS/Android)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                        │                        │
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ User            │    │ Device           │    │ Analytics       │
│ Preferences     │    │ Management       │    │ & Monitoring    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Notification Types:

• NotificationTypeIncidentCreated: New incident alerts with severity-based priority
• NotificationTypeIncidentUpdated: Status change notifications for incident tracking
• NotificationTypeIncidentEscalated: High-priority escalation alerts requiring attention
• NotificationTypeSLABreach: Critical SLA breach warnings with urgent priority
• NotificationTypeIncidentAssigned: Personal assignment notifications for responders

Delivery Modes:

• PushModeNone: Disabled mode for development or environments without mobile notifications
• PushModeLocal: Direct APNS/FCM integration for maximum control and minimal latency
• PushModeGorush: Gorush service integration for simplified deployment and management

Example usage:

// Configure push notification service
config := &push.UnifiedConfig{
	Mode: push.PushModeGorush,
	Gorush: &push.GorushConfig{
		GorushURL:    "https://gorush.example.com",
		GorushAPIKey: "your-api-key",
		RateLimit:    100,
		BatchSize:    50,
	},
	DefaultSound:   "default",
	MaxRetries:     3,
	RetryDelay:     time.Second * 5,
}

// Create push notifier with storage backend
storage := push.NewSQLStorage(db)
notifier, err := push.NewPushNotifier(ctx, config, storage)
if err != nil {
	log.Fatal(err)
}

// Register user device for notifications
err = notifier.RegisterDevice(ctx, "device-token-123", push.PlatformIOS,
	map[string]string{
		"deviceName":  "John's iPhone",
		"deviceModel": "iPhone 14 Pro",
	}, "user-123")
if err != nil {
	log.Fatal(err)
}

// Configure user notification preferences
settings := &push.PushSettings{
	UserID:     "user-123",
	Enabled:    true,
	Severities: []string{"SEV-1", "SEV-2"},
	Statuses:   []string{"open", "acknowledged", "resolved"},
	QuietHours: &push.QuietHours{
		Start: "22:00",
		End:   "08:00",
	},
}

err = notifier.UpdateSettings(ctx, "user-123", settings)
if err != nil {
	log.Fatal(err)
}

// Send incident notification
err = notifier.SendIncidentNotification(ctx, "INC-123", []string{"user-123"},
	push.NotificationTypeIncidentCreated, map[string]interface{}{
		"title":    "Database Connection Failure",
		"severity": "SEV-1",
		"service":  "database-cluster",
	})
if err != nil {
	log.Fatal(err)
}

User Preferences: The push notification system supports comprehensive user preference management:

• Global enable/disable toggle for all notifications
• Severity filtering to receive only critical or important incidents
• Status filtering to track specific incident lifecycle events
• Quiet hours configuration to respect work-life balance
• Device-specific preferences and notification routing

Device Management: Comprehensive device lifecycle management including:

• Multi-device registration per user across iOS and Android platforms
• Device token validation and refresh handling
• Automatic cleanup of expired or invalid device tokens
• Device naming and metadata for user-friendly management
• Platform-specific configuration and capability detection

Analytics and Monitoring: The push notification system provides detailed operational visibility:

• Delivery success and failure rates with platform-specific metrics
• User engagement tracking and notification effectiveness analysis
• Performance monitoring with delivery latency and throughput metrics
• Error tracking and debugging information for troubleshooting
• Cost optimization insights for efficient notification delivery

Security and Privacy: All push notifications include comprehensive security measures:

• Device token encryption and secure storage
• User preference privacy and data protection
• Notification content filtering to prevent sensitive data exposure
• Platform-specific security best practices (APNS certificates, FCM keys)
• Audit logging for compliance and security monitoring

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

Types#

AnalyticsEvent#

Analytics integration

{<nil> 14589 type 0 [0x1400031af40] 0}

BatchQueue#

BatchQueue for efficient bulk sending

{<nil> 11125 type 0 [0x140002f9000] 0}

Methods#

NewBatchQueue#

NewBatchQueue creates a new batch queue

{<nil> <nil> NewBatchQueue 0x14000452fc0 <nil>}

Config#

Enhanced configuration

{<nil> 7298 type 0 [0x140002c9780] 0}

DashboardData#

Dashboard data for UI

{<nil> 76648 type 0 [0x140007090c0] 0}

DeviceToken#

DeviceToken represents a registered mobile device with comprehensive metadata for push notifications.

This structure contains all necessary information for delivering push notifications to specific devices, including platform identification, user association, and device management metadata for lifecycle tracking and user experience optimization.

Device Lifecycle: DeviceToken instances track the complete lifecycle of device registrations:

• Registration: Initial device token storage with platform and user association
• Updates: Token refresh handling for platform-specific token rotation
• Usage Tracking: Last activity monitoring for cleanup and analytics
• Cleanup: Automatic removal of expired or invalid device tokens

Security and Privacy: Device tokens are handled with appropriate security measures:

• Secure token storage with encryption at rest
• User association validation and authorization checks
• Token validation and expiration handling
• Privacy-compliant device information storage

{<nil> 38403 type 0 [0x14000471940] 0}

GorushClient#

GorushClient wraps Gorush API for push notifications

{<nil> 147 type 0 [0x14000273d00] 0}

Methods#

NewGorushClient#

NewGorushClient creates a new Gorush client

{<nil> <nil> NewGorushClient 0x140002684e0 <nil>}

GorushConfig#

GorushConfig holds configuration for Gorush mode (reuses existing Config)

{<nil> 51516 type 0 [0x14000335e80] 0}

GorushNotification#

GorushNotification represents a Gorush API notification

{<nil> 596 type 0 [0x1400017e280] 0}

HealthChecker#

HealthChecker monitors Gorush instances health

{<nil> 68938 type 0 [0x1400023b600] 0}

HealthStatus#

{<nil> 69058 type 0 [0x1400023b780] 0}

HybridPushService#

HybridPushService combines our domain logic with Gorush’s infrastructure

{<nil> 6179 type 0 [0x140002c8f80] 0}

Methods#

NewHybridPushService#

NewHybridPushService creates a service that uses Gorush for delivery

{<nil> <nil> NewHybridPushService 0x140002cb7c0 <nil>}

LocalPushConfig#

LocalPushConfig holds configuration for direct APNS/FCM

{<nil> 51041 type 0 [0x14000335c40] 0}

LocalPushService#

LocalPushService implements PushNotifier with direct APNS/FCM

{<nil> 54510 type 0 [0x1400039e780] 0}

Methods#

NewLocalPushService#

NewLocalPushService creates a new local push service

{<nil> <nil> NewLocalPushService 0x1400023cb80 <nil>}

MetricsStore#

MetricsStore for tracking notification performance

{<nil> 13869 type 0 [0x1400031a7c0] 0}

Methods#

NewMetricsStore#

{<nil> <nil> NewMetricsStore 0x14000319de0 <nil>}

MonitoringService#

MonitoringService provides observability for push notifications

{<nil> 68732 type 0 [0x1400023b100] 0}

Methods#

NewMonitoringService#

NewMonitoringService creates a monitoring service

{<nil> <nil> NewMonitoringService 0x1400070aca0 <nil>}

NoPushService#

NoPushService implements PushNotifier with no-op behavior

{<nil> 79269 type 0 [0x1400078bc80] 0}

Methods#

NewNoPushService#

NewNoPushService creates a new no-push service

{<nil> <nil> NewNoPushService 0x1400024ef20 <nil>}

Notification#

Notification represents a push notification

{<nil> 39965 type 0 [0x14000471ec0] 0}

NotificationMetrics#

{<nil> 13962 type 0 [0x1400031a8c0] 0}

NotificationType#

NotificationType defines the categories of push notifications for incident management.

These notification types enable targeted delivery of incident-related information with appropriate priority levels, formatting, and user experience optimization for different stages of the incident response lifecycle.

{<nil> 35556 type 0 [0x14000471680] 0}

Constants#

const NotificationTypeIncidentCreated const NotificationTypeIncidentUpdated const NotificationTypeIncidentEscalated const NotificationTypeSLABreach const NotificationTypeIncidentAssigned

Platform#

Platform represents the mobile device platform for push notification delivery.

The platform identifier determines the appropriate push notification service (APNS for iOS, FCM for Android) and enables platform-specific formatting, capabilities, and delivery optimization.

{<nil> 37051 type 0 [0x14000471840] 0}

Constants#

const PlatformIOS const PlatformAndroid

Priority#

Priority levels for notifications

{<nil> 8688 type 0 [0x140002f8140] 0}

Constants#

const PriorityImmediate const PriorityHigh const PriorityNormal const PriorityLow

PrometheusExporter#

PrometheusExporter exports metrics in Prometheus format

{<nil> 73871 type 0 [0x140002b3200] 0}

Methods#

NewPrometheusExporter#

{<nil> <nil> NewPrometheusExporter 0x140000b1c00 <nil>}

PushMode#

PushMode defines the supported push notification modes

{<nil> 50304 type 0 [0x14000335900] 0}

Constants#

const PushModeNone const PushModeLocal const PushModeGorush

PushNotifier#

PushNotifier is the unified interface for all push notification implementations across delivery modes.

This interface provides a comprehensive abstraction over different push notification delivery mechanisms (direct APNS/FCM, Gorush service, or disabled mode), enabling consistent notification delivery regardless of the underlying infrastructure. It supports the complete notification lifecycle from device registration through preference management to message delivery.

Core Capabilities:

• Multi-platform push notification delivery with platform-specific optimization
• User-centric notification targeting with preference filtering and routing
• Device lifecycle management including registration, updates, and cleanup
• Comprehensive user preference management with fine-grained control
• Incident-specific notification formatting with severity and context awareness
• Analytics and delivery tracking for operational monitoring and optimization

Implementation Modes: The interface supports multiple implementation modes:

• LocalPushService: Direct APNS/FCM integration for maximum control
• HybridPushService: Gorush service integration for simplified deployment
• NoPushService: Disabled mode for development and testing environments

The interface design ensures consistent behavior across all modes while allowing mode-specific optimizations and capabilities.

Concurrency Safety: All interface methods are designed to be safe for concurrent use across multiple goroutines, enabling high-throughput notification processing without synchronization concerns at the caller level.

Error Handling: Interface methods provide comprehensive error information including:

• Delivery failures with platform-specific error details
• Configuration validation errors with corrective guidance
• Rate limiting and quota exhaustion with backoff recommendations
• Device registration issues with token validation context

{<nil> 42905 type 0 [0x14000334e00] 0}

Methods#

NewPushNotifier#

NewPushNotifier creates the appropriate push notification service based on configuration mode.

This factory function provides a unified entry point for creating push notification services across different deployment modes and infrastructure configurations. It handles service initialization, configuration validation, and mode-specific setup while providing a consistent PushNotifier interface regardless of the underlying implementation.

Supported Modes:

• PushModeNone: Returns NoPushService for development or disabled environments
• PushModeLocal: Returns LocalPushService with direct APNS/FCM integration
• PushModeGorush: Returns HybridPushService with Gorush service integration

Parameters:

• ctx: Context for service initialization and configuration validation
• config: Unified configuration specifying mode and mode-specific settings
• storage: Storage backend for device tokens, user preferences, and analytics

Configuration Validation: The factory performs comprehensive configuration validation:

• Mode-specific configuration presence verification
• Required credential and endpoint validation
• Storage backend compatibility checking
• Performance parameter validation and optimization

Service Initialization: Each mode undergoes appropriate initialization:

• NoPush: Immediate return with no-op implementation
• Local: APNS/FCM credential validation and connection testing
• Gorush: Service endpoint validation and API key verification

Error Handling: The factory provides detailed error context for:

• Missing or invalid mode-specific configuration
• Credential validation failures with corrective guidance
• Storage backend connection or compatibility issues
• Service initialization failures with debugging information

Returns a fully initialized PushNotifier implementation or an error if configuration validation or service initialization fails.

{<nil> <nil> NewPushNotifier 0x14000386d40 <nil>}

PushSettings#

PushSettings represents user push notification preferences

{<nil> 39415 type 0 [0x14000471bc0] 0}

QueuedNotification#

{<nil> 11272 type 0 [0x140002f91c0] 0}

QuietHours#

QuietHours defines when not to send notifications

{<nil> 39794 type 0 [0x14000471dc0] 0}

RateLimiter#

RateLimiter for controlling notification rate

{<nil> 13174 type 0 [0x1400031a080] 0}

Methods#

NewRateLimiter#

{<nil> <nil> NewRateLimiter 0x14000319740 <nil>}

RetryManager#

Enhanced retry manager with exponential backoff

{<nil> 15913 type 0 [0x1400031b780] 0}

Methods#

NewRetryManager#

{<nil> <nil> NewRetryManager 0x1400031d2a0 <nil>}

SQLiteStorage#

SQLiteStorage implements Storage interface using SQLite

{<nil> 81611 type 0 [0x140001e2000] 0}

Methods#

NewSQLiteStorage#

NewSQLiteStorage creates a new SQLite storage instance

{<nil> <nil> NewSQLiteStorage 0x14000258bc0 <nil>}

Storage#

Storage interface for device tokens and settings

{<nil> 40413 type 0 [0x14000334640] 0}

UnifiedConfig#

UnifiedConfig holds configuration for all push modes

{<nil> 50567 type 0 [0x14000335a00] 0}

Functions#

getPlatformInt#

getPlatformInt converts platform to Gorush platform code

{<nil> <nil> getPlatformInt 0x14000403b20 <nil>}

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