uploados 0.1.0

package/ios/Upload/UploadManager.swift

@@ -0,0 +1,813 @@
+import ExpoModulesCore
+import Foundation
+
+final class UploadManager: NSObject {
+  static let shared = UploadManager()
+
+  static let backgroundSessionIdentifier = "expo.modules.uploados.background"
+
+  private let store = UploadTaskStore.shared
+  private let sessionDelegate = UploadSessionDelegate()
+  private var eventEmitter: (([String: Any]) -> Void)?
+  private var foregroundWaitSession: URLSession!
+  private var foregroundFailFastSession: URLSession!
+  private var backgroundSession: URLSession!
+  private var backgroundCompletionHandlers: [String: () -> Void] = [:]
+  private var lastProgressEmit: [String: TimeInterval] = [:]
+  private let progressThrottleMs: TimeInterval = 250
+  private let baseRetryDelayMs: TimeInterval = 1000
+  private let maxRetryDelayMs: TimeInterval = 30_000
+
+  private override init() {
+    super.init()
+    sessionDelegate.manager = self
+    let foregroundWaitConfig = URLSessionConfiguration.default
+    foregroundWaitConfig.waitsForConnectivity = true
+    foregroundWaitSession = URLSession(
+      configuration: foregroundWaitConfig,
+      delegate: sessionDelegate,
+      delegateQueue: nil
+    )
+    let foregroundFailFastConfig = URLSessionConfiguration.default
+    foregroundFailFastConfig.waitsForConnectivity = false
+    foregroundFailFastSession = URLSession(
+      configuration: foregroundFailFastConfig,
+      delegate: sessionDelegate,
+      delegateQueue: nil
+    )
+    let backgroundConfig = URLSessionConfiguration.background(
+      withIdentifier: Self.backgroundSessionIdentifier
+    )
+    backgroundConfig.waitsForConnectivity = true
+    backgroundSession = URLSession(
+      configuration: backgroundConfig,
+      delegate: sessionDelegate,
+      delegateQueue: nil
+    )
+  }
+
+  func setEventEmitter(_ emitter: @escaping ([String: Any]) -> Void) {
+    eventEmitter = emitter
+  }
+
+  func createUpload(options: CreateUploadOptions) throws -> UploadTaskRecord {
+    let now = Date().timeIntervalSince1970 * 1000
+    let taskId = UUID().uuidString
+    var record = UploadTaskRecord(
+      id: taskId,
+      localUri: options.localUri,
+      compressionEnabled: options.compressionEnabled,
+      compressionPreset: options.compressionEnabled ? options.compressionPreset.rawValue : nil,
+      uploadUrl: options.uploadUrl,
+      method: options.method,
+      state: .created,
+      progress: UploadProgress(bytesUploaded: 0, totalBytes: 0, percentage: 0),
+      background: options.background,
+      networkPolicy: options.networkPolicy,
+      attempt: 0,
+      maxAttempts: options.maxAttempts,
+      nextRetryAt: nil,
+      createdAt: now,
+      updatedAt: now,
+      headers: options.headers,
+      sessionTaskIdentifier: nil,
+      error: nil
+    )
+    store.upsert(record)
+    emit(event: ["type": "created", "task": record.toDictionary()])
+
+    record = store.update(id: taskId) { task in
+      task.state = .compressing
+    } ?? record
+    emit(event: ["type": "compressing", "taskId": taskId, "task": record.toDictionary()])
+
+    let fileURL: URL
+    let fileSize: Int
+    do {
+      let prepared = try prepareUploadFile(for: taskId, localUri: options.localUri, stagedFilePath: nil)
+      if let stagedPath = prepared.stagedPath {
+        record = store.update(id: taskId) { task in
+          task.stagedFilePath = stagedPath
+        } ?? record
+      }
+
+      if options.compressionEnabled {
+        if let optimizedPath = record.optimizedFilePath,
+           FileManager.default.fileExists(atPath: optimizedPath) {
+          fileURL = URL(fileURLWithPath: optimizedPath)
+          let attributes = try FileManager.default.attributesOfItem(atPath: optimizedPath)
+          fileSize = (attributes[.size] as? NSNumber)?.intValue ?? 0
+        } else {
+          let result = try CompressionPipeline.compress(
+            sourceURL: prepared.url,
+            taskId: taskId,
+            preset: options.compressionPreset
+          )
+          record = store.update(id: taskId) { task in
+            task.optimizedFilePath = result.outputURL.path
+            task.originalSize = result.stats.originalSize
+            task.optimizedSize = result.stats.optimizedSize
+          } ?? record
+          emit(event: [
+            "type": "compressed",
+            "taskId": taskId,
+            "task": record.toDictionary(),
+            "stats": result.stats.toDictionary(),
+          ])
+          fileURL = result.outputURL
+          fileSize = result.stats.optimizedSize
+        }
+      } else {
+        fileURL = prepared.url
+        let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
+        fileSize = (attributes[.size] as? NSNumber)?.intValue ?? 0
+        if fileSize > 0 {
+          record = store.update(id: taskId) { task in
+            task.originalSize = fileSize
+          } ?? record
+        }
+      }
+      guard fileSize > 0 else {
+        throw UploadManagerError.fileNotFound(options.localUri)
+      }
+    } catch let error as CompressionPipelineError {
+      markFailed(
+        taskId: taskId,
+        code: .COMPRESSION_FAILED,
+        message: error.localizedDescription,
+        retryable: false,
+        phase: "compressing",
+        httpStatus: nil,
+        providerCode: nil,
+        providerMessage: nil,
+        nativeCause: nil
+      )
+      throw error
+    } catch {
+      markFailed(
+        taskId: taskId,
+        code: .FILE_NOT_FOUND,
+        message: error.localizedDescription,
+        retryable: false,
+        phase: "compressing",
+        httpStatus: nil,
+        providerCode: nil,
+        providerMessage: nil,
+        nativeCause: nil
+      )
+      throw error
+    }
+
+    record = store.update(id: taskId) { task in
+      task.state = .queued
+      task.progress = UploadProgress(bytesUploaded: 0, totalBytes: fileSize, percentage: 0)
+    } ?? record
+    emit(event: ["type": "queued", "taskId": taskId])
+
+    try startUploadOrMarkFailed(for: record, fileURL: fileURL)
+    return store.task(id: taskId) ?? record
+  }
+
+  func cancelUpload(taskId: String) throws -> UploadTaskRecord {
+    guard var record = store.task(id: taskId) else {
+      throw UploadManagerError.taskNotFound(taskId)
+    }
+    if let sessionTaskId = record.sessionTaskIdentifier {
+      session(for: record).getAllTasks { tasks in
+        tasks.first(where: { $0.taskIdentifier == sessionTaskId })?.cancel()
+      }
+    }
+    record.state = .cancelled
+    record.error = UploadErrorPayload(
+      code: .CANCELLED,
+      message: "Upload cancelled.",
+      retryable: false,
+      taskId: taskId,
+      phase: nil,
+      httpStatus: nil,
+      providerCode: nil,
+      providerMessage: nil,
+      nativeCause: nil
+    )
+    record.nextRetryAt = nil
+    record.sessionTaskIdentifier = nil
+    record.updatedAt = Date().timeIntervalSince1970 * 1000
+    cleanupDerivedFilesIfNeeded(for: record)
+    record.stagedFilePath = nil
+    record.optimizedFilePath = nil
+    store.upsert(record)
+    emit(event: ["type": "cancelled", "taskId": taskId])
+    return store.task(id: taskId) ?? record
+  }
+
+  func retryUpload(taskId: String) throws -> UploadTaskRecord {
+    guard var record = store.task(id: taskId) else {
+      throw UploadManagerError.taskNotFound(taskId)
+    }
+    guard record.state == .failed else {
+      throw UploadManagerError.invalidRetryState(taskId, record.state.rawValue)
+    }
+
+    record = store.update(id: taskId) { task in
+      task.state = .compressing
+      task.error = nil
+      task.nextRetryAt = nil
+      task.sessionTaskIdentifier = nil
+    } ?? record
+    emit(event: ["type": "compressing", "taskId": taskId, "task": record.toDictionary()])
+
+    let fileURL: URL
+    let fileSize: Int
+    do {
+      fileURL = try resolveUploadFileURL(for: record)
+      let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
+      fileSize = (attributes[.size] as? NSNumber)?.intValue ?? record.optimizedSize ?? record.progress.totalBytes
+      guard fileSize > 0 else {
+        throw UploadManagerError.fileNotFound(record.localUri)
+      }
+    } catch {
+      markFailed(
+        taskId: taskId,
+        code: .FILE_NOT_FOUND,
+        message: error.localizedDescription,
+        retryable: false,
+        phase: "compressing",
+        httpStatus: nil,
+        providerCode: nil,
+        providerMessage: nil,
+        nativeCause: nil
+      )
+      throw error
+    }
+
+    record = store.update(id: taskId) { task in
+      task.state = .queued
+      task.progress = UploadProgress(
+        bytesUploaded: 0,
+        totalBytes: fileSize,
+        percentage: 0
+      )
+      task.attempt = 0
+      task.error = nil
+      task.nextRetryAt = nil
+      task.sessionTaskIdentifier = nil
+    } ?? record
+    emit(event: ["type": "queued", "taskId": taskId])
+
+    try startUploadOrMarkFailed(for: record, fileURL: fileURL)
+    return store.task(id: taskId) ?? record
+  }
+
+  func restoreQueue() -> [UploadTaskRecord] {
+    let pending = store.restorableTasks()
+    let activeBackgroundTaskIds = reconcileBackgroundSessionTasks()
+    for record in pending {
+      if record.background && activeBackgroundTaskIds.contains(record.id) {
+        continue
+      }
+      do {
+        let fileURL = try resolveUploadFileURL(for: record)
+        if record.state == .retrying, let nextRetryAt = record.nextRetryAt {
+          let delayMs = max(0, nextRetryAt - Date().timeIntervalSince1970 * 1000)
+          scheduleStart(for: record.id, delayMs: delayMs)
+        } else {
+          try startUpload(for: record, fileURL: fileURL)
+        }
+      } catch {
+        markFailed(
+          taskId: record.id,
+          code: .FILE_NOT_FOUND,
+          message: error.localizedDescription,
+          retryable: false,
+          phase: "compressing",
+          httpStatus: nil,
+          providerCode: nil,
+          providerMessage: nil,
+          nativeCause: nil
+        )
+      }
+    }
+    return store.allTasks()
+  }
+
+  func registerBackgroundCompletionHandler(
+    for identifier: String,
+    completionHandler: @escaping () -> Void
+  ) {
+    backgroundCompletionHandlers[identifier] = completionHandler
+  }
+
+  func invokeBackgroundCompletionHandler(for identifier: String?) {
+    guard let identifier,
+          let handler = backgroundCompletionHandlers.removeValue(forKey: identifier) else {
+      return
+    }
+    DispatchQueue.main.async {
+      handler()
+    }
+  }
+
+  func handleProgress(taskId: String, bytesUploaded: Int, totalBytes: Int) {
+    let now = Date().timeIntervalSince1970 * 1000
+    let lastEmit = lastProgressEmit[taskId] ?? 0
+    let percentage = totalBytes > 0
+      ? min(100, max(0, (Double(bytesUploaded) / Double(totalBytes)) * 100))
+      : 0
+    let previous = store.task(id: taskId)
+    let isVerifying = percentage >= 100
+
+    guard let updated = store.update(id: taskId, mutate: { task in
+      task.state = isVerifying ? .verifying : .uploading
+      task.progress = UploadProgress(
+        bytesUploaded: bytesUploaded,
+        totalBytes: totalBytes,
+        percentage: percentage
+      )
+    }) else {
+      return
+    }
+
+    if now - lastEmit < progressThrottleMs && percentage < 100 {
+      return
+    }
+    lastProgressEmit[taskId] = now
+    if isVerifying && previous?.state != .verifying {
+      emit(event: ["type": "verifying", "taskId": taskId])
+    }
+    emit(event: [
+      "type": "progress",
+      "taskId": taskId,
+      "progress": [
+        "bytesUploaded": updated.progress.bytesUploaded,
+        "totalBytes": updated.progress.totalBytes,
+        "percentage": updated.progress.percentage,
+      ],
+    ])
+  }
+
+  func handleCompletion(taskId: String) {
+    guard let updated = store.update(id: taskId, mutate: { task in
+      task.state = .completed
+      task.progress.percentage = 100
+      task.progress.bytesUploaded = task.progress.totalBytes
+      task.error = nil
+      task.nextRetryAt = nil
+      task.sessionTaskIdentifier = nil
+    }) else {
+      return
+    }
+    lastProgressEmit.removeValue(forKey: taskId)
+    cleanupDerivedFilesIfNeeded(for: updated)
+    let finalRecord = store.update(id: taskId) { record in
+      record.stagedFilePath = nil
+      record.optimizedFilePath = nil
+    } ?? updated
+    emit(event: [
+      "type": "completed",
+      "taskId": taskId,
+      "task": finalRecord.toDictionary(),
+    ])
+  }
+
+  func handleFailure(taskId: String, error: Error, response: URLResponse?) {
+    if (error as NSError).code == NSURLErrorCancelled {
+      return
+    }
+    let retryable = isRetryable(error: error, response: response)
+    let nsError = error as NSError
+    failOrRetry(
+      taskId: taskId,
+      code: .NETWORK_ERROR,
+      message: error.localizedDescription,
+      retryable: retryable,
+      phase: failurePhase(taskId: taskId),
+      httpStatus: (response as? HTTPURLResponse)?.statusCode,
+      providerCode: nil,
+      providerMessage: nil,
+      nativeCause: "\(nsError.domain):\(nsError.code)"
+    )
+  }
+
+  private func failurePhase(taskId: String) -> String {
+    switch store.task(id: taskId)?.state {
+    case .compressing:
+      return "compressing"
+    case .connecting:
+      return "connecting"
+    case .verifying:
+      return "verifying"
+    case .retrying:
+      return "retrying"
+    default:
+      return "uploading"
+    }
+  }
+
+  func handleHttpFailure(taskId: String, statusCode: Int, responseBody: String?) {
+    let code: UploadErrorCode = statusCode == 401 || statusCode == 403 ? .AUTH_ERROR : .PROVIDER_ERROR
+    let providerError = parseProviderError(from: responseBody)
+    failOrRetry(
+      taskId: taskId,
+      code: code,
+      message: providerError.message ?? "Upload failed with HTTP status \(statusCode).",
+      retryable: statusCode >= 500,
+      phase: "verifying",
+      httpStatus: statusCode,
+      providerCode: providerError.code,
+      providerMessage: providerError.message,
+      nativeCause: nil
+    )
+  }
+
+  private func startUpload(for record: UploadTaskRecord, fileURL: URL) throws {
+    guard let destination = URL(string: record.uploadUrl) else {
+      throw UploadManagerError.invalidUploadUrl(record.uploadUrl)
+    }
+
+    var request = URLRequest(url: destination)
+    request.httpMethod = record.method
+    for (key, value) in record.headers {
+      request.setValue(value, forHTTPHeaderField: key)
+    }
+
+    let session = session(for: record)
+    let uploadTask = session.uploadTask(with: request, fromFile: fileURL)
+    uploadTask.taskDescription = record.id
+    uploadTask.priority = URLSessionTask.defaultPriority
+
+    let updated = store.update(id: record.id) { task in
+      let nextAttempt = task.attempt + 1
+      task.state = .connecting
+      task.attempt = nextAttempt
+      task.nextRetryAt = nil
+      if nextAttempt > 1 {
+        task.progress.bytesUploaded = 0
+        task.progress.percentage = 0
+      }
+      task.sessionTaskIdentifier = uploadTask.taskIdentifier
+    }
+    if let updated {
+      emit(event: ["type": "connecting", "taskId": record.id, "task": updated.toDictionary()])
+    }
+    uploadTask.resume()
+  }
+
+  private func startUploadOrMarkFailed(for record: UploadTaskRecord, fileURL: URL) throws {
+    do {
+      try startUpload(for: record, fileURL: fileURL)
+    } catch {
+      markFailed(
+        taskId: record.id,
+        code: .UNKNOWN,
+        message: error.localizedDescription,
+        retryable: false,
+        phase: "connecting",
+        httpStatus: nil,
+        providerCode: nil,
+        providerMessage: nil,
+        nativeCause: nil
+      )
+      throw error
+    }
+  }
+
+  private func session(for record: UploadTaskRecord) -> URLSession {
+    if record.background {
+      return backgroundSession
+    }
+    return record.networkPolicy == .failFast ? foregroundFailFastSession : foregroundWaitSession
+  }
+
+  private func reconcileBackgroundSessionTasks() -> Set<String> {
+    let semaphore = DispatchSemaphore(value: 0)
+    var activeTaskIds = Set<String>()
+    backgroundSession.getAllTasks { tasks in
+      for task in tasks {
+        guard let taskId = task.taskDescription else {
+          continue
+        }
+        activeTaskIds.insert(taskId)
+        if self.store.task(id: taskId) == nil {
+          task.cancel()
+        } else {
+          _ = self.store.update(id: taskId) { record in
+            record.sessionTaskIdentifier = task.taskIdentifier
+          }
+        }
+      }
+      semaphore.signal()
+    }
+    _ = semaphore.wait(timeout: .now() + 2)
+    return activeTaskIds
+  }
+
+  private func markFailed(
+    taskId: String,
+    code: UploadErrorCode,
+    message: String,
+    retryable: Bool,
+    phase: String?,
+    httpStatus: Int?,
+    providerCode: String?,
+    providerMessage: String?,
+    nativeCause: String?
+  ) {
+    let error = UploadErrorPayload(
+      code: code,
+      message: message,
+      retryable: retryable,
+      taskId: taskId,
+      phase: phase,
+      httpStatus: httpStatus,
+      providerCode: providerCode,
+      providerMessage: providerMessage,
+      nativeCause: nativeCause
+    )
+    guard let updated = store.update(id: taskId, mutate: { task in
+      task.state = .failed
+      task.error = error
+      task.nextRetryAt = nil
+      task.sessionTaskIdentifier = nil
+    }) else {
+      return
+    }
+    lastProgressEmit.removeValue(forKey: taskId)
+    cleanupDerivedFilesIfNeeded(for: updated)
+    let finalRecord = store.update(id: taskId) { record in
+      record.stagedFilePath = nil
+      record.optimizedFilePath = nil
+    } ?? updated
+    emit(event: [
+      "type": "failed",
+      "taskId": taskId,
+      "error": error.toDictionary(),
+      "task": finalRecord.toDictionary(),
+    ])
+  }
+
+  private func failOrRetry(
+    taskId: String,
+    code: UploadErrorCode,
+    message: String,
+    retryable: Bool,
+    phase: String?,
+    httpStatus: Int?,
+    providerCode: String?,
+    providerMessage: String?,
+    nativeCause: String?
+  ) {
+    guard let record = store.task(id: taskId) else {
+      return
+    }
+
+    if retryable && record.networkPolicy != .failFast && record.attempt < record.maxAttempts {
+      scheduleRetry(
+        record: record,
+        code: code,
+        message: message,
+        phase: phase,
+        httpStatus: httpStatus,
+        providerCode: providerCode,
+        providerMessage: providerMessage,
+        nativeCause: nativeCause
+      )
+      return
+    }
+
+    markFailed(
+      taskId: taskId,
+      code: code,
+      message: message,
+      retryable: retryable,
+      phase: phase,
+      httpStatus: httpStatus,
+      providerCode: providerCode,
+      providerMessage: providerMessage,
+      nativeCause: nativeCause
+    )
+  }
+
+  private func scheduleRetry(
+    record: UploadTaskRecord,
+    code: UploadErrorCode,
+    message: String,
+    phase: String?,
+    httpStatus: Int?,
+    providerCode: String?,
+    providerMessage: String?,
+    nativeCause: String?
+  ) {
+    let delayMs = retryDelayMs(forAttempt: record.attempt)
+    let nextRetryAt = Date().timeIntervalSince1970 * 1000 + delayMs
+    let error = UploadErrorPayload(
+      code: code,
+      message: message,
+      retryable: true,
+      taskId: record.id,
+      phase: phase,
+      httpStatus: httpStatus,
+      providerCode: providerCode,
+      providerMessage: providerMessage,
+      nativeCause: nativeCause
+    )
+    guard let updated = store.update(id: record.id, mutate: { task in
+      task.state = .retrying
+      task.error = error
+      task.nextRetryAt = nextRetryAt
+      task.sessionTaskIdentifier = nil
+    }) else {
+      return
+    }
+    lastProgressEmit.removeValue(forKey: record.id)
+    emit(event: [
+      "type": "retrying",
+      "taskId": record.id,
+      "attempt": updated.attempt + 1,
+      "delayMs": delayMs,
+      "error": error.toDictionary(),
+    ])
+    scheduleStart(for: record.id, delayMs: delayMs)
+  }
+
+  private func scheduleStart(for taskId: String, delayMs: TimeInterval) {
+    DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + delayMs / 1000) { [weak self] in
+      guard let self,
+            let latest = self.store.task(id: taskId),
+            latest.state == .retrying || latest.state == .queued || latest.state == .connecting || latest.state == .uploading else {
+        return
+      }
+      do {
+        let fileURL = try self.resolveUploadFileURL(for: latest)
+        try self.startUpload(for: latest, fileURL: fileURL)
+      } catch {
+        self.markFailed(
+          taskId: taskId,
+          code: .FILE_NOT_FOUND,
+          message: error.localizedDescription,
+          retryable: false,
+          phase: "compressing",
+          httpStatus: nil,
+          providerCode: nil,
+          providerMessage: nil,
+          nativeCause: nil
+        )
+      }
+    }
+  }
+
+  private func retryDelayMs(forAttempt attempt: Int) -> TimeInterval {
+    let exponent = max(0, attempt - 1)
+    let delay = min(maxRetryDelayMs, baseRetryDelayMs * pow(2.0, Double(exponent)))
+    return delay + Double.random(in: 0...(delay * 0.2))
+  }
+
+  private func isRetryable(error: Error, response: URLResponse?) -> Bool {
+    let nsError = error as NSError
+    if nsError.domain == NSURLErrorDomain {
+      switch nsError.code {
+      case NSURLErrorTimedOut,
+           NSURLErrorNetworkConnectionLost,
+           NSURLErrorNotConnectedToInternet,
+           NSURLErrorCannotConnectToHost,
+           NSURLErrorCannotFindHost,
+           NSURLErrorDNSLookupFailed,
+           NSURLErrorInternationalRoamingOff,
+           NSURLErrorDataNotAllowed:
+        return true
+      default:
+        break
+      }
+    }
+    if let http = response as? HTTPURLResponse {
+      return http.statusCode >= 500
+    }
+    return false
+  }
+
+  private func parseProviderError(from responseBody: String?) -> (code: String?, message: String?) {
+    guard let responseBody, !responseBody.isEmpty else {
+      return (nil, nil)
+    }
+    if let data = responseBody.data(using: .utf8),
+       let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+      let code = object["Code"] as? String ?? object["code"] as? String
+      let message = object["Message"] as? String ?? object["message"] as? String
+      return (code, message)
+    }
+    return (
+      xmlValue("Code", in: responseBody),
+      xmlValue("Message", in: responseBody)
+    )
+  }
+
+  private func xmlValue(_ name: String, in body: String) -> String? {
+    guard let openRange = body.range(of: "<\(name)>"),
+          let closeRange = body.range(of: "</\(name)>", range: openRange.upperBound..<body.endIndex) else {
+      return nil
+    }
+    return String(body[openRange.upperBound..<closeRange.lowerBound])
+  }
+
+  private func emit(event: [String: Any]) {
+    eventEmitter?(event)
+  }
+
+  private struct PreparedUploadFile {
+    let url: URL
+    let stagedPath: String?
+  }
+
+  private func prepareUploadFile(
+    for taskId: String,
+    localUri: String,
+    stagedFilePath: String?
+  ) throws -> PreparedUploadFile {
+    if let stagedFilePath, !stagedFilePath.isEmpty {
+      let stagedURL = URL(fileURLWithPath: stagedFilePath)
+      if FileManager.default.fileExists(atPath: stagedURL.path),
+         FileManager.default.isReadableFile(atPath: stagedURL.path) {
+        return PreparedUploadFile(url: stagedURL, stagedPath: stagedFilePath)
+      }
+    }
+
+    let sourceURL = try resolveSourceFileURL(localUri)
+    guard FileStager.needsStaging(uri: localUri, fileURL: sourceURL) else {
+      return PreparedUploadFile(url: sourceURL, stagedPath: nil)
+    }
+
+    let stagedURL = try FileStager.stageFile(sourceURL: sourceURL, taskId: taskId)
+    return PreparedUploadFile(url: stagedURL, stagedPath: stagedURL.path)
+  }
+
+  private func resolveUploadFileURL(for record: UploadTaskRecord) throws -> URL {
+    if let optimizedFilePath = record.optimizedFilePath,
+       FileManager.default.fileExists(atPath: optimizedFilePath) {
+      return URL(fileURLWithPath: optimizedFilePath)
+    }
+    let prepared = try prepareUploadFile(
+      for: record.id,
+      localUri: record.localUri,
+      stagedFilePath: record.stagedFilePath
+    )
+    if let stagedPath = prepared.stagedPath, record.stagedFilePath != stagedPath {
+      _ = store.update(id: record.id) { task in
+        task.stagedFilePath = stagedPath
+      }
+    }
+    return prepared.url
+  }
+
+  private func cleanupDerivedFilesIfNeeded(for record: UploadTaskRecord) {
+    cleanupStagedFileIfNeeded(for: record)
+    if let optimizedFilePath = record.optimizedFilePath {
+      CompressionPipeline.cleanupOptimizedFile(path: optimizedFilePath)
+    }
+  }
+
+  private func cleanupStagedFileIfNeeded(for record: UploadTaskRecord) {
+    guard let stagedFilePath = record.stagedFilePath else {
+      return
+    }
+    FileStager.cleanupStagedFile(path: stagedFilePath)
+  }
+
+  private func resolveSourceFileURL(_ uri: String) throws -> URL {
+    let fileURL: URL
+    if uri.hasPrefix("file://") {
+      guard let parsed = URL(string: uri) else {
+        throw UploadManagerError.fileNotFound(uri)
+      }
+      fileURL = parsed
+    } else {
+      fileURL = URL(fileURLWithPath: uri)
+    }
+
+    // Picker/Inbox paths (e.g. …-Inbox/topImage.jpeg) are temporary; after restart the file
+    // is gone. URLSession throws NSInvalidArgumentException if fromFile: is missing — validate first.
+    guard FileManager.default.fileExists(atPath: fileURL.path),
+          FileManager.default.isReadableFile(atPath: fileURL.path) else {
+      throw UploadManagerError.fileNotFound(uri)
+    }
+    return fileURL
+  }
+}
+
+enum UploadManagerError: Error, LocalizedError {
+  case fileNotFound(String)
+  case invalidUploadUrl(String)
+  case invalidRetryState(String, String)
+  case taskNotFound(String)
+
+  var errorDescription: String? {
+    switch self {
+    case .fileNotFound(let uri):
+      return "File not found at \(uri)."
+    case .invalidUploadUrl(let url):
+      return "Invalid upload URL: \(url)."
+    case .invalidRetryState(let id, let state):
+      return "Upload task \(id) cannot be retried from state \(state)."
+    case .taskNotFound(let id):
+      return "Upload task not found: \(id)."
+    }
+  }
+}