Make CDNRequester a constructor dependency of StreamMediaLoader (#4070)

* Make CDNRequester a constructor dependency of StreamMediaLoader

Instead of passing CDNRequester through ImageLoadOptions / VideoLoadOptions
on every call, it is now provided once via StreamMediaLoader's init.

- Add resolveFileURL to MediaLoader protocol for CDN URL resolution
- Deprecate cdnRequester on Components (UIKit) and ImageLoadOptions/VideoLoadOptions
- Update all call sites to use simplified option constructors
- Add deprecated shims for backward compatibility

* Enrich MediaLoaderImage and DownloadedImage with animated image data

Add isAnimated and animatedImageData fields so that callers like
StreamAsyncImage can get GIF metadata through MediaLoader instead of
bypassing it with a parallel Nuke pipeline.

* Add cachingKey to MediaLoaderImage for sync cache lookups

StreamMediaLoader now passes the CDN cachingKey through the result so
UI layers can maintain their own synchronous cache lookup tables without
needing direct access to CDNRequester.

* Rename resolveFileURL to loadFile with options and MediaLoaderFile result

Aligns the file loading API with the rest of MediaLoader:
- loadFile(at:options:completion:) with FileLoadOptions and MediaLoaderFile
- MediaLoaderFile carries the resolved URL and optional headers

* Remove deprecated CDNRequester shims

This is a breaking change: remove all backward-compatibility shims for
the old cdnRequester-in-options pattern. Removed:
- StreamMediaLoader.init(downloader:)
- ImageLoadOptions.init(resize:cdnRequester:)
- VideoLoadOptions.init(cdnRequester:)
- Components.cdnRequester
- ImageLoaderOptions.init(resize:placeholder:cdnRequester:)
- ImageDownloadOptions.init(resize:cdnRequester:)
- MediaLoader+UIKit loadImage(into:from:maxResolutionInPixels:cdnRequester:)

* Replace loadFile with loadFileRequest returning MediaLoaderFileRequest

Replaces the loadFile(at:options:) method with loadFileRequest(for:options:)
that returns a MediaLoaderFileRequest wrapping a URLRequest with CDN-resolved
URL and headers. The download pipeline (AttachmentDownloader, APIClient,
MessageUpdater, Chat, MessageController) now accepts a URLRequest instead of
a separate URL + headers, keeping CDN concerns encapsulated in MediaLoader.

* Only set animatedImageData for GIF images in StreamImageDownloader

* Add convenience MediaLoader extensions that omit options parameter

* Use convenience MediaLoader methods without empty options

* Fix swiftformat

* Update changelog for CDNRequester as StreamMediaLoader dependency

* Remove isAnimated property from DownloadedImage and MediaLoaderImage

* Reorder StreamMediaLoader init: downloader first, cdnRequester second

Author: nuno-vieira

CHANGELOG.md

@@ -3,7 +3,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 # Upcoming
 
+## StreamChatUI
 ### 🔄 Changed
+- `CDNRequester` is now passed in the constructor of `StreamMediaLoader` instead of `Components` [#4070](https://github.com/GetStream/stream-chat-swift/pull/4070)
 
 # [5.0.0](https://github.com/GetStream/stream-chat-swift/releases/tag/5.0.0)
 _April 16, 2026_

DemoApp/Screens/UserProfile/UserProfileViewController.swift

@@ -158,7 +158,7 @@ class UserProfileViewController: UITableViewController, CurrentChatUserControlle
             .loadImage(
                 into: imageView,
                 from: currentUserController.currentUser?.imageURL,
-                with: ImageLoaderOptions(cdnRequester: Components.default.cdnRequester)
+                with: ImageLoaderOptions()
             )
 
         if let typingIndicatorsEnabled = currentUserController.currentUser?.privacySettings.typingIndicators?.enabled {

Examples/MessengerClone/MessengerChatMessageContentView.swift

@@ -125,8 +125,7 @@ final class MessengerChatMessageContentView: ChatMessageContentView {
                 from: imageURL,
                 with: ImageLoaderOptions(
                     resize: .init(components.avatarThumbnailSize),
-                    placeholder: placeholder,
-                    cdnRequester: components.cdnRequester
+                    placeholder: placeholder
                 )
             )
         } else {

Sources/StreamChat/APIClient/APIClient.swift

@@ -288,13 +288,13 @@ class APIClient: @unchecked Sendable {
     }
 
     func downloadFile(
-        from remoteURL: URL,
+        _ request: URLRequest,
         to localURL: URL,
         progress: (@Sendable (Double) -> Void)?,
         completion: @escaping @Sendable (Error?) -> Void
     ) {
         let downloadOperation = AsyncOperation(maxRetries: maximumRequestRetries) { [weak self] operation, done in
-            self?.attachmentDownloader.download(from: remoteURL, to: localURL, progress: progress) { [weak self] error in
+            self?.attachmentDownloader.download(request, to: localURL, progress: progress) { [weak self] error in
                 if let error, self?.isConnectionError(error) == true {
                     // Do not retry unless its a connection problem and we still have retries left
                     if operation.canRetry {

Sources/StreamChat/APIClient/AttachmentDownloader/AttachmentDownloader.swift

@@ -9,12 +9,12 @@ protocol AttachmentDownloader {
     /// Downloads a file attachment to the specified local URL.
     ///
     /// - Parameters:
-    ///   - remoteURL: A remote URL of the file.
+    ///   - request: The URL request for the remote file.
     ///   - localURL: The destination URL of the download.
     ///   - progress: The progress of the download.
     ///   - completion: The callback with an error if a failure occurred.
     func download(
-        from remoteURL: URL,
+        _ request: URLRequest,
         to localURL: URL,
         progress: (@Sendable (Double) -> Void)?,
         completion: @escaping @Sendable (Error?) -> Void
@@ -30,12 +30,11 @@ final class StreamAttachmentDownloader: AttachmentDownloader, @unchecked Sendabl
     }
 
     func download(
-        from remoteURL: URL,
+        _ request: URLRequest,
         to localURL: URL,
         progress: (@Sendable (Double) -> Void)?,
         completion: @escaping @Sendable (Error?) -> Void
     ) {
-        let request = URLRequest(url: remoteURL)
         let task = session.downloadTask(with: request) { temporaryURL, _, downloadError in
             if let downloadError {
                 completion(downloadError)

Sources/StreamChat/Controllers/MessageController/MessageController.swift

@@ -789,17 +789,17 @@ public class ChatMessageController: DataController, DelegateCallable, DataStoreP
     ///
     /// - Parameters:
     ///   - attachment: The attachment to download.
-    ///   - remoteURL: An optional pre-resolved URL to download from (e.g. after CDN signing).
-    ///     If `nil`, the attachment's original `remoteURL` is used.
+    ///   - request: An optional pre-resolved `URLRequest` (e.g. from ``MediaLoader/loadFileRequest(for:options:completion:)``).
+    ///     If `nil`, a default request using the attachment's `remoteURL` is used.
     ///   - completion: A completion block with the attachment containing the downloading state.
     ///
     /// - Note: The local storage URL (`attachment.downloadingState?.localFileURL`) can change between app launches.
     public func downloadAttachment<Payload>(
         _ attachment: ChatMessageAttachment<Payload>,
-        remoteURL: URL? = nil,
+        request: URLRequest? = nil,
         completion: @escaping @MainActor (Result<ChatMessageAttachment<Payload>, Error>) -> Void
     ) where Payload: DownloadableAttachmentPayload {
-        messageUpdater.downloadAttachment(attachment, remoteURL: remoteURL) { [weak self] result in
+        messageUpdater.downloadAttachment(attachment, request: request) { [weak self] result in
             self?.callback {
                 completion(result)
             }

Sources/StreamChat/StateLayer/Chat.swift

@@ -430,18 +430,18 @@ public class Chat: @unchecked Sendable {
     ///
     /// - Parameters:
     ///   - attachment: The attachment to download.
-    ///   - remoteURL: An optional pre-resolved URL to download from (e.g. after CDN signing).
-    ///     If `nil`, the attachment's original `remoteURL` is used.
+    ///   - request: An optional pre-resolved `URLRequest` (e.g. from ``MediaLoader/loadFileRequest(for:options:completion:)``).
+    ///     If `nil`, a default request using the attachment's `remoteURL` is used.
     ///
     /// - Note: The local storage URL can change between app launches.
     ///
     /// - Throws: An error while downloading the attachment.
     /// - Returns: An instance of the downloaded attachment which includes the local URL.
     @discardableResult public func downloadAttachment<Payload>(
         _ attachment: ChatMessageAttachment<Payload>,
-        remoteURL: URL? = nil
+        request: URLRequest? = nil
     ) async throws -> ChatMessageAttachment<Payload> where Payload: DownloadableAttachmentPayload {
-        try await messageUpdater.downloadAttachment(attachment, remoteURL: remoteURL)
+        try await messageUpdater.downloadAttachment(attachment, request: request)
     }
 
     /// Deletes the locally downloaded file.

Sources/StreamChat/Workers/MessageUpdater.swift

@@ -761,13 +761,14 @@ class MessageUpdater: Worker, @unchecked Sendable {
 
     func downloadAttachment<Payload>(
         _ attachment: ChatMessageAttachment<Payload>,
-        remoteURL: URL? = nil,
+        request: URLRequest? = nil,
         completion: @escaping @Sendable (Result<ChatMessageAttachment<Payload>, Error>) -> Void
     ) where Payload: DownloadableAttachmentPayload {
         let attachmentId = attachment.id
         let localURL = URL.streamAttachmentLocalStorageURL(forRelativePath: attachment.relativeStoragePath)
+        let downloadRequest = request ?? URLRequest(url: attachment.remoteURL)
         apiClient.downloadFile(
-            from: remoteURL ?? attachment.remoteURL,
+            downloadRequest,
             to: localURL,
             progress: { [weak self] progress in
                 self?.updateDownloadProgress(
@@ -1270,10 +1271,10 @@ extension MessageUpdater {
 
     func downloadAttachment<Payload>(
         _ attachment: ChatMessageAttachment<Payload>,
-        remoteURL: URL? = nil
+        request: URLRequest? = nil
     ) async throws -> ChatMessageAttachment<Payload> where Payload: DownloadableAttachmentPayload {
         try await withCheckedThrowingContinuation { continuation in
-            downloadAttachment(attachment, remoteURL: remoteURL) { result in
+            downloadAttachment(attachment, request: request) { result in
                 continuation.resume(with: result)
             }
         }

Sources/StreamChatCommonUI/ImageLoading/ImageDownloading.swift

@@ -51,8 +51,11 @@ public struct ImageDownloadingOptions: Sendable {
 public struct DownloadedImage: Sendable {
     /// The downloaded image.
     public var image: UIImage
+    /// The raw image data for animated rendering. `nil` for static images.
+    public var animatedImageData: Data?
 
-    public init(image: UIImage) {
+    public init(image: UIImage, animatedImageData: Data? = nil) {
         self.image = image
+        self.animatedImageData = animatedImageData
     }
 }

Sources/StreamChatCommonUI/ImageLoading/MediaLoader.swift

@@ -6,20 +6,20 @@ import AVKit
 import StreamChat
 import UIKit
 
-/// A unified protocol for loading images and video previews.
+/// A unified protocol for loading images, video previews, and resolving file URLs.
 ///
-/// Configuration is passed via options structs on every call, so concrete
-/// implementations remain stateless with respect to CDN configuration.
-/// Changing the requester on `ChatClientConfig` takes effect immediately without
-/// recreating the loader.
+/// The ``CDNRequester`` is provided as a constructor dependency of the concrete
+/// implementation (e.g. ``StreamMediaLoader``), so callers don't need to pass
+/// it on every call. Configuring the CDN requester in one place ensures all
+/// content loading automatically picks it up.
 public protocol MediaLoader: AnyObject, Sendable {
     // MARK: - Image Loading
 
     /// Loads a single image from the given URL.
     ///
     /// - Parameters:
     ///   - url: The image URL. If nil, the completion is called with a failure.
-    ///   - options: Options controlling resize and CDN behavior.
+    ///   - options: Options controlling resize behavior.
     ///   - completion: A completion handler called on the main actor with the loaded image.
     func loadImage(
         url: URL?,
@@ -31,8 +31,8 @@ public protocol MediaLoader: AnyObject, Sendable {
 
     /// Returns a video asset for the given URL.
     ///
-    /// Implementers should use the CDN requester in options to adjust the URL
-    /// before creating the asset.
+    /// The implementation resolves the URL through its CDN requester before
+    /// creating the asset.
     func loadVideoAsset(
         at url: URL,
         options: VideoLoadOptions,
@@ -47,7 +47,7 @@ public protocol MediaLoader: AnyObject, Sendable {
     ///
     /// - Parameters:
     ///   - attachment: A video attachment containing the video URL and optional thumbnail URL.
-    ///   - options: Options controlling CDN behavior.
+    ///   - options: Options controlling video load behavior.
     ///   - completion: A completion handler called on the main actor with the preview image.
     func loadVideoPreview(
         with attachment: ChatMessageVideoAttachment,
@@ -67,22 +67,78 @@ public protocol MediaLoader: AnyObject, Sendable {
     ///
     /// - Parameters:
     ///   - url: The video URL (typically a local `file://` URL).
-    ///   - options: Options controlling CDN behavior.
+    ///   - options: Options controlling video load behavior.
     ///   - completion: A completion handler called on the main actor with the preview image.
     func loadVideoPreview(
         at url: URL,
         options: VideoLoadOptions,
         completion: @escaping @MainActor (Result<MediaLoaderVideoPreview, Error>) -> Void
     )
+
+    // MARK: - File Request
+
+    /// Creates a request for downloading or previewing a file.
+    ///
+    /// Resolves the URL through the CDN (signing, rewriting) and packages the
+    /// result into a ready-to-use request with any required HTTP headers.
+    /// Pass the returned request to `downloadAttachment` or load it in a web view.
+    ///
+    /// - Parameters:
+    ///   - url: The original file URL to resolve.
+    ///   - options: Options controlling file request behavior.
+    ///   - completion: A completion handler called on the main actor with the resolved request.
+    func loadFileRequest(
+        for url: URL,
+        options: DownloadFileRequestOptions,
+        completion: @escaping @MainActor (Result<MediaLoaderFileRequest, Error>) -> Void
+    )
+}
+
+// MARK: - Convenience Extensions
+
+extension MediaLoader {
+    public func loadImage(
+        url: URL?,
+        completion: @escaping @MainActor (Result<MediaLoaderImage, Error>) -> Void
+    ) {
+        loadImage(url: url, options: ImageLoadOptions(), completion: completion)
+    }
+
+    public func loadVideoAsset(
+        at url: URL,
+        completion: @escaping @MainActor (Result<MediaLoaderVideoAsset, Error>) -> Void
+    ) {
+        loadVideoAsset(at: url, options: VideoLoadOptions(), completion: completion)
+    }
+
+    public func loadVideoPreview(
+        with attachment: ChatMessageVideoAttachment,
+        completion: @escaping @MainActor (Result<MediaLoaderVideoPreview, Error>) -> Void
+    ) {
+        loadVideoPreview(with: attachment, options: VideoLoadOptions(), completion: completion)
+    }
+
+    public func loadVideoPreview(
+        at url: URL,
+        completion: @escaping @MainActor (Result<MediaLoaderVideoPreview, Error>) -> Void
+    ) {
+        loadVideoPreview(at: url, options: VideoLoadOptions(), completion: completion)
+    }
+
+    public func loadFileRequest(
+        for url: URL,
+        completion: @escaping @MainActor (Result<MediaLoaderFileRequest, Error>) -> Void
+    ) {
+        loadFileRequest(for: url, options: DownloadFileRequestOptions(), completion: completion)
+    }
 }
 
 // MARK: - Async/Await Extensions
 
 extension MediaLoader {
-    /// Loads a single image from the given URL.
     public func loadImage(
         url: URL?,
-        options: ImageLoadOptions
+        options: ImageLoadOptions = ImageLoadOptions()
     ) async throws -> MediaLoaderImage {
         try await withCheckedThrowingContinuation { continuation in
             loadImage(url: url, options: options) { result in
@@ -91,10 +147,9 @@ extension MediaLoader {
         }
     }
 
-    /// Returns a video asset for the given URL.
     public func loadVideoAsset(
         at url: URL,
-        options: VideoLoadOptions
+        options: VideoLoadOptions = VideoLoadOptions()
     ) async throws -> MediaLoaderVideoAsset {
         try await withCheckedThrowingContinuation { continuation in
             loadVideoAsset(at: url, options: options) { result in
@@ -103,17 +158,27 @@ extension MediaLoader {
         }
     }
 
-    /// Generates a video preview thumbnail from a URL.
     public func loadVideoPreview(
         at url: URL,
-        options: VideoLoadOptions
+        options: VideoLoadOptions = VideoLoadOptions()
     ) async throws -> MediaLoaderVideoPreview {
         try await withCheckedThrowingContinuation { continuation in
             loadVideoPreview(at: url, options: options) { result in
                 continuation.resume(with: result)
             }
         }
     }
+
+    public func loadFileRequest(
+        for url: URL,
+        options: DownloadFileRequestOptions = DownloadFileRequestOptions()
+    ) async throws -> MediaLoaderFileRequest {
+        try await withCheckedThrowingContinuation { continuation in
+            loadFileRequest(for: url, options: options) { result in
+                continuation.resume(with: result)
+            }
+        }
+    }
 }
 
 // MARK: - Options
@@ -122,23 +187,20 @@ extension MediaLoader {
 public struct ImageLoadOptions: Sendable {
     /// Optional resize parameters for server-side resizing.
     public var resize: ImageResize?
-    /// The CDN requester for URL transformation (signing, headers, resizing).
-    public var cdnRequester: CDNRequester
 
-    public init(resize: ImageResize? = nil, cdnRequester: CDNRequester) {
+    public init(resize: ImageResize? = nil) {
         self.resize = resize
-        self.cdnRequester = cdnRequester
     }
 }
 
 /// Options for loading video content through a ``MediaLoader``.
 public struct VideoLoadOptions: Sendable {
-    /// The CDN requester for URL transformation (signing, headers).
-    public var cdnRequester: CDNRequester
+    public init() {}
+}
 
-    public init(cdnRequester: CDNRequester) {
-        self.cdnRequester = cdnRequester
-    }
+/// Options for creating a file download request through a ``MediaLoader``.
+public struct DownloadFileRequestOptions: Sendable {
+    public init() {}
 }
 
 // MARK: - Result Types
@@ -147,9 +209,16 @@ public struct VideoLoadOptions: Sendable {
 public struct MediaLoaderImage: Sendable {
     /// The loaded image.
     public var image: UIImage
+    /// The raw image data for animated rendering. `nil` for static images.
+    public var animatedImageData: Data?
+    /// The caching key used by the CDN requester, if any.
+    /// UI layers can use this to maintain a synchronous cache lookup table.
+    public var cachingKey: String?
 
-    public init(image: UIImage) {
+    public init(image: UIImage, animatedImageData: Data? = nil, cachingKey: String? = nil) {
         self.image = image
+        self.animatedImageData = animatedImageData
+        self.cachingKey = cachingKey
     }
 }
 
@@ -172,3 +241,13 @@ public struct MediaLoaderVideoPreview: Sendable {
         self.image = image
     }
 }
+
+/// The result of resolving a file download request through a ``MediaLoader``.
+public struct MediaLoaderFileRequest: Sendable {
+    /// A ready-to-use URL request with CDN-resolved URL and any required HTTP headers.
+    public var urlRequest: URLRequest
+
+    public init(urlRequest: URLRequest) {
+        self.urlRequest = urlRequest
+    }
+}