daily-notification-plugin/ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift

//
//  DailyNotificationBackgroundTaskTestHarness.swift
//  DailyNotificationPlugin
//
//  Test harness for BGTaskScheduler prefetch functionality
//  Reference implementation demonstrating task registration, scheduling, and handling
//
//  See: doc/test-app-ios/IOS_PREFETCH_TESTING.md for testing procedures
//

import Foundation
import BackgroundTasks
import UIKit
import os.log

/// Minimal BGTaskScheduler test harness for DailyNotificationPlugin prefetch testing
///
/// This is a reference implementation demonstrating:
/// - Task registration
/// - Task scheduling
/// - Task handler implementation
/// - Expiration handling
/// - Completion reporting
///
/// **Usage:**
/// - Reference this when implementing actual prefetch logic in `DailyNotificationBackgroundTaskManager.swift`
/// - Use in test app for debugging BGTaskScheduler behavior
/// - See `doc/test-app-ios/IOS_PREFETCH_TESTING.md` for comprehensive testing guide
///
/// **Info.plist Requirements:**
/// ```xml
/// <key>BGTaskSchedulerPermittedIdentifiers</key>
/// <array>
///     <string>com.timesafari.dailynotification.fetch</string>
/// </array>
/// ```
///
/// **Background Modes (Xcode Capabilities):**
/// - Background fetch
/// - Background processing (if using BGProcessingTask)
class DailyNotificationBackgroundTaskTestHarness {
    
    // MARK: - Constants
    
    static let prefetchTaskIdentifier = "com.timesafari.dailynotification.fetch"
    
    // MARK: - Structured Logging
    
    /// Swift Logger categories for structured logging
    static let pluginLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "plugin")
    static let fetchLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "fetch")
    static let schedulerLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "scheduler")
    static let storageLogger = Logger(subsystem: "com.timesafari.dailynotification", category: "storage")
    
    /// Log telemetry snapshot for validation
    static func logTelemetrySnapshot(prefix: String = "DNP-") {
        // Phase 2: Capture telemetry counters from structured logs
        fetchLogger.info("Telemetry snapshot: \(prefix)prefetch_scheduled_total, \(prefix)prefetch_executed_total, \(prefix)prefetch_success_total")
    }
    
    // MARK: - Registration
    
    /// Register BGTaskScheduler task handler
    ///
    /// Call this in AppDelegate.application(_:didFinishLaunchingWithOptions:)
    /// before app finishes launching.
    static func registerBackgroundTasks() {
        BGTaskScheduler.shared.register(
            forTaskWithIdentifier: prefetchTaskIdentifier,
            using: nil
        ) { task in
            // This closure is called when the task is launched by the system
            handlePrefetchTask(task: task as! BGAppRefreshTask)
        }
        
        print("[DNP-FETCH] Registered BGTaskScheduler with id=\(prefetchTaskIdentifier)")
    }
    
    // MARK: - Scheduling
    
    /// Schedule a BGAppRefreshTask for prefetch
    ///
    /// - Parameter earliestOffsetSeconds: Seconds from now when task can begin
    /// - Returns: true if scheduling succeeded, false otherwise
    @discardableResult
    static func schedulePrefetchTask(earliestOffsetSeconds: TimeInterval) -> Bool {
        let request = BGAppRefreshTaskRequest(identifier: prefetchTaskIdentifier)
        request.earliestBeginDate = Date(timeIntervalSinceNow: earliestOffsetSeconds)
        
        do {
            try BGTaskScheduler.shared.submit(request)
            print("[DNP-FETCH] BGAppRefreshTask scheduled (earliestBeginDate=\(String(describing: request.earliestBeginDate)))")
            return true
        } catch {
            print("[DNP-FETCH] Failed to schedule BGAppRefreshTask: \(error)")
            return false
        }
    }
    
    // MARK: - Time Warp Simulation (Testing)
    
    /// Simulate time warp for accelerated testing
    ///
    /// Useful to accelerate DST, T-Lead, and cache TTL tests without waiting in real time.
    /// - Parameter minutesForward: Number of minutes to advance simulated time
    static func simulateTimeWarp(minutesForward: Int) {
        let timeWarpOffset = TimeInterval(minutesForward * 60)
        // Store time warp offset in UserDefaults for test harness use
        UserDefaults.standard.set(timeWarpOffset, forKey: "DNP_TimeWarpOffset")
        print("[DNP-FETCH] Time warp simulated: +\(minutesForward) minutes")
    }
    
    /// Get current time with time warp applied (testing only)
    static func getWarpedTime() -> Date {
        let offset = UserDefaults.standard.double(forKey: "DNP_TimeWarpOffset")
        return Date().addingTimeInterval(offset)
    }
    
    // MARK: - Force Reschedule
    
    /// Force reschedule all BGTasks and notifications
    ///
    /// Forces re-registration of BGTasks and notifications.
    /// Useful when testing repeated failures or BGTask recovery behavior.
    static func forceRescheduleAll() {
        print("[DNP-FETCH] Force rescheduling all tasks and notifications")
        // Cancel existing tasks
        BGTaskScheduler.shared.cancelAllTaskRequests()
        // Re-register and reschedule
        registerBackgroundTasks()
        // Trigger reschedule logic (implementation-specific)
    }
    
    // MARK: - Handler
    
    /// Handle BGAppRefreshTask execution
    ///
    /// This is called by the system when the background task is launched.
    /// Replace PrefetchOperation with your actual prefetch logic.
    private static func handlePrefetchTask(task: BGAppRefreshTask) {
        print("[DNP-FETCH] BGTask handler invoked (task.identifier=\(task.identifier))")
        
        // Schedule the next one early, so that there's always a pending task
        // In real implementation, calculate next schedule based on notification time
        schedulePrefetchTask(earliestOffsetSeconds: 60 * 30) // 30 minutes later, for example
        
        // Define the work
        let queue = OperationQueue()
        queue.maxConcurrentOperationCount = 1
        
        let operation = PrefetchOperation()
        
        // Set expiration handler
        // Called if iOS decides to end the task early (typically ~30 seconds)
        task.expirationHandler = {
            print("[DNP-FETCH] Task expired")
            operation.cancel()
        }
        
        // Set completion handler
        operation.completionBlock = {
            let success = !operation.isCancelled
            print("[DNP-FETCH] Task completionBlock (success=\(success))")
            task.setTaskCompleted(success: success)
        }
        
        queue.addOperation(operation)
    }
}

