gnunet-handbook

commit bc6bbd4031ee382c3013a811f6d4f3a30da27c37
parent d86773638e15598d51559ab2cbaf8883f86caab3
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Tue, 18 Oct 2022 13:54:35 +0900

more namestore documentation

Diffstat:
M
developers/rest/namestore.rst
 | 
28
++++++++++++++++++++--------
M
developers/subsystems/namestore/namestore.rst
 | 
34
++++++++++++++++++++++++++++++++++

2 files changed, 54 insertions(+), 8 deletions(-)
diff --git a/developers/rest/namestore.rst b/developers/rest/namestore.rst
@@ -8,7 +8,8 @@ Record Set
 
 Namestore entries are GNS record sets. A record set consists of a ``record_name`` and a ``data`` field.
 
-  .. ts:def:: RecordSet
+.. _RecordSet:
+.. ts:def:: RecordSet
 
     interface RecordSet {
 
@@ -20,6 +21,9 @@ Namestore entries are GNS record sets. A record set consists of a ``record_name`
 
     }
 
+.. _RecordData:
+.. ts:def:: RecordData
+
     interface RecordData {
 
       // The string representation of the record data value, e.g. "1.2.3.4" for an A record
@@ -48,8 +52,9 @@ Namestore entries are GNS record sets. A record set consists of a ``record_name`
 Error Response
 ^^^^^^^^^^^^^^
 
-All error responses are sent with a `NamestoreError` body.
+All error responses are sent with a `NamestoreError`_ body.
 
+  .. _NamestoreError:
   .. ts:def:: NamestoreError
 
     interface NamestoreError {
@@ -69,7 +74,7 @@ Requests
   **Response**
 
   :http:statuscode:`200 Ok`:
-    The body is a `RecordSet` array.
+    The body is a `RecordSet`_ array.
   :http:statuscode:`404 Not found`:
     The zone $ZNAME was not found.
 
@@ -79,7 +84,7 @@ Requests
   Create or append a record set under a label.
 
   **Request**
-    The request body is a single `RecordSet`.
+    The request body is a single `RecordSet`_.
 
   **Response**
 
@@ -93,7 +98,7 @@ Requests
   Create or replace a record set under a label.
 
   **Request**
-    The request body is a single `RecordSet`.
+    The request body is a single `RecordSet`_.
 
   **Response**
 
@@ -106,7 +111,7 @@ Requests
 
 .. http:delete:: /namestore/$ZNAME?record_name=$RNAME
 
-  Delete the record set under name $RNAME in zone $ZNAME                                                                     |
+  Delete the record set under name $RNAME in zone $ZNAME
 
   **Response**
 
@@ -117,10 +122,17 @@ Requests
 
 .. http:post:: /namestore/import/$ZNAME
 
-  Bulk import (no replace) record sets under a label.
+  Bulk import of record sets into a zone.
+  This API adds the provided array of `RecordSet`_ to the zone.
+  This operation does **NOT** replace existing records under the label(s).
+  If you want a clean import, reset your database before using this API.
+  This API is making sure that the records are added within one database
+  transaction, calling ``GNUNET_NAMESTORE_transaction_begin``,
+  ``GNUNET_NAMESTORE_records_store2`` (successively, if necessary) and finally
+  ``GNUNET_NAMESTORE_transaction_commit``.
 
   **Request**
-    The request body is a `RecordSet` array.
+    The request body is a `RecordSet`_ array.
 
   **Response**
 
diff --git a/developers/subsystems/namestore/namestore.rst b/developers/subsystems/namestore/namestore.rst
@@ -93,6 +93,40 @@ all labels and records stored in a zone. Here the client uses the
 zone, the nickname as string plus a the callback with the result of the
 operation.
 
+.. _Transactional-Namestore-API:
+
+Transactional operations
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+All API calls by default are mapped to implicit single transactions in the
+database backends.
+This happends automatically, as most databases support implicit transactions
+including the databases supported by NAMESTORE.
+
+However, implicit transactions have two drawbacks:
+
+  1. When storing or deleting a lot of records individual transactions cause
+     a significant overhead in the database.
+  2. Storage and deletion of records my multiple clients concurrently can lead
+     to inconsistencies.
+
+This is why NAMESTORE supports explicit transactions in order to efficiently
+handle large amounds of zone data as well as keep then NAMESTORE consistent
+when the client thinks this is necessary.
+
+When the client wants to start a transaction, ``GNUNET_NAMESTORE_transaction_begin``
+is called.
+After this call, ``GNUNET_NAMESTORE_records_lookup`` or ``GNUNET_NAMESTORE_records_store(2)``
+can be called successively.
+The operations will only be commited to the database (and monitors such as ZONEMASTER
+notified of the changes) when ``GNUNET_NAMESTORE_transaction_commit`` is used
+to finalize the transaction.
+Alternatively, the transaction can be aborted using ``GNUNET_NAMESTORE_transaction_rollback``.
+Should the client disconnect after calling ``GNUNET_NAMESTORE_transaction_begin``
+any running transaction will automatically be rolled-back.
+
+
+
 .. _Iterating-Zone-Information:
 
 Iterating Zone Information