epoch_topics.h 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. // Copyright 2022 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_
  5. #define COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_
  6. #include "base/time/time.h"
  7. #include "base/values.h"
  8. #include "components/browsing_topics/topic_and_domains.h"
  9. #include "components/browsing_topics/util.h"
  10. #include "url/origin.h"
  11. namespace browsing_topics {
  12. // Contains the epoch's top topics. This is the necessary data to calculate the
  13. // browsing topic for one epoch when a context requests it via
  14. // document.browsingTopics().
  15. class EpochTopics {
  16. public:
  17. explicit EpochTopics(base::Time calculation_time);
  18. EpochTopics(std::vector<TopicAndDomains> top_topics_and_observing_domains,
  19. size_t padded_top_topics_start_index,
  20. size_t taxonomy_size,
  21. int taxonomy_version,
  22. int64_t model_version,
  23. base::Time calculation_time);
  24. EpochTopics(const EpochTopics&) = delete;
  25. EpochTopics& operator=(const EpochTopics&) = delete;
  26. EpochTopics(EpochTopics&&);
  27. EpochTopics& operator=(EpochTopics&&);
  28. ~EpochTopics();
  29. // Serialization functions for storing in prefs.
  30. static EpochTopics FromDictValue(const base::Value::Dict& dict_value);
  31. base::Value::Dict ToDictValue() const;
  32. // Calculate the topic to expose on `top_domain` when requested by a context
  33. // where the domain hash is `hashed_context_domain`. `output_is_true_topic`
  34. // will indicate whether the returned topic (if any) is a true top topic.
  35. // `candidate_topic_filtered` will indicate whether the empty result is due to
  36. // the candicate topic is filtered. Return absl::nullopt when there are no
  37. // topics (i.e. calculation failed, or the topics were cleared), or when the
  38. // candidate topic is filtered due to the context has not observed the topic
  39. // before. The `hmac_key` is the one used to hash the domains inside
  40. // `top_topics_and_observing_domains_` and `hashed_context_domain`.
  41. absl::optional<Topic> TopicForSite(const std::string& top_domain,
  42. const HashedDomain& hashed_context_domain,
  43. ReadOnlyHmacKey hmac_key,
  44. bool& output_is_true_topic,
  45. bool& candidate_topic_filtered) const;
  46. // Similar to `TopicForSite`, but this does not apply the filtering based on a
  47. // calling context, and only returns a topic if the candidate topic is a true
  48. // top topic (as opposed to the random topic, or the randomly padded top
  49. // topic). This method is used for displaying the candidate topics for a site
  50. // for the UX.
  51. absl::optional<Topic> TopicForSiteForDisplay(const std::string& top_domain,
  52. ReadOnlyHmacKey hmac_key) const;
  53. // Whether `top_topics_and_observing_domains_` is empty.
  54. bool empty() const { return top_topics_and_observing_domains_.empty(); }
  55. // Clear `top_topics_and_observing_domains_` and
  56. // reset `padded_top_topics_start_index_` to 0.
  57. void ClearTopics();
  58. // Clear an entry in `top_topics_and_observing_domains_` that matches `topic`.
  59. void ClearTopic(Topic topic);
  60. // Clear the domains in `top_topics_and_observing_domains_` that match
  61. // `hashed_context_domain`.
  62. void ClearContextDomain(const HashedDomain& hashed_context_domain);
  63. const std::vector<TopicAndDomains>& top_topics_and_observing_domains() const {
  64. return top_topics_and_observing_domains_;
  65. }
  66. size_t padded_top_topics_start_index() const {
  67. return padded_top_topics_start_index_;
  68. }
  69. size_t taxonomy_size() const { return taxonomy_size_; }
  70. int taxonomy_version() const { return taxonomy_version_; }
  71. int64_t model_version() const { return model_version_; }
  72. base::Time calculation_time() const { return calculation_time_; }
  73. private:
  74. absl::optional<Topic> TopicForSiteHelper(
  75. const std::string& top_domain,
  76. bool need_filtering,
  77. bool allow_random_or_padded_topic,
  78. const HashedDomain& hashed_context_domain,
  79. ReadOnlyHmacKey hmac_key,
  80. bool& output_is_true_topic,
  81. bool& candidate_topic_filtered) const;
  82. // The top topics for this epoch, and the context domains that observed each
  83. // topic across
  84. // `kBrowsingTopicsNumberOfEpochsOfObservationDataToUseForFiltering` epochs.
  85. // Its length should be either equal to the configuration parameter
  86. // `kBrowsingTopicsNumberOfTopTopicsPerEpoch`, or 0, which may be due to not
  87. // enough history entries, permission denial for calculating, or history
  88. // deletion.
  89. std::vector<TopicAndDomains> top_topics_and_observing_domains_;
  90. // Some topics in `top_topics_and_observing_domains_` may be randomly padded
  91. // at the end. `padded_top_topics_start_index_` is the starting index of
  92. // those randomly padded topics. If all topics in
  93. // `top_topics_and_observing_domains_` are real, then
  94. // `padded_top_topics_start_index_` will equal
  95. // `top_topics_and_observing_domains_.size()`.
  96. size_t padded_top_topics_start_index_ = 0;
  97. // The size of the taxonomy applicable to this epoch's topics.
  98. size_t taxonomy_size_ = 0;
  99. // The version of the taxonomy applicable to this epoch's topics.
  100. int taxonomy_version_ = 0;
  101. // The version of the model used to calculate this epoch's topics.
  102. int64_t model_version_ = 0;
  103. // The calculation start time. This determines the end time of this epoch's
  104. // underlying topics data, and may determine the start time of future epochs'
  105. // underlying topics data. It's only best effort to read this field from a
  106. // failed calculation, as historically this field is only set for successful
  107. // calculations.
  108. base::Time calculation_time_;
  109. };
  110. } // namespace browsing_topics
  111. #endif // COMPONENTS_BROWSING_TOPICS_EPOCH_TOPICS_H_