// Copyright 2025 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.
@available(added=HEAD)
library fuchsia.power.internal;

using zx;

/// A scheduler of collaborative device reboots.
///
/// Collaborative reboot is a mechanism that allows multiple actors to work
/// together to schedule a device reboot at a time that avoids user disruption.
/// Actors fulfill one of two roles: Scheduler or Initiator. The scheduler
/// registers the desire to reboot the device at a later point in time, while
/// the initiator identifies appropriate times to perform a reboot and actuates
/// any scheduled requests. This protocol fulfills the scheduler role. For the
/// initiator role's protocol, see
/// [`fuchsia.power/CollaborativeRebootInitiator`].
///
/// Collaborative reboot can be used when the platform is configured to let the
/// product drive reboot scheduling.
///
/// As a concrete example, this mechanism can be used to drive software updates.
/// When the platform identifies that there is an outstanding software update to
/// apply, it can download the update, and schedule a collaborative reboot.
/// Later, when the product identifies that it is an appropriate time for the
/// device to reboot (say, after it's observed a sufficient period of user
/// inactivity), it can initate the collaborative reboot.
@discoverable
@available(added=HEAD)
closed protocol CollaborativeRebootScheduler {
    /// Schedules a collaborative reboot.
    ///
    /// Notifies the server of a new reason to perform collaborative reboot.
    /// This method may be called multiple times, by multiple actors for a
    /// single collaborative reboot.
    ///
    /// The server will not respond to the method until the request has been
    /// scheduled.
    ///
    /// Arguments:
    ///  - reason: The reason for requesting the collaborative reboot.
    ///  - cancel: An optional Zircon Eventpair. If provided, the caller may
    ///            cancel their request by signaling the event's peer. A
    ///            canceled request will not cause a future call to
    ///            [`CollaborativeRebootInitiator.PerformPendingReboot`]
    ///            to initiate a reboot.
    ///            Any `ZX_USER_SIGNAL_*` can be used to cancel the request.
    ///            If the server observes `ZX_OBJECT_PEER_CLOSED` (i.e. because
    ///            the client dropped the event pair), it will be interpretted
    ///            as a cancellation.
    strict ScheduleReboot(resource struct {
        reason CollaborativeRebootReason;
        cancel zx.Handle:<EVENTPAIR, zx.Rights.WAIT, optional>;
    }) -> ();
};

/// The reason why a collaborative reboot was scheduled.
// Note: This enum is strict while it is internal-only. If it's ever stabilized,
// convert it to a flexible enum.
@available(added=HEAD)
type CollaborativeRebootReason = strict enum {
    /// A new system update has been downloaded. A reboot is required to apply
    /// the update.
    SYSTEM_UPDATE = 1;
    /// The configured netstack version on the system has changed. A reboot is
    /// required to start the new Netstack.
    // TODO(https://fxbug.dev/42081574): Remove this reason once Netstack2 is
    // fully migrated to Netstack3.
    NETSTACK_MIGRATION = 2;
};