Make Call object reusable after leave()

[aleksandar-apostolov]

Goal

Make Call objects reusable after leave() so integrations that cache Call objects can rejoin without creating new instances. Currently, calling leave() cancels coroutine scopes making the Call unusable.

Implementation

• Add resetScopes() method called after cleanup to reset state for rejoin:
  • Generate new session IDs for fresh RTC connections
  • Clear participants to remove stale video/audio tracks
  • Reset device statuses to allow media re-initialization
  • Reset ScopeProvider to allow executor recreation
• Track cleanupJob to prevent race conditions between leave cleanup and rapid rejoin
• Keep Call in client's calls map after leave (remove destroyedCalls cache)
• Make MediaManager.scope a dynamic getter from call.scope
• Maintain API compatibility with deprecated scope parameter in MediaManagerImpl

Testing

• Join a call, leave, then rejoin using the same Call object - verify audio/video works
• Verify CallState (participants, duration, etc.) continues to update after rejoin
• Verify no race conditions between leave cleanup and rapid rejoin
• Run ./gradlew apiCheck to confirm no breaking API changes
• Test with integrations that cache Call objects

[github-actions]

PR checklist ✅

All required conditions are satisfied:

• Title length is OK (or ignored by label).
• At least one pr: label exists.
• Sections ### Goal, ### Implementation, and ### Testing are filled.

🎉 Great job! This PR is ready for review.

[coderabbitai]

Walkthrough

The changes refactor Call lifecycle management to support call object reuse across multiple sessions. Key modifications include making core scope properties mutable, introducing cleanup job tracking, reworking cleanup and reset semantics to preserve StateFlow lifetimes, adding reset methods to media managers and scope providers, and removing LruCache-based call destruction tracking.

Changes

Cohort / File(s)	Summary
Configuration & Ignore Patterns .gitignore	Added .planning/ directory ignore pattern under video-buddy workflow files.
Call Lifecycle & Scope Management stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/Call.kt	Made scopeProvider, supervisorJob, scope, and unifiedSessionId mutable (var). Added cleanupJob to track ongoing cleanup. Tightened join/leave sequencing with cleanupJob?.join() before join proceeds. Reworked cleanup/reset semantics: cleanup() now calls resetScopes() for re-initialization without recreating core objects. Updated MediaManager initialization to use named parameters.
Scope Provider Interface & Implementation stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/call/scope/ScopeProvider.kt, stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/call/scope/ScopeProviderImpl.kt	Added public reset() method to ScopeProvider interface. Implemented reset() in ScopeProviderImpl to set isCleanedUp to false, enabling executor recreation on next use.
Media Manager stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/MediaManager.kt	Increased visibility of _status from private to internal in CameraManager, MicrophoneManager, ScreenShareManager, and MediaManagerImpl. Added internal reset() methods to all four classes to reset device statuses to NotSelected. Updated MediaManagerImpl scope handling to derive dynamically from call.scope instead of constructor parameter.
Client-Level Configuration & Updates stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoBuilder.kt, stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/StreamVideoClient.kt	Added @Deprecated annotation to callUpdatesAfterLeave in StreamVideoBuilder. Removed LruCache-based call destruction mechanism in StreamVideoClient; calls are now retained in memory for potential reuse instead of eviction. Calls no longer evicted on cleanup; scope clearing and event handling simplified. Added @Deprecated annotation to enableCallUpdatesAfterLeave in StreamVideoClient.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A call reborn, no longer destroyed,
Just reset and ready, forever deployed!
Cleanup waits kindly, then joins the dance,
Scopes stay steady through rejoin's advance. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main objective of the changeset: enabling Call objects to be reused after calling leave(), which is the primary purpose reflected across all file modifications.
Description check	✅ Passed	The PR description covers the goal, implementation approach, and testing strategy well, with clear explanations of the changes and rationale.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/reusable-call-after-leave

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/Call.kt (1)

974-985: Ensure resetScopes always runs, even if cleanup fails.

If cleanup() throws or the coroutine is cancelled mid‑cleanup, resetScopes() won’t run, leaving isDestroyed true and potentially blocking future leaves/rejoins. A try/finally here keeps the object reusable even on partial failures.

🐛 Suggested fix

 cleanupJob = clientImpl.scope.launch {
-    safeCall {
-        session?.sfuTracer?.trace(
-            "leave-call",
-            "[reason=$reason, error=${disconnectionReason?.message}]",
-        )
-        val stats = collectStats()
-        session?.sendCallStats(stats)
-    }
-    cleanup()
-    resetScopes()
+    try {
+        safeCall {
+            session?.sfuTracer?.trace(
+                "leave-call",
+                "[reason=$reason, error=${disconnectionReason?.message}]",
+            )
+            val stats = collectStats()
+            session?.sendCallStats(stats)
+        }
+        cleanup()
+    } finally {
+        resetScopes()
+    }
 }

As per coding guidelines, ensure cleanup/teardown paths handle cancellation and failure.

Also applies to: 1512-1546

🧹 Nitpick comments (2)

