@voltkit-rtc/react-native 0.0.0-stage → 0.1.1

package/src/platform/streams.ts

@@ -0,0 +1,285 @@
+/**
+ * Every native MediaStream this package makes, and the order in which streams and tracks are let go.
+ *
+ * In react-native-webrtc a MediaStream is a native object that holds its tracks. Releasing a stream after one of its
+ * tracks was disposed -- a local track released, or a remote one whose peer connection closed -- kills the app:
+ * `mediaStreamRemoveTrack` cannot find the track, so it stays in the native stream, and disposing the stream throws
+ * `IllegalStateException: MediaStreamTrack has been disposed` on the module's thread (Phase 0 finding 1, seen on a
+ * reconnect, a room closing and a plain release in the wrong order). So:
+ *
+ * - Views (VideoTrack) show a track through a wrapper stream made only here: one per track, shared by every view of it,
+ *   released (`release(false)`, never the track) when the last view goes.
+ * - Before the client closes what receives remote tracks (a consumer, the receive transport, the session) it calls the
+ *   platform's `detachTracks`: their wrappers are released then, while the peer connection still exists, and no new
+ *   one is made for them.
+ * - `stop(track)` (the platform's stopTrack) releases the track's wrappers and takes it out of every other stream made
+ *   here before it disposes the track; a capture stream left empty is released too. A stream the app got from
+ *   getUserMedia through this package can therefore never be left holding a disposed track.
+ * - A stream the app gave the client (`client.publish(stream)` with a stream the app captured itself) is the app's: the
+ *   client stops and releases its tracks but never the stream. Once told of it (`adoptAppStream`), `stop(track)` takes
+ *   the track out of it too while the track is alive, so the app can still release it afterwards; this package never
+ *   releases it. @voltkit-rtc/client 0.9.12's publish() and publishScreen({ stream }) call that hook.
+ * - A stream that would still be released while holding a disposed track (a remote track already ended, a track
+ *   released elsewhere) is left alone instead: a small native leak, never a crash. A view wrapper whose track ended
+ *   before the view let go is left the same way: only the end shows that an app released the track itself.
+ */
+import type { MediaStream as RNMediaStream } from 'react-native-webrtc';
+import { loadWebRTC } from '../globals';
+import { logError, webrtcMissing } from '../errors';
+
+/** What this module needs of a track: react-native-webrtc's MediaStreamTrack, or a test's stand-in. */
+export interface TrackLike {
+  readonly id: string;
+  readonly kind: string;
+  readonly remote?: boolean;
+  readonly readyState: string;
+  enabled: boolean;
+  stop(): void;
+  release?(): void;
+}
+
+/** What this module needs of a stream: react-native-webrtc's MediaStream. */
+export interface StreamLike {
+  getTracks(): TrackLike[];
+  removeTrack(track: TrackLike): void;
+  release(releaseTracks?: boolean): void;
+  toURL(): string;
+}
+
+/**
+ * Why a stream is kept: a capture (getUserMedia, getDisplayMedia), the client's own (createStream), a view, or the
+ * app's own that the client publishes (adoptAppStream: tracks taken out of it, never released here).
+ */
+export type StreamRole = 'capture' | 'client' | 'view' | 'app';
+
+interface Entry {
+  readonly stream: StreamLike;
+  readonly role: StreamRole;
+  released: boolean;
+}
+
+interface View {
+  readonly entry: Entry;
+  refs: number;
+  readonly ended: Set<() => void>;
+}
+
+/** One view's hold on a track's wrapper stream. */
+export interface ViewHandle {
+  /** The wrapper's URL, for RTCView's streamURL. */
+  readonly url: string;
+  /** Called when the wrapper goes before this view lets go of it (the track was stopped or detached). */
+  onEnd(listener: () => void): () => void;
+  /** This view is done; the wrapper is released when the last view of the track lets go. */
+  release(): void;
+}
+
+export class StreamBook {
+  private readonly live = new Set<Entry>();
+  private readonly entries = new WeakMap<object, Entry>();
+  private readonly views = new Map<TrackLike, View>();
+  /** Local tracks this package disposed (released). */
+  private readonly disposed = new WeakSet<object>();
+  /** Remote tracks whose connection is closing: no new view, their wrappers already released. */
+  private readonly detached = new WeakSet<object>();
+  private readonly stopped = new WeakSet<object>();
+  private readonly screens = new WeakSet<object>();
+  /** Streams left unreleased because releasing them would have crashed the app. */
+  leaked = 0;
+  /** Called after a screen track is stopped and released (react-native-webrtc's MediaProjectionService then stops). */
+  onScreenStopped: (() => void) | null = null;
+
+  constructor(private readonly makeStream: (tracks: TrackLike[]) => StreamLike) {}
+
+  /** Keep `stream`, one the platform made (or the app's, `app`), to let go of in the right order. */
+  adopt(stream: StreamLike, role: StreamRole): void {
+    const known = this.entries.get(stream);
+    if (known) {
+      // The app's stream given again (published once more): watched again.
+      if (known.role === 'app' && !known.released) this.live.add(known);
+      return;
+    }
+    const entry: Entry = { stream, role, released: false };
+    this.entries.set(stream, entry);
+    this.live.add(entry);
+  }
+
+  /** A stream of these tracks for the client's own use (ClientPlatform.createStream). */
+  create(tracks: TrackLike[]): StreamLike {
+    const stream = this.makeStream(tracks);
+    this.adopt(stream, 'client');
+    return stream;
+  }
+
+  /** The tracks of `stream` are a screen capture's. */
+  markScreen(stream: StreamLike): void {
+    for (const track of stream.getTracks()) this.screens.add(track);
+  }
+
+  /** Release `stream` without its tracks (ClientPlatform.releaseStream). Again does nothing. */
+  release(stream: StreamLike): void {
+    let entry = this.entries.get(stream);
+    if (!entry) {
+      // Not one made here: released the same careful way.
+      entry = { stream, role: 'client', released: false };
+      this.entries.set(stream, entry);
+    }
+    this.releaseEntry(entry);
+  }
+
+  /**
+   * Stop and release `track` (ClientPlatform.stopTrack): its view wrappers are released and it leaves every stream
+   * kept here first (made here, or the app's adopted), while the native track still exists. Again does nothing. A
+   * remote track is only let go of: its connection owns it.
+   */
+  stop(track: TrackLike): void {
+    if (this.stopped.has(track)) return;
+    this.stopped.add(track);
+    this.dropViews(track);
+    const safe = !this.unsafe(track);
+    for (const entry of [...this.live]) {
+      if (entry.role === 'view' || !entry.stream.getTracks().includes(track)) continue;
+      // A track the native side can no longer find stays where it is: the stream is then left, never released.
+      if (safe) {
+        try {
+          entry.stream.removeTrack(track);
+        } catch (err) {
+          logError('could not take a track out of a stream', err);
+        }
+      }
+      if (entry.stream.getTracks().length > 0) continue;
+      if (entry.role === 'capture') this.releaseEntry(entry);
+      // The app's, now empty: nothing in it can crash its release, which is the app's to do.
+      else if (entry.role === 'app') this.live.delete(entry);
+    }
+    if (track.remote) return;
+    try {
+      track.stop();
+    } catch (err) {
+      logError('could not stop a track', err);
+    }
+    try {
+      track.release?.();
+    } catch (err) {
+      logError('could not release a track', err);
+    }
+    this.disposed.add(track);
+    if (this.screens.has(track)) {
+      try {
+        this.onScreenStopped?.();
+      } catch (err) {
+        logError('could not stop the screen-share service', err);
+      }
+    }
+  }
+
+  /**
+   * The client is about to close what receives these remote tracks (ClientPlatform.detachTracks): release their
+   * wrappers now, while their peer connection still exists, and make no new ones.
+   */
+  detach(tracks: readonly TrackLike[]): void {
+    for (const track of tracks) {
+      this.dropViews(track);
+      this.detached.add(track);
+    }
+  }
+
+  /** A view of `track` (VideoTrack), or null when it cannot be shown: ended, stopped or detached. */
+  view(track: TrackLike): ViewHandle | null {
+    if (this.stopped.has(track) || this.detached.has(track) || this.unsafe(track) || track.readyState === 'ended') return null;
+    let view = this.views.get(track);
+    if (!view) {
+      let stream: StreamLike;
+      try {
+        stream = this.makeStream([track]);
+      } catch (err) {
+        logError('could not make a stream to show a track', err);
+        return null;
+      }
+      const entry: Entry = { stream, role: 'view', released: false };
+      this.entries.set(stream, entry);
+      this.live.add(entry);
+      view = { entry, refs: 0, ended: new Set() };
+      this.views.set(track, view);
+    }
+    view.refs += 1;
+    const held = view;
+    let done = false;
+    return {
+      url: held.entry.stream.toURL(),
+      onEnd: (listener) => {
+        held.ended.add(listener);
+        return () => {
+          held.ended.delete(listener);
+        };
+      },
+      release: () => {
+        if (done) return;
+        done = true;
+        held.refs -= 1;
+        if (held.refs > 0 || this.views.get(track) !== held) return;
+        this.views.delete(track);
+        this.releaseEntry(held.entry);
+      },
+    };
+  }
+
+  /** How many streams made here are not released yet, how many tracks have views, and how many were left unreleased. */
+  stats(): { live: number; views: number; leaked: number } {
+    return { live: this.live.size, views: this.views.size, leaked: this.leaked };
+  }
+
+  /** A track the native side may no longer have: disposed here, or remote and ended (its connection closed). */
+  private unsafe(track: TrackLike): boolean {
+    return this.disposed.has(track) || (track.remote === true && track.readyState === 'ended');
+  }
+
+  private dropViews(track: TrackLike): void {
+    const view = this.views.get(track);
+    if (!view) return;
+    this.views.delete(track);
+    this.releaseEntry(view.entry);
+    for (const listener of [...view.ended]) {
+      try {
+        listener();
+      } catch (err) {
+        logError('listener for viewEnded threw', err);
+      }
+    }
+  }
+
+  private releaseEntry(entry: Entry): void {
+    if (entry.released) return;
+    entry.released = true;
+    this.live.delete(entry);
+    // A view's track that ended may have been released outside this package (an app's own stop() and release()),
+    // which only its end shows: its wrapper is left too. Views of live tracks are let go while their tracks live.
+    const hazard = entry.role === 'view'
+      ? (track: TrackLike) => this.unsafe(track) || track.readyState === 'ended'
+      : (track: TrackLike) => this.unsafe(track);
+    if (entry.stream.getTracks().some(hazard)) {
+      // Released, it would dispose a native stream that still holds a disposed track, and the app would die.
+      this.leaked += 1;
+      return;
+    }
+    try {
+      entry.stream.release(false);
+    } catch (err) {
+      logError('could not release a media stream', err);
+    }
+  }
+}
+
+let shared: StreamBook | null = null;
+
+/** The process's book of streams (one for every client and view). */
+export function streamBook(): StreamBook {
+  if (!shared) {
+    shared = new StreamBook((tracks) => {
+      const webrtc = loadWebRTC();
+      if (!webrtc) throw webrtcMissing();
+      return new webrtc.MediaStream(tracks as unknown as ConstructorParameters<typeof RNMediaStream>[0] & object) as unknown as StreamLike;
+    });
+  }
+  return shared;
+}

