commit 160809d12e9a956ffb4cbef0e3cb8cbb72804114
parent c68cb55278b9e1d6ce5cfebb5f948ccbf56be41e
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 8 Apr 2023 17:47:08 +0200
redo diagram in dot
Diffstat:
3 files changed, 74 insertions(+), 24 deletions(-)
diff --git a/Makefile b/Makefile
@@ -53,6 +53,8 @@ clean:
arch-api.png: arch-api.dot
dot -Tpng arch-api.dot > arch-api.png
+transaction-common-states.png: transaction-common-states.dot
+ dot -Tpng transaction-common-states.dot > transaction-common-states.png
coin.png: coin.dot
dot -Tpng coin.dot > coin.png
deposit.png: deposit.dot
@@ -60,7 +62,7 @@ deposit.png: deposit.dot
reserve.png: reserve.dot
dot -Tpng reserve.dot > reserve.png
-diagrams: arch-api.png coin.png
+diagrams: arch-api.png coin.png deposit.png reserve.png transaction-common-states.png
# The html-linked builder does not support caching, so we
diff --git 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
=========
diff --git a/transaction-common-states.dot b/transaction-common-states.dot
@@ -0,0 +1,28 @@
+digraph G {
+
+ initial[label="", shape="circle"];
+ pending[label="pending"];
+ done[label="done", shape="box"];
+ aborted[label="aborted", shape="box"];
+ aborting[label="aborting"];
+ failed[label="failed", shape="box"];
+ suspended[label="suspended"];
+
+ subgraph {
+ rank = same; pending;suspended;
+ }
+
+ subgraph {
+ rank = same; done; aborted; failed;
+ }
+
+ initial->pending;
+ pending->suspended [color="blue",label="suspend"];
+ suspended->pending [color="blue",label="resume"];
+ pending->done [color="green",label="success"];
+ pending->failed [color="red",label="error"];
+ pending->aborting [color="blue",label="abort"];
+ pending->aborted [color="blue",label="abort"];
+ aborting->aborted [color="green",label="success"];
+ aborting->failed [color="red",label="error"];
+}
