commit c409e987a7cbe04423c86e5844b1d723e2d5759f
parent 280ca4052700a6c6e5a1bd031dcc26f06994593b
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Thu, 10 Mar 2022 12:46:06 +0100
review underlay api
Diffstat:
1 file changed, 41 insertions(+), 27 deletions(-)
diff --git 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>
