Use background URLSession with delegate for share-extension downloads

Final architecture for the web-URL share path. Earlier iterations
ranged through opening the host app via openURL: (broken on iOS 18+),
queueing into shared UserDefaults for the main app to drain (race
conditions and lost events), and downloading inline in the share
extension's foreground (worked but blocked the share UI for the
duration of the download). This commit lands the version that
actually works in the way iOS expects.

The share extension creates a background URLSession with
sharedContainerIdentifier set to the app group, kicks off a
downloadTask, and immediately returns from completeRequest -- the
share UI dismisses without waiting on bytes. iOS' nsurlsessiond
keeps the transfer running in its own daemon process.

Two delivery paths handle the eventual completion:

1. If the share extension's process is still alive when the download
   completes (typical for small files that finish in seconds), iOS
   routes the URLSession completion to *the alive process's session*.
   The previous "delegate: nil" version silently dropped the temp
   file in this case because there was no delegate to claim it. Now
   ShareViewController retains a BackgroundDownloadCoordinator that
   moves the temp file into DataManager.getSharedFilesFolderURL().

2. If iOS terminates the extension before the download completes
   (large files, slow networks), the transfer keeps running in
   nsurlsessiond. When it finishes, iOS launches the main app via
   application(_:handleEventsForBackgroundURLSession:completionHandler:);
   AppDelegate hands off to BackgroundShareDownloadDelegate, which
   recreates the same-identifier session, claims the temp file, and
   moves it into the same shared folder.

Either way the file lands in the app group's shared folder, where
the existing AirDrop-style import pipeline (notifyPendingFiles +
DirectoryWatcher + ImportManager) picks it up on the next foreground
and runs it through BookPlayer's standard review-and-place dialogs.

File URL shares (AirDrop, Files app, document picker) keep their
original synchronous-copy behaviour; only web URLs go through the
background-session path.

Includes the abandoned LibraryRootView UserDefaults-drain code being
cleaned up from earlier iterations, plus
Constants.shareExtensionBackgroundSessionIdentifier as the documented
shared key between extension and main app.

Author: matalvernaz

BookPlayer/AppDelegate.swift

@@ -79,9 +79,30 @@ class AppDelegate: UIResponder, UIApplicationDelegate, BPLogger {
     // Setup core services
     AppServices.shared.setupCoreServices()
 
+    /// Hook the URLSession delegate that handles share-extension background downloads.
+    /// Touching the lazy session re-attaches us as delegate for any transfer iOS already
+    /// has in flight from a prior share — without this, completions queued before the app
+    /// launched would be silently dropped.
+    BackgroundShareDownloadDelegate.shared.ensureSessionReady()
+
     return true
   }
 
+  func application(
+    _ application: UIApplication,
+    handleEventsForBackgroundURLSession identifier: String,
+    completionHandler: @escaping () -> Void
+  ) {
+    /// iOS calls this when a background URLSession we own has events to deliver and the app
+    /// was suspended/terminated. We only own the share-extension session; ignore others.
+    guard identifier == Constants.shareExtensionBackgroundSessionIdentifier else {
+      completionHandler()
+      return
+    }
+    BackgroundShareDownloadDelegate.shared.backgroundCompletionHandler = completionHandler
+    BackgroundShareDownloadDelegate.shared.ensureSessionReady()
+  }
+
   func application(
     _ application: UIApplication,
     handle intent: INIntent,
@@ -468,3 +489,94 @@ extension AppDelegate {
     queue.addOperation(backupOperation)
   }
 }
