// 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);
};
Codebase Browser
chromium