// -*- Protocol-Buffers -*-
//==============================================================================
/// @file upgrade.proto
/// @brief Software Upgrade interface
/// @author Tor Slettnes <tslettnes@picarro.com>
//==============================================================================

syntax = "proto3";

package picarro.platform.upgrade;

import "vfs.proto";
import "version.proto";
import "signal.proto";
import "status.proto";
import "google/protobuf/empty.proto";

service Upgrade
{
    // Explicit scan for available upgrade packages in the specified location
    // if provided, otherwise in the preconfigured/default locations.
    //
    // To observe scan progress, use the `watch()` streaming call
    // to monitor the `scan_progress` signal, below.
    //
    // Once the scan completes a list of package packages discovered in this
    // location is returned.  Additionally, a `upgrade_available` signal may be
    // emitted if the "best available" package is changed as a result of this
    // scan (either because a new package is discovered or because a previous
    // "best candidate" from this scanned location is no longer available).
    //
    // This call is not required for ongoing upgrade availability notifications.
    // By default, removable devices (e.g. USB drives) are scanned on insertion,
    // and online checks are performed at regular intervals if an Internet
    // connection is available.
    rpc scan (PackageSource)
        returns (PackageCatalogue);

    // List available package sources (indexes), whether or not they contain
    // applicable packages.
    rpc list_sources (google.protobuf.Empty)
        returns (PackageSources);

    // Return information about available upgrade packages discovered during
    // a prior (implicit or explicit) scan of the specified package source
    // if specified, otherwise across all preconfigured/default sources.
    rpc list_available (PackageSource)
        returns (PackageCatalogue);

    // Return information about the best available upgrade package discovered
    // during a prior scan of the specified package source if specified,
    // otherwise the best overall candidate discovered across all
    // preconfigured/default locations. This will normally be the package with
    // the highest version number, with local (VFS) sources preferered over
    // remote (URL).
    //
    // This information is also available by watching the signal
    // `upgrade_available`, below.
    rpc best_available (PackageSource)
        returns (PackageInfo);

    // Install an upgrade from the specified package source if provided,
    // otherwise the current "best" package source based on prior scans.
    // To perform an explicit scan, invoke `scan()` before `install()`.
    //
    // This call returns immediately with information about the package being
    // installed. To monitor the upgrade progress and result use the `watch()`
    // method below.
    rpc install (InstallRequest)
        returns (PackageInfo);

    // Finalize a completed upgrade. This clears the `upgrade_progress`
    // signal, and if the upgrade requires a system reboot, do so now.
    rpc finalize (google.protobuf.Empty)
        returns (google.protobuf.Empty);

    // Listen for event updates from server.
    //
    // The input is a filter mask indicating which event types to monitor,
    // indicated by their respective field numbers in the `Signal` message,
    // below. By default, all events are streamed back.
    //
    // The output is a stream of `Signal` messages, each containing exactly
    // one event as described below.
    rpc watch (picarro.signal.Filter)
        returns (stream Signal);
}

message PackageSource
{
    // Source folder/location for packages.  Depending on context, this may be
    //
    //  - a VFS context/path or a referring to a local folder containing release
    //    packages, or a web URL referring to a JSON package index hat enumerates
    //    specific retrievable release packages (e.g. as input for `scan()` or
    //    as returned from `list_sources()`).
    //
    //  - a VFS context/path or a web URL pointing to a specific release package
    //    (e.g. as optional input for `install()`, as or included in packages
    //    returned from `list_available()`).

    oneof location
    {
        // Specific URL
        string url = 2;

        // Specific filesystem context/path, e.g. removable drive
        vfs.Path vfs_path = 3;
    }
}


message PackageSources
{
    repeated PackageSource sources = 1;
}

message InstallRequest
{
    // Optional package source. If not provided, the best available source
    // discovered from prior scans is used.
    PackageSource source = 1;

    // Force install even if the specified package source is not applicable
    // (e.g. because the product name does not match or the release version
    // is older than the currently installed release).
    bool force = 8;
}


message PackageInfo
{
    bool is_applicable = 1;
    PackageSource source = 2;
    string product_name = 4;
    picarro.version.Version release_version = 5;
    string release_description = 6;
    bool reboot_required = 8;
}

message PackageCatalogue
{
    repeated PackageInfo packages = 1;
}

message ScanProgress
{
    PackageSource source = 1;
}

message UpgradeProgress
{
    enum UpgradeState
    {
        STATE_NONE = 0;
        STATE_DOWNLOADING = 1;
        STATE_UNPACKING = 2;
        STATE_INSTALLING = 3;
        STATE_COMPLETED = 4;
        STATE_FAILED = 5;
        STATE_FINALIZED = 9;
    };

    message ProgressFraction
    {
        uint32 current = 1;
        uint32 total = 2;
    }

    UpgradeState state = 1;
    string task_description = 4;
    ProgressFraction task_progress = 5;
    ProgressFraction total_progress = 6;

    optional picarro.status.Error error = 15;
}


//==============================================================================
// Event signals, emitted whenever there's an status change related to
// software upgrade availability or progress.
//
// To listen for only specific event types, apply a corresponding signal filter
// as input parameter to the `watch()` call. The filter should contain a list of
// field indices to include or exclude, based on their field numbers within the
// `oneof` block below. The filter also contains a `polarity` field to indicate
// whether the listed fields are to be included (1) or excluded (0). As such, an
// empty filter means that all events will be streamed back to the client.

message Signal
{
    // All of the signals below are cached on the server side,
    // and replayed in response to subsequant `watch()` invocations
    // (cfr. "late subscriber pattern").

    // Mapping type, one of: MAP_ADDITION, MAP_UPDATE or MAP_REMOVAL.
    // Indicates whether the event is new/updated or no longer applicable.
    picarro.signal.MappingAction mapping_action = 1;

    oneof signal {

        // A package scan is in progress.  `mapping_action` is
        //  * `MAP_ADDITION' if the scan has just started
        //  * `MAP_UPDATE` for scan progress updates
        //  * `MAP_REMOVAL` if the scan has completed.
        //
        // This signal is cached and re-emitted in response to subsequent
        // `watch()` invocations from newly connected clients.
        ScanProgress scan_progress = 8;

        // Emitted on (applicable) software update availability changes.
        // `mapping_action` is
        //  * `MAP_ADDITION` if this is the first/only applicable source
        //  * `MAP_UPDATE` if the "best" available upgrade has changed
        //    (for instance, after a removable drive insertion/removal)
        //  * `MAP_REMOVAL` if the last applicable source was removed
        PackageInfo upgrade_available = 9;

        // Emitted with information about a pending software upgrade.
        // `mapping_action` is
        //  * `MAP_ADDITION` if the upgrade has started
        //  * `MAP_REMOVAL` if the upgrade has ended.
        PackageInfo upgrade_pending = 10;

        // Emitted continuously during a software upgrade.
        // `mapping_action` is
        //  * `MAP_ADDITION` if the upgrade has just stared
        //  * `MAP_UPDATE` whenver the progress is updated
        //  * `MAP_REMOVAL` once the upgrade has ended.
        UpgradeProgress upgrade_progress = 11;
    }
}