src/diagnostics/archivist/tests/integration/realm_factory/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;
using zx;

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 {
        /// The message carried by this log.
        /// Required.
        1: message LogMessage;
        /// The severity of this log.
        /// Required.
        2: severity fuchsia.diagnostics.Severity;
        /// Hardcode the time at which log is emitted.
        /// Optional, defaults to current time.
        3: time zx.Time;
    }) -> ();

    /// 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.
@discoverable
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;
};