// 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.
@available(added=7)
library fuchsia.inspect;
using fuchsia.mem;

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

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

alias TreeName = string:MAX_TREE_NAME_LENGTH;

/// The content of a specific Inspect Tree.
type TreeContent = resource table {
    /// Buffer containing the bytes of a tree in Inspect format.
    1: buffer fuchsia.mem.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() -> (struct {
        name vector<TreeName>:MAX_TREE_NAME_LIST_SIZE;
    });
};

/// 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() -> (resource struct {
        content TreeContent;
    });

    /// 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(resource struct {
        tree_iterator server_end:TreeNameIterator;
    });

    /// Open a child Tree by name.
    ///
    /// If the child cannot be opened, the given request is closed.
    OpenChild(resource struct {
        child_name TreeName;
        tree server_end:Tree;
    });
};