@newrelic/video-core 3.2.0-beta-1 → 4.0.1

package/src/harvestScheduler.js

@@ -0,0 +1,416 @@
+import { NrVideoEventAggregator } from "./eventAggregator";
+import { RetryQueueHandler } from "./retryQueueHandler";
+import { OptimizedHttpClient } from "./optimizedHttpClient";
+import { buildUrl, dataSize } from "./utils";
+import Constants from "./constants";
+import Log from "./log";
+
+/**
+ * Enhanced harvest scheduler that orchestrates the video analytics data collection,
+ * processing, and transmission with smart harvesting and performance monitoring.
+ */
+
+export class HarvestScheduler {
+  constructor(eventAggregator) {
+    // Core components
+    this.eventBuffer = eventAggregator;
+    this.retryQueueHandler = new RetryQueueHandler();
+    this.httpClient = new OptimizedHttpClient();
+    this.fallBackUrl = "";
+    this.retryCount = 0;
+
+    // Set up smart harvest callback
+    if (this.eventBuffer instanceof NrVideoEventAggregator) {
+      this.eventBuffer.setSmartHarvestCallback((type, threshold) =>
+        this.triggerSmartHarvest(type, threshold)
+      );
+    }
+
+    // Scheduler state
+    this.isStarted = false;
+    this.currentTimerId = null;
+    this.harvestCycle = Constants.INTERVAL;
+    this.isHarvesting = false;
+
+    // Page lifecycle handling
+    this.setupPageLifecycleHandlers();
+  }
+
+  /**
+   * Starts the harvest scheduler.
+   */
+  startScheduler() {
+    if (this.isStarted) {
+      Log.warn("Harvest scheduler is already started");
+      return;
+    }
+
+    this.isStarted = true;
+
+    Log.notice("Starting harvest scheduler", {
+      harvestCycle: this.harvestCycle,
+      eventBufferSize: this.eventBuffer ? this.eventBuffer.size() : 0,
+    });
+
+    this.scheduleNextHarvest();
+  }
+
+  /**
+   * Stops the harvest scheduler.
+   */
+  stopScheduler() {
+    if (!this.isStarted) {
+      return;
+    }
+
+    this.isStarted = false;
+
+    if (this.currentTimerId) {
+      clearTimeout(this.currentTimerId);
+      this.currentTimerId = null;
+    }
+
+    Log.notice("Harvest scheduler stopped");
+  }
+
+  /**
+   * Triggers a smart harvest when buffer reaches threshold capacity.
+   * @param {string} type - Type of harvest trigger ('smart' or 'overflow')
+   * @param {number} threshold - Threshold percentage that triggered the harvest (60 or 90)
+   */
+  async triggerSmartHarvest(type, threshold) {
+    Log.notice(`${type} harvest triggered at ${threshold}% threshold`, {
+      type,
+      threshold,
+    });
+
+    // If buffer is empty, abort harvest
+    if (!this.eventBuffer || this.eventBuffer.isEmpty()) return;
+
+    // Clear existing timer to prevent redundant harvests
+    if (this.currentTimerId) {
+      clearTimeout(this.currentTimerId);
+      this.currentTimerId = null;
+    }
+
+    try {
+      await this.triggerHarvest({});
+    } catch (error) {
+      Log.error(`${type} harvest failed:`, error.message);
+    } finally {
+      // Schedule next harvest after smart harvest completes
+      if (this.isStarted) {
+        this.scheduleNextHarvest();
+      }
+    }
+  }
+
+  /**
+   * Schedules the next harvest based on current conditions.
+   * @private
+   */
+  scheduleNextHarvest() {
+    if (!this.isStarted) return;
+
+    const interval = this.harvestCycle;
+    this.currentTimerId = setTimeout(() => this.onHarvestInterval(), interval);
+  }
+
+  /**
+   * Handles the harvest interval timer.
+   * @private
+   */
+  async onHarvestInterval() {
+    try {
+      // Check if there's any data to harvest (buffer or retry queue) before starting the harvest process
+      const hasBufferData = this.eventBuffer && !this.eventBuffer.isEmpty();
+      const hasRetryData =
+        this.retryQueueHandler && this.retryQueueHandler.getQueueSize() > 0;
+
+      if (!hasBufferData && !hasRetryData) return;
+      await this.triggerHarvest({});
+    } catch (error) {
+      Log.error("Error during scheduled harvest:", error.message);
+    } finally {
+      this.scheduleNextHarvest();
+    }
+  }
+
+  /**
+   * Triggers a harvest cycle with comprehensive error handling and monitoring.
+   * @param {object} options - Harvest options
+   * @param {boolean} options.isFinalHarvest - Whether this is a final harvest on page unload
+   * @param {boolean} options.force - Force harvest even if buffer is empty
+   * @returns {Promise<object>} Harvest result
+   */
+  async triggerHarvest(options = {}) {
+    if (this.isHarvesting) {
+      return { success: false, reason: "harvest_in_progress" };
+    }
+
+    this.isHarvesting = true;
+
+    try {
+      // Drain events from buffer
+      let events = this.drainEvents(options);
+
+      // For beacon harvests, trim events to fit beacon size if necessary
+      if (options.isFinalHarvest) {
+        const maxBeaconSize = Constants.MAX_BEACON_SIZE;
+        const payloadSize = dataSize(events);
+
+        if (payloadSize > maxBeaconSize) {
+          // Trim events to fit beacon size (keep most recent events)
+          events = this.trimEventsToFit(events, maxBeaconSize);
+        }
+      }
+
+      // Send single payload - buffer limits guarantee it fits API constraints
+      const result = await this.sendChunk(events, options, true);
+
+      return {
+        success: result.success,
+        totalChunks: 1,
+        results: [result],
+      };
+    } catch (error) {
+      Log.error("Harvest cycle failed:", error.message);
+      this.handleHarvestFailure(error);
+
+      return {
+        success: false,
+        error: error.message,
+        consecutiveFailures: this.consecutiveFailures,
+      };
+    } finally {
+      this.isHarvesting = false;
+    }
+  }
+
+  /**
+   * Trims events to fit within a specified size limit for beacon harvests.
+   * Keeps the most recent events and discards older ones.
+   * @param {Array} events - Events to trim
+   * @param {number} maxSize - Maximum payload size in bytes
+   * @returns {Array} Trimmed events that fit within size limit
+   * @private
+   */
+  trimEventsToFit(events, maxSize) {
+    if (events.length === 0) return events;
+
+    // Start from the most recent events (end of array) and work backwards
+    const trimmedEvents = [];
+    let currentSize = 0;
+
+    for (let i = events.length - 1; i >= 0; i--) {
+      const event = events[i];
+
+      // Check if adding this event would exceed the limit
+      const testPayloadSize = dataSize({ ins: [event, ...trimmedEvents] });
+
+      if (testPayloadSize > maxSize) continue;
+
+      // Add event to the beginning to maintain chronological order
+      trimmedEvents.unshift(event);
+      currentSize = testPayloadSize;
+    }
+
+    const discardedCount = events.length - trimmedEvents.length;
+    if (discardedCount > 0) {
+      const discardedEvents = events.slice(0, discardedCount);
+      Log.warn(`Discarded ${discardedCount} events to fit beacon size limit`, {
+        originalCount: events.length,
+        trimmedCount: trimmedEvents.length,
+        finalSize: currentSize,
+        maxSize,
+      });
+
+      // send discarded events to retry queue
+      if (this.retryQueueHandler) {
+        this.retryQueueHandler.addFailedEvents(discardedEvents);
+      }
+    }
+
+    return trimmedEvents;
+  }
+
+  /**
+   * Drains events from the event buffer and optionally includes retry queue data.
+   * Uses fresh-events-first approach with payload limits.
+   * @param {object} options - Harvest options
+   * @returns {Array} Drained events
+   * @private
+   */
+  drainEvents() {
+    // Always drain fresh events first (priority approach)
+    const freshEvents = this.eventBuffer.drain();
+    let events = [...freshEvents];
+    let currentPayloadSize = dataSize(freshEvents);
+
+    // Always check retry queue if it has data - no flags needed
+    if (this.retryQueueHandler && this.retryQueueHandler.getQueueSize() > 0) {
+      //const retryQueueSize = this.retryQueueHandler.getQueueSize();
+
+      // Calculate available space for retry events
+      const availableSpace = Constants.MAX_PAYLOAD_SIZE - currentPayloadSize;
+      const availableEventCount =
+        Constants.MAX_EVENTS_PER_BATCH - events.length;
+
+      if (availableSpace > 0 && availableEventCount > 0) {
+        const retryEvents = this.retryQueueHandler.getRetryEventsToFit(
+          availableSpace,
+          availableEventCount
+        );
+
+        if (retryEvents.length > 0) {
+          events = [...retryEvents, ...events]; // Append retry events before fresh events for maintaining chronoligical order
+        }
+      }
+    }
+    return events;
+  }
+
+  /**
+   * Sends a chunk of events using the optimized HTTP client.
+   * @param {Array} chunk - Events to send
+   * @param {object} options - Harvest options
+   * @param {boolean} isLastChunk - Whether this is the last chunk
+   * @returns {Promise<object>} Send result
+   * @private
+   */
+  async sendChunk(chunk, options, isLastChunk) {
+    const url = buildUrl(this.fallBackUrl); //
+    const payload = { body: { ins: chunk } };
+    const requestOptions = {
+      url,
+      payload,
+      options: {
+        ...options,
+        isLastChunk,
+      },
+    };
+    return new Promise((resolve) => {
+      this.httpClient.send(requestOptions, (result) => {
+        if (result.retry) {
+          this.handleRequestFailure(chunk);
+        } else {
+          // Inline reset logic for successful request
+          this.retryCount = 0;
+          this.fallBackUrl = "";
+        }
+        resolve({
+          success: !result.retry,
+          status: result.status,
+          error: result.error,
+          chunk,
+          eventCount: chunk.length,
+        });
+      });
+    });
+  }
+
+  /**
+   * Handles request failure and implements failover logic for US region.
+   * @param {Array} chunk - Failed chunk to add to retry queue
+   * @private
+   */
+  handleRequestFailure(chunk) {
+    // Add failed events to retry queue
+    this.retryQueueHandler.addFailedEvents(chunk);
+    // Only apply failover logic for US region
+    if (window.NRVIDEO?.info?.region !== "US") return;
+    this.retryCount++;
+    if (this.retryCount > 5) {
+      // Reset to primary endpoint after too many failures
+      this.retryCount = 0;
+      this.fallBackUrl = "";
+    } else if (this.retryCount >= 2) {
+      // Switch to fallback after 2 consecutive failures
+      this.fallBackUrl = Constants.COLLECTOR["US"][1];
+    }
+  }
+
+  /**
+   * Handles harvest failure scenarios.
+   * @param {Error} error - Harvest error
+   * @private
+   */
+  handleHarvestFailure(error) {
+    this.consecutiveFailures++;
+
+    Log.warn("Harvest failure handled", {
+      error: error.message,
+      consecutiveFailures: this.consecutiveFailures,
+    });
+  }
+
+  /**
+   * Updates the harvest interval and restarts the scheduler to apply the new interval.
+   * @param {number} newInterval - The new harvest interval in milliseconds
+   * @returns {boolean} - True if interval was updated successfully, false otherwise
+   */
+
+  updateHarvestInterval(newInterval) {
+    if (typeof newInterval !== "number" && isNaN(newInterval)) {
+      Log.warn("Invalid newInterval provided to updateHarvestInterval");
+      return;
+    }
+
+    if (newInterval < 1000 || newInterval > 300000) {
+      Log.warn("newInterval out of bounds (1000-300000), ignoring");
+      return;
+    }
+
+    // Check if the interval has actually changed to avoid unnecessary actions
+    if (this.harvestCycle === newInterval) {
+      return;
+    }
+
+    // 1. Update the harvestCycle property with the new interval
+    this.harvestCycle = newInterval;
+    Log.notice("Updated harvestCycle:", this.harvestCycle);
+
+    // 2. Clear the existing timer
+    if (this.currentTimerId) {
+      clearTimeout(this.currentTimerId);
+      this.currentTimerId = null;
+    }
+
+    // 3. Schedule a new timer with the updated interval
+    if (this.isStarted) {
+      this.scheduleNextHarvest();
+    }
+
+    return;
+  }
+
+  /**
+   * Sets up page lifecycle event handlers.
+   * @private
+   */
+  setupPageLifecycleHandlers() {
+    let finalHarvestTriggered = false;
+
+    const triggerFinalHarvest = () => {
+      if (finalHarvestTriggered) return;
+      finalHarvestTriggered = true;
+
+      this.triggerHarvest({ isFinalHarvest: true, force: true });
+    };
+
+    // Handle page visibility changes
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden) triggerFinalHarvest();
+    });
+
+    // Handle page unload
+    window.addEventListener("pagehide", () => {
+      triggerFinalHarvest();
+    });
+
+    // Handle beforeunload as backup
+    window.addEventListener("beforeunload", () => {
+      triggerFinalHarvest();
+    });
+  }
+}

