ChannelListController.swift

//
// Copyright © 2026 Stream.io Inc. All rights reserved.
//

import CoreData
import Foundation

extension ChatClient {
    /// Creates a new `ChannelListController` with the provided channel query.
    /// - Parameter query: The query specify the filter and sorting of the channels the controller should fetch.    ///
    /// - Returns: A new instance of `ChatChannelListController`.
    public func channelListController(query: ChannelListQuery) -> ChatChannelListController {
        .init(query: query, client: self)
    }

    /// Creates a new `ChannelListController` with the provided channel query and filter block.
    ///
    /// When passing `filter`, make sure the runtime logic matches the one expected by the filter passed in the query object.
    /// If they don't match, there can be jumps when loading the list.
    ///
    /// - Parameters:
    ///   - query: The query specify the filter and sorting of the channels the controller should fetch.
    ///   - filter: A block that determines whether the channels belongs to this controller.
    /// - Returns: A new instance of `ChatChannelListController`
    public func channelListController(
        query: ChannelListQuery,
        filter: (@Sendable (ChatChannel) -> Bool)? = nil
    ) -> ChatChannelListController {
        .init(query: query, client: self, filter: filter)
    }
}

/// `ChatChannelListController` is a controller class which allows observing a list of chat channels based on the provided query.
///
/// - Note: For an async-await alternative of the `ChatChannelListController`, please check ``ChannelList`` in the async-await supported [state layer](https://getstream.io/chat/docs/sdk/ios/client/state-layer/state-layer-overview/).
public class ChatChannelListController: DataController, DelegateCallable, DataStoreProvider, @unchecked Sendable {
    /// The query specifying and filtering the list of channels.
    public internal(set) var query: ChannelListQuery

    /// The `ChatClient` instance this controller belongs to.
    public let client: ChatClient

    /// The channels matching the query of this controller.
    ///
    /// To observe changes of the channels, set your class as a delegate of this controller or use the provided
    /// `Combine` publishers.
    ///
    public var channels: [ChatChannel] {
        startChannelListObserverIfNeeded()
        return channelListObserver.items
    }

    /// The worker used to fetch the remote data and communicate with servers.
    private lazy var worker: ChannelListUpdater = self.environment
        .channelQueryUpdaterBuilder(
            client.databaseContainer,
            client.apiClient
        )
    
    /// The worker used to update current user data.
    private lazy var currentUserUpdater: CurrentUserUpdater = self.environment
        .currentUserUpdaterBuilder(
            client.databaseContainer,
            client.apiClient
        )
    
    /// The validator used to determine if messages can be marked as delivered.
    private let deliveryCriteriaValidator: MessageDeliveryCriteriaValidating

    /// A Boolean value that returns whether pagination is finished
    public private(set) var hasLoadedAllPreviousChannels: Bool = false

    /// A type-erased delegate.
    var multicastDelegate: MulticastDelegate<ChatChannelListControllerDelegate> = .init() {
        didSet {
            stateMulticastDelegate.set(mainDelegate: multicastDelegate.mainDelegate)
            stateMulticastDelegate.set(additionalDelegates: multicastDelegate.additionalDelegates)

            // After setting delegate local changes will be fetched and observed.
            startChannelListObserverIfNeeded()
        }
    }

    private(set) lazy var channelListObserver: BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> = {
        if let updated = worker.loadPredefinedFilter(for: query) {
            query = updated
        }
        return makeChannelListObserver()
    }()

    private func makeChannelListObserver() -> BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> {
        let request = ChannelDTO.channelListFetchRequest(query: self.query, chatClientConfig: client.config)
        let observer = environment.createChannelListDatabaseObserver(
            client.databaseContainer,
            request,
            { try $0.asModel() },
            query.runtimeSortingValues
        )

        observer.onDidChange = { [weak self] changes in
            self?.delegateCallback { [weak self] in
                guard let self = self else {
                    log.warning("Callback called while self is nil")
                    return
                }
                log.debug("didChangeChannels: \(changes.map(\.debugDescription))")
                $0.controller(self, didChangeChannels: changes)
            }
        }
        return observer
    }