stream-video-android-core/src/main/kotlin/io/getstream/video/android/core/MediaManager.kt (2)

553-556: Reset should clear stale microphone state beyond status.

Consider also clearing priorStatus and device selections so rejoin doesn’t inherit old pause/resume or routing state.

♻️ Suggested tweak

 internal fun reset() {
     _status.value = DeviceStatus.NotSelected
+    priorStatus = null
+    _selectedDevice.value = null
+    nonHeadsetFallbackDevice = null
 }

Also applies to: 722-727

---

1401-1410: Delegate to the new reset helpers to avoid duplication.

Now that each manager exposes reset(), using them here keeps reset behavior centralized and less error‑prone if those methods evolve.

♻️ Suggested tweak

 internal fun reset() {
-    camera._status.value = DeviceStatus.NotSelected
-    microphone._status.value = DeviceStatus.NotSelected
-    speaker._status.value = DeviceStatus.NotSelected
-    screenShare._status.value = DeviceStatus.NotSelected
+    camera.reset()
+    microphone.reset()
+    screenShare.reset()
+    speaker._status.value = DeviceStatus.NotSelected
 }

[github-actions]

SDK Size Comparison 📏

SDK	Before	After	Difference	Status
stream-video-android-core	12.00 MB	12.00 MB	0.00 MB	🟢
stream-video-android-ui-xml	5.68 MB	5.68 MB	0.00 MB	🟢
stream-video-android-ui-compose	6.28 MB	6.28 MB	0.00 MB	🟢

[rahul-lohra]

I think we should use mutex to re-init scopes and update isDestroyed to prevent race-condition

[aleksandar-apostolov]

Yes, we should

[github-actions]

This pull request has been automatically marked as stale because it has been inactive for 14 days. It will be closed in 7 days if no further activity occurs.

[sonarqubecloud]

Quality Gate failed

Failed conditions
45.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[rahul-lohra]

Risk Analysis: Not cancelling call.scope in call.leave()
The problem
We want to make the Call class reusable after leave(). But scope.cancel() in shutDownJobsGracefully() cancels all Flow.stateIn() operators — they cannot be restarted.

If we remove scope.cancel(), we introduce risks in already stable code.

Risk: Zombie coroutines
call.scope is not just used in Call.kt. It is passed down to multiple components that internally launch their own coroutines:

If scope is not cancelled, we need to micromanage every usage of scope running after leave() — Coordinator Event processing/SFU event processing, SFU event listeners, ICE monitoring, stats reporting, audio processing, and more. I am aware we are handling them but introducing micromanag does not not appear scalable
These are zombie operations on a dead session.

Approaches to solve this
Approach 1: Manually cancel each scope.launch
Go through every scope.launch{} usage and cancel them individually in leave().

Downside: Fragile. Easy to miss one. Every new feature that adds a scope.launch needs to remember to add cancellation. Not scalable.

Approach 2: Create a child scope for session work, keep scope for stateIn
Create a new sessionScope (child of scope). Pass it to all components. Cancel only sessionScope in leave(). stateIn flows stay on scope and survive.

Downside: We need to audit every usage of scope and decide — does this go on scope or sessionScope? High risk of miscategorizing. Changes the cancellation behavior of existing stable code.

Approach 3: Create a new scope just for stateIn flows ✅
Keep scope exactly as-is. Create a new stateScope only for the stateIn calls that need to survive.

scope — untouched. Cancelled in leave(). All existing scope.launch code works exactly as today.
stateScope — new. Only the ~6 stateIn calls move here.
Benefit: Existing code path has zero behavior change. If we miss moving a stateIn, it stays on scope and gets cancelled like today — safe default.

Trade-off: stateScope stays alive after leave(). But it only holds StateFlows with their last emitted value — no active work, no upstream collection, no side effects. For non-reusable calls, we can cancel it in cleanup().

Approach 3b: Replace stateIn with a restartable operator ✅
Instead of managing scope lifetimes, replace stateIn with RestartableStateFlow + RestartableScope:

RestartableScope — wraps a coroutine scope. Can be cancelled and restarted.
RestartableStateFlow — registers itself with RestartableScope. On restart, automatically re-subscribes to upstream. Preserves last emitted value across cancel/restart.
Benefit:

shutDownJobsGracefully() still cancels everything (including RestartableScope) — existing behavior preserved
On join(), calling restartableScope.restart() brings all stateIn flows back to life automatically
Change surface is small — only the ~6 stateIn call sites change
No new scope that lives forever
Trade-off: Introduces a new abstraction (RestartableStateFlow). Needs to be well-tested.

Recommendation
I'd lean towards Approach 3b (restartable operator). It keeps the existing cancel-everything behavior intact, isolates the change to a small surface area, and solves the reuse problem cleanly.

Happy to discuss implementation details in a separate thread.

[aleksandar-apostolov]

Approach 3b cannot work because the state flows need to be observable even if the call is joined/left multiple times even if you are not in a session you still need to be able to get updates via call.get() or client.queryCalls.