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 MAX_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 MAX_MONIKER_SEGMENTS = 25;

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

/// StringSelector is an union 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.
    ///
    ///   In addition, the "**" literal is treated as a special sequence that may match
    ///   multiple levels in a component selector only. See |ComponentSelector| for
    ///   details.
    1: string:MAX_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:MAX_STRING_SELECTOR_LENGTH exact_match;
};

/// Specifies a pattern of component relative monikers which
/// identify components being selected for.
///
/// Component selectors support wildcarding, which will glob a single "level" of a
/// component moniker. eg:
///    core/*/echo
/// will match all echo instances running only in realms directly under core, but none
/// nested further.
///
/// Component selectors also support a recursive wildcard, which will glob multiple
/// "levels" of a component moniker. eg:
///    core/**
/// will match all component instances running under core/ and all descendants of it.
/// Note that the wildcard does not select core itself. Clients that wish to choose a
/// subtree including the root should pass two selectors, eg:
///    core
///    core/**
/// The recursive wildcard is only allowed as the final segment of the selector.
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.
    1: vector<StringSelector>:MAX_MONIKER_SEGMENTS moniker_segments;
};

/// A selector defining a set of nodes to match, for which the entire subtree including
/// those nodes are selected.
struct SubtreeSelector {
    /// A vector of StringSelectors which serve as a pattern matcher
    ///   for paths through a hierarchy of named nodes. Each entry in the vector
    ///   is a selector for a single named node in a data hierarchy. The vector
    ///   of selectors for named nodes, then, defines a selector on paths through the
    ///   data hierarchy.
    ///
    /// Node paths support wildcarding, which will glob a single level of a
    /// node hierarchy. eg:
    ///    root/a/b/*/d
    /// will match all nodes named d which are below some child of node b.
    ///    root/a/b/c*
    /// will match all nodes below b which start with the character "c".
    vector<StringSelector>:MAX_DATA_HIERARCHY_DEPTH node_path;
};

/// A selector defining a set of nodes to match, and on those matched nodes a set of named
/// properties to match.
struct PropertySelector {
    /// A vector of StringSelectors which serve as a pattern matcher
    ///   for paths through a hierarchy of named nodes. Each entry in the vector
    ///   is a selector for a single named node in a data hierarchy. The vector
    ///   of selectors for named nodes, then, defines a selector on paths through the
    ///   data hierarchy.
    ///
    /// Node paths support wildcarding, which will glob a single level of a
    /// node hierarchy. eg:
    ///    root/a/b/*/d
    /// will match all nodes named d which are below some child of node b.
    ///    root/a/b/c*
    /// will match all nodes below b which start with the character "c".
    vector<StringSelector>:MAX_DATA_HIERARCHY_DEPTH node_path;

    /// A StringSelector which serves as a pattern matcher for
    ///   string-named properties on a node in a data hierarchy.
    ///
    /// target_properties supports wildcarding, which will match against all properties
    /// on any node matched by node_path.
    StringSelector target_properties;
};

/// TreeSelector represents a selection request on a hierarchy of named nodes, with
/// named properties on those nodes.
flexible union TreeSelector {
    /// A selector defining a set of nodes to match, for which the entire subtree including
    /// those nodes are selected.
    1: SubtreeSelector subtree_selector;

    /// A selector defining a set of nodes to match, and on those matched nodes a set of named
    /// propperties to match.
    2: PropertySelector property_selector;
};

/// 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.
///
/// These selectors are represented in text form as three segments, colon delimited,
/// specifying:
///         <component_moniker>:<node_selector>:<property_selector>
/// Examples:
///    Property selection:
///         realm1/realm2/echo.cmx:root/active_users:user_count
///
///    Subtree selection:
///         realm1/realm2/echo.cmx:root/active_users
table Selector {
    /// The selector defining a pattern of component monikers to match
    /// against.
    1: ComponentSelector component_selector;

    /// The selector defining data hierarchy properties to match against
    /// within the data hierarchies owned by components matched by
    /// `component_selector`.
    2: TreeSelector tree_selector;
};