[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lsd0004] branch master updated (4ad3f38 -> 9019e66)
|
From: |
gnunet |
|
Subject: |
[lsd0004] branch master updated (4ad3f38 -> 9019e66) |
|
Date: |
Mon, 15 Jul 2024 12:39:57 +0200 |
This is an automated email from the git hooks/post-receive script.
martin-schanzenbach pushed a change to branch master
in repository lsd0004.
from 4ad3f38 minor wording fix
new bfc35b9 remove unnecessary emphasis
new 9019e66 more wording and reorder
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
draft-schanzen-r5n.xml | 161 ++++++++++++++++++++++++++-----------------------
1 file changed, 84 insertions(+), 77 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index dc34340..3cd2311 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -261,11 +261,17 @@
It includes logic for enforcing storage quotas, caching strategies and
block validation.
</dd>
- <dt>Block-Type</dt>
+ <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>
@@ -470,15 +476,15 @@
</t>
<ul>
<li>
- <tt>PUT</tt>: This operation stores a <em>block</em>
- under a <em>key</em> on one or more <em>peers</em> with
- the goal of making the <em>block</em> availiable for queries using
the <tt>GET</tt> operation.
+ <tt>PUT</tt>: This operation stores a block
+ under a key on one or more peers with
+ the goal of making the block availiable for queries using the
<tt>GET</tt> operation.
In the classical definition of a dictionary interface, this
operation would be
called "insert".
</li>
<li>
- <tt>GET</tt>: This operation queries the network of peers for any
number of <em>blocks</em>
- previously stored under or near a <em>key</em>.
+ <tt>GET</tt>: This operation queries the network of peers for any
number of blocks
+ previously stored under or near a key.
In the classical definition of a dictionary interface, this
operation would be
called "find".
</li>
@@ -489,11 +495,11 @@
outlined in <xref target="overlay"/>.
</t>
<t>
- A <em>peer</em> does not necessarily need to expose the above
- operations to <em>applications</em>, but it commonly will. A
- <em>peer</em> that does not expose the above operations could
- be a host purely used for <em>bootstrapping</em>,
- <em>routing</em> or supporting
+ A peer does not necessarily need to expose the above
+ operations to applications, but it commonly will. A
+ peer that does not expose the above operations could
+ be a host purely used for bootstrapping,
+ routing or supporting
the overlay network with resources.
</t>
<t>
@@ -502,10 +508,10 @@
data. Examples for such hosts would be mobile devices with
limited bandwidth, battery and storage capacity. Such hosts
may be used to run applications that use the DHT. However, we
- will not refer to such hosts as <em>peers</em>.
+ will not refer to such hosts as peers.
</t>
<t>
- In a trivial scenario where there is only one <em>peer</em> (on the
local host),
+ In a trivial scenario where there is only one peer (on the local host),
R<sup>5</sup>N operates similarly to a dictionary data structure.
However, the default use case is one where nodes communicate directly
and
indirectly in order to realize a distributed storage mechanism.
@@ -525,30 +531,24 @@
<!-- consider moving some of this back into sec considerations -->
<t>
Specifics about the protocols of the underlays implementing
- the <em>underlay interface</em> or the <em>applications</em>
+ the underlay interface or the applications
using the DHT are out of the scope of this document.
</t>
<t>
To establish an initial connection to a network of
R<sup>5</sup>N peers, at least one initial, addressable
- <em>peer</em> is required as part of the
- <em>bootstrapping</em> process. Further <em>peers</em>,
- including <em>neighbors</em>, are then learned via a peer
+ peer is required as part of the
+ bootstrapping process. Further peers,
+ including neighbors, are then learned via a peer
discovery process as defined in <xref target="find_peer"/>.
</t>
<t>
Across this document, the functional components of an
R<sup>5</sup>N implementation are divided into
- <em>routing</em> (<xref target="routing"/>), <em>message
- processing</em> (<xref target="p2p_messages"/>) and
- block processing (<xref target="blockstorage"/>).
- <em>Applications</em> that require application-specific
- <em>block</em> payloads are expected to register a
- <em>Block-Type</em> in the GANA <em>Block-Type</em> 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
+ routing (<xref target="routing"/>), message
+ processing (<xref target="p2p_messages"/>) and
+ 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,14 +589,16 @@ 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 <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>.
+ distribution of address information to other
+ 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
+ underlay understands the respective address.
</t>
<!--
1) The current API is always fire+forget, it doesn't allow for flow
@@ -632,8 +634,8 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<t>
It is expected that the underlay provides basic mechanisms to
manage peer connectivity and addressing.
- The essence of the <em>underlay interface</em> is
- captured by the following set of API calls:
+ The essence of the underlay interface is
+ 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>
@@ -727,7 +729,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
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
+ as a full peer and thus should not be considered
for routing.
</dd>
<dt>
@@ -774,7 +776,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
To enable routing, any R<sup>5</sup>N implementation must keep
information about its current set of neighbors.
Upon receiving a connection notification from the
- <em>underlay interface</em> through a
+ underlay interface through a
<tt>PEER_CONNECTED</tt> signal, information on the new neighbor
<bcp14>MUST</bcp14> be added to the routing table, except if the
respective <tt>k</tt>-bucket in the routing table is full or if
meta-data
@@ -792,7 +794,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
the data structure for managing neighbors and their
metadata <bcp14>MUST</bcp14> be implemented using the k-buckets
concept of
<xref target="Kademlia"/> as defined in <xref
target="routing_table"/>.
- Maintenance of the routing table (after <em>bootstrapping</em>) is
+ Maintenance of the routing table (after bootstrapping) is
described in <xref target="find_peer"/>.
</t>
<t>
@@ -826,17 +828,17 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
the underlay, the respective peer is considered for
insertion into the routing table. The routing table
consists of an array of <tt>k</tt>-buckets. Each
- <tt>k</tt>-bucket contains a list of <em>neighbors</em>.
+ <tt>k</tt>-bucket contains a list of neighbors.
The i-th <tt>k</tt>-bucket stores neighbors whose peer
public keys are between XOR-distance 2<sup>i</sup> and
2<sup>i+1</sup> from the local peer; <tt>i</tt> can be
directly computed from the two peer identities using the
<tt>GetDistance()</tt> function. System constraints will
typically force an implementation to impose some upper limit
- on the number of <em>neighbors</em> kept per
+ on the number of neighbors kept per
<tt>k</tt>-bucket. Upon insertion, the implementation
<bcp14>MUST</bcp14> call <tt>HOLD()</tt> on the respective
- <em>neighor</em>.
+ neighor.
</t>
<t>
Implementations <bcp14>SHOULD</bcp14> try to keep at least
@@ -851,42 +853,46 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<t>
If a system hits constraints with respect to
the number of active connections, an implementation
- <bcp14>MUST</bcp14> evict <em>neighbours</em> from those
<tt>k</tt>-buckets with the
+ <bcp14>MUST</bcp14> evict neighbours from those <tt>k</tt>-buckets
with the
largest number of neighbors. The eviction strategy
<bcp14>MUST</bcp14> be
to drop the shortest-lived connection per <tt>k</tt>-bucket first.
</t>
<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>
+ Implementations <bcp14>MAY</bcp14> cache valid addresses of
disconnected
+ peers outside of the routing table and sporadically or periodically
try to (re-)establish connection
+ to the peer by making <tt>TRY_CONNECT()</tt> calls to the underlay
interface
if the respective <tt>k</tt>-bucket has empty slots.
</t>
</section>
<section anchor="find_peer">
<name>Peer Discovery</name>
<t>
- Initially, implementations depend upon either the underlay
- providing at least one initial connection to a
- <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
- 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
- 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
+ Initially, implementations require at least one initial connection
to a
+ neighbor (signalled through
+ <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>
@@ -899,7 +905,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
<bcp14>MUST</bcp14> be
initialized to filter the peer's own peer identity as well as the
peer
identities of all currently connected
- <em>neighbors</em>. These requests <bcp14>MUST</bcp14> use
+ neighbors. These requests <bcp14>MUST</bcp14> use
the <tt>FindApproximate</tt> and
<tt>DemultiplexEverywhere</tt>
flags. <tt>FindApproximate</tt> will ensure that other peers
@@ -922,7 +928,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
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>HelloMessages</tt>. The
+ its neighbors through <tt>HelloMessages</tt>. The
advertisement interval and expiration <bcp14>SHOULD</bcp14>
be configurable.
If the values are chosen at the discretion of the
@@ -1075,7 +1081,7 @@ Connectivity | |Underlay| |Underlay| | Underlay | ...
</dt>
<dd>
<t>
- This function computes the number of <em>neighbors</em>
+ This function computes the number of neighbors
that a message should be forwarded to. The arguments
are the desired replication level (<tt>REPL_LVL</tt>),
the <tt>HOPCOUNT</tt> of the message so far and
@@ -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.
@@ -1179,13 +1186,13 @@ BEGIN
An implementation will process
messages either because it needs to transmit messages as part of
routing
table maintenance, or due to requests from local applications, or
- because it received a message from a <em>neighbor</em>.
+ because it received a message from a neighbor.
If instructed through an application-facing API such as the one
outlined
- in <xref target="overlay"/>, a peer acts as an <em>initiator</em>
+ in <xref target="overlay"/>, a peer acts as an initiator
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>.
+ due to the required handover of results to the originating application.
</t>
<t>
The implementation <bcp14>MUST</bcp14> listen for <tt>RECEIVE(P,
M)</tt> signals
@@ -1228,7 +1235,7 @@ BEGIN
</dd>
<dt>2: FindApproximate</dt>
<dd>
- This bit asks peers to return results even if the <em>key</em>
+ This bit asks peers to return results even if the key
does not exactly match the query hash.
</dd>
<dt>3: Truncated</dt>
@@ -3599,12 +3606,12 @@ bchar = *(ALPHA / DIGIT)
</artwork>
</figure>
<t>
- It specifies that the peer with the <em>pid</em> "1MVZ..."
+ It specifies that the peer with the <tt>pid</tt> "1MVZ..."
is reachable via "foo" at "example.com" and "bar+baz" at
"1.2.3.4" on port 5678 until
1708333757 seconds after the Epoch. Note that "foo"
and "bar+baz" here are underspecified and just used as a simple
example.
- In practice, the <em>addr-name</em> refers to a scheme supported by a
+ In practice, the <tt>addr-name</tt> refers to a scheme supported by a
DHT underlay.
</t>
</section>
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [lsd0004] branch master updated (4ad3f38 -> 9019e66),
gnunet <=