components/precache/core/proto/precache.proto

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

syntax = "proto2";

package precache;

// Chrome requires this.
option optimize_for = LITE_RUNTIME;

// Information about a cacheable resource to be precached.
message PrecacheResource {
  // The URL of the resource. This field must always be present.
  optional string url = 1;

  // The tophost this resource corresponds to.
  optional string top_host_name = 2;

  // How important this resource is for the host. It ranges from 0.0 to 1.0.
  // Higher values mean more important.
  optional double weight_ratio = 3;

  // How important this resource is for the client; a combination of
  // weight_ratio and TopHost.visits. Populated only in PrecacheUnfinishedWork.
  // This is a non-negative number, with higher being more important. Its value
  // depends on PrecacheConfigurationSettings.resource_weight_function.
  optional double weight = 4;

  enum Type {
    RESOURCE_TYPE_UNKNOWN = 0;

    RESOURCE_TYPE_IMAGE = 1;
    RESOURCE_TYPE_FONT = 2;
    RESOURCE_TYPE_STYLESHEET = 3;
    RESOURCE_TYPE_SCRIPT = 4;

    RESOURCE_TYPE_OTHER = 7;
  }

  // The type of resource.
  optional Type type = 5;
};

message PrecacheManifestId {
  optional int64 id = 1;
};

// A manifest of cacheable resources to be precached for a specific host.
// CAUTION: When any change is done here, bump kDatabaseVersion in
// chrome/browser/predictors/resource_prefetch_predictor_tables.h
message PrecacheManifest {
  // List of resources that we predict that the user will need if they are
  // likely to fetch the host.
  repeated PrecacheResource resource = 1;

  // Experiments running on this manifest.
  optional PrecacheExperiments experiments = 2;

  // Identifier for the manifest sent by the server.
  optional PrecacheManifestId id = 3;
};

message PrecacheExperiments {
  // A mapping between experiment groups and the resources that should be
  // considered for the experiment.
  map<fixed32, PrecacheResourceSelection> resources_by_experiment_group = 1;
};

// Determines which of the resources in the manifest should be selected.
message PrecacheResourceSelection {
  // A bitset over the resources listed in the manifest. Bits correspond to
  // resource position in LSB-to-MSB order, as in:
  //
  //   if ((0x1ULL << i) && DEPRECATED_bitset) IncludeResource(i);
  //
  // Deprecated because it only supports up to 64 resources.
  optional fixed64 DEPRECATED_bitset = 1
      [default = 0xFFFFFFFFFFFFFFFF, deprecated = true];

  // A bitset over the resources listed in the manifest. Bits correspond to
  // resource position. Bytes are ordered little-endian, and bits within each
  // byte are ordered LSB-to-MSB. The resulting bitstream is of mixed order,
  // but easy to test:
  //
  //   if ((1 << (i % 8)) & bitset[i / 8]) IncludeResource(i);
  //
  // Takes precedence over DEPRECATED_bitset, if both are present.
  optional bytes bitset = 2;

  // A PrecacheResourceSelection without DEPRECATED_bitset or bitset means that
  // all resources should be selected.
};

message PrecacheConfigurationSettings {
  // The maximum rank of the user's most visited hosts to consider precaching
  // resources for, starting from 1. For example, a value of 10 means that only
  // hosts that are in the user's top 10 most visited hosts will be considered
  // as starting URLs for resource precaching. This is specified by the server
  // for testing purposes, so that it's easy to adjust how aggressively
  // resources are precached.
  // Values that are zero or lower indicate that none of the user's top sites
  // will be used for precaching.
  optional int64 top_sites_count = 1 [default = 100];

  // List of additional hosts that resources will be precached for.
  // These are hosts that the server predicts that the user will visit, as a
  // result of server-side analytics.
  repeated string forced_site = 2;

  // The number of resources to fetch for each site. Only the top
  // |top_resources_count| URLs from each manifest are fetched.
  optional int32 top_resources_count = 3 [default = 100];

  // The maximum number of bytes to download per resource. Downloads of
  // resources larger than this will be cancelled. This max applies only to new
  // downloads; cached resources are not capped.
  optional uint64 max_bytes_per_resource = 4 [default = 500000 /* 500 KB */];

  // The maximum number of bytes per precache run. While precaching, the total
  // number of bytes used for resources is tallied -- this includes new
  // downloads as well as cached resources. After this limit is reached, no
  // other resources will be downloaded.
  optional uint64 max_bytes_total = 5 [default = 10000000 /* 10 MB */];

  // The maximum number of bytes that can be fetched by precache on a single
  // day. After this limit is reached, no more resources will be downloaded,
  // until the quota gets replenished the next day.
  optional uint64 daily_quota_total = 6 [default = 40000000 /* 40 MB */];

  // The number of resources to fetch per precache run. Only the first
  // |total_resources_count| resource URLs are fetched.
  optional uint32 total_resources_count = 7 [default = 999999];

  // The minimum visit-adjusted weight for which a resource will be downloaded.
  optional double min_weight = 8 [default = 0];

  // Whether to sort resources by weight, descending, before fetching. This
  // affects the fetcher's behavior with respect to max_bytes_total and
  // total_resources_count.
  optional bool global_ranking = 9 [default = false];

  // If true, resource fetches are only made over the network for a given URL if
  // an existing cache entry exists and has revalidation headers.
  optional bool revalidation_only = 10 [default = false];

  // The function to use to combine a resource's weight_ratio with its
  // referring manifest's host_visits count to produce a final score.
  enum ResourceWeightFunction {
    // Models the expected number of requests for the resource in the next 30
    // days, given that weight_ratio is a probability that a visit to the host
    // will request a resource, and host_visits is an estimate of the number of
    // visits to the host in the next 30 days.
    FUNCTION_NAIVE = 0;
    // Models the probability of at least one request, given the same.
    FUNCTION_GEOMETRIC = 1;
  };
  optional ResourceWeightFunction resource_weight_function = 11
      [default = FUNCTION_NAIVE];
};