Add downloading state and download_details to PackageStatus (#206)

Add a separate `Downloading` `PackageStatusEnum` so an agent can use a distinguish between downloading and installing a new package.
Add a `download_details` attribute that may optionally be used with the new `Downloading` status to give a user additional details about the package download: download rate, and percentage download.

- Closes #204

proto/opamp.proto

@@ -802,6 +802,22 @@ message PackageStatus {
 
     // Error message if the status is erroneous.
     string error_message = 7;
+
+    // Optional details that may be of interest to a user.
+    // Should only be set if status is Downloading.
+    // Status: [Development]
+    PackageDownloadDetails download_details = 8;
+}
+
+
+// Additional details that an agent can use to describe an in-progress package download.
+// Status: [Development]
+message PackageDownloadDetails {
+    // The package download progress as a percentage.
+    double download_percent = 1;
+
+    // The current package download rate in bytes per second.
+    uint64 download_bytes_per_second = 2;
 }
 
 // The status of this package.
@@ -814,7 +830,7 @@ enum PackageStatusEnum {
     // Installation of this package has not yet started.
     PackageStatusEnum_InstallPending = 1;
 
-    // Agent is currently downloading and installing the package.
+    // Agent is currently installing the package.
     // server_offered_hash field MUST be set to indicate the version that the
     // Agent is installing. The error_message field MUST NOT be set.
     PackageStatusEnum_Installing = 2;
@@ -824,6 +840,12 @@ enum PackageStatusEnum {
     // tried to install. The error_message may also contain more details about
     // the failure.
     PackageStatusEnum_InstallFailed = 3;
+
+    // Agent is currently downloading the package.
+    // server_offered_hash field MUST be set to indicate the version that the
+    // Agent is installing. The error_message field MUST NOT be set.
+    // Status: [Development]
+    PackageStatusEnum_Downloading = 4;
 }
 
 // Properties related to identification of the Agent, which can be overridden

specification.md

@@ -88,6 +88,7 @@ Status: [Beta]
       - [PackageStatus.server_offered_hash](#packagestatusserver_offered_hash)
       - [PackageStatus.status](#packagestatusstatus)
       - [PackageStatus.error_message](#packagestatuserror_message)
+      - [PackageStatus.download_details](#packagestatusdownload_details)
   * [Connection Settings Management](#connection-settings-management)
     + [OpAMP Connection Setting Offer Flow](#opamp-connection-setting-offer-flow)
     + [Trust On First Use](#trust-on-first-use)
@@ -1310,11 +1311,14 @@ message PackageStatus {
     bytes server_offered_hash = 5;
     enum Status {
         INSTALLED = 0;
-        INSTALLING = 1;
-        INSTALL_FAILED = 2;
+        INSTALL_PENDING = 1;
+        INSTALLING = 2;
+        INSTALL_FAILED = 3;
+        DOWNLOADING = 4;
     }
     Status status = 6;
     string error_message = 7;
+    PackageDownloadDetails download_details = 8;
 }
 ```
 
@@ -1393,6 +1397,20 @@ failure.
 
 An error message if the status is erroneous.
 
+##### PackageStatus.download_details
+
+Status: [Development]
+
+The download_details contains additional details that descibe a package download.
+It should only be set if the status is `DOWNLOADING`.
+
+```protobuf
+message PackageDownloadDetails {
+  double download_percent = 1;
+  uint64 download_bytes_per_second = 2;
+}
+```
+
 ### Connection Settings Management
 
 Status: [Beta]