commit a1beda531e0f6d6e138d5a14cf774ee933f2b32a
parent cd8c94da90d6a8bea1aa8187c4f32e2fbc50b88f
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Fri, 23 Dec 2022 19:13:06 +0900
Rewrite architecture and structure into an overview
Diffstat:
1 file changed, 65 insertions(+), 40 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -254,39 +254,75 @@
</dl>
</section>
<section>
- <name>Structure of This Document</name>
+ <name>Overview</name>
<t>
- <xref target="terminology"/> gives an overview of the terminology used in
- this document.
- <xref target="architecture"/> then describes the overall architecture and
- the scope of this specification.
- <xref target="overlay"/> describes the application API, which clarifies
- the semantics provided by R<sup>5</sup>N for applications
- and thus is crucial as it motivates the rest of the design.
- <xref target="underlay"/> describes the underlay interface. This is the
- abstraction that applications must provide to R<sup>5</sup>N
- and thus a prerequisite for using the DHT.
- Before a DHT is usable, it must be bootstrapped.
- Bootstrapping is described in <xref target="bootstrapping"/>.
- Bloom filters, a key data structure used in various
- places, are introduced in <xref target="bloom_filters" />
- The central operation of a DHT is routing, which is
- detailed in <xref target="routing"/>. The processing of the various
- network messages is described in <xref target="p2p_messages"/>. Handling
- of Blocks, including validation and storage are described
- in <xref target="blockstorage"/>. General security considerations are detailed
- in <xref target="security" />. IANA and GANA registry updates are listed
- in <xref target="iana" /> and <xref target="gana"/>. The document concludes with test
- vectors in <xref target="testvectors"/> and appendices with references.
+ In R<sup>5</sup>N peers communicate with each other in order to realize and
+ maintain two basic operations of a distributed hash table:
</t>
- </section>
- <section anchor="architecture" numbered="true" toc="default">
- <name>Architecture</name>
+ <ul>
+ <li>
+ PUT: This operation stores a block payload on one or more peers with
+ the goal of making the block availiable for queries using the GET operation.
+ In the classical definition of a dictionary interface, this operation would be
+ called "insert".
+ </li>
+ <li>
+ GET: This operation queries the network of peers for blocks
+ previously stored under or near the key.
+ In the classical definition of a dictionary interface, this operation would be
+ called "find".
+ </li>
+ </ul>
+ <t>
+ The specific semantics of the above operations as provided by R<sup>5</sup>N
+ for applications are defined in <xref target="overlay"/>.
+ The handling of blocks and their validation and storage is defined in
+ <xref target="blockstorage".
+ </t>
+ <t>
+ In a trivial scenario where there is only one peer (the local host),
+ R<sup>5</sup>N operates in a very similar fashion 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.
+ This communication requires a lower-level peer addressing and message transport
+ mechanism such as TCP/IP.
+ R<sup>5</sup>N is agnostic to the underlying transport protocol which is why
+ this document defines a common addressing and messaging interface in
+ <xref target="underlay"/>.
+ The interface provided by this underlay is used across the specification of the
+ R<sup>5</sup>N protocol.
+ It also serves as a set of requirements of possible transport mechanism that
+ can be used to implement R<sup>5</sup>N on.
+ That being said, common transport protocols such as TCP/IP or UDP/IP are
+ supported.
+ </t>
+ <!-- consider moving some of this back into sec considerations -->
<t>
- R<sup>5</sup>N is an overlay network with a pluggable transport layer.
- The following figure shows the R<sup>5</sup>N architecture.
+ Specifics about the protocols of the underlays providing
+ connectivity or the applications using the DHT are out of
+ the scope of this document. However, we note that peers
+ implementing disjoint sets of underlay protocols may
+ experience difficulties communicating (unless other peers
+ bridge the respective underlays). Similarly, peers that
+ do not support a particular application will not be able
+ to validate application-specific payloads and may thus be
+ tricked into storing or forwarding corrupt blocks.
</t>
- <figure title="The R5N Architecture.">
+ <t>
+ In order to establish an initial connection to a network of R<sup>5</sup>N
+ peers, an initial, addressable bootstrap peer is required.
+ Further peers, including neighbors, are then learned via a bootstrapping
+ process as defined in <xref target="bootstrapping"/>.
+ </t>
+ <t>
+ Across this document, the functional components of an R<sup>5</sup>N
+ implementation are divided into block processing (<xref target="blockstorage"),
+ message processing (<xref target="p2p_messages") and routing
+ (<xref target="routing").
+ <xref taget="figure_r5n_arch" illustrates the architectural overview of
+ R<sup>5</sup>N.
+ </t>
+ <figure anchor="figure_r5n_arch" title="The R5N architecture.">
<artwork><![CDATA[
| +-----------------+ +-------+
Applications | | GNU Name System | | CADET | ...
@@ -312,17 +348,6 @@ Connectivity | |Underlay| |Underlay|
]]>
</artwork>
</figure>
- <t>
- Specifics about the protocols of the underlays providing
- connectivity or the applications using the DHT are out of
- the scope of this document. However, we note that peers
- implementing disjoint sets of underlay protocols may
- experience difficulties communicating (unless other peers
- bridge the respective underlays). Similarly, peers that
- do not support a particular application will not be able
- to validate application-specific payloads and may thus be
- tricked into storing or forwarding corrupt blocks.
- </t>
</section>
<section anchor="overlay" numbered="true" toc="default">
<name>Application API</name>
