[Enhancement]Coordinate call leave cleanup through the Call state machine

Sources/StreamVideo/Call.swift

@@ -634,38 +634,41 @@ public class Call: @unchecked Sendable, WSEventsSubscriber {
 
     /// Leave the current call.
     ///
-    /// The cleanup sequence clears active/ringing call references from
-    /// `StreamVideo` state before emitting `CallNotification.callEnded`.
+    /// The cleanup sequence is coordinated by the ``Call/StateMachine`` so
+    /// repeated leave requests from UI, CallKit, or backend-event fallbacks
+    /// share a single teardown path.
+    ///
+    /// The SDK clears `StreamVideo.State.activeCall` and
+    /// `StreamVideo.State.ringingCall` before posting
+    /// `Notification.Name(CallNotification.callEnded)`.
     ///
     /// - Parameter reason: Optional reason forwarded to the SFU leave request.
     ///   Pass a custom value when you want the backend to distinguish between
     ///   different leave flows (for example, user action vs timeout).
     public func leave(reason: String? = nil) {
-        disposableBag.removeAll()
-        callController.leave(reason: reason)
-        closedCaptionsAdapter.stop()
-        stateMachine.transition(.idle(.init(call: self)))
-        /// Upon `Call.leave` we remove the call from the cache. Any further actions that are required
-        /// to happen on the call object (e.g. rejoin) will need to fetch a new instance from `StreamVideo`
-        /// client.
-        callCache.remove(for: cId)
-        outgoingRingingController = nil
-
-        // Reset the activeAudioFilter
-        setAudioFilter(nil)
-
-        let strongSelf = self
-        let cId = self.cId
-        Task(disposableBag: disposableBag) { @MainActor [strongSelf, streamVideo, cId] in
-            if streamVideo.state.ringingCall?.cId == cId {
-                streamVideo.state.ringingCall = nil
-            }
-            if streamVideo.state.activeCall?.cId == cId {
-                streamVideo.state.activeCall = nil
-            }
-
-            postNotification(with: CallNotification.callEnded, object: strongSelf)
-        }
+        stateMachine.transition(
+            .leaving(
+                .init(
+                    call: self,
+                    input: .leaving(
+                        .init(
+                            reason: reason,
+                            disposableBag: disposableBag,
+                            callController: callController,
+                            closedCaptionsAdapter: closedCaptionsAdapter,
+                            callCache: callCache,
+                            resetOutgoingRingingController: { [weak self] in
+                                self?.outgoingRingingController = nil
+                            },
+                            resetAudioFilter: { [weak self] in
+                                self?.setAudioFilter(nil)
+                            }
+                        )
+                    )
+                ),
+                reason: reason
+            )
+        )
     }
 
     /// Starts noise cancellation asynchronously.

Sources/StreamVideo/CallStateMachine/Stages/Call+LeavingStage.swift

@@ -0,0 +1,92 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import Foundation
+
+extension Call.StateMachine.Stage {
+
+    /// Creates a leaving stage for the call state machine.
+    ///
+    /// - Parameters:
+    ///   - context: The context containing necessary state.
+    ///   - reason: Optional reason forwarded to the backend leave request.
+    /// - Returns: A new `LeavingStage` instance.
+    static func leaving(
+        _ context: Context,
+        reason: String?
+    ) -> Call.StateMachine.Stage {
+        LeavingStage(context, reason: reason)
+    }
+}
+
+extension Call.StateMachine.Stage {
+
+    /// Represents the leaving stage in the call state machine.
+    final class LeavingStage: Call.StateMachine.Stage, @unchecked Sendable {
+        private let reason: String?
+        private let disposableBag = DisposableBag()
+
+        init(
+            _ context: Context,
+            reason: String?
+        ) {
+            self.reason = reason
+            super.init(id: .leaving, context: context)
+        }
+
+        override func transition(
+            from previousStage: Call.StateMachine.Stage
+        ) -> Self? {
+            switch previousStage.id {
+            case .leaving:
+                return nil
+            default:
+                execute()
+                return self
+            }
+        }
+
+        private func execute() {
+            guard
+                let call = context.call,
+                case let .leaving(input) = context.input
+            else {
+                return
+            }
+
+            input.disposableBag.removeAll()
+            input.callController.leave(reason: reason)
+            input.closedCaptionsAdapter.stop()
+
+            /// Upon `Call.leave` we remove the call from the cache. Any
+            /// further actions that are required to happen on the call object
+            /// (e.g. rejoin) will need to fetch a new instance from
+            /// `StreamVideo`.
+            input.callCache.remove(for: call.cId)
+            input.resetOutgoingRingingController()
+            input.resetAudioFilter()
+
+            Task(disposableBag: disposableBag) { @MainActor [weak self, call] in
+                guard let self else {
+                    return
+                }
+
+                if call.streamVideo.state.ringingCall?.cId == call.cId {
+                    call.streamVideo.state.ringingCall = nil
+                }
+                if call.streamVideo.state.activeCall?.cId == call.cId {
+                    call.streamVideo.state.activeCall = nil
+                }
+
+                do {
+                    try transition?(.idle(.init(call: call)))
+                } catch {
+                    log.error(error)
+                }
+
+                postNotification(with: CallNotification.callEnded, object: call)
+            }
+        }
+    }
+}

Sources/StreamVideo/CallStateMachine/Stages/Call+Stage.swift

@@ -13,6 +13,7 @@ extension Call.StateMachine {
             enum Input {
                 case none
                 case join(JoinInput)
+                case leaving(LeavingInput)
                 case accepting(deliverySubject: PassthroughSubject<AcceptCallResponse, Error>)
                 case rejecting(RejectingInput)
             }
@@ -46,6 +47,16 @@ extension Call.StateMachine {
                 var deliverySubject: CurrentValueSubject<RejectCallResponse?, Error>
             }
 
+            struct LeavingInput {
+                let reason: String?
+                let disposableBag: DisposableBag
+                let callController: CallController
+                let closedCaptionsAdapter: ClosedCaptionsAdapter
+                let callCache: CallCache
+                let resetOutgoingRingingController: @Sendable () -> Void
+                let resetAudioFilter: @Sendable () -> Void
+            }
+
             weak var call: Call?
             var input: Input = .none
             var output: Output = .none
@@ -56,6 +67,7 @@ extension Call.StateMachine {
             case idle
             case joining
             case joined
+            case leaving
             case accepting
             case accepted
             case rejecting

StreamVideoTests/Call/Call_Tests.swift

@@ -734,12 +734,31 @@ final class Call_Tests: StreamVideoTestCase, @unchecked Sendable {
 
     func test_leave_withReason_reasonWasPassedToCallController() {
         let mockCallController = MockCallController()
-        let call = MockCall(.dummy(callController: mockCallController))
-        call.stub(for: \.state, with: .init(.dummy()))
+        let subject = MockCall(.dummy(callController: mockCallController))
+        subject.stub(for: \.state, with: .init(.dummy()))
+        let expectedReason = "manual-hangup"
+
+        subject.leave(reason: expectedReason)
+
+        XCTAssertEqual(
+            mockCallController.recordedInputPayload(
+                String.self,
+                for: .leave
+            )?.first,
+            expectedReason
+        )
+    }
+
+    func test_leave_whenCalledRepeatedly_callsCallControllerOnlyOnce() {
+        let mockCallController = MockCallController()
+        let subject = MockCall(.dummy(callController: mockCallController))
+        subject.stub(for: \.state, with: .init(.dummy()))
         let expectedReason = "manual-hangup"
 
-        call.leave(reason: expectedReason)
+        subject.leave(reason: expectedReason)
+        subject.leave(reason: expectedReason)
 
+        XCTAssertEqual(mockCallController.timesCalled(.leave), 1)
         XCTAssertEqual(
             mockCallController.recordedInputPayload(
                 String.self,

StreamVideoTests/StreamVideo_Tests.swift

@@ -107,6 +107,44 @@ final class StreamVideo_Tests: StreamVideoTestCase, @unchecked Sendable {
         XCTAssertNil(streamVideo.state.ringingCall)
     }
 
+    @MainActor
+    func test_streamVideo_activeCallReplacement_postsCallEndedNotificationForPreviousCall() async throws {
+        let subject = StreamVideo.mock(httpClient: HTTPClient_Mock())
+        self.streamVideo = subject
+        let previousCallId = String(String.unique.prefix(10))
+        let previousCallCid = callCid(from: previousCallId, callType: callType)
+        let nextActiveCall = subject.call(callType: callType, callId: callId)
+
+        let notificationExpectation = expectation(
+            description: "Previous call ended notification"
+        )
+        let token = NotificationCenter.default.addObserver(
+            forName: NSNotification.Name(CallNotification.callEnded),
+            object: nil,
+            queue: .main
+        ) { notification in
+            guard (notification.object as? Call)?.cId == previousCallCid else {
+                return
+            }
+            notificationExpectation.fulfill()
+        }
+        defer { NotificationCenter.default.removeObserver(token) }
+
+        do {
+            let previousCall = subject.call(
+                callType: callType,
+                callId: previousCallId
+            )
+            subject.state.activeCall = previousCall
+            subject.state.activeCall = nextActiveCall
+        }
+
+        await fulfillment(of: [notificationExpectation], timeout: defaultTimeout)
+
+        XCTAssertTrue(subject.state.activeCall === nextActiveCall)
+        XCTAssertNil(subject.state.ringingCall)
+    }
+
     func test_streamVideo_ringCallAccept() async throws {
         let httpClient = httpClientWithGetCallResponse()
         let streamVideo = StreamVideo.mock(httpClient: httpClient)