+
+/// Receives completion events for the background `URLSession` that the share extension
+/// uses to download shared web URLs. The share extension cannot keep its own foreground
+/// session alive after dismissal, so it kicks off the transfer with a background session
+/// keyed by `Constants.shareExtensionBackgroundSessionIdentifier`. When the download
+/// completes, iOS launches BookPlayer (in the background if needed) and routes events
+/// here. The delegate moves the temp file into the app group's shared folder, where
+/// BookPlayer's normal `ImportManager` pipeline picks it up the next time the user
+/// foregrounds the app.
+final class BackgroundShareDownloadDelegate: NSObject, URLSessionDownloadDelegate, BPLogger {
+  static let shared = BackgroundShareDownloadDelegate()
+
+  /// Stored from `application(_:handleEventsForBackgroundURLSession:completionHandler:)` —
+  /// must be invoked once `urlSessionDidFinishEvents` fires so iOS can take a fresh app
+  /// snapshot.
+  var backgroundCompletionHandler: (() -> Void)?
+
+  /// The session is recreated lazily with the same identifier the share extension uses,
+  /// which connects this delegate to any in-flight transfers iOS is already running for us.
+  private(set) lazy var session: URLSession = {
+    let config = URLSessionConfiguration.background(
+      withIdentifier: Constants.shareExtensionBackgroundSessionIdentifier
+    )
+    config.sharedContainerIdentifier = Constants.ApplicationGroupIdentifier
+    config.sessionSendsLaunchEvents = true
+    config.isDiscretionary = false
+    return URLSession(configuration: config, delegate: self, delegateQueue: nil)
+  }()
+
+  /// Touch the lazy session so it hooks up as the delegate for any pending transfers. Call
+  /// from `AppDelegate.didFinishLaunching` so completions don't get lost when the app cold-
+  /// starts after a download finished while the app was suspended.
+  func ensureSessionReady() {
+    _ = session
+  }
+
+  // MARK: - URLSessionDownloadDelegate
+
+  func urlSession(
+    _ session: URLSession,
+    downloadTask: URLSessionDownloadTask,
+    didFinishDownloadingTo location: URL
+  ) {
+    /// Reject non-2xx HTTP responses — `URLSession` reports success on a 404 and the temp
+    /// file just contains the error body. Don't deposit garbage into the library.
+    if let httpResponse = downloadTask.response as? HTTPURLResponse,
+       !(200..<300).contains(httpResponse.statusCode)
+    {
+      Self.logger.error(
+        "share download \(downloadTask.originalRequest?.url?.absoluteString ?? "?") returned status \(httpResponse.statusCode)"
+      )
+      return
+    }
+
+    let originalURL = downloadTask.originalRequest?.url
+    let filename =
+      downloadTask.response?.suggestedFilename
+      ?? originalURL?.lastPathComponent
+      ?? "shared-\(UUID().uuidString)"
+    let destinationURL = DataManager.getSharedFilesFolderURL().appendingPathComponent(filename)
+
+    /// Replace any same-named stale download from a previous attempt.
+    try? FileManager.default.removeItem(at: destinationURL)
+    do {
+      try FileManager.default.moveItem(at: location, to: destinationURL)
+      Self.logger.info("share download landed at \(destinationURL.lastPathComponent)")
+    } catch {
+      Self.logger.error("share download move failed: \(error.localizedDescription)")
+    }
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    didCompleteWithError error: Error?
+  ) {
+    if let error {
+      Self.logger.error(
+        "share download task error: \(error.localizedDescription) for \(task.originalRequest?.url?.absoluteString ?? "?")"
+      )
+    }
+  }
+
+  func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
+    DispatchQueue.main.async { [weak self] in
+      let handler = self?.backgroundCompletionHandler
+      self?.backgroundCompletionHandler = nil
+      handler?()
+    }
+  }
+}

BookPlayer/Library/ItemList/LibraryRootView.swift

