// Copyright 2020 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.developer.ffx;
using fuchsia.device;
using fuchsia.developer.remotecontrol as rc;

type StreamMode = strict enum : uint32 {
    SNAPSHOT_ALL = 1;
    SNAPSHOT_RECENT_THEN_SUBSCRIBE = 2;
    SNAPSHOT_ALL_THEN_SUBSCRIBE = 3;
    SUBSCRIBE = 4;
};

type DiagnosticsStreamError = strict enum : uint32 {
    // Indicates an error that doesn't fall into any of the below types.
    GENERIC_ERROR = 1;
    // Indicates a required parameter is missing
    MISSING_PARAMETER = 2;
    // Indicates the provided target specifier does not match any targets
    // or matches more than target.
    TARGET_MATCH_FAILED = 3;
    // Indicates the provided target specifier does not match any targets.
    // This is a more specific version of TARGET_MATCH_FAILED that is
    // used when possible.
    NO_MATCHING_TARGETS = 4;
    // Indicates that we have not successfully setup a logging stream
    // for the specified target.
    NO_STREAM_FOR_TARGET = 5;
    // Indicates there are no log streams for the provided target specifier,
    // either in the target cache or on disk.
    NO_MATCHING_OFFLINE_TARGETS = 6;
    // Indicates there are no log streams for the provided target specifier,
    // either in the target cache or on disk.
    NO_MATCHING_OFFLINE_SESSIONS = 7;
};

// Represents a time-bound in nanoseconds, which may be either a host timestamp or monotonic time.
type TimeBound = flexible union {
    1: absolute uint64;
    2: monotonic uint64;
};

type DaemonDiagnosticsStreamParameters = table {
    1: stream_mode StreamMode;
    // Sets the earliest time (in monotonic nanoseconds) of logs that will be returned.
    2: min_target_timestamp_nanos uint64;
    // The session the client intends to stream.
    3: session SessionSpec;
    // Sets the earliest time (in nanoseconds) of logs that will be returned.
    4: min_timestamp_nanos TimeBound;
};

// Specifies a particular log session
type SessionSpec = flexible union {
    // An absolute timestamp identifying the session.
    1: timestamp_nanos uint64;
    // A number specifying a session relative to the most-recent one, where
    // "0" means the most-recent session, "1" would be the second-most-recent, etc.
    2: relative uint32;
};

// Metadata about a particular log session
type LogSession = table {
    // Identifier for the logging target (nodename, in the case of a Fuchsia device).
    1: target_identifier string:fuchsia.device.DEVICE_NAME_MAX;
    // Timestamp identifier for the logging session. For Fuchsia targets, this is the
    // boot timestamp of the target.
    2: session_timestamp_nanos uint64;
};

@discoverable
protocol Diagnostics {
    /// Creates an iterator over diagnostics data. At present, this means cached log data.
    ///
    /// Note that there is some duplication in this API and the StreamDiagnostics API in RCS.
    /// This is because the surface for the service API needs to be slightly different:
    /// 1) It needs to accommodate specifying a target.
    /// 2) The error surface is accordingly slightly different.
    /// 3) The parameters surface is currently different (SNAPSHOT_RECENT_THEN_SUBSCRIBE has no
    ///    meaning in the diagnostics bridge) and have different evolution paths - for example, this
    ///    service may eventually support multi-target log streaming.
    ///
    /// If the target field is a nodename or log session identifier (e.g. "ffx_daemon"),
    /// then cached logs will be returned for that target even if the target is
    /// currently offline.
    ///
    /// One must keep the channel open to this protocol in order for the
    /// ArchiveIterator to function properly.
    StreamDiagnostics(resource struct {
        target string:<fuchsia.device.DEVICE_NAME_MAX, optional>;
        parameters DaemonDiagnosticsStreamParameters;
        iterator server_end:rc.ArchiveIterator;
    }) -> (struct {
        session LogSession;
    }) error DiagnosticsStreamError;
};