sdk/fidl/fuchsia.component.decl/config.fidl

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

library fuchsia.component.decl;

/// Config keys can only consist of these many bytes
const CONFIG_KEY_MAX_SIZE uint32 = 64;

/// The string identifier for a config field.
alias ConfigKey = string:CONFIG_KEY_MAX_SIZE;

/// The checksum produced for a configuration interface.
/// Two configuration interfaces are the same if their checksums are the same.
type ConfigChecksum = flexible union {
    /// A SHA-256 hash produced over a component's config interface.
    1: sha256 array<uint8, 32>;
};

/// The schema of a component's configuration interface.
type ConfigSchema = table {
    /// (Required) Ordered fields of the component's configuration interface.
    1: fields vector<ConfigField>:MAX;

    /// (Required) Checksum over the config declaration.
    2: checksum ConfigChecksum;

    /// (Required) Strategy used to resolve config values.
    3: value_source ConfigValueSource;
};

@available(added=HEAD)
type ConfigSourceCapabilities = table {};

/// Strategies available for resolving configuration values.
type ConfigValueSource = flexible union {
    /// (Required) The path within the component's package at which to find config value files.
    1: package_path string:MAX;
    /// If this is set, then all of the config values are found through CML files.
    @available(added=HEAD)
    2: capabilities ConfigSourceCapabilities;
};

/// Declares a single config field (key + type)
type ConfigField = table {
    /// (Required) The identifier for this config field.
    /// This key will be used to match overrides.
    1: key ConfigKey;

    /// (Required) The type of config values. Config values are verified
    /// against this layout at build time and run time.
    2: type ConfigType;

    /// Allowed sources for runtime overrides of this field's value.
    @available(added=12)
    3: mutability ConfigMutability;
};

// The type of a config value
type ConfigType = struct {
    layout ConfigTypeLayout;
    // This optional is not necessary, but without it,
    // FIDL compilation complains because of a possible include-cycle.
    // Bug: https://fxbug.dev/42145148
    parameters vector<LayoutParameter>:<MAX, optional>;
    constraints vector<LayoutConstraint>:MAX;
};

// Defines valid type ids for config fields.
type ConfigTypeLayout = flexible enum {
    BOOL = 1;
    UINT8 = 2;
    UINT16 = 3;
    UINT32 = 4;
    UINT64 = 5;
    INT8 = 6;
    INT16 = 7;
    INT32 = 8;
    INT64 = 9;
    STRING = 10;
    VECTOR = 11;
};

// Parameters of a given type layout
type LayoutParameter = flexible union {
    // For vectors, this is the type of the nested element.
    1: nested_type ConfigType;
};

// Constraints on a given type layout
type LayoutConstraint = flexible union {
    // For strings, this is the maximum number of bytes allowed.
    // For vectors, this is the maximum number of elements allowed.
    1: max_size uint32;
};

/// Allowed sources for runtime overrides of a config field's value.
@available(added=12)
type ConfigMutability = flexible bits {
    /// Allow parent components to provide overrides for the configuration field.
    PARENT = 1;
};

/// A configuration value which can be provided to a component.
///
/// Used both for storing configuration at-rest and in runtime configuration APIs.
@available(added=12)
type ConfigValue = flexible union {
    1: single ConfigSingleValue;
    2: vector ConfigVectorValue;
};

/// A single configuration value.
@available(added=12)
type ConfigSingleValue = flexible union {
    1: bool bool;
    2: uint8 uint8;
    3: uint16 uint16;
    4: uint32 uint32;
    5: uint64 uint64;
    6: int8 int8;
    7: int16 int16;
    8: int32 int32;
    9: int64 int64;
    10: string string:MAX;
};

/// A vector configuration value.
@available(added=12)
type ConfigVectorValue = flexible union {
    1: bool_vector vector<bool>:MAX;
    2: uint8_vector vector<uint8>:MAX;
    3: uint16_vector vector<uint16>:MAX;
    4: uint32_vector vector<uint32>:MAX;
    5: uint64_vector vector<uint64>:MAX;
    6: int8_vector vector<int8>:MAX;
    7: int16_vector vector<int16>:MAX;
    8: int32_vector vector<int32>:MAX;
    9: int64_vector vector<int64>:MAX;
    10: string_vector vector<string:MAX>:MAX;
};

/// Contents of the configuration value file. Defines the base values for a component's config.
@available(added=12)
type ConfigValuesData = table {
    /// The concrete values for the component's configuration.
    1: values vector<ConfigValueSpec>:MAX;
    /// A SHA-256 checksum of the configuration schema. Must match the checksum in the component
    /// manifest and config parser library used to resolve the final configuration.
    2: checksum ConfigChecksum;
};

/// An individual configuration value. It is matched against a specific configuration field based
/// on its offset within `ValuesData.values`.
@available(added=12)
type ConfigValueSpec = table {
    1: value ConfigValue;
};

/// A configuration that has been completely resolved by component manager.
@available(added=12)
type ResolvedConfig = struct {
    fields vector<ResolvedConfigField>:MAX;
    checksum ConfigChecksum;
};

@available(added=12)
type ResolvedConfigField = struct {
    key string:MAX;
    value ConfigValue;
};