local_profile.proto

// Copyright(c) 2021 Zededa, Inc.
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

import "info/info.proto";
import "metrics/metrics.proto";
import "google/protobuf/timestamp.proto";

package org.lfedge.eve.profile;

option go_package  = "github.com/lf-edge/eve-api/go/profile";
option java_package = "org.lfedge.eve.profile";

// LocalProfile message is sent in response to a GET to
// the api/v1/local_profile API
message LocalProfile {
   string local_profile = 1;
   string server_token = 2;
}

// RadioStatus message is sent in the POST request to the api/v1/radio API.
message RadioStatus {
   // radio_silence is True if the Radio-Silence mode is enabled by config AND successfully
   // applied for all radio devices.
   // If the radio silence was requested but this field is still returned as False,
   // expect non-empty config_error attached.
   bool radio_silence = 1;
   // If the last radio configuration change failed, error message is reported here.
   // Please note that there is also a per-modem configuration error reported under CellularStatus.
   string config_error = 2;
   // Status of every LTE network.
   repeated CellularStatus cellular_status = 3;
   // Metrics for every LTE network.
   repeated org.lfedge.eve.metrics.CellularMetric cellular_metrics = 4;
   // XXX Later we can add status for every WiFi network adapter.
}

// CellularStatus contains status information for a single LTE network.
message CellularStatus {
   // Logical label assigned to the physical cellular modem.
   string logicallabel = 1;
   org.lfedge.eve.info.ZCellularModuleInfo module = 2;
   repeated org.lfedge.eve.info.ZSimcardInfo sim_cards = 3;
   repeated org.lfedge.eve.info.ZCellularProvider providers = 4;
   string config_error = 10;
   string probe_error = 11;
}

// RadioConfig message may be returned in the response from a POST request
// sent to the api/v1/radio API by the local profile server (see PROFILE.md),
// or the message can be a part of the CompoundEdgeDevConfig message and
// returned by the local operator console (see config/compound_devconfig.proto).
message RadioConfig {
   // Security token. EVE will verify that serverToken matches the profile server
   // token received from the controller. Not used for the LOC case.
   string server_token = 1;
   // If enabled, EVE will disable radio transmission on all wireless devices available
   // to the host (i.e. it does not cover wireless devices directly attached to applications).
   bool radio_silence = 2;
}

// LocalAppInfoList contains information about all app on EdgeNode
// sent to the api/v1/appinfo
message LocalAppInfoList {
   repeated LocalAppInfo apps_info = 1;
}

// LocalAppInfo contains information about app on EdgeNode
message LocalAppInfo {
   string id = 1;
   string version = 2;
   string name = 3;
   org.lfedge.eve.info.ErrorInfo err = 4;
   org.lfedge.eve.info.ZSwState state = 5;
   // Value of the field `timestamp` from the last `AppCommand` that was
   // requested by the Local profile server, received by EVE and has completed
   // its execution for this application instance.
   uint64 last_cmd_timestamp = 6;
}

// LocalAppCmdList message may be returned in the response from a POST request
// sent to the api/v1/appinfo API by the local profile server (see PROFILE.md),
// or the message can be a part of the CompoundEdgeDevConfig message and
// returned by the local operator console (see config/compound_devconfig.proto)
message LocalAppCmdList {
   // Security token. EVE will verify that server_token matches the profile server
   // token received from the controller. Not used for the LOC case.
   string server_token = 1;
   // A list of commands requested to be executed for locally running application instances.
   // A new request created for the same application should overwrite the previous entry
   // with the 'timestamp' field updated. In other words, the list should contain at most
   // one entry for each application instance.
   // It is not required for the Local profile server to persist command requests.
   // Also, it is not required for the Local profile server to stop submitting command
   // requests that have been already processed by EVE. Using the `timestamp` field,
   // EVE is able to determine if a given command request has been already handled or not.
   // To check if the last requested command has completed, compare its timestamp with
   // 'last_cmd_timestamp' from `LocalAppInfo` message, submitted by EVE in the request
   // body of the api/v1/appinfo API.
   repeated AppCommand app_commands = 2;
}

