Releases/v0.3.0 (#26)

# API Changes

* `MuxUpload`'s initializer no longer requires a MIME type or Retry Time. These are calculated internally
* Added methods for querying the `UploadManager` for the list of currenty-active uploads, and listening for changes to the list

## Improvements

* NFC: call into upload manager reference (#14)
* api: Remove extraneous MIME type and retry time config fields, add opt-out for event tracking (#16)
* doc: Add a much-improved example app (#15)

## Fixes
* Fix: Uploads continue without reporting progress after being resumed (#24)
* Fix: handlers not retained unless callers retain the `MuxUpload` (#25)



Co-authored-by: AJ Lauer Barinov <102617203+andrewjl-mux@users.noreply.github.com>
Co-authored-by: Liam Lindner <liam@mux.com>
Co-authored-by: Emily Dixon <edixon@mux.com>
Co-authored-by: GitHub <noreply@github.com>

Author: 4 people

Mux-Upload-SDK.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
   s.name             = 'Mux-Upload-SDK'
   s.module_name      = 'MuxUploadSDK'
-  s.version          = '0.2.1'
+  s.version          = '0.3.0'
   s.summary          = 'Upload video to Mux.'
   s.description      = 'A library for uploading video to Mux. Similar to UpChunk, but for iOS.'
 

Sources/MuxUploadSDK/Internal Utilities/ChunkedFile.swift Sources/MuxUploadSDK/InternalUtilities/ChunkedFile.swift

@@ -28,7 +28,7 @@ class ChunkedFile {
 
     /// Reads the next chunk from the file, advancing the file for the next read
     ///  This method does synchronous I/O, so call it in the background
-    public func readNextChunk() -> Result<FileChunk, Error> {
+    func readNextChunk() -> Result<FileChunk, Error> {
         MuxUploadSDK.logger?.info("--readNextChunk(): called")
         do {
             guard fileHandle != nil else {
@@ -84,8 +84,8 @@ class ChunkedFile {
         }
         let data = try fileHandle.read(upToCount: chunkSize)
         guard let data = data else {
-            // No more data to read, we reached EOF. The caller shouldn't call us like this, but let's be safe
-            return FileChunk(startByte: 0, endByte: 0, totalFileSize: 0, chunkData: Data(capacity: 0))
+            // Called while already at the end of the file. We read zero bytes, "ending" at the end of the file
+            return FileChunk(startByte: fileSize, endByte: fileSize, totalFileSize: fileSize, chunkData: Data(capacity: 0))
         }
 
         let nsData = NSData(data: data)

Sources/MuxUploadSDK/Internal Utilities/Error+InternalErrors.swift Sources/MuxUploadSDK/InternalUtilities/Error+InternalErrors.swift

@@ -43,7 +43,7 @@ struct UploadEvent: Codable {
 
         self.deviceModel = device.model
 
-        self.appName = Bundle.main.appName
+        self.appName = Bundle.main.bundleIdentifier
         self.appVersion = Bundle.main.appVersion
 
         if #available(iOS 16, *) {

Sources/MuxUploadSDK/Internal Utilities/HttpError.swift Sources/MuxUploadSDK/InternalUtilities/HttpError.swift

@@ -0,0 +1,22 @@
+//
+//  MuxErrorCode.swift
+//  
+//
+//  Created by Emily Dixon on 2/27/23.
+//
+
+import Foundation
+
+/// Represents the possible error cases from a ``MuxUpload``
+public enum MuxErrorCase : Int {
+    /// The cause of the error is not known
+    case unknown = -1
+    /// The upload was cancelled
+    case cancelled = 0
+    /// The input file could not be read or processed
+    case file = 1
+    /// The upload could not be completed due to an HTTP error
+    case http = 2
+    /// The upload could not be completed due to a connection error
+    case connection = 3
+}

Sources/MuxUploadSDK/Internal Utilities/Reporter.swift Sources/MuxUploadSDK/InternalUtilities/Reporter.swift

@@ -7,13 +7,45 @@
 
 import Foundation
 
-/**
- Uploads a video file to a previously-created Direct Upload. Create instances of this object using ``Builder``
+///
+/// Uploads a video file to a previously-created Mux Video Direct Upload.
+///
+/// This class is part of a full-stack workflow for uploading video files to Mux Video. In order to use this object you must first have
+/// created a [Direct Upload](https://docs.mux.com/guides/video/upload-files-directly) on your server backend.
+/// Then, use the PUT URL created there to upload your video file.
+///
+/// For example:
+/// ```swift
+/// let upload = MuxUpload(
+///   uploadURL: myMuxUploadURL,
+///   videoFileURL: myVideoFileURL,
+/// )
+///
+/// upload.progressHandler = { state in
+///   self.uploadScreenState = .uploading(state)
+/// }
+///
+/// upload.resultHandler = { result in
+///   switch result {
+///     case .success(let success):
+///     self.uploadScreenState = .done(success)
+///     self.upload = nil
+///     NSLog("Upload Success!")
+///     case .failure(let error):
+///     self.uploadScreenState = .failure(error)
+///     NSLog("!! Upload error: \(error.localizedDescription)")
+///   }
+/// }
+///
+/// self.upload = upload
+/// upload.start()
+/// ```
+///
+/// Uploads created by this SDK are globally managed by default, and can be resumed after failures or even after process death. For more information on
+/// this topic, see ``UploadManager``
+///
+public final class MuxUpload : Hashable, Equatable {
 
- TODO: usage here
- */
-public final class MuxUpload {
-    
     private let uploadInfo: UploadInfo
     private let manageBySDK: Bool
     private let id: Int
@@ -26,7 +58,7 @@ public final class MuxUpload {
     /**
      Represents the state of an upload in progress.
      */
-    public struct Status : Sendable {
+    public struct Status : Sendable, Hashable {
         public let progress: Progress?
         public let updatedTime: TimeInterval
         public let startTime: TimeInterval
@@ -50,21 +82,25 @@ public final class MuxUpload {
 
     }
 
+    /// Creates a new `MuxUpload` with the given confguration
+    /// - Parameters
+    ///   - uploadURL: the PUT URL for your direct upload
+    ///   - videoFileURL: A URL to the input video file
+    ///   - retriesPerChunk: The number of times each chunk of the file upload can be retried before failure is declared
+    ///   - optOutOfEventTracking: This SDK collects performance and reliability data that helps make the Upload SDK the best it can be. If you do not wish to share this information with Mux, you may pass `true` for this parameter
     public convenience init(
         uploadURL: URL,
         videoFileURL: URL,
-        videoMIMEType: String = "video/*", // TODO: We can guess this, so make it optional,
-        chunkSize: Int = 8 * 1024 * 1024, // Google recommends *at least* 8M,
+        chunkSize: Int = 8 * 1024 * 1024, // Google recommends at least 8M
         retriesPerChunk: Int = 3,
-        retryBaseTimeInterval: TimeInterval = 0.5
+        optOutOfEventTracking: Bool = false
     ) {
         let uploadInfo = UploadInfo(
             uploadURL: uploadURL,
             videoFile: videoFileURL,
-            videoMIMEType: videoMIMEType,
             chunkSize: chunkSize,
             retriesPerChunk: retriesPerChunk,
-            retryBaseTime: retryBaseTimeInterval
+            optOutOfEventTracking: optOutOfEventTracking
         )
 
         self.init(
@@ -84,7 +120,7 @@ public final class MuxUpload {
      */
     public var progressHandler: StateHandler?
 
-    public struct Success : Sendable {
+    public struct Success : Sendable, Hashable {
         public let finalState: Status
     }
 
@@ -107,7 +143,12 @@ public final class MuxUpload {
     /**
      True if this upload is currently in progress and not paused
      */
-    var inProgress: Bool { get { fileWorker != nil } }
+    public var inProgress: Bool { get { fileWorker != nil && !complete } }
+    
+    /**
+     True if this upload was completed
+     */
+    public var complete: Bool { get { lastSeenStatus.progress?.completedUnitCount ?? 0 > 0 && lastSeenStatus.progress?.fractionCompleted ?? 0 >= 1.0 } }
 
     /**
     URL to the file that will be uploaded
@@ -118,30 +159,38 @@ public final class MuxUpload {
      The remote endpoint that this object uploads to
      */
     public var uploadURL: URL { get { return uploadInfo.uploadURL } }
-    // TODO: Computed Properties for some other UploadInfo properties
 
     /**
      Begins the upload. You can control what happens when the upload is already started. If `forceRestart` is true, the upload will be restarted. Otherwise, nothing will happen. The default is not to restart
      */
     public func start(forceRestart: Bool = false) {
-        if self.manageBySDK {
+        // Use an existing globally-managed upload if desired & one exists
+        if self.manageBySDK && fileWorker == nil {
             // See if there's anything in progress already
-            fileWorker = UploadManager.shared.findUploaderFor(videoFile: videoFile)
+            fileWorker = uploadManager.findUploaderFor(videoFile: videoFile)
         }
-        guard !forceRestart && fileWorker == nil else {
-            MuxUploadSDK.logger?.warning("start() called but upload is in progress")
+        if fileWorker != nil && !forceRestart {
+            MuxUploadSDK.logger?.warning("start() called but upload is already in progress")
+            fileWorker?.addDelegate(
+                withToken: id,
+                InternalUploaderDelegate { [weak self] state in self?.handleStateUpdate(state) }
+            )
+            fileWorker?.start()
             return
         }
+        
+        // Start a new upload
         if forceRestart {
-            fileWorker?.cancel()
+            cancel()
         }
         let completedUnitCount = UInt64({ self.lastSeenStatus.progress?.completedUnitCount ?? 0 }())
         let fileWorker = ChunkedFileUploader(uploadInfo: uploadInfo, startingAtByte: completedUnitCount)
         fileWorker.addDelegate(
             withToken: id,
-            InternalUploaderDelegate { [weak self] state in self?.handleStateUpdate(state) }
+            InternalUploaderDelegate { [self] state in handleStateUpdate(state) }
         )
         fileWorker.start()
+        uploadManager.registerUploader(fileWorker, withId: id)
         self.fileWorker = fileWorker
     }
 
@@ -156,11 +205,11 @@ public final class MuxUpload {
     }
 
     /**
-     Cancels an ongoing download. Temp files will be deleted asynchronously. State and Delegates will be cleared. Your delegates will recieve no further calls
+     Cancels an ongoing download. State and Delegates will be cleared. Your delegates will recieve no further calls
      */
     public func cancel() {
         fileWorker?.cancel()
-        UploadManager.shared.acknowledgeUpload(ofFile: videoFile)
+        uploadManager.acknowledgeUpload(ofFile: videoFile)
 
         lastSeenStatus = Status(progress: nil, updatedTime: 0, startTime: 0, isPaused: true)
         progressHandler = nil
@@ -174,6 +223,7 @@ public final class MuxUpload {
                 let finalStatus = Status(progress: result.finalProgress, updatedTime: result.finishTime, startTime: result.startTime, isPaused: false)
                 notifySuccess(Result<Success, UploadError>.success(Success(finalState: finalStatus)))
             }
+            fileWorker?.removeDelegate(withToken: id)
             fileWorker = nil
         }
         case .failure(let error): do {
@@ -192,6 +242,7 @@ public final class MuxUpload {
                     notifyFailure(Result.failure(parsedError))
                 }
             }
+            fileWorker?.removeDelegate(withToken: id)
             fileWorker = nil
         }
         case .uploading(let update): do {
@@ -209,6 +260,19 @@ public final class MuxUpload {
         }
     }
 
+    /// Two`MuxUpload`s with the same ``MuxUpload/videoFile`` and ``MuxUpload/uploadURL`` are considered equivalent
+    public static func == (lhs: MuxUpload, rhs: MuxUpload) -> Bool {
+        lhs.videoFile == rhs.videoFile
+        && lhs.uploadURL == rhs.uploadURL
+    }
+    
+    /// This object's hash is computed based on its ``MuxUpload/videoFile`` and its ``MuxUpload/uploadURL``
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(videoFile)
+        hasher.combine(uploadURL)
+    }
+   
+    
     private init (uploadInfo: UploadInfo, manage: Bool = true, uploadManager: UploadManager) {
         self.uploadInfo = uploadInfo
         self.manageBySDK = manage
@@ -222,7 +286,7 @@ public final class MuxUpload {
 
         handleStateUpdate(uploader.currentState)
         uploader.addDelegate(
-            withToken: id,
+            withToken: self.id,
             InternalUploaderDelegate { [weak self] state in self?.handleStateUpdate(state) }
         )
     }

Sources/MuxUploadSDK/Internal Utilities/UploadEvent.swift Sources/MuxUploadSDK/InternalUtilities/UploadEvent.swift

@@ -9,19 +9,24 @@ import Foundation
 import OSLog
 
 ///
-/// Exposes SDK metadata. Has some extensions that hide global data
+/// Metadata and logging for this SDK
 ///
 public enum MuxUploadSDK {
 }
 
 public extension MuxUploadSDK {
+    
+    /// The `Logger` being used to log events from this SDK
     static var logger: Logger? = nil
 
+    /// Enables logging by adding a `Logger` with `subsystem: "Mux"` and `category: "Upload"`
     static func enableDefaultLogging() {
         logger = Logger(subsystem: "Mux", category: "MuxUpload")
     }
 
+    /// Uses the specified `Logger` to log events from this SDK
     static func useLogger(logger: Logger) {
         self.logger = logger
     }
+
 }