// 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.inspect;
using fuchsia.mem;

/// Maximum length of an Inspect Tree, specified by the format.
const uint64 MAX_TREE_NAME_LENGTH = 2040;

/// Maximum number of children returned by a single read of the tree name iterator.
const uint64 MAX_TREE_NAME_LIST_SIZE = 64;

using TreeName = string:MAX_TREE_NAME_LENGTH;

/// The content of a specific Inspect Tree.
table TreeContent {
    /// Buffer containing the bytes of a tree in Inspect format.
    1: fuchsia.mem.Buffer buffer;
};

/// Iterator protocol for listing the names of children of a particular Tree.
protocol TreeNameIterator {
    /// Get the next batch of names.
    ///
    /// Returns an empty vector and closes the channel when no more names are present.
    /// Implementors may eagerly close the channel after sending the last batch.
    GetNext() -> (vector<TreeName>:MAX_TREE_NAME_LIST_SIZE name);
};

/// The Tree protocol represents a hierarchy of Inspect VMOs.
///
/// Link values stored in an Inspect file contain references to new
/// named files that contain a continuation of the data for the overall
/// hierarchy. Protocol Tree allows clients to request these named files so
/// long as the hosting component is still alive.
///
/// Connecting to a particular tree keeps the content for that Tree resident
/// in memory. Clients are recommended to traverse the trees in depth-first
/// order to reduce memory usage. Serving components are free to deny
/// connections to avoid unbounded memory usage.
[Discoverable]
protocol Tree {
    /// Get the content for the Inspect VMO backing this tree.
    ///
    /// So long as the Tree connection is still maintained, the contents
    /// of the tree are guaranteed to still be live. Once the connection is
    /// lost, the serving component is free to clear the contents of returned
    /// shared buffers.
    ///
    /// Serving components may return different buffers to GetContent
    /// requests for the same Tree.
    GetContent() -> (TreeContent content);

    /// Iterate over the names of Trees that are children of this Tree.
    ///
    /// The underlying list of children may change in between calls to
    /// ListChildNames and OpenChild.
    ListChildNames(request<TreeNameIterator> tree_iterator);

    /// Open a child Tree by name.
    ///
    /// If the child cannot be opened, the given request is closed.
    OpenChild(TreeName child_name, request<Tree> tree);
};