// -*- Protocol-Buffers -*-
//==============================================================================
/// @file sysconfig.proto
/// @brief Host configuration interface
/// @author Tor Slettnes <tslettnes@picarro.com>
//==============================================================================

syntax = "proto3";

package picarro.platform.sysconfig;

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";
import "version.proto";
import "signal.proto";

service SysConfig
{
    //==========================================================================
    // Product information

    rpc get_product_info (google.protobuf.Empty) returns (ProductInfo);
    rpc set_serial_number (google.protobuf.StringValue) returns (google.protobuf.Empty);
    rpc set_model_name (google.protobuf.StringValue) returns (google.protobuf.Empty);

    //==========================================================================
    // Host Information

    rpc get_host_info (google.protobuf.Empty) returns (HostInfo);
    rpc set_host_name (google.protobuf.StringValue) returns (google.protobuf.Empty);

    //==========================================================================
    // Time configuration

    // Current timestamp
    rpc set_current_time (google.protobuf.Timestamp) returns (google.protobuf.Empty);
    rpc get_current_time (google.protobuf.Empty) returns (google.protobuf.Timestamp);

    // Get or set time configuration
    rpc set_time_config (TimeConfig) returns (google.protobuf.Empty);
    rpc get_time_config (google.protobuf.Empty) returns (TimeConfig);

    //==========================================================================
    // Time zone configuration

    // List time zone _areas_, which are continents or oceans. Results are
    // sorted roughly with a west to east then north to south bias.
    rpc list_timezone_areas (google.protobuf.Empty) returns (TimeZoneAreas);

    // List countries, optionally within a specific area.
    // Results are sorted alphabetically, except that within "Americas"
    // the North American countries (US, Canada, Mexico) appear first
    // in that order (coincidentally, by their westernmost points).
    rpc list_timezone_countries (TimeZoneArea) returns (TimeZoneCountries);

    // List regions within a specified country, optionally also limited by area.
    // Results are sorted alphabetically, except that within the US the four
    // major timezone regions (Eastern, Central, Mountain, Pacific) appear in
    // that order.
    //
    // If there are no subregions within the specified country, return an empty
    // response.
    rpc list_timezone_regions (TimeZoneLocationFilter) returns (TimeZoneRegions);

    // Obtain canonical time zone specifications, optionally restricted by a
    // specific area and/or country.
    rpc list_timezone_specs (TimeZoneLocationFilter) returns (TimeZoneCanonicalSpecs);

    /// Return geographic information about a specific canonical timezone. If no
    /// zone name is specified, return info about the currently configured zone.
    rpc get_timezone_spec (TimeZoneCanonicalName) returns (TimeZoneCanonicalSpec);

    /// Get offset information about the specified time zone at the specified
    /// time, or the currently configured zone and/or system time if not
    /// specified. Information includes current and
    /// standard time offsets from UTC, and whether Daylight Savings Time (or
    /// Summer Time) is currently in effect.
    rpc get_timezone_info (TimeZoneInfoRequest) returns (TimeZoneInfo);

    /// Configure the system time zone. Return the resulting applied zone
    /// information.
    rpc set_timezone (TimeZoneConfig) returns (TimeZoneInfo);

    //==========================================================================
    // Spawn a new process, with or without capturing stdin/stdout/stderr.

    rpc invoke_sync (CommandInvocation) returns (CommandResponse);
    rpc invoke_async (CommandInvocation) returns (CommandInvocationResponse);
    rpc invoke_finish (CommandContinuation) returns (CommandResponse);
    // rpc invoke_piped (stream CommandInvocation) returns (stream CommandResponse);

    rpc reboot (google.protobuf.Empty) returns (google.protobuf.Empty);

    //==========================================================================
    // Watch for changes from server

    rpc watch (picarro.signal.Filter) returns (stream Signal);
}

//==============================================================================
// Product Information

message ProductInfo
{
    string product_name = 1;
    string product_description = 2;

    string product_serial = 4;
    string hardware_model = 5;

    picarro.version.Version release_version = 8;
    picarro.version.ComponentVersions component_versions = 9;
    SubsystemInfo subsystem_info = 15;
}

message SubsystemInfo
{
    repeated ProductInfo subsystems  = 1;
}


//==============================================================================
// Host Information

message HostInfo
{
    string hostname = 1;

    string os_name = 16;
    string os_version = 17;
    string os_release_flavor_short = 20;
    string os_release_flavor_long = 21;
    string os_release_version_id = 22;
    string os_release_version_name = 23;

    string machine_arch = 24;
    string machine_cpu = 25;
    string machine_name = 26;
    string machine_description = 27;
    string machine_serial = 28;
    string machine_uid = 29;
}

//==============================================================================
// Time Configuration

enum TimeSync
{
    // Synchronized to TimeSync enumeration in
    // '../cpp/services/sysconfig/base/sysconfig-time.h++'.
    TSYNC_NONE = 0;             // No settings change
    TSYNC_NTP = 1;              // Synchronization via NTP
}

message TimeConfig
{
    // Synchronization scheme (e.g. NTP)
    TimeSync synchronization = 1;

    // Server(s) with which to synchronize (e.g. "pool.ntp.org").
    // When settting, only include this to change current service(s).
    repeated string servers = 2;
}


//==============================================================================
// Time Zone Configuration

message TimeZoneAreas
{
    repeated string areas = 1;
}