package/src/platform/timers.ts

@@ -0,0 +1,72 @@
+/**
+ * The timers the client's own work runs on (reconnect backoff, socket liveness, request deadlines, sampling).
+ *
+ * React Native's JavaScript timers run on Choreographer frames, which stop when the app leaves the foreground, when
+ * the screen goes off even with the app in front, and while a permission dialog is open (Phase 0 S5): a call whose
+ * timers stop cannot notice a dead socket or reconnect. On Android they wait natively instead (the module's
+ * timerStart/timerStop on a thread of their own) and fire back through its onTimer event, which reaches JavaScript
+ * whether frames run or not. Without the native module (iOS, Expo Go) they are JavaScript's own.
+ */
+import type { PlatformTimers } from '@voltkit-rtc/client';
+import type { Spec } from '../specs/NativeVoltkitRtc';
+import { listen } from '../native';
+import { logError } from '../errors';
+
+/** JavaScript's own timers, looked up at each call (a test's fake clock replaces them, and is used). */
+export const jsTimers: PlatformTimers = Object.freeze({
+  setTimeout: (fn: () => void, ms: number): unknown => setTimeout(fn, ms),
+  clearTimeout: (handle: unknown): void => clearTimeout(handle as ReturnType<typeof setTimeout>),
+  setInterval: (fn: () => void, ms: number): unknown => setInterval(fn, ms),
+  clearInterval: (handle: unknown): void => clearInterval(handle as ReturnType<typeof setInterval>),
+});
+
+interface Pending {
+  fn: () => void;
+  repeat: boolean;
+}
+
+/**
+ * Timers that wait natively. Ids are this side's and never reused, so a fire already on its way for a timer stopped
+ * since is recognised and ignored. One onTimer subscription for the whole process.
+ */
+export function nativeTimers(module: Spec): PlatformTimers {
+  const pending = new Map<number, Pending>();
+  let next = 0;
+  let subscribed = false;
+
+  const fire = (id: number) => {
+    const timer = pending.get(id);
+    if (!timer) return;
+    if (!timer.repeat) pending.delete(id);
+    try {
+      timer.fn();
+    } catch (err) {
+      logError('a timer callback threw', err);
+    }
+  };
+
+  const start = (fn: () => void, ms: number, repeat: boolean): number => {
+    if (!subscribed) {
+      subscribed = true;
+      listen(module.onTimer, 'onTimer', fire);
+    }
+    next += 1;
+    const id = next;
+    pending.set(id, { fn, repeat });
+    const delay = typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? ms : 0;
+    module.timerStart(id, delay, repeat);
+    return id;
+  };
+
+  const stop = (handle: unknown) => {
+    if (typeof handle !== 'number' || !pending.delete(handle)) return;
+    module.timerStop(handle);
+  };
+
+  return Object.freeze({
+    setTimeout: (fn: () => void, ms: number): unknown => start(fn, ms, false),
+    clearTimeout: stop,
+    setInterval: (fn: () => void, ms: number): unknown => start(fn, ms, true),
+    clearInterval: stop,
+  });
+}

