// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module browsing_topics.mojom;

import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";

// Struct representing the features and configuration parameters related to the
// topics API.
struct WebUIBrowsingTopicsConfiguration {
  // Whether the `BrowsingTopics` feature is enabled.
  bool browsing_topics_enabled;

  // Whether the `PrivacySandboxAdsAPIsOverride` feature is enabled.
  bool privacy_sandbox_ads_apis_override_enabled;

  // Whether the `OverridePrivacySandboxSettingsLocalTesting` feature is
  // enabled.
  bool override_privacy_sandbox_settings_local_testing_enabled;

  // Whether the `BrowsingTopicsBypassIPIsPubliclyRoutableCheck` feature is
  // enabled.
  bool browsing_topics_bypass_ip_is_publicly_routable_check_enabled;

  // Whether document.browsingTopics() is allowed.
  bool browsing_topics_document_api_enabled;

  // The configuration version derived from topics parameters.
  int32 config_version;

  // Whether the `BrowsingTopicsParameters` feature is enabled.
  bool browsing_topics_parameters_enabled;

  // The number of epochs from where to calculate the topics to give to a
  // requesting contexts.
  int32 number_of_epochs_to_expose;

  // The periodic topics calculation interval.
  mojo_base.mojom.TimeDelta time_period_per_epoch;

  // The number of top topics to derive and to keep for each epoch.
  int32 number_of_top_topics_per_epoch;

  // The probability (in percent number) to return the random topic to a site.
  // The "random topic" is per-site, and is selected from the full taxonomy
  // uniformly at random, and each site has a
  // `use_random_topic_probability_percent`% chance to see the random topic
  // instead of one of the top topics.
  int32 use_random_topic_probability_percent;

  // Maximum duration between when a epoch is calculated and when a site starts
  // using that new epoch's topics. The time chosen is a per-site random point
  // in time between [calculation time, calculation time + max duration).
  mojo_base.mojom.TimeDelta max_epoch_introduction_delay;

  // How many epochs of API usage data (i.e. topics observations) will be based
  // off for the filtering of topics for a calling context.
  int32 number_of_epochs_of_observation_data_to_use_for_filtering;

  // The max number of observed-by context domains to keep for each top topic.
  // The intent is to cap the in-use memory.
  int32 max_number_of_api_usage_context_domains_to_keep_per_topic;

  // The max number of entries allowed to be retrieved from the
  // `BrowsingTopicsSiteDataStorage` database for each query for the API usage
  // contexts. The query will occur once per epoch at topics calculation time.
  // The intent is to cap the peak memory usage.
  int32 max_number_of_api_usage_context_entries_to_load_per_epoch;

  // The max number of API usage context domains allowed to be stored per page
  // load.
  int32 max_number_of_api_usage_context_domains_to_store_per_page_load;

  // The taxonomy version. This only affects the topics classification that
  // occurs during this browser session, and doesn't affect the pre-existing
  // epochs.
  int32 taxonomy_version;

  // Comma separated Topic IDs to be blocked. Descendant topics of each blocked
  // topic will be blocked as well.
  string disabled_topics_list;
};

// Struct representing the state of one topic that will be displayed by WebUI.
struct WebUITopic {
  // An integer id for this topic.
  int32 topic_id;

  // The readable name for this topic.
  mojo_base.mojom.String16 topic_name;

  // Whether the topic is a real topic derived from browsing history or a
  // randomly padded one.
  bool is_real_topic;

  // The context domains that have observed the topic (i.e. called the
  // document.browsingTopics() API in a page that is classified to the topic).
  array<string> observed_by_domains;
};

// Struct representing the state of one epoch that will be displayed by WebUI.
struct WebUIEpoch {
  // The top topics for this epoch derived from the browsing history.
  array<WebUITopic> topics;

  // When the topics were calculated.
  mojo_base.mojom.Time calculation_time;

  // The version of the model used to calculate this epoch's topics.
  string model_version;

  // The version of the taxonomy applicable to this epoch's topics.
  string taxonomy_version;
};

// Struct representing the topics state that will be displayed by WebUI.
struct WebUIBrowsingTopicsState {
  // Epochs ordered from latest to oldest.
  array<WebUIEpoch> epochs;

  // The next time when topics will be calculated.
  mojo_base.mojom.Time next_scheduled_calculation_time;
};

// Contains either the topics state, or an error/override message.
union WebUIGetBrowsingTopicsStateResult {
  // To be displayed in the UI for showing errors, or giving more clarifications
  // for an empty state.
  string override_status_message;

  // The topics state.
  WebUIBrowsingTopicsState browsing_topics_state;
};

// Struct representing the model metadata that will be displayed by WebUI.
struct WebUIModelInfo {
  string model_version;
  string model_file_path;
};

// Contains either the model metadata, or an error/override message.
union WebUIGetModelInfoResult {
  string override_status_message;
  WebUIModelInfo model_info;
};

// Browser interface for the page. Consists of calls for data and hooks for
// interactivity. This is implemented in the browser and handling requests from
// the WebUI renderer.
interface PageHandler {
  // Get the features and configuration parameters related to the topics API.
  GetBrowsingTopicsConfiguration() => (WebUIBrowsingTopicsConfiguration config);

  // Get the topics state. If `calculate_now` is true, this will first trigger a
  // calculation before returning the topics state.
  GetBrowsingTopicsState(bool calculate_now)
    => (WebUIGetBrowsingTopicsStateResult result);

  // Get the model metadata.
  GetModelInfo() => (WebUIGetModelInfoResult result);

  // Classify `hosts` into topics using the same classification service that the
  // Topics API (https://github.com/patcg-individual-drafts/topics) relies on,
  // e.g. as if the Topics calculation happens now where `hosts` are the
  // eligible hosts in the browsing history. Precondition: `hosts` is not empty.
  // If the classification succeeds, each nested array in `topics_for_hosts`
  // will contain the topics for the corresponding entry in `hosts`; if the
  // classification fails, (e.g. model unavailable), `topics_for_hosts` will be
  // an empty array.
  //
  // Note that the model or its availability status may have changed since the
  // last call to `GetModelInfo()` (i.e. the WebUI implementation always happens
  // to do in this order), but this is a minor issue so we won't expose the
  // model info via this method again.
  ClassifyHosts(array<string> hosts)
    => (array<array<WebUITopic>> topics_for_hosts);
};