message TimeZoneArea
{
    // Time zone area name. This corresponds to the first component of the
    // available canonical names, transcribed slightly for more descriptive
    // English names:
    //   - America/*  -> "Americas"
    //   - Atlantic/* -> "Atlantic Ocean"
    //   - Europe/* -> "Europe"
    //   - Africa/* -> "Africa"
    //   - Asia/* -> "Asia"
    //   - Indian/* -> "Indian Ocean"
    //   - Australia/* -> "Australia"
    //   - Pacific/* -> "Pacific Ocean"
    //   - Antarctica/* -> "Antarctica"

    string name = 1;
}

message TimeZoneCountries
{
    repeated TimeZoneCountry countries = 1;
}

message TimeZoneCountry
{
    string code = 1;            // ISO 3166 country code, e.g., "US, "DE", ...
    string name = 2;            // English name, e.g. "United States, "Germany", ...
}

message TimeZoneRegions
{
    repeated string regions = 1;
}

message TimeZoneLocation
{
    // Country code and/or name, and possibly a region within.
    //
    // For example, if included in `TimeZoneConfig()` when invoking `set_timezone()`:
    //  * `country.code = NO` is sufficient, and equivalent to `canonical_zone = Europe/Berlin`
    //  * `country.code = US` is insufficient, and requires a named region (e.g. `Pacific`).
    //
    // As included in `TimeZoneCanonicalSpec`, this message is guaranteed to
    // include a country specified by both `code` and `name`.  It includes a
    // `region` if *and only if* that country has more than one time zone.

    // Country, specified either by its 2-letter code (e.g. "DE") or its name in
    // English (e.g. "Germany").
    TimeZoneCountry country = 1;

    // Region within country. Present only for countries with more than one timezone.
    string region = 2;
}

message TimeZoneLocationFilter
{
    // Optional area (continent or ocean). This can be either the first
    // component of the canonical name (e.g. "America") or its transcribed name
    // (e.g. "Americas") - see the `TimeZoneArea` message above.
    TimeZoneArea area = 1;

    // Optional country, identified by either `code` or `name`
    TimeZoneCountry country = 2;
}

message TimeZoneCanonicalName
{
    // Canonical/Olson name, e.g., "Etc/UTC", "America/Los_Angeles"
    string name = 1;
}

message TimeZoneCanonicalSpecs
{
    repeated TimeZoneCanonicalSpec specs = 1;
}

message TimeZoneCanonicalSpec
{
    // Canonical name ("Olson" name), e.g. `America/Los_Angeles` or `Etc/UTC`.
    string name = 1;

    // The English name for the area (continent or ocean) where this zone is
    // located. This corresponds to the first component of the canonical name,
    // e.g.:
    //   - America/*  -> "Americas"
    //   - Atlantic/* -> "Atlantic Ocean" 
   //   -  ...
    string area = 2;

    // One or more countries (and possibly a region within any of these
    // countries) where this time zone is used.
    repeated TimeZoneLocation locations = 3;

    // Geographical cordinates of the canonical location. For instance the
    // coordinates of `Europe/Berlin` is that of Berlin, not any other countries
    // where it is used (e.g. Norway, Sweden, Denmark)
    int32 latitude = 6;         // Seconds north of Equator
    int32 longitude = 7;        // Seconds east of Prime Meridian
}

message TimeZoneConfig
{
    // Used to uniquely identify a timezone, either by name or geographical locaion.
    oneof config
    {
        // Canonical zone name, e.g. "America/Los_Angeles"
        string canonical_zone = 1;

        // Country name and possibly region within.
        TimeZoneLocation location = 2;
    }
}

message TimeZoneInfoRequest
{
    // Canonical zone name.  If unspecified, use the currently configured zone.
    string canonical_zone = 1;

    // Timestamp, used to determine if DST is applicable. If unspecified, use
    // the server's current system time.
    google.protobuf.Timestamp time = 2;
}


message TimeZoneInfo
{
    /// Effective zone abbreviation, e.g.
    ///   - `PST` or `PDT` for Pacific Standard/Daylight Time
    ///   - `CET` or `CEST` for Central European Time / Summer Time
    string shortname = 1;       // Short name, e.g. PST or PDT

    /// Current zone offset from UTC, e.g. -7 hours if zone is PDT
    google.protobuf.Duration offset = 3;

    /// Current standard zone offset from UTC, e.g. -8 hours for PST
    google.protobuf.Duration stdoffset = 4;

    /// Whether Daylight Savings Time / Summer Time is currently in effect
    bool dst = 5;
}

//==============================================================================
// Process management

message CommandInvocation
{
    string working_directory = 1;
    repeated string argv = 2;
    string stdin = 3;
}

message CommandInvocationResponse
{
    uint64 pid = 1;
}

message CommandContinuation
{
    uint64 pid = 1;
    string stdin = 2;
}

message CommandResponse
{
    string stdout = 1;
    string stderr = 2;

    bool success = 3;

    oneof exit_status
    {
        int32 exit_code = 4;
        int32 exit_signal = 5;
    }

    string error_symbol = 6;
    string error_text = 7;
}

message Signal
{
    oneof signal {

        // Emitted 1x/second based on the server's current time.
        google.protobuf.Timestamp time = 8;

        // Emitted when automatic time settings changes.
        TimeConfig time_config = 9;

        // Emitted when canonical timezone configuration changes.
        TimeZoneCanonicalName tz_config = 10;

        // Effective zone change. Emitted when the canonical zone is updated,
        // or when daylight savings time stars or ends.
        TimeZoneInfo tz_info = 12;

        // Emitted when the server's primary host name changes
        HostInfo host_info = 14;

        // Emitted when there's a change in the product info, e.g. serial number configured
        ProductInfo product_info = 15;
    }
}