From a73ae9961f8a39d94c490ba5fe25c6de88bba7e0 Mon Sep 17 00:00:00 2001
From: Finn Stutzenstein <finn.stutzenstein@hotmail.de>
Date: Thu, 19 Nov 2020 13:52:39 +0100
Subject: [PATCH] Include new transaction mode for bulk actions

---
 docs/interfaces/action-service.txt | 59 ++++++++++++++++++------------
 1 file changed, 35 insertions(+), 24 deletions(-)

diff --git a/docs/interfaces/action-service.txt b/docs/interfaces/action-service.txt
index 173e4892e..0b17c2701 100644
--- a/docs/interfaces/action-service.txt
+++ b/docs/interfaces/action-service.txt
@@ -1,33 +1,28 @@
-# Actions Service Interface
-
-/**
- * JSON resonse with a status code of !=200:
- * {
- *     success: false;
- *     message: string;
- * }
- *
- */
-Exception ActionException(message: string);
+// Actions Service Interface
 
 /**
  * Executes multiple actions in the context of the user given by the user_id.
- * All actions are depdend: If one fails, nothing is written to the DataStore.
- * It can be seen as one transaction.
- *
- * For each action an ActionResult is returned. If an action has an error,
- * ActionError is used in combination wuth error_index to indicate, which action
- * resulted in an error.
+ * There are two modes of execution:
+ * single_validation=false (default):
+ *   All actions are validated in common, so if one action or one payload of
+ *   one action fails, the request is aborted with an ActionException indicating
+ *   the problematic action with both indices.
+ * single_validation=true:
+ *   Each action is validated by it's own. If there is an error, the error must
+ *   be reported via an ActionError in the ActionsResponse. The actions result
+ *   is not written into the Datastore. It might raise an ActionException if the
+ *   single write request to the Datastore fails (e.g. because of locking there)
  *
  * For general, non specific action-related, errors an ActionException is used.
  *
  * @throws ActionException
  */
-handle_request (payload: Action[], user_id: Id): ActionsResponse | ActionError
+handle_request(payload: Action[], user_id: Id): ActionsResponse
 
 interface Action {
     action: string;
-    data: object[];  # An array of action specific data.
+    data: object[];
+    single_validation?: boolean;
 }
 
 interace ActionsResponse {
@@ -35,19 +30,21 @@ interace ActionsResponse {
     message: string;
 
     /**
-     * this is a potentially double-array with entries for each action
+     * This is a potentially double-array with entries for each action
      * and, if not null, an array for each data provided for each action.
      *
-     *
-     * If an action does not producy a result, the inner array can be omitted and
+     * If an action does not produce a result, the inner array can be omitted and
      * null can be used. If the inner array is given, each entry must be an object
      * with the result (e.g. for a create action `{id: <the id>}`) or null.
-
+     *
      * E.g. for valid arrays (two actions with two data entries each):
      * - [null, null]
      * - [null, [null, null]]
      * - [null, [{id: 2}, null]]
      * - [[{id: 2}, {id: 3}], [{id: 5}, {id: 8}]]
+     *
+     *
+     * To report errors, use the ActionError format!
      **/
     results: ((object | null)[] | null )[]
 }
@@ -55,5 +52,19 @@ interace ActionsResponse {
 interface ActionError {
     success: false;
     message: string;
-    error_index: number;
+}
+
+/**
+ * JSON resonse with a status code of !=200. If a specific action raised the error,
+ * use the action_error_index and action_payload_error_index to indicate the errored
+ * action and payload. If there were general errors, both indices must be omitted.
+ *
+ * If the single_validation Flag was true in the request, it is not allowed to send
+ * action-specific errors with this exception. It must be responded through ActionsResponse.
+ */
+Exception ActionException {
+    success: false;
+    message: string;
+    action_error_index: number;
+    action_payload_error_index: number;
 }
\ No newline at end of file