@@ -92,7 +92,6 @@ struct LibraryRootView: View {
       }
       .onChange(of: scenePhase) {
         guard scenePhase == .active else { return }
-        drainPendingShareDownloadURLs()
         showImport()
       }
       .onReceive(syncService.downloadErrorPublisher) { (relativePath, error) in
@@ -143,30 +142,6 @@ struct LibraryRootView: View {
     for action in pendingActions {
       ActionParserService.handleAction(action)
     }
-
-    drainPendingShareDownloadURLs()
-  }
-
-  /// Drain web URLs the share extension queued in shared `UserDefaults` and feed them
-  /// to `SingleFileDownloadService` so the download runs in BookPlayer's normal UI and
-  /// lands directly in the library. Called both on initial library load and on every
-  /// `scenePhase == .active` transition: handleLibraryLoaded only fires once per
-  /// `LibraryRootView` lifecycle, but the user can share to BookPlayer while it's still
-  /// in memory in the background, in which case the drain has to run on warm-foreground
-  /// too. Idempotent: removing the UserDefaults key first means re-runs are no-ops.
-  func drainPendingShareDownloadURLs() {
-    let pendingShareURLStrings =
-      UserDefaults.sharedDefaults.stringArray(forKey: Constants.UserDefaults.pendingShareDownloadURLs)
-      ?? []
-    NSLog("BP-DRAIN: drainPendingShareDownloadURLs called, found %d URLs", pendingShareURLStrings.count)
-    guard !pendingShareURLStrings.isEmpty else { return }
-
-    UserDefaults.sharedDefaults.removeObject(forKey: Constants.UserDefaults.pendingShareDownloadURLs)
-    let urls = pendingShareURLStrings.compactMap(URL.init(string:))
-    if !urls.isEmpty {
-      NSLog("BP-DRAIN: handing %d URLs to singleFileDownloadService", urls.count)
-      singleFileDownloadService.handleDownload(urls)
-    }
   }
 
   func loadLastBookIfNeeded() async {

BookPlayerShareExtension/ShareViewController.swift

@@ -90,6 +90,10 @@ class ShareViewController: UIViewController {
   /// In-memory array of shared items
   var sharedItems = [URL]()
 
+  /// Retained URLSession delegate. Held so iOS can deliver the completion to *this*
+  /// process if the extension survives long enough — see `kickOffBackgroundDownloads`.
+  private var backgroundDownloadCoordinator: BackgroundDownloadCoordinator?
+
   /// File extensions BookPlayer can fetch from a remote `http(s)` URL.
   ///
   /// File-URL shares (AirDrop, Files app) are accepted unconditionally — they're already
@@ -201,14 +205,19 @@ class ShareViewController: UIViewController {
   }
 
   func saveSharedItems(_ items: [URL]) {
-    /// Two paths: file URLs (AirDrop, Files, Photos) get copied into the app group's shared
-    /// folder where the main app's `DirectoryWatcher` + `ImportManager` import them — same
-    /// code path that handles AirDropped audio. Web URLs are stashed in the app group's
-    /// shared `UserDefaults`; on next foreground the main app drains them and feeds them
-    /// to its existing `SingleFileDownloadService`, so the download runs in BookPlayer's
-    /// usual UI (progress bar, direct-into-library) instead of inside this extension.
-    /// (Share extensions can't launch their host app on current iOS, so a real URL handoff
-    /// isn't an option; queueing through shared `UserDefaults` is the closest substitute.)
+    /// File URLs (AirDrop, Files, document picker) are concrete on-disk items: copy them
+    /// into the app group's shared folder synchronously where the main app's
+    /// `ImportManager` will pick them up on next foreground — same code path AirDropped
+    /// audio uses.
+    ///
+    /// Web URLs are handed to a background `URLSession` keyed by
+    /// `Constants.shareExtensionBackgroundSessionIdentifier`, with
+    /// `sharedContainerIdentifier` set to the app group. The transfer is owned by iOS's
+    /// `nsurlsessiond` daemon, not by this extension's process, so we can immediately call
+    /// `completeRequest` and let the share UI dismiss without waiting for the bytes. When
+    /// the download finishes, iOS launches the BookPlayer main app (in the background if
+    /// needed) and `BackgroundShareDownloadDelegate` moves the temp file into the same
+    /// shared folder, where the standard import flow takes over.
     let fileItems = items.filter { $0.isFileURL }
     let webItems = items.filter { !$0.isFileURL }
 
@@ -218,24 +227,48 @@ class ShareViewController: UIViewController {
     }
 
     if !webItems.isEmpty {
-      queueWebURLsForMainApp(webItems)
+      kickOffBackgroundDownloads(for: webItems)
     }
 
     completeRequestOnMain()
   }
 
-  /// Append web URLs to the app group's shared `pendingShareDownloadURLs` array. The main
-  /// app reads and clears this array on next foreground (see `LibraryRootView.handleLibraryLoaded`)
-  /// and hands each URL to `SingleFileDownloadService.handleDownload(_:)`.
-  private func queueWebURLsForMainApp(_ urls: [URL]) {
-    let strings = urls.map { $0.absoluteString }
-    let existing =
-      UserDefaults.sharedDefaults.stringArray(forKey: Constants.UserDefaults.pendingShareDownloadURLs)
-      ?? []
-    UserDefaults.sharedDefaults.set(
-      existing + strings,
-      forKey: Constants.UserDefaults.pendingShareDownloadURLs
+  /// Schedules a background `URLSession` download for each shared web URL.
+  ///
+  /// Two delivery paths cover the lifecycle of the transfer:
+  ///
+  /// 1. If the extension's process is still alive when the download completes (typical for
+  ///    small files that finish in seconds), iOS routes the completion to *this session's*
+  ///    `URLSessionDownloadDelegate` — `BackgroundDownloadCoordinator` below — which moves
+  ///    the temp file into the app group's shared folder.
+  /// 2. If iOS suspends/terminates the extension before the download completes, the
+  ///    transfer continues via `nsurlsessiond` and iOS routes completion to the main app
+  ///    via `application(_:handleEventsForBackgroundURLSession:completionHandler:)`. Main
+  ///    app recreates the same session identifier and `BackgroundShareDownloadDelegate`
+  ///    handles the move there.
+  ///
+  /// We previously created the session with `delegate: nil` assuming iOS would always
+  /// route to the main app, but in practice downloads small enough to finish before the
+  /// extension dies got their events delivered to a nil delegate and the temp file was
+  /// silently discarded. The first path above plugs that gap.
+  private func kickOffBackgroundDownloads(for urls: [URL]) {
+    let config = URLSessionConfiguration.background(
+      withIdentifier: Constants.shareExtensionBackgroundSessionIdentifier
     )
+    config.sharedContainerIdentifier = Constants.ApplicationGroupIdentifier
+    config.sessionSendsLaunchEvents = true
+    config.isDiscretionary = false
+
+    /// Retain the coordinator on the running view controller so its delegate methods can
+    /// fire if iOS keeps this process alive past the share-sheet dismissal — typical for
+    /// downloads that complete in a few seconds.
+    let coordinator = BackgroundDownloadCoordinator()
+    self.backgroundDownloadCoordinator = coordinator
+    let session = URLSession(configuration: config, delegate: coordinator, delegateQueue: nil)
+    for url in urls {
+      session.downloadTask(with: url).resume()
+    }
+    session.finishTasksAndInvalidate()
   }
 
   private func completeRequestOnMain() {
@@ -303,3 +336,40 @@ extension ShareViewController: UITableViewDelegate {}
 enum ShareExtensionError: Error {
   case cancelled
 }
+
+/// `URLSessionDownloadDelegate` for the share extension's background download.
+///
+/// Used when the extension's process is still alive when iOS finishes the download —
+/// typically the case for small files that complete in a few seconds. Without a delegate
+/// here, iOS would silently discard the temp file because the alive-extension's session
+/// is the active one (iOS only escalates to the main app's matching-identifier session
+/// when the extension's process is gone).
+///
+/// Moves the temp file into the app group's shared folder, where the main app's
+/// `ImportManager` picks it up on next foreground.
+final class BackgroundDownloadCoordinator: NSObject, URLSessionDownloadDelegate {
+  func urlSession(
+    _ session: URLSession,
+    downloadTask: URLSessionDownloadTask,
+    didFinishDownloadingTo location: URL
+  ) {
+    /// Reject non-2xx HTTP responses — `URLSession` reports success on a 404 and the temp
+    /// file just contains the error body.
+    if let httpResponse = downloadTask.response as? HTTPURLResponse,
+       !(200..<300).contains(httpResponse.statusCode)
+    {
+      return
+    }
+
+    let originalURL = downloadTask.originalRequest?.url
+    let filename =
+      downloadTask.response?.suggestedFilename
+      ?? originalURL?.lastPathComponent
+      ?? "shared-\(UUID().uuidString)"
+    let destinationURL = DataManager.getSharedFilesFolderURL().appendingPathComponent(filename)
+
+    /// Replace any same-named stale download from a previous attempt.
+    try? FileManager.default.removeItem(at: destinationURL)
+    try? FileManager.default.moveItem(at: location, to: destinationURL)
+  }
+}

Shared/Constants.swift

@@ -53,11 +53,6 @@ public enum Constants {
     /// Key to store an array of identifiers that need their progress recalculated
     public static let staleProgressIdentifiers = "staleProgressIdentifiers"
 
-    /// Web URLs the share extension queued for the main app to download with
-    /// `SingleFileDownloadService` on next foreground. Lives in the app group's shared
-    /// `UserDefaults` so both processes see the same value.
-    public static let pendingShareDownloadURLs = "pendingShareDownloadURLs"
-
     // One-time migrations
     public static let fileProtectionMigration = "userFileProtectionMigration"
 
@@ -136,6 +131,14 @@ public enum Constants {
   public static let UserActivityPlayback = Bundle.main.bundleIdentifier! + ".activity.playback"
   public static let ApplicationGroupIdentifier = "group.\(Bundle.main.configurationString(for: .bundleIdentifier)).files"
 
+  /// `URLSessionConfiguration.background` identifier used by the share extension to download
+  /// shared web URLs. The main app re-creates a session with the same identifier in
+  /// `application(_:handleEventsForBackgroundURLSession:completionHandler:)` so the
+  /// `BackgroundShareDownloadDelegate` receives completion and can move the resulting file
+  /// into the app group's shared folder.
+  public static let shareExtensionBackgroundSessionIdentifier =
+    "\(Bundle.main.configurationString(for: .bundleIdentifier)).shareext.background"
+
   public enum Widgets: String {
     case sharedNowPlayingWidget = "com.bookplayer.shared.widget"
     case sharedIconWidget = "com.bookplayer.shared.icon.widget"