src/diagnostics/archivist/testing/fidl/puppet.test.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.archivist.test;

using fuchsia.diagnostics;

alias LogMessage = string:MAX;

/// Puppet is testing component that interacts with Archivist.
///
/// For full documentation see //src/diagnostics/testing/realm-factory/README.md.
@discoverable
open protocol Puppet {
    compose InspectPuppet;
    compose LogPuppet;

    /// Returns a LazyInspectPuppet client for recording lazy values.
    flexible RecordLazyValues(struct {
        key string:MAX;
    }) -> (resource struct {
        client client_end:LazyInspectPuppet;
    });

    // Causes the puppet to crash with an optional error message.
    //
    // The connection will be closed after this is called.
    flexible Crash(struct {
        message LogMessage;
    });
};

/// LoggerPuppet emits log messages when requested.
open protocol LogPuppet {
    /// Prints a message to stdout and appends a newline.
    flexible Println(struct {
        message LogMessage;
    });

    /// Prints a message stderr and appends a newline.
    flexible Eprintln(struct {
        message LogMessage;
    });

    // Emits a tracing event at the specified severity level.
    flexible Log(table {
        1: message LogMessage;
        2: severity fuchsia.diagnostics.Severity;
    }) -> ();

    // Blocks the caller until the next time an interest change event is observed.
    // Messages are lost if they are emitted using LogPuppet.Log before the
    // puppet has observed the the interest change.
    flexible WaitForInterestChange() -> (table {
        // The new log interest observed by this component.
        1: severity fuchsia.diagnostics.Severity;
    });
};

/// InspectPuppet emits inspect data when requested.
///
/// Values are always reported on the root inspect node.
open protocol InspectPuppet {
    /// Emits a health inspect node with OK status.
    flexible SetHealthOk() -> ();

    /// Records a string inspect property.
    flexible RecordString(struct {
        key string:MAX;
        value string:MAX;
    });

    /// Records an integer inspect property.
    flexible RecordInt(struct {
        key string:MAX;
        // Inspect properties don't distinguish between int8, int16, etc...
        // so we accept the maximum width for convenience.
        value int64;
    });

    /// Emits a collection of example of inspect data.
    ///
    /// TODO(https://fuchsia.dev/302716196): Split this into several methods
    /// tests can call to explicitly emit the same data as this method.
    flexible EmitExampleInspectData();
};

/// Records values on a lazy inspect node.
///
/// If this connection is dropped before [`CommitLazyValues`] is called, no
/// values are recorded.
///
/// Values are always reported on the root inspect node.
open protocol LazyInspectPuppet {
    compose InspectPuppet;

    /// Reports all recorded values on the root node.
    ///
    /// The server will close the connection after this method is called.
    flexible Commit(struct {
        options CommitOptions;
    });
};

type CommitOptions = table {
    /// Whether to hang when reporting values.
    1: hang bool;
};