// Copyright 2021 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.virtualization;

using zx;

/// The status of the Linux container.
type ContainerStatus = strict enum {
    TRANSIENT = 1;
    LAUNCHING_GUEST = 2;
    STARTING_VM = 3;
    DOWNLOADING = 4;
    EXTRACTING = 5;
    STARTING = 6;
    READY = 7;
    FAILED = 8;
};

/// Linux guest information.
type LinuxGuestInfo = table {
    /// Linux guest CID.
    1: cid uint32;

    /// The current container status.
    2: container_status ContainerStatus;

    /// Container download in percentage. Download percent is only
    /// available if container status is DOWNLOADING.
    3: download_percent int32;

    /// The reason for failure if the container could not be created,
    /// set if container status is FAILED.
    4: failure_reason string:MAX;
};

/// A `LinuxManager` provides access to the status of Linux guest instances.
@discoverable
closed protocol LinuxManager {
    /// Get Linux guest environment info.
    ///
    /// Returns ZX_ERR_UNAVAILABLE if the Linux guest is not available.
    strict StartAndGetLinuxGuestInfo(struct {
        label string:MAX;
    }) -> (struct {
        info LinuxGuestInfo;
    }) error zx.Status;

    /// Linux guest info event.
    ///
    /// Sent to the client when the status of the container changed.
    strict -> OnGuestInfoChanged(struct {
        label string:MAX;
        info LinuxGuestInfo;
    });

    /// Clears the stateful data. This includes any installed containers and any user data
    /// they may contain.
    ///
    /// Returns ZX_ERR_BAD_STATE if this is called while the VM is running.
    /// Returns ZX_ERR_IO if there was an IO failure while performing the
    /// operation.
    strict WipeData() -> () error zx.Status;

    /// Attempts to gracefully shut down a running guest. The caller must ensure that the guest
    /// has actually stopped (such as by waiting on a Guest client PEER_CLOSED signal and checking
    /// the epitaph) before attempting to launch another guest.
    ///
    /// On a clean shutdown the Guest client will contain a ZX_OK epitaph, and on an unexpected
    /// shutdown the client will contain a ZX_ERR_INTERNAL epitaph (or no epitaph if there was
    /// a component crash).
    strict GracefulShutdown();
};