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

/// Monitors a single update installation attempt.
///
/// Clients interested in receiving progress information for an update attempt
/// should implement this protocol and provide the client end to
/// [`Installer.StartUpdate`] or [`Installer.MonitorUpdate`].
protocol Monitor {
    /// Receives a status update for this installation attempt.
    ///
    /// This request will be called for all state changes, skipping none.
    /// However, message delivery is throttled by the rate at which the
    /// implementation acknowledges the messages.
    ///
    /// The throttled delivery doesn't impact the underlying state of the
    /// [`Installer`].  It does not wait for any acknowledgements before it
    /// moves on to the next state in its state machine.  The [`Installer`] will
    /// simply queue up the states for the [`Monitor`] implementor to receive.
    ///
    /// During states with data that changes as the updage progress, the
    /// [`Installer`] may, at its discretion, collapse redundant information
    /// like the fraction completed, in the event that the [`Monitor`]
    /// implementation is not responding to the `OnState()` requests in a timely
    /// manner.
    ///
    /// + request `state` The new state of the update installation attempt.
    /// - response        The implementation is ready to receive the next
    ///                   [`State`] from the [`Installer`].
    OnState(State state) -> ();
};

/// The set of states that a [`Monitor`] can receive during an update
/// installation attempt.
///
/// An installation attempt ends when it enters a terminal state, denoted below
/// as the states on the right-hand side of the diagram with no arrows leading
/// out of them.
///
/// # State Machine Diagram
///
/// ```
///     +----------------+     +----------------+
///     |    prepare     |---->|  fail_prepare  |
///     +----------------+     +----------------+
///             |
///             v
///     +----------------+     +----------------+
///     |     fetch      |---->|   fail_fetch   |
///     +----------------+     +----------------+
///             |
///             v
///     +----------------+     +----------------+
///     |     stage      |---->|   fail_stage   |
///     +----------------+     +----------------+
///             |
///             |              +----------------+
///             +------------->|    complete    |
///             |              +----------------+
///             v
///     +----------------+     +----------------+
///     | wait_to_reboot |---->|  defer_reboot  |
///     +----------------+     +----------------+
///             |
///             |              +----------------+
///             +------------->|     reboot     |
///                            +----------------+
/// ```
union State {
    /// Fetching required metadata to begin the update and verifying system
    /// state.
    ///
    /// Next States:
    /// * `fetch` system is ready to install the update.
    /// * `fail_prepare` on error.
    1: PrepareData prepare;

    /// Fetching packages and kernel images.
    ///
    /// Next States:
    /// * `stage` required assets are ready to be staged for next boot.
    /// * `fail_fetch` on error.
    2: FetchData fetch;

    /// Writing kernel images and preparing to switch over to the new system.
    ///
    /// Next States:
    /// * `wait_to_reboot` if a reboot is necessary to complete the update.
    /// * `complete` if no reboot is necessary to complete the update.
    /// * `fail_stage` on error.
    3: StageData stage;

    /// The system is configured to boot the updated OS on next boot, and the
    /// installer is waiting for the trigger to reboot the system.
    ///
    /// Next States:
    /// * `reboot` when the installer decides it is time to initiate the reboot.
    /// * `defer_reboot` if the initiator specifically requests to not reboot.
    ///
    4: WaitToRebootData wait_to_reboot;

    /// The installer has initiated a system reboot into the updated OS.
    ///
    /// **This is a terminal state**
    ///
    5: RebootData reboot;

    /// The initiator specifically requested to skip the reboot, but a reboot is
    /// still required to complete the update.
    ///
    /// **This is a terminal state**
    ///
    6: DeferRebootData defer_reboot;

    /// The update is complete and no reboot was required.
    ///
    /// **This is a terminal state**
    ///
    7: CompleteData complete;

    /// An error occured while preparing the install.
    ///
    /// **This is a terminal state**
    ///
    8: FailPrepareData fail_prepare;

    /// An error occured while fetching the required artifacts.
    ///
    /// **This is a terminal state**
    ///
    9: FailFetchData fail_fetch;

    /// An error occured while staging the new OS.
    ///
    /// **This is a terminal state**
    ///
    10: FailStageData fail_stage;
};

/// Data associated with [`State.prepare`].
table PrepareData {
};

/// Data associated with [`State.fetch`].
table FetchData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.stage`].
table StageData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.wait_to_reboot`].
table WaitToRebootData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.reboot`].
table RebootData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.defer_reboot`].
table DeferRebootData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.complete`].
table CompleteData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Data associated with [`State.fail_prepare`].
table FailPrepareData {
    1: PrepareFailureReason reason;
};

/// Data associated with [`State.fail_fetch`].
table FailFetchData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
    3: FetchFailureReason reason;
};

/// Data associated with [`State.fail_stage`].
table FailStageData {
    1: UpdateInfo info;
    2: InstallationProgress progress;
};

/// Metadata for an update.  Once a field is populated during an installation
/// attempt, the value will not change.
table UpdateInfo {
    /// The total number of bytes that may be downloaded to apply this update.
    /// Optional, the installer may not be able to provide this value.
    1: uint64 download_size;
};

/// Current progress for an installation attempt.
table InstallationProgress {
    /// The fraction [0-1.0f] of the installation that has been completed.
    1: float32 fraction_completed;

    /// The number of bytes downloaded during this installation attempt. Less
    /// than or equal to [`UpdateInfo.download_size`] and only present if that
    /// field is also present.
    2: uint64 bytes_downloaded;
};

/// The set of values provided when an installation attempt fails on [`State.prepare`].
enum PrepareFailureReason {
    /// The prepare failed because of some other reason.
    INTERNAL = 0;

    /// The prepare failed because the system does not have enough space to fetch
    /// the update package.
    OUT_OF_SPACE = 1;
};

/// The set of values provided when an installation attempt fails on [`State.fetch`].
enum FetchFailureReason {
    /// The fetch failed because of some other reason.
    INTERNAL = 0;

    /// The fetch failed because the system does not have enough space to fetch a package.
    OUT_OF_SPACE = 1;
};