From d9adcf0322fa261d1d1f58cf4590f02f50f88280 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Wolfgang=20M=C3=BCller?= Date: Thu, 18 Jul 2019 14:30:42 +0300 Subject: [PATCH] Proofreading ethermess.7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Juhani Krekelä --- ethermess.7 | 68 ++++++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/ethermess.7 b/ethermess.7 index a72f16b..18b3056 100644 --- a/ethermess.7 +++ b/ethermess.7 @@ -59,7 +59,7 @@ Tells the recipient to speak the given version of the protocol. Should be generated whenever an EtherMess packet with a version one doesn't speak is received. .It Status request (0x01) -Requests the recipient to tell its status and nick. +Requests the recipient to announce its status and nick. Upon receiving this packet, a status packet should be sent to the sender. .It Status (0x02) .TS @@ -98,14 +98,14 @@ The packet must be ignored if .It Status is not one of the recognized values. .It -Nick length is more than the remaining size of the packet +Nick length is more than the remaining size of the packet. .It Nick is not valid utf-8. .It Nick contains disallowed codepoints. .El .It Msgid request (0x03) -Requests the recipient to tell the message ID of the next message it is +Requests the recipient to announce the message ID of the next message it is expecting from the sender. Upon receiving this packet, a msgid packet should be sent to the sender. .It Msgid (0x04) @@ -114,13 +114,13 @@ allbox; lb lb lb l l l. Field Length (B) Contents -Msgid 2 Expected ID of next message +Msgid 2 Expected ID of the next message .TE .Pp -Informs the recipient of the expected ID of next message the recipient will -send to the sender. -Generally speaking, this should be one greater than the message ID of the -message sender last received from the recipient. +Announces the next message ID that the sender expects from the recipient. +Generally speaking, this should be one greater than the message ID last +received from that recipient. +However, an implementation may randomize the message ID upon each request. .Pp For special cases, see the Msgid section. .It Message (0x05) @@ -142,9 +142,9 @@ Msgid section), the message should be displayed to the user and the next message ID to expect should be made msgid + 1. If instead the ID is considered to be in the past, the message should be skipped as a repeat. -Note however than even in this case an ACK should be generated. +Note however that even in this case an ACK should be generated. .Pp -The message field has similar requirements to the nick field in its +The message field has similar requirements to the nick field regarding its encoding and contents, except that the message field may additionally contain the codepoints U+0A LINE FEED and U+09 CHARACTER TABULATION. .Pp @@ -184,10 +184,11 @@ They are unique to each sender and recipient pair. This means that the message IDs of messages A sends to B are completely unrelated to the IDs of messages A sends to C or messages B sends to A. .Pp -Because they are 16 bit, there is a possibility of a rollover. -For that reason, a simple comparison whether the ID of the message received -is equal or greater than the ID the recipient was expecting next doesn't -work. +Because they are 16 bit (which is comparably small) and the initial value +is randomized, there is a possibility of a rollover. +For that reason, a simple comparison of +.Li received_msgid >= next_expected_msgid +doesn't work. The correct way to test if a message ID is considered to be in the future is to do .Li (received_msgid - next_expected_msgid) modulus 2^16 @@ -197,18 +198,17 @@ There are special cases for if the recipient doesn't know what the ID of the next message they receive should be. If they have received a message, it should be accepted and the next ID to expect should be set to the ID of the message plus one, just like if the -message ID was considered to be in the future. -(Though it may be marked as a possible repeat.) +message ID was considered to be in the future (though it may be marked as +a possible repeat). If they have received an msgid request packet, they should set the next ID to expect to a random value and send that value in the msgid packet. .Pp -Implementations should not store the next message IDs to use in any -persistent storage. +Implementations should not store the next message IDs persistently. This is because if those values are out of date, messages sent by the implementation may be silently dropped. -Storing next message ID to expect is safer, though a value more than 0x8000 -out of date will lead to valid messages being dropped by the implementation -itself. +Storing the next message ID to expect is safer, though a value of more than +0x8000 out of date will lead to valid messages being dropped by the +implementation itself. .Ss Sending a message To send a message, the sender should first figure out the correct message ID to use. @@ -220,7 +220,7 @@ If the recipient doesn't answer the msgid request, the sender should retry the transmission a few times. The reference implementation, .Xr ethermess 1 , -will attempt to transmit at most 5 times, and uses a randomized timeout +will attempt to transmit at most 5 times, and uses a randomized timeout of around 1 to 1.5 seconds. Implementations should randomize the retry timeout to reduce chances of packet collisions with other @@ -230,18 +230,18 @@ If there is still no msgid packet, the message should be considered to have failed to send. .Pp Once the message ID to use is known, the sender should send the message to -the recipient and wait for an ACK with the same message ID. -(Note that the sender might receive ACKs for different messages.) +the recipient and wait for an ACK with the same message ID (note that the +sender might receive ACKs for different message). The transmission should have a similar timeout and retry mechanism as with the msgid request. If no matching ACK is received, the message should be considered to have failed to send, but the implementation may keep it around in case an ACK with its message ID is received later. .Pp -After sending the message, regardless of if an ACK was received for it or -not, the sender should update its cached value of the next message ID to -use when sending to the target to the message ID of the message that was -send plus one. +After sending the message, regardless of whether an ACK was received for +it or not, the sender should update its cached value of the next message +ID to use when sending to the target to the message ID of the message that +was sent plus one. .Ss Changing one's own nick or status When a user changes their nick or status, they should broadcast (send to the MAC FF:FF:FF:FF:FF:FF) the status and nick with the status packet. @@ -269,17 +269,17 @@ To find peers, an implementation should broadcast a status request package. Alternatively it may wait until it receives a keep-alive status broadcast from all of its peers. .Ss Getting the status of a peer -An implementation should keep a cache of statuses and nicks that is updated +An implementation should keep a cache of statuses and nicks and update it whenever a status packet is received. .Pp -If the cache doesn't have a given peer, the implementation may request the -status using the status request packet targeted at that peer. -The timeout and retry mechanism should be designed to avoid spammyness and +If the cache doesn't contain a given peer, the implementation may request +the status using the status request packet targeted at that peer. +The timeout and retry mechanism should be designed to avoid spamminess and minimize the possibility of packet collisions. .Pp An implementation may also implement a user-initiated status check by first -looking at the cache and then regardless of whether it was in the cache or -not sending a status request packet. +looking at the cache and then, regardless of whether it was in the cache or +not, sending a status request packet. This way the user can both receive an answer fast and in case the cached value was outdated get the correct result once it arrives. .Ss Starting up