[Fix]CallKit ringing edge cases for already-handled incoming calls (#1115)

Author: ipavlidakis

CHANGELOG.md

@@ -19,6 +19,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Fix join-call timeout caused by a `PassthroughSubject` race where the response was emitted before the subscription was established. [#1113](https://github.com/GetStream/stream-video-swift/pull/1113)
 - CallKit-managed calls now respect the configured `participantAutoLeavePolicy`. [#1112](https://github.com/GetStream/stream-video-swift/pull/1112)
 - Prevent `CallViewModel` from entering `.inCall` from participant updates before the call is ready, while preserving the CallKit join handoff to `.inCall`. [#1109](https://github.com/GetStream/stream-video-swift/pull/1109)
+- Handle CallKit ringing edge cases by ending already-handled incoming calls with explicit leave reasons when they were answered, rejected, missed, or ended elsewhere. [#1115](https://github.com/GetStream/stream-video-swift/pull/1115)
 
 # [1.45.0](https://github.com/GetStream/stream-video-swift/releases/tag/1.45.0)
 _March 31, 2026_

Sources/StreamVideo/CallKit/CallKitService.swift

@@ -174,7 +174,16 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
             .default
             .publisher(for: Notification.Name(CallNotification.callEnded))
             .compactMap { $0.object as? Call }
-            .sink { [weak self] in self?.callEnded($0.cId, ringingTimedOut: false) }
+            .sink {
+                [weak self] in self?.callEnded(
+                    $0.cId,
+                    ringingTimedOut: false,
+                    leaveReason: StreamRejectionReasonProvider
+                        .HandledCallReason
+                        .callEndedLocally
+                        .rawValue
+                )
+            }
 
         /// - Important:
         /// It used to debounce System's attempts to mute/unmute the call. It seems that the system
@@ -234,7 +243,14 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
                 """,
                 subsystems: .callKit
             )
-            callEnded(cid, ringingTimedOut: false)
+            callEnded(
+                cid,
+                ringingTimedOut: false,
+                leaveReason: StreamRejectionReasonProvider
+                    .HandledCallReason
+                    .notConfigured
+                    .rawValue
+            )
             return
         }
 
@@ -268,21 +284,19 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
                     .reportCall()
 
                 let callState = try await callEntry.call.get()
-                if !checkIfCallWasHandled(callState: callState) {
-                    callEntry.createdBy = callState.call.createdBy.toUser
-                    setUpRingingTimer(for: callState)
-                } else {
+                if let leaveReason = checkIfCallWasHandled(callState: callState) {
                     log.debug(
-                        """
-                        Rejecting VoIP incoming call as it has been handled.
-                        callUUID:\(callUUID)
-                        cid:\(cid) 
-                        callerId:\(callerId)
-                        callerName:\(localizedCallerName)
-                        """,
+                        "Ending call with reason:\(leaveReason) { uuid:\(callUUID), cid:\(cid), callerId:\(callerId), callerName:\(localizedCallerName) }",
                         subsystems: .callKit
                     )
-                    callEnded(cid, ringingTimedOut: false)
+                    callEnded(
+                        cid,
+                        ringingTimedOut: false,
+                        leaveReason: leaveReason
+                    )
+                } else {
+                    callEntry.createdBy = callState.call.createdBy.toUser
+                    setUpRingingTimer(for: callState)
                 }
             } catch {
                 log.error(
@@ -295,7 +309,14 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
                     subsystems: .callKit,
                     error: error
                 )
-                callEnded(cid, ringingTimedOut: false)
+                callEnded(
+                    cid,
+                    ringingTimedOut: false,
+                    leaveReason: StreamRejectionReasonProvider
+                        .HandledCallReason
+                        .reportCallFailed
+                        .rawValue
+                )
             }
         }
     }
@@ -376,12 +397,29 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
         callCache.remove(for: newCallEntry.call.cId)
     }
 
-    /// Handle call end event.
+    /// Handles a ringing or active CallKit call ending.
+    ///
+    /// Calling this method requests the matching `CXEndCallAction`. If the call
+    /// is still ringing, the eventual reject request uses `leaveReason` when
+    /// provided; otherwise the SDK derives a rejection reason from the current
+    /// ringing state.
+    ///
+    /// - Parameters:
+    ///   - cId: The call CID managed by CallKit.
+    ///   - ringingTimedOut: Whether the ringing timer elapsed before the user
+    ///     answered.
+    ///   - leaveReason: An explicit backend rejection reason to use for ringing
+    ///     calls that were already handled elsewhere.
     open func callEnded(
         _ cId: String,
-        ringingTimedOut: Bool
+        ringingTimedOut: Bool,
+        leaveReason: String? = nil
     ) {
-        endCall(cId, ringingTimedOut: ringingTimedOut)
+        endCall(
+            cId,
+            ringingTimedOut: ringingTimedOut,
+            leaveReason: leaveReason
+        )
     }
 
     /// Called when a participant leaves the call.
@@ -569,12 +607,16 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
                 stackEntry.call.leave(reason: stackEntry.leaveReason)
             } else {
                 do {
-                    let rejectionReason = await streamVideo?
-                        .rejectionReasonProvider
-                        .reason(
-                            for: stackEntry.call.cId,
-                            ringTimeout: stackEntry.ringingTimedOut
-                        )
+                    let rejectionReason = if let leaveReason = stackEntry.leaveReason {
+                        leaveReason
+                    } else {
+                        await streamVideo?
+                            .rejectionReasonProvider
+                            .reason(
+                                for: stackEntry.call.cId,
+                                ringTimeout: stackEntry.ringingTimedOut
+                            )
+                    }
                     log.debug(
                         """
                         Rejecting with reason: \(rejectionReason ?? "nil")
@@ -639,32 +681,32 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
         try await callController.requestTransaction(with: action)
     }
 
-    /// Return whether this call was already accepted or rejected.
-    open func checkIfCallWasHandled(callState: GetCallResponse) -> Bool {
+    /// Checks whether the incoming ringing call was already handled before
+    /// this device finished presenting CallKit.
+    ///
+    /// CallKit uses this gate right after fetching the latest backend state,
+    /// before starting the local ringing timer. If a leave reason is returned,
+    /// the service immediately ends the CallKit flow instead of continuing to
+    /// ring locally.
+    ///
+    /// - Parameter callState: The latest backend state for the ringing call.
+    /// - Returns: A backend leave reason when CallKit should stop ringing
+    ///   immediately, or `nil` when the local device should keep ringing.
+    open func checkIfCallWasHandled(callState: GetCallResponse) -> String? {
         guard let streamVideo else {
             log.warning(
                 "CallKit operation:\(#function) cannot be fulfilled because StreamVideo is nil.",
                 subsystems: .callKit
             )
-            return false
-        }
-
-        var allMembers = callState.members.map(\.user.toUser)
-        let creator = callState.call.createdBy.toUser
-        let isUserInMembersArray = allMembers.filter { $0.id == creator.id }.isEmpty == false
-        if !isUserInMembersArray {
-            allMembers.append(creator)
+            return StreamRejectionReasonProvider
+                .HandledCallReason
+                .notConfigured
+                .rawValue
         }
-        let allCallees = allMembers.filter { $0.id != creator.id }
 
-        let currentUserId = streamVideo.user.id
-        let acceptedBy = callState.call.session?.acceptedBy ?? [:]
-        let rejectedBy = callState.call.session?.rejectedBy ?? [:]
-        let isAccepted = acceptedBy[currentUserId] != nil
-        let isRejected = rejectedBy[currentUserId] != nil
-        let isRejectedByEveryoneElse = (allCallees.endIndex > 1)
-            && rejectedBy.keys.filter { $0 != currentUserId }.count == (allCallees.endIndex - 1)
-        return isAccepted || isRejected || isRejectedByEveryoneElse
+        return streamVideo
+            .rejectionReasonProvider
+            .reason(callState: callState)
     }
 
     /// Start the ringing timeout timer for the call.
@@ -716,7 +758,14 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
                 guard let self else { return }
                 switch event {
                 case let .typeCallEndedEvent(response):
-                    callEnded(response.callCid, ringingTimedOut: false)
+                    callEnded(
+                        response.callCid,
+                        ringingTimedOut: false,
+                        leaveReason: StreamRejectionReasonProvider
+                            .HandledCallReason
+                            .callEventReceived
+                            .rawValue
+                    )
                 case let .typeCallAcceptedEvent(response):
                     callAccepted(response)
                 case let .typeCallRejectedEvent(response):
@@ -819,10 +868,13 @@ open class CallKitService: NSObject, CXProviderDelegate, @unchecked Sendable {
             return
         }
 
-        endCall(
+        callEnded(
             activeCallEntry.call.cId,
             ringingTimedOut: false,
-            leaveReason: "auto-leave"
+            leaveReason: StreamRejectionReasonProvider
+                .HandledCallReason
+                .autoLeave
+                .rawValue
         )
     }
 

Sources/StreamVideo/Utils/RejectionReasonProvider/RejectionReasonProvider.swift

@@ -20,11 +20,69 @@ public protocol RejectionReasonProviding: Sendable {
     /// - Note: ``ringTimeout`` being true, has an effect **only** when it's set  from the side of
     /// the caller when the callee doesn't reply the ringing call in the amount of time set on the dashboard.
     func reason(for callCid: String, ringTimeout: Bool) async -> String?
+
+    /// Determines whether a ringing call was already handled elsewhere and, if
+    /// so, returns the backend leave reason that should be used locally.
+    ///
+    /// - Parameter callState: The latest backend state for the ringing call.
+    /// - Returns: A backend leave reason, or `nil` when the device should keep
+    ///   ringing locally.
+    func reason(callState: GetCallResponse) -> String?
+}
+
+public extension RejectionReasonProviding {
+
+    /// Default no-op implementation to preserve source compatibility for
+    /// existing custom providers that do not yet reason about handled calls.
+    func reason(callState: GetCallResponse) -> String? {
+        _ = callState
+        return nil
+    }
 }
 
 /// A provider that determines the rejection reason for a call based on its state.
 final class StreamRejectionReasonProvider: RejectionReasonProviding, @unchecked Sendable {
 
+    /// Backend leave reasons for incoming ringing calls that were already
+    /// handled on another device or by another participant.
+    enum HandledCallReason: String {
+        /// Used when CallKit needs a handled-call reason before a
+        /// `StreamVideo` client is configured on the service/provider.
+        case notConfigured = "not-configured"
+
+        /// Used when reporting the incoming call fails before the local device
+        /// can continue the ringing flow.
+        case reportCallFailed = "report-call-failed"
+
+        /// Used when a backend `call.ended` event dismisses the local ringing
+        /// flow before the user answers.
+        case callEventReceived = "call.ended event received"
+
+        /// Used when the latest backend call state already marks the call as
+        /// ended before CallKit starts ringing locally.
+        case callHasEnded = "call-has-ended"
+
+        /// Used when the local SDK already ended the call and CallKit is being
+        /// brought back in sync through `CallNotification.callEnded`.
+        case callEndedLocally = "call-ended-locally"
+
+        /// Used when the same user already accepted, rejected, or missed the
+        /// ringing call on another device.
+        case userRespondedElsewhere = "user-responded-elsewhere"
+
+        /// Used when the caller cancels the ringing flow before any other
+        /// invitee has accepted the call.
+        case creatorRejected = "ring: creator rejected"
+
+        /// Used when every invitee other than the current user and the caller
+        /// has already rejected the ringing call.
+        case allOtherParticipantsRejected = "ring: everyone rejected"
+
+        /// Used when the configured participant auto-leave policy ends the
+        /// active CallKit-managed call.
+        case autoLeave = "auto-leave"
+    }
+
     /// The stream video associated with this provider.
     private nonisolated(unsafe) weak var streamVideo: StreamVideo?
 
@@ -66,4 +124,96 @@ final class StreamRejectionReasonProvider: RejectionReasonProviding, @unchecked
                 : RejectCallRequest.Reason.decline
         }
     }
+
+    /// Returns the backend leave reason for a ringing call that no longer
+    /// needs to keep ringing on this device.
+    func reason(callState: GetCallResponse) -> String? {
+        guard let currentUserId = streamVideo?.user.id else {
+            return HandledCallReason.notConfigured.rawValue
+        }
+
+        if callHasEnded(callState) {
+            return HandledCallReason.callHasEnded.rawValue
+        } else if currentUserRespondedElsewhere(callState, currentUserId: currentUserId) {
+            return HandledCallReason.userRespondedElsewhere.rawValue
+        } else if creatorHungUpAndNoOneElseAccepted(callState) {
+            return HandledCallReason.creatorRejected.rawValue
+        } else if otherParticipantsRejected(callState, currentUserId: currentUserId) {
+            return HandledCallReason.allOtherParticipantsRejected.rawValue
+        } else {
+            return nil
+        }
+    }
+
+    // MARK: - Private Helpers
+
+    private func callHasEnded(_ callState: GetCallResponse) -> Bool {
+        callState.call.endedAt != nil
+    }
+
+    private func currentUserRespondedElsewhere(
+        _ callState: GetCallResponse,
+        currentUserId: String
+    ) -> Bool {
+        let hasCurrentUserAcceptedElsewhere =
+            callState.call.session?.acceptedBy[currentUserId] != nil
+        let hasCurrentUserRejectedElsewhere =
+            callState.call.session?.rejectedBy[currentUserId] != nil
+        let hasCurrentUserMissed =
+            callState.call.session?.missedBy[currentUserId] != nil
+        return hasCurrentUserAcceptedElsewhere
+            || hasCurrentUserRejectedElsewhere
+            || hasCurrentUserMissed
+    }
+
+    private func creatorHungUpAndNoOneElseAccepted(
+        _ callState: GetCallResponse
+    ) -> Bool {
+        let creatorId = callState.call.createdBy.id
+
+        guard
+            callState.call.session?.rejectedBy[creatorId] != nil
+        else {
+            return false
+        }
+
+        let otherAcceptedParticipants = Set(
+            (callState.call.session?.acceptedBy ?? [:]).keys.filter { $0 != creatorId }
+        )
+
+        guard otherAcceptedParticipants.isEmpty else {
+            return false
+        }
+
+        return true
+    }
+
+    private func otherParticipantsRejected(
+        _ callState: GetCallResponse,
+        currentUserId: String
+    ) -> Bool {
+        let creatorId = callState.call.createdBy.id
+
+        // Only invitees other than the current user and the creator count
+        // toward the "everyone else rejected" rule.
+        let otherParticipants = Set(
+            callState.members
+                .map(\.userId)
+                .filter { $0 != currentUserId && $0 != creatorId }
+        )
+        let rejectedOtherParticipants = Set(
+            (callState.call.session?.rejectedBy ?? [:])
+                .keys
+                .filter { $0 != currentUserId && $0 != creatorId }
+        )
+
+        guard
+            otherParticipants.isEmpty == false,
+            otherParticipants.isSubset(of: rejectedOtherParticipants)
+        else {
+            return false
+        }
+
+        return true
+    }
 }