// MARK: - Prefetch Operation

/// Simple Operation example for testing
///
/// Replace this with your actual prefetch logic:
/// - HTTP fetch from TimeSafari API
/// - JWT signing
/// - ETag validation
/// - Content caching
/// - Error handling
class PrefetchOperation: Operation {
    
    override func main() {
        if isCancelled { return }
        
        print("[DNP-FETCH] PrefetchOperation: starting fake fetch...")
        
        // Simulate some work
        // In real implementation, this would be:
        // - Make HTTP request
        // - Parse response
        // - Cache content
        // - Update database
        Thread.sleep(forTimeInterval: 2)
        
        if isCancelled { return }
        
        print("[DNP-FETCH] PrefetchOperation: finished fake fetch.")
    }
}

// MARK: - AppDelegate Integration Example

/*
 Example integration in AppDelegate.swift:
 
 import UIKit
 import BackgroundTasks
 
 @main
 class AppDelegate: UIResponder, UIApplicationDelegate {
     
     func application(
         _ application: UIApplication,
         didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
     ) -> Bool {
         
         // Register background tasks BEFORE app finishes launching
         DailyNotificationBackgroundTaskTestHarness.registerBackgroundTasks()
         
         // Schedule initial task (for testing)
         DailyNotificationBackgroundTaskTestHarness.schedulePrefetchTask(earliestOffsetSeconds: 5 * 60) // 5 minutes
         
         return true
     }
 }
 */

// MARK: - Testing in Simulator

/*
 To test in simulator:
 
 1. Run app in Xcode
 2. Background the app (Home button / Cmd+Shift+H)
 3. In Xcode menu:
    - Debug → Simulate Background Fetch, or
    - Debug → Simulate Background Refresh
 4. Check console logs for [DNP-FETCH] messages
 
 Expected logs:
 - [DNP-FETCH] Registered BGTaskScheduler with id=...
 - [DNP-FETCH] BGAppRefreshTask scheduled (earliestBeginDate=...)
 - [DNP-FETCH] BGTask handler invoked (task.identifier=...)
 - [DNP-FETCH] PrefetchOperation: starting fake fetch...
 - [DNP-FETCH] PrefetchOperation: finished fake fetch.
 - [DNP-FETCH] Task completionBlock (success=true)
 */

// MARK: - Testing on Real Device

/*
 To test on real device:
 
 1. Install app on iPhone
 2. Enable Background App Refresh in Settings → [Your App]
 3. Schedule a notification with prefetch
 4. Lock device and leave idle (plugged in for best results)
 5. Monitor logs via:
    - Xcode → Devices & Simulators → device → open console
    - Or os_log aggregator / remote logging
 
 Note: Real device timing is heuristic, not deterministic.
 iOS will run the task when it determines it's appropriate,
 not necessarily at the exact earliestBeginDate.
 */