blob: 882377d83a2936d75d88534e8b356c004e7d0a71 [file] [log] [blame]
// 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.
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:
/// hub/*/echo.cmx
/// will match all echo.cmx instances running only in realms directly under hub, but none
/// nested further.
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
/// propperties 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;
};