From 5b0047b093824ffa038b0f849ed76e48e19595ef Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Tue, 10 Nov 2020 17:28:57 +0100 Subject: [PATCH 1/7] Enhance the action interface --- docs/interfaces/actions-service.txt | 48 ++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/interfaces/actions-service.txt b/docs/interfaces/actions-service.txt index 7b9ee2f88..0b3c43083 100644 --- a/docs/interfaces/actions-service.txt +++ b/docs/interfaces/actions-service.txt @@ -1,25 +1,59 @@ # Actions Service Interface +/** + * JSON resonse with a status code of !=200: + * { + * success: false; + * message: string; + * } + * + */ Exception ActionException(message: string); - /** * Executes multiple actions in the context of the user given by the user_id. - * All actions are processed independently. + * All actions are depdend: If one fails, nothing is written to the DataStore. + * It can be seen as one transaction. * - * TODO: Maybe we do not want to run them independently. + * 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. * + * For general, non specific action-related, errors an ActionException is used. * * @throws ActionException */ -handle_request (payload: Action[], user_id: Id): ActionResult[] +handle_request (payload: Action[], user_id: Id): ActionsResult | ActionError interface Action { action: string; - data: object[]; # An array of action specific data. See JSON schema defintions. + data: object[]; # An array of action specific data. } -interface ActionResult { - success: boolean; +interace ActionsResult { + success: true; message: string; + + /** + * 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 + * 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: }`) 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}]] + **/ + results: ((object | null)[] | null )[] } + +interface ActionError { + success: false; + message: string; + error_index: number; +} \ No newline at end of file From 8cfa7d0a514a3fe4f676483b73f2879f30622e78 Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Wed, 11 Nov 2020 08:33:59 +0100 Subject: [PATCH 2/7] Result->Response, actions->action --- docs/interfaces/{actions-service.txt => action-service.txt} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/interfaces/{actions-service.txt => action-service.txt} (93%) diff --git a/docs/interfaces/actions-service.txt b/docs/interfaces/action-service.txt similarity index 93% rename from docs/interfaces/actions-service.txt rename to docs/interfaces/action-service.txt index 0b3c43083..173e4892e 100644 --- a/docs/interfaces/actions-service.txt +++ b/docs/interfaces/action-service.txt @@ -23,14 +23,14 @@ Exception ActionException(message: string); * * @throws ActionException */ -handle_request (payload: Action[], user_id: Id): ActionsResult | ActionError +handle_request (payload: Action[], user_id: Id): ActionsResponse | ActionError interface Action { action: string; data: object[]; # An array of action specific data. } -interace ActionsResult { +interace ActionsResponse { success: true; message: string; From a73ae9961f8a39d94c490ba5fe25c6de88bba7e0 Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Thu, 19 Nov 2020 13:52:39 +0100 Subject: [PATCH 3/7] 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: }`) 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 From cb7e91d8c59e360560842c17583395d558ad77ef Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Thu, 19 Nov 2020 13:54:53 +0100 Subject: [PATCH 4/7] Fixed ActionsResult --- docs/interfaces/action-service.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/interfaces/action-service.txt b/docs/interfaces/action-service.txt index 0b17c2701..1b4178d87 100644 --- a/docs/interfaces/action-service.txt +++ b/docs/interfaces/action-service.txt @@ -46,7 +46,7 @@ interace ActionsResponse { * * To report errors, use the ActionError format! **/ - results: ((object | null)[] | null )[] + results: ((object | ActionError | null)[] | null )[] } interface ActionError { From a0d0a4ac0bfd20ddb8627faa827c1a39d480bef5 Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Thu, 19 Nov 2020 15:01:49 +0100 Subject: [PATCH 5/7] Change name --- docs/interfaces/action-service.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/interfaces/action-service.txt b/docs/interfaces/action-service.txt index 1b4178d87..56c2464f8 100644 --- a/docs/interfaces/action-service.txt +++ b/docs/interfaces/action-service.txt @@ -3,11 +3,11 @@ /** * Executes multiple actions in the context of the user given by the user_id. * There are two modes of execution: - * single_validation=false (default): + * atomic=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: + * atomic=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 @@ -22,7 +22,7 @@ handle_request(payload: Action[], user_id: Id): ActionsResponse interface Action { action: string; data: object[]; - single_validation?: boolean; + atomic?: boolean; } interace ActionsResponse { @@ -59,7 +59,7 @@ interface ActionError { * 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 + * If the atomic 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 { From 62f40d1447f3c040420aa7d85ed8a045c2f9e148 Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Wed, 25 Nov 2020 12:17:01 +0100 Subject: [PATCH 6/7] move atomic parameter --- docs/interfaces/action-service.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/interfaces/action-service.txt b/docs/interfaces/action-service.txt index 56c2464f8..da8e4dfdc 100644 --- a/docs/interfaces/action-service.txt +++ b/docs/interfaces/action-service.txt @@ -17,12 +17,11 @@ * * @throws ActionException */ -handle_request(payload: Action[], user_id: Id): ActionsResponse +handle_request(payload: Action[], user_id: Id, atomic?: boolean): ActionsResponse interface Action { action: string; data: object[]; - atomic?: boolean; } interace ActionsResponse { From 4f02a236b479446ff492883659488a28e4cd22ef Mon Sep 17 00:00:00 2001 From: Finn Stutzenstein Date: Fri, 27 Nov 2020 10:47:02 +0100 Subject: [PATCH 7/7] small changes --- docs/interfaces/action-service.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/interfaces/action-service.txt b/docs/interfaces/action-service.txt index da8e4dfdc..59dc3f00b 100644 --- a/docs/interfaces/action-service.txt +++ b/docs/interfaces/action-service.txt @@ -56,14 +56,15 @@ interface ActionError { /** * 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. + * action and payload. If there were general errors, both indices must be omitted or null. * * If the atomic flag was true in the request, it is not allowed to send - * action-specific errors with this exception. It must be responded through ActionsResponse. + * action-specific errors with this exception. It must be responded with an + * ActionError through ActionsResponse (resulting in a status code of 200). */ Exception ActionException { success: false; message: string; - action_error_index: number; - action_payload_error_index: number; -} \ No newline at end of file + action_error_index?: number; + action_payload_error_index?: number; +}