package/src/index.js

@@ -6,9 +6,15 @@ import Emitter from "./emitter";
 import Tracker from "./tracker";
 import VideoTracker from "./videotracker";
 import VideoTrackerState from "./videotrackerstate";
+import { NrVideoEventAggregator } from "./eventAggregator";
+import { RetryQueueHandler } from "./retryQueueHandler";
+import { OptimizedHttpClient } from "./optimizedHttpClient";
+import { HarvestScheduler } from "./harvestScheduler";
+import { recordEvent } from "./recordEvent";
 import { version } from "../package.json";
 
 const nrvideo = {
+  // Core components (existing)
   Constants,
   Chrono,
   Log,
@@ -18,5 +24,20 @@ const nrvideo = {
   VideoTrackerState,
   Core,
   version,
+
+  // Enhanced video analytics components (new)
+ 
+  NrVideoEventAggregator,
+  RetryQueueHandler,
+  OptimizedHttpClient,
+  HarvestScheduler,
+
+
+
+  // Enhanced event recording
+  recordEvent,
+
+
 };
+
 export default nrvideo;

package/src/optimizedHttpClient.js

@@ -0,0 +1,165 @@
+import { dataSize, shouldRetry } from "./utils";
+import Log from "./log";
+
+/**
+ * Optimized HTTP client for video analytics data transmission with
+ * performance monitoring and efficient request handling.
+ */
+export class OptimizedHttpClient {
+  /**
+   * Sends data to the specified URL with performance monitoring.
+   * @param {object} requestOptions - Request configuration
+   * @param {string} requestOptions.url - Target URL
+   * @param {object} requestOptions.payload - Request payload
+   * @param {object} requestOptions.options - Additional options
+   * @param {Function} callback - Callback function for handling response
+   * @returns {Promise<void>}
+   */
+  async send(requestOptions, callback) {
+    const { url, payload, options = {} } = requestOptions;
+
+    try {
+      // Validate input
+      if (!url || !payload) {
+        throw new Error("URL and payload are required");
+      }
+
+      // Create request object
+      const request = {
+        url,
+        payload,
+        options,
+        callback,
+      };
+
+      // Execute request immediately
+      await this.executeRequest(request);
+    } catch (error) {
+      Log.error("Failed to send request:", error.message);
+      callback({ retry: false, status: 0, error: error.message });
+    }
+  }
+
+  /**
+   * Executes an HTTP request with timeout and error handling.
+   * @param {object} request - Request object
+   * @private
+   */
+  async executeRequest(request) {
+    const { url, payload, options, callback } = request;
+    const startTime = Date.now();
+
+    try {
+      const requestBody = JSON.stringify(payload.body);
+
+      // Handle final harvest with sendBeacon
+      if (options.isFinalHarvest && navigator.sendBeacon) {
+        const success = await this.sendWithBeacon(url, requestBody);
+        const result = { success, status: success ? 204 : 0 };
+        this.handleRequestComplete(request, result, startTime);
+        return;
+      }
+
+      // Use fetch with timeout
+      const response = await this.fetchWithTimeout(
+        url,
+        {
+          method: "POST",
+          body: requestBody,
+          headers: {
+            "Content-Type": "application/json",
+          },
+          keepalive: options.isFinalHarvest,
+        },
+        10000
+      );
+
+      const result = {
+        success: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+      };
+
+      this.handleRequestComplete(request, result, startTime);
+    } catch (error) {
+      const result = {
+        success: false,
+        status: 0,
+        error: error.message,
+      };
+
+      this.handleRequestComplete(request, result, startTime);
+    }
+  }
+
+  /**
+   * Handles request completion.
+   * @param {object} request - Request object
+   * @param {object} result - Request result
+   * @param {number} startTime - Request start timestamp
+   * @param {string} endpoint - The endpoint that was used for the request
+   * @private
+   */
+  handleRequestComplete(request, result) {
+    const { callback } = request;
+
+    // Use smart retry logic based on HTTP status codes
+    const shouldRetryRequest =
+      !result.success &&
+      (result.status === 0 || // Network/timeout errors
+        shouldRetry(result.status)); // Smart status code-based retry
+
+    callback({
+      retry: shouldRetryRequest,
+      status: result.status,
+      error: result.error,
+    });
+  }
+
+  /**
+   * Sends data using navigator.sendBeacon for final harvests.
+   * @param {string} url - Target URL
+   * @param {string} body - Request body
+   * @returns {Promise<boolean>} True if successful
+   * @private
+   */
+  async sendWithBeacon(url, body) {
+    try {
+      return navigator.sendBeacon(url, body);
+    } catch (error) {
+      Log.warn("sendBeacon failed, falling back to fetch:", error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Fetch with timeout implementation.
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController|MDN AbortController}
+   * @param {string} url - Target URL
+   * @param {object} options - Fetch options
+   * @param {number} timeout - Timeout in milliseconds
+   * @returns {Promise<Response>} Fetch response
+   * @private
+   */
+  async fetchWithTimeout(url, options, timeout) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new Error(`Request timeout after ${timeout}ms`);
+      }
+      throw error;
+    }
+  }
+}
+
+export default OptimizedHttpClient;

