feat: Expose Foundation Measurement API for chunk size (#94)

* Minor inline API doc tweaks

Author: andrewjl-mux

Sources/MuxUploadSDK/PublicAPI/Options/DirectUploadOptions.swift

@@ -11,8 +11,9 @@ public struct DirectUploadOptions {
 
     // MARK: - Transport Options
 
-    /// Options to adjust ``DirectUpload`` chunk transport
-    /// over the network.
+    /// Options for tuning network transport of direct upload
+    /// chunks to Mux. Using the ``default`` is recommended
+    /// for most applications.
     public struct Transport {
 
         /// The size of each file chunk in bytes sent by the
@@ -33,15 +34,35 @@ public struct DirectUploadOptions {
             )
         }
 
-        /// Initializes options for upload chunk transport
+        /// Initializes options for transport of upload chunks
+        /// over the network
+        /// - Parameters:
+        ///     - chunkSize: the size of each file chunk sent
+        ///     by the SDK during an upload.
+        ///     Defaults to 8MB.
+        ///     - retryLimitPerChunk: number of times a failed
+        ///     chunk request is retried. Default limit is
+        ///     3 retries.
+        public init(
+            chunkSize: Measurement<UnitInformationStorage> = .defaultDirectUploadChunkSize,
+            retryLimitPerChunk: Int = 3
+        ) {
+            self.chunkSizeInBytes = Int(
+                abs(chunkSize.converted(to: .bytes).value)
+                    .rounded(.down)
+            )
+            self.retryLimitPerChunk = retryLimitPerChunk
+        }
+
+        /// Initializes options for transport of upload chunks
         /// over the network
-        ///
         /// - Parameters:
-        ///     - chunkSizeInBytes: the size of each file chunk in
-        ///     bytes the SDK sends when uploading, default
-        ///     value is 8MB
-        ///     - retryLimitPerChunk: number of retry attempts
-        ///     if the chunk request fails, default value is 3
+        ///     - chunkSizeInBytes: the size of each file
+        ///     chunk in bytes the SDK uploads in a single
+        ///     request. Default chunk size is 8MB.
+        ///     - retryLimitPerChunk: number of times a failed
+        ///     chunk request is retried. Default limit is
+        ///     3 retries.
         public init(
             chunkSizeInBytes: Int = 8 * 1024 * 1024,
             retryLimitPerChunk: Int = 3
@@ -51,7 +72,7 @@ public struct DirectUploadOptions {
         }
     }
 
-    /// Transport options for the direct upload
+    /// Network transport options for direct upload chunks
     public var transport: Transport
 
     // MARK: - Input Standardization Options
@@ -190,12 +211,14 @@ public struct DirectUploadOptions {
 
     // MARK: Direct Upload Options Initializers
 
+    /// Initializes options that dictate how the direct upload
+    /// is carried out by the SDK
     /// - Parameters:
-    ///     - inputStandardization: options to enable or
-    ///     disable standardizing the format of the direct
-    ///     upload inputs, it is requested by default. To
-    ///     prevent the SDK from making any changes to the
-    ///     format of the input use ``DirectUploadOptions.InputStandardization.skipped``
+    ///     - inputStandardization: options related to input
+    ///     standardization. Input standardization is requested
+    ///     by default.
+    ///     To skip input standardization pass in
+    ///     ``DirectUploadOptions.InputStandardization.skipped``.
     ///     - transport: options for transporting the
     ///     direct upload input to Mux
     ///     - eventTracking: event tracking options for the
@@ -210,26 +233,49 @@ public struct DirectUploadOptions {
         self.eventTracking = eventTracking
     }
 
+    /// Initializes options that dictate how the direct upload
+    /// is carried out by the SDK
     /// - Parameters:
     ///     - eventTracking: event tracking options for the
     ///     direct upload
-    ///     - inputStandardization: options to enable or
-    ///     disable standardizing the format of the direct
-    ///     upload inputs, it is requested by default. To
-    ///     prevent the SDK from making any changes to the
+    ///     - inputStandardization: options related to input
+    ///     standardization. Input standardization is requested
+    ///     by default.
+    ///     To skip input standardization pass in
+    ///     ``DirectUploadOptions.InputStandardization.skipped``.
+    ///     - chunkSize: The size of each file chunk sent by
+    ///     the SDK during an upload. Defaults to 8MB.
+    ///     - retryLimitPerChunk: number of retry attempts
+    ///     if the chunk request fails. Defaults to 3.
+    public init(
+        eventTracking: EventTracking = .default,
+        inputStandardization: InputStandardization = .default,
+        chunkSize: Measurement<UnitInformationStorage> = .defaultDirectUploadChunkSize,
+        retryLimitPerChunk: Int = 3
+    ) {
+        self.eventTracking = eventTracking
+        self.inputStandardization = inputStandardization
+        self.transport = Transport(
+            chunkSize: chunkSize,
+            retryLimitPerChunk: retryLimitPerChunk
+        )
+    }
+
+    /// Initializes options that dictate how the direct upload
+    /// is carried out by the SDK
     /// - Parameters:
     ///     - eventTracking: event tracking options for the
     ///     direct upload
-    ///     - inputStandardization: options to enable or
-    ///     disable standardizing the format of the direct
-    ///     upload inputs. True by default.
-    ///     To prevent the SDK from making any changes to the
-    ///     format of the input use ``DirectUploadOptions.InputStandardization.skipped``
+    ///     - inputStandardization: options related to input
+    ///     standardization. Input standardization is requested
+    ///     by default.
+    ///     To skip input standardization pass in
+    ///     ``DirectUploadOptions.InputStandardization.skipped``.
     ///     - chunkSizeInBytes: The size of each file chunk
     ///     in bytes sent by the SDK during an upload.
     ///     Defaults to 8MB.
     ///     - retryLimitPerChunk: number of retry attempts
-    ///     if the chunk request fails, default value is 3
+    ///     if the chunk request fails. Defaults to 3.
     public init(
         eventTracking: EventTracking = .default,
         inputStandardization: InputStandardization = .default,
@@ -248,6 +294,16 @@ public struct DirectUploadOptions {
 
 // MARK: - Extensions
 
+extension Measurement where UnitType == UnitInformationStorage {
+    /// Default direct upload chunk size
+    public static var defaultDirectUploadChunkSize: Self {
+        Measurement(
+            value: 8,
+            unit: .megabytes
+        )
+    }
+}
+
 extension DirectUploadOptions.InputStandardization.MaximumResolution: CustomStringConvertible {
     public var description: String {
         switch self {