// AppCommand references a running application instance by UUID and/or displayname,
// and describes a command to execute for this instance.
message AppCommand {
   // Reference the application instance by its ID (which is an instance of UUID).
   // At least one of the id and displayname should be defined.
   string id = 1;
   // Reference the application instance by the user-friendly displayname.
   // At least one of the id and displayname should be defined.
   string displayname = 2;
   // Timestamp to record when the request to run the command was made.
   // The format of the timestamp is not defined. It can be a Unix timestamp
   // or a different time representation. It is not even required for the timestamp
   // to match the real time or to be in-sync with the device clock.
   // What is required, however, is that two successive but distinct requests made
   // for the same application will have different timestamps attached.
   // This requirement applies even between restarts of the Local profile server.
   // A request made after a restart should not have the same timestamp attached
   // as the previous request made for the same application before the restart.
   //
   // EVE guarantees that a newly added command request or a change of the timestamp
   // will result in the command being triggered ASAP. Even if the execution of a command
   // is interrupted by a device reboot/crash, the eventuality of the command completion
   // is still guaranteed. The only exception is if Local Profile Server restarts/crashes
   // shortly after a request is made, in which case it can get lost before EVE is able
   // to receive it. For this scenario to be avoided, a persistence of command requests
   // on the side of the Local Profile server is necessary.
   uint64 timestamp = 3;
   enum Command {
      COMMAND_UNSPECIFIED = 0;
      // Application instance, which is either running or transitioning to a running state,
      // will be stopped and subsequently started again, preserving the mutated run time state.
      COMMAND_RESTART = 1;
      // Application instance, which is either running or transitioning to a running state,
      // will be stopped and the mutated run time state of the app is deleted.
      // A subsequent action to start the app will start it with a pristine runtime state.
      // This command will purge ALL volumes used by the application.
      COMMAND_PURGE = 2;
   }
   // Command to run.
   Command command = 4;
}

// LocalDevInfo contains information about an EdgeNode
// sent to the api/v1/devinfo
message LocalDevInfo {
   string device_uuid = 1;
   org.lfedge.eve.info.ZDeviceState state = 2;
   repeated org.lfedge.eve.info.MaintenanceModeReason maintenance_mode_reasons = 3;
   google.protobuf.Timestamp boot_time = 4;
   org.lfedge.eve.info.BootReason last_boot_reason = 5;

   // Value of the field `timestamp` from the last `DevCommand` that was
   // requested by the Local profile server, received by EVE and has completed
   // its execution for this edge node.
   uint64 last_cmd_timestamp = 10;
}

// LocalDevCmd message may be returned in the response from a POST request
// sent to the api/v1/devinfo API by the local profile server (see PROFILE.md),
// or the message can be a part of the CompoundEdgeDevConfig message and
// returned by the local operator console (see config/compound_devconfig.proto).
message LocalDevCmd {
   // Security token. EVE will verify that server_token matches the profile server
   // token received from the controller. Not used for the LOC case.
   string server_token = 1;
   // A command requested to be executed for the edge node.
   // A new request created will overwrite the previous entry with the 'timestamp'
   // field updated. In other words, if there are multiple commands to execute
   // then the local profile server has to wait until it receives the
   // last_cmd_timestamp for a command before issuing the next command.
   // It is not required for the Local profile server to persist command requests.
   // Also, it is not required for the Local profile server to stop submitting command
   // requests that have been already processed by EVE. Using the `timestamp` field,
   // EVE is able to determine if a given command request has been already handled or not.
   // To check if the last requested command has completed, compare its timestamp with
   // 'last_cmd_timestamp' from `LocalDevInfo` message, submitted by EVE in the request
   // body of the api/v1/devinfo API.

   uint64 timestamp = 2;
   enum Command {
      COMMAND_UNSPECIFIED = 0;
      // SHUTDOWN: Edge node will initiate a graceful shutdown of all of the app
      // instances on the node (including an application instance implementing
      // the local profile server API).
      // The state of the application instances (HALTING, HALTED, etc) can be
      // observed since is sent to the api/v1/appinfo API endpoint as normal.
      // Any local profile server is shut down after all the other app instances
      // have halted.
      COMMAND_SHUTDOWN = 1;
      // SHUTDOWN_POWEROFF: As above, but once all of the app instances have
      // been shut down the edge node will also power off. Note that the power
      // on will need to be done through other local means (UPS power cycling
      // the edge node or someone manually power cycling the edge node.)
      COMMAND_SHUTDOWN_POWEROFF = 2;
   }
   // Command to run.
   Command command = 3;
}