Quelle  NewTabContentPing.sys.mjs   Sprache: unbekannt

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";

const lazy = {};

ChromeUtils.defineESModuleGetters(lazy, {
  DeferredTask: "resource://gre/modules/DeferredTask.sys.mjs",
  PersistentCache: "resource://newtab/lib/PersistentCache.sys.mjs",
});

XPCOMUtils.defineLazyPreferenceGetter(
  lazy,
  "MAX_SUBMISSION_DELAY_PREF_VALUE",
  "browser.newtabpage.activity-stream.telemetry.privatePing.maxSubmissionDelayMs",
  5000
);

const EVENT_STATS_KEY = "event_stats";
const CACHE_KEY = "newtab_content_event_stats";

const CLICK_EVENT_ID = "click";

const EVENT_STATS_DAILY_PERIOD_MS = 60 * 60 * 24 * 1000;
const EVENT_STATS_WEEKLY_PERIOD_MS = 7 * 60 * 60 * 24 * 1000;

const MAX_UINT32 = 0xffffffff;

export class NewTabContentPing {
  #eventBuffer = [];
  #deferredTask = null;
  #lastDelaySelection = 0;
  #maxDailyEvents = 0;
  #maxDailyClickEvents = 0;
  #maxWeeklyClickEvents = 0;
  #curInstanceEventsSent = 0; // Used for tests

  constructor() {
    this.#maxDailyEvents = 0;
    this.#maxDailyClickEvents = 0;
    this.#maxWeeklyClickEvents = 0;
    this.cache = this.PersistentCache(CACHE_KEY, true);
  }

  /**
   * Set the maximum number of events to send in a 24 hour period
   *
   * @param {int} maxEvents
   */
  setMaxEventsPerDay(maxEvents) {
    this.#maxDailyEvents = maxEvents || 0;
  }

  /**
   * Set the maximum number of events to send in a 24 hour period
   *
   * @param {int} maxEvents
   */
  setMaxClickEventsPerDay(maxEvents) {
    this.#maxDailyClickEvents = maxEvents || 0;
  }

  /**
   * Set the maximum number of events to send in a 24 hour period
   *
   * @param {int} maxEvents
   */
  setMaxClickEventsPerWeek(maxEvents) {
    this.#maxWeeklyClickEvents = maxEvents || 0;
  }

  /**
   * Adds a event recording for Glean.newtabContent to the internal buffer.
   * The event will be recorded when the ping is sent.
   *
   * @param {string} name
   *   The name of the event to record.
   * @param {object} data
   *   The extra data being recorded with the event.
   */
  recordEvent(name, data) {
    this.#eventBuffer.push([name, this.sanitizeEventData(data)]);
  }

