commit 9346b9b61174f9b61e86cc5db2cad1e18bf86ffc
parent f938cdfbd3be80aba346a462e8a0ce6b3f244035
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Fri, 24 Dec 2021 12:28:07 +0100
some message processing with FIXMEs
Diffstat:
1 file changed, 292 insertions(+), 127 deletions(-)
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
@@ -586,6 +586,8 @@ END
</section>
<section anchor="p2p_put" numbered="true" toc="default">
<name>PUT message</name>
+ <section anchor="p2p_put_wire">
+ <name>Wire Format</name>
<figure anchor="figure_putmsg">
<artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
@@ -671,12 +673,66 @@ END
by the BTYPE field.
</dd>
</dl>
-
+ </section>
+ <section anchor="p2p_put_processing">
+ <name>Processing</name>
+ <t>
+ Upon receiving a PUT message from a connected peer. An implementation
+ MUST process it step by step as follows:
+ </t>
+ <ol>
+ <li>
+ The EXPIRATION field is evaluated. If the message is expired,
+ it MUST be discarded.
+ </li>
+ <li>
+ If the BTYPE is not supported by the implementation, no validation
+ of the block payload is performed and processing continues at (4).
+ Else, the block MUST be validated as defined in (3).
+ </li>
+ <li>
+ The block key is extracted from BLOCK. If the block key
+ does not match KEY or cannot be extracted because the BLOCK
+ is malformed, the message MUST be discarded.
+ The block is evaluated. TODO FIXME: In the code, we do not really
+ do this. We should review.
+ </li>
+ <li>
+ The sender peer ID SHOULD be in the BLOOMFILTER. If not, the
+ implementation MAY log an error, but MUST continue.
+ </li>
+ <li>
+ If the "Record Route" flag is set in OPTIONS, add the local peer ID
+ to PUTPATH. FIXME: Should should come way later (?)
+ </li>
+ <li>
+ If the KEY of this PUT message is in the list of pending queries,
+ return the message through the API. FIXME: Is this a conversion to
+ a RESULT??
+ </li>
+ <li>
+ If the local peer is the closest peer (AM-CLOSEST-PEER) or the
+ "Demultiplex Everywhere" options flag ist set, the message MUST
+ be stored locally in the block storage.
+ </li>
+ <li>
+ Given the value in REPL_LVL, the number of peers to forward to
+ MUST be calculated (NUM-FORWARD-PEERS). If there is at least one
+ peer to forward to, the implementation SHOULD select up to this
+ number of peers to forward the message to. The implementation MAY
+ forward to fewer or no peers in order to handle resource constraints
+ such as bandwidth.
+ The message BLOOMFILTER MUST be updated with the local peer ID.
+ </li>
+ </ol>
+ </section>
</section>
<section anchor="p2p_get" numbered="true" toc="default">
- <name>GET message</name>
- <figure anchor="figure_getmsg">
- <artwork name="" type="" align="left" alt=""><![CDATA[
+ <name>GET Message</name>
+ <section anchor="p2p_get_wire">
+ <name>Wire Format</name>
+ <figure anchor="figure_getmsg">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
| MSIZE | MTYPE | BTYPE |
@@ -696,70 +752,123 @@ END
/ BF_RESULT (variable length) /
+-----+-----+-----+-----+-----+-----+-----+-----+
]]></artwork>
- </figure>
- <t>where:</t>
- <dl>
- <dt>MSIZE</dt>
- <dd>
- denotes the size of this message in network byte order.
- </dd>
- <dt>MTYPE</dt>
- <dd>
- is the 16-bit message type. This type can be one of the DHT message
- types but for put messages it must be set to
- the value 147 in network byte order.
- </dd>
- <dt>BTYPE</dt>
- <dd>
- is a 32-bit block type field. The block type indicates the content
- type of the payload. In network byte order.
- </dd>
- <dt>OPTIONS</dt>
- <dd>
- is a 16-bit options field (see below).
- </dd>
- <dt>HOPCOUNT</dt>
- <dd>
- is a 16-bit number indicating how many hops this message has
- traversed to far. In network byte order.
- </dd>
- <dt>REPL_LVL</dt>
- <dd>
- is a 16-bit number indicating the desired replication level of
- the data. In network byte order.
- </dd>
- <dt>XQ_SIZE</dt>
- <dd>
- is a 32-bit number indicating the length of the optional
- extended query XQUERY. In network byte order.
- </dd>
- <dt>BLOOMFILTER</dt>
- <dd>
- A bloomfilter (for peer identities) to stop circular routes.
- </dd>
- <dt>KEY</dt>
- <dd>
- The key under which the PUT request wants to store content
- under.
- </dd>
- <dt>XQUERY</dt>
- <dd>
- the variable-length extended query. Optional.
- </dd>
- <dt>BF_MUTATOR</dt>
- <dd>
- The 32-bit bloomfilter mutator for the result bloomfilter.
- </dd>
- <dt>RESULT_BF</dt>
- <dd>
- the variable-length result bloomfilter.
- </dd>
- </dl>
+ </figure>
+ <t>where:</t>
+ <dl>
+ <dt>MSIZE</dt>
+ <dd>
+ denotes the size of this message in network byte order.
+ </dd>
+ <dt>MTYPE</dt>
+ <dd>
+ is the 16-bit message type. This type can be one of the DHT message
+ types but for put messages it must be set to
+ the value 147 in network byte order.
+ </dd>
+ <dt>BTYPE</dt>
+ <dd>
+ is a 32-bit block type field. The block type indicates the content
+ type of the payload. In network byte order.
+ </dd>
+ <dt>OPTIONS</dt>
+ <dd>
+ is a 16-bit options field (see below).
+ </dd>
+ <dt>HOPCOUNT</dt>
+ <dd>
+ is a 16-bit number indicating how many hops this message has
+ traversed to far. In network byte order.
+ </dd>
+ <dt>REPL_LVL</dt>
+ <dd>
+ is a 16-bit number indicating the desired replication level of
+ the data. In network byte order.
+ </dd>
+ <dt>XQ_SIZE</dt>
+ <dd>
+ is a 32-bit number indicating the length of the optional
+ extended query XQUERY. In network byte order.
+ </dd>
+ <dt>BLOOMFILTER</dt>
+ <dd>
+ A bloomfilter (for peer identities) to stop circular routes.
+ </dd>
+ <dt>KEY</dt>
+ <dd>
+ The key under which the PUT request wants to store content
+ under.
+ </dd>
+ <dt>XQUERY</dt>
+ <dd>
+ the variable-length extended query. Optional.
+ </dd>
+ <dt>BF_MUTATOR</dt>
+ <dd>
+ The 32-bit bloomfilter mutator for the result bloomfilter.
+ </dd>
+ <dt>RESULT_BF</dt>
+ <dd>
+ the variable-length result bloomfilter.
+ </dd>
+ </dl>
+ </section>
+ <section anchor="p2p_get_processing">
+ <name>Processing</name>
+ <t>
+ Upon receiving a GET message from a connected peer. An implementation
+ MUST process it step by step as follows:
+ </t>
+ <ol>
+ <li>
+ The KEY and XQUERY is validated against the requested BTYPE.
+ If the BTYPE is not supported, or if the block key
+ does not match the BTYPE or if the XQUERY is malformed,
+ the message MUST be discarded.
+ </li>
+ <li>
+ The sender peer ID SHOULD be in the BLOOMFILTER. If not, the
+ implementation MAY log an error, but MUST continue.
+ </li>
+ <li>
+ <t>
+ If the local peer is the closest peer (AM-CLOSEST-PEER) or the
+ "Demultiplex Everywhere" options flag is set, a reply MUST be
+ produced:
+ </t>
+ <ol>
+ <li>
+ If OPTIONS indicate a "Find Peer" request, FIXME the peer selection
+ foo from buckets that probably needs fixing. Take into account
+ REPLY_BF
+ </li>
+ <li>
+ Else, if there is a BLOCK in the local Block Storage which is
+ not already in the RESULT_BF, a RESULT message MUST be sent.
+ FIXME link to how the result is sent?
+ </li>
+ </ol>
+ </li>
+ <li>
+ FIXME: We only handle if not GNUNET_BLOCK_EVALUATION_OK_LAST??
+ </li>
+ <li>
+ Given the value in REPL_LVL, the number of peers to forward to
+ MUST be calculated (NUM-FORWARD-PEERS). If there is at least one
+ peer to forward to, the implementation SHOULD select up to this
+ number of peers to forward the message to. The implementation MAY
+ forward to fewer or no peers in order to handle resource constraints
+ such as bandwidth.
+ The message BLOOMFILTER MUST be updated with the local peer ID.
+ </li>
+ </ol>
+ </section>
</section>
<section anchor="p2p_result" numbered="true" toc="default">
<name>RESULT message</name>
- <figure anchor="figure_resmsg">
- <artwork name="" type="" align="left" alt=""><![CDATA[
+ <section anchor="p2p_result_wire">
+ <name>Wire Format</name>
+ <figure anchor="figure_resmsg">
+ <artwork name="" type="" align="left" alt=""><![CDATA[
0 8 16 24 32 40 48 56
+-----+-----+-----+-----+-----+-----+-----+-----+
| MSIZE | MTYPE | BTYPE |
@@ -781,75 +890,131 @@ END
/ (variable length) /
+-----+-----+-----+-----+-----+-----+-----+-----+
]]></artwork>
- </figure>
- <t>where:</t>
- <dl>
- <dt>MSIZE</dt>
- <dd>
- denotes the size of this message in network byte order.
- </dd>
- <dt>MTYPE</dt>
- <dd>
- is the 16-bit message type. This type can be one of the DHT message
- types but for put messages it must be set to
- the value 148 in network byte order.
- </dd>
- <dt>OPTIONS</dt>
- <dd>
- is a 16-bit options field (see below).
- </dd>
- <dt>BTYPE</dt>
- <dd>
- is a 32-bit block type field. The block type indicates the content
- type of the payload. In network byte order.
- </dd>
- <dt>PUTPATH_L</dt>
- <dd>
- is a 16-bit number indicating the length of the PUT path recorded
- in PUTPATH. As PUTPATH is optiona, this value may be zero.
- In network byte order.
- </dd>
- <dt>GET_PATH_LEN</dt>
- <dd>
- is a 16-bit number indicating the length of the GET path recorded
- in GETPATH. As PUTPATH is optiona, this value may be zero.
- In network byte order.
- </dd>
- <dt>EXPIRATION</dt>
- <dd>
- denotes the absolute 64-bit expiration date of the content.
- In microseconds since midnight (0 hour), January 1, 1970 in network
- byte order.
- </dd>
- <dt>KEY</dt>
- <dd>
- The key under which the PUT request wants to store content
- under.
- </dd>
- <dt>PUTPATH</dt>
- <dd>
- the variable-length PUT path.
- The path consists of a list of PATH_LEN peer IDs.
- </dd>
- <dt>GETPATH</dt>
- <dd>
- the variable-length PUT path.
- The path consists of a list of PATH_LEN peer IDs.
- </dd>
- <dt>BLOCK</dt>
- <dd>
- the variable-length resource record data payload.
- The contents are defined by the respective type of the resource record.
- </dd>
- </dl>
+ </figure>
+ <t>where:</t>
+ <dl>
+ <dt>MSIZE</dt>
+ <dd>
+ denotes the size of this message in network byte order.
+ </dd>
+ <dt>MTYPE</dt>
+ <dd>
+ is the 16-bit message type. This type can be one of the DHT message
+ types but for put messages it must be set to
+ the value 148 in network byte order.
+ </dd>
+ <dt>OPTIONS</dt>
+ <dd>
+ is a 16-bit options field (see below).
+ </dd>
+ <dt>BTYPE</dt>
+ <dd>
+ is a 32-bit block type field. The block type indicates the content
+ type of the payload. In network byte order.
+ </dd>
+ <dt>PUTPATH_L</dt>
+ <dd>
+ is a 16-bit number indicating the length of the PUT path recorded
+ in PUTPATH. As PUTPATH is optiona, this value may be zero.
+ In network byte order.
+ </dd>
+ <dt>GET_PATH_LEN</dt>
+ <dd>
+ is a 16-bit number indicating the length of the GET path recorded
+ in GETPATH. As PUTPATH is optiona, this value may be zero.
+ In network byte order.
+ </dd>
+ <dt>EXPIRATION</dt>
+ <dd>
+ denotes the absolute 64-bit expiration date of the content.
+ In microseconds since midnight (0 hour), January 1, 1970 in network
+ byte order.
+ </dd>
+ <dt>KEY</dt>
+ <dd>
+ The key under which the PUT request wants to store content
+ under.
+ </dd>
+ <dt>PUTPATH</dt>
+ <dd>
+ the variable-length PUT path.
+ The path consists of a list of PATH_LEN peer IDs.
+ </dd>
+ <dt>GETPATH</dt>
+ <dd>
+ the variable-length PUT path.
+ The path consists of a list of PATH_LEN peer IDs.
+ </dd>
+ <dt>BLOCK</dt>
+ <dd>
+ the variable-length resource record data payload.
+ The contents are defined by the respective type of the resource record.
+ </dd>
+ </dl>
+ </section>
+ <section anchor="p2p_result_processing">
+ <name>Processing</name>
+ <t>
+ Upon receiving a RESULT message from a connected peer. An implementation
+ MUST process it step by step as follows:
+ </t>
+ <ol>
+ <li>
+ The EXPIRATION field is evaluated. If the message is expired,
+ it MUST be discarded.
+ </li>
+ <li>
+ If the MTYPE of the message indicates a HELLO block, the
+ payload MUST be considered for the local routing table.
+ FIXME: Considered how?
+ </li>
+ <li>
+ If the sender peer (FIXME which peer?) is already found in the
+ GETPATH, the path MUST be truncated.
+ </li>
+ <li>
+ FIXME: No validation??
+ </li>
+ <li>
+ If the KEY of this PUT message is in the list of pending queries,
+ return the message through the API.
+ </li>
+ <li>
+ The implementation MAY cache RESULT messages.
+ </li>
+ <li>
+ If no requests for this KEY or BTYPE are known, result processing
+ is completed.
+ </li>
+ <li>
+ If the request is of type "Find Peer" and the message BTYPE is
+ of type HELLO the block key is extracted from BLOCK, and if the
+ block key does not match KEY or cannot be extracted because
+ the BLOCK is malformed, the message MUST be discarded.
+ Otherwise, the block is evaluated against the message KEY.
+ FIXME: If OK_MORE or OK_LAST the RESULT is routed. One (!) peer is
+ selected from the connected peers (!). If none is found the message
+ is discarded.
+ </li>
+ </ol>
+ </section>
</section>
</section>
<section>
<name>Bootstrapping</name>
<t>
+ It is assumed that the peer is already connected to at least
+ one other peer.
+ First, those initial peers are sorted into their respective buckets.
+ </t>
+ <t>
In order to find the closest peers in the network to itself, an
- implementation MUST periodically send HELLO GET queries for its own
+ implementation MUST now periodically send HELLO GET queries for its own
peer ID.
+ Both the "record route" and "find peer" message options are set in the
+ GET queries in order to learn peers and network topology from the
+ message route and in order to receive approximate replies to the
+ query key (the peer ID).
</t>
<t>FIXME: Periodically -> more specific? No. Frequency may be adapted depending on network conditions, known peers, busy/idle etc.</t>
<t>
