components/browsing_topics/epoch_topics.h

   1 // Copyright 2022 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_
   6 #define COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_
   7
   8 #include "base/time/time.h"
   9 #include "base/values.h"
  10 #include "components/browsing_topics/candidate_topic.h"
  11 #include "components/browsing_topics/topic_and_domains.h"
  12 #include "components/browsing_topics/util.h"
  13 #include "url/origin.h"
  14
  15 namespace browsing_topics {
  16
  17 // Contains the epoch's top topics. This is the necessary data to calculate the
  18 // browsing topic for one epoch when a context requests it via
  19 // document.browsingTopics().
  20 class EpochTopics {
  21  public:
  22   explicit EpochTopics(base::Time calculation_time);
  23
  24   EpochTopics(std::vector<TopicAndDomains> top_topics_and_observing_domains,
  25               size_t padded_top_topics_start_index,
  26               int config_version,
  27               int taxonomy_version,
  28               int64_t model_version,
  29               base::Time calculation_time,
  30               bool from_manually_triggered_calculation);
  31
  32   EpochTopics(const EpochTopics&) = delete;
  33   EpochTopics& operator=(const EpochTopics&) = delete;
  34
  35   EpochTopics(EpochTopics&&);
  36   EpochTopics& operator=(EpochTopics&&);
  37
  38   ~EpochTopics();
  39
  40   // Serialization functions for storing in prefs.
  41   static EpochTopics FromDictValue(const base::Value::Dict& dict_value);
  42   base::Value::Dict ToDictValue() const;
  43
  44   // Calculate the candidate topic to expose on `top_domain` when requested by a
  45   // context where the domain hash is `hashed_context_domain`. The candidate
  46   // topic will be annotated with `is_true_topic` and `should_be_filtered` based
  47   // on its type and/or whether `hashed_context_domain` has observed the topic.
  48   // Returns an invalid `CandidateTopic` when there is no topic (e.g.
  49   // failed epoch topics calculation, cleared history, or cleared/blocked
  50   // individual topics). The `hmac_key` is the one used to hash the domains
  51   // inside `top_topics_and_observing_domains_` and `hashed_context_domain`.
  52   CandidateTopic CandidateTopicForSite(
  53       const std::string& top_domain,
  54       const HashedDomain& hashed_context_domain,
  55       ReadOnlyHmacKey hmac_key) const;
  56
  57   // Whether `top_topics_and_observing_domains_` is empty.
  58   bool empty() const { return top_topics_and_observing_domains_.empty(); }
  59
  60   // Clear `top_topics_and_observing_domains_` and
  61   // reset `padded_top_topics_start_index_` to 0.
  62   void ClearTopics();
  63
  64   // Clear an entry in `top_topics_and_observing_domains_` that matches `topic`
  65   // and any entry in `top_topics_and_observing_domains_` that is a topic
  66   // descended from `topic`.
  67   void ClearTopic(Topic topic);
  68
  69   // Clear the domains in `top_topics_and_observing_domains_`  that match
  70   // `hashed_context_domain`.
  71   void ClearContextDomain(const HashedDomain& hashed_context_domain);
  72
  73   bool HasValidVersions() const {
  74     return config_version_ > 0 && taxonomy_version_ > 0 && model_version_ > 0;
  75   }
  76
  77   const std::vector<TopicAndDomains>& top_topics_and_observing_domains() const {
  78     return top_topics_and_observing_domains_;
  79   }
  80
  81   size_t padded_top_topics_start_index() const {
  82     return padded_top_topics_start_index_;
  83   }
  84
  85   int config_version() const { return config_version_; }
  86
  87   int taxonomy_version() const { return taxonomy_version_; }
  88
  89   int64_t model_version() const { return model_version_; }
  90
  91   base::Time calculation_time() const { return calculation_time_; }
  92
  93   bool from_manually_triggered_calculation() const {
  94     return from_manually_triggered_calculation_;
  95   }
  96
  97  private:
  98   absl::optional<Topic> TopicForSiteHelper(
  99       const std::string& top_domain,
 100       bool need_filtering,
 101       bool allow_random_or_padded_topic,
 102       const HashedDomain& hashed_context_domain,
 103       ReadOnlyHmacKey hmac_key,
 104       bool& output_is_true_topic,
 105       bool& candidate_topic_filtered) const;
 106
 107   // The top topics for this epoch, and the context domains that observed each
 108   // topic across
 109   // `kBrowsingTopicsNumberOfEpochsOfObservationDataToUseForFiltering` epochs.
 110   // Its length should be either equal to the configuration parameter
 111   // `kBrowsingTopicsNumberOfTopTopicsPerEpoch`, or 0, which may be due to not
 112   // enough history entries, permission denial for calculating, or history
 113   // deletion.
 114   std::vector<TopicAndDomains> top_topics_and_observing_domains_;
 115
 116   // Some topics in `top_topics_and_observing_domains_` may be randomly padded
 117   // at the end. `padded_top_topics_start_index_` is the starting index of
 118   // those randomly padded topics. If all topics in
 119   // `top_topics_and_observing_domains_` are real, then
 120   // `padded_top_topics_start_index_` will equal
 121   // `top_topics_and_observing_domains_.size()`.
 122   size_t padded_top_topics_start_index_ = 0;
 123
 124   // The version of the configuration (other than taxonomy and model) applicable
 125   // to this epoch's topics.
 126   int config_version_ = 0;
 127
 128   // The version of the taxonomy applicable to this epoch's topics.
 129   int taxonomy_version_ = 0;
 130
 131   // The version of the model used to calculate this epoch's topics.
 132   int64_t model_version_ = 0;
 133
 134   // The calculation start time. This determines the end time of this epoch's
 135   // underlying topics data, and may determine the start time of future epochs'
 136   // underlying topics data. It's only best effort to read this field from a
 137   // failed calculation, as historically this field is only set for successful
 138   // calculations.
 139   base::Time calculation_time_;
 140
 141   // Whether the topic calculation was manually triggered via the UI. It is used
 142   // to distinguish manual calculations from scheduled calculations so that
 143   // topics calculated via the UI can be immediately visible to the tester,
 144   // instead of being visible only after a caller-dependant delay. The value
 145   // does not persist after restarting the browser (it is not saved).
 146   bool from_manually_triggered_calculation_ = false;
 147 };
 148
 149 }  // namespace browsing_topics
 150
 151 #endif  // COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_