commit 0006a4c39af131ae52171f73f0b2d209045a03d6
parent ceeae4984fb7f8ca72878b98f22fa10bd1d1fcad
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 19 Nov 2026 10:51:24 +0100
api-common: history row IDs must become visible in order
Wirewatch continues strictly after the last row ID it processed, so a
history row that commits after one with a higher ID is never seen.
libeufin and taler-rust already lock the table for this; say so in the
spec, so that new wire gateways and history endpoints keep the guarantee.
Diffstat:
1 file changed, 16 insertions(+), 0 deletions(-)
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -244,6 +244,22 @@ If *offset* is not explicitly given, it defaults to:
* A value **smaller** than all other row IDs if *limit* is **positive**.
* A value **larger** than all other row IDs if *limit* is **negative**.
+Row IDs of a history (for example the wire gateway's ``/history/incoming``
+and ``/history/outgoing``, and the revenue API's ``/history``) are assigned in
+the order in which their elements become visible: once a client has received
+an element with row ID *n*, no element with a row ID at or below *n* may
+appear later. Clients rely on this: they store the row ID of the last element
+that they processed and continue strictly after it, so an element that became
+visible after one with a higher row ID would never reach them. Row IDs may
+have gaps, and clients must not expect them to be consecutive.
+
+A database sequence alone does not give this order, because transactions can
+commit in another order than the one in which they drew their row IDs, and
+not even ``SERIALIZABLE`` isolation prevents that. An implementation
+therefore lets only one transaction at a time draw row IDs of a history and
+holds that exclusion until the transaction has committed, for example with a
+table lock or an advisory lock taken just before the row ID is drawn.
+
:query limit: *Optional.*
At most return the given number of results. Negative for descending by row
ID, positive for ascending by row ID.