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

syntax = "proto2";
option optimize_for = LITE_RUNTIME;
option java_package = "org.chromium.components.optimization_guide.proto";
option java_outer_classname = "HintsProto";

package optimization_guide.proto;

import "components/optimization_guide/proto/common_types.proto";
import "components/optimization_guide/proto/loading_predictor_metadata.proto";

// Information about the hint that the client already has for a host.
message MatchedHintInfo {
  // Describes the granularity of the key field.
  optional KeyRepresentation key_representation = 1;
  // The key of the hint currently used for the host.
  optional string key = 2;
  // The version of the hint for this key already stored on the client.
  optional int64 version = 3;
}

message HostInfo {
  // Host that the client is requesting information for.
  optional string host = 1;
  // Information about the hint that the client already has for the host.
  optional MatchedHintInfo matched_hint = 2;
}

// Information about a URL to request hints for.
message UrlInfo {
  // The URL that the client is requesting information for.
  optional string url = 1;
}

// Information about the set of host hashes to retrieve hints for.
message HashedHostInfos {
  // The partial host hash will be the first num_hash_bits least significant bit
  // of the hashed host.
  repeated uint32 partial_host_hashes = 1;
  optional uint32 num_hash_bits = 2;
}

// Request to return a set of hints that guide what optimizations to perform
// on those hosts.
message GetHintsRequest {
  reserved 6, 10;

  // Information about the set of hosts to retrieve hints for.
  repeated HostInfo hosts = 1;

  // Information about the set of URLs to retrieve hints for.
  repeated UrlInfo urls = 4;

  // Information about the set of host hashes to retrieve hints for.
  optional HashedHostInfos hashed_hosts = 8;

  // The set of optimization types that the requesting client can support
  // and perform.
  //
  // It is guaranteed that the response will only contain hints for
  // optimizations present in this set.
  repeated OptimizationType supported_optimizations = 2;

  // The set of key representations that the client can process.
  //
  // It is guaranteed that the response will only contain hints for key
  // representations present in this set. If not specified,
  // [HOST_SUFFIX, FULL_URL] will be used.
  repeated KeyRepresentation supported_key_representations = 5;

  // Context in which this request is made.
  optional RequestContext context = 3;

  // Metadata related to how the request with this context was made.
  optional RequestContextMetadata context_metadata = 11;

  // The locale to associate with this request.
  //
  // It is the IETF language tag, defined in BCP 47. The region subtag is not
  // included when it adds no distinguishing information to the language tag
  // (e.g. both "en-US" and "fr" are correct here).
  optional string locale = 7;

  // Information about the request origin.
  optional OriginInfo origin_info = 9;
}

message RequestContextMetadata {
  // update logic at {@link HintsManager::CanApplyOptimizationOnDemand} for
  // getting the context metadata sent and setting the metadata w.r.t the
  // context.
  oneof metadata {
    // Only filled in when RequestContext is CONTEXT_PAGE_INSIGHTS_HUB.
    PageInsightsHubRequestContextMetadata page_insights_hub_metadata = 1;
  }
}

message PageInsightsHubRequestContextMetadata {
  // True if the Page Insights feature was triggered by the user (as opposed to
  // auto-peeking).
  optional bool is_user_initiated = 1;
  // True if the Page Insights feature is showing on top of an initial page. See
  // go/pih-cct-conditions.
  optional bool is_initial_page = 2;
  // True if logging of URL by server, and personalisation of response, is
  // forbidden.
  optional bool should_not_log_or_personalize = 3;
  // Timestamp for the navigation that reached the URL, in milliseconds.
  optional int64 navigation_timestamp_ms = 4;
}

// Response to the GetHints request.
message GetHintsResponse {
  // An ordered list containing hints for key/optimization combinations.
  //
  // It is guaranteed that there will only be a single hint per key and key
  // representation combination. These hints are intended to apply to a full
  // page. It is expected that the client will use the Hint record with the
  // most specific key that matches the main frame URL.
  repeated Hint hints = 1;

  // The maximum duration in which the hints, or lack of hints, provided in
  // this response are valid.
  optional Duration max_cache_duration = 2;

  // A set of hint keys to remove from the client cache.
  //
  // It is guaranteed that all entries in this list were provided by the client
  // in the corresponding request's |hosts.matched_hint| fields.
  //
  // It is expected for the client to immediately stop using all hints contained
  // in this field. Hints that are not present in |hints| or in this field
  // should adhere to the client cache's existing expiration policy.
  repeated MatchedHintInfo hints_to_remove = 3;
}