  /**
   * Schedules the sending of the newtab-content ping at some randomly selected
   * point in the future.
   *
   * @param {object} privateMetrics
   *   The metrics to send along with the ping when it is sent, keyed on the
   *   name of the metric.
   */
  scheduleSubmission(privateMetrics) {
    for (let metric of Object.keys(privateMetrics)) {
      try {
        Glean.newtabContent[metric].set(privateMetrics[metric]);
      } catch (e) {
        console.error(e);
      }
    }

    if (!this.#deferredTask) {
      this.#lastDelaySelection = this.#generateRandomSubmissionDelayMs();
      this.#deferredTask = new lazy.DeferredTask(async () => {
        await this.#flushEventsAndSubmit();
      }, this.#lastDelaySelection);
      this.#deferredTask.arm();
    }
  }

  /**
   * Disarms any pre-existing scheduled newtab-content pings and clears the
   * event buffer.
   */
  uninit() {
    this.#deferredTask?.disarm();
    this.#eventBuffer = [];
  }

  /**
   * Resets the impression stats object of the Newtab_content ping and returns it.
   */
  async resetDailyStats(eventStats = {}) {
    const stats = {
      ...eventStats,
      dailyCount: 0,
      lastUpdatedDaily: this.Date().now(),
      dailyClickCount: 0,
    };
    await this.cache.set(EVENT_STATS_KEY, stats);
    return stats;
  }

  async resetWeeklyStats(eventStats = {}) {
    const stats = {
      ...eventStats,
      lastUpdatedWeekly: this.Date().now(),
      weeklyClickCount: 0,
    };
    await this.cache.set(EVENT_STATS_KEY, stats);
    return stats;
  }

  /**
   * Resets all stats for testing purposes.
   */
  async test_only_resetAllStats() {
    let eventStats = await this.resetDailyStats();
    await this.resetWeeklyStats(eventStats);
  }

  /**
   * Randomly shuffles the elements of an array in place using the Fisher–Yates algorithm.
   *
   * @param {Array} array - The array to shuffle. This array will be modified.
   * @returns {Array} The same array instance, shuffled randomly.
   */
  static shuffleArray(array) {
    for (let i = array.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      const temp = array[i];
      array[i] = array[j];
      array[j] = temp;
    }
    return array;
  }
  /**
   * Called by the DeferredTask when the randomly selected delay has elapsed
   * after calling scheduleSubmission.
   */
  async #flushEventsAndSubmit() {
    const isOrganicClickEvent = (event, data) => {
      return event === CLICK_EVENT_ID && !data.is_sponsored;
    };

    this.#deferredTask = null;

    // See if we have no event stats or the stats period has cycled
    let eventStats = await this.cache.get(EVENT_STATS_KEY, {});

    if (
      !eventStats?.lastUpdatedDaily ||
      !(
        this.Date().now() - eventStats.lastUpdatedDaily <
        EVENT_STATS_DAILY_PERIOD_MS
      )
    ) {
      eventStats = await this.resetDailyStats(eventStats);
    }

    if (
      !eventStats?.lastUpdatedWeekly ||
      !(
        this.Date().now() - eventStats.lastUpdatedWeekly <
        EVENT_STATS_WEEKLY_PERIOD_MS
      )
    ) {
      eventStats = await this.resetWeeklyStats(eventStats);
    }

    let events = this.#eventBuffer;
    this.#eventBuffer = [];
    if (this.#maxDailyEvents > 0) {
      if (eventStats?.dailyCount >= this.#maxDailyEvents) {
        // Drop all events. Don't send
        return;
      }
    }
    let clickEvents = events.filter(([eventName, data]) =>
      isOrganicClickEvent(eventName, data)
    );
    let numOriginalClickEvents = clickEvents.length;
    // Check if we need to cap organic click events
    if (
      numOriginalClickEvents > 0 &&
      (this.#maxDailyClickEvents > 0 || this.#maxWeeklyClickEvents > 0)
    ) {
      if (this.#maxDailyClickEvents > 0) {
        clickEvents = clickEvents.slice(
          0,
          Math.max(0, this.#maxDailyClickEvents - eventStats?.dailyClickCount)
        );
      }
      if (this.#maxWeeklyClickEvents > 0) {
        clickEvents = clickEvents.slice(
          0,
          Math.max(0, this.#maxWeeklyClickEvents - eventStats?.weeklyClickCount)
        );
      }
      events = events
        .filter(([eventName, data]) => !isOrganicClickEvent(eventName, data))
        .concat(clickEvents);
    }

    eventStats.dailyCount += events.length;
    eventStats.weeklyClickCount += clickEvents.length;
    eventStats.dailyClickCount += clickEvents.length;

    await this.cache.set(EVENT_STATS_KEY, eventStats);

    for (let [eventName, data] of NewTabContentPing.shuffleArray(events)) {
      try {
        Glean.newtabContent[eventName].record(data);
      } catch (e) {
        console.error(e);
      }
    }
    GleanPings.newtabContent.submit();
    this.#curInstanceEventsSent += events.length;
  }

  /**
   * Returns number of events sent through Glean in this instance of the class.
   */
  get testOnlyCurInstanceEventCount() {
    return this.#curInstanceEventsSent;
  }

  /**
   * Removes fields from an event that can be linked to a user in any way, in
   * order to preserve anonymity of the newtab_content ping. This is just to
   * ensure we don't accidentally send these if copying information between
   * the newtab ping and the newtab-content ping.
   *
   * @param {object} eventDataDict
   *   The Glean event data that would be passed to a `record` method.
   * @returns {object}
   *   The sanitized event data.
   */
  sanitizeEventData(eventDataDict) {
    const {
      // eslint-disable-next-line no-unused-vars
      tile_id,
      // eslint-disable-next-line no-unused-vars
      newtab_visit_id,
      // eslint-disable-next-line no-unused-vars
      matches_selected_topic,
      // eslint-disable-next-line no-unused-vars
      recommended_at,
      // eslint-disable-next-line no-unused-vars
      received_rank,
      // eslint-disable-next-line no-unused-vars
      event_source,
      // eslint-disable-next-line no-unused-vars
      recommendation_id,
      // eslint-disable-next-line no-unused-vars
      layout_name,
      ...result
    } = eventDataDict;
    return result;
  }

  /**
   * Generate a random delay to submit the ping from the point of
   * scheduling. This uses a cryptographically secure mechanism for
   * generating the random delay and returns it in millseconds.
   *
   * @returns {number}
   *   A random number between 1000 and the max new content ping submission
   *   delay pref.
   */
  #generateRandomSubmissionDelayMs() {
    const MIN_SUBMISSION_DELAY = 1000;

    if (lazy.MAX_SUBMISSION_DELAY_PREF_VALUE <= MIN_SUBMISSION_DELAY) {
      // Somehow we got configured with a maximum delay less than the minimum...
      // Let's fallback to 5000 then.
      console.error(
        "Can not have a newtab-content maximum submission delay less" +
          ` than 1000: ${lazy.MAX_SUBMISSION_DELAY_PREF_VALUE}`
      );
    }
    const MAX_SUBMISSION_DELAY =
      lazy.MAX_SUBMISSION_DELAY_PREF_VALUE > MIN_SUBMISSION_DELAY
        ? lazy.MAX_SUBMISSION_DELAY_PREF_VALUE
        : 5000;

    const RANGE = MAX_SUBMISSION_DELAY - MIN_SUBMISSION_DELAY + 1;
    const selection = NewTabContentPing.secureRandIntInRange(RANGE);
    return MIN_SUBMISSION_DELAY + (selection % RANGE);
  }

  /**
   * Returns a secure random number between 0 and range
   *
   * @param {int} range Integer value range
   * @returns {int} Random value between 0 and range non-inclusive
   */
  static secureRandIntInRange(range) {
    // To ensure a uniform distribution, we discard values that could introduce
    // modulo bias. We divide the 2^32 range into equal-sized "buckets" and only
    // accept random values that fall entirely within one of these buckets.
    // This ensures each possible output in the target range is equally likely.

    const BUCKET_SIZE = Math.floor(MAX_UINT32 / range);
    const MAX_ACCEPTABLE = BUCKET_SIZE * range;

    let selection;
    let randomValues = new Uint32Array(1);
    do {
      crypto.getRandomValues(randomValues);
      [selection] = randomValues;
    } while (selection >= MAX_ACCEPTABLE);
    return selection % range;
  }

  /**
   * Returns true or false with a certain proability specified
   *
   * @param {number} prob Probability
   * @returns {boolean} Random boolean result of probability prob. A higher prob
   *   increases the chance of true being returned.
   */
  static decideWithProbability(prob) {
    if (prob <= 0) {
      return false;
    }
    if (prob >= 1) {
      return true;
    }
    const randomValues = new Uint32Array(1);
    crypto.getRandomValues(randomValues);
    const random = randomValues[0] / MAX_UINT32;
    return random < prob;
  }

  /**
   * This is a test-only function that will disarm the DeferredTask from sending
   * the newtab-content ping, and instead send it manually. The originally
   * selected submission delay is returned.
   *
   * This function is a no-op when not running in test automation.
   *
   * @returns {number}
   *   The originally selected random delay for submitting the newtab-content
   *   ping.
   * @throws {Error}
   *   Function throws an exception if this is called when no submission has been scheduled yet.
   */
  async testOnlyForceFlush() {
    if (!Cu.isInAutomation) {
      return 0;
    }

    if (this.#deferredTask) {
      this.#deferredTask.disarm();
      this.#deferredTask = null;
      await this.#flushEventsAndSubmit();
      return this.#lastDelaySelection;
    }
    throw new Error("No submission was scheduled.");
  }
}

/**
 * Creating a thin wrapper around PersistentCache, and Date.
 * This makes it easier for us to write automated tests
 */
NewTabContentPing.prototype.PersistentCache = (...args) => {
  return new lazy.PersistentCache(...args);
};

NewTabContentPing.prototype.Date = () => {
  return Date;
};