[lsd0004] branch master updated: review underlay api

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository lsd0004.

The following commit(s) were added to refs/heads/master by this push:
     new c409e98  review underlay api
c409e98 is described below

commit c409e987a7cbe04423c86e5844b1d723e2d5759f
Author: Christian Grothoff <grothoff@gnunet.org>
AuthorDate: Thu Mar 10 12:46:06 2022 +0100

    review underlay api
---
 draft-schanzen-r5n.xml | 68 ++++++++++++++++++++++++++++++--------------------
 1 file changed, 41 insertions(+), 27 deletions(-)

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 05350f4..ffe61d3 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -476,7 +476,9 @@ Connectivity | |Underlay|  |Underlay|
         for this document, it is necessary to define a universal addressing
         format in order to facilitate the distribution of connectivity
         information to other peers in the DHT overlay.
-        This format is the "HELLO" message.
+        This format is the "HELLO" Block (described in <xref 
target="hello_block"/>),
+       which contains URIs. The schema of each URI indicates which underlay 
understands the
+       respective address given in the rest of the URI.
       </t>
       <!--
         1) The current API is always fire+forget, it doesn't allow for flow
@@ -500,10 +502,10 @@ Connectivity | |Underlay|  |Underlay|
         Security considerations? Prerequisites?
       -->
       <t>
-        It is expected that there are basic mechanisms available to
+        It is expected that the underlay provides basic mechanisms to
         manage peer connectivity and addressing.
-        The required functionality are abstracted through the following
-        procedures:
+        The required functionalities can be represented by the following
+        API:
       </t>
       <dl>
         <dt>
@@ -519,44 +521,47 @@ Connectivity | |Underlay|  |Underlay|
           <tt>HOLD(P)</tt>
         </dt>
         <dd>
-          A function which tells the underlay to keep a hold on the connection
-          to a peer <tt>P</tt>. <!--FIXME what is this needed for?-->
+          A function which tells the underlay to keep a hold on to a connection
+          to a peer <tt>P</tt>.  Underlays are usually limited in the number
+         of active connections.  With this function the DHT can indicate to the
+         underlay which connections should preferably be preserved.
         </dd>
         <dt>
           <tt>DROP(P)</tt>
         </dt>
         <dd>
           A function which tells the underlay to drop the connection to a
-          peer <tt>P</tt>. <!--FIXME what is this needed for?-->
-        </dd>
-        <dt>
-          <tt>M = RECEIVE(P)</tt>
-        </dt>
-        <dd>
-          A function or event that allows the local peer to receive a protocol
-          message <tt>M</tt> as defined in this document from a peer 
<tt>P</tt>.
+          peer <tt>P</tt>.  This function is only there for symmetry and
+         used during the peer's shutdown to release all of the remaining
+         HOLDs.  As R<sup>5</sup>N always prefers the longest-lived
+         connections, it would never drop an active connection that it
+         has called HOLD() on before. Nevertheless, underlay implementations
+         should not rely on this always being true.  A call to DROP() also
+         does not imply that the underlay must close the connection: it merely
+         removes the preference to preserve the connection that was established
+         by HOLD().
         </dd>
         <dt>
           <tt>SEND(P, M)</tt>
         </dt>
         <dd>
           A function that allows the local peer to send a protocol message
-          <tt>M</tt> as defined in this document to a peer <tt>P</tt>.
-          If call to SEND fails, the message has not been sent.
+          <tt>M</tt> to a peer <tt>P</tt>.
         </dd>
         <dt>
           <tt>S = ESTIMATE_NETWORK_SIZE()</tt>
         </dt>
         <dd>
           A procedure that provides estimates on the network size
-          <tt>S</tt> for use in the DHT routing algorithms.
-          <!--FIXME: What is S and give an example.-->
+          <tt>S</tt>, that is the number of peers in the network,
+         for use by the routing algorithm.
         </dd>
       </dl>
       <t>
         In addition to the above procedures, which are meant to be actively
         executed by the implementation as part of the peer-to-peer protocol,
-        the following callbacks or signals drive updates of the routing table:
+        the following signals (usually implemented as callbacks) drive
+       updates of the routing table, local storage and message transmission:
       </t>
       <dl>
         <dt>
@@ -566,7 +571,7 @@ Connectivity | |Underlay|  |Underlay|
           is a signal that allows the DHT to react to a newly connected peer
           <tt>P</tt>.
           Such an event triggers, for example, updates in the
-          routing table.
+          routing table and gossiping of HELLOs to that peer.
         </dd>
         <dt>
           <tt>PEER_DISCONNECTED -> P</tt>
@@ -581,20 +586,29 @@ Connectivity | |Underlay|  |Underlay|
           <tt>ADDRESS_ADDED -> A</tt>
         </dt>
         <dd>
-          The underlay signals us that an address <tt>A</tt> was added for our
-          local peer.
+          The underlay signals indicates that an address <tt>A</tt> was added 
for our
+          local peer and that henceforth the peer may be reachable under this 
address.
           This information is used to advertise
-          connectivity information to the local peer.
-          <tt>A</tt> is a string suitable for inclusion in a HELLO payload
+          connectivity information about the local peer to other peers.
+          <tt>A</tt> must be a URI suitable for inclusion in a HELLO payload
           <xref target="hello_block"/>.
         </dd>
         <dt>
           <tt>ADDRESS_DELETED -> A</tt>
         </dt>
         <dd>
-          The underlay signals us that an address <tt>A</tt> was removed.
-          This information is used, for example, to no longer advertise
-          this address.
+          This underlay signals indicates that an address <tt>A</tt> was 
removed
+         from the set of addresses the local peer is possibly reachable
+         under. Addresses must have been added before they may be deleted.
+          This information is used to no longer advertise
+          this address to other peers.
+        </dd>
+        <dt>
+          <tt>RECEIVE() -> (P, M)</tt>
+        </dt>
+        <dd>
+          This signal informs the local peer that a protocol
+          message <tt>M</tt> was received from a peer <tt>P</tt>.
         </dd>
       </dl>
     </section>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.