    var _basePublishers: Any?
    /// An internal backing object for all publicly available Combine publishers. We use it to simplify the way we expose
    /// publishers. Instead of creating custom `Publisher` types, we use `CurrentValueSubject` and `PassthroughSubject` internally,
    /// and expose the published values by mapping them to a read-only `AnyPublisher` type.
    var basePublishers: BasePublishers {
        if let value = _basePublishers as? BasePublishers {
            return value
        }
        _basePublishers = BasePublishers(controller: self)
        return _basePublishers as? BasePublishers ?? .init(controller: self)
    }

    private let filter: (@Sendable (ChatChannel) -> Bool)?
    private let environment: Environment
    private lazy var channelListLinker: ChannelListLinker = self.environment
        .channelListLinkerBuilder(
            query, filter, client.config, client.databaseContainer, worker, client.channelWatcherHandler
        )

    /// Creates a new `ChannelListController`.
    ///
    /// - Parameters:
    ///   - query: The query used for filtering the channels.
    ///   - client: The `Client` instance this controller belongs to.
    ///   - filter: A block that determines whether the channels belongs to this controller.
    init(
        query: ChannelListQuery,
        client: ChatClient,
        filter: (@Sendable (ChatChannel) -> Bool)? = nil,
        environment: Environment = .init()
    ) {
        self.client = client
        self.query = query
        self.filter = filter
        self.environment = environment
        self.deliveryCriteriaValidator = environment.deliveryCriteriaValidatorBuilder()
        super.init()
    }

    override public func synchronize(_ completion: (@MainActor (_ error: Error?) -> Void)? = nil) {
        startChannelListObserverIfNeeded()
        channelListLinker.start(with: client.eventNotificationCenter)
        client.syncRepository.startTrackingChannelListController(self)
        updateChannelList { result in
            completion?(result.error)
        }
    }
    
    // MARK: - Actions

    /// Loads next channels from backend.
    ///
    /// - Parameters:
    ///   - limit: Limit for page size.
    ///   - completion: The completion. Will be called on a **callbackQueue** when the network request is finished.
    ///                 If request fails, the completion will be called with an error.
    ///
    public func loadNextChannels(
        limit: Int? = nil,
        completion: (@MainActor (Error?) -> Void)? = nil
    ) {
        if hasLoadedAllPreviousChannels {
            callback {
                completion?(nil)
            }
            return
        }

        let limit = limit ?? query.pagination.pageSize
        var updatedQuery = query
        updatedQuery.pagination = Pagination(pageSize: limit, offset: channels.count)
        worker.update(channelListQuery: updatedQuery) { result in
            switch result {
            case let .success(updateResult):
                self.markChannelsAsDeliveredIfNeeded(channels: updateResult.channels)
                self.hasLoadedAllPreviousChannels = updateResult.channels.count < limit
                if let updatedQuery = updateResult.updatedQuery {
                    self.query = updatedQuery
                    self.updateChannelListObserver()
                }
                self.callback { completion?(nil) }
            case let .failure(error):
                self.callback { completion?(error) }
            }
        }
    }

    // MARK: - Internal

    func refreshLoadedChannels(completion: @escaping @Sendable (Result<Set<ChannelId>, Error>) -> Void) {
        let channelCount = channelListObserver.items.count
        worker.refreshLoadedChannels(for: query, channelCount: channelCount, completion: completion)
    }

    // MARK: - Helpers

    private func updateChannelList(
        _ completion: (@MainActor (Result<ChannelListUpdateResult, Error>) -> Void)? = nil
    ) {
        let limit = query.pagination.pageSize
        worker.update(
            channelListQuery: query
        ) { [weak self] result in
            switch result {
            case let .success(updateResult):
                self?.state = .remoteDataFetched
                self?.hasLoadedAllPreviousChannels = updateResult.channels.count < limit

                // Mark channels as delivered if synchronization was successful
                self?.markChannelsAsDeliveredIfNeeded(channels: updateResult.channels)

                // Predefined filters can update local query representation
                if let updatedQuery = updateResult.updatedQuery {
                    self?.query = updatedQuery
                    self?.updateChannelListObserver()
                }
                
                self?.callback { completion?(.success(updateResult)) }
            case let .failure(error):
                self?.state = .remoteDataFetchFailed(ClientError(with: error))
                self?.callback { completion?(.failure(error)) }
            }
        }
    }

