// 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.

library fuchsia.update.installer;

using zx;

/// Updates the system.
///
/// This protocol is intended to be consumed by a component capable of
/// discovering when to update and what version of the system to install.
[Discoverable]
protocol Installer {
    /// Get the status of the last update attempt. If this device hasn't
    /// attempted an update since the last factory reset, every field in the
    /// result will be absent.
    ///
    /// - response `info` the status of the last update attempt, if available.
    GetLastUpdateResult() -> (UpdateResult info);

    /// Get the status of the given update attempt, if it exists. If this device
    /// hasn't attempted an update with the given `attempt_id` or forgotten about
    /// that attempt, every field in the result will be absent.
    ///
    /// + request `attempt_id` UUID identifying the requested update attempt.
    /// - response `info` the status of the last update attempt, if available.
    GetUpdateResult(string attempt_id) -> (UpdateResult info);

    /// Start an update if one is not running, or attach to a pending update
    /// attempt. Attach the provided monitor to the update attempt.
    ///
    /// + request `url` The fuchsia-pkg URL of the update package to update to.
    /// + request `options` Configuration options for this update attempt. Ignored or merged
    ///     with the existing `options` if an update attempt is already in progress.
    /// + request `monitor` A protocol on which to receive progress updates.
    /// + request `monitor_options` Configuration options to control the behavior of the
    ///     given [`Monitor`].
    ///
    /// - response `attempt_id` UUID identifying this update attempt. For
    ///     updates that require a reboot, components may use this identifier to
    ///     disambiguate the completion of this update attempt from new update
    ///     attempts that start post-reboot.
    StartUpdate(
        string url,
        Options options,
        request<Monitor> monitor,
        MonitorOptions monitor_options) -> (string attempt_id);

    /// Attempt to monitor a specific update attempt, if it exists. This API
    /// will not start an update if one is not already running.
    ///
    /// + request `attempt_id` UUID identifying the requested update attempt. If
    ///     not given, monitor any active update attempt.
    /// + request `monitor` A protocol on which to receive progress updates.
    /// + request `monitor_options` Configuration options to control the behavior of the
    ///     given [`Monitor`].
    ///
    /// - response `attached` Whether or not the provided monitor was attached
    ///     to an in-progress update attempt. If false, monitor will be closed
    ///     by the server.
    MonitorUpdate(
        string? attempt_id,
        request<Monitor> monitor,
        MonitorOptions monitor_options) -> (bool attached);

    /// Monitor all update attempts as they start, as well as an in-progress
    /// attempt, if there is one.
    ///
    /// + request `attempts_monitor` A protocol on which to receive [`Monitor`]
    ///     instances as update attempts start.
    /// + request `monitor_options` Configuration options to control the behavior of the
    ///     given [`Monitor`].
    MonitorAllUpdates(
        request<AttemptsMonitor> attempts_monitor,
        MonitorOptions monitor_options);
};

/// Metadata about a prior update attempt.
table UpdateResult {
    /// UUID for this specific update attempt. Always present.
    1: string attempt_id;

    // TODO stabilize the concept of what defines a system version. If it is a
    // single blob ID, of what package? Or should it be a fuchsia-pkg URL?
    /// Source version of this update attempt. Always present.
    2: string source_version;

    /// Target version of this update attempt, if known.
    3: string target_version;

    /// Configuration options for this update attempt. Always present.
    4: Options options;

    /// Terminal state of this update attempt. Always present.
    5: State state;

    /// When this update attempt started. Always present.
    6: zx.time when;
};

/// Configuration options for an update attempt.
table Options {
    /// What initiated this update attempt. Required.
    1: Initiator initiator;
};

/// Configuration options for the [`Monitor`] protocol.
table MonitorOptions {
    /// True if events should be sent over the [`Monitor`] protocol. Assumed to
    /// be false if absent.
    1: bool should_notify;
};

/// Who or what initiated the update check.
enum Initiator {
    /// The update check was initiated by an interactive user, or the user is
    /// otherwise blocked and waiting for the result of this update check.
    USER = 0;

    /// The update check was initiated by a service, in the background.
    SERVICE = 1;
};