@mentra/engine 3.2.0-dev.226 → 3.2.0-dev.227

package/build/services/PhoneStreamCoordinator.js

@@ -33,9 +33,11 @@
  *   An explicit stop that could not reach BLE is sent on the next reconnect.
  */
 import BluetoothSdk from "@mentra/bluetooth-sdk/internal";
+import { createManagedWebRtcRelay } from "./ManagedWebRtcRelay";
 import { isGlassesConnected } from "./GlassesReadiness";
 import { phoneCameraFovCoordinator } from "./PhoneCameraFovCoordinator";
 import { useGlassesStore } from "../stores/glasses";
+import { BgTimer } from "../utils/timers";
 import { slimStreamStatusEvent, streamStatusSignature } from "./slimStreamStatus";
 import { getManagedStreamStatus, provisionManagedStream, teardownManagedStream, } from "./cloudStreamApi";
 /**
@@ -88,6 +90,7 @@ export class PhoneStreamCoordinator {
     statusSubscriber = null;
     idCounter = 0;
     timings;
+    relayFactory;
     linkSource;
     pendingCameraChanges;
     unsubscribeLink = null;
@@ -113,6 +116,7 @@ export class PhoneStreamCoordinator {
     /** Send full resolvedConfig only once per stream session. */
     resolvedConfigForwarded = false;
     constructor(timings = {}, deps = {}) {
+        this.relayFactory = deps.relayFactory ?? createManagedWebRtcRelay;
         this.timings = { ...DEFAULT_TIMINGS, ...timings };
         this.linkSource = deps.linkSource ?? storeLinkSource;
         this.pendingCameraChanges = deps.pendingCameraChanges ?? (() => phoneCameraFovCoordinator.whenSettled());
@@ -162,7 +166,8 @@ export class PhoneStreamCoordinator {
      * check covers the multi-subscriber case.
      */
     owns(streamId) {
-        return this.current !== null && this.current.streamId === streamId;
+        return (this.current !== null &&
+            (this.current.streamId === streamId || (this.current.kind === "managed" && !!this.current.relay?.owns(streamId))));
     }
     /** Report-safe stream ownership snapshot for incident diagnostics. */
     getDiagnosticSnapshot() {
@@ -203,6 +208,7 @@ export class PhoneStreamCoordinator {
         return this.runExclusive(async () => {
             await cameraReady;
             this.assertGlassesConnected();
+            await this.flushPendingBleStop();
             if (this.current) {
                 throw new StreamConflictError("STREAM_ALREADY_ACTIVE", `A ${this.current.kind} stream is already active. Stop it before starting a new one.`);
             }
@@ -259,12 +265,18 @@ export class PhoneStreamCoordinator {
         const decision = await this.runExclusive(async () => {
             await cameraReady;
             this.assertGlassesConnected();
+            await this.flushPendingBleStop();
             if (this.current && this.current.kind === "unmanaged") {
                 throw new StreamConflictError("STREAM_ALREADY_ACTIVE", "An unmanaged stream is already active. Stop it before starting a managed stream.");
             }
             // Join an existing managed stream if one is already running.
             if (this.current && this.current.kind === "managed") {
                 const existing = this.current;
+                if (existing.stopping)
+                    throw new StreamConflictError("STREAM_CLEANUP_PENDING", "Previous stream cleanup has not completed; retry stop first");
+                if (opts.ingest !== undefined && (opts.ingest === "whip") !== (existing.mode === "webrtc")) {
+                    throw new StreamConflictError("STREAM_MODE_CONFLICT", "Stop the existing stream before switching playback modes");
+                }
                 // Restream destinations are immutable after provision — a second
                 // caller trying to dictate destinations on an already-live stream
                 // is a likely bug or a feature we don't yet support.
@@ -280,7 +292,14 @@ export class PhoneStreamCoordinator {
             // and joins instead of double-provisioning.
             const provision = await provisionManagedStream(opts.restreamDestinations);
             const streamId = this.mintId("m");
-            const ingestUrl = pickIngestUrl(provision, opts.ingest);
+            let ingestUrl;
+            try {
+                ingestUrl = pickIngestUrl(provision, opts.ingest);
+            }
+            catch (error) {
+                await teardownManagedStream(provision.liveInputId).catch(() => undefined);
+                throw error;
+            }
             const mode = ingestUrl === provision.webrtcPublishUrl ? "webrtc" : "hls";
             const entry = {
                 kind: "managed",
@@ -307,17 +326,35 @@ export class PhoneStreamCoordinator {
                 elapsedMs: Date.now() - startupStartedAtMs,
             });
             try {
-                const event = await BluetoothSdk.startStream({
-                    type: "start_stream",
-                    streamUrl: ingestUrl,
-                    streamId,
-                    sound: opts.sound ?? true,
-                    // See startUnmanaged: the native bridge rejects explicit `undefined`.
-                    ...(opts.video !== undefined ? { video: opts.video } : {}),
-                    ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
-                    ...(typeof opts.captureAudio === "boolean" ? { captureAudio: opts.captureAudio } : {}),
-                });
-                entry.publisherStart = publisherStartResult(streamId, event);
+                if (mode === "webrtc") {
+                    entry.relay = this.relayFactory({ streamId, ingestUrl, ...opts }, (status, reason) => {
+                        if (this.current === entry && !entry.stopping)
+                            this.fanout({ streamId, source: "coordinator", status, data: { reason, transport: "softap_relay" } });
+                    }, (error) => {
+                        void this.runExclusive(async () => {
+                            if (this.current !== entry)
+                                return;
+                            this.fanout({ streamId, source: "coordinator", status: "error", data: { reason: error.message } });
+                            await this.teardownLocked("relay_failed");
+                        }).catch((cleanupError) => console.warn("[STREAM] relay cleanup failed", cleanupError));
+                    }, () => this.linkSource.isConnected(), () => {
+                        this.pendingBleStop = { streamId, hotspot: true };
+                        this.attachLink();
+                    });
+                }
+                const event = entry.relay
+                    ? await entry.relay.start()
+                    : await BluetoothSdk.startStream({
+                        type: "start_stream",
+                        streamUrl: ingestUrl,
+                        streamId,
+                        sound: opts.sound ?? true,
+                        // See startUnmanaged: the native bridge rejects explicit `undefined`.
+                        ...(opts.video !== undefined ? { video: opts.video } : {}),
+                        ...(opts.audio !== undefined ? { audio: opts.audio } : {}),
+                        ...(typeof opts.captureAudio === "boolean" ? { captureAudio: opts.captureAudio } : {}),
+                    });
+                entry.publisherStart = { ...publisherStartResult(streamId, event), streamId };
                 console.info("[STREAM_STARTUP]", {
                     streamId,
                     stage: "publisher_ready",
@@ -326,8 +363,15 @@ export class PhoneStreamCoordinator {
                 });
             }
             catch (err) {
-                this.current = null;
-                await teardownManagedStream(provision.liveInputId).catch(() => undefined);
+                entry.stopping = true;
+                try {
+                    await entry.relay?.stop();
+                    this.current = null;
+                    await this.flushPendingBleStop();
+                }
+                finally {
+                    await teardownManagedStream(provision.liveInputId).catch(() => undefined);
+                }
                 throw err;
             }
             this.startLifecycle(streamId);
@@ -340,6 +384,9 @@ export class PhoneStreamCoordinator {
             }
             return { kind: "fresh", entry };
         });
+        if (this.current !== decision.entry || decision.entry.stopping) {
+            throw new Error("Stream stopped before playback readiness");
+        }
         if (decision.kind === "join" && decision.immediate) {
             return decision.immediate;
         }
@@ -357,6 +404,13 @@ export class PhoneStreamCoordinator {
         });
     }
     async stop(packageName, streamId) {
+        // Cancel in-flight native preparation immediately; cleanup remains serialized below.
+        const pending = this.current;
+        if (pending?.kind === "managed" &&
+            (!streamId || pending.streamId === streamId) &&
+            pending.subscribers.size === 1 &&
+            pending.subscribers.has(packageName))
+            pending.relay?.cancel();
         await this.runExclusive(async () => {
             if (!this.current)
                 return;
@@ -386,6 +440,10 @@ export class PhoneStreamCoordinator {
     handleGlassesStatus(event) {
         if (!this.current)
             return;
+        if (this.current.kind === "managed" && this.current.relay) {
+            this.current.relay.handleGlassesStatus(event);
+            return;
+        }
         if (event.streamId && event.streamId !== this.current.streamId)
             return;
         const includeResolvedConfig = !this.resolvedConfigForwarded && !!event.resolvedConfig;
@@ -415,13 +473,7 @@ export class PhoneStreamCoordinator {
         if (event.terminal === true || isGiveUp || isStopped) {
             const reason = isGiveUp ? "glasses_gave_up" : event.status === "error" ? "glasses_error" : "glasses_stopped";
             const targetStreamId = this.current.streamId;
-            void this.runExclusive(async () => {
-                // The stream we wanted to tear down may already be gone (e.g. another
-                // teardown won the lock and unwound it). Guard before acting.
-                if (this.current?.streamId !== targetStreamId)
-                    return;
-                await this.teardownLocked(reason, { sendBleStop: false });
-            });
+            this.requestTeardown(targetStreamId, reason, { sendBleStop: false });
         }
     }
     // ===========================================================================
@@ -444,7 +496,7 @@ export class PhoneStreamCoordinator {
                 this.resumeLocked();
             }
             else if (!this.current && this.pendingBleStop) {
-                this.flushPendingBleStop();
+                void this.runExclusive(() => this.flushPendingBleStop()).catch((error) => console.warn("[STREAM] deferred cleanup failed", error));
             }
             return;
         }
@@ -456,7 +508,7 @@ export class PhoneStreamCoordinator {
         if (!entry)
             return;
         const since = Date.now();
-        const graceTimer = setTimeout(() => this.onGraceExpired(entry.streamId), this.timings.glassesGraceMs);
+        const graceTimer = BgTimer.setTimeout(() => this.onGraceExpired(entry.streamId), this.timings.glassesGraceMs);
         this.suspended = { since, graceTimer, publisherGoneProbes: 0 };
         console.warn("[STREAM] BLE link lost; stream suspended", {
             streamId: entry.streamId,
@@ -474,7 +526,7 @@ export class PhoneStreamCoordinator {
         const suspended = this.suspended;
         if (!entry || !suspended)
             return;
-        clearTimeout(suspended.graceTimer);
+        BgTimer.clearTimeout(suspended.graceTimer);
         this.suspended = null;
         const suspendedMs = Date.now() - suspended.since;
         console.info("[STREAM] BLE link back; stream resumed", { streamId: entry.streamId, suspendedMs });
@@ -504,21 +556,35 @@ export class PhoneStreamCoordinator {
             status: "error",
             data: { reason: LINK_STATUS.reason, teardownReason: reason, ...detail },
         });
+        this.requestTeardown(streamId, reason);
+    }
+    /** Event/timer failures have no awaiting caller; retain and report cleanup errors locally. */
+    requestTeardown(streamId, reason, options = {}) {
         void this.runExclusive(async () => {
             if (this.current?.streamId !== streamId)
                 return;
-            await this.teardownLocked(reason);
+            await this.teardownLocked(reason, options);
+        }).catch((error) => {
+            console.warn("[STREAM] cleanup failed", error);
+            if (this.current?.streamId === streamId) {
+                this.fanout({ streamId, source: "coordinator", status: "error", data: { reason: "cleanup_failed" } });
+            }
         });
     }
-    flushPendingBleStop() {
+    async flushPendingBleStop() {
         const pending = this.pendingBleStop;
-        if (!pending)
+        if (!pending || this.current || !this.linkSource.isConnected())
             return;
-        this.pendingBleStop = null;
         console.info("[STREAM] BLE link back; sending deferred stopStream", pending);
-        void BluetoothSdk.stopStream()
-            .catch((err) => console.warn("[STREAM] deferred stopStream failed:", err))
-            .finally(() => this.detachLinkIfIdle());
+        await BluetoothSdk.stopStream();
+        if (pending.hotspot) {
+            const result = await BluetoothSdk.setHotspotState(false);
+            if (result.state !== "disabled")
+                throw new Error("Deferred hotspot shutdown was not confirmed");
+        }
+        if (this.pendingBleStop === pending)
+            this.pendingBleStop = null;
+        this.detachLinkIfIdle();
     }
     // ===========================================================================
     // Internal
@@ -540,23 +606,25 @@ export class PhoneStreamCoordinator {
         const connectTimeoutMs = Math.max(1, this.timings.hlsReadinessMaxAttempts * this.timings.hlsReadinessPollMs);
         const pollingStartedAtMs = Date.now();
         const scheduleNext = () => {
-            if (this.current !== entry)
+            if (this.current !== entry || entry.stopping)
                 return;
             const waitingForWebRtc = entry.mode === "webrtc" && !entry.hlsReady;
             const elapsedMs = Date.now() - pollingStartedAtMs;
             const remainingMs = Math.max(0, connectTimeoutMs - elapsedMs);
             const startupDelayMs = Math.min(this.timings.cloudflareStatusPollMs, this.timings.cloudflareStartupPollInitialMs * 2 ** Math.min(Math.max(0, entry.cloudflareAttempts - 1), 10));
             const delayMs = waitingForWebRtc ? Math.min(startupDelayMs, remainingMs) : this.timings.cloudflareStatusPollMs;
-            entry.cloudflareTimer = setTimeout(() => void poll(), delayMs);
+            entry.cloudflareTimer = BgTimer.setTimeout(() => void poll(), delayMs);
         };
         const poll = async () => {
-            if (this.current !== entry)
+            if (this.current !== entry || entry.stopping)
                 return;
             const requestStartedAtMs = Date.now();
             let keepPolling = true;
             entry.cloudflareAttempts += 1;
             try {
                 const status = await getManagedStreamStatus(entry.liveInputId);
+                if (this.current !== entry || entry.stopping)
+                    return;
                 console.debug("[STREAM_STARTUP]", {
                     streamId: entry.streamId,
                     stage: "cloudflare_probe",
@@ -625,17 +693,15 @@ export class PhoneStreamCoordinator {
                                 data: { reason: "webrtc_not_connected" },
                             });
                             const targetStreamId = entry.streamId;
-                            void this.runExclusive(async () => {
-                                if (this.current?.streamId !== targetStreamId)
-                                    return;
-                                await this.teardownLocked("webrtc_not_connected");
-                            });
+                            this.requestTeardown(targetStreamId, "webrtc_not_connected");
                             keepPolling = false;
                         }
                     }
                 }
             }
             catch (err) {
+                if (this.current !== entry || entry.stopping)
+                    return;
                 console.warn("[STREAM] cloudflare status poll failed:", err);
                 if (entry.mode === "webrtc" && !entry.hlsReady && Date.now() - pollingStartedAtMs >= connectTimeoutMs) {
                     const timeoutErr = new Error(`WebRTC ingest status could not be confirmed after ${connectTimeoutMs}ms`);
@@ -644,11 +710,7 @@ export class PhoneStreamCoordinator {
                     entry.hlsReadyResolvers = [];
                     entry.hlsReadyRejecters = [];
                     const targetStreamId = entry.streamId;
-                    void this.runExclusive(async () => {
-                        if (this.current?.streamId !== targetStreamId)
-                            return;
-                        await this.teardownLocked("webrtc_status_unavailable");
-                    });
+                    this.requestTeardown(targetStreamId, "webrtc_status_unavailable");
                     keepPolling = false;
                 }
             }
@@ -665,7 +727,7 @@ export class PhoneStreamCoordinator {
         // Skip the first few seconds — Cloudflare doesn't have first-frame yet,
         // and the HEAD requests would all 404 and burn battery.
         const tick = async () => {
-            if (this.current !== entry)
+            if (this.current !== entry || entry.stopping)
                 return;
             entry.hlsAttempts += 1;
             try {
@@ -673,6 +735,8 @@ export class PhoneStreamCoordinator {
                 // playback edge returns 204 No Content while the input has no
                 // HLS-capable frames (e.g. WebRTC ingest), and 204 is "ok".
                 const res = await fetch(entry.hlsUrl, { method: "HEAD" });
+                if (this.current !== entry || entry.stopping)
+                    return;
                 if (res.status === 200) {
                     entry.hlsReady = true;
                     console.info("[STREAM_STARTUP]", {
@@ -683,7 +747,7 @@ export class PhoneStreamCoordinator {
                         elapsedMs: Date.now() - entry.startupStartedAtMs,
                     });
                     if (entry.hlsTimer) {
-                        clearInterval(entry.hlsTimer);
+                        BgTimer.clearInterval(entry.hlsTimer);
                         entry.hlsTimer = undefined;
                     }
                     const result = managedStartResult(entry);
@@ -705,7 +769,7 @@ export class PhoneStreamCoordinator {
             }
             if (entry.hlsAttempts >= this.timings.hlsReadinessMaxAttempts) {
                 if (entry.hlsTimer) {
-                    clearInterval(entry.hlsTimer);
+                    BgTimer.clearInterval(entry.hlsTimer);
                     entry.hlsTimer = undefined;
                 }
                 const err = new Error(`HLS playback URL did not become ready after ${this.timings.hlsReadinessMaxAttempts} attempts`);
@@ -720,18 +784,14 @@ export class PhoneStreamCoordinator {
                     data: { reason: "hls_not_ready" },
                 });
                 const targetStreamId = entry.streamId;
-                void this.runExclusive(async () => {
-                    if (this.current?.streamId !== targetStreamId)
-                        return;
-                    await this.teardownLocked("hls_not_ready");
-                });
+                this.requestTeardown(targetStreamId, "hls_not_ready");
             }
         };
-        setTimeout(() => {
+        BgTimer.setTimeout(() => {
             // Guard: stream may have been torn down during the initial delay.
-            if (this.current !== entry)
+            if (this.current !== entry || entry.stopping)
                 return;
-            entry.hlsTimer = setInterval(tick, this.timings.hlsReadinessPollMs);
+            entry.hlsTimer = BgTimer.setInterval(tick, this.timings.hlsReadinessPollMs);
         }, this.timings.hlsReadinessInitialDelayMs);
     }
     fanout(update) {
@@ -762,24 +822,25 @@ export class PhoneStreamCoordinator {
         this.lastFanoutSignature = null;
         this.resolvedConfigForwarded = false;
         if (this.suspended) {
-            clearTimeout(this.suspended.graceTimer);
+            BgTimer.clearTimeout(this.suspended.graceTimer);
             this.suspended = null;
         }
         // With the link down a BLE write can only fail (and hold the transition
         // lock for the native timeout). Defer it to the next reconnect instead.
         const linkUp = this.linkSource.isConnected();
         if (sendBleStop && !linkUp) {
-            this.pendingBleStop = { streamId: entry.streamId };
+            this.pendingBleStop = { streamId: entry.streamId, hotspot: entry.kind === "managed" && !!entry.relay };
             console.warn("[STREAM] BLE link down during teardown; stopStream deferred", {
                 streamId: entry.streamId,
                 reason,
             });
         }
         if (entry.kind === "managed") {
+            entry.stopping = true;
             if (entry.cloudflareTimer)
-                clearTimeout(entry.cloudflareTimer);
+                BgTimer.clearTimeout(entry.cloudflareTimer);
             if (entry.hlsTimer)
-                clearInterval(entry.hlsTimer);
+                BgTimer.clearInterval(entry.hlsTimer);
             // Reject any still-pending HLS readiness waiters.
             const pendingErr = new Error(`Stream torn down: ${reason}`);
             for (const reject of entry.hlsReadyRejecters)
@@ -787,8 +848,12 @@ export class PhoneStreamCoordinator {
             entry.hlsReadyResolvers = [];
             entry.hlsReadyRejecters = [];
         }
+        // Relay stop owns the BLE publisher, native peers and hotspot. Keep the entry on failure
+        // so another start cannot acquire resources whose teardown has not been confirmed.
+        if (entry.kind === "managed" && entry.relay)
+            await entry.relay.stop();
         try {
-            if (sendBleStop && linkUp) {
+            if (sendBleStop && linkUp && !(entry.kind === "managed" && entry.relay)) {
                 await BluetoothSdk.stopStream();
             }
         }
@@ -802,7 +867,6 @@ export class PhoneStreamCoordinator {
             // serializes us, so this should always be true).
             if (this.current === entry)
                 this.current = null;
-            this.detachLinkIfIdle();
             if (entry.kind === "managed") {
                 // Start remote cleanup only after the publisher has stopped, but do not
                 // hold the local transition lock on an unbounded network request. The
@@ -812,13 +876,16 @@ export class PhoneStreamCoordinator {
                     console.warn("[STREAM] teardownManagedStream failed:", err);
                 });
             }
+            // BLE can recover while native cleanup is draining; no second link event is required.
+            await this.flushPendingBleStop();
+            this.detachLinkIfIdle();
         }
     }
 }
 function pickIngestUrl(p, preference) {
     // Glasses' StreamCommandHandler detects protocol from URL prefix.
     //
-    // Default priority: SRT > RTMP > WHIP. SRT first: Cloudflare's WebRTC (WHIP)
+    // Default priority: SRT > RTMP. WHIP is explicit. SRT first: Cloudflare's WebRTC (WHIP)
     // ingest does NOT feed HLS/DASH playback or recording — a WHIP-ingested
     // managed stream reports "connected" while its hlsUrl serves 204 forever,
     // which breaks the managed contract (subscribers share HLS playback). SRT
@@ -832,11 +899,7 @@ function pickIngestUrl(p, preference) {
     //
     // Throw if none resolved so the caller's Promise rejects with a clear
     // message rather than the glasses' "unknown protocol" error.
-    const url = preference === "whip"
-        ? p.webrtcPublishUrl || p.srtUrl || p.rtmpUrl
-        : preference === "rtmp"
-            ? p.rtmpUrl || p.srtUrl || p.webrtcPublishUrl
-            : p.srtUrl || p.rtmpUrl || p.webrtcPublishUrl;
+    const url = preference === "whip" ? p.webrtcPublishUrl : preference === "rtmp" ? p.rtmpUrl || p.srtUrl : p.srtUrl || p.rtmpUrl;
     if (!url) {
         throw new Error("Cloudflare provision returned no usable ingest URL");
     }