DDI API: Extend API response to report previous update execution status. (#506)

* DDI API: Limit number of feedback messages for an action status.

Even though the number of ActionStatus entries are limited to 1000 per
action using QuotaManagement, there is no limit on the number of
messages that can be sent as part of a single ActionStatus. This allows
a controller to potentially send large number of messages for a single
action.

Limiting the number of allowed messages to 50 using the
javax.validation.constraints.Size within DdiStatus.

Signed-off-by: Christian Storm <christian.storm@siemens.com>
Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com>
Signed-off-by: Raju HS <raju.hs@siemens.com>

* DDI API: Extend API response to retrieve controller feedback. (#381)

Resolves #381

The mechanism is useful for example, when the client software running on
the device loses this information prior to reporting a final execution
status such as 'closed' to hawkBit. This may happen, e.g., due to a
power cycle or simply a crash. Upon the client software restarting, it
installs the same payload again as advertised by hawkBit (as the device
has not sent a final update execution status). Instead, if the last
feedback sent to hawkBit would be reported back to the device, the
client may resume installation.

Feedback messages sent as part of POST
    /{tenant}/controller/v1/{targetid}/deploymentBase/{actionId}/feedback,
are sent back to controller as part of response to GET
    /{tenant}/controller/v1/{targetid}/deploymentBase/{actionId}.

Following example illustrates the API changes:

1. After retrieving the action from server, controller starts download
and sends a feedback.
curl
'http://127.0.0.1:8080/default/controller/v1/1/deploymentBase/1/feedback'
-i -X POST -H 'Content-Type: application/json;charset=UTF-8' -H 'Accept:
application/hal+json' -d '{
  "id" : "1",
  "time" : "20170406T121500",
  "status" : {
    "result" : {
      "progress" : {
        "of" : 1,
        "cnt" : 0
      },
      "finished" : "none"
    },
    "execution" : "proceeding",
    "details" : [ "proceeding with download" ]
  }
}'

2. Once artifact download has finished, controller sends another
feedback.
curl
'http://127.0.0.1:8080/default/controller/v1/1/deploymentBase/1/feedback'
-i -X POST -H 'Content-Type: application/json;charset=UTF-8' -H 'Accept:
application/hal+json' -d '{
{
  "id" : "1",
  "time" : "20170406T123000",
  "status" : {
    "result" : {
      "progress" : {
        "of" : 1,
        "cnt" : 0
      },
      "finished" : "none"
    },
    "execution" : "proceeding",
    "details" : [ "downloaded artifacts for update" ]
  }
}'

3. If there is a power outage now, the controller can retrieve the
messages posted earlier from the action history when it restarts again.
curl
'http://127.0.0.1:8080/default/controller/v1/1/deploymentBase/1?c=411599879&actionHistory=-1'
-i -H 'Accept: application/hal+json'

Response will be like below
{
  "id": "1",
  "deployment": {
    "download": "forced",
    "update": "forced",
    "chunks": [
      {
      "part": "os",
      "version": "1",
      "name": "1",
      "artifacts": [....],
      }
    ],
  },
  "actionHistory": {
    "status": "RETRIEVED",
    "messages": [
      "downloaded artifacts for update",
      "proceeding with download"
    ]
  }
}

4. Based on the feedback messages, controller may be able to skip the
download and resume with installation and send additional feedback.
curl
'http://127.0.0.1:8080/default/controller/v1/1/deploymentBase/1/feedback'
-i -X POST -H 'Content-Type: application/json;charset=UTF-8' -H 'Accept:
application/hal+json' -d '{
  "id" : "1",
  "time" : "20170406T121314",
  "status" : {
    "result" : {
      "progress" : {
        "of" : 1,
        "cnt" : 0
      },
      "finished" : "none"
    },
    "execution" : "resumed",
    "details" : [ "resuming installation based on previous feedback,
download skipped" ]
  }
}'

Note: The maximum number of messages to be retrieved from the database
by a controller is limited to 100. The actionHistory parameter's value
has the following meaning:

Input Value         | Output
-----------------------------
  <0                | Retrieve maximum allowed number of messages from
                    | action history.
  unspecified or =0 | Do not retrieve any message (default).
  >0                | Retrieve specified number of messages, limited by
                    | maximum allowed number.

Signed-off-by: Christian Storm <christian.storm@siemens.com>
Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com>
Signed-off-by: Raju HS <raju.hs@siemens.com>

hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/repository/ControllerManagement.java

@@ -9,6 +9,7 @@
 package org.eclipse.hawkbit.repository;
 
 import java.net.URI;
+import java.util.List;
 import java.util.Map;
 import java.util.Optional;
 
@@ -317,4 +318,30 @@ public interface ControllerManagement {
             + SpringEvalExpressions.IS_SYSTEM_CODE)
     Optional<Target> findByTargetId(@NotNull Long targetId);
 
+    /**
+     * Retrieves the specified number of messages from action history of the
+     * given {@link Action} based on messageCount. Regardless of the value of
+     * messageCount, in order to restrict resource utilization by controllers,
+     * maximum number of messages that are retrieved from database is limited by
+     * {@link RepositoryConstants#MAX_ACTION_HISTORY_MSG_COUNT}. messageCount <
+     * 0, retrieves the maximum allowed number of action status messages from
+     * history; messageCount = 0, does not retrieve any message; and
+     * messageCount > 0, retrieves the specified number of messages, limited by
+     * maximum allowed number. A controller sends the feedback for an
+     * {@link ActionStatus} as a list of messages; while returning the messages,
+     * even though the messages from multiple {@link ActionStatus} are retrieved
+     * in descending order by the reported time
+     * ({@link ActionStatus#getOccurredAt()}), i.e. latest ActionStatus first,
+     * the sub-ordering of messages from within single {@link ActionStatus} is
+     * unspecified.
+     *
+     * @param actionId
+     *            to be filtered on
+     * @param messageCount
+     *            is the number of messages to return from history
+     *
+     * @return action history.
+     */
+    @PreAuthorize(SpringEvalExpressions.IS_CONTROLLER)
+    List<String> getActionHistoryMessages(@NotNull Long actionId, final int messageCount);
 }

hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/repository/RepositoryConstants.java

@@ -30,6 +30,12 @@ public final class RepositoryConstants {
      */
     public static final int DEFAULT_DS_TYPES_IN_TENANT = 2;
 
+    /**
+     * Maximum number of messages that can be retrieved by a controller for an
+     * {@link Action}.
+     */
+    public static final int MAX_ACTION_HISTORY_MSG_COUNT = 100;
+
     private RepositoryConstants() {
         // Utility class.
     }