// These values must reflect the values defined in the server-side
// OptimizationType enum at http://shortn/_t8G1sv8yAS (Google-internal link).
// Additionally, these values must be synchronized with the OptimizationType
// enum in enums.xml and optimization/histograms.xml for metric recording.
enum OptimizationType {
  // Values for obsolete optimizations.
  reserved 11, 12, 16, 29, 32, 66, 72, 73, 89, 94, 95;

  TYPE_UNSPECIFIED = 0;
  // This optimization blocks JavaScript on the page.
  NOSCRIPT = 1;
  // This optimization applies a set of ResourceLoadingHint(s) to load the
  // page.
  RESOURCE_LOADING = 2;
  // This optimization redirects the navigation through a lite page server.
  LITE_PAGE_REDIRECT = 3;
  // This optimization does validation of metadata fetch on navigation.
  METADATA_FETCH_VALIDATION = 4;
  // This optimization defers execution of parser-blocking script until after
  // parsing completes.
  DEFER_ALL_SCRIPT = 5;
  // This optimization is used to provide aggregated performance information
  // about the page and pages it links to.
  PERFORMANCE_HINTS = 6;
  // This optimization allows page loads going through the data reduction
  // proxy to be transformed by the proxy.
  LITE_PAGE = 7;
  // This optimization compresses public images.
  COMPRESS_PUBLIC_IMAGES = 8;
  // This optimization provides the Loading Predictor with resources predicted
  // to be on the page.
  LOADING_PREDICTOR = 9;
  // This optimization provides information about hosts that historically
  // provide a fast and responsive user experience.
  FAST_HOST_HINTS = 10;
  // This optimization provides information about how to throttle meda requests
  // to reduce the bitrate of adaptively streamed media.
  LITE_VIDEO = 13;
  // This optimization is used to provide aggregated performance information
  // about pages linked to from the current page.
  LINK_PERFORMANCE = 14;
  // Detects if a page is a shopping page or not. A tradeoff has been made here
  // where the number of shopping page predictions for non-shopping pages is
  // increased to reduce the number of non-shopping page predictions for
  // shopping pages.
  SHOPPING_PAGE_PREDICTOR = 15;
  // Provides key information about the merchant represented by the current
  // host.
  MERCHANT_TRUST_SIGNALS = 17;
  // Provides pricing data so the user can track prices and price updates.
  PRICE_TRACKING = 18;
  // This optimization does validation of bloom filter.
  BLOOM_FILTER_VALIDATION = 19;
  // Provides 'About this site' data about the site being visited.
  ABOUT_THIS_SITE = 20;
  // Provides key information about the merchant represented by the current
  // host -- VERSION 2.
  MERCHANT_TRUST_SIGNALS_V2 = 21;
  // Provides the entities that are present on the page.
  PAGE_ENTITIES = 22;
  // This optimization provides information for whether a page should be
  // included in a history cluster.
  HISTORY_CLUSTERS = 23;
  // Determines if a page is eligible for 'Thank creator' functionality.
  THANK_CREATOR_ELIGIBLE = 24;
  // This optimization provides information about hosts that are blocked for
  // IBAN autofill.
  IBAN_AUTOFILL_BLOCKED = 25;
  // This optimization provides information about images for a URL.
  SALIENT_IMAGE = 26;
  // This optimization provides information about a sampling rate of Autofill
  // UKM metrics per origin based on origin popularity.
  AUTOFILL_SAMPLING_RATE = 27;
  // This optimization provides information about whether a merchant is
  // opted-out of Visa virtual cards for a URL.
  VCN_MERCHANT_OPT_OUT_VISA = 28;
  // Provides price insights data including the typical price range and the
  // price history.
  PRICE_INSIGHTS = 30;
  // Information about which JavaScript functions should be eager compiled.
  V8_COMPILE_HINTS = 31;
  // This optimization provides information about shoppinge page types of this
  // page.
  SHOPPING_PAGE_TYPES = 33;
  // This optimization provides information about shopping discounts for a URL.
  SHOPPING_DISCOUNTS = 34;
  // This optimization helps determine if this page is a good candidate for
  // compose.
  COMPOSE = 35;
  // This optimization provides information about whether a merchant can be
  // triggered with PIX bottom sheet. This allowlist uses page pattern matching
  // to perform regex match against entire URLs.
  PIX_PAYMENT_MERCHANT_ALLOWLIST = 36;
  // The below optimizations provide information for merchant URLs that are
  // eligible for credit card category benefits. These URLs are shared and apply
  // to all card issuers that support showing benefits on Chrome.
  SHARED_CREDIT_CARD_FLIGHT_BENEFITS = 37;
  SHARED_CREDIT_CARD_DINING_BENEFITS = 38;
  SHARED_CREDIT_CARD_GROCERY_BENEFITS = 39;
  SHARED_CREDIT_CARD_ENTERTAINMENT_BENEFITS = 40;
  SHARED_CREDIT_CARD_STREAMING_BENEFITS = 41;
  SHARED_CREDIT_CARD_SUBSCRIPTION_BENEFITS = 42;
  // The below optimizations provide information about merchant URLs that only
  // Capital One supports for credit card category benefits.
  CAPITAL_ONE_CREDIT_CARD_DINING_BENEFITS = 43;
  CAPITAL_ONE_CREDIT_CARD_GROCERY_BENEFITS = 44;
  CAPITAL_ONE_CREDIT_CARD_ENTERTAINMENT_BENEFITS = 45;
  CAPITAL_ONE_CREDIT_CARD_STREAMING_BENEFITS = 46;
  // The below optimizations provide information about merchant URLs that only
  // American Express supports for credit card category benefits.
  AMERICAN_EXPRESS_CREDIT_CARD_FLIGHT_BENEFITS = 47;
  AMERICAN_EXPRESS_CREDIT_CARD_SUBSCRIPTION_BENEFITS = 48;
  // This optimization provides information about URLs that should be blocked
  // from displaying Capital One credit card benefits.
  CAPITAL_ONE_CREDIT_CARD_BENEFITS_BLOCKED = 55;
  // This optimization provides information about whether a merchant is
  // opted-out of Discover virtual cards for a URL.
  VCN_MERCHANT_OPT_OUT_DISCOVER = 56;
  // This optimization provides information about whether a merchant is
  // opted-out of Mastercard virtual cards for a URL.
  VCN_MERCHANT_OPT_OUT_MASTERCARD = 57;
  // This optimization provides information about merchants origins for which
  // PIX payments should be triggered. This allowlist contains a list of origins
  // and uses a bloom filter for matching.
  PIX_MERCHANT_ORIGINS_ALLOWLIST = 58;
  // This optimization provides information for whether a page is eligible for
  // history embeddings.
  HISTORY_EMBEDDINGS = 59;
  // The following optimizations provide information about sites on which
  // an autofill ablation is supposed to be applied.
  AUTOFILL_ABLATION_SITES_LIST1 = 60;
  AUTOFILL_ABLATION_SITES_LIST2 = 61;
  AUTOFILL_ABLATION_SITES_LIST3 = 62;
  AUTOFILL_ABLATION_SITES_LIST4 = 63;
  AUTOFILL_ABLATION_SITES_LIST5 = 64;
  AUTOFILL_ABLATION_SITES_LIST6 = 65;
  // This optimization helps determine if this merchant page is a good candidate
  // for enabling price/amount extraction.
  AMOUNT_EXTRACTION_ALLOWLIST = 67;
  // This optimization provides information about sites for which pages Autofill
  // prediction improvements should be triggered on.
  AUTOFILL_PREDICTION_IMPROVEMENTS_ALLOWLIST = 68;
  // This optimization helps determine if this merchant page is a good candidate
  // for enabling buy now pay later flow with Affirm.
  BUY_NOW_PAY_LATER_ALLOWLIST_AFFIRM = 69;
  // This optimization helps determine if this merchant page is a good candidate
  // for enabling buy now pay later flow with Zip.
  BUY_NOW_PAY_LATER_ALLOWLIST_ZIP = 70;
  // Provides information about whether a URL can be synced across devices for
  // saved tab groups feature.
  SAVED_TAB_GROUP = 71;
  // This optimization provides information about whether a page is eligible for
  // text classifier entity detection. This feature is iOS only.
  TEXT_CLASSIFIER_ENTITY_DETECTION = 74;
  // This optimization provides information about merchants origins for which
  // eWallet push payments should be allowed.
  EWALLET_MERCHANT_ALLOWLIST = 75;
  // Provides information for what to show in the debug icon view.
  OPTIMIZATION_GUIDE_ICON_VIEW = 76;
  // This optimization provides information about whether a page is a privacy
  // policy page.
  PRIVACY_POLICY_ANNOTATION = 77;
  // The below optimizations provide information about merchant URLs that only
  // BMO supports for credit card category benefits.
  BMO_CREDIT_CARD_AIR_MILES_PARTNER_BENEFITS = 78;
  BMO_CREDIT_CARD_ALCOHOL_STORE_BENEFITS = 79;
  BMO_CREDIT_CARD_DINING_BENEFITS = 80;
  BMO_CREDIT_CARD_DRUGSTORE_BENEFITS = 81;
  BMO_CREDIT_CARD_ENTERTAINMENT_BENEFITS = 82;
  BMO_CREDIT_CARD_GROCERY_BENEFITS = 83;
  BMO_CREDIT_CARD_OFFICE_SUPPLY_BENEFITS = 84;
  BMO_CREDIT_CARD_RECURRING_BILL_BENEFITS = 85;
  BMO_CREDIT_CARD_TRANSIT_BENEFITS = 86;
  BMO_CREDIT_CARD_TRAVEL_BENEFITS = 87;
  BMO_CREDIT_CARD_WHOLESALE_CLUB_BENEFITS = 88;
  // Provides information about whether a page is eligible to cue for GLIC.
  GLIC_CONTEXTUAL_CUEING = 90;
  // Provides information about the contextual zero state suggestions for a
  // page.
  GLIC_ZERO_STATE_SUGGESTIONS = 91;
  // Provides information about whether GLIC may act on a page.
  GLIC_ACTION_PAGE_BLOCK = 92;
  // Provides information about FedCM API clickthrough rate aggregated across
  // all users on the page.
  FEDCM_CLICKTHROUGH_RATE = 93;
  // Provides information about whether the page is eligible for GLIC.
  GLIC_PAGE_CONTEXT_ELIGIBILITY = 96;
  // Provides information about whether the page is eligible for Digital
  // Credentials low friction.
  DIGITAL_CREDENTIALS_LOW_FRICTION = 97;
}

