diff options
author | Martin Schanzenbach <schanzen@gnunet.org> | 2022-12-25 17:52:45 +0900 |
---|---|---|
committer | Martin Schanzenbach <schanzen@gnunet.org> | 2022-12-25 17:52:45 +0900 |
commit | 128a1dbad6d2fa1677674784d2cfe77f5c2b2284 (patch) | |
tree | 5f746a73f5e8bdfc956e585840b1319c767b70ca | |
parent | ada4dc07acf571ab5c0dabb69c3dbc3303ca5474 (diff) | |
download | lsd0004-128a1dbad6d2fa1677674784d2cfe77f5c2b2284.tar.gz lsd0004-128a1dbad6d2fa1677674784d2cfe77f5c2b2284.zip |
First pass overhault message processing (with FIXMEs)
-rw-r--r-- | draft-schanzen-r5n.xml | 204 |
1 files changed, 156 insertions, 48 deletions
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml index 5db7b9e..f4a8099 100644 --- a/draft-schanzen-r5n.xml +++ b/draft-schanzen-r5n.xml | |||
@@ -924,11 +924,33 @@ BEGIN | |||
924 | <section anchor="p2p_messages" numbered="true" toc="default"> | 924 | <section anchor="p2p_messages" numbered="true" toc="default"> |
925 | <name>Message Processing</name> | 925 | <name>Message Processing</name> |
926 | <t> | 926 | <t> |
927 | Further, the implementation <bcp14>MAY</bcp14> act as an initiator of | ||
928 | messages. | ||
929 | If instructed through an application-facing API such as the one outlined | ||
930 | in <xref target="overlay"/>, the peer may acts as an initiator of <tt>GetMessage</tt>s | ||
931 | or <tt>PutMessage</tt>s. | ||
932 | The status of initiator is relevant for peers when processing <tt>ResultMessages</tt> | ||
933 | and the potential handover of results to the application. | ||
934 | <!-- FIXME: Are hello messages should or must? | ||
935 | --> | ||
936 | Initiation of <tt>HelloMessages</tt> is <bcp14>RECOMMENDED</bcp14>. | ||
937 | <tt>HelloMessage</tt>s are used to inform neighbors of | ||
938 | a peer about the sender's available addresses. The | ||
939 | recipients use these messages to inform their respective | ||
940 | Underlays about ways to sustain the connections and to | ||
941 | generate HELLO blocks (see <xref target="hello_block"/>) | ||
942 | to answer peer discovery queries | ||
943 | from other peers. | ||
944 | </t> | ||
945 | <t> | ||
927 | The implementation <bcp14>MUST</bcp14> listen for <tt>RECEIVE(P, M)</tt> signals | 946 | The implementation <bcp14>MUST</bcp14> listen for <tt>RECEIVE(P, M)</tt> signals |
928 | from the Underlay and respond to the respective messages sent by | 947 | from the Underlay and respond to the respective messages sent by |
929 | the peer <tt>P</tt>. | 948 | the peer <tt>P</tt>. |
930 | In the following, the wire formats of the messages and the required | 949 | </t> |
931 | processing are detailed. | 950 | <t> |
951 | Wheather initiated locally or received from a neighbour, the implementation | ||
952 | processes the messages according to the wire formats and the required | ||
953 | validations detailed in the following. | ||
932 | Where required, the local peer's ID is referred to as <tt>SELF</tt>. | 954 | Where required, the local peer's ID is referred to as <tt>SELF</tt>. |
933 | </t> | 955 | </t> |
934 | <section anchor="message_components"> | 956 | <section anchor="message_components"> |
@@ -1229,13 +1251,7 @@ BEGIN | |||
1229 | <!-- FIXME: While it is discussed here how to hangle HelloMessages | 1251 | <!-- FIXME: While it is discussed here how to hangle HelloMessages |
1230 | nowhere in the draft is a HelloMessage created at the | 1252 | nowhere in the draft is a HelloMessage created at the |
1231 | initiator so it is completely irrelevant atm --> | 1253 | initiator so it is completely irrelevant atm --> |
1232 | <tt>HelloMessage</tt>s are used to inform neighbors of | 1254 | In contrast to a HELLO block, a |
1233 | a peer about the sender's available addresses. The | ||
1234 | recipients use these messages to inform their respective | ||
1235 | Underlays about ways to sustain the connections and to | ||
1236 | generate HELLO blocks (see <xref target="hello_block"/>) | ||
1237 | to answer peer discovery queries | ||
1238 | from other peers. In contrast to a HELLO block, a | ||
1239 | <tt>HelloMessage</tt> does not contain the ID of | 1255 | <tt>HelloMessage</tt> does not contain the ID of |
1240 | the peer the address information is about: in a | 1256 | the peer the address information is about: in a |
1241 | <tt>HelloMessage</tt>, the address information is always | 1257 | <tt>HelloMessage</tt>, the address information is always |
@@ -1338,6 +1354,12 @@ BEGIN | |||
1338 | <name>PutMessage</name> | 1354 | <name>PutMessage</name> |
1339 | <t> | 1355 | <t> |
1340 | <tt>PutMessage</tt>s are used to store information at other peers in the DHT. | 1356 | <tt>PutMessage</tt>s are used to store information at other peers in the DHT. |
1357 | Any API which allows applications to initiate <tt>PutMessage</tt>s needs to | ||
1358 | provide sufficient, implementation-specific information needed to construct | ||
1359 | the initial <tt>PutMessage</tt>. | ||
1360 | For example, implementations supporting multiple applications and blocks will | ||
1361 | have block type and message flag parameters in addition to the actual data | ||
1362 | payload and key. | ||
1341 | </t> | 1363 | </t> |
1342 | <section anchor="p2p_put_wire"> | 1364 | <section anchor="p2p_put_wire"> |
1343 | <name>Wire Format</name> | 1365 | <name>Wire Format</name> |
@@ -1372,52 +1394,69 @@ BEGIN | |||
1372 | <dt>MSIZE</dt> | 1394 | <dt>MSIZE</dt> |
1373 | <dd> | 1395 | <dd> |
1374 | denotes the size of this message in network byte order. | 1396 | denotes the size of this message in network byte order. |
1397 | Set by the initiator. | ||
1398 | Modified by processing peers when message contents such as the path lengths change. | ||
1375 | </dd> | 1399 | </dd> |
1376 | <dt>MTYPE</dt> | 1400 | <dt>MTYPE</dt> |
1377 | <dd> | 1401 | <dd> |
1378 | is the 16-bit message type. It must be set to | 1402 | is the 16-bit message type. It is set by the initiator to |
1379 | the value 146 in network byte order. | 1403 | the value 146 in network byte order. Read-only. |
1380 | </dd> | 1404 | </dd> |
1381 | <dt>BTYPE</dt> | 1405 | <dt>BTYPE</dt> |
1382 | <dd> | 1406 | <dd> |
1383 | is a 32-bit block type. The block type indicates the content | 1407 | is a 32-bit block type. |
1384 | type of the payload. In network byte order. | 1408 | The block type indicates the content |
1409 | type of the payload. | ||
1410 | Set by the initiator. Read-only. | ||
1411 | In network byte order. | ||
1385 | </dd> | 1412 | </dd> |
1386 | <dt>FLAGS</dt> | 1413 | <dt>FLAGS</dt> |
1387 | <dd> | 1414 | <dd> |
1388 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). | 1415 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). |
1416 | Set by the initiator. Read-only. | ||
1389 | </dd> | 1417 | </dd> |
1390 | <dt>HOPCOUNT</dt> | 1418 | <dt>HOPCOUNT</dt> |
1391 | <dd> | 1419 | <dd> |
1392 | is a 16-bit number indicating how many hops this message has | 1420 | is a 16-bit number indicating how many hops this message has |
1393 | traversed to far. In network byte order. | 1421 | traversed to far. |
1422 | Set by the initiator to 0. | ||
1423 | Incremented by processing peers. | ||
1424 | In network byte order. | ||
1394 | </dd> | 1425 | </dd> |
1395 | <dt>REPL_LVL</dt> | 1426 | <dt>REPL_LVL</dt> |
1396 | <dd> | 1427 | <dd> |
1397 | is a 16-bit number indicating the desired replication level of | 1428 | is a 16-bit number indicating the desired replication level of |
1398 | the data. In network byte order. | 1429 | the data. |
1430 | Set by the initiator. Read-only. | ||
1431 | In network byte order. | ||
1399 | </dd> | 1432 | </dd> |
1400 | <dt>PATH_LEN</dt> | 1433 | <dt>PATH_LEN</dt> |
1401 | <dd> | 1434 | <dd> |
1402 | is a 16-bit number indicating the number of Path Elements | 1435 | is a 16-bit number indicating the number of Path Elements |
1403 | recorded in PUTPATH. | 1436 | recorded in PUTPATH. |
1404 | As PUTPATH is optional, this value may be zero. | 1437 | As PUTPATH is optional, this value may be zero. |
1438 | If the PUTPATH is enabled, set initially to 0 by the initiator. | ||
1439 | Incremented by processing peers. | ||
1405 | In network byte order. | 1440 | In network byte order. |
1406 | </dd> | 1441 | </dd> |
1407 | <dt>EXPIRATION</dt> | 1442 | <dt>EXPIRATION</dt> |
1408 | <dd> | 1443 | <dd> |
1409 | denotes the absolute 64-bit expiration date of the content. | 1444 | denotes the absolute 64-bit expiration date of the content. |
1445 | Set by the initiator. Read-only. | ||
1410 | In microseconds since midnight (0 hour), January 1, 1970 in network | 1446 | In microseconds since midnight (0 hour), January 1, 1970 in network |
1411 | byte order. | 1447 | byte order. |
1412 | </dd> | 1448 | </dd> |
1413 | <dt>PEER_BF</dt> | 1449 | <dt>PEER_BF</dt> |
1414 | <dd> | 1450 | <dd> |
1415 | A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>). | 1451 | A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>). |
1452 | Set by the initiator to include itself. <!-- FIXME: Is that so? --> | ||
1453 | Modified by processing peers to include their own peer ID. | ||
1416 | </dd> | 1454 | </dd> |
1417 | <dt>BLOCK_KEY</dt> | 1455 | <dt>BLOCK_KEY</dt> |
1418 | <dd> | 1456 | <dd> |
1419 | The key under which the <tt>PutMessage</tt> wants to store content | 1457 | The key under which the <tt>PutMessage</tt> wants to store content |
1420 | under. | 1458 | under. |
1459 | Set by the initiator. Read-only. | ||
1421 | </dd> | 1460 | </dd> |
1422 | <dt>TRUNCATED ORIGIN</dt> | 1461 | <dt>TRUNCATED ORIGIN</dt> |
1423 | <dd> | 1462 | <dd> |
@@ -1431,11 +1470,14 @@ BEGIN | |||
1431 | this public key must be used. Note that | 1470 | this public key must be used. Note that |
1432 | due to the truncation, this last hop | 1471 | due to the truncation, this last hop |
1433 | cannot be verified to exist. | 1472 | cannot be verified to exist. |
1473 | Value is modified by processing peers. | ||
1434 | </dd> | 1474 | </dd> |
1435 | <dt>PUTPATH</dt> | 1475 | <dt>PUTPATH</dt> |
1436 | <dd> | 1476 | <dd> |
1437 | the variable-length PUT path. | 1477 | the variable-length PUT path. |
1438 | The path consists of a list of PATH_LEN Path Elements. | 1478 | The path consists of a list of PATH_LEN Path Elements. |
1479 | Set by the initiator to 0. | ||
1480 | Incremented by processing peers. | ||
1439 | </dd> | 1481 | </dd> |
1440 | <dt>LAST HOP SIGNATURE</dt> | 1482 | <dt>LAST HOP SIGNATURE</dt> |
1441 | <dd> | 1483 | <dd> |
@@ -1447,12 +1489,14 @@ BEGIN | |||
1447 | the predecessor (all zeros if PATH_LEN is 0, | 1489 | the predecessor (all zeros if PATH_LEN is 0, |
1448 | otherwise the last peer in PUTPATH) to | 1490 | otherwise the last peer in PUTPATH) to |
1449 | the target peer. | 1491 | the target peer. |
1492 | Modified by processing peers (if flag is set). | ||
1450 | </dd> | 1493 | </dd> |
1451 | <dt>BLOCK</dt> | 1494 | <dt>BLOCK</dt> |
1452 | <dd> | 1495 | <dd> |
1453 | the variable-length block payload. The contents are determined | 1496 | the variable-length block payload. The contents are determined |
1454 | by the BTYPE field. The length is determined by MSIZE minus | 1497 | by the BTYPE field. The length is determined by MSIZE minus |
1455 | the size of all of the other fields. | 1498 | the size of all of the other fields. |
1499 | Set by the initiator. Read-only. | ||
1456 | </dd> | 1500 | </dd> |
1457 | </dl> | 1501 | </dl> |
1458 | </section> | 1502 | </section> |
@@ -1460,6 +1504,7 @@ BEGIN | |||
1460 | <name>Processing</name> | 1504 | <name>Processing</name> |
1461 | <t> | 1505 | <t> |
1462 | Upon receiving a <tt>PutMessage</tt> from a peer <tt>P</tt> | 1506 | Upon receiving a <tt>PutMessage</tt> from a peer <tt>P</tt> |
1507 | , or created through initiation by an overlay API, | ||
1463 | an implementation <bcp14>MUST</bcp14> process it step by step as follows: | 1508 | an implementation <bcp14>MUST</bcp14> process it step by step as follows: |
1464 | </t> | 1509 | </t> |
1465 | <ol> | 1510 | <ol> |
@@ -1491,13 +1536,18 @@ BEGIN | |||
1491 | The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in <tt>PEER_BF</tt>. | 1536 | The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in <tt>PEER_BF</tt>. |
1492 | If not, the implementation <bcp14>MAY</bcp14> log an error, but <bcp14>MUST</bcp14> continue. | 1537 | If not, the implementation <bcp14>MAY</bcp14> log an error, but <bcp14>MUST</bcp14> continue. |
1493 | </li> | 1538 | </li> |
1494 | <li> | 1539 | <!--<li> |
1540 | FIXME: I do not know what is going on here. "local peer address" | ||
1541 | is certainly wrong. | ||
1542 | But then, looking at the PathElement description, so wold be local peer ID. | ||
1543 | Also, no signatures are ever created in this processing | ||
1495 | If the <tt>RecordRoute</tt> flag is set in FLAGS, | 1544 | If the <tt>RecordRoute</tt> flag is set in FLAGS, |
1496 | the local peer address <bcp14>MUST</bcp14> be appended to the <tt>PUTPATH</tt> | 1545 | the local peer address <bcp14>MUST</bcp14> be appended to the <tt>PUTPATH</tt> |
1497 | of the message. If the flag is not set, the <tt>PATH_LEN</tt> | 1546 | of the message. |
1498 | <bcp14>MUST</bcp14> be set to zero. | 1547 | </li>--> |
1499 | </li> | ||
1500 | <li> | 1548 | <li> |
1549 | If the flag is not set, the <tt>PATH_LEN</tt> | ||
1550 | <bcp14>MUST</bcp14> be set to zero. | ||
1501 | If the <tt>PATH_LEN</tt> is non-zero, | 1551 | If the <tt>PATH_LEN</tt> is non-zero, |
1502 | the local peer <bcp14>SHOULD</bcp14> verify the signatures from the <tt>PUTPATH</tt>. | 1552 | the local peer <bcp14>SHOULD</bcp14> verify the signatures from the <tt>PUTPATH</tt>. |
1503 | Verification <bcp14>MAY</bcp14> involve checking all signatures or any random | 1553 | Verification <bcp14>MAY</bcp14> involve checking all signatures or any random |
@@ -1533,12 +1583,16 @@ BEGIN | |||
1533 | number of peers to forward the message to. The implementation <bcp14>MAY</bcp14> | 1583 | number of peers to forward the message to. The implementation <bcp14>MAY</bcp14> |
1534 | forward to fewer or no peers in order to handle resource constraints | 1584 | forward to fewer or no peers in order to handle resource constraints |
1535 | such as limited bandwidth. | 1585 | such as limited bandwidth. |
1536 | Finally, the local peer address <bcp14>MUST</bcp14> be added to the | 1586 | <!-- FIXME: From above. it seems to me that here we need to add a new putpath |
1537 | <tt>PEER_BF</tt> before forwarding the message. | 1587 | signature element (as we know the successor now)--> |
1538 | For all peers with peer address <tt>P</tt> selected to forward the message | 1588 | For each selected peer with peer address <tt>P</tt> a dedicated <tt>PutMessage'</tt> |
1539 | to, <tt>SEND(P, PutMessage')</tt> is called. Here, <tt>PutMessage'</tt> | 1589 | is created containing the original (and where applicable already updated) fields |
1540 | is the original message with updated fields. In particular, <tt>HOPCOUNT</tt> | 1590 | of the received <tt>PutMessage</tt>. |
1541 | <bcp14>MUST</bcp14> be incremented by 1. | 1591 | In each message the local peer address <bcp14>MUST</bcp14> be added to the |
1592 | <tt>PEER_BF</tt> and the <tt>HOPCOUNT</tt> is incremented by 1. | ||
1593 | If the <tt>RecordRoute</tt> flag is set, a new Path Element is created and added | ||
1594 | to the <tt>PUTPATH</tt> fields and the <tt>PATH_LEN</tt> field is incremented by 1. | ||
1595 | Finally, <tt>SEND(P, PutMessage')</tt> is called. | ||
1542 | </li> | 1596 | </li> |
1543 | </ol> | 1597 | </ol> |
1544 | </section> | 1598 | </section> |
@@ -1547,7 +1601,11 @@ BEGIN | |||
1547 | <name>GetMessage</name> | 1601 | <name>GetMessage</name> |
1548 | <t> | 1602 | <t> |
1549 | <tt>GetMessage</tt>s are used to request information from other peers in the DHT. | 1603 | <tt>GetMessage</tt>s are used to request information from other peers in the DHT. |
1550 | </t> | 1604 | Any overlay API which allows applications to initiate <tt>GetMessage</tt>s needs to provide |
1605 | sufficient, implementation-specific information needed to construct the initial <tt>GetMessage</tt>. | ||
1606 | For example, implementations supporting multiple applications and blocks will have block type and | ||
1607 | message flag parameters. | ||
1608 | </t> | ||
1551 | <section anchor="p2p_get_wire"> | 1609 | <section anchor="p2p_get_wire"> |
1552 | <name>Wire Format</name> | 1610 | <name>Wire Format</name> |
1553 | <figure anchor="figure_getmsg" title="The GetMessage Wire Format."> | 1611 | <figure anchor="figure_getmsg" title="The GetMessage Wire Format."> |
@@ -1576,54 +1634,71 @@ BEGIN | |||
1576 | <dt>MSIZE</dt> | 1634 | <dt>MSIZE</dt> |
1577 | <dd> | 1635 | <dd> |
1578 | denotes the size of this message in network byte order. | 1636 | denotes the size of this message in network byte order. |
1637 | Set by the initiator. | ||
1638 | <!-- FIXME: Is this not fixed-length once set by initiator?--> | ||
1639 | Modified by processing peers when message contents change. | ||
1579 | </dd> | 1640 | </dd> |
1580 | <dt>MTYPE</dt> | 1641 | <dt>MTYPE</dt> |
1581 | <dd> | 1642 | <dd> |
1582 | is the 16-bit message type. It must be set to | 1643 | is the 16-bit message type. It is set by the initiator to |
1583 | the value 147 in network byte order. | 1644 | the value 147 in network byte order. Read-only. |
1584 | </dd> | 1645 | </dd> |
1585 | <dt>BTYPE</dt> | 1646 | <dt>BTYPE</dt> |
1586 | <dd> | 1647 | <dd> |
1587 | is a 32-bit block type field. The block type indicates the content | 1648 | is a 32-bit block type field. The block type indicates the content |
1588 | type of the payload. In network byte order. | 1649 | type of the payload. Set by the initiator. Read-only. In network byte order. |
1589 | </dd> | 1650 | </dd> |
1590 | <dt>FLAGS</dt> | 1651 | <dt>FLAGS</dt> |
1591 | <dd> | 1652 | <dd> |
1592 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). | 1653 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). |
1654 | Set by the initiator. Read-only. | ||
1593 | </dd> | 1655 | </dd> |
1594 | <dt>HOPCOUNT</dt> | 1656 | <dt>HOPCOUNT</dt> |
1595 | <dd> | 1657 | <dd> |
1596 | is a 16-bit number indicating how many hops this message has | 1658 | is a 16-bit number indicating how many hops this message has |
1597 | traversed to far. In network byte order. | 1659 | traversed to far. |
1660 | Set by the initiator to 0. | ||
1661 | Incremented by processing peers. | ||
1662 | In network byte order. | ||
1598 | </dd> | 1663 | </dd> |
1599 | <dt>REPL_LVL</dt> | 1664 | <dt>REPL_LVL</dt> |
1600 | <dd> | 1665 | <dd> |
1601 | is a 16-bit number indicating the desired replication level of | 1666 | is a 16-bit number indicating the desired replication level of |
1602 | the data. In network byte order. | 1667 | the data. |
1668 | Set by the initiator. Read-only. | ||
1669 | In network byte order. | ||
1603 | </dd> | 1670 | </dd> |
1604 | <dt>RF_SIZE</dt> | 1671 | <dt>RF_SIZE</dt> |
1605 | <dd> | 1672 | <dd> |
1606 | is a 16-bit number indicating the length of the | 1673 | is a 16-bit number indicating the length of the |
1607 | result filter RESULT_FILTER. In network byte order. | 1674 | result filter RESULT_FILTER. |
1675 | Set by the initiator. Read-only. <!--FIXME is that so? --> | ||
1676 | In network byte order. | ||
1608 | </dd> | 1677 | </dd> |
1609 | <dt>PEER_BF</dt> | 1678 | <dt>PEER_BF</dt> |
1610 | <dd> | 1679 | <dd> |
1611 | A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>). | 1680 | A peer Bloom filter to stop circular routes (see <xref target="routing_bloomfilter"/>). |
1681 | Set by the initiator to include itself. <!-- Is that so? --> | ||
1682 | Modified by processing peers to include their own peer address. | ||
1612 | </dd> | 1683 | </dd> |
1613 | <dt>QUERY_HASH</dt> | 1684 | <dt>QUERY_HASH</dt> |
1614 | <dd> | 1685 | <dd> |
1615 | The query used to indicate what the key is under which the originator is looking | 1686 | The query used to indicate what the key is under which the initiator is looking |
1616 | for blocks with this request. | 1687 | for blocks with this request. |
1617 | The block type may use a different evaluation logic to determine | 1688 | The block type may use a different evaluation logic to determine |
1618 | applicable result blocks. | 1689 | applicable result blocks. |
1690 | Set by the initiator. Read-only. | ||
1619 | </dd> | 1691 | </dd> |
1620 | <dt>RESULT_FILTER</dt> | 1692 | <dt>RESULT_FILTER</dt> |
1621 | <dd> | 1693 | <dd> |
1622 | the variable-length result filter, described in <xref target="result_filter"/>. | 1694 | the variable-length result filter, described in <xref target="result_filter"/>. |
1695 | Set by the initiator. | ||
1696 | Modified by processing peers. | ||
1623 | </dd> | 1697 | </dd> |
1624 | <dt>XQUERY</dt> | 1698 | <dt>XQUERY</dt> |
1625 | <dd> | 1699 | <dd> |
1626 | the variable-length extended query. Optional. | 1700 | the variable-length extended query. Optional. |
1701 | Set by the initiator. <!-- FIXME: Modified by processing peers? --> | ||
1627 | </dd> | 1702 | </dd> |
1628 | </dl> | 1703 | </dl> |
1629 | </section> | 1704 | </section> |
@@ -1637,8 +1712,9 @@ BEGIN | |||
1637 | which matches the query key <bcp14>MUST</bcp14> check the result filter | 1712 | which matches the query key <bcp14>MUST</bcp14> check the result filter |
1638 | and only send a reply message if the result does not test positive | 1713 | and only send a reply message if the result does not test positive |
1639 | under the result filter. Before forwarding the <tt>GetMessage</tt>, the | 1714 | under the result filter. Before forwarding the <tt>GetMessage</tt>, the |
1640 | result filter <bcp14>MUST</bcp14> be updated to filter out all results | 1715 | result filter <bcp14>MUST</bcp14> be updated using the result of the <tt>BTYPE</tt>-specific |
1641 | already returned by the local peer. | 1716 | <tt>FilterResult</tt> (see <xref target="block_functions"/>) function to filter |
1717 | out all results already returned by the local peer. | ||
1642 | </t> | 1718 | </t> |
1643 | <t> | 1719 | <t> |
1644 | How a result filter is implemented depends on the block type | 1720 | How a result filter is implemented depends on the block type |
@@ -1647,16 +1723,17 @@ BEGIN | |||
1647 | it is possible that a desireable result is filtered by a result | 1723 | it is possible that a desireable result is filtered by a result |
1648 | filter because of a false-positive test. | 1724 | filter because of a false-positive test. |
1649 | </t> | 1725 | </t> |
1650 | <t> | 1726 | <t> |
1727 | <!-- FIXME: then this should be part of the registration policy --> | ||
1651 | How exactly a block result is added to a result filter | 1728 | How exactly a block result is added to a result filter |
1652 | <bcp14>MUST</bcp14> be | 1729 | <bcp14>MUST</bcp14> be specified as part of the definition of a block type. |
1653 | specified as part of the definition of a block type. | ||
1654 | </t> | 1730 | </t> |
1655 | </section> | 1731 | </section> |
1656 | <section anchor="p2p_get_processing"> | 1732 | <section anchor="p2p_get_processing"> |
1657 | <name>Processing</name> | 1733 | <name>Processing</name> |
1658 | <t> | 1734 | <t> |
1659 | Upon receiving a <tt>GetMessage</tt> from a peer an | 1735 | Upon receiving a <tt>GetMessage</tt> from a peer <tt>P</tt>, or |
1736 | created through initiation by the overlay API, an | ||
1660 | implementation <bcp14>MUST</bcp14> process it step by step as follows: | 1737 | implementation <bcp14>MUST</bcp14> process it step by step as follows: |
1661 | </t> | 1738 | </t> |
1662 | <ol> | 1739 | <ol> |
@@ -1667,7 +1744,7 @@ BEGIN | |||
1667 | If validation | 1744 | If validation |
1668 | function yields <tt>REQUEST_INVALID</tt>, the message <bcp14>MUST</bcp14> be discarded. | 1745 | function yields <tt>REQUEST_INVALID</tt>, the message <bcp14>MUST</bcp14> be discarded. |
1669 | If the <tt>BTYPE</tt> is not supported, the message <bcp14>MUST</bcp14> | 1746 | If the <tt>BTYPE</tt> is not supported, the message <bcp14>MUST</bcp14> |
1670 | be forwarded. | 1747 | be forwarded (Skip to step 4). |
1671 | If the <tt>BTYPE</tt> is <tt>ANY</tt>, the message is processed | 1748 | If the <tt>BTYPE</tt> is <tt>ANY</tt>, the message is processed |
1672 | without validation. | 1749 | without validation. |
1673 | </li> | 1750 | </li> |
@@ -1736,8 +1813,8 @@ BEGIN | |||
1736 | peer address <tt>SELF</tt>. | 1813 | peer address <tt>SELF</tt>. |
1737 | For all peers with peer address <tt>P'</tt> chosen to forward the message | 1814 | For all peers with peer address <tt>P'</tt> chosen to forward the message |
1738 | to, <tt>SEND(P', GetMessage')</tt> is called. Here, <tt>GetMessage'</tt> | 1815 | to, <tt>SEND(P', GetMessage')</tt> is called. Here, <tt>GetMessage'</tt> |
1739 | is the original message with updated fields. In particular, <tt>HOPCOUNT</tt> | 1816 | is the original message with the updated fields for <tt>HOPCOUNT</tt> (incremented |
1740 | <bcp14>MUST</bcp14> be incremented by 1. | 1817 | by 1), <tt>PEER_BF</tt> and <tt>RESULT_FILTER</tt>. |
1741 | </li> | 1818 | </li> |
1742 | </ol> | 1819 | </ol> |
1743 | </section> | 1820 | </section> |
@@ -1745,7 +1822,10 @@ BEGIN | |||
1745 | <section anchor="p2p_result" numbered="true" toc="default"> | 1822 | <section anchor="p2p_result" numbered="true" toc="default"> |
1746 | <name>ResultMessage</name> | 1823 | <name>ResultMessage</name> |
1747 | <t> | 1824 | <t> |
1748 | <tt>ResultMessage</tt>s are used to return information to other peers in the DHT. | 1825 | <tt>ResultMessage</tt>s are used to return information to other peers in the DHT |
1826 | or to applications using the overlay API that previously initiated a <tt>GetMessage</tt>. | ||
1827 | The initiator of a <tt>ResultMessage</tt> is a peer triggered through the processing | ||
1828 | of a <tt>GetMessage</tt>. | ||
1749 | </t> | 1829 | </t> |
1750 | <section anchor="p2p_result_wire"> | 1830 | <section anchor="p2p_result_wire"> |
1751 | <name>Wire Format</name> | 1831 | <name>Wire Format</name> |
@@ -1782,16 +1862,21 @@ BEGIN | |||
1782 | <dt>MSIZE</dt> | 1862 | <dt>MSIZE</dt> |
1783 | <dd> | 1863 | <dd> |
1784 | denotes the size of this message in network byte order. | 1864 | denotes the size of this message in network byte order. |
1865 | Set by the initiator. | ||
1866 | Updated by processing peers. | ||
1785 | </dd> | 1867 | </dd> |
1786 | <dt>MTYPE</dt> | 1868 | <dt>MTYPE</dt> |
1787 | <dd> | 1869 | <dd> |
1788 | is the 16-bit message type. It must be set to | 1870 | is the 16-bit message type. It must be set to |
1789 | the value 148 in network byte order. | 1871 | the value 148 in network byte order. |
1872 | Set by the initiator. Read-only. | ||
1790 | </dd> | 1873 | </dd> |
1791 | <dt>BTYPE</dt> | 1874 | <dt>BTYPE</dt> |
1792 | <dd> | 1875 | <dd> |
1793 | is a 32-bit block type field. The block type indicates the content | 1876 | is a 32-bit block type field. The block type indicates the content |
1794 | type of the payload. In network byte order. | 1877 | type of the payload. |
1878 | Set by the initiator. Read-only. | ||
1879 | In network byte order. | ||
1795 | </dd> | 1880 | </dd> |
1796 | <dt>RESERVED</dt> | 1881 | <dt>RESERVED</dt> |
1797 | <dd> | 1882 | <dd> |
@@ -1803,12 +1888,16 @@ BEGIN | |||
1803 | <dt>FLAGS</dt> | 1888 | <dt>FLAGS</dt> |
1804 | <dd> | 1889 | <dd> |
1805 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). | 1890 | is a 16-bit vector with binary options (see <xref target="route_flags"/>). |
1891 | Set by the initiator. <!-- FIXME to what? --> | ||
1806 | </dd> | 1892 | </dd> |
1807 | <dt>PUTPATH_L</dt> | 1893 | <dt>PUTPATH_L</dt> |
1808 | <dd> | 1894 | <dd> |
1809 | is a 16-bit number indicating the number of Path Elements recorded | 1895 | is a 16-bit number indicating the number of Path Elements recorded |
1810 | in <tt>PUTPATH</tt>. As <tt>PUTPATH</tt> is optional, this value may be zero | 1896 | in <tt>PUTPATH</tt>. As <tt>PUTPATH</tt> is optional, this value may be zero |
1811 | even if the message has traversed several peers. | 1897 | even if the message has traversed several peers. |
1898 | Set by the initiator to the <tt>PATH_LEN</tt> of the <tt>PutMessage</tt> | ||
1899 | from which the block originated. | ||
1900 | Modified by processing peers in case of path truncation. | ||
1812 | In network byte order. | 1901 | In network byte order. |
1813 | </dd> | 1902 | </dd> |
1814 | <dt>GETPATH_L</dt> | 1903 | <dt>GETPATH_L</dt> |
@@ -1816,6 +1905,8 @@ BEGIN | |||
1816 | is a 16-bit number indicating the number of Path Elements | 1905 | is a 16-bit number indicating the number of Path Elements |
1817 | recorded in <tt>GETPATH</tt>. As <tt>GETPATH</tt> is optional, this value may be zero | 1906 | recorded in <tt>GETPATH</tt>. As <tt>GETPATH</tt> is optional, this value may be zero |
1818 | even if the message has traversed several peers. | 1907 | even if the message has traversed several peers. |
1908 | Set by the initiator to 0. | ||
1909 | Modified by processing peers. | ||
1819 | In network byte order. | 1910 | In network byte order. |
1820 | </dd> | 1911 | </dd> |
1821 | <dt>EXPIRATION</dt> | 1912 | <dt>EXPIRATION</dt> |
@@ -1823,11 +1914,16 @@ BEGIN | |||
1823 | denotes the absolute 64-bit expiration date of the content. | 1914 | denotes the absolute 64-bit expiration date of the content. |
1824 | In microseconds since midnight (0 hour), January 1, 1970 in network | 1915 | In microseconds since midnight (0 hour), January 1, 1970 in network |
1825 | byte order. | 1916 | byte order. |
1917 | Set by the initiator to the expiration value as recorded from | ||
1918 | the <tt>PutMessage</tt> from which the block originated. | ||
1919 | Read-only. | ||
1826 | </dd> | 1920 | </dd> |
1827 | <dt>QUERY_HASH</dt> | 1921 | <dt>QUERY_HASH</dt> |
1828 | <dd> | 1922 | <dd> |
1829 | the query hash corresponding to the <tt>GetMessage</tt> which | 1923 | the query hash corresponding to the <tt>GetMessage</tt> which |
1830 | caused this reply message to be sent. | 1924 | caused this reply message to be sent. |
1925 | Set by the initiator using the value of the <tt>GetMessage</tt>. | ||
1926 | Read-only. | ||
1831 | </dd> | 1927 | </dd> |
1832 | <dt>TRUNCATED ORIGIN</dt> | 1928 | <dt>TRUNCATED ORIGIN</dt> |
1833 | <dd> | 1929 | <dd> |
@@ -1841,20 +1937,25 @@ BEGIN | |||
1841 | this public key must be used. Note that | 1937 | this public key must be used. Note that |
1842 | due to the truncation, this last hop | 1938 | due to the truncation, this last hop |
1843 | cannot be verified to exist. | 1939 | cannot be verified to exist. |
1940 | Set by processing peers. | ||
1844 | </dd> | 1941 | </dd> |
1845 | <dt>PUTPATH</dt> | 1942 | <dt>PUTPATH</dt> |
1846 | <dd> | 1943 | <dd> |
1847 | the variable-length PUT path. | 1944 | the variable-length PUT path. |
1848 | The path consists of a list of <tt>PUTPATH_L</tt> Path Elements. | 1945 | The path consists of a list of <tt>PUTPATH_L</tt> Path Elements. |
1946 | Set by the initiator to the the <tt>PUTPATH</tt> of the <tt>PutMessage</tt> | ||
1947 | from which the block originated. | ||
1948 | Modified by processing peers in case of path truncation. | ||
1849 | </dd> | 1949 | </dd> |
1850 | <dt>GETPATH</dt> | 1950 | <dt>GETPATH</dt> |
1851 | <dd> | 1951 | <dd> |
1852 | the variable-length PUT path. | 1952 | the variable-length PUT path. |
1853 | The path consists of a list of <tt>GETPATH_L</tt> Path Elements. | 1953 | The path consists of a list of <tt>GETPATH_L</tt> Path Elements. |
1954 | Set by processing peers. | ||
1854 | </dd> | 1955 | </dd> |
1855 | <dt>LAST HOP SIGNATURE</dt> | 1956 | <dt>LAST HOP SIGNATURE</dt> |
1856 | <dd> | 1957 | <dd> |
1857 | is only provided if the RECORD ROUTE flag | 1958 | is only provided if the <tt>RecordRoute</tt> flag |
1858 | is set in FLAGS. If present, this is | 1959 | is set in FLAGS. If present, this is |
1859 | an EdDSA signature of the sender of this message | 1960 | an EdDSA signature of the sender of this message |
1860 | (using the same format as the signatures in PUTPATH) | 1961 | (using the same format as the signatures in PUTPATH) |
@@ -1867,13 +1968,15 @@ BEGIN | |||
1867 | <dd> | 1968 | <dd> |
1868 | the variable-length resource record data payload. | 1969 | the variable-length resource record data payload. |
1869 | The contents are defined by the respective type of the resource record. | 1970 | The contents are defined by the respective type of the resource record. |
1971 | Set by the initiator. Read-only. | ||
1870 | </dd> | 1972 | </dd> |
1871 | </dl> | 1973 | </dl> |
1872 | </section> | 1974 | </section> |
1873 | <section anchor="p2p_result_processing"> | 1975 | <section anchor="p2p_result_processing"> |
1874 | <name>Processing</name> | 1976 | <name>Processing</name> |
1875 | <t> | 1977 | <t> |
1876 | Upon receiving a <tt>ResultMessage</tt> from a connected peer | 1978 | Upon receiving a <tt>ResultMessage</tt> from a connected peer or |
1979 | triggered by the processing of a <tt>GetMessage</tt>, | ||
1877 | an implementation <bcp14>MUST</bcp14> process it step by step as follows: | 1980 | an implementation <bcp14>MUST</bcp14> process it step by step as follows: |
1878 | </t> | 1981 | </t> |
1879 | <ol> | 1982 | <ol> |
@@ -1960,12 +2063,17 @@ BEGIN | |||
1960 | </ol> | 2063 | </ol> |
1961 | <t> | 2064 | <t> |
1962 | If the result is either <tt>FILTER_MORE</tt> or <tt>FILTER_LAST</tt>, | 2065 | If the result is either <tt>FILTER_MORE</tt> or <tt>FILTER_LAST</tt>, |
1963 | the result is forwarded to the origin of the query. If the result | 2066 | the message is forwarded to the origin of the query through |
1964 | was <tt>FILTER_LAST</tt>, the query is removed from the list of pending | 2067 | either the overlay API or using <tt>SEND(P, ResultMessage')</tt> where |
2068 | <tt>ResultMessage'</tt> is the now modified message. | ||
2069 | If the result was <tt>FILTER_LAST</tt>, the query is removed from the list of pending | ||
1965 | queries. | 2070 | queries. |
1966 | </t> | 2071 | </t> |
1967 | </li> | 2072 | </li> |
1968 | <li> | 2073 | <li> |
2074 | <!-- FIXME: If that is the case, then this also needs to be in the | ||
2075 | processing of GetMessage: I think we shoul dmove this to some | ||
2076 | performance considerations instead. --> | ||
1969 | Finally, the implementation <bcp14>MAY</bcp14> choose to | 2077 | Finally, the implementation <bcp14>MAY</bcp14> choose to |
1970 | cache data from <tt>ResultMessage</tt>s. | 2078 | cache data from <tt>ResultMessage</tt>s. |
1971 | </li> | 2079 | </li> |