    /// Marks channels as delivered if they meet the specified criteria.
    /// - Parameter channels: The channels to evaluate for marking as delivered.
    private func markChannelsAsDeliveredIfNeeded(channels: [ChatChannel]) {
        guard let currentUser = client.currentUserController().currentUser else { return }

        // Extract channels that should be marked as delivered
        let deliveries: [MessageDeliveryInfo] = channels.compactMap { channel in
            guard let message = channel.latestMessages.first else {
                return nil
            }
            guard deliveryCriteriaValidator.canMarkMessageAsDelivered(message, for: currentUser, in: channel) else {
                return nil
            }
            return MessageDeliveryInfo(channelId: channel.cid, messageId: message.id)
        }

        // Only make the API call if there are channels to mark as delivered
        guard !deliveries.isEmpty else { return }

        // Mark channels as delivered
        currentUserUpdater.markMessagesAsDelivered(deliveries) { error in
            if let error = error {
                log.error("Failed to mark channels as delivered: \(error)")
            }
        }
    }

    /// If the `state` of the controller is `initialized`, this method calls `startObserving` on the
    /// `channelListObserver` to fetch the local data and start observing the changes. It also changes
    /// `state` based on the result.
    ///
    /// It's safe to call this method repeatedly.
    ///
    private func startChannelListObserverIfNeeded() {
        guard state == .initialized else { return }
        do {
            try channelListObserver.startObserving()
            state = .localDataFetched
        } catch {
            state = .localDataFetchFailed(ClientError(with: error))
            log.error("Failed to perform fetch request with error: \(error). This is an internal error.")
        }
    }
    
    private func updateChannelListObserver() {
        channelListObserver = makeChannelListObserver()
        do {
            try channelListObserver.startObserving()
        } catch {
            state = .localDataFetchFailed(ClientError(with: error))
            log.error("Failed to update the channel list observer: \(error)")
        }
    }
}

extension ChatChannelListController {
    struct Environment {
        var channelQueryUpdaterBuilder: (
            _ database: DatabaseContainer,
            _ apiClient: APIClient
        ) -> ChannelListUpdater = ChannelListUpdater.init

        var channelListLinkerBuilder: (
            _ query: ChannelListQuery,
            _ filter: (@Sendable (ChatChannel) -> Bool)?,
            _ clientConfig: ChatClientConfig,
            _ databaseContainer: DatabaseContainer,
            _ worker: ChannelListUpdater,
            _ channelWatcherHandler: ChannelWatcherHandling
        ) -> ChannelListLinker = ChannelListLinker.init
        
        var currentUserUpdaterBuilder: (
            _ database: DatabaseContainer,
            _ apiClient: APIClient
        ) -> CurrentUserUpdater = CurrentUserUpdater.init
        
        var deliveryCriteriaValidatorBuilder: () -> MessageDeliveryCriteriaValidating = {
            MessageDeliveryCriteriaValidator()
        }
        
        var createChannelListDatabaseObserver: (
            _ database: DatabaseContainer,
            _ fetchRequest: NSFetchRequest<ChannelDTO>,
            _ itemCreator: @escaping (ChannelDTO) throws -> ChatChannel,
            _ sort: [SortValue<ChatChannel>]
        )
            -> BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> = {
                BackgroundListDatabaseObserver(
                    database: $0,
                    fetchRequest: $1,
                    itemCreator: $2,
                    itemReuseKeyPaths: (\ChatChannel.cid.rawValue, \ChannelDTO.cid),
                    runtimeSorting: $3
                )
            }
    }
}

extension ChatChannelListController {
    /// Set the delegate of `ChannelListController` to observe the changes in the system.
    public weak var delegate: ChatChannelListControllerDelegate? {
        get { multicastDelegate.mainDelegate }
        set { multicastDelegate.set(mainDelegate: newValue) }
    }
}

/// `ChatChannelListController` uses this protocol to communicate changes to its delegate.
public protocol ChatChannelListControllerDelegate: DataControllerStateDelegate {
    /// The controller changed the list of observed channels.
    ///
    /// - Parameters:
    ///   - controller: The controller emitting the change callback.
    ///   - changes: The change to the list of channels.\
    ///
    func controller(
        _ controller: ChatChannelListController,
        didChangeChannels changes: [ListChange<ChatChannel>]
    )
}

public extension ChatChannelListControllerDelegate {
    func controller(
        _ controller: ChatChannelListController,
        didChangeChannels changes: [ListChange<ChatChannel>]
    ) {}
}

extension ClientError {
    public final class FetchFailed: Error {
        public let localizedDescription: String = "Failed to perform fetch request. This is an internal error."
    }
}