@scalebun/react-native 1.2.0 → 1.2.1

package/src/features/performance/PerformanceFeature.ts

@@ -25,6 +25,15 @@ import { PerformanceTransport, type PerfTransportSink } from './transport/Perfor
 import { MetricKeys } from './metrics/MetricsEngine';
 import { SessionManager } from '../session/SessionManager';
 
+/** Shape accepted by BackendSessionAdapter.queuePerformanceMetric. */
+type BackendPerfMetric = {
+    type: string;
+    screenName?: string;
+    duration?: number;
+    value?: number;
+    metadata?: Record<string, unknown>;
+};
+
 export class PerformanceFeature implements IFeature {
     readonly name = 'performance';
     private active = false;
@@ -70,7 +79,31 @@ export class PerformanceFeature implements IFeature {
     /** Delay schedule for each attempt (ms) — escalating to let views settle */
     private static readonly CAPTURE_DELAYS = [300, 600, 1200];
 
-    // Track event function from SDK pipeline
+    // ─── Early-metric buffering (backend) ───────────────────────────────
+    //
+    // Performance metrics reach the cloud via the SessionManager's backend
+    // transport. But the first metrics — most importantly app_launch — fire
+    // during PerformanceFeature.initialize() (appLaunchCollector.collect()),
+    // which runs from featureRegistry.initializeAll() BEFORE the bootstrap
+    // attaches the backend transport (SDKBootstrapper). In that window
+    // getBackendTransport() is null, so without buffering the metric is sent
+    // only to the desktop debugger and silently dropped from the cloud
+    // ("App start = 0" in Insights). We buffer such metrics locally and drain
+    // them the moment the transport appears (via subsequent events or a
+    // bounded retry). The backend adapter itself buffers again until the
+    // session row is ready, so ordering across the session boundary is safe.
+    /** Metrics captured before the backend transport was available. */
+    private _pendingBackendMetrics: BackendPerfMetric[] = [];
+    /** Retry timer that drains the buffer once the transport attaches. */
+    private _backendDrainTimer: ReturnType<typeof setTimeout> | null = null;
+    /** Number of drain attempts made for the current buffered batch. */
+    private _backendDrainAttempts = 0;
+    /** Hard cap on buffered metrics — bounds memory if a transport never attaches (non-SaaS). */
+    private static readonly BACKEND_BUFFER_MAX = 64;
+    /** Max drain retries before giving up (non-SaaS mode never attaches a transport). */
+    private static readonly BACKEND_DRAIN_MAX_ATTEMPTS = 6;
+    /** Escalating retry delays (ms); last value repeats. Covers the startup attach race. */
+    private static readonly BACKEND_DRAIN_DELAYS = [250, 500, 1000, 2000, 4000];
 
     constructor(config?: Partial<PerformanceConfig>) {
         this.config = mergePerformanceConfig(config);
@@ -297,6 +330,11 @@ export class PerformanceFeature implements IFeature {
             clearTimeout(this._captureTimer);
             this._captureTimer = null;
         }
+        // Stop the backend-drain retry loop (buffered metrics are dropped —
+        // the desktop transport already received them via sendEvent/sendMetric).
+        this._clearBackendDrainTimer();
+        this._backendDrainAttempts = 0;
+        this._pendingBackendMetrics = [];
     }
 
     get isActive(): boolean {
@@ -570,28 +608,100 @@ export class PerformanceFeature implements IFeature {
          * and it costs a duplicate serialize + upload per sample on every session.
          */
 
-        // Queue to SaaS backend dedicated performance endpoint
+        // Queue to SaaS backend dedicated performance endpoint. When the backend
+        // transport isn't attached yet (startup race — app_launch fires before
+        // SDKBootstrapper wires it), buffer locally and drain once it appears so
+        // the cloud gets the metric instead of only the desktop debugger.
+        this._forwardMetricToBackend(this._toBackendMetric(event));
+    }
+
+    /** Map a raw perf event onto the backend metric envelope. */
+    private _toBackendMetric(event: AnyPerfEvent): BackendPerfMetric {
+        const e = event as any;
+        // Forward structured launch fields so the backend can group by launch
+        // type and reconstruct the startup waterfall. Without this, only the
+        // raw duration reaches the analytics table and cold/warm/hot + phase
+        // timings are lost. Additive + forward-only: pre-existing rows stay as
+        // { id } and historical launch-type windows remain empty.
+        const metadata: Record<string, unknown> = { id: event.id };
+        if (event.type === 'app_launch') {
+            if (e.launchType) metadata.launchType = e.launchType;
+            if (e.breakdown) metadata.breakdown = e.breakdown;
+            if (e.phaseLabels) metadata.phaseLabels = e.phaseLabels;
+        }
+        return {
+            type: event.type,
+            screenName: e.screenName ?? e.context?.screenKey,
+            duration: e.durationMs,
+            value: e.estimatedFps ?? e.value,
+            metadata,
+        };
+    }
+
+    /**
+     * Hand a metric to the backend transport, or buffer it until one attaches.
+     * Every call first drains anything buffered, so a late-arriving transport
+     * flushes the backlog in the order the metrics were produced.
+     */
+    private _forwardMetricToBackend(metric: BackendPerfMetric): void {
         const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();
         if (backendTransport) {
-            const e = event as any;
-            // Forward structured launch fields so the backend can group by launch
-            // type and reconstruct the startup waterfall. Without this, only the
-            // raw duration reaches the analytics table and cold/warm/hot + phase
-            // timings are lost. Additive + forward-only: pre-existing rows stay as
-            // { id } and historical launch-type windows remain empty.
-            const metadata: Record<string, unknown> = { id: event.id };
-            if (event.type === 'app_launch') {
-                if (e.launchType) metadata.launchType = e.launchType;
-                if (e.breakdown) metadata.breakdown = e.breakdown;
-                if (e.phaseLabels) metadata.phaseLabels = e.phaseLabels;
+            this._drainPendingBackendMetrics(backendTransport);
+            backendTransport.queuePerformanceMetric(metric);
+            return;
+        }
+
+        // No transport yet — buffer (bounded, drop-oldest) and schedule a drain.
+        this._pendingBackendMetrics.push(metric);
+        if (this._pendingBackendMetrics.length > PerformanceFeature.BACKEND_BUFFER_MAX) {
+            this._pendingBackendMetrics.shift();
+        }
+        this._scheduleBackendDrain();
+    }
+
+    /** Flush all buffered metrics into the transport, preserving order. */
+    private _drainPendingBackendMetrics(
+        backendTransport: NonNullable<ReturnType<SessionManager['getBackendTransport']>>,
+    ): void {
+        if (this._pendingBackendMetrics.length === 0) return;
+        const buffered = this._pendingBackendMetrics;
+        this._pendingBackendMetrics = [];
+        for (const metric of buffered) {
+            backendTransport.queuePerformanceMetric(metric);
+        }
+        this._clearBackendDrainTimer();
+        this._backendDrainAttempts = 0;
+    }
+
+    /**
+     * Poll for the backend transport a bounded number of times so the sole
+     * early metric (app_launch) still reaches the cloud even when no later
+     * event arrives to trigger a drain. Gives up after BACKEND_DRAIN_MAX_ATTEMPTS
+     * (non-SaaS mode never attaches a transport — the desktop path already has
+     * the data), leaving the bounded buffer to be GC'd on teardown.
+     */
+    private _scheduleBackendDrain(): void {
+        if (this._backendDrainTimer) return;
+        if (this._backendDrainAttempts >= PerformanceFeature.BACKEND_DRAIN_MAX_ATTEMPTS) return;
+
+        const delays = PerformanceFeature.BACKEND_DRAIN_DELAYS;
+        const delay = delays[Math.min(this._backendDrainAttempts, delays.length - 1)];
+        this._backendDrainAttempts++;
+        this._backendDrainTimer = setTimeout(() => {
+            this._backendDrainTimer = null;
+            const backendTransport = SessionManager.getExistingInstance()?.getBackendTransport();
+            if (backendTransport) {
+                this._drainPendingBackendMetrics(backendTransport);
+            } else if (this._pendingBackendMetrics.length > 0) {
+                this._scheduleBackendDrain();
             }
-            backendTransport.queuePerformanceMetric({
-                type: event.type,
-                screenName: e.screenName ?? e.context?.screenKey,
-                duration: e.durationMs,
-                value: e.estimatedFps ?? e.value,
-                metadata,
-            });
+        }, delay);
+    }
+
+    private _clearBackendDrainTimer(): void {
+        if (this._backendDrainTimer) {
+            clearTimeout(this._backendDrainTimer);
+            this._backendDrainTimer = null;
         }
     }
 }