sdk/fidl/fuchsia.inspect/inspect_sink.fidl

// Copyright 2023 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 zx;

@available(added=HEAD)
type EscrowToken = resource struct {
    token zx.Handle:<EVENTPAIR, zx.Rights.TRANSFER | zx.Rights.WAIT | zx.Rights.INSPECT>;
};

@available(added=HEAD)
alias EscrowedVmo
        = zx.Handle:<VMO, zx.RIGHTS_BASIC | zx.RIGHTS_PROPERTY | zx.Rights.READ | zx.Rights.MAP>;

@available(added=16)
const MAX_NAME_LENGTH uint64 = 4096;

@available(added=22)
const DEFAULT_TREE_NAME string = "root";

@discoverable(server="platform")
@available(added=16)
closed(removed=21) open(added=21) protocol InspectSink {
    /// Publishes a handle to the `fuchsia.inspect.Tree` protocol that the
    /// server can use to read Inspect data, including lazy nodes.
    strict(removed=21) flexible(added=21) Publish(resource table {
        /// The Tree that the server will use to fetch Inspect data.
        ///
        /// The connection will be closed if this isn't provided.
        ///
        /// Required
        1: tree client_end:Tree;

        /// A name to identify this tree from the client perspective. This name
        /// isn't required to be unique across multiple trees. Multiple trees
        /// published under the same name are accepted and will not overwrite
        /// previously published trees.
        ///
        /// Optional
        2: name string:MAX_NAME_LENGTH;
    });

    /// Instructs the server to store the VMO provided to make its data
    /// available to Inspect readers, even when the component that published
    /// this VMO isn't running.
    ///
    /// This is meant to be used when integrating with Component Framework's
    /// Escrow APIs to enable stopping when IDLE but still ensure that some
    /// useful diagnostics information is available.
    ///
    /// The client must provide a `token` that will be used as a unique
    /// identifier to this VMO by the the server. This token is an event pair, a
    /// client must provide one end of this event pair and hold to the other end
    /// (or escrow the handle it using Component APIs). If the server sees a
    /// PEER_CLOSED on the handle it received, it will drop the VMO associated
    /// with this token.
    ///
    /// If any of the required arguments isn't passed the connection will be
    /// closed.
    ///
    /// To learn more about stopping IDLE components, please refer to:
    /// https://fuchsia.dev/fuchsia-src/development/components/stop_idle
    @available(added=HEAD)
    flexible Escrow(resource table {
        /// The VMO containing Inspect data that the server will store.
        /// Required
        1: vmo EscrowedVmo;

        /// The token identifying this VMO and also serving as a controller to
        /// stop storing this VMO in the server.
        /// Required
        2: token EscrowToken;

        /// An optional name to identify this VMO, that can be human readable.
        ///
        /// Optional
        3: name string:MAX_NAME_LENGTH;

        /// An optional reference to the Tree that was previously provided to
        /// the server using `Publish`. The server will drop the handle
        /// associated with that tree connection, triggering a peer closed on
        /// the tree server. This enables the client to ensure the following:
        ///
        /// - Tree data and escrowed data won't be present twice in snapshots.
        /// - The caller can know when to stop serving the tree, preventing data
        ///   missing from snapshots.
        ///
        /// If `name` isn't provided, the `name` of this Inspect will be the one
        /// associated with this tree.
        ///
        /// If the server isn't tracking any handle associated with the source
        /// component with this koid, this will be ignored and treated as if
        /// nothing had been provided.
        ///
        /// Optional
        4: tree zx.Koid;
    });

    /// Instructs the server to return (and stop tracking) the VMO associated
    /// with the given token.
    ///
    /// This is meant to be used when a component restarts and wants to fetch
    /// Inspect data that it escrowed.
    ///
    /// To learn more about stopping IDLE components, please refer to:
    /// https://fuchsia.dev/fuchsia-src/development/components/stop_idle
    @available(added=HEAD)
    flexible FetchEscrow(resource table {
        /// The token associated with the VMO taht we want to fetch. If this
        /// token isn't associated with any VMO the response will be empty.
        ///
        /// Required
        1: token EscrowToken;

        /// A handle that the server can use to continue reading data associated
        /// with this VMO. The previous name that the component had given to
        /// this VMO will be maintained. This would be equivalent to calling
        /// `Publish` with the return VMO, except that it removes the race that
        /// can happen if Inspect data is read, between the time that the
        /// component fetches the VMO and publishes a tree for it.
        ///
        /// Optional
        2: tree client_end:Tree;
    }) -> (resource table {
        1: vmo EscrowedVmo;
    });
};