Add a convenience method for encrypting a stream (#207)

feat(crypto-module): add a convenience `encryptStream(from:)` method in CryptoModule

Author: jguz-pubnub

.pubnub.yml

@@ -1,9 +1,14 @@
 ---
 name: swift
 scm: github.com/pubnub/swift
-version: "9.1.0"
+version: "9.2.0"
 schema: 1
 changelog:
+  - date: 2025-05-15
+    version: 9.2.0
+    changes:
+      - type: feature
+        text: "The `encryptStream(from:)` convenience method is designed to encrypt a local file. It eliminates the need for the caller to provide an `InputStream` and its content length - these are handled internally. You only need to pass a local file URL."
   - date: 2025-05-13
     version: 9.1.0
     changes:
@@ -683,7 +688,7 @@ sdks:
           - distribution-type: source
             distribution-repository: GitHub release
             package-name: PubNub
-            location: https://github.com/pubnub/swift/archive/refs/tags/9.1.0.zip
+            location: https://github.com/pubnub/swift/archive/refs/tags/9.2.0.zip
             supported-platforms:
               supported-operating-systems:
                 macOS:

PubNub.xcodeproj/project.pbxproj

@@ -4011,7 +4011,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4062,7 +4062,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4170,7 +4170,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4223,7 +4223,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4344,7 +4344,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4396,7 +4396,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4876,7 +4876,7 @@
 					"$(TOOLCHAIN_DIR)/usr/lib/swift/macosx",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu17 gnu++14";
 				OTHER_CFLAGS = "$(inherited)";
 				OTHER_LDFLAGS = "$(inherited)";
@@ -4919,7 +4919,7 @@
 					"$(TOOLCHAIN_DIR)/usr/lib/swift/macosx",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.1.0;
+				MARKETING_VERSION = 9.2.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu17 gnu++14";
 				OTHER_CFLAGS = "$(inherited)";
 				OTHER_LDFLAGS = "$(inherited)";

PubNubSwift.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name     = 'PubNubSwift'
-  s.version  = '9.1.0'
+  s.version  = '9.2.0'
   s.homepage = 'https://github.com/pubnub/swift'
   s.documentation_url = 'https://www.pubnub.com/docs/swift-native/pubnub-swift-sdk'
   s.authors = { 'PubNub, Inc.' => '[email protected]' }

Sources/PubNub/Helpers/Constants.swift

@@ -57,7 +57,7 @@ public enum Constant {
 
   static let pubnubSwiftSDKName: String = "PubNubSwift"
 
-  static let pubnubSwiftSDKVersion: String = "9.1.0"
+  static let pubnubSwiftSDKVersion: String = "9.2.0"
 
   static let appBundleId: String = {
     if let info = Bundle.main.infoDictionary,

Sources/PubNub/Helpers/Crypto/CryptoModule.swift

@@ -207,6 +207,45 @@ public struct CryptoModule {
     }
   }
 
+  /// Encrypts the given local file URL and returns the result as an `EncryptedStreamResult`
+  ///
+  /// - Parameters:
+  ///   - from: The local file URL of the stream to encrypt
+  /// - Returns:
+  ///   - **Success**: An `EncryptedStreamResult` containing the encrypted input stream and its total content length
+  ///   - **Failure**: `PubNubError` describing the reason of failure
+  public func encryptStream(from localFileURL: URL) -> Result<EncryptedStreamResult, PubNubError> {
+    guard let inputStream = InputStream(url: localFileURL) else {
+      PubNub.log.debug(
+        "Cannot create InputStream from \(localFileURL). Ensure that the file exists at the specified path",
+        category: .crypto
+      )
+      return .failure(PubNubError(
+        .fileMissingAtPath,
+        additional: ["Cannot create InputStream from \(localFileURL)"]
+      ))
+    }
+
+    let streamEncryptionResult = performStreamEncryption(
+      stream: inputStream,
+      contentLength: localFileURL.sizeOf
+    )
+
+    switch streamEncryptionResult {
+    case .success:
+      PubNub.log.debug("File encrypted successfully")
+    case let .failure(error):
+      PubNub.log.debug("Encryption of file failed due to \(error)")
+    }
+
+    return streamEncryptionResult.map {
+      EncryptedStreamResult(
+        stream: $0,
+        contentLength: $0.length
+      )
+    }
+  }
+
   private func performStreamEncryption(stream: InputStream, contentLength: Int) -> Result<MultipartInputStream, PubNubError> {
     guard contentLength > 0 else {
       return .failure(PubNubError(
@@ -275,35 +314,35 @@ public struct CryptoModule {
     return streamDecryptionResult
   }
 
-  /// Decrypts the stream from the given URL and writes it to the output path
+  /// Decrypts the stream from the given local file URL and writes it to the output path
   ///
   /// - Parameters:
-  ///   - url: URL of the encrypted stream
-  ///   - outputPath: Path to write the decrypted stream
+  ///   - from: The local file URL of the encrypted stream
+  ///   - to: The path to write the decrypted stream
   /// - Returns:
   ///  - **Success**: A decrypted `InputStream` object
   ///  - **Failure**: `PubNubError` describing the reason of failure
   @discardableResult
-  public func decryptStream(from url: URL, to outputPath: URL) -> Result<InputStream, PubNubError> {
+  public func decryptStream(from localFileURL: URL, to outputPath: URL) -> Result<InputStream, PubNubError> {
     PubNub.log.debug(
       "Decrypting file",
       category: .crypto
     )
 
-    guard let inputStream = InputStream(url: url) else {
+    guard let inputStream = InputStream(url: localFileURL) else {
       PubNub.log.debug(
-        "Cannot create InputStream from \(url). Ensure that the file exists at the specified path",
+        "Cannot create InputStream from \(localFileURL). Ensure that the file exists at the specified path",
         category: .crypto
       )
       return .failure(PubNubError(
         .decryptionFailure,
-        additional: ["File doesn't exist at \(url) path"]
+        additional: ["File doesn't exist at \(localFileURL) path"]
       ))
     }
 
     let streamDecryptionResult = performStreamDecryption(
       stream: inputStream,
-      contentLength: url.sizeOf,
+      contentLength: localFileURL.sizeOf,
       to: outputPath
     )
 
@@ -317,8 +356,7 @@ public struct CryptoModule {
     return streamDecryptionResult
   }
 
-  @discardableResult
-  public func performStreamDecryption(
+  private func performStreamDecryption(
     stream: InputStream,
     contentLength: Int,
     to outputPath: URL

Sources/PubNub/Networking/HTTPFileTask.swift

@@ -242,16 +242,14 @@ public class HTTPFileDownloadTask: HTTPFileTask {
 
   func decrypt(_ encryptedURL: URL, to outpuURL: URL, using cryptoModule: CryptoModule) throws {
     // If we were provided a Crypto object we should try and decrypt the file
-
     guard let inputStream = InputStream(url: encryptedURL) else {
       throw PubNubError(.streamCouldNotBeInitialized, additional: [encryptedURL.absoluteString])
     }
-
-    cryptoModule.decrypt(
+    _ = try cryptoModule.decrypt(
       stream: inputStream,
       contentLength: encryptedURL.sizeOf,
       to: outpuURL
-    )
+    ).get()
   }
 
   open func temporaryURL() -> URL {
@@ -314,12 +312,11 @@ public class HTTPFileDownloadTask: HTTPFileTask {
         guard let stream = InputStream(url: url) else {
           throw PubNubError(.streamCouldNotBeInitialized, additional: [url.absoluteString])
         }
-
-        cryptoModule.decrypt(
+        _ = try cryptoModule.decrypt(
           stream: stream,
           contentLength: url.sizeOf,
           to: destinationURL
-        )
+        ).get()
       } else {
         try fileManager.moveItem(at: url, to: destinationURL)
       }