sayance-matrix-native-module/NATIVE_POLLING_IMPROVEMENTS.md

Native Matrix client module for Expo using Rust SDK

# Native Polling Improvements Implementation

## Overview

This document outlines the improvements made to the Matrix native module to enhance polling functionality and app lifecycle management, based on the robust implementation found in the NativePollingModule.

## Changes Made

### iOS Improvements (`ios/MatrixModule.swift`)

#### 1. **App Lifecycle Management**
- Added comprehensive app state observers to handle background/foreground transitions
- Monitors `UIApplication.didEnterBackgroundNotification`, `UIApplication.willEnterForegroundNotification`, and `UIApplication.didBecomeActiveNotification`
- Automatic polling restoration when app becomes active

#### 2. **Background Task Management**
- Robust background task handling using `UIApplication.shared.beginBackgroundTask`
- Proper cleanup of background tasks when no longer needed
- Prevents system termination during critical Matrix sync operations

#### 3. **Configuration Persistence**
- Stores polling configuration in `currentPollingConfig` for app state restoration
- Maintains polling state across app lifecycle events
- Automatic polling restart when app becomes active

#### 4. **Enhanced Logging**
- Added `OSLog` for better system-level logging and debugging
- Structured logging with categories for Console.app visibility
- Improved error tracking and performance monitoring

#### Key Methods Added:
```swift
// Background task management
private func beginBackgroundTask()
private func endBackgroundTask()

// App lifecycle handling
private func setupAppStateObservers()
@objc private func appDidEnterBackground()
@objc private func appWillEnterForeground()
@objc private func appDidBecomeActive()
```

### Android Improvements (`android/src/main/java/sayance/matrix/MatrixModule.kt`)

#### 1. **App Lifecycle Awareness**
- Integrated with `ProcessLifecycleOwner` for app-wide lifecycle monitoring
- Implements `LifecycleObserver` interface for automatic lifecycle event handling
- Tracks app background/foreground state with `isAppInBackground` flag

#### 2. **Configuration Persistence**
- Stores polling configuration in `currentPollingConfig` for state restoration
- Maintains polling state across app lifecycle transitions
- Automatic polling restart when app returns to foreground

#### 3. **Improved Background Handling**
- Better handling of background operations using Android's lifecycle-aware components
- Continues polling in background when app is backgrounded
- Proper cleanup and restoration of polling state

#### Key Methods Added:
```kotlin
// Lifecycle event handlers
@OnLifecycleEvent(Lifecycle.Event.ON_STOP)
fun onAppBackgrounded()

@OnLifecycleEvent(Lifecycle.Event.ON_START)
fun onAppForegrounded()
```

## App Configuration Requirements

### iOS Background Modes

Add the following to your `app.json`:

```json
{
  "expo": {
    "ios": {
      "backgroundModes": [
        "background-processing",
        "background-fetch"
      ],
      "infoPlist": {
        "BGTaskSchedulerPermittedIdentifiers": [
          "com.kybershield.sayance.matrix-sync"
        ]
      }
    }
  }
}
```

### Android Permissions

✅ **No additional configuration needed** - the module already includes necessary permissions:
- `android.permission.INTERNET`
- `android.permission.ACCESS_NETWORK_STATE`

## Benefits

### Enhanced Reliability
- **Automatic Recovery**: Polling automatically restarts when app becomes active
- **Background Continuity**: Polling continues in background for iOS (with system limitations)
- **State Persistence**: Configuration is maintained across app lifecycle events

### Better User Experience
- **Seamless Transitions**: No missed messages when switching between apps
- **Reduced Battery Drain**: Proper background task management prevents unnecessary processing
- **Improved Debugging**: Enhanced logging for better troubleshooting

### Robust Architecture
- **Lifecycle-Aware**: Responds appropriately to app state changes
- **Memory Efficient**: Proper cleanup of resources when not needed
- **Platform Optimized**: Uses platform-specific best practices for each OS

## Implementation Details

### Background Task Flow (iOS)
1. **App Goes to Background**: `beginBackgroundTask()` is called to request background execution time
2. **Background Processing**: Timer continues to run with system-granted background time
3. **App Returns to Foreground**: `endBackgroundTask()` is called to clean up background task
4. **State Restoration**: Polling configuration is checked and restored if needed

### Lifecycle Management (Android)
1. **App Backgrounded**: `onAppBackgrounded()` is called, `isAppInBackground` is set to true
2. **Background Processing**: Polling continues using Handler on main looper
3. **App Foregrounded**: `onAppForegrounded()` is called, polling state is checked and restored
4. **State Restoration**: Configuration is validated and polling restarted if necessary

## Testing Recommendations

### iOS Testing
1. Use Console.app to monitor OSLog messages with category "MatrixModule"
2. Test background/foreground transitions with Xcode's Debug Navigator
3. Verify background task behavior using Instruments

### Android Testing
1. Monitor logs using `adb logcat | grep MatrixModule`
2. Test app lifecycle using "Don't keep activities" in Developer Options
3. Verify background processing with Android Studio's Memory Profiler

## Migration Guide

### For Existing Apps
1. Update your `app.json` with the iOS background modes (see `recommended-app.json`)
2. No code changes required - improvements are handled internally by the module
3. Test background/foreground transitions to ensure proper behavior

### For New Apps
1. Include the iOS background modes configuration from the start
2. The module will automatically handle all lifecycle management
3. No additional setup required beyond standard Matrix client initialization

## Troubleshooting

### Common Issues

#### iOS Background Tasks Not Working
- Ensure `backgroundModes` are properly configured in `app.json`
- Check that `BGTaskSchedulerPermittedIdentifiers` includes your app's bundle identifier
- Verify background app refresh is enabled in iOS Settings

#### Android Polling Stops
- Check that the app has unrestricted battery optimization
- Ensure `ProcessLifecycleOwner` is properly initialized
- Verify that lifecycle events are being received

#### Memory Leaks
- Check that `NotificationCenter.default.removeObserver(self)` is called in deinit (iOS)
- Ensure proper cleanup of handlers and runnables (Android)
- Use memory profiling tools to identify retained objects

## Performance Considerations

### iOS
- Background tasks are limited by system policies (typically 30 seconds)
- Use background app refresh sparingly to maintain good App Store review standing
- Monitor battery usage and optimize polling intervals accordingly

### Android
- Background processing may be limited by battery optimization settings
- Consider implementing Firebase Cloud Messaging for critical notifications
- Monitor memory usage to prevent OOM conditions

## Future Enhancements

### Potential Improvements
1. **Adaptive Polling**: Adjust polling interval based on app state and network conditions
2. **Push Notifications**: Integrate with system push notifications for better background updates
3. **Sync Optimization**: Implement incremental sync to reduce data usage
4. **Battery Optimization**: Dynamic polling based on battery level and charging state

### API Enhancements
1. **Configuration Methods**: Expose polling configuration to JavaScript layer
2. **Event Filtering**: Allow filtering of specific Matrix events
3. **Metrics Collection**: Detailed polling statistics and performance metrics
4. **Connection Quality**: Network-aware polling adjustments

## Conclusion

These improvements bring the Matrix native module's polling functionality up to production-grade standards, with robust app lifecycle management, proper background task handling, and enhanced reliability. The implementation follows platform-specific best practices and provides a solid foundation for real-time Matrix communication in mobile applications.