// Presents semantics for how page load URLs should be matched.
enum KeyRepresentation {
  REPRESENTATION_UNSPECIFIED = 0;
  // The suffix to match in the hostname of a page load URL.
  //
  // Example: A host suffix of example.com would match pages with host
  // sports.example.com, but not fooexample.com.
  HOST_SUFFIX = 1 [deprecated = true];
  // The full URL to match.
  //
  // This will be an exact match of a page load URL, including query params and
  // fragments.
  FULL_URL = 2;
  // The host to match.
  //
  // This will be an exact match of a page load host.
  HOST = 3;
  // This will be a partial hash of a page load host.
  HASHED_HOST = 4;
}

message Optimization {
  reserved 2, 3, 4, 5, 10, 11, 12, 14;
  // The type of optimization the hint applies to.
  optional OptimizationType optimization_type = 1;
  // The version of the tuning group for the optimization type.
  //
  // This will only be populated if this optimization is being autotuned.
  //
  // If this is set to UINT64_MAX, this optimization should be considered as
  // not allowed and was only included for metrics purposes.
  optional uint64 tuning_version = 6;
  // The metadata associated with the optimization type.
  //
  // It is expected that the client and server have agreed upon the appropriate
  // metadata type for the optimization type.
  //
  // New clients should utilize any_metadata rather than adding another field.
  oneof metadata {
    LoadingPredictorMetadata loading_predictor_metadata = 13;
    Any any_metadata = 15;
  }
}

