commit b396a9e51a1c3650c7cda056d6dd01b61b35a095
parent f4f4afaca956c4c15c536a62dc41bf160feb0a99
Author: Christian Grothoff <christian@grothoff.org>
Date: Sat, 13 Jul 2024 09:17:01 +0200
English improvements, consistency fixes
Diffstat:
1 file changed, 72 insertions(+), 67 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -294,7 +294,7 @@
</dd>
<dt>Key</dt>
<dd>
- 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
+ 512-bit identifier of a location in the DHT. Multiple <tt>Blocks</tt> can be
stored under the same <em>key</em>. A <em>peer identity</em> is also a <tt>key</tt>.
In the context of "key-value stores" this
refers to "key" under which values (<em>blocks</em>) are stored.
@@ -782,7 +782,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
is present that indicates that the peer does not wish to participate
in routing.
Peers added to the routing table <bcp14>SHOULD</bcp14> be signalled to the
- underlay as important connections using a <tt>HOLD</tt> call.
+ underlay as important connections using a <tt>HOLD()</tt> call.
Similarly when a disconnect is indicated by the underlay through
a <tt>PEER_DISCONNECTED</tt> signal, the peer
<bcp14>MUST</bcp14> be removed from the routing table.
@@ -836,7 +836,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
typically force an implementation to impose some upper limit
on the number of <em>neighbors</em> kept per
<tt>k</tt>-bucket. Upon insertion, the implementation
- <bcp14>MUST</bcp14> call <tt>HOLD</tt> on the respective
+ <bcp14>MUST</bcp14> call <tt>HOLD()</tt> on the respective
<em>neighor</em>.
</t>
<t>
@@ -859,7 +859,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<t>
Implementations <bcp14>MAY</bcp14> cache valid <em>addresses</em> of disconnected
<em>peers</em> outside of the routing table and sporadically or periodically try to (re-)establish connection
- to the <em>peer</em> by making <tt>TRY_CONNECT</tt> calls to the <em>underlay interface</em>
+ to the <em>peer</em> by making <tt>TRY_CONNECT()</tt> calls to the <em>underlay interface</em>
if the respective <tt>k</tt>-bucket has empty slots.
</t>
</section>
@@ -871,7 +871,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<em>neighbor</em> (signalled through
<tt>PEER_CONNECTED</tt>), or the <em>application</em> 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
+ 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 <em>underlay
interface</em>. This is commonly achieved through the
@@ -887,7 +887,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
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
- both import and export of <tt>HELLO</tt>s.
+ both import and export of <tt>HELLOs</tt>.
</t>
<t>
To discover additional peers for its routing table, a peer
@@ -906,7 +906,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
close-enough, while <tt>DemultiplexEverywhere</tt> will
cause each peer on the path to respond if it has relevant
information. The combination of these flags is thus likely
- to yield <tt>HELLO</tt>s of peers that are useful somewhere
+ to yield <tt>HELLOs</tt> of peers that are useful somewhere
in the initiator's routing table. The <tt>RECOMMENDED</tt>
replication level to be set in the <tt>REPL_LVL</tt> field
is 4. The size and format of the result filter is specified
@@ -915,13 +915,13 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
</t>
<t>
In order to facilitate peers answering requests for
- <tt>HELLO</tt>s, the underlay is expected to provide the
+ <tt>HELLOs</tt>, the underlay is expected to provide the
implementation with one or more addresses signalled through
<tt>ADDRESS_ADDED</tt>. Zero addresses <bcp14>MAY</bcp14> be
provided if a peer can only establish outgoing connections
and is otherwise unreachable. An implementation
<bcp14>MUST</bcp14> advertise its addresses periodically to
- its <em>neighbors</em> through <tt>HelloMessage</tt>s. The
+ its <em>neighbors</em> through <tt>HelloMessages</tt>. The
advertisement interval and expiration <bcp14>SHOULD</bcp14>
be configurable or chosen at the discretion of the
implementation based on external factors such as expiration
@@ -944,7 +944,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<section anchor="routing_bloomfilter">
<name>Peer Bloom Filter</name>
<t>
- As DHT <tt>GetMessage</tt>s and <tt>PutMessage</tt>s
+ As DHT <tt>GetMessages</tt> and <tt>PutMessages</tt>
traverse a random path through the network for the first
<tt>L2NSE</tt> hops, a key design objective of
R<sup>5</sup>N is to avoid routing loops. The peer Bloom
@@ -967,7 +967,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
peer selection process.
</t>
<t>
- Any peer which is forwarding <tt>GetMessage</tt>s or <tt>PutMessage</tt>s
+ Any peer which is forwarding <tt>GetMessages</tt> or <tt>PutMessages</tt>
(<xref target="p2p_messages"/>) thus adds its own peer public key to the
peer Bloom filter.
This allows other peers to (probabilistically) exclude already
@@ -1152,8 +1152,8 @@ BEGIN
because it received a message from a <em>neighbor</em>.
If instructed through an application-facing API such as the one outlined
in <xref target="overlay"/>, a peer acts as an <em>initiator</em>
- of <tt>GetMessage</tt>s
- or <tt>PutMessage</tt>s.
+ of <tt>GetMessages</tt>
+ or <tt>PutMessages</tt>.
The status of initiator is relevant for peers when processing <tt>ResultMessages</tt>
due to the required handover of results to the originating <em>application</em>.
</t>
@@ -1188,8 +1188,8 @@ BEGIN
If the bit is not set, intermediate peers only route the message and only
peers which consider themselves closest to the key (based on their
routing table) look for answers
- in their local storage for <tt>GetMessage</tt>s, or respectively cache the
- block in their local storage for <tt>PutMessage</tt>s and <tt>ResultMessage</tt>s.
+ in their local storage for <tt>GetMessages</tt>, or respectively cache the
+ block in their local storage for <tt>PutMessages</tt> and <tt>ResultMessages</tt>.
</dd>
<dt>1: RecordRoute</dt>
<dd>
@@ -1264,7 +1264,7 @@ BEGIN
</dl>
<t>
An ordered list of path elements may be appended to any routed
- <tt>PutMessage</tt>s or <tt>ResultMessage</tt>s.
+ <tt>PutMessages</tt> or <tt>ResultMessages</tt>.
The last signature (after which the peer public key is omitted)
is created by the current hop only after the peer made its routing
decision identifiying the successor peer. The peer public key is not
@@ -1477,18 +1477,18 @@ BEGIN
<section anchor="p2p_hello" numbered="true" toc="default">
<name>HelloMessage</name>
<t>
- When the underlay signals the implementation of added or removed
- addresses through <tt>ADDRESS_ADDED</tt> and <tt>ADDRESS_DELETED</tt>
- an implementation <bcp14>MAY</bcp14> disseminate those changes to neighbors using
- <tt>HelloMessage</tt>s.
- Initiation of such <tt>HelloMessages</tt> by the implementation itself is <bcp14>RECOMMENDED</bcp14>.
- <tt>HelloMessage</tt>s are used to inform neighbors of
- a peer about the sender's available addresses. The
- recipients use these messages to inform their respective
- underlays about ways to sustain the connections and to
- generate <tt>HELLO</tt> blocks (see <xref target="hello_block"/>)
- to answer peer discovery queries
- from other peers.
+ When the underlay signals the implementation of added or
+ removed addresses through <tt>ADDRESS_ADDED</tt> and
+ <tt>ADDRESS_DELETED</tt> an implementation
+ <bcp14>MUST</bcp14> disseminate those changes to neighbors
+ using <tt>HelloMessages</tt> (as already discussed in
+ section <xref target="find_peer"/>). <tt>HelloMessages</tt>
+ are used to inform neighbors of a peer about the sender's
+ available addresses. The recipients use these messages to
+ inform their respective underlays about ways to sustain the
+ connections and to generate <tt>HELLO</tt> blocks (see <xref
+ target="hello_block"/>) to answer peer discovery queries
+ from other peers.
</t>
<section anchor="p2p_hello_wire">
<name>Wire Format</name>
@@ -1496,14 +1496,14 @@ BEGIN
<artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
-| MSIZE | MTYPE | VERSION | NUM_ADDRS |
+| MSIZE | MTYPE | VERSION | NUM_ADDRS |
+-----+-----+-----+-----+-----+-----+-----+-----+
| SIGNATURE /
/ (64 bytes) |
+-----+-----+-----+-----+-----+-----+-----+-----+
| EXPIRATION |
+-----+-----+-----+-----+-----+-----+-----+-----+
-/ ADDRESSES (variable length) /
+/ ADDRESSES (variable length) /
+-----+-----+-----+-----+-----+-----+-----+-----+
]]></artwork>
</figure>
@@ -1517,7 +1517,8 @@ BEGIN
<dd>
is the 16-bit message type.
It must be set to
- the value 157 in network byte order as defined in the GANA "GNUnet Message Type" registry <xref target="gana_message_type"/>.
+ the value 157 in network byte order as defined in the GANA "GNUnet Message Type" registry
+ (see <xref target="gana_message_type"/>).
</dd>
<dt>VERSION</dt>
<dd>
@@ -1547,9 +1548,8 @@ BEGIN
</dd>
<dt>ADDRESSES</dt>
<dd>
- A sequence of exactly NUM_ADDRS
- addresses (<xref target="terminology"/>)
- which can be used to contact the peer.
+ A sequence of exactly <tt>NUM_ADDRS</tt>
+ addresses which can be used to contact the peer.
Each address <bcp14>MUST</bcp14> be 0-terminated.
The set of addresses <bcp14>MAY</bcp14> be empty.
</dd>
@@ -1560,33 +1560,37 @@ BEGIN
<t>
If the initiator of a <tt>HelloMessage</tt> is <tt>SELF</tt>, the message
is simply sent to all neighbors <tt>P</tt> currently in the routing table
- using <tt>SEND</tt>.
+ using the <tt>SEND()</tt> function of the underlay as defined in
+ <xref target="underlay"/>.
</t>
<t>
- Otherwise, upon receiving a <tt>HelloMessage</tt> from a peer <tt>P</tt>
+ Upon receiving a <tt>HelloMessage</tt> from a peer <tt>P</tt>
an implementation <bcp14>MUST</bcp14> process it step by step as follows:
</t>
<ol>
<li>
- If <tt>P</tt> is not in its routing table, the message
- is discarded.
+ If <tt>P</tt> is not in its routing table, the message is discarded.
</li>
<li>
The signature is verified, including a check that the expiration time
is in the future. If the signature is invalid, the message is discarded.
</li>
<li>
- The information contained in the <tt>HelloMessage</tt> can be used to synthesize a
- block of type <tt>HELLO</tt> (<xref target="hello_block"/>).
- The block is cached in the routing table until it expires,
- the peer is removed from the routing table, or the information is replaced by another message
- from the peer.
- The implementation <bcp14>SHOULD</bcp14> instruct the underlay to connect to all now available addresses
- using <tt>TRY_CONNECT</tt> in order to make the underlay aware of alternative addresses for this connection and
+ The information contained in the <tt>HelloMessage</tt>
+ is used to synthesize a block of type <tt>HELLO</tt>
+ (<xref target="hello_block"/>). The block is cached in
+ the routing table until it expires, or the peer is
+ removed from the routing table, or the information is
+ replaced by another message from the peer. The
+ implementation <bcp14>SHOULD</bcp14> instruct the
+ underlay to connect to all now available addresses using
+ <tt>TRY_CONNECT()</tt> in order to make the underlay
+ aware of alternative addresses for this connection and
to maintain optimal connectivity.
</li>
<li>
- Received <tt>HelloMessages</tt> <bcp14>MUST NOT</bcp14> be forwarded.
+ Received <tt>HelloMessages</tt> <bcp14>MUST NOT</bcp14>
+ be forwarded.
</li>
</ol>
</section>
@@ -1594,13 +1598,14 @@ BEGIN
<section anchor="p2p_put" numbered="true" toc="default">
<name>PutMessage</name>
<t>
- <tt>PutMessage</tt>s are used to store information at other peers in the DHT.
- Any API which allows applications to initiate <tt>PutMessage</tt>s needs to
- provide sufficient, implementation-specific information to construct
- the initial <tt>PutMessage</tt>.
- For example, implementations supporting multiple applications and blocks will
- have block type and message flag parameters in addition to the actual data
- payload and key.
+ <tt>PutMessages</tt> are used to store information at other
+ peers in the DHT. Any API which allows applications to
+ initiate <tt>PutMessages</tt> needs to provide sufficient,
+ implementation-specific information to construct the initial
+ <tt>PutMessage</tt>. For example, implementations
+ supporting multiple applications and blocks will have block
+ type and message flag parameters in addition to the actual
+ data payload and key.
</t>
<section anchor="p2p_put_wire">
<name>Wire Format</name>
@@ -1810,9 +1815,9 @@ BEGIN
not already full the peer <bcp14>MUST</bcp14> try to establish a
connection to the peer indicated in the <tt>HELLO</tt> block using
the address information
- from the <tt>HELLO</tt> block and the underlay function <tt>TRY_CONNECT</tt>.
+ from the <tt>HELLO</tt> block and the underlay's <tt>TRY_CONNECT()</tt> function.
The implementation <bcp14>MUST</bcp14> instruct the underlay to try to connect to all
- provided addresses using <tt>TRY_CONNECT</tt> in order to make the underlay aware of
+ provided addresses using <tt>TRY_CONNECT()</tt> in order to make the underlay aware of
multiple addresses for this connection.
When a connection is established, the signal <tt>PEER_CONNECTED</tt> will cause
the peer to be added to the respective k-bucket of the routing table (<xref target="routing"/>).
@@ -1848,8 +1853,8 @@ BEGIN
<section anchor="p2p_get" numbered="true" toc="default">
<name>GetMessage</name>
<t>
- <tt>GetMessage</tt>s are used to request information from other peers in the DHT.
- Any overlay API which allows applications to initiate <tt>GetMessage</tt>s needs to provide
+ <tt>GetMessages</tt> are used to request information from other peers in the DHT.
+ Any overlay API which allows applications to initiate <tt>GetMessages</tt> needs to provide
sufficient, implementation-specific information needed to construct the initial <tt>GetMessage</tt>.
For example, implementations supporting multiple applications and blocks will have block type and
message flag parameters.
@@ -1959,7 +1964,7 @@ BEGIN
The result filter is used to indicate to other peers which results
are not of interest when processing a <tt>GetMessage</tt>
(<xref target="p2p_get"/>).
- Any peer which is processing <tt>GetMessage</tt>s and has a result
+ Any peer which is processing <tt>GetMessages</tt> and has a result
which matches the query key <bcp14>MUST</bcp14> check the result filter
and only send a reply message if the result does not test positive
under the result filter. Before forwarding the <tt>GetMessage</tt>, the
@@ -2023,7 +2028,7 @@ BEGIN
Otherwise, if the <tt>BTYPE</tt> does not indicate a request for a <tt>HELLO</tt> block or
<tt>ANY</tt>,
the implementation <bcp14>MUST</bcp14> only consider blocks in the local block storage
- and previously cached <tt>ResultMessage</tt>s.
+ and previously cached <tt>ResultMessages</tt>.
</li>
<li>
If the <tt>FLAGS</tt> field includes the flag <tt>FindApproximate</tt>,
@@ -2043,7 +2048,7 @@ BEGIN
</ol>
<t>
Implementations <bcp14>MAY</bcp14> not reply if they are resource-constrained.
- However, <tt>ResultMessage</tt>s <bcp14>MUST</bcp14> be given the
+ However, <tt>ResultMessages</tt> <bcp14>MUST</bcp14> be given the
highest priority among competing transmissions.
</t>
<t>
@@ -2086,7 +2091,7 @@ BEGIN
<section anchor="p2p_result" numbered="true" toc="default">
<name>ResultMessage</name>
<t>
- <tt>ResultMessage</tt>s are used to return information to other peers in the DHT
+ <tt>ResultMessages</tt> are used to return information to other peers in the DHT
or to applications using the overlay API that previously initiated a <tt>GetMessage</tt>.
The initiator of a <tt>ResultMessage</tt> is a peer triggered through the processing
of a <tt>GetMessage</tt>.
@@ -2290,9 +2295,9 @@ BEGIN
because the routing table or the respective k-bucket is already full.
If the peer is a suitable candidate for insertion, the local peer <bcp14>MUST</bcp14> try to establish a connection
to the peer indicated in the <tt>HELLO</tt> block using the address information
- from the <tt>HELLO</tt> block and the underlay function <tt>TRY_CONNECT</tt>.
+ from the <tt>HELLO</tt> block and the underlay's <tt>TRY_CONNECT()</tt> function.
The implementation <bcp14>MUST</bcp14> instruct the underlay to connect to all provided addresses
- using <tt>TRY_CONNECT</tt> in order to make the underlay aware of multiple addresses for this connection.
+ using <tt>TRY_CONNECT()</tt> in order to make the underlay aware of multiple addresses for this connection.
When a connection is established, the signal <tt>PEER_CONNECTED</tt> will cause
the peer to be added to the respective k-bucket of the routing table (<xref target="routing"/>).
</li>
@@ -2349,10 +2354,10 @@ BEGIN
</li>
<li>
Finally, the implementation <bcp14>SHOULD</bcp14> cache
- <tt>ResultMessage</tt>s in order to provide already seen replies to
- future <tt>GetMessage</tt>s.
+ <tt>ResultMessages</tt> in order to provide already seen replies to
+ future <tt>GetMessages</tt>.
The implementation <bcp14>MAY</bcp14> choose not no cache any or
- a limited number of <tt>ResultMessage</tt>s for reasons such as resource
+ a limited number of <tt>ResultMessages</tt> for reasons such as resource
limitations.
</li>
</ol>
@@ -2373,7 +2378,7 @@ BEGIN
<t>
Applications can and should define their own block types.
The block type determines the format and handling of the block
- payload by peers in <tt>PutMessage</tt>s and <tt>ResultMessage</tt>s.
+ payload by peers in <tt>PutMessages</tt> and <tt>ResultMessages</tt>.
Block types <bcp14>MUST</bcp14> be registered with GANA
(see <xref target="gana_block_type"/>).
</t>
