// 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 fuchsia.pkg;

alias AttemptId = string:36; // 36 == strlen("01234567-89ab-cdef-0123-456789abcdef")

/// 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(AttemptId attempt_id) -> (UpdateResult info);

    /// Start an update if one is not running, or attach to a pending update
    /// attempt if one is running and
    /// [`Options.allow_attach_to_existing_attempt`] is true. If an update
    /// attempt is started or attached to, provide status updates through
    /// `monitor`.
    ///
    /// + 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 `reboot_controller` An optional protocol to control the timing
    ///     of the reboot into the update system. If not provided, the update
    ///     attempt will initiate the reboot as soon as it is ready.
    ///
    /// - 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(
        fuchsia.pkg.PackageUrl url,
        Options options,
        Monitor monitor,
        request<RebootController>? reboot_controller
        ) -> (AttemptId attempt_id) error UpdateNotStartedReason;

    /// Attempt to monitor a specific update attempt, if it exists. This request
    /// 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.
    ///
    /// - 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(
        AttemptId? attempt_id,
        Monitor monitor
        ) -> (bool attached);
};

/// Controls the timing of the reboot into the updated system.
///
/// If the client end of a [`RebootController`] is closed without calling
/// [`RebootController.Detach()`], the update attempt will fall back to the
/// default behavior of rebooting as soon as it is ready.
protocol RebootController {
    /// Informs the update attempt that it may reboot when ready, unblocking a
    /// pending reboot if it is already ready to reboot.
    ///
    /// If a controller is dropped without sending this request or
    /// [`RebootController.Detach`], the update attempt reclaims control of the
    /// timing of the reboot, behaving as if the update attempt was not given a
    /// [`RebootController`] at all.
    Unblock();

    /// Informs the update attempt that it should wait to reboot indefinitely,
    /// even if this [`RebootController`] connection is dropped.
    Detach();
};

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

    /// fuchsia-pkg:// url for the update package associated with this update
    /// attempt. Always present.
    2: fuchsia.pkg.PackageUrl url;

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

    /// Terminal state of this update attempt. Always present if the update
    /// failed. None if the update succeeded.
    4: State state;
};

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

    /// If an update is already in progress, it's acceptable to instead attach a
    /// Monitor to that in-progress update instead of failing this request to
    /// install the update.  Setting this option to true may convert situations
    /// that would have resulted in the ALREADY_IN_PROGRESS to be treated as
    /// non-error cases. A controller, if provided, will be ignored if the
    /// running update attempt already has a controller.
    2: bool allow_attach_to_existing_attempt;

    /// Determines if the installer should update the recovery partition if an
    /// update is available.  Defaults to true.
    3: bool should_write_recovery;
};

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

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

/// The set of values that are returned by an request to start an update.
enum UpdateNotStartedReason {
    /// There was already another update attempt in progress when this request was
    /// made.  A new update attempt will not be started.
    ALREADY_IN_PROGRESS = 1;
};