message PageHint {
  reserved 2;

  // The pattern to match against the committed page URL.
  //
  // The pattern may be a single substring to match against the full URL or it
  // may be an ordered set of substrings to match where the substrings are
  // separated by the ‘*’ wildcard character (with an implicit ‘*’ at the
  // beginning and end).
  optional string page_pattern = 1;
  // An ordered set of optimizations that should be allowlisted for this page
  // pattern.
  //
  // The client will use the first optimization that it supports.
  repeated Optimization allowlisted_optimizations = 3;
}

message Hint {
  // Describes the granularity of the key field.
  optional KeyRepresentation key_representation = 1;
  // The key that applies to this hint. The key_representation field describes
  // the form in which this key takes. Guaranteed to be non-empty.
  optional string key = 2;
  // An unordered set of optimizations that should be allowlisted for this
  // hint.
  //
  // This field is currently only specified for key_representation of HOST.
  repeated Optimization allowlisted_optimizations = 3;
  // An ordered set of per-page hints. Only the first PageHint record
  // that matches a committed page URL should be used for that page load.
  repeated PageHint page_hints = 4;
  // Version that generated this hint.
  //
  // It is expected that this version be sent along with subsequent requests
  // for hosts that match this hint.
  optional string version = 5;
  // The maximum duration for which the hint should be used for.
  optional Duration max_cache_duration = 6;
}

