sdk/fidl/fuchsia.diagnostics/selector.fidl

// Copyright 2019 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.diagnostics;

//  The size bound of 100 is a reasonably low limit chosen based on observed
//  strings used as identifiers.
const uint16 MAXIMUM_STRING_SELECTOR_LENGTH = 100;

//  The size bound of 25 is a reasonably low limit chosen based on observed
//  component hierarchy depths, and awareness of maximum zircon message sizes.
const uint16 MAXIMUM_MONIKER_SEGMENTS = 25;

//  The size bound of 100 is a reasonably low limit chosen based on observed Inspect
//  hierarchy use cases.
const uint16 MAXIMUM_DATA_HIERARCHY_DEPTH = 100;

/// StringSelector is an xunion defining different ways to describe a pattern to match
/// strings against.
flexible union StringSelector {
    ///   This is a provided string that defines a pattern to
    ///   match against. The parser treats asterisks (*), colons (:) and backslashes
    ///   (\) as special characters.
    ///
    ///   If you wish to match against literal asterisks (*), they must be escaped.
    ///   If you wish to match against literal backslashes (\), they must be escaped.
    ///   If you wish to match against literal colons (:), they must be escaped.
    ///
    ///   eg: abc will match any string with the exact name "abc".
    ///   eg: a\* will match any string with the exact name "a*".
    ///   eg: a\\* will match any that starts with exactly "a\".
    ///   eg: a* will match any string that starts with "a".
    ///   eg: a*b will match any string that starts with a and ends with b.
    ///   eg: a*b*c will match any string that starts with a and ends with c, with `b`
    ///       in the middle.
    1: string:MAXIMUM_STRING_SELECTOR_LENGTH string_pattern;

    ///  This is a provided string that defines an exact string to match against. No
    ///  characters are treated as special, or carry special syntax.
    2: string:MAXIMUM_STRING_SELECTOR_LENGTH exact_match;
};

/// ComponentSelector encodes path to a component that is being selected for.
/// The `component_moniker` specifies a pattern of component relative monikers which
/// identify components being selected for.
table ComponentSelector {
    /// Vector encoding the a pattern for monikers of components being selected for.
    /// These monikers are child-monikers relative to a "root" hierarchy that the archivist
    /// is aware of.
    ///
    /// There must be at least one StringSelector provided, which
    /// specifies the component names that are matched by
    /// the current selector.
    /// TODO(4601): Investigate options for introduction of recursive wildcards.
    ///
    1: vector<StringSelector>:MAXIMUM_MONIKER_SEGMENTS moniker_segments;
};

/// TreeSelector represents a selection request on a nested structure where each
/// nested node has properties that can be retrieved. The node_path specifies which
/// nodes we search through, and the target_properties specify which properties to
/// look for on the matched nodes.
///
/// Given that a Tree Selector has two sections, <object node selector>:<property selector>,
/// in the absence of an optional property_selector, we return the subtree of all nodes specified
/// by the object node selector.
table TreeSelector {
    /// A vector of StringSelectors which serve as a pattern matcher
    ///   for paths through a hierarchy of named nodes.
    ///
    /// This field is required.
    ///
    1: vector<StringSelector>:MAXIMUM_DATA_HIERARCHY_DEPTH node_path;

    /// A StringSelector which serves as a pattern matcher for
    ///   string-named properties on a node in a data hierarchy.
    ///
    /// This field is optional. Without a property selector, the TreeSelector
    /// will select the entire subtree of all nodes selected by the node_path.
    2: StringSelector target_properties;
};

/// Structured selector containing all required information for pattern-matching onto
/// string-named properties owned by nodes in a data hierarchy, where data hierarchies belong
/// to specific components.
struct Selector {
    /// The selector defining a pattern of component monikers to match
    /// against.
    ComponentSelector component_selector;
    /// The selector defining data hierarchy properties to match against
    /// within the data hierarchies owned by components matched by
    /// `component_selector`.
    TreeSelector tree_selector;
};