commit a74e8aa5d720da763d0ee628356434c9f785b13e
parent 8c16ce42ffe188a8519ea9fe3e8e5f178ff4a6c4
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 12 Jul 2024 01:10:13 +0200
more text work
Diffstat:
1 file changed, 73 insertions(+), 55 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -574,17 +574,20 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<section anchor="underlay" numbered="true" toc="default">
<name>Underlay</name>
<t>
- How peers are addressed in the underlay is out of scope of this document.
- For example, a peer may have a TCP/IP address, or expose a QUIC endpoint.
- While the specific addressing options and mechanisms are out of scope,
- it is necessary to define a universal addressing
- format in order to facilitate the distribution of <em>address</em>
- information to other <em>peers</em> in the DHT overlay.
- This standardized format is the <em>HELLO Block</em>
- (described in <xref target="hello_block"/>),
- which contains sets of addresses.
- If the address is a URI, it may indicate which underlay understands the
- respective <em>address</em> details.
+ A peer <bcp14>MUST</bcp14> implement one or more underlay
+ protocols. Peers supporting multiple underlays effectively
+ create a bridge between different networks. How peers are
+ addressed in a specific underlay is out of scope of this
+ document. For example, a peer may have a TCP/IP address, or
+ expose a QUIC endpoint. While the specific addressing options
+ and mechanisms are out of scope, it is necessary to define a
+ universal addressing format in order to facilitate the
+ distribution of <em>address</em> information to other
+ <em>peers</em> in the DHT overlay. This standardized format
+ is the <em>HELLO Block</em> (described in <xref
+ target="hello_block"/>), which contains sets of addresses. If
+ the address is a URI, it <bcp14>MAY</bcp14> indicate which
+ underlay understands the respective <em>address</em>.
</t>
<!--
1) The current API is always fire+forget, it doesn't allow for flow
@@ -628,16 +631,22 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<tt>TRY_CONNECT(P, A)</tt>
</dt>
<dd>
- This call allows an implementation to signal to the underlay that
- it wants to establish a connection to another peer <tt>P</tt> using an address <tt>A</tt>.
- If the connection attempt is successful, information on the new
- peer will be offered through the <tt>PEER_CONNECTED</tt> signal.
+ This call allows the DHT implementation to signal to the
+ underlay that the DHT wants to establish a connection to the
+ target peer <tt>P</tt> using the given address <tt>A</tt>.
+ If the connection attempt is successful, information on the
+ new peer connection will be offered through the
+ <tt>PEER_CONNECTED</tt> signal.
+ <!--
+ Underlay implementations
+ can ignore calls with addresses they do not support.
+ -->
</dd>
<dt>
<tt>HOLD(P)</tt>
</dt>
<dd>
- This call tells the underlay to keep a hold on to a connection
+ This call tells the underlay to 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.
@@ -650,7 +659,12 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
peer <tt>P</tt>. This call is only there for symmetry and
used during the peer's shutdown to release all of the remaining
<tt>HOLDs</tt>.
- <!-- FIXME: are we supposed to call DROP if a peer disconnects!?? -->
+ <!-- FIXME: are we supposed to call DROP if a peer disconnects?
+ NOTE: That would seem to be an implementation detail beyond what needs
+ to be in the RFC. An API may mandate DROP on disconnect, or
+ it may simply state that when the underlay signals a
+ disconnect, all holds are automatically dropped.
+ -->
As R<sup>5</sup>N always prefers the longest-lived
connections, it would never drop an active connection that it
has called <tt>HOLD()</tt> on before. Nevertheless, underlay implementations
@@ -664,70 +678,78 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
</dt>
<dd>
This call allows the local peer to send a protocol message
- <tt>M</tt> to a peer <tt>P</tt>.
+ <tt>M</tt> to a peer <tt>P</tt>. Sending messages is expected
+ to be done on a best-effort basis, thus the underlay does not
+ have to guarantee delivery or message ordering. If the underlay
+ implements flow- or congestion-control, it <bcp14>MAY</bcp14>
+ also discard messages to limit its queue size.
</dd>
<dt>
<tt>ESTIMATE_NETWORK_SIZE() -> L2NSE</tt>
</dt>
<dd>
- A call that provides an estimate of the network size.
- The result, <tt>L2NSE</tt>, must be the base-2 logarithm of the estimated number of peers in the network.
- It is used by the routing algorithm.
- If the underlay does not support a protocol for network size estimation
- (such as <xref target="NSE"/>) the value
- is assumed to be provided as a configuration parameter to the implementation.
+ This call must return an estimate of the network size. The
+ resulting <tt>L2NSE</tt> value must be the base-2 logarithm
+ of the <em>estimated</em> number of peers in the network.
+ It is used by the routing algorithm. If the underlay does
+ not support a protocol for network size estimation (such as
+ <xref target="NSE"/>) the value is assumed to be provided as
+ a configuration parameter to the implementation.
</dd>
</dl>
<t>
- The above calls are meant to be actively
- executed by the implementation as part of the peer-to-peer protocol.
- In addition, the underlay is expected to emit
- the following signals (usually implemented as callbacks)
- based on network events observed by the underlay implementation:
+ The above calls are meant to be actively executed by the
+ implementation as part of the peer-to-peer protocol. In
+ addition, the underlay creates <em>signals</em> to drive
+ updates of the routing table, local storage and message
+ processing (<xref target="p2p_messages"/>). Specifically,
+ the underlay is expected to emit the following
+ signals (usually implemented as callbacks) based on network
+ events observed by the underlay implementation:
</t>
<dl>
<dt>
<tt>PEER_CONNECTED -> P</tt>
</dt>
<dd>
- 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 and gossiping of HELLOs to that peer. Underlays may
- include meta-data about the connection, for example to indicate
- that the connection is from a resource-constrained host that does
- not intend to function as a full <em>peer</em> and thus should not
- be considered for routing.
+ This signal allows the DHT to react to a newly connected
+ peer <tt>P</tt>. Such an event triggers, for example,
+ updates in the routing table and gossiping of HELLOs to that
+ peer. Underlays may include meta-data about the connection,
+ for example to indicate that the connection is from a
+ resource-constrained host that does not intend to function
+ as a full <em>peer</em> and thus should not be considered
+ for routing.
</dd>
<dt>
<tt>PEER_DISCONNECTED -> P</tt>
</dt>
<dd>
- is a signal that allows the DHT to react to a recently disconnected
- peer.
- Such an event triggers, for example, updates in the
- routing table.
+ This signal allows the DHT to react to a recently
+ disconnected peer. Such an event primarily triggers updates
+ in the routing table.
</dd>
<dt>
<tt>ADDRESS_ADDED -> A</tt>
</dt>
<dd>
- 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 about the local peer to other peers.
- <tt>A</tt> must be a URI suitable for inclusion in a <tt>HELLO</tt> payload
+ 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 about the local
+ peer to other peers. <tt>A</tt> <bcp14>MUST</bcp14> be an
+ address suitable for inclusion in a <tt>HELLO</tt> payload
<xref target="hello_block"/>.
</dd>
<dt>
<tt>ADDRESS_DELETED -> A</tt>
</dt>
<dd>
- This underlay signal 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.
+ This underlay signal indicates that an address <tt>A</tt>
+ was removed from the set of addresses the local peer is
+ possibly reachable under. Addresses <bcp14>MUST</bcp14> have
+ been added before they may be deleted. The signal is used
+ to stop advertising this address to other peers.
</dd>
<dt>
<tt>RECEIVE -> (P, M)</tt>
@@ -737,10 +759,6 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
message <tt>M</tt> was received from a peer <tt>P</tt>.
</dd>
</dl>
- <t>
- These signals then drive updates of the routing table, local storage
- and message transmission.
- </t>
</section>
<section anchor="routing" numbered="true" toc="default">
<name>Routing</name>