// Configuration and data for a Bloom filter.
//
// Note that some additional aspects of the BloomFilter are separately
// specified between the client and server including the specific MurmurHash3
// hashing function, how the hashing function is seeded, how bits are
// addressed in the byte vector, and the nature of the strings that the
// Bloom filter holds (whether host, host suffix, URL path, etc.).
message BloomFilter {
  // Specifies the number of hash functions to use in the Bloom filter.
  // This essentially means how many bits will be set in the bit array
  // for a string member of the Bloom filter.
  optional uint32 num_hash_functions = 1;
  // The number of bits in the Bloom filter's bit array.
  optional uint32 num_bits = 2;
  // The bit array data of the Bloom filter provided via a byte vector.
  // The number of bytes provided must be large enough to hold the
  // specified number of bits (num_bits).
  optional bytes data = 3;
}

// The format for input to the bloom filter.
enum BloomFilterFormat {
  BLOOM_FILTER_FORMAT_UNKNOWN = 0;
  BLOOM_FILTER_FORMAT_PLAINTEXT = 1;
  BLOOM_FILTER_FORMAT_SHA256 = 2;
}

// A scalable filter for an optimization type.
//
// Next ID: 7
message OptimizationFilter {
  // The type of optimization this filter applies to.
  optional OptimizationType optimization_type = 1;
  // The filter data represented as a Bloom filter.
  optional BloomFilter bloom_filter = 2;
  // Additional filters represented as regexps matched against the main page
  // URL. If matched, the URL will be considered as contained in the filter.
  repeated string regexps = 3;
  // Additional filters represented as regexps matched against the main page
  // URL. If matched, the URL will be considered as not contained in the filter.
  //
  // This set of regexps should be checked prior to any matching against the
  // contained bloom_filter or regexps fields.
  repeated string exclusion_regexps = 5;
  // Whether additional host suffixes (other than the host) should be checked
  // against the filter.
  optional bool skip_host_suffix_checking = 4;
  // The format to check against the bloom filter. Note this only applies
  // to checks in the bloom_filter and not regexps.
  optional BloomFilterFormat bloom_filter_format = 6;
}

message Configuration {
  // An ordered list containing hints for key/optimization combinations.
  //
  // It is guaranteed that there will only be a single hint per key and key
  // representation combination. These hints are intended to apply to a full
  // page.
  //
  // Note, this list may contain multiple hints that apply to a page. For
  // example, if there are hints for (HOST_SUFFIX,example.com) and
  // (HOST_SUFFIX,sports.example.com), these may both apply to
  // sports.example.com/foo.
  //
  // The client will use the first Hint record with a key that matches the
  // main frame URL. Therefore, the server should provide all the hint
  // details for that key that it wants to provide as the client will only
  // look at that one record to decide which optimization to apply.
  repeated Hint hints = 1;
  // A set of per-optimization blocklists.
  //
  // It is guaranteed that an optimization type will not have filters in both
  // |optimization_blocklists| and |optimization_allowlists|.
  repeated OptimizationFilter optimization_blocklists = 2;
  // A set of per-optimization allowlists.
  //
  // It is guaranteed that an optimization type will not have filters in both
  // |optimization_blocklists| and |optimization_allowlists|.
  repeated OptimizationFilter optimization_allowlists = 3;
}

enum HintSource {
  HINT_SOURCE_UNKNOWN = 0;
  // Served from the Chrome Optimization Hints Component.
  HINT_SOURCE_OPTIMIZATION_HINTS_COMPONENT = 1;
  // Served from the Chrome Optimization Guide Service.
  HINT_SOURCE_OPTIMIZATION_GUIDE_SERVICE = 2;
}

message Version {
  reserved 2;

  // The time the hint was generated.
  optional Timestamp generation_timestamp = 1;
  // The source from which the hint was served from.
  optional HintSource hint_source = 3;
}

// The theme the user is using.
enum ThemeKey {
  THEME_KEY_UNKNOWN = 0;
  // User is using light mode.
  THEME_KEY_LIGHT = 1;
  // User is using dark mode.
  THEME_KEY_DARK = 2;
}