system_api/dbus/featured/featured.proto

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

syntax = "proto3";

option optimize_for = LITE_RUNTIME;

// This file defines messages necessary for early boot experimentation
package featured;

option go_package = "go.chromium.org/chromiumos/system_api/featured_proto";

// Defines the key and value of a feature's parameter.
message Param {
  // Key of an experiment's parameter.
  string key = 1;
  // Value of an experiment's parameter.
  string value = 2;
}

// Specifies whether a feature override enables or disables the feature. This
// enum is based off the OverrideState enum in chromium's base/feature_list.h.
enum OverrideState {
  OVERRIDE_USE_DEFAULT = 0;
  OVERRIDE_DISABLE_FEATURE = 1;
  OVERRIDE_ENABLE_FEATURE = 2;
}

// Defines a chrome://flags entry that can override a feature's state determined
// by the evaluate_seed binary.
message FeatureOverride {
  // Name of the feature, always starting with "CrOSEarlyBoot"
  string name = 1;
  // True if the feature is enabled, and false otherwise.
  // NOTE: This field is *deprecated* and will eventually be replaced by the
  // |override_state| field. This field will be deleted after all existing
  // references to it are removed. Future code should *not* use this field.
  bool enabled = 2;
  // If the feature is enabled AND has parameters associated with it,
  // they'll appear here.
  repeated Param params = 3;
  // Name of the field trial (study).
  string trial_name = 4;
  // Name of the experiment group the device is enrolled in.
  string group_name = 5;
  // A tri-state value indicating if the feature is enabled, disabled, or uses
  // default state.
  OverrideState override_state = 6;
}

// Information about the last known "safe" seed.
// Keep in sync with featured::SeedsEqual when adding new fields.
message SeedDetails {
  // The active client locale that was successfully used in association with the
  // last known "safe" seed.
  string locale = 4;
  // Milestone with which the last known "safe" seed was fetched.
  int32 milestone = 5;
  // String form of pair <Chrome version string, country code string> (eg.
  // "106.0.5249.119,us") representing the country used for filtering permanent
  // consistency studies until the next time Chrome is updated.
  string permanent_consistency_country = 6;
  // A country code string representing the country used for evaluating session
  // consistency studies.
  string session_consistency_country = 7;
  // Base64-encoded digital signature of the last known "safe" seed's binary
  // data. Empty if there is no known "safe" seed.
  string signature = 8;
  // The serialized base::Time used for safe seed expiry checks. This is usually
  // the time at which the last known "safe" seed was received; however, it
  // could be a build timestamp if the received date is unknown. An empty
  // (default-constructed) base::Time if there is no known "safe" seed. This is
  // a server-provided timestamp in milliseconds.
  int64 date = 9;
  // The serialized base::Time from the fetch corresponding to the last known
  // "safe" seed. This is a client timestamp in milliseconds.
  int64 fetch_time = 10;
  // Last known "safe" seed represented as the base64-encoded compressed
  // serialized form of the variations.VariationsSeed protobuf.
  bytes b64_compressed_data = 11;

  // Tags 1, 2, and 3 are reserved since they have been deleted.
  // Tag 1 was the last known "safe" seed represented as the serialized form of
  // the variations.VariationsSeed protobuf. Despite the name, it was
  // decompressed data that came from VariationsSeedStore::LoadSeed.
  // Tags 2 and 3 were used for older versions of the date and fetch_time
  // fields, which were both of type google.protobuf.Timestamp. Importing
  // google.protobuf.Timestamp is not supported in Chromium's
  // third_party/cros_system_api, so both fields were changed to type int64 (the
  // same data type finch protos use for dates).
  reserved 1, 2, 3;
}

// Message containing all the chrome://flags overrides.
message OverridesSet {
  repeated FeatureOverride overrides = 1;
}

// Encapsulates information necessary for platform disaster recovery.
message Store {
  // Number of platform reboots since receiving a Chrome dbus call indicating
  // successful seed fetch.
  uint32 boot_attempts_since_last_seed_update = 1;
  // Data associated with the last known "safe" seed.
  SeedDetails last_good_seed = 2;
  // chrome://flags overrides, as a serialized OverridesSet.
  bytes overrides = 4;
  // HMAC of |overrides|.
  bytes overrides_hmac = 5;

  // The repeated FeatureOverride overrides was a member of this message
  // directly, but we need to wrap it in a message so we can separately
  // serialize and HMAC it.
  reserved 3;
}

// ComputedState is evaluate_seed's output, including both the evaluated state
// of each feature in the seed as well as the seed that was used to generate
// that state.
message ComputedState {
  // Computed state for each experiment in a seed.
  repeated FeatureOverride overrides = 1;
  // Which seed was used to generate the overrides?
  SeedDetails used_seed = 2;
}