commit aa55c2cbde372b3367b2d1bad38be5da547848e7
parent 6ff1319b86a1b30bae471349dac4047485f1be44
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 11 Jan 2022 21:47:17 +0100
minor
Diffstat:
1 file changed, 116 insertions(+), 96 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -162,21 +162,24 @@
<section>
<name>Terminology</name>
<dl>
- <dt>Node:</dt>
+ <dt>Peer:</dt>
<dd>
- A node is participant in the network and addressable through the
- network overlay.
+ A host that is participating in the overlay. Peers are
+ responsible for holding some portion of the data that has been
+ stored in the overlay, and they are responsible for routing
+ messages on behalf of other hosts as needed by the Routing
+ Algorithm.
</dd>
- <dt>Node Address:</dt>
+ <dt>Peer Key:</dt>
<dd>
- The <tt>Node Address</tt> is the identifier used on the Overlay
- to address a node.
+ The <tt>Peer Key</tt> is the identifier used on the Overlay
+ to address a peer.
</dd>
- <dt>Node ID:</dt>
+ <dt>Peer ID:</dt>
<dd>
- The <tt>Node ID</tt> is the identity which is used to authenticate
- a node in the underlay.
- The <tt>Node Address</tt> is derived from the <tt>Node ID</tt>.
+ The <tt>Peer ID</tt> is the identity which is used to authenticate
+ a peer in the underlay.
+ The <tt>Peer Address</tt> is derived from the <tt>Peer ID</tt>.
</dd>
<dt>Neighbour:</dt>
<dd>
@@ -184,6 +187,54 @@
</dd>
<dt>Block:</dt>
<dd>
+ An object or group of objects stored in the DHT.
+ </dd>
+ <dt>Block-Type:</dt>
+ <dd>
+ A unique 32-bit value identifying a block type.
+ Block-Types are either private or allocated by GANA (see <xref target="gana"/>).
+ </dd>
+ <dt>Block Storage</dt>
+ <dd>
+ The Block Storage component is used to persist and manage data
+ by nodes. It includes logic for quotas, caching stragegies and
+ data validation.
+ </dd>
+ <dt>Responsible Peer:</dt>
+ <dd>
+ The peer <tt>N</tt> that is responsible for a specific resource <tt>K</tt>, as defined by
+ the <tt>SelectClosestNode(K, N)</tt> algorithm (see <xref target="routing"/>.
+ </dd>
+ <dt>Applications</dt>
+ <dd>
+ Applications are components which directly use the DHT overlay
+ interfaces. Possible applications include the GNU Name System
+ <xref target="I-D.draft-schanzen-gns"/> or the CADET transport system
+ <xref target="cadet"/>.
+ </dd>
+ <dt>Overlay Interface</dt>
+ <dd>
+ The Overlay Interface exposes the core operations of the DHT overlay
+ to applications.
+ This includes querying and retrieving data from the DHT.
+ </dd>
+ <dt>Message Processing</dt>
+ <dd>
+ The Message Processing component processes requests from and responses
+ to applications as well as messages from the underlay network.
+ </dd>
+ <dt>Routing</dt>
+ <dd>
+ The Routing component includes the routing table as well as
+ routing and node selection logic. It facilitates the R5N routing
+ algorithm with required data structures and algorithms.
+ </dd>
+ <dt>Underlay Interface</dt>
+ <dd>
+ The DHT Underlay Interface is an abstraction layer on top of the
+ supported links of a node. Nodes may be linked by a variety of
+ different transports, including "classical" protocols such as
+ TCP, UDP and TLS or advanced protocols such as GNUnet, L2P or Tor.
</dd>
</dl>
</section>
@@ -219,45 +270,6 @@ Connectivity | |Underlay| |Underlay|
]]>
</artwork>
</figure>
- <dl>
- <dt>Applications</dt>
- <dd>
- Applications are components which directly use the DHT overlay
- interfaces. Possible applications include the GNU Name System
- <xref target="I-D.draft-schanzen-gns"/> or the CADET transport system
- <xref target="cadet"/>.
- </dd>
- <dt>Overlay Interface</dt>
- <dd>
- The Overlay Interface exposes the core operations of the DHT overlay
- to applications.
- This includes querying and retrieving data from the DHT.
- </dd>
- <dt>Block Storage</dt>
- <dd>
- The Block Storage component is used to persist and manage data
- by nodes. It includes logic for quotas, caching stragegies and
- data validation.
- </dd>
- <dt>Message Processing</dt>
- <dd>
- The Message Processing component processes requests from and responses
- to applications as well as messages from the underlay network.
- </dd>
- <dt>Routing</dt>
- <dd>
- The Routing component includes the routing table as well as
- routing and node selection logic. It facilitates the R5N routing
- algorithm with required data structures and algorithms.
- </dd>
- <dt>Underlay Interface</dt>
- <dd>
- The DHT Underlay Interface is an abstraction layer on top of the
- supported links of a node. Nodes may be linked by a variety of
- different transports, including "classical" protocols such as
- TCP, UDP and TLS or advanced protocols such as GNUnet, L2P or Tor.
- </dd>
- </dl>
<t>
Other glossary
</t>
@@ -273,69 +285,53 @@ Connectivity | |Underlay| |Underlay|
Ed25519<xref target="ed25519" /> node private key.
</t>
<t>
- Any implementation of this specification MUST expose the two API
+ An implementation of this specification commonly exposes the two API
procedures "GET" and "PUT".
+ The following are non-normative examples of such APIs and their
+ behaviour are detailed in order to give implementers a fuller picture of the protocol.
</t>
<section>
<name>The GET procedure</name>
<t>
- The GET procedure is defined as follows:
+ A basic GET procedure may be exposed as:
</t>
<t>
- <tt>GET(Key[, GetParams]) -> Results as List</tt>
+ <tt>GET(QueryKey) -> Results as List</tt>
</t>
<t>
- The procedure takes a single additional <tt>QueryParams</tt>
- argument in order to specify detailed query parameters.
- The <tt>GetParams</tt> consist of the following parameters:
+ The procedure takes a single inputargument : The <tt>QueryKey</tt>.
+ It initiates a lookup for this key in the DHT and - if the procedure
+ is implemented synchronuously - returns a list of results.
+ The procedure may allow a set of optional parameters in order to
+ control or modify the query:
</t>
<dl>
- <dt>BlockType</dt>
+ <dt>Block-Type:</dt>
<dd>
- The default setting of this parameter is to request any type of
- block types under the key.
+ The type of block to look for.
</dd>
- <dt>ReplicationLevel</dt>
- <dd>The default setting of this parameter is X (FIXME).</dd>
- <dt>RouteOptions</dt>
+ <dt>Replication-Level:</dt>
<dd>
- are used in order to indicate certain
+ An integer which controls how many nearest peers the request
+ should reach.
+ </dd>
+ <dt>Route-Options</dt>
+ <dd>
+ Flags that are used in order to indicate certain
processing requirements for messages.
Any combination of options as defined in <xref target="route_options"/>
- may be specificied.
- The default setting of this parameter is that no option is set.
+ may be specified.
</dd>
<dt>XQuery</dt>
<dd>
is extended query medatadata which may be
- required depending on the respective <tt>BlockType</tt>.
- A <tt>BlockType</tt> must define if the <tt>XQuery</tt> can or must
+ required depending on the respective <tt>Block-Type</tt>.
+ A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
be used and what the specific format of its contents should be.
See also <xref target="block_types"/>.
- The default setting of this parameter is empty.
- </dd>
- </dl>
- <t>
- The <tt>RouteOptions</tt> consist of the following flags:
- </t>
- <dl anchor="route_options">
- <dt>DemultiplexEverywhere</dt>
- <dd>
- indicates that each node along the way should process the request.
- </dd>
- <dt>RecordRoute</dt>
- <dd>
- indicates to keep track of the route that the message takes
- in the P2P network.
- </dd>
- <dt>FindNode</dt>
- <dd>
- indicates that this is a request used to find additional nodes.
- This is a special flag which modifies the message processing to
- allow approximate results.
</dd>
</dl>
- <t>
+ <t>
As the time it takes for results to arrive may vary an implementation
may either return a list of results after a timeout or allow the
caller to provide a callback function which is called for any result
@@ -417,6 +413,7 @@ Connectivity | |Underlay| |Underlay|
The required functionality are abstracted through the following
procedures and events:
</t>
+ <!-- FIXME separate procedures from events -->
<dl>
<dt>
<tt>PEER_CONNECTED(P)</tt>
@@ -501,12 +498,6 @@ Connectivity | |Underlay| |Underlay|
This information is used, for example, to no longer advertise
this address.
</dd>
- <dt>
- <tt>VERIFY(blob)</tt>
- </dt>
- <dd>
- Signature verification by underlay. FIXME unclear. Required?
- </dd>
</dl>
</section>
<section>
@@ -656,6 +647,28 @@ Connectivity | |Underlay| |Underlay|
processing are detailed.
The local node address is referred to as <tt>N</tt>.
</t>
+ <section anchor="route_options">
+ <name>Route Options</name>
+ <t>
+ The <tt>RouteOptions</tt> consist of the following flags:
+ </t>
+ <dl>
+ <dt>Demultiplex-Everywhere</dt>
+ <dd>
+ indicates that each node along the way should process the request.
+ </dd>
+ <dt>Record-Route</dt>
+ <dd>
+ indicates to keep track of the route that the message takes
+ in the P2P network.
+ </dd>
+ <dt>Allow-Approximate</dt>
+ <dd>
+ This is a special flag which modifies the message processing to
+ allow approximate results.
+ </dd>
+ </dl>
+ </section>
<section anchor="p2p_bf" numbered="true" toc="default">
<name>Bloomfilter</name>
<t>
@@ -1221,8 +1234,8 @@ Connectivity | |Underlay| |Underlay|
<artwork name="" type="" align="left" alt=""><