nortti
/
ethermess
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Proofreading ethermess.7 

Co-authored-by: Juhani Krekelä <juhani@krekelä.fi>
This commit is contained in:
Wolfgang Müller 2019-07-18 14:30:42 +03:00 committed by Juhani Krekelä
parent a6aa7ba70d
commit d9adcf0322
1 changed files with 34 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
ethermess.7
View File

@ -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 Should be generated whenever an EtherMess packet with a version one doesn't
speak is received. speak is received.
.It Status request (0x01) .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. Upon receiving this packet, a status packet should be sent to the sender.
.It Status (0x02) .It Status (0x02)
.TS .TS
@ -98,14 +98,14 @@ The packet must be ignored if
.It .It
Status is not one of the recognized values. Status is not one of the recognized values.
.It .It
Nick length is more than the remaining size of the packet Nick length is more than the remaining size of the packet.
.It .It
Nick is not valid utf-8. Nick is not valid utf-8.
.It .It
Nick contains disallowed codepoints. Nick contains disallowed codepoints.
.El .El
.It Msgid request (0x03) .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. expecting from the sender.
Upon receiving this packet, a msgid packet should be sent to the sender. Upon receiving this packet, a msgid packet should be sent to the sender.
.It Msgid (0x04) .It Msgid (0x04)
@ -114,13 +114,13 @@ allbox;
lb lb lb lb lb lb
l l l. l l l.
Field Length (B) Contents Field Length (B) Contents
Msgid 2 Expected ID of next message Msgid 2 Expected ID of the next message
.TE .TE
.Pp .Pp
Informs the recipient of the expected ID of next message the recipient will Announces the next message ID that the sender expects from the recipient.
send to the sender. Generally speaking, this should be one greater than the message ID last
Generally speaking, this should be one greater than the message ID of the received from that recipient.
message sender last received from the recipient. However, an implementation may randomize the message ID upon each request.
.Pp .Pp
For special cases, see the Msgid section. For special cases, see the Msgid section.
.It Message (0x05) .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. message ID to expect should be made msgid + 1.
If instead the ID is considered to be in the past, the message should be If instead the ID is considered to be in the past, the message should be
skipped as a repeat. 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 .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 encoding and contents, except that the message field may additionally
contain the codepoints U+0A LINE FEED and U+09 CHARACTER TABULATION. contain the codepoints U+0A LINE FEED and U+09 CHARACTER TABULATION.
.Pp .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 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. unrelated to the IDs of messages A sends to C or messages B sends to A.
.Pp .Pp
Because they are 16 bit, there is a possibility of a rollover. Because they are 16 bit (which is comparably small) and the initial value
For that reason, a simple comparison whether the ID of the message received is randomized, there is a possibility of a rollover.
is equal or greater than the ID the recipient was expecting next doesn't For that reason, a simple comparison of
work. .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 The correct way to test if a message ID is considered to be in the future
is to do is to do
.Li (received_msgid - next_expected_msgid) modulus 2^16 .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. the next message they receive should be.
If they have received a message, it should be accepted and the next ID to 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 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. message ID was considered to be in the future (though it may be marked as
(Though it may be marked as a possible repeat.) a possible repeat).
If they have received an msgid request packet, they should set the next ID 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. to expect to a random value and send that value in the msgid packet.
.Pp .Pp
Implementations should not store the next message IDs to use in any Implementations should not store the next message IDs persistently.
persistent storage.
This is because if those values are out of date, messages sent by the This is because if those values are out of date, messages sent by the
implementation may be silently dropped. implementation may be silently dropped.
Storing next message ID to expect is safer, though a value more than 0x8000 Storing the next message ID to expect is safer, though a value of more than
out of date will lead to valid messages being dropped by the implementation 0x8000 out of date will lead to valid messages being dropped by the
itself. implementation itself.
.Ss Sending a message .Ss Sending a message
To send a message, the sender should first figure out the correct message To send a message, the sender should first figure out the correct message
ID to use. 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 transmission a few times.
The reference implementation, The reference implementation,
.Xr ethermess 1 , .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. around 1 to 1.5 seconds.
Implementations should randomize the retry timeout to reduce chances of Implementations should randomize the retry timeout to reduce chances of
packet collisions with other 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. failed to send.
.Pp .Pp
Once the message ID to use is known, the sender should send the message to 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. the recipient and wait for an ACK with the same message ID (note that the
(Note that the sender might receive ACKs for different messages.) sender might receive ACKs for different message).
The transmission should have a similar timeout and retry mechanism as with The transmission should have a similar timeout and retry mechanism as with
the msgid request. the msgid request.
If no matching ACK is received, the message should be considered to have 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 failed to send, but the implementation may keep it around in case an ACK
with its message ID is received later. with its message ID is received later.
.Pp .Pp
After sending the message, regardless of if an ACK was received for it or After sending the message, regardless of whether an ACK was received for
not, the sender should update its cached value of the next message ID to it or not, the sender should update its cached value of the next message
use when sending to the target to the message ID of the message that was ID to use when sending to the target to the message ID of the message that
send plus one. was sent plus one.
.Ss Changing one's own nick or status .Ss Changing one's own nick or status
When a user changes their nick or status, they should broadcast (send to 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. 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 Alternatively it may wait until it receives a keep-alive status broadcast
from all of its peers. from all of its peers.
.Ss Getting the status of a peer .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. whenever a status packet is received.
.Pp .Pp
If the cache doesn't have a given peer, the implementation may request the If the cache doesn't contain a given peer, the implementation may request
status using the status request packet targeted at that peer. the status using the status request packet targeted at that peer.
The timeout and retry mechanism should be designed to avoid spammyness and The timeout and retry mechanism should be designed to avoid spamminess and
minimize the possibility of packet collisions. minimize the possibility of packet collisions.
.Pp .Pp
An implementation may also implement a user-initiated status check by first 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 looking at the cache and then, regardless of whether it was in the cache or
not sending a status request packet. not, sending a status request packet.
This way the user can both receive an answer fast and in case the cached 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. value was outdated get the correct result once it arrives.
.Ss Starting up .Ss Starting up