featured/README.md - third_party/platform2 - Git at Google

 # ChromeOS Feature Daemon

 `featured` is a service used for enabling and managing platform specific
 features. Its main user is Chrome field trials.

 ## Components

 In this directory are two main components: `feature_library` and featured.

 ### feature\_library

 The `feature_library` is the main way most users will interact with variations
 in platform2. (If you're familiar with
 [base::Feature and base::FeatureList](https://source.chromium.org/chromium/chromium/src/+/main:base/feature_list.h)
 in chrome, it will look very similar.)  Most documentation for this is in
 `feature_library.h`, but there is also a C wrapper API as well as a Rust API.

 As of March 2023, all features queried via `feature_library` must start with
 CrOSLateBoot. For CrOSLateBoot features, `feature_library` is a thin wrapper
 around a dbus call to ash-chrome, so state can only be queried **after** chrome
 is up.

 Work is underway to support "early boot" features as well; feel free to contact
 OWNERS for more details.

 #### Using feature\_library
 Clients can use `feature_library` by creating an instance of
 [PlatformFeatures](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/feature_library.h;l=169).
 The instance is used to query feature state and associated parameters, if there are any.

 `PlatformFeatures` is implemented as a singleton class and is thread-safe.
 Here is an example of how to initialize and obtain an instance:

 ```
 dbus::Bus::Options options;
 options.bus_type = dbus::Bus::SYSTEM;
 scoped_refptr<dbus::Bus> bus(new dbus::Bus(options));

 // |Initialize| must be called before calling |Get| and the return value must
 // be used since it has the [[nodiscard]] attribute.
 CHECK(feature::PlatformFeatures::Initialize(bus));

 // |Get| will return a valid handle if |Initialize| succeeds.
 // Note that |Get| and subsequent calls can happen much later than |Initialize|
 // since the object pointer remains valid until program exit.
 feature::PlatformFeatures* feature_lib = feature::PlatformFeatures::Get();

 // Use the handle to query feature state.
 feature_lib->GetParamsAndEnabled(...);
 ```

 Note that no shutdown call is necessary. The initialized instance will get
 automatically cleaned up on program exit.

 [platform2/featured/cpp_feature_check_example.cc](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/cpp_feature_check_example.cc)
 provides another example on how to use `PlatformFeatures` and associated
 functions like `IsEnabled{,Blocking}`, and `GetParamsAndEnabled{,Blocking}`.

 ### featured

 The feature daemon (featured) is primarily responsible for managing
 [share/platform-features.json](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/share/platform-features.json).
 This file configures platform and kernel features that can be enabled
 _dynamically_ at runtime, late in boot (that is, after user login).

 Each entry in this file consists of a feature name, to be checked using
 `feature_library`, an optional set of `support_check_commands` (to check whether
 the device supports the feature), and a set of `commands` to be run when the
 feature is supported and chrome determines that it should be enabled.

 Support check commands include FileExists and FileNotExists. Commands to execute
 include WriteFile and Mkdir, which respectively write specified contents to a
 file and create a given directory.

 Featured is heavily sandboxed: writing to a new location requires an update to
 selinux policy in `platform2/sepolicy/policy/chromeos/cros_featured.te` as well
 as the allow-list in service.cc (see `CheckPathPrefix`).

 We are actively working (in 2023) on support for "early boot" features in
 featured. The primary user interface for these will be via `feature_library`,
 but featured will perform some work to support this, largely behind the scenes.

 ### Upstart Configurations

 Featured starts relatively late in boot, during
 [system-services](https://www.chromium.org/chromium-os/chromiumos-design-docs/boot-design/#system-services-startup),
 since Chrome needs to be available for platform-features.json support to work.

 Additionally, featured waits for user login to enable platform-features.json
 features for two reasons:
 1. **Safety:** It is easier to roll back after user login since it is more
 likely for the platform to have connected to the network and downloaded a new
 seed.
 2. **Compatibility:** Historically, we have checked after login. There is no
 strong reason to change that, and changing it could break existing users.

 Upon crashes or abnormal exits (non-zero status code), featured restarts with
 the intention that if we fail initially, we want to re-try and make sure
 platform-features.json (and eventually "early boot" features) will work.

 We are actively working (in 2023) on support for "early boot" features in
 featured. To support "early boot" features, featured startup will be moved
 earlier to start during
 [basic services](https://www.chromium.org/chromium-os/chromiumos-design-docs/boot-design/#basic-services-startup).
	# ChromeOS Feature Daemon

	`featured` is a service used for enabling and managing platform specific
	features. Its main user is Chrome field trials.

	## Components

	In this directory are two main components: `feature_library` and featured.

	### feature\_library

	The `feature_library` is the main way most users will interact with variations
	in platform2. (If you're familiar with
	[base::Feature and base::FeatureList](https://source.chromium.org/chromium/chromium/src/+/main:base/feature_list.h)
	in chrome, it will look very similar.) Most documentation for this is in
	`feature_library.h`, but there is also a C wrapper API as well as a Rust API.

	As of March 2023, all features queried via `feature_library` must start with
	CrOSLateBoot. For CrOSLateBoot features, `feature_library` is a thin wrapper
	around a dbus call to ash-chrome, so state can only be queried after chrome
	is up.

	Work is underway to support "early boot" features as well; feel free to contact
	OWNERS for more details.

	#### Using feature\_library
	Clients can use `feature_library` by creating an instance of
	[PlatformFeatures](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/feature_library.h;l=169).
	The instance is used to query feature state and associated parameters, if there are any.

	`PlatformFeatures` is implemented as a singleton class and is thread-safe.
	Here is an example of how to initialize and obtain an instance:

	```
	dbus::Bus::Options options;
	options.bus_type = dbus::Bus::SYSTEM;
	scoped_refptr<dbus::Bus> bus(new dbus::Bus(options));

	// \|Initialize\| must be called before calling \|Get\| and the return value must
	// be used since it has the [[nodiscard]] attribute.
	CHECK(feature::PlatformFeatures::Initialize(bus));

	// \|Get\| will return a valid handle if \|Initialize\| succeeds.
	// Note that \|Get\| and subsequent calls can happen much later than \|Initialize\|
	// since the object pointer remains valid until program exit.
	feature::PlatformFeatures* feature_lib = feature::PlatformFeatures::Get();

	// Use the handle to query feature state.
	feature_lib->GetParamsAndEnabled(...);
	```

	Note that no shutdown call is necessary. The initialized instance will get
	automatically cleaned up on program exit.

	[platform2/featured/cpp_feature_check_example.cc](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/cpp_feature_check_example.cc)
	provides another example on how to use `PlatformFeatures` and associated
	functions like `IsEnabled{,Blocking}`, and `GetParamsAndEnabled{,Blocking}`.

	### featured

	The feature daemon (featured) is primarily responsible for managing
	[share/platform-features.json](https://source.chromium.org/chromiumos/chromiumos/codesearch/+/main:src/platform2/featured/share/platform-features.json).
	This file configures platform and kernel features that can be enabled
	_dynamically_ at runtime, late in boot (that is, after user login).

	Each entry in this file consists of a feature name, to be checked using
	`feature_library`, an optional set of `support_check_commands` (to check whether
	the device supports the feature), and a set of `commands` to be run when the
	feature is supported and chrome determines that it should be enabled.

	Support check commands include FileExists and FileNotExists. Commands to execute
	include WriteFile and Mkdir, which respectively write specified contents to a
	file and create a given directory.

	Featured is heavily sandboxed: writing to a new location requires an update to
	selinux policy in `platform2/sepolicy/policy/chromeos/cros_featured.te` as well
	as the allow-list in service.cc (see `CheckPathPrefix`).

	We are actively working (in 2023) on support for "early boot" features in
	featured. The primary user interface for these will be via `feature_library`,
	but featured will perform some work to support this, largely behind the scenes.

	### Upstart Configurations

	Featured starts relatively late in boot, during
	[system-services](https://www.chromium.org/chromium-os/chromiumos-design-docs/boot-design/#system-services-startup),
	since Chrome needs to be available for platform-features.json support to work.

	Additionally, featured waits for user login to enable platform-features.json
	features for two reasons:
	1. Safety: It is easier to roll back after user login since it is more
	likely for the platform to have connected to the network and downloaded a new
	seed.
	2. Compatibility: Historically, we have checked after login. There is no
	strong reason to change that, and changing it could break existing users.

	Upon crashes or abnormal exits (non-zero status code), featured restarts with
	the intention that if we fail initially, we want to re-try and make sure
	platform-features.json (and eventually "early boot" features) will work.

	We are actively working (in 2023) on support for "early boot" features in
	featured. To support "early boot" features, featured startup will be moved
	earlier to start during
	[basic services](https://www.chromium.org/chromium-os/chromiumos-design-docs/boot-design/#basic-services-startup).