From 160809d12e9a956ffb4cbef0e3cb8cbb72804114 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 8 Apr 2023 17:47:08 +0200 Subject: redo diagram in dot --- .../037-wallet-transactions-lifecycle.rst | 66 ++++++++++++++-------- 1 file changed, 43 insertions(+), 23 deletions(-) (limited to 'design-documents') diff --git a/design-documents/037-wallet-transactions-lifecycle.rst b/design-documents/037-wallet-transactions-lifecycle.rst index 8a8df2e2..64ec242a 100644 --- a/design-documents/037-wallet-transactions-lifecycle.rst +++ b/design-documents/037-wallet-transactions-lifecycle.rst @@ -23,7 +23,7 @@ and aborting have transaction-specific sub-states, denoted by ``state(substate)` ``initial``: The initial state is the result a user interaction. A transaction may have more than one initial state (if it is started in multiple ways) or none -(if it's the result of another process) +(if it's the result of another process). ``pending``: A pending transaction waits for some external event/service. The transaction stays pending until its change on the wallet's material balance @@ -31,12 +31,13 @@ is finished. Any pending state can be suspended and resumed. There are some other distinctions for pending transactions: -* long-polling vs exponential backoff: A pending transaction is either waiting +* long-polling vs. exponential backoff: A pending transaction is either waiting on an external service by making a long-polling request or by repeating requests with exponential back-off. * ``lastError``: A pending transaction is either clean (i.e. the network interaction is literally active in transmission or the external service successfully - communicated that it is not ready yet) or has a ``lastError``, which is a ``TalerErrorDetails`` + communicated that it is not ready yet and this is perfectly normal) + or has a ``lastError``, which is a ``TalerErrorDetails`` object with details about what happened during the last attempt to proceed with the transaction. @@ -47,7 +48,7 @@ never has a ``lastError`` but is considered successful. complete the transaction, the wallet is taking active steps to abort it. The ``lastError`` indicates errors the wallet experienced while taking active steps to abort the transaction. -``aborted``: Similar to a ``done`` transaction, but the transaction was successfully aborted +``aborted``: Similar to ``done``, but the transaction was successfully aborted instead of successfully finished. It will have the information of when (timestamp) it was aborted and in which pending sub-state the abort action was initiated. Also, we can include more information information relevant to the transaction in `abortReason` @@ -55,11 +56,11 @@ include more information information relevant to the transaction in `abortReason ``suspended``: Similar to a ``aborted`` transaction, but the transaction was could be resumed and may then still succeed. -``failed``: Similar to ``done``, but the transaction could not even be aborted successfully. +``failed``: Similar to ``done``, but the transaction could not even be aborted properly. ``deleted``: A ``deleted`` state is always a final state. We only use this state for illustrative purposes. In the implementation, the data associated -with the transaction would be deleted. +with the transaction would be literally deleted. Common Transitions @@ -67,12 +68,12 @@ Common Transitions Transitions are actions or other events. -``[action:delete]``: Deleting a transaction (also called "forgetting" in the UI) -completely deletes the transaction in the database. Depending on the type of +``[action:delete]``: Deleting a transaction +completely deletes the transaction from the database. Depending on the type of transaction, some of the other data *resulting* from the transaction might still survive deletion. For example, deleting a withdrawal transaction does not delete already successfully withdrawn coins. Deleting is only safe (no money lost) -on initial and final state (failed, aborted, done) +on initial and final states (failed, aborted, done). ``[action:retry]``: Retrying a transaction *(1.)* stops ongoing long-polling requests for the transaction *(2.)* resets the retry timeout *(3.)* re-runs the @@ -84,35 +85,51 @@ states: ``pending(*)`` and ``aborting(*)``. Should we show the retry timeout in the UI somewhere? Should we show it in dev mode? SEBASJM: Since the wallet will retry anyway, maybe is better if we replace the "retry" - button with a "try now" button and a side text "retrying in xxx seconds" + button with a "try now" button and a side text "retrying in xxx seconds". + + CG: Instead of a side text, this *might* make a good mouse-over hint for + a "retry" (or "try now") button. I would not make this overly visible with + side-text as the information is not that important. The text should also be + "retrying next at XXX" using an absolute time XXX --- otherwise the UI would + be way too busy recomputing/updating all of these strings: Using an absolute time, + we only have to redraw anything once a retry actually happened. Given that + retries should basically never be > 24h (we can impose a hard cap), the absolute + time can just be in the format HH:MM:SS (without day). ``[action:abort]``: Aborting a transaction either directly stops processing for the -transaction and puts it in an ``aborted`` state or starts the necessary steps to +transaction and puts it in an ``aborted`` state, or starts the necessary steps to actively abort the transaction (e.g. to avoid losing money) and puts it in an ``aborting`` state. -``[action:suspend]``: Suspends a pending transaction, stopping any associated network activities, but with a chance of trying -again at a later time. This could be useful if a user needs to save battery power or bandwidth and an operation is expected -to take longer (such as a backup, recovery or very large withdrawal operation). +``[action:suspend]``: Suspends a pending transaction, stopping any associated +network activities, but with a chance of trying again at a later time. This +could be useful if a user needs to save battery power or bandwidth and an +operation is expected to take longer (such as a backup, recovery or very large +withdrawal operation). -``[action:resume]``: Suspended transactions may be resumed, placing them back into a pending state. +``[action:resume]``: Suspended transactions may be resumed, placing them back +into a pending state. -``[action:abort-force]``: Directly puts an ``aborting`` transaction into the ``failed`` state. +``[action:abort-force]``: Directly puts an ``aborting`` transaction into the +``failed`` state. -Whether aborting or resuming is possible depends on the transaction type, and usually only one -of the two choices should be offered. +Whether aborting or resuming are possible depends on the transaction type, and +usually only one of the two choices should be offered. -.. image:: ../transaction-common-states.svg +.. image:: ../transaction-common-states.png :width: 400 -Boxed label means end state, where it is safe to delete the transaction record since no work is due. -Blue arrows means mean user-triggered actions +Boxed labels indicate an end state in which it is safe to delete the +transaction record since no work is due. + +Blue arrows are used for user-triggered actions (via UI buttons). + Common pending sub-states ---------------------------------- +------------------------- During the pending state the transaction can go through several sub-states before reaching a final state. Some of this sub-states are shared between different @@ -627,7 +644,10 @@ The payment succeed but if auto-refund-check is active it will be checking for r Alternatives ============ -* each transaction could be treated completely separately +* Each transaction could be treated completely separately; however, uniform + terminology for actions (and thus button labels) is likely more helpful for + the user experience. + Drawbacks ========= -- cgit v1.2.3