@stream-io/video-react-native-sdk 1.45.1 → 1.46.0

package/src/utils/StreamVideoRN/types.ts

@@ -19,6 +19,74 @@ export type KeepAliveAndroidNotificationTexts = {
 export type NonRingingPushEvent =
   'call.live_started' | 'call.notification' | 'call.missed';
 
+/**
+ * Hooks that run around a ringing call's join, wherever that join is triggered.
+ *
+ * A ringing call is joined by the SDK, not by your code: the accept button joins
+ * internally, and an outgoing call joins itself once the callee answers. That
+ * leaves no moment in which app code holds the call and the join has not yet
+ * happened - which is a problem for anything that must be installed first, most
+ * notably `call.setE2EEManager()`, since it throws once a call has peer
+ * connections.
+ *
+ * These hooks are that moment. They run for every ringing path: accepted from the
+ * CallKit/Telecom UI, accepted inside the app, and outgoing.
+ *
+ * Register them with {@link StreamVideoRN.setRingingCallLifecycleHooks} at your app's
+ * entry point, next to `setPushConfig`. A call accepted from a push notification
+ * can be created and joined before any component mounts - the app may be launched
+ * from a killed state - so registering them from inside React is too late.
+ */
+export type RingingCallLifecycleHooks = {
+  /**
+   * Awaited by `Call.join()` for a ringing call, before any peer connection exists.
+   * **Throwing aborts the join** and the call is not entered.
+   *
+   * That is deliberate: joining without whatever this hook installs would, in the
+   * E2EE case, publish unencrypted media on a call the user believes is private.
+   * On the push path there is no UI to reveal it, so the join fails closed instead.
+   * A failed join also ends the call, so the `Call` it failed on is finished with -
+   * a later attempt happens on a new incoming call or a newly created one.
+   *
+   * Keep it fast. On the CallKit accept path it runs inside iOS's accept deadline
+   * (roughly 30s before the app is killed) and anything slower than five seconds is
+   * treated as a failure. Deriving a key locally is fine; fetching one over the
+   * network does not belong here.
+   *
+   * @example
+   * onBeforeCallJoin: async (call) => {
+   *   await attachE2EEIfConfigured(call);
+   * }
+   */
+  onBeforeCallJoin?: (call: Call) => Promise<void>;
+  /**
+   * Called once, when a ringing call is finished with - it left, whether because
+   * the user hung up, the other side ended it, or its join failed and the SDK
+   * ended the flow.
+   *
+   * Use it to free per-call resources the SDK does not own. An E2EE manager is the
+   * motivating case: it has no native detach, closing the peer connections does not
+   * free it, and on the push path the call can end while the app is still in the
+   * background, where no React cleanup ever runs.
+   *
+   * When an {@link onBeforeCallJoin} is also registered, this is only called for a
+   * call that hook actually entered, so it always pairs with a setup that happened -
+   * a call that rings and is then rejected, cancelled or missed was never set up and
+   * releases nothing. Registered on its own it has no such pairing to honour and is
+   * called for every ringing call that ends. Either way it is tied to the call
+   * ending rather than to any view's lifetime, so navigating away from a live call
+   * does not release it.
+   *
+   * If the setup hook is still running when the call ends - it timed out, say - the
+   * release waits for it to settle, so it cannot free something that hook is about
+   * to create.
+   *
+   * May return a promise; rejections are logged. Nothing is gated on it, so do not
+   * rely on it completing before the OS suspends the app.
+   */
+  onAfterCallLeave?: (call: Call) => void | Promise<void>;
+};
+
 export type StreamVideoConfig = {
   /**
    * The configuration to be used for push notifications.

package/src/utils/internal/callingx/callingx.ts

@@ -67,9 +67,14 @@ function getCallingxCallArgs(call: Call): [string, string, string, boolean] {
       call.state.participants,
       call.currentUserId,
     );
+  const createdByHandle = call.state.createdBy?.id ?? callDisplayName;
   return [
     call.cid, // unique id for call
-    call.state.createdBy?.id ?? callDisplayName, // handle for native call UI (prefer createdBy user id, fallback to call display name)
+    // handle for the native call UI. On iOS it is shown in CallKit Recents and used for
+    // call-back, so we send the caller's user id (matches the Swift SDK). On Android the
+    // self-managed Telecom address is never displayed and callingx wraps it as
+    // `<packageName>:<handle>`, so we send the call id (matches the Android SDK).
+    Platform.OS === 'android' ? call.id : createdByHandle,
     callDisplayName, // display name for display in call screen
     call.state.settings?.video?.enabled ?? false, // is video call?
   ];
@@ -110,7 +115,11 @@ export async function registerOutgoingCall(call: Call) {
  * 2. Displays the incoming call in the callingx library
  * 3. Optionally for non-ringing calls also when ongoing calls are enabled.
  */
-export async function joinCallingxCall(call: Call, activeCalls: Call[]) {
+export async function joinCallingxCall(
+  call: Call,
+  activeCalls: Call[],
+  isCancelled?: () => boolean,
+) {
   if (
     !CallingxModule ||
     !CallingxModule.isSetup ||
@@ -146,12 +155,25 @@ export async function joinCallingxCall(call: Call, activeCalls: Call[]) {
         logger.error(`failed to leave active call ${activeCall.cid}`, e);
       });
     }
+    // Leaving the other calls above can take arbitrarily long, and this join may
+    // have been cancelled meanwhile. Registering now would create a native call
+    // nobody owns. The caller decides, not the call's state: a `Call` reused for
+    // a fresh ring is still `LEFT` here, because `setup()` runs after this.
+    if (isCancelled?.()) {
+      logger.debug(
+        `joinCallingxCall: skipping registration for ${call.cid}: join cancelled while waiting for other calls`,
+      );
+      return;
+    }
     logger.debug(
       `joinCallingxCall: Joining call ${call.cid} isIncoming: ${isIncomingCall} isOutgoing: ${isOutcomingCall}`,
     );
     const callArgs = getCallingxCallArgs(call);
     if (isIncomingCall) {
       await CallingxModule.displayIncomingCall(...callArgs);
+      // never answer a call that was hung up while the OS was displaying it -
+      // the cleanup below ends the registration instead
+      if (isCancelled?.()) return;
       await CallingxModule.answerIncomingCall(call.cid);
     } else {
       await CallingxModule.startCall(...callArgs);
@@ -161,6 +183,19 @@ export async function joinCallingxCall(call: Call, activeCalls: Call[]) {
       `startCallingxCall: Error starting call in callingx: ${call.cid} isIncoming: ${isIncomingCall} isOutgoing: ${isOutcomingCall}`,
       error,
     );
+  } finally {
+    // The registration above can outlive the join that asked for it: `leave()`
+    // may land while native is still bringing the call up, and by the time the
+    // caller aborts, the call exists natively with nobody to end it. Ringing
+    // calls have a lifecycle owner that would clean up; ordinary ones do not.
+    // Nothing was registered when the check above already skipped it, and
+    // `endCallingxCall` no-ops for an untracked cid, so this is safe either way.
+    if (isCancelled?.()) {
+      logger.debug(
+        `joinCallingxCall: ending ${call.cid}: join was cancelled while registering`,
+      );
+      await endCallingxCall(call, 'canceled');
+    }
   }
 }
 

package/src/utils/internal/iosPipTrack.ts

@@ -0,0 +1,39 @@
+import {
+  type Call,
+  DebounceType,
+  type VideoTrackType,
+} from '@stream-io/video-client';
+import { BehaviorSubject } from 'rxjs';
+
+export type PipTrack = { sessionId: string; trackType: VideoTrackType };
+
+/**
+ * The track currently rendered by the native iOS Picture in Picture window,
+ * per Call instance. While set, the window's bounds are the demand of that
+ * track and the inline views of the same track stop requesting their layout.
+ */
+const tracks = new WeakMap<Call, BehaviorSubject<PipTrack | undefined>>();
+
+export const getIosPipTrack$ = (call: Call) => {
+  let track$ = tracks.get(call);
+  if (!track$) {
+    track$ = new BehaviorSubject<PipTrack | undefined>(undefined);
+    tracks.set(call, track$);
+  }
+  return track$;
+};
+
+export const setIosPipTrack = (call: Call, track: PipTrack | undefined) => {
+  const track$ = getIosPipTrack$(call);
+  const previous = track$.getValue();
+  if (previous) {
+    // Clear before opening the gate: mounted inline views replay their layout
+    // synchronously on the gate change and overwrite this. If none is mounted,
+    // the cleared demand stands.
+    call.state.updateParticipantTracks(previous.trackType, {
+      [previous.sessionId]: { dimension: undefined },
+    });
+    call.trackSubscriptionManager.apply(DebounceType.MEDIUM);
+  }
+  track$.next(track);
+};

package/src/utils/internal/registerSDKGlobals.ts

@@ -16,6 +16,7 @@ import {
   unwireAudioEngineSubscription,
 } from './callingx/callingx';
 import { registerCallMediaEngine } from './registerMediaEngine';
+import { beforeJoin, onJoinFailed, onLeave } from './ringingCallLifecycle';
 import { callManager as publicCallManager } from '../../modules/call-manager';
 
 const StreamInCallManagerNativeModule = NativeModules.StreamInCallManager;
@@ -91,6 +92,7 @@ const streamRNVideoSDKGlobals: StreamRNVideoSDKGlobals = {
     wireAudioEngineSubscription: wireAudioEngineSubscription,
     unwireAudioEngineSubscription: unwireAudioEngineSubscription,
   },
+  ringingCallLifecycle: { beforeJoin, onJoinFailed, onLeave },
   callManager: {
     setup: ({ defaultDevice, isRingingTypeCall, cid }) => {
       const isTelecomManaged = isAndroidTelecomManaged({ cid });

package/src/utils/internal/ringingCallLifecycle.ts

@@ -0,0 +1,148 @@
+import {
+  CallingState,
+  videoLoggerSystem,
+  type Call,
+} from '@stream-io/video-client';
+import type { RingingCallLifecycleHooks } from '../StreamVideoRN/types';
+
+const logger = videoLoggerSystem.getLogger('ringingCallLifecycle');
+
+/**
+ * How long `onBeforeCallJoin` may take before the join gives up on it.
+ *
+ * The hook runs inside the CallKit accept, which iOS gives a hard deadline of
+ * roughly 30s before killing the app. Failing well short of that leaves room to
+ * report the failure and end the native call cleanly, and a hook that legitimately
+ * needs longer than this does not belong on the accept path at all.
+ */
+const ON_BEFORE_CALL_JOIN_TIMEOUT_MS = 5_000;
+
+/**
+ * The registered hooks.
+ *
+ * Held here rather than on `StreamVideoRN.config` so the push internals and the
+ * globals bridge can both reach them without importing the `StreamVideoRN`
+ * class, which would close an import cycle through the push setup modules.
+ */
+let hooks: RingingCallLifecycleHooks | undefined;
+
+export const setRingingCallLifecycleHooks = (
+  next: RingingCallLifecycleHooks,
+) => {
+  hooks = next;
+};
+
+/**
+ * How to release what a call's setup hook installed.
+ *
+ * Kept per call rather than in a single current-call slot: an abandoned call's
+ * hook can still finish after the next call has joined, and it has to release
+ * its own manager rather than whatever is current. An entry exists only for a
+ * call whose setup hook actually ran.
+ */
+const cleanups = new WeakMap<Call, () => void>();
+
+/** Invokes the release hook, swallowing whatever it throws. */
+const fireRelease = (call: Call): void => {
+  const hook = hooks?.onAfterCallLeave;
+  if (!hook) return;
+  try {
+    Promise.resolve(hook(call)).catch((e) => {
+      logger.warn(`onAfterCallLeave failed for callCid: ${call.cid}`, e);
+    });
+  } catch (e) {
+    logger.warn(`onAfterCallLeave threw for callCid: ${call.cid}`, e);
+  }
+};
+
+/** Releases what the setup hook installed, at most once. */
+const requestRelease = (call: Call): void => {
+  const cleanup = cleanups.get(call);
+  if (!cleanup) return;
+  // Dropped before it runs: that is what makes a failed join followed by a
+  // leave release exactly once.
+  cleanups.delete(call);
+  cleanup();
+};
+
+/**
+ * Runs the app's pre-join setup, bounded by the deadline.
+ *
+ * Rejecting fails the join closed - joining without whatever this installs would
+ * publish unencrypted media on a call the user believes is private.
+ */
+export const beforeJoin = (call: Call): Promise<void> => {
+  const hook = hooks?.onBeforeCallJoin;
+  if (!hook) return Promise.resolve();
+
+  // Invoked synchronously - a caller expects its hook to start now - but a
+  // synchronous throw becomes a rejection so it cannot escape the bookkeeping.
+  let started: Promise<void>;
+  try {
+    started = Promise.resolve(hook(call));
+  } catch (error) {
+    started = Promise.reject(error);
+  }
+
+  // Cleanup tracks the hook's own promise, never the bounded wait below. The
+  // deadline ends this join's wait but cannot cancel the app's work, so a
+  // manager the hook creates late still has an owner waiting to release it.
+  const settled = started.catch(() => {});
+  cleanups.set(call, () => void settled.then(() => fireRelease(call)));
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const expiry = new Promise<never>((_, reject) => {
+    timeout = setTimeout(
+      () =>
+        reject(
+          new Error(
+            `onBeforeCallJoin did not settle within ${ON_BEFORE_CALL_JOIN_TIMEOUT_MS}ms`,
+          ),
+        ),
+      ON_BEFORE_CALL_JOIN_TIMEOUT_MS,
+    );
+  });
+
+  return Promise.race([started, expiry]).finally(() => clearTimeout(timeout));
+};
+
+/**
+ * The join failed and will not be retried on this call.
+ *
+ * Ends the ringing flow rather than leaving the call sitting in `RINGING`: one
+ * `Call` is one call flow, so the accept button must not be able to offer this
+ * instance again. Never rejects, so the original join error survives.
+ */
+export const onJoinFailed = async (call: Call): Promise<void> => {
+  if (call.state.callingState !== CallingState.LEFT) {
+    try {
+      // Takes the call out of the client's list, which unmounts the ringing UI.
+      // `reject: false`: the join failed locally, so this is not the callee
+      // declining, and the native call has already been ended with 'error'.
+      await call.leave({ reject: false });
+    } catch (error) {
+      logger.warn(`failed to leave after a failed join: ${call.cid}`, error);
+    }
+  }
+  // The leave above notifies {@link onLeave}, which consumes the cleanup. This
+  // covers what it could not: a call already left, or a leave that itself failed.
+  requestRelease(call);
+};
+
+/**
+ * The call has ended.
+ *
+ * Releases what the setup hook installed, once the hook has actually settled -
+ * a hook still running may yet install something, and releasing before it
+ * finishes would strand that.
+ */
+export const onLeave = (call: Call): void => {
+  // A release-only registration has nothing to pair with, so its hook belongs to
+  // the call ending rather than to a join: it is owed for every ringing call
+  // that ends, including one declined without ever joining.
+  if (!hooks?.onBeforeCallJoin) {
+    fireRelease(call);
+    return;
+  }
+  requestRelease(call);
+};

package/src/utils/push/internal/utils.ts

@@ -128,6 +128,10 @@ export const processCallFromPushInBackground = async (
         'processCallFromPushInBackground: failed to join call from push notification',
         e,
       );
+      // Cleanup is not repeated here: `join()`'s own failure boundary already
+      // released whatever the pre-join hook installed, and a second call would
+      // invoke a release-only registration twice.
+      onIOSActionCanBeFulfilled(true);
     }
   } else if (action === 'decline') {
     const alreadyLeft = callFromPush.state.callingState === CallingState.LEFT;

package/src/version.ts

@@ -1 +1 @@
-export const version = '1.45.1';
+export const version = '1.46.0';