@desklink/react-native 0.2.0 → 0.3.1

package/src/useDesktopSession.ts

@@ -4,6 +4,7 @@ import { AppState } from 'react-native';
 import type { NativeDesklinkModule } from './native';
 import type {
     ControlMessage,
+    CursorSample,
     IceServerConfig,
     Permission,
     SessionFailure,
@@ -54,6 +55,18 @@ const RESTART_REPLY_MS = 5000;
  * 8 s costs nothing next to a live desktop.
  */
 export const REOPEN_BACKOFF_MS = [1000, 2000, 4000, 8000, 8000, 8000, 8000, 8000];
+/**
+ * Away from the foreground this long, the path is presumed dead: ICE consent
+ * lapses after about 30 s (RFC 7675), and the engine then revokes the session.
+ * A return after that reopens at once instead of spending restarts on it.
+ */
+export const BACKGROUND_REOPEN_MS = 30_000;
+/**
+ * A resumed app hears what queued up while it was suspended just after it
+ * hears it is active again. A revocation among it decides whether a reopen is
+ * allowed at all, so the long-absence reopen waits this long for it first.
+ */
+const RESUME_DRAIN_MS = 750;
 
 /** The delay before attempt `n` (0-based), or null when the schedule is spent. */
 export function backoffDelay(schedule: readonly number[], attempt: number): number | null {
@@ -96,12 +109,12 @@ export function connectionStatusFor(
 }
 
 /**
- * Without a relay there is no route between two networks: ICE only ever finds
- * host candidates. A client that cannot reach the desktop is told that plainly
- * rather than left on a spinner.
+ * With no app-supplied ICE servers, ICE only finds host candidates, which need
+ * a directly reachable desktop. A client with no usable route is told that
+ * plainly rather than left on a spinner.
  */
 const UNREACHABLE_DESKTOP =
-    'The phone must reach the desktop directly, on the same network or its tailnet. Other networks need a relay, which is not available yet.';
+    'The phone must reach the desktop directly, on the same network or its tailnet. Other networks need a relay route supplied by the app.';
 
 /**
  * The engine's and host's own refusal tokens, mapped to this package's failure
@@ -166,6 +179,7 @@ export interface DesktopSessionOptions {
      */
     authorize: () => Promise<{ signaling: Signaling; session: SessionOpenRequest }>;
     onStateChange?: (snapshot: SessionSnapshot) => void;
+    onCursor?: (sample: CursorSample) => void;
     onError?: (failure: SessionFailure) => void;
     /**
      * The engine refused one input message and the session carries on, such as
@@ -241,6 +255,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
      * before the native session exists waits here and is replayed into it.
      */
     const pendingOffer = useRef<{ sdp: string; sessionId?: string } | null>(null);
+    const pendingCursorEvents = useRef<CursorSample[]>([]);
     const pendingCandidates = useRef<Array<{ candidate: string; sdpMid: string | null; sdpMLineIndex: number | null; sessionId?: string }>>([]);
     const attempts = useRef(0);
     /**
@@ -275,6 +290,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     /** The latest snapshot; mirrored eagerly so timers read exact state. */
     const snapshotRef = useRef<SessionSnapshot>(IDLE);
     const diagnostics = useRef<Record<string, string | number | boolean>>({});
+    /** When the app left the foreground, or null while it is active. */
+    const awaySince = useRef<number | null>(null);
     /** Guards every asynchronous callback against a session that already ended. */
     const generationToken = useRef(0);
     const optionsRef = useRef(options);
@@ -327,17 +344,20 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const scheduleRestartRef = useRef<(delay: number) => void>(() => undefined);
 
     /**
-     * Spend one restart from the backoff schedule, or stop asking when the
-     * schedule is spent: ICE's own failure then moves the session to a full
-     * reopen. Only refs and module constants, so stable callbacks may hold it.
+     * Spend one restart from the backoff schedule, or reopen when the schedule
+     * is spent: a peer may never report `failed` (a resumed phone often does
+     * not), and waiting for it would leave the session reconnecting forever.
      */
     const spendRestartAttempt = useCallback((): void => {
         if (statusRef.current !== 'reconnecting' || nativeRef.current == null) return;
         const wait = backoffDelay(RESTART_BACKOFF_MS, restartAttempts.current);
-        if (wait === null) return;
+        if (wait === null) {
+            transportFailed('the desktop did not come back; reopening the session');
+            return;
+        }
         restartAttempts.current += 1;
         scheduleRestartRef.current(wait);
-    }, []);
+    }, [transportFailed]);
 
     /**
      * Queue the next ICE restart after `delay`, or do nothing when an attempt
@@ -555,6 +575,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         pendingClipboard.current.clear();
         pendingOffer.current = null;
         pendingCandidates.current = [];
+        pendingCursorEvents.current = [];
         restartGraceUntil.current = 0;
         restartCycles.current = 0;
         opened.current = null;
@@ -598,6 +619,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const establish = useCallback(async () => {
         if (nativeRef.current != null) return;
         const token = ++generationToken.current;
+        pendingCursorEvents.current = [];
         if (!(await loadPlatform())) {
             if (token === generationToken.current) refuse('this build cannot show a desktop surface');
             return;
@@ -655,6 +677,13 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         event.candidate.sdpMLineIndex ?? null,
                     );
                     return;
+                case 'cursor':
+                    if (held == null) {
+                        pendingCursorEvents.current.push(event);
+                        return;
+                    }
+                    if (current) optionsRef.current.onCursor?.(event);
+                    return;
                 case 'state':
                     if (!current) return;
                     diagnostics.current.transport = event.transport;
@@ -670,6 +699,13 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                     // Nothing held: the reopen policy owns recovery, and a
                     // dead session's late revocation must not end it.
                     if (held == null || !current) return;
+                    // A lost path is an outage, not a verdict: the reopen
+                    // policy asks for fresh authority. Any other code, or
+                    // none, is the session's authority ending.
+                    if (event.code === 'transport') {
+                        transportFailed(event.reason);
+                        return;
+                    }
                     void teardown(event.reason, false);
                     update({ status: 'ended', failure: { code: 'revoked', message: event.reason } });
                     return;
@@ -683,6 +719,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             openedResult = await authorization.signaling.request<SessionOpenResult>('session.open', {
                 permissions: authorization.session.permissions,
                 max_width: authorization.session.maxWidth,
+                ...(authorization.session.cursor === undefined ? {} : { cursor: authorization.session.cursor }),
                 max_height: authorization.session.maxHeight,
                 bitrate_kbps: authorization.session.bitrateKbps,
                 max_fps: authorization.session.maxFps,
@@ -701,6 +738,9 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         try {
             if (token !== generationToken.current) return;
             opened.current = openedResult;
+            for (const sample of pendingCursorEvents.current.splice(0)) {
+                if (sample.sessionId === openedResult.sessionId) optionsRef.current.onCursor?.(sample);
+            }
             update({ geometry: openedResult.geometry, status: 'connecting' });
             if (token !== generationToken.current) return;
 
@@ -745,7 +785,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 await endRemote(openedResult, authorization.signaling);
             }
         }
-    }, [discardSession, endRemote, refuse, teardown, update, onTransportState]);
+    }, [discardSession, endRemote, refuse, teardown, transportFailed, update, onTransportState]);
 
     /**
      * Open (or reopen) the session with fresh authority. A deliberate call
@@ -844,7 +884,12 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         if (reply.kind === 'revoked') {
                             // The engine ends the data channel with a revocation when
                             // the session is replaced or closed; it is the only notice
-                            // the client gets, so it has to end the session here.
+                            // the client gets, so it has to end the session here —
+                            // unless the path was lost, which a reopen heals.
+                            if (reply.code === 'transport') {
+                                transportFailed(reply.reason);
+                                return;
+                            }
                             void teardown(reply.reason, false);
                             update({ status: 'ended', failure: { code: 'revoked', message: reply.reason } });
                             return;
@@ -935,6 +980,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         // native handle that makes `connect()` a no-op.
         const owner = signaling.current;
         const openedRef = opened.current;
+        cancelRestart();
         discardSession();
         void endRemote(openedRef, owner);
         const wait = backoffDelay(REOPEN_BACKOFF_MS, attempts.current);
@@ -945,7 +991,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             reconnectTimer.current = null;
             void establish();
         }, wait);
-    }, [establish, discardSession, endRemote, snapshot.status, snapshot.failure, update]);
+    }, [establish, cancelRestart, discardSession, endRemote, snapshot.status, snapshot.failure, update]);
 
     useEffect(() => () => {
         cancelReconnect();
@@ -966,12 +1012,50 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     // A phone that goes to the background must not leave a remote button held:
     // the desktop cannot know the finger left the glass. This is the same
     // release path a lost control channel takes.
+    //
+    // Coming back, a session that was away long enough for the path to lapse
+    // reopens without spending restarts on it, once anything queued has had
+    // a moment to arrive; one already waiting to reopen stops waiting: the
+    // app was suspended, so no timer or peer event can be trusted to have run.
     useEffect(() => {
+        let resumeTimer: ReturnType<typeof setTimeout> | null = null;
         const subscription = AppState.addEventListener('change', (status) => {
-            if (status !== 'active') releaseHeld();
+            if (status !== 'active') {
+                // `inactive` is Control Centre or the app switcher: the app
+                // still runs, so only `background` starts the clock.
+                if (status === 'background') awaySince.current ??= Date.now();
+                releaseHeld();
+                return;
+            }
+            const away = awaySince.current === null ? 0 : Date.now() - awaySince.current;
+            awaySince.current = null;
+            const current = statusRef.current;
+            const waiting = (current === 'reconnecting' && nativeRef.current == null)
+                || (current === 'failed' && snapshotRef.current.failure?.code === 'transport');
+            if (waiting) {
+                cancelReconnect();
+                void connect();
+                return;
+            }
+            const id = nativeRef.current;
+            if (away < BACKGROUND_REOPEN_MS || id == null) return;
+            // ponytail: a fixed drain window; a revocation queued behind it
+            // is dropped with the old session, as any reopen drops one.
+            if (resumeTimer !== null) clearTimeout(resumeTimer);
+            resumeTimer = setTimeout(() => {
+                resumeTimer = null;
+                const now = statusRef.current;
+                if (nativeRef.current !== id) return;
+                if (now !== 'live' && now !== 'connecting' && now !== 'reconnecting') return;
+                attempts.current = 0;
+                transportFailed('the app was in the background; reopening the session');
+            }, RESUME_DRAIN_MS);
         });
-        return () => subscription.remove();
-    }, [releaseHeld]);
+        return () => {
+            if (resumeTimer !== null) clearTimeout(resumeTimer);
+            subscription.remove();
+        };
+    }, [releaseHeld, cancelReconnect, connect, transportFailed]);
 
     return useMemo<DesktopSession>(() => ({
         snapshot,

package/src/webrtc.ios.ts

@@ -0,0 +1,10 @@
+/**
+ * The app's `react-native-webrtc`, evaluated on the first call rather than
+ * with the package: importing the package must not pull the native WebRTC
+ * libraries into the application's first paint. Metro bundles an inline
+ * `require` and runs it only when reached; a require by a name built at
+ * runtime would not be bundled at all.
+ */
+export function requireWebRTC(): unknown {
+    return require('react-native-webrtc');
+}