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

[Discoverable]
protocol Manager {
    /// Immediately check for an update.
    ///  `options`:  Did a user initiate this request? (`USER_INITIATED`) This changes
    ///              some parameters about aggressiveness of retries and throttling.
    ///  `monitor`:  An interface on which to receive the status events for this update check.
    ///               It's only valid for a single update check, after that it won't receive any
    ///               more events.
    ///
    ///  -> Was the update check successfully started (state machine in a proper state
    ///     to do so).
    CheckNow(Options options, request<Monitor>? monitor)
        -> (CheckStartedResult result);

    /// Get the current state of the Manager (is an update available, is it currently
    /// checking for an update, etc).
    GetState() -> (State state);

    /// Get all status events, for all update checks (interactive and background).
    AddMonitor(request<Monitor> monitor);
};

/// Receiver of updates for either an individual update check, or to continuously
/// receive updates for all checks.
protocol Monitor {
    /// Receive the current state as it changes.
    -> OnState(State state);

    // TODO: support progress reporting.
};

/// Configuration options for an update attempt (this is common with the Fuchsia
///  OTA Interface v2)
table Options {
    /// What initiated this update attempt.
    1: Initiator initiator;
};

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

/// ```
/// The various states that the manager can be in.
///
///     +----------------------+
/// --->|         IDLE         |<--------------------------------+
/// |   +----------------------+                                 |
/// |              |               +----------------------+      |
/// |              |<--------------|   UPDATE_AVAILABLE   |      |
/// |              |               +----------------------+      |
/// |              v                       ^                     |
/// |   +----------------------+           |                     |
/// |<--| CHECKING_FOR_UPDATES |-----------------+               |
/// |   +----------------------+                 |               |
/// |              v                             |               |
/// |   +----------------------+                 |               |
/// |   |  PERFORMING_UPDATE   |---------------->|               |
/// |   +----------------------+                 |               |
/// |              v                             |               |
/// |   +----------------------+                 |               |
/// |   |  WAITING_FOR_REBOOT  |---------------->|               |
/// |   +----------------------+                 |               |
/// |              v                             v               |
/// |   +----------------------+     +----------------------+    |
/// +---|  FINALIZING_UPDATE   |---->|  ENCOUNTERED_ERROR   |----+
///     +----------------------+     +----------------------+
///
/// ```
enum ManagerState {
    /// The Manager is currently idle (in between updates).
    ///
    /// Next states:
    /// * `CHECKING_FOR_UPDATES`
    IDLE = 0;
    /// The Manager is currently checking for an update.
    ///
    /// Next states:
    /// * `IDLE` update is not available
    /// * `UPDATE_AVAILABLE` update is available but not allowed by policy
    /// * `PERFORMING_UPDATE` update is available and allowed by policy
    /// * `ENCOUNTERED_ERROR` on error
    CHECKING_FOR_UPDATES = 1;
    /// The Manager has found an available update but is not allowed to update
    /// due to policy.
    ///
    /// Next states:
    /// * `CHECKING_FOR_UPDATES` when CheckNow() is called or a background update starts
    UPDATE_AVAILABLE = 2;
    /// The Manager has started the available update.
    ///
    /// Next states:
    /// * `WAITING_FOR_REBOOT` on success
    /// * `ENCOUNTERED_ERROR` on error
    PERFORMING_UPDATE = 3;
    /// The update has been performed, and the device is waiting to be rebooted.
    ///
    /// Next states:
    /// * `FINALIZING_UPDATE` after device reboot
    /// * `ENCOUNTERED_ERROR` on error
    WAITING_FOR_REBOOT = 4;
    /// The update is being finalized after reboot.
    ///
    /// Next states:
    /// * `IDLE` on success
    /// * `ENCOUNTERED_ERROR` on error
    FINALIZING_UPDATE = 5;
    /// The Manager is reporting to Omaha that an error has occurred during the
    /// update.
    ///
    /// Next states:
    /// * `IDLE`
    ENCOUNTERED_ERROR = 6;
};

enum CheckStartedResult {
    /// The update check has been started.
    STARTED = 0;
    /// The update check was not started, as an update is already in progress, `monitor` is
    /// attached to that update and will immediately get a OnState() call on current state.
    IN_PROGRESS = 1;
    /// The update check was not started, because too many requests to check have
    /// been made in a short period of time.
    THROTTLED = 2;
};

table State {
    /// The current state of the Manager. Always present.
    1: ManagerState state;

    /// The version available from Omaha. Will be present in `UPDATE_AVAILABLE` or starting
    /// from `PERFORMING_UPDATE`.
    2: string version_available;
};