package/src/platform/visibility.ts

@@ -0,0 +1,59 @@
+/**
+ * Whether the app can be seen, for the background pause, adaptive stream and the call service.
+ *
+ * Android: from the process lifecycle (the native module's isAppVisible / onAppVisibilityChanged, ProcessLifecycleOwner):
+ * the app is visible while any of its activities is started. React Native's AppState is not used there: it says
+ * `background` while a permission dialog or the screen-share consent is open over the app (Phase 0 S8), which would
+ * pause the camera for a dialog.
+ *
+ * iOS (preview) and Android without the native module: AppState, with `inactive` (a call banner, the app switcher
+ * opening) counted as visible.
+ */
+import { AppState, type AppStateStatus } from 'react-native';
+import type { Spec } from '../specs/NativeVoltkitRtc';
+import { listen } from '../native';
+import { logError } from '../errors';
+
+export interface Visibility {
+  visible(): boolean;
+  /** Hear every change; returns the function that stops. */
+  subscribe(listener: (visible: boolean) => void): () => void;
+}
+
+const shown = (state: AppStateStatus | string | null | undefined): boolean => state !== 'background';
+
+/** From the process lifecycle (Android). */
+export function nativeVisibility(module: Spec): Visibility {
+  return {
+    visible: () => {
+      try {
+        return module.isAppVisible();
+      } catch (err) {
+        logError('could not read the app\'s visibility', err);
+        return true;
+      }
+    },
+    subscribe: (listener) => listen(module.onAppVisibilityChanged, 'onAppVisibilityChanged', (e) => listener(e.visible)),
+  };
+}
+
+/** From AppState: `active` and `inactive` are visible, `background` is not. */
+export function appStateVisibility(): Visibility {
+  return {
+    visible: () => shown(AppState.currentState),
+    subscribe: (listener) => {
+      let last = shown(AppState.currentState);
+      const subscription = AppState.addEventListener('change', (state) => {
+        const now = shown(state);
+        if (now === last) return;
+        last = now;
+        try {
+          listener(now);
+        } catch (err) {
+          logError('listener for appVisibility threw', err);
+        }
+      });
+      return () => subscription?.remove();
+    },
+  };
+}