package/src/recordEvent.js

@@ -1,68 +1,41 @@
-import { customEventAggregator } from "./agent.js";
-import { getPayloadSize } from "./utils.js";
-import Constants from "./constants";
-
-const { VALID_EVENT_TYPES, MAX_EVENT_SIZE } = Constants;
+import { videoAnalyticsHarvester } from "./agent.js";
+import Constants from "./constants.js";
+import Log from "./log.js";
 
 /**
- * Records a video event with the specified type and attributes
- * @param {string} eventType - The type of event to record
- * @param {Object} attributes - Additional attributes to include with the event
- * @returns {boolean} - True if event was recorded successfully, false otherwise
+ * Enhanced record event function with validation, enrichment, and unified handling.
+ * @param {string} eventType - Type of event to record
+ * @param {object} attributes - Event attributes
  */
 export function recordEvent(eventType, attributes = {}) {
-  // Input validation
-  if (
-    typeof eventType !== "string" ||
-    eventType.length === 0 ||
-    !VALID_EVENT_TYPES.includes(eventType)
-  ) {
-    console.warn("recordEvent: Invalid eventType provided:", eventType);
-    return false;
-  }
-
-  // Validate attributes parameter
-  if (
-    attributes !== null &&
-    (typeof attributes !== "object" || Array.isArray(attributes))
-  ) {
-    console.warn("recordEvent: attributes must be a plain object");
-    return false;
-  }
+  try {
+    // Validate event type
+    if (!Constants.VALID_EVENT_TYPES.includes(eventType)) {
+      Log.warn("Invalid event type provided to recordEvent", { eventType });
+      return false;
+    }
 
-  // Ensure attributes is an object (handle null case)
-  attributes = attributes || {};
+    // Get app configuration
 
-  // Check if NRVIDEO is properly initialized
-  if (!window.NRVIDEO || !window.NRVIDEO.info) {
-    console.error("recordEvent: NRVIDEO not properly initialized");
-    return false;
-  }
+    if (!window?.NRVIDEO?.info) return;
 
-  try {
-    const { appName } = window.NRVIDEO.info;
+    const { appName, applicationID } = window.NRVIDEO.info;
 
     const eventObject = {
       ...attributes,
       eventType,
-      appName,
+      ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
       timestamp: Date.now(),
+      timeSinceLoad: window.performance
+        ? window.performance.now() / 1000
+        : null,
     };
 
-    // Check event size to prevent oversized payloads
-    const eventSize = getPayloadSize(eventObject);
-
-    if (eventSize > MAX_EVENT_SIZE) {
-      console.warn(
-        `recordEvent: Event size (${eventSize} bytes) exceeds maximum (${MAX_EVENT_SIZE} bytes)`
-      );
-      return false;
-    }
-
-    customEventAggregator.add(eventObject);
-    return true;
+    // Send to video analytics harvester
+    const success = videoAnalyticsHarvester.addEvent(eventObject);
+    return success;
   } catch (error) {
-    console.error("recordEvent: Error recording event:", error);
+    Log.error("Failed to record event:", error.message);
     return false;
   }
 }