@3dsource/angular-unreal-module 0.0.161 → 0.0.163

package/README.md

@@ -114,6 +114,15 @@ The `loadChildren()` boundary keeps the streaming engine out of the initial
 bundle. Route-scoping `provideUnrealModule()` tears down its effects when the
 route is left.
 
+> `UNREAL_CONFIG` on a route's `providers` does **not** work: the engine
+> services are `providedIn: 'root'`, so they are created by the root injector
+> and read the token from there. A route-level value is invisible to them and
+> `inject(UNREAL_CONFIG, { optional: true })` resolves to `null` — e.g. region
+> pinging is skipped entirely (empty `regionsPingUrl`), the orchestration
+> `requestStream` goes out without a region and the post-connection re-ping
+> never runs. Importing only the token at the root does not pull the module into
+> the initial bundle (the package is `sideEffects: false`).
+
 ### 3. Render the scene
 
 ```typescript
@@ -174,6 +183,9 @@ The package publishes two dependency-free scripts for use in the document
 `stream-prefetch.js` runs by default only on
 `metabox-configurator/{modular|basic}/...` routes. It reads the same-origin
 `assets/config.json`; override that path with `data-config-url` when needed.
+It also forwards the orchestration-issued `streamRequestId` from the polling
+response to Cirrus on the WebSocket URL (the session `connectionId`) and parks it
+for the Angular side to adopt.
 Pin an exact package version in production when deterministic CDN assets are
 required.
 

package/fesm2022/3dsource-angular-unreal-module.mjs

@@ -479,7 +479,7 @@ const initialState = {
 };
 const unrealReducer = createReducer(initialState, on(changeStatusMainVideoOnScene, (state, { isVideoPlaying }) => {
     return { ...state, isVideoPlaying };
-}), on(setAwsInstance, (state, { instanceName, wsUrl, pollingUrl }) => {
+}), on(setAwsInstance, (state, { instanceName, wsUrl, pollingUrl, streamRequestId }) => {
     return {
         ...state,
         awsInstance: {
@@ -487,6 +487,7 @@ const unrealReducer = createReducer(initialState, on(changeStatusMainVideoOnScen
             instanceName,
             wsUrl,
             pollingUrl,
+            streamRequestId,
             progressComplete: 0,
         },
     };
@@ -642,7 +643,7 @@ const unrealReducer = createReducer(initialState, on(changeStatusMainVideoOnScen
     return { ...state, analyticsEvent: event };
 }), on(setCirrusConnected, (state) => {
     return { ...state, cirrusConnected: true };
-}), on(streamAdopted, (state, { machineId, ssData }) => {
+}), on(streamAdopted, (state, { machineId, ssData, streamRequestId }) => {
     return {
         ...state,
         cirrusConnected: true,
@@ -653,6 +654,7 @@ const unrealReducer = createReducer(initialState, on(changeStatusMainVideoOnScen
             wsUrl: machineId,
             pollingUrl: null,
             instanceName: 'Adopted Connection',
+            streamRequestId: streamRequestId ?? state.awsInstance.streamRequestId,
             progressComplete: 0,
         },
     };
@@ -782,8 +784,9 @@ function InstanceReadyHandler(msg) {
     this.store.dispatch(instanceReady(payload));
     // Open the SECOND socket directly to the stream machine and route the whole
     // WebRTC signalling through it. The orchestration socket stays open for
-    // control/lifecycle.
-    this.connectToStreamMachine(payload.originInstanceUri);
+    // control/lifecycle. `streamRequestId` is handed over so the stream machine's
+    // Cirrus reuses the orchestration-issued connection id.
+    this.connectToStreamMachine(payload.originInstanceUri, payload.streamRequestId);
 }
 
 function InstanceReservedHandler(msg) {
@@ -1223,8 +1226,19 @@ const selectTotalProgress = createSelector(unrealFeature.selectStatusPercentSign
     const progressRest = lerp(0, 1 - splitPoint, commandProgress);
     return clampf(0, 1, progressSignaling + progressRest);
 });
-/** Used by external consumers (e.g., metabox). Do not remove. */
-const selectCirrusConnectionId = createSelector(unrealFeature.selectSsData, (data) => data?.connectionId);
+/**
+ * The connection id of the current stream session.
+ *
+ * Primary source is the orchestration, which issues it as `streamRequestId` —
+ * in the polling response (legacy flow) or in `instanceReserved`/`instanceReady`
+ * (new orchestration) — and the browser hands it to Cirrus on the WS upgrade
+ * URL. `ssData.connectionId` (the `ssInfo` message) is the fallback for
+ * backends that don't issue one yet: Cirrus then generates it itself and
+ * reports it back here.
+ *
+ * Used by external consumers (e.g., metabox). Do not remove.
+ */
+const selectCirrusConnectionId = createSelector(unrealFeature.selectAwsInstance, unrealFeature.selectSsData, (awsInstance, ssData) => awsInstance?.streamRequestId ?? ssData?.connectionId);
 /** Used by external consumers (e.g., metabox). Do not remove. */
 const selectUserInactivityDetected = createSelector(unrealFeature.selectAfkCountdown, unrealFeature.selectIsAfkTimerVisible, (remainingSecondsToDisconnect, countdownVisible) => ({
     remainingSecondsToDisconnect,
@@ -1538,6 +1552,16 @@ class RegionsPingService {
                     pingsMs: data.result,
                 }))), map$1((data) => data.region_code));
             }
+            // No regions URL and no cache: there is nothing to ping. Bail out loudly
+            // instead of letting `HttpClient.get('')` request the current document
+            // (which yields HTML, fails to parse and silently resolves an empty
+            // region). The usual cause is `UNREAL_CONFIG` provided on a lazy route
+            // rather than at the application root — this service is
+            // `providedIn: 'root'`, so a route-level value never reaches it.
+            if (!regionListUrl) {
+                Logger.warn('RegionsPingService: regionsPingUrl is empty — skipping region discovery. Provide UNREAL_CONFIG at the APPLICATION ROOT (a route-level provider is invisible to root-scoped services).');
+                return of(undefined).pipe(tap(() => this.store.dispatch(regionPingFetchEnd())), tap(() => this.store.dispatch(regionResolved({ region: '', pingsMs: [] }))));
+            }
             return this.getProviders(regionListUrl).pipe(tap(() => this.store.dispatch(regionPingFetchEnd())), switchMap((providers) => this.getPingResult(providers)), catchError(() => of(null)), tapLog('PingResult'), 
             // Warm the cache with the live result so the next connection (and any
             // reload within the TTL) can skip pinging even if the prefetch script
@@ -1558,9 +1582,11 @@ class RegionsPingService {
      * All access is guarded — `localStorage` can throw (private mode, disabled
      * storage) or be absent (non-browser).
      *
-     * Public so adopted connections (which skip `getFastest`) can replay the
+     * Public so adopted connections (which skip `getFastest`) can still report a
      * region-resolving telemetry phase from the same cached winner — see
-     * `UnrealEffects.regionTelemetryOnAdopt$`.
+     * `StreamStatusTelemetryService2.emitAdoptedConnection`. Returns `null` when
+     * the region-ping prefetch never ran or its cache expired; that phase then
+     * carries no region and no ping samples.
      */
     readCachedWinner() {
         try {
@@ -1606,6 +1632,10 @@ class RegionsPingService {
      * connection handshake. Aborts with the injector via `destroyController`.
      */
     refreshCacheInBackground(regionListUrl = this.unrealConfig?.regionsPingUrl || '') {
+        if (!regionListUrl) {
+            Logger.warn('RegionsPingService: regionsPingUrl is empty — skipping the background region re-ping.');
+            return of(null);
+        }
         return defer(() => this.getProviders(regionListUrl)).pipe(switchMap((providers) => from(this.measureAccurate(providers.regions, providers.timeout ?? this.config.ping_timeout))), tap((winner) => {
             if (winner) {
                 this.writeCachedWinner(winner.region_code, winner.result);
@@ -1819,6 +1849,27 @@ function httpUrlToWs(url) {
     return url.replace('http://', 'ws://').replace('https://', 'wss://');
 }
 
+/**
+ * Append the orchestration-issued connection id to a signalling WS URL as
+ * `?streamRequestId=…`.
+ *
+ * Cirrus reads it in its `onConnection` upgrade handler and uses it as the
+ * player's `connectionId` instead of generating one (both the legacy Cirrus and
+ * the new Cirrus-WS keep their `guid()` generator as a fallback). A missing id
+ * is a no-op, so the URL stays byte-identical for backends that don't issue one.
+ *
+ * Only used at the moment of connecting — the URL kept in the store stays clean
+ * (it is rendered in the debug overlay and pattern-matched by
+ * `selectTotalProgress`).
+ */
+function withStreamRequestId(wsUrl, streamRequestId) {
+    if (!wsUrl || !streamRequestId) {
+        return wsUrl;
+    }
+    const separator = wsUrl.includes('?') ? '&' : '?';
+    return `${wsUrl}${separator}streamRequestId=${encodeURIComponent(streamRequestId)}`;
+}
+
 /**
  * Factory that creates a WebSocket connection and wraps it in an RxJS Observable.
  *
@@ -2153,7 +2204,7 @@ class SignallingService extends SubService {
      */
     connectAttempt(urls) {
         const urlGen = getActiveUrl(urls);
-        return defer(() => this.getAwsInstance(`${urlGen.next().value}`)).pipe(tap((awsInstance) => this.store.dispatch(setAwsInstance(awsInstance))), switchMap(({ wsUrl }) => 
+        return defer(() => this.getAwsInstance(`${urlGen.next().value}`)).pipe(tap((awsInstance) => this.store.dispatch(setAwsInstance(awsInstance))), switchMap(({ wsUrl, streamRequestId }) => 
         // ── WS-only retry tier ─────────────────────────────────────────────
         // Tries the SAME `wsUrl` up to `WS_RETRY_PER_INSTANCE` extra times
         // before letting the error bubble up to the outer (URL-rotating)
@@ -2167,7 +2218,14 @@ class SignallingService extends SubService {
         // burning a second reservation. If WS still fails after these
         // extra attempts, the instance is genuinely unusable and we
         // accept the cost of rotating.
-        this.connectToCirrus(wsUrl ?? '').pipe(filter(Truthy), take(1), retry({
+        // POLLING flow only: the polled `signallingServer` IS Cirrus (single
+        // socket), so the orchestration-issued connection id rides on this
+        // upgrade URL. In the new WS flow this socket is orchestration-only
+        // control and `streamRequestId` is still unknown here (it arrives later
+        // in `instanceReserved`/`instanceReady`) → no-op, URL unchanged; the id
+        // is attached to the machine address instead, see
+        // `connectToStreamMachine`.
+        this.connectToCirrus(withStreamRequestId(wsUrl ?? '', streamRequestId)).pipe(filter(Truthy), take(1), retry({
             count: WS_RETRY_PER_INSTANCE,
             delay: (err, attempt) => {
                 this.store.dispatch(signalingRetryAttempted({
@@ -2198,9 +2256,18 @@ class SignallingService extends SubService {
             },
         }));
     }
+    /**
+     * Status message for the connect branch. It does NOT dispatch
+     * `setEstablishingConnection` — `UnrealEffects.connectToSignaling$` already
+     * emits that once per logical attempt via `startWith(...)`, covering BOTH
+     * branches (prefetch adoption and a fresh connect). Dispatching it here as
+     * well fired the boundary twice on every cold start, and since
+     * `StreamStatusTelemetryService2` starts a session on that boundary, the
+     * first session was killed 2 ms in as `restart` — losing the only honest
+     * page-load measurement and the prefetch adoption with it.
+     */
     startEstablishingConnection() {
         this.showStatusMessage(UnrealStatusMessage.STARTING_YOUR_SESSION);
-        this.store.dispatch(setEstablishingConnection({ value: true }));
     }
     adaptUrlsToRegion(urlList, region) {
         return urlList.map((url) => {
@@ -2254,6 +2321,9 @@ class SignallingService extends SubService {
                 wsUrl: httpUrlToWs(`${location.protocol}//${data.signallingServer}`),
                 pollingUrl: url,
                 instanceName: data.signallingServer ?? '',