package/src/preflight.ts

@@ -0,0 +1,60 @@
+/**
+ * The pre-call check on React Native: @voltkit-rtc/client's preflight with this package's platform. It joins the room
+ * the token names, publishes for a few seconds, measures and leaves, and never rejects: offline, a refused permission,
+ * a bad token or a missing native module all give a report whose steps say what failed.
+ *
+ * React Native cannot make a test tone or picture. Without `options.media` the check publishes the microphone, which
+ * it captures itself once joined (so nothing opens the microphone for a join that fails) and releases at the end. It
+ * never asks for the permission: where it is not granted, the join is still tested and the media step says why.
+ * Android shows its microphone indicator for those seconds.
+ */
+import { StreamClient, type PreflightOptions, type PreflightReport } from '@voltkit-rtc/client';
+import { registerVoltkitGlobals } from './globals';
+import { describeError, webrtcMissing } from './errors';
+import { reactNativeClientOptions, type BackgroundOptions } from './create-client';
+
+export interface ReactNativePreflightOptions extends PreflightOptions {
+  /** The test client's background pause (as createClient's). */
+  background?: BackgroundOptions;
+}
+
+/** A report for a check that could not even start. */
+function failed(error: unknown): PreflightReport {
+  return {
+    ok: false,
+    steps: [{ name: 'join', ok: false, ms: null, error: describeError(error) }],
+    path: null,
+    rttMs: null,
+    lossPct: null,
+    uploadKbps: null,
+    level: null,
+    warnings: [],
+  };
+}
+
+/**
+ * What the client's check reads from `options.media` on a platform that cannot copy tracks: which devices to capture
+ * again once joined (it never publishes the app's own tracks, which its close would stop). One microphone, the default
+ * one, and no camera; nothing native behind it.
+ */
+const MICROPHONE_TRACK = Object.freeze({ kind: 'audio', getSettings: () => ({}) });
+const MICROPHONE_FOR_TEST = Object.freeze({
+  getTracks: () => [MICROPHONE_TRACK],
+  getAudioTracks: () => [MICROPHONE_TRACK],
+  getVideoTracks: () => [],
+});
+
+/** Test the connection and the media path before a call. Never rejects. */
+export async function preflight(wsUrl: string, token: string, options: ReactNativePreflightOptions = {}): Promise<PreflightReport> {
+  if (!registerVoltkitGlobals()) return failed(webrtcMissing());
+  const { background, clientOptions, ...rest } = options;
+  try {
+    return await StreamClient.preflight(wsUrl, token, {
+      ...rest,
+      media: rest.media ?? (MICROPHONE_FOR_TEST as unknown as PreflightOptions['media']),
+      clientOptions: reactNativeClientOptions({ background, clientOptions }),
+    });
+  } catch (err) {
+    return failed(err);
+  }
+}

