docs/development/settings/policy_concepts.md

# Policy concepts

## What is a policy?

The Fuchsia Settings API protocols are fairly static and their behavior cannot
be customized. A few interfaces have parameters that can be configured at
build-time for a particular product, but none can be adjusted dynamically.

Fuchsia Settings provides this feature through the concept of a policy. A policy
modifies the behavior of Fuchsia Settings at runtime. Since the adjustments
happen at runtime, policies are modified through FIDL APIs.

The policy API is readable and writable by any client with the appropriate
policy permissions. The ability to control the policies is a separate permission
since a policy API client can affect the behavior for all Fuchsia Settings API
clients, for example by setting a minimum and maximum brightness value to the
same value.

## Anatomy of a policy API

Policies are defined in terms of **transforms**, which modify the requests sent
to the Fuchsia Settings API. An example of a transform would be a minimum
brightness limit.

Brightness is a simple setting and there’s only one brightness value to be
controlled, but suppose a device had multiple displays, each with their own
brightness value. In that case, a client of the policy API would need to specify
which display that their minimum brightness limit applies to. The policy API
calls this identifier a **target**, specifying an aspect of a setting.

## Policy API example {#policy-example-table}

```fidl
library fuchsia.settings.policy;

alias PolicyId = uint32;

@discoverable
protocol VolumePolicyController {
    GetProperties() -> (struct {
        properties vector<Property>:MAX;
    });

    AddPolicy(struct {
        target Target;
        parameters PolicyParameters;
    }) -> (struct {
        policy_id PolicyId;
    }) error Error;

    RemovePolicy(struct {
        policy_id PolicyId;
    }) -> () error Error;
};

type Property = table {
    1: target Target;
    2: available_transforms vector<Transform>:MAX;
    3: active_policies vector<Policy>:MAX;
};

type Target = strict union {
    1: stream fuchsia.media.AudioRenderUsage;
};

type Transform = strict enum : uint8 {
    MAX = 1;
    MIN = 2;
};

type Policy = table {
    1: policy_id PolicyId;
    2: parameters PolicyParameters;
};

type PolicyParameters = strict union {
    1: min Volume;
    2: max Volume;
};

type Volume = table {
    1: volume float32;
};
```

Note: For the full FIDL definition, see [volume_policy.fidl][volume_policy_fidl].

The policy API looks similar to the Fuchsia Settings API but there are some
notable differences.

### Add and remove instead of Set

Instead of a single Set method, the policy API offers the pair of `AddPolicy`
and `RemovePolicy`. The Fuchsia Settings API only offers a `Set`, since settings
values are always expected to exist. For example, there is always a default
brightness level even if no client ever set it. A client would never need to
“remove” the brightness level, only modify it. In contrast, a policy transform
is an action to be taken on an input to the Fuchsia Settings API, so there can
be any number of policies active for a particular target, including none.

### Get instead of Watch

The Fuchsia Settings API return values through Watch methods that implement the
[hanging get pattern][hanging-get]. Policy only offers a simple `GetProperties`
method to provide information about policy targets, including possible
transforms and active policies. Policy API clients are not expected to respond
to changing policies so a hanging get isn't necessary. Clients should only need
to know the active policies before attempting to add or remove a policy.

Each policy has a unique identifier that is generated when added, that can be
used to remove it later. To add a policy, clients need to provide the target the
policy is aimed at, as well as their parameters for the policy.

### Different namespace

The policy API lives in the `fuchsia.settings.policy` namespace instead of the
`fuchsia.settings` namespace that the Fuchsia Settings API lives under. Using a
different namespace requires a different permission for clients so that being
able to use the Fuchsia Settings API doesn't automatically grant permission to
use the policy API.

In the [policy interface for volume example](#policy-example-table), any client
can apply a maximum volume limit to any target. This allows multiple policies to
apply to the same target, either from the same client or from multiple clients.
All policies added are considered valid unless there’s a logical error (such as
a minimum limit that’s higher than the maximum limit).

The policy API will attempt to respect all active policies and apply the
intersection of policies. In this case, the strictest maximum volume limit will
be the lowest maximum volume among the active policies. In the event that the
current lowest maximum volume limit is removed, the next lowest policy will take
effect.

## Policy concept definitions

The following is a recap of policy API concepts:

* Target: Unique identifier for a controllable aspect of a setting.

  For example, the targets in the volume policy are the individual audio streams

* Transform: An operation on the values for a setting target.

  Policy clients can specify customizable parameters for transforms, ex. max
  volume limit

* Policy: A client-specified transform, along with its parameters.

  Policies each have a globally unique ID to identify them

* Property: A collection of information about a policy target.

  A property contains information about what transforms are possible on a given
  target, and what policies are active

<!-- link labels -->
[volume_policy_fidl]: /sdk/fidl/fuchsia.settings.policy/volume_policy.fidl
[hanging-get]: /docs/development/api/fidl.md#hanging-get