/* 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/. */

#include "nsISupports.idl"
#include "nsIBounceTrackingMapEntry.idl"

[scriptable, uuid(4866F748-29DA-4C10-8EAA-ED2F7851E6B1)]
interface nsIBounceTrackingProtection : nsISupports {
    /**
    *  Modes for Bounce Tracking Protection
    *
    *  MODE_DISABLED - Feature fully disabled and not initialized at startup. No
    *  user activation signals are collected. Requires a restart to apply.
    *  MODE_ENABLED - Feature fully enabled. This includes: collection of user
    *  activation signals, classification of bounce trackers, periodic purging
    *  of bounce trackers.
    *  MODE_ENABLED_STANDBY - Tracker classification and purging is disabled.
    *  User activation signals are still collected and stored.
    *  MODE_ENABLED_DRY_RUN - Dry-run mode: The feature is fully enabled, but
    *  tracker purging is simulated. No site data is purged. Purge telemetry
    *  still gets collected.  This mode is helpful for testing the feature
    *  without risking data loss.
    *
    *  For toggling the feature in privacy settings UI switch between
    *  MODE_ENABLED and MODE_ENABLED_DRY_RUN. This is important so that user
    *  activation signals and telemetry are still collected even if the feature
    *  is "turned off" for the user. In the future when we're done collecting
    *  telemetry we may switch this to MODE_ENABLED_STANDBY where we still
    *  collect user activation signals but do not simulate purging.
    *
    *  Fully enabling / disabling the feature (MODE_DISABLED -> x or x ->
    *  MODE_DISABLED) requires a restart to apply.
    */
    cenum Modes : 8 {
        MODE_DISABLED = 0,
        MODE_ENABLED = 1,
        MODE_ENABLED_STANDBY = 2,
        MODE_ENABLED_DRY_RUN = 3,
        // Not a valid mode, only used for pref validation.
        MAX_MODE_VALUE = 3,
    };

    // Reset the global bounce tracking state, including the maps for tracking
    // bounce tracker candidates and user activation.
    void clearAll();

    // Clear bounce tracking state for a specific site host and OriginAttributes pair.
    [implicit_jscontext]
    void clearBySiteHostAndOriginAttributes(in ACString aSiteHost, in jsval originAttributes);

    // Clear bounce tracking state for a specific site host and
    // OriginAttributesPattern.
    // aOriginAttributesPattern = {} clears for all OriginAttributes.
    [implicit_jscontext]
    void clearBySiteHostAndOriginAttributesPattern(in ACString aSiteHost, in jsval aOriginAttributesPattern);

    // Clear bounce tracking state for a specific time range.
    void clearByTimeRange(in PRTime aFrom, in PRTime aTo);

    // Clear bounce tracking state for the given origin attributes.
    void clearByOriginAttributesPattern(in AString aPattern);

    // Add a list of hosts to the global exception list. Hosts on the exception
    // list don't get purged. addSiteHostExceptions and removeSiteHostExceptions
    // are used by BTPRemoteExceptionList to populate entries coming from
    // RemoteSettings.
    void addSiteHostExceptions(in Array<ACString> aSiteHosts);

    // Remove a list of hosts from the global exception list.
    void removeSiteHostExceptions(in Array<ACString> aSiteHosts);

    // Checks whether a site has recently been purged by BTP. This check is done
    // across all OriginAttributes.
    boolean hasRecentlyPurgedSite(in ACString aSiteHost);

    // Test getter to inspect remote exception list state.
    Array<ACString> testGetSiteHostExceptions();

    // Trigger the bounce tracking timer algorithm that clears state for
    // classified bounce trackers.
    [implicit_jscontext]
    Promise testRunPurgeBounceTrackers();

    // Clear expired user activation flags. Expiry is set via pref
    // "privacy.bounceTrackingProtection.bounceTrackingActivationLifetimeSec".
    void testClearExpiredUserActivations();

    // Getters and setters for user activation and bounce tracker state.
    // These are used for testing purposes only.
    // State is keyed by OriginAttributes.

    [implicit_jscontext]
    Array<nsIBounceTrackingMapEntry> testGetBounceTrackerCandidateHosts(in jsval originAttributes);

    [implicit_jscontext]
    Array<nsIBounceTrackingMapEntry> testGetUserActivationHosts(in jsval originAttributes);

    [implicit_jscontext]
    void testAddBounceTrackerCandidate(in jsval originAttributes, in ACString aSiteHost, in PRTime aBounceTime);

    [implicit_jscontext]
    void testAddUserActivation(in jsval originAttributes, in ACString aSiteHost, in PRTime aActivationTime);

    // Get a list of recently purged bounce trackers.
    [implicit_jscontext]
    Array<nsIBounceTrackingPurgeEntry> testGetRecentlyPurgedTrackers(in jsval originAttributes);

    // Test helper to trigger user activation import from the permission
    // manager. Will only import if the pref
    // privacy.bounceTrackingProtection.hasMigratedUserActivationData is set to
    // false.
    void testMaybeMigrateUserInteractionPermissions();
};