taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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:
Mcore/api-common.rst | 16++++++++++++++++
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.