Unified CDN & Media Loading Architecture (v5)

Sources/StreamChat/APIClient/APIClient.swift

@@ -23,12 +23,9 @@ class APIClient: @unchecked Sendable {
 
     /// The attachment downloader.
     let attachmentDownloader: AttachmentDownloader
-
-    /// The attachment uploader.
-    let attachmentUploader: AttachmentUploader
 
-    /// The CDN Client to store and delete attachments.
-    let cdnClient: CDNClient
+    /// The CDN uploader for storing and deleting attachments.
+    let cdnUploader: CDNUploader
 
     /// Queue in charge of handling incoming requests
     private let operationQueue: OperationQueue = {
@@ -66,15 +63,13 @@ class APIClient: @unchecked Sendable {
         requestEncoder: RequestEncoder,
         requestDecoder: RequestDecoder,
         attachmentDownloader: AttachmentDownloader,
-        attachmentUploader: AttachmentUploader,
-        cdnClient: CDNClient
+        cdnUploader: CDNUploader
     ) {
         encoder = requestEncoder
         decoder = requestDecoder
         session = URLSession(configuration: sessionConfiguration)
         self.attachmentDownloader = attachmentDownloader
-        self.attachmentUploader = attachmentUploader
-        self.cdnClient = cdnClient
+        self.cdnUploader = cdnUploader
     }
 
     /// Performs a network request and retries in case of network failures
@@ -323,18 +318,24 @@ class APIClient: @unchecked Sendable {
         completion: @escaping @Sendable (Result<UploadedAttachment, Error>) -> Void
     ) {
         let uploadOperation = AsyncOperation(maxRetries: maximumRequestRetries) { [weak self] operation, done in
-            self?.attachmentUploader.upload(attachment, progress: progress) { [weak self] result in
-                switch result {
+            self?.cdnUploader.uploadAttachment(attachment, progress: progress) { [weak self] result in
+                let mappedResult = result.map { file in
+                    UploadedAttachment(
+                        attachment: attachment,
+                        remoteURL: file.fileURL,
+                        thumbnailURL: file.thumbnailURL
+                    )
+                }
+                switch mappedResult {
                 case let .failure(error) where self?.isConnectionError(error) == true:
-                    // Do not retry unless its a connection problem and we still have retries left
                     if operation.canRetry {
                         done(.retry)
                     } else {
-                        completion(result)
+                        completion(mappedResult)
                         done(.continue)
                     }
                 case .success, .failure:
-                    completion(result)
+                    completion(mappedResult)
                     done(.continue)
                 }
             }

Sources/StreamChat/APIClient/CDNClient/CDN.swift

@@ -0,0 +1,64 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+/// A protocol for transforming CDN URLs before loading images and files.
+///
+/// Implement this protocol to add signing, authentication headers,
+/// resize query parameters, or to rewrite the CDN host.
+///
+/// All methods use completion handlers to support asynchronous operations
+/// such as fetching pre-signed URLs from a server.
+public protocol CDN: Sendable {
+    /// Transforms an image URL for loading.
+    ///
+    /// Called before every image load. Use this to add signing,
+    /// auth headers, resize query params, or rewrite the host.
+    ///
+    /// - Parameters:
+    ///   - url: The original image URL.
+    ///   - resize: Optional resize parameters for server-side resizing.
+    ///   - completion: A completion handler with the transformed request.
+    func imageRequest(
+        for url: URL,
+        resize: ImageResize?,
+        completion: @escaping (Result<CDNRequest, Error>) -> Void
+    )
+
+    /// Transforms a file or video URL for loading or playback.
+    ///
+    /// Called before loading non-image media. Use this to add signing
+    /// or auth headers for file and video access.
+    ///
+    /// - Parameters:
+    ///   - url: The original file/video URL.
+    ///   - completion: A completion handler with the transformed request.
+    func fileRequest(
+        for url: URL,
+        completion: @escaping (Result<CDNRequest, Error>) -> Void
+    )
+}
+
+// MARK: - Async/Await Extensions
+
+extension CDN {
+    /// Transforms an image URL for loading.
+    public func imageRequest(for url: URL, resize: ImageResize? = nil) async throws -> CDNRequest {
+        try await withCheckedThrowingContinuation { continuation in
+            imageRequest(for: url, resize: resize) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+
+    /// Transforms a file or video URL for loading or playback.
+    public func fileRequest(for url: URL) async throws -> CDNRequest {
+        try await withCheckedThrowingContinuation { continuation in
+            fileRequest(for: url) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
+}

Sources/StreamChat/APIClient/CDNClient/CDNClient.swift

@@ -15,78 +15,13 @@ public struct UploadedFile: Decodable {
     }
 }
 
-/// The CDN client is responsible to upload files to a CDN.
-public protocol CDNClient: Sendable {
-    static var maxAttachmentSize: Int64 { get }
-
-    /// Uploads attachment as a multipart/form-data and returns only the uploaded remote file.
-    /// - Parameters:
-    ///   - attachment: An attachment to upload.
-    ///   - progress: A closure that broadcasts upload progress.
-    ///   - completion: Returns the uploaded file's information.
-    func uploadAttachment(
-        _ attachment: AnyChatMessageAttachment,
-        progress: (@Sendable (Double) -> Void)?,
-        completion: @escaping @Sendable (Result<URL, Error>) -> Void
-    )
-
-    /// Uploads attachment as a multipart/form-data and returns the uploaded remote file and its thumbnail.
-    /// - Parameters:
-    ///   - attachment: An attachment to upload.
-    ///   - progress: A closure that broadcasts upload progress.
-    ///   - completion: Returns the uploaded file's information.
-    func uploadAttachment(
-        _ attachment: AnyChatMessageAttachment,
-        progress: (@Sendable (Double) -> Void)?,
-        completion: @escaping @Sendable (Result<UploadedFile, Error>) -> Void
-    )
-
-    /// Uploads standalone attachment as a multipart/form-data and returns the uploaded remote file and its thumbnail.
-    /// - Parameters:
-    ///   - attachment: An attachment to upload.
-    ///   - progress: A closure that broadcasts upload progress.
-    ///   - completion: Returns the uploaded file's information.
-    func uploadStandaloneAttachment<Payload>(
-        _ attachment: StreamAttachment<Payload>,
-        progress: (@Sendable (Double) -> Void)?,
-        completion: @escaping @Sendable (Result<UploadedFile, Error>) -> Void
-    )
-
-    /// Deletes the attachment from the CDN, given the remote URL.
-    /// - Parameters:
-    ///   - remoteUrl: The remote url of the attachment.
-    ///   - completion: Returns an error in case the delete operation fails.
-    func deleteAttachment(
-        remoteUrl: URL,
-        completion: @escaping @Sendable (Error?) -> Void
-    )
-}
-
-public extension CDNClient {
-    func uploadAttachment(
-        _ attachment: AnyChatMessageAttachment,
-        progress: (@Sendable (Double) -> Void)?,
-        completion: @escaping @Sendable (Result<UploadedFile, Error>) -> Void
-    ) {
-        uploadAttachment(attachment, progress: progress, completion: { (result: Result<URL, Error>) in
-            switch result {
-            case let .success(url):
-                completion(.success(UploadedFile(fileURL: url, thumbnailURL: nil)))
-            case let .failure(error):
-                completion(.failure(error))
-            }
-        })
-    }
-}
-
-/// Default implementation of CDNClient that uses Stream CDN
-final class StreamCDNClient: CDNClient, @unchecked Sendable {
+/// Default implementation of CDNUploader that uses Stream's API.
+final class StreamCDNUploader: CDNUploader, @unchecked Sendable {
     static var maxAttachmentSize: Int64 { 100 * 1024 * 1024 }
 
     private let decoder: RequestDecoder
     private let encoder: RequestEncoder
     private let session: URLSession
-    /// Keeps track of uploading tasks progress
     @Atomic private var taskProgressObservers: [Int: NSKeyValueObservation] = [:]
 
     init(
@@ -99,21 +34,6 @@ final class StreamCDNClient: CDNClient, @unchecked Sendable {
         self.decoder = decoder
     }
 
-    func uploadAttachment(
-        _ attachment: AnyChatMessageAttachment,
-        progress: (@Sendable (Double) -> Void)? = nil,
-        completion: @escaping @Sendable (Result<URL, Error>) -> Void
-    ) {
-        uploadAttachment(attachment, progress: progress, completion: { (result: Result<UploadedFile, Error>) in
-            switch result {
-            case let .success(file):
-                completion(.success(file.fileURL))
-            case let .failure(error):
-                completion(.failure(error))
-            }
-        })
-    }
-
     func uploadAttachment(
         _ attachment: AnyChatMessageAttachment,
         progress: (@Sendable (Double) -> Void)? = nil,
@@ -125,7 +45,7 @@ final class StreamCDNClient: CDNClient, @unchecked Sendable {
             return completion(.failure(ClientError.AttachmentUploading(id: attachment.id)))
         }
         let endpoint = Endpoint<FileUploadPayload>.uploadAttachment(with: attachment.id.cid, type: attachment.type)
-        
+
         uploadAttachment(
             endpoint: endpoint,
             fileData: fileData,
@@ -134,20 +54,31 @@ final class StreamCDNClient: CDNClient, @unchecked Sendable {
             completion: completion
         )
     }
-    
-    func uploadStandaloneAttachment<Payload>(
-        _ attachment: StreamAttachment<Payload>,
+
+    func uploadAttachment(
+        localUrl: URL,
         progress: (@Sendable (Double) -> Void)? = nil,
         completion: @escaping @Sendable (Result<UploadedFile, Error>) -> Void
     ) {
-        guard
-            let uploadingState = attachment.uploadingState,
-            let fileData = try? Data(contentsOf: uploadingState.localFileURL) else {
+        let uploadingState: AttachmentUploadingState
+        do {
+            uploadingState = AttachmentUploadingState(
+                localFileURL: localUrl,
+                state: .pendingUpload,
+                file: try .init(url: localUrl)
+            )
+        } catch {
+            completion(.failure(error))
+            return
+        }
+
+        guard let fileData = try? Data(contentsOf: localUrl) else {
             return completion(.failure(ClientError.Unknown()))
         }
 
-        let endpoint = Endpoint<FileUploadPayload>.uploadAttachment(type: attachment.type)
-
+        let isImage = uploadingState.file.type.isImage
+        let endpoint = Endpoint<FileUploadPayload>.uploadAttachment(type: isImage ? .image : .file)
+
         uploadAttachment(
             endpoint: endpoint,
             fileData: fileData,
@@ -196,7 +127,6 @@ final class StreamCDNClient: CDNClient, @unchecked Sendable {
         progress: (@Sendable (Double) -> Void)? = nil,
         completion: @escaping @Sendable (Result<UploadedFile, Error>) -> Void
     ) {
-        // Encode locally stored attachment into multipart form data
         let multipartFormData = MultipartFormData(
             fileData,
             fileName: uploadingState.localFileURL.lastPathComponent,

Sources/StreamChat/APIClient/CDNClient/CDNRequest.swift

@@ -0,0 +1,22 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+/// The result of a CDN URL transformation, containing the final URL,
+/// optional HTTP headers, and an optional caching key.
+public struct CDNRequest: Sendable {
+    /// The (potentially rewritten/signed) URL to load.
+    public var url: URL
+    /// Optional HTTP headers to include in the load request.
+    public var headers: [String: String]?
+    /// Optional caching key. If nil, the loader defaults to using the URL string.
+    public var cachingKey: String?
+
+    public init(url: URL, headers: [String: String]? = nil, cachingKey: String? = nil) {
+        self.url = url
+        self.headers = headers
+        self.cachingKey = cachingKey
+    }
+}