package/src/provider.tsx

@@ -0,0 +1,88 @@
+/**
+ * VoltkitProvider for React Native: @voltkit-rtc/react's provider (the same props, token hand-over and StrictMode
+ * behaviour, so every re-exported hook works below it) making its client with this package's platform, plus what a call
+ * needs from the device: the call audio, the call service and the background pause.
+ *
+ * In Expo Go, or an app not rebuilt after installing react-native-webrtc, no client is made: onError gets
+ * `media-unavailable` with `{ reason: 'webrtc-missing' }` (it needs a development build) and the hooks keep their
+ * defaults. Nothing throws.
+ */
+import { useEffect, useMemo, useRef, type ReactElement } from 'react';
+import { Platform } from 'react-native';
+import { VoltkitProvider as ReactVoltkitProvider, type VoltkitProviderProps as ReactVoltkitProviderProps } from '@voltkit-rtc/react';
+import { registerVoltkitGlobals } from './globals';
+import { nativeModule } from './native';
+import { nativeMissing, webrtcMissing } from './errors';
+import { reactNativeClientOptions, type BackgroundOptions } from './create-client';
+import { NativeSession, type AudioSessionOptions, type CallServiceText } from './native-session';
+
+export interface VoltkitProviderProps extends ReactVoltkitProviderProps {
+  /**
+   * The call audio (Android): held from the join to the close -- the audio mode, focus and routing -- with the
+   * loudspeaker unless `speakerphone: false` (the earpiece) or setSpeakerphoneOn chose. `false`, or `manage: false`,
+   * leaves the device's audio to the app. Default `{ speakerphone: true, manage: true }`.
+   */
+  audio?: AudioSessionOptions | false;
+  /**
+   * The background pause, read when the client is made: the camera goes off in the background and comes back with the
+   * app (default `pauseCamera: true`); the microphone keeps going (`pauseMic: false`). Your `clientOptions` win.
+   */
+  background?: BackgroundOptions;
+  /**
+   * The call service (Android): a foreground service that keeps the call's network and microphone alive in the
+   * background and with the screen off. Started on the join when the app's manifest declares it (the Expo plugin's
+   * callService, default on), with this notification; `false` never starts it. Default true.
+   */
+  callService?: boolean | CallServiceText;
+}
+
+/** One StreamClient for the components below, with the device's audio, the call service and the background pause. */
+export function VoltkitProvider({
+  audio,
+  background,
+  callService,
+  clientOptions,
+  client,
+  wsUrl,
+  token,
+  onError,
+  children,
+  ...rest
+}: VoltkitProviderProps): ReactElement {
+  const webrtc = useMemo(() => registerVoltkitGlobals(), []);
+  const errors = useRef(onError);
+  useEffect(() => {
+    errors.current = onError;
+  });
+
+  const wanted = Boolean(client || (wsUrl && token));
+  useEffect(() => {
+    if (!wanted) return;
+    if (!webrtc) errors.current?.(webrtcMissing());
+    else if (Platform.OS === 'android' && !nativeModule()) errors.current?.(nativeMissing('Background calls, audio routing and native timers'));
+  }, [webrtc, wanted]);
+
+  // Read when the provider makes a client, as @voltkit-rtc/react reads clientOptions: a later change does not remake it.
+  const options = useMemo(
+    () => (webrtc ? reactNativeClientOptions({ background, clientOptions }) : undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [webrtc, wsUrl, token],
+  );
+  // The call service reads the setting from the client it runs for (an app-made client has its own); this stands in
+  // when the client's options cannot be read.
+  const pauseCamera = options?.pauseCameraInBackground === true;
+
+  return (
+    <ReactVoltkitProvider
+      {...rest}
+      wsUrl={webrtc ? wsUrl : undefined}
+      token={webrtc ? token : undefined}
+      client={webrtc ? client : null}
+      clientOptions={options}
+      onError={onError}
+    >
+      {webrtc ? <NativeSession audio={audio} callService={callService} pauseCamera={pauseCamera} onError={errors} /> : null}
+      {children}
+    </ReactVoltkitProvider>
+  );
+}