src/proto/feature_flag.proto

syntax = "proto2";
option optimize_for = LITE_RUNTIME;

package otbr;

enum ProtoLogLevel
{
    PROTO_LOG_UNSPECIFIED = 0;  ///< Zero value enum is UNSPECIFIED
    PROTO_LOG_EMERG       = 1;  ///< System is unusable
    PROTO_LOG_ALERT       = 2;  ///< Action must be taken immediately
    PROTO_LOG_CRIT        = 3;  ///< Critical conditions
    PROTO_LOG_ERR         = 4;  ///< Error conditions
    PROTO_LOG_WARNING     = 5;  ///< Warning conditions
    PROTO_LOG_NOTICE      = 6;  ///< Normal but significant condition
    PROTO_LOG_INFO        = 7;  ///< Informational
    PROTO_LOG_DEBUG       = 8;  ///< Debug level messages
}

// Feature flag list message defines the list of feature flags to be used
// on OpenThread.
//
/////////////         Definition Policy Guide            /////////////
// * Every field is optional with a default value. The default value should
//   allow the feature to behave safe when the upper layer wants to rollback
//   or doesn't have the flag value (e.g., due to some network config download
//   error, API version mismatch, etc.). This makes sure that the system can
//   always rollback to safe status, even in the edge case.
// * When a feature finishes the rollup and becomes stable, the clear up process
//   should update the feature flag default value with the rolluped value.

/////////////  Feature Flag & API Evolving Policy Guide  /////////////
// * Add a new feature flag: add a new field in the proto.
// * Remove feature flag: mark the field as deprecated. Do NOT delete the field.
//   By default, the deprecated field should not impact OpenThread. If feature
//   owner wants to keep the deprecated flag backward compatible, he need to
//   clearly specify: what is the behavior if no/portion/all
//   deprecated_flag & its_new_flags exist.
// * Rename feature flag: if the feature’s semantics are not changed, it is
//   allowed to rename the field (the tag should not be changed). If the feature’s
//   semantics are changed, deprecate the field and add a new one.
// * Divide the flag into 2 flags: deprecate the old feature field, and add 2
//   new feature fields. If feature owner wants to keep the deprecated flag backward
//   compatible, he need to clearly specify: what is the behavior if no/portion/all
//   deprecated_flag & its_new_flags exist.
// * API Compatibility:
//   - If the OTBR API is older than the upper layer API, there are unrecognized
//     flags during proto parsing and they will be ignored.
//   - If the OTBR API is newer than the upper layer API, some new flags are
//     missing during the proto parsing, and these flags' default value will
//     be used as the feature flag value.
//   - If OTBR API is newer and deprecates a previously defined flag and upper
//     layer API is older (not aware of the deprecation) and uses the flag,
//     the flag takes no effect on OTBR as OTBR API deprecates it.
message FeatureFlagList {
  // Whether to enable the NAT64 feature.
  optional bool enable_nat64 = 1 [default = false];
  // Whether to enable detailed logging.
  optional bool enable_detailed_logging = 2 [default = false];
  // Set specific detailed logging level, default = PROTO_LOG_INFO
  optional ProtoLogLevel detailed_logging_level = 3 [default = PROTO_LOG_INFO];
  // Whether to enable the TREL feature.
  optional bool enable_trel = 4 [default = false];
  // Whether to enable upstream DNS forwarding.
  optional bool enable_dns_upstream_query = 5 [default = false];
  // Whether to enable prefix delegation.
  optional bool enable_dhcp6_pd = 6 [default = false];
  // Whether to enable link metrics manager.
  optional bool enable_link_metrics_manager = 7 [default = false];
  // Whether to enable the ePSKc feature.
  optional bool enable_ephemeralkey = 8 [default = false];
}