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

/**
 * Observer for query stripping list updates.
 */
[scriptable, uuid(ef56ae12-b1bb-43e6-b1d8-16459cb98dfd)]
interface nsIURLQueryStrippingListObserver : nsISupports
{
  /**
   * Called by nsIQueryStrippingListService when the list of query stripping
   * changes and when the observer is first registered. Note that the lists
   * could have duplicate entries because we would combine the lists from the
   * pref and remote settings.
   *
   * @param aStripList
   *        A space-separated list of query parameters that will be stripped.
   * @param aAllowList
   *        A comma-separated list of hosts (eTLD+1) that are exempt from query
   *        stripping.
   */
  void onQueryStrippingListUpdate(in AString aStripList, in ACString aAllowList);

  /**
   * Called by nsIQueryStrippingListService when the list of query stripping
   * parameters for strip-on-share feature is updated and when the observer is first registered.
   *
   * @param aStripRules
   *        An Array of stringified strip rules.
   *        A stringified rule has the form of:
   *        "'queryParams': ['param1', 'param2', ...], 'topLevelSites': ['www.site.com', 'www.site.de', ...]"
   */
  [implicit_jscontext]
  void onStripOnShareUpdate(in Array<AString> aStripRules);
};

/**
 * A service that monitors updates to the query stripping list from sources such
 * as a local pref and remote settings updates.
 */
[scriptable, uuid(afff16f0-3fd2-4153-9ccd-c6d9abd879e4)]
interface nsIURLQueryStrippingListService : nsISupports
{
  /**
   * Register a new observer to query stripping list updates. When the observer
   * is registered it is called immediately once. Afterwards it will be called
   * whenever the specified pref changes or when remote settings for
   * partitioning updates.
   *
   * @param aObserver
   *        An nsIURLQueryStrippingListObserver object or function that
   *        will receive updates to the strip list and the allow list. Will be
   *        called immediately with the current list value.
   */
  void registerAndRunObserver(in nsIURLQueryStrippingListObserver aObserver);


  /**
   * Register a new observer to strip-on-share stripping list updates
   * (this is the strip-on-share list combined with the QPS list).
   * When the observer is registered it is called immediately once. Afterwards it will be called
   * when there is an remote settings update to the QPS strip list.
   *
   * @param aObserver
   *        An nsIURLQueryStrippingListObserver object or function that
   *        will receive updates to the strip list and the allow list. Will be
   *        called immediately with the current list value.
   */
  void registerAndRunObserverStripOnShare(in nsIURLQueryStrippingListObserver aObserver);

  /**
   * Unregister an observer.
   *
   * @param aObserver
   *        The nsIURLQueryStrippingListObserver object to unregister.
   */
  void unregisterObserver(in nsIURLQueryStrippingListObserver aObserver);

  /**
   * Unregister an observer for strip-on-share.
   *
   * @param aObserver
   *        The nsIURLQueryStrippingListObserver object to unregister.
   */
  void unregisterStripOnShareObserver(in nsIURLQueryStrippingListObserver aObserver);

  /**
   * Clear all Lists.
   *
   * Note that this is for testing purpose.
   */
  void clearLists();

  /**
   * Test-only method used to wait for the list service to initialize fully.
   * Resolves once the service has reached a fully disabled (false) or fully
   * enabled state (true).
   * May also be called when the service is already fully initialized or
   * disabled, in this case it will resolve immediately.
   */
  Promise testWaitForInit();


  /**
   * Add new lists with different params
   *
   * Note that this is for testing purpose.
   */
  Promise testSetList(in jsval testFile);


  /**
   * Check if Strip on Share observers are unregistered
   *
   * Note that this is for testing purpose.
   */
  boolean testHasStripOnShareObservers();

  /**
   * Check if QPS observers are unregistered
   *
   * Note that this is for testing purpose.
   */
  boolean testHasQPSObservers();
};