commit 9019e66771e402aa4d4e2dcf6ebaec31fdf46331
parent bfc35b90931460b506f797f4104d6b411311449c
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 15 Jul 2024 12:39:52 +0200
more wording and reorder
Diffstat:
1 file changed, 41 insertions(+), 34 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -264,8 +264,14 @@
<dt>Block Type</dt>
<dd>
A unique 32-bit value identifying the data format of a <em>block</em>.
- <em>Block types</em> are either private or registered in the GANA block type registry (see
- <xref target="gana_block_type"/>).
+ <em>Block types</em> may be public or private.
+ Applications that require application-specific
+ block payloads are expected to register a
+ block type in the GANA Block-Type registry
+ (<xref target="gana_block_type"/>) and provide a specification
+ of the associated block operations (<xref
+ target="block_functions"/>) to implementors of
+ R<sup>5</sup>N.
</dd>
<dt>Bootstrapping</dt>
<dd>
@@ -541,14 +547,8 @@
R<sup>5</sup>N implementation are divided into
routing (<xref target="routing"/>), message
processing (<xref target="p2p_messages"/>) and
- block processing (<xref target="blockstorage"/>).
- Applications that require application-specific
- block payloads are expected to register a
- block type in the GANA Block Type registry
- (<xref target="gana_block_type"/>) and provide a specification
- of the associated block operations (<xref
- target="block_functions"/>) to implementors of
- R<sup>5</sup>N. <xref target="figure_r5n_arch"/> illustrates
+ block storage (<xref target="blockstorage"/>).
+ <xref target="figure_r5n_arch"/> illustrates
the architectural overview of R<sup>5</sup>N.
</t>
<figure anchor="figure_r5n_arch" title="The R5N architecture.">
@@ -589,13 +589,15 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
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, or both. While the specific addressing options
- and mechanisms are out of scope, it is necessary to define a
+ and mechanisms are out of scope for this document,
+ it is necessary to define a
universal addressing format in order to facilitate the
distribution of address information to other
- peers in the DHT overlay. This standardized format
+ peers in the DHT overlay.
+ This standardized format
is the HELLO block (described in <xref
- target="hello_block"/>), which contains sets of addresses. If
- the address is a URI, it may indicate which
+ target="hello_block"/>), which contains sets of addresses.
+ If the address is a URI, it may indicate which
underlay understands the respective address.
</t>
<!--
@@ -633,7 +635,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
It is expected that the underlay provides basic mechanisms to
manage peer connectivity and addressing.
The essence of the underlay interface is
- captured by the following set of API calls:
+ captured by the following set of API calls:
</t>
<dl>
<dt>
@@ -700,10 +702,10 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
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
+ This estimate 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.
+ a configuration parameter to the underlay implementation.
</dd>
</dl>
<t>
@@ -865,28 +867,32 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<section anchor="find_peer">
<name>Peer Discovery</name>
<t>
- Initially, implementations depend upon either the underlay
- providing at least one initial connection to a
+ Initially, implementations require at least one initial connection to a
neighbor (signalled through
- <tt>PEER_CONNECTED</tt>), or the application or
- even end-user providing at least one working <tt>HELLO</tt>
- which is then in turn used to call <tt>TRY_CONNECT()</tt> on
- the underlay in order to trigger a subsequent
- <tt>PEER_CONNECTED</tt> signal from the underlay
- interface. This is commonly achieved through the
- configuration of hardcoded bootstrap peers or bootstrap
- servers either for the underlay or the R<sup>5</sup>N
- implementation. The first connection <bcp14>SHOULD</bcp14> be established
+ <tt>PEER_CONNECTED</tt>).
+ The first connection <bcp14>SHOULD</bcp14> be established
by an out-of-band exchange of the information from a
<tt>HELLO</tt> block.
+ This is commonly achieved through the
+ configuration of hardcoded bootstrap peers or bootstrap
+ servers either for the underlay or the R<sup>5</sup>N
+ implementation.
+ </t>
+ <t>
Implementations <bcp14>MAY</bcp14> have other means to achieve this
initial connection.
+ For example, implementations could allow the application or
+ even end-user to provide a working <tt>HELLO</tt>
+ which is then in turn used to call <tt>TRY_CONNECT()</tt> on
+ the underlay in order to trigger a subsequent
+ <tt>PEER_CONNECTED</tt> signal from the underlay
+ interface.
<xref target="hello_url"/> specifies
a URL format for encoding HELLO blocks as text strings. The
URL format thus provides a portable, human-readable,
text-based serialization format that can, for example, be
- encoded into a QR code for dissemination. HELLO URLs
- <bcp14>SHOULD</bcp14> be supported by implementations for
+ encoded into a QR code for dissemination.
+ HELLO URLs <bcp14>SHOULD</bcp14> be supported by implementations for
both import and export of <tt>HELLOs</tt>.
</t>
<t>
@@ -1108,7 +1114,7 @@ BEGIN
rounded probabilistically to the nearest
discrete value, using the fraction
as the probability for rounding up.
- This probabillistic rounding is necessary to achieve
+ This probabilistic rounding is necessary to achieve
the statistically expected value of the replication
level and average number of peers a message is forwarded to.
</t>
@@ -1124,12 +1130,13 @@ BEGIN
towards the key is done hop-by-hop using the routing table and the
query hash. The pending table is used to route responses
back to the originator. In the pending table each peer
- primarily associates a query hash with the associated
+ primarily maps a query hash to the associated
originator of the request. The pending table <bcp14>MUST</bcp14>
store entries for the last <tt>MAX_RECENT</tt> requests
- the peer has encountered. To ensure that the peer does
+ the peer has encountered.
+ To ensure that the peer does
not run out of memory, information about older requests
- is discarded.
+ <bcp14>MAY</bcp14> be discarded.
The value of <tt>MAX_RECENT</tt> <bcp14>MAY</bcp14> be configurable
at the host level to use available memory resources without
conflicting with other system requirements and limitations.