+                // The orchestration issues the connection id here; it is handed to
+                // Cirrus on the WS upgrade URL (see `connectAttempt`).
+                streamRequestId: data.streamRequestId,
             })), finalize(() => {
                 this.commandTelemetryService.trackStopCommand('EXT-getSignaling', true, { ...(lastResp ?? {}), multi: true });
                 this.store.dispatch(pollingEnded());
@@ -2371,8 +2441,15 @@ class SignallingService extends SubService {
      *
      * "Just connect" — nothing is sent on open (the machine is already reserved
      * for this session): Cirrus pushes `config` and Unreal sends the `offer`.
+     *
+     * The orchestration-issued `streamRequestId` (from the same `instanceReady`
+     * payload) rides on this upgrade URL: in the new flow THIS is the Cirrus
+     * socket, so it is the one that must carry the id (the first socket is
+     * orchestration-only control and needs nothing). Without it the stream
+     * machine's Cirrus falls back to its own `guid()` and the session can no
+     * longer be correlated. Absent id → URL unchanged.
      */
-    connectToStreamMachine(originInstanceUri) {
+    connectToStreamMachine(originInstanceUri, streamRequestId) {
         if (!originInstanceUri) {
             Logger.warn('instanceReady without originInstanceUri — stream socket not opened');
             return;
@@ -2387,7 +2464,7 @@ class SignallingService extends SubService {
         // before a fresh attempt — e.g. a retry that resolved to a different machine
         // or two instanceReady messages before the first connect resolves.
         this.teardownStreamWs();
-        this.streamWsSub = createWebSocket(originInstanceUri)
+        this.streamWsSub = createWebSocket(withStreamRequestId(originInstanceUri, streamRequestId))
             .pipe(takeUntil(this.abort$), takeUntil(this.destroy$), take(1))
             .subscribe({
             next: (ws) => {
@@ -3688,11 +3765,12 @@ class StreamAdoptionService {
      *
      * Wrapped in `defer` so the `tryAdopt()` side effect (which dispatches
      * `streamAdopted`) runs at SUBSCRIPTION time, not when the observable is
-     * built. The effect prepends `startWith(setEstablishingConnection(true))`,
-     * which starts the telemetry session and subscribes its phase catalog; that
-     * must happen BEFORE `streamAdopted` → `regionTelemetryOnAdopt$` replays
-     * `regionResolved`, or the region phase fires into a session that doesn't
-     * exist yet and is lost. `defer` guarantees that ordering.
+     * built. The effect prepends `startWith(setEstablishingConnection(true))` —
+     * the single dispatch site for that boundary — which starts the telemetry
+     * session and subscribes its phase catalog; that must happen BEFORE
+     * `streamAdopted`, or `emitAdoptedConnection` fires into a session that does
+     * not exist yet and the whole connection waterfall is lost. `defer`
+     * guarantees that ordering.
      */
     awaitAndAdopt$() {
         return defer(() => {
@@ -3762,6 +3840,7 @@ class StreamAdoptionService {
         this.store.dispatch(streamAdopted({
             machineId: parked.machineId ?? null,
             ssData: parked.ssData ?? null,
+            streamRequestId: parked.ids?.streamRequestId || null,
             timings: parked.timings ?? null,
         }));
         // Hand the live socket over without re-sending `requestStream`, reusing the
@@ -4063,9 +4142,12 @@ class UnrealEffects {
             return this.actions$.pipe(ofType(setAwsInstance), 
             // require wsUrl present on the action payload
             filter((action) => !!action.wsUrl), 
-            // for each awsInstance action capture one ssData snapshot, then wait for dataChannelConnected
+            // for each awsInstance action capture one connectionId snapshot, then wait
+            // for dataChannelConnected. The gate stays on `ssInfo` (unchanged timing);
+            // the id itself now comes from the orchestration when it issued one, and
+            // falls back to the `ssInfo` value otherwise.
             switchMap((awsInstance) => {
-                return this.actions$.pipe(ofType(updateCirrusInfo), take(1), switchMap(({ ssData }) => {
+                return this.actions$.pipe(ofType(updateCirrusInfo), take(1), withLatestFrom(this.store.select(selectCirrusConnectionId)), switchMap(([, connectionId]) => {
                     const abort$ = this.actions$.pipe(ofType(setCirrusDisconnected, // ← "Cirrus closed" action — direct,
                     //                        no fan-in tick delay
                     abortEstablishingConnection), take(1));
@@ -4082,7 +4164,7 @@ class UnrealEffects {
                         Logger.error(error);
                         const body = {
                             awsInstance,
-                            connectionId: ssData?.connectionId,
+                            connectionId,
                             href: location.href,
                             userAgent: navigator.userAgent,
                             error,
@@ -5880,10 +5962,14 @@ class StreamStatusTelemetryService2 {
                     // CLOSER — the `regionResolved` action carries the raw ping
                     // samples (one per probe) from `RegionsPingService`; the
                     // catalog flattens them to a comma-separated string since
-                    // `toPhaseParams` only accepts primitives. Adopted connections never
-                    // run `getRegion`, but `UnrealEffects.regionTelemetryOnAdopt$` replays
-                    // the region waterfall (start → end → resolved) from the cached winner,
-                    // so this phase still appears with its ping samples.
+                    // `toPhaseParams` only accepts primitives.
+                    //
+                    // Adopted connections never run `getRegion`, so this closer never
+                    // fires for them (and is suppressed anyway via PREFETCHED_PHASE_IDS).
+                    // Their region phase comes from {@link emitAdoptedConnection}, which
+                    // reports `duration: 0`, no milestones, and reads the winner + samples
+                    // out of the ping cache — so it is EMPTY when the region-ping prefetch
+                    // never ran or its cache expired.
                     {
                         id: 'region-resolved',
                         event: this.actions$.pipe(ofType(regionResolved), take(1), map(({ region, pingsMs }) => ({
@@ -6053,12 +6139,17 @@ class StreamStatusTelemetryService2 {
         // times per page load (the unreal-scene effect, `startStream`, the
         // reconnect effect), but the connection layer collapses them into one
         // attempt via `connectToSignaling$` (`exhaustMap` + `!cirrusConnected`
-        // filter). `setEstablishingConnection(true)` is dispatched exactly
-        // once per real attempt from `SignallingService.startEstablishingConnection()`,
-        // downstream of that guard — so binding here yields one session per
-        // attempt instead of a burst of `restart` churn sessions. Genuine
+        // filter). `setEstablishingConnection(true)` is dispatched exactly once
+        // per real attempt, by that effect's `startWith(...)` — the SINGLE
+        // dispatch site, downstream of the guard and ahead of both branches
+        // (prefetch adoption / fresh connect). So binding here yields one session
+        // per attempt instead of a burst of `restart` churn sessions. Genuine
         // reconnects (e.g. DataChannelTimeout) re-enter the same path and
         // correctly end the prior session as `restart` + start a new one.
+        //
+        // Do NOT add a second dispatch site: this binding turns every extra
+        // `true` into `endSession('restart')` + a new session, which throws away
+        // the first session's page-load measurement and its prefetch adoption.
         this.actions$
             .pipe(ofType(setEstablishingConnection), filter$1(({ value }) => value === true), takeUntil$1(this.destroy$))
             .subscribe(() => this.startSession());