@@ -120,7 +120,7 @@ Debug output can be adjusted using `%sift` and `%spew` `$task`'s.
120Ames datagram packets are handled as nouns internally by Arvo but as serial data
120Ames datagram packets are handled as nouns internally by Arvo but as serial data
121by Unix. In this section we describe how packets are formed, serialized, and relayed.
121by Unix. In this section we describe how packets are formed, serialized, and relayed.
123−### Serial format
123+### Packet format
125There is a 32-bit header followed by a variable width body.
125There is a 32-bit header followed by a variable width body.
@@ -161,7 +161,7 @@ required to send the message. To do this, it first `+jam`s the
161message, producing an atom. Ames checks how large the atom is, and if it is
161message, producing an atom. Ames checks how large the atom is, and if it is
162bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
162bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
163less. It then numbers each one - this is message 17, packet 12, this is message
163less. It then numbers each one - this is message 17, packet 12, this is message
164−17, packet 13, etc, so that when the receiver receives these packets it knows
164+17, packet 13, etc., so that when the receiver receives these packets it knows
165which number they are. Finally it encrypts each individual packet and enqueues
165which number they are. Finally it encrypts each individual packet and enqueues
166them to be sent along their stated flow.
166them to be sent along their stated flow.
@@ -170,24 +170,21 @@ for reconstruction, and also packets may get lost. So Ames does transmission
170control (the TC in TCP) to solve this problem. It makes sure that all packets
170control (the TC in TCP) to solve this problem. It makes sure that all packets
171eventually get through, and when the other side gets them it can put them in the
171eventually get through, and when the other side gets them it can put them in the
172correct order. If Ames doesn't get an ack on a packet then it will resend it
172correct order. If Ames doesn't get an ack on a packet then it will resend it
173−until it does. The timing on resending packets is called congestion control and
173+until it does. The logic for determining how many packets to send or re-send at what time is performed by an Ames-specific variant of TCP's "NewReno" congestion control algorithm.
174−works in the same fashion as TCP, namely exponential backoff.
176−Once all packets are received, the receiving Ames decrypts them, deserializes
175+As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.
177−them, and puts them back together to form a message.
181### Acks and Nacks
179### Acks and Nacks
183−In this section we discuss acks and nacks. Ack is short for acknowledgement, which are small
181+In this section we discuss acks and nacks. In Ames, an "ack", short for "acknowledgment", is a small packet attesting that a piece of information (either a packet or a whole message) was received. Ames makes use of
184−packets attesting that packets were successfully received. Ames makes use of
185−acks to maintain synchrony between two communicating parties. Nacks are 'negative
182+acks to maintain synchronization between two communicating parties. Nacks are 'negative
186acknowledgments' and are used when something goes wrong.
183acknowledgments' and are used when something goes wrong.
190−Every message (i.e. a `%plea`, `%boon`, or naxplanation) is split up by Ames into some number
187+Every message (i.e. a `%plea` or `%boon`) is split up by Ames into some number
191of _fragments_ that are 1kB in size or less. The fragments are then encrypted
188of _fragments_ that are 1kB in size or less. The fragments are then encrypted
192and encapsulated into
189and encapsulated into
193packets and sent along a flow. The message will be considered successfully
190packets and sent along a flow. The message will be considered successfully
@@ -195,10 +192,10 @@ received once the sender has received the appropriate set of acks in response,
195defined as follows.
192defined as follows.
197There are two types of acks: fragment acks and message acks. Acks are
194There are two types of acks: fragment acks and message acks. Acks are
198−not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
195+not considered messages, and thus are not `%plea`s or `%boon`s. Given a message split into N
199−required to appear in a particular order. Given a message split into N
200fragments, the sender of the message will expect N-1 fragment acks followed
196fragments, the sender of the message will expect N-1 fragment acks followed
197+by exactly one message ack (ignoring any duplicate packets, which are idempotent
201−by exactly one message ack. This is because the receiver
198+from the perspective of the application). This is because the receiver
202will send a fragment ack for the first N-1 packets it received, and what
199will send a fragment ack for the first N-1 packets it received, and what
203would have been the final fragment ack will instead be a message ack.
200would have been the final fragment ack will instead be a message ack.
@@ -206,7 +203,7 @@ Acks are considered to be part of the flow in which that `%plea` or
206`%boon` lives, as the packets containing their fragments and packets acking the
203`%boon` lives, as the packets containing their fragments and packets acking the
207receipt of those packets are considered to be what makes up a given message.
204receipt of those packets are considered to be what makes up a given message.
208Thus a message-level ack must be received before the next message on the flow
205Thus a message-level ack must be received before the next message on the flow
209−can begin. The full story is more complicated than this, see the section on
206+can begin. The full story is more complicated than this; see the section on
210[flows](#flows).
207[flows](#flows).
@@ -216,42 +213,46 @@ A nack indicates a negative acknowledgement to a `%plea`, meaning that the
216requested action was not performed.
213requested action was not performed.
218`%boon`s and naxplanations are never nacked.
215`%boon`s and naxplanations are never nacked.
219−Individual packets are never nacked, only complete `%plea` messages. This works
216+Individual packets are also never nacked, only complete `%plea` messages are.
220−because only complete packets ever make it to Ames, as malformed
217+Whether a malformed packet causes a `%plea` to be nacked depends on its content.
221−packets will be discarded by the Ames I/O module in the
218+In the case of an incorrect checksum or a failure to decrypt then Ames drops the
222−[King](#the-serf-and-the-king). Therefore there is no need for Ames to do
219+packet and it is as though it never happened. However, if the packet does
223−something like nack a packet whose checksum does not match the `+mug` of the
220+decrypt and has invalid ciphertext (i.e. something other than a jammed
224−body.
221+`$shutpacket` data structure), then Ames will nack the whole `%plea` since that
225−
222+indicates that the peer is misbehaving. Eventually Ames should also present a
223+warning to the user that the peer is untrustworthy.
226−A nack will be accompanied by a naxplanation, which is a third type of message
225+A nack will be accompanied by a naxplanation, which is a special type of`%boon`
227−separate from `%plea`s and `%boon`s. Ames won't give the vane that requested the
226+that uses its own `bone` (see [flows](#flows)). Ames won't give the vane that requested the
228initial `%plea` a nack until it also receives the naxplanation, which it will send to
227initial `%plea` a nack until it also receives the naxplanation, which it will send to
229the vane as a `%done` gift. Naxplanations may only be acked, never nacked.
228the vane as a `%done` gift. Naxplanations may only be acked, never nacked.
229+Furthermore, naxplanations can only ever be sent as a rejection of a `%plea` -
230+the receiver will never both perform a `%plea` and return a naxplanation.
231#### (N)ack packets
232#### (N)ack packets
233−The contents of a given (n)ack packet are deterministic. The `content` (i.e. the
234+A fragment ack's contents (before encryption) are a pure function of the
234−encrypted portion of the packet) of a fragment ack is obtained by encrypting the `+jam` of the
235following noun:
235following noun:
238[our-life her-life bone message-num fragment-num]
237[our-life her-life bone message-num fragment-num]
239+This means all re-sends of an ack packet will be bitwise identical to each other, unless one of the peers changes its encryption keys.
240Each datum in this noun is an atom with the aura `@ud` or an aura that nests
241Each datum in this noun is an atom with the aura `@ud` or an aura that nests
241under `@ud`.
242under `@ud`.
243Here, `our-life` refers to the [`life`](@/docs/glossary/breach), or revision
244Here, `our-life` refers to the [`life`](@/docs/glossary/breach), or revision
244number, of the acking ship's networking keys, and `her-life` is the `life` of
245number, of the acking ship's networking keys, and `her-life` is the `life` of
245−the ack-receiving ship's networking keys. `bone` is an opaque number identifying the flow, `message-num` denotes the number of the
246+the ack-receiving ship's networking keys. `bone` is an opaque number identifying
247+the flow. `message-num` denotes the number of the
246−message in the flow identified by `bone`, and
248+message in the flow identified by `bone`. `fragment-num` denotes the number of
247−`fragment-num` denotes the number of the fragment of the message identified by
249+the fragment of the message identified by `message-num` that is being acked.
248−`message-num` being acked.
250−A message (n)ack is an extended fragment ack that is obtained by encrypting the
251+A message (n)ack is a different kind of ack that is obtained by encrypting the
251`+jam` of the following noun:
252`+jam` of the following noun:
254−[our-life her-life bone message-num fragment-num ok=? lag=@dr]
255+[our-life her-life bone message-num ok=? lag=@dr]
256`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message
257`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message
257nack. In the future, `lag` will be used to
258nack. In the future, `lag` will be used to
@@ -263,22 +264,22 @@ describe the time it took to process a message, but for now it is always zero.
263Flows are asymmetric communication channels along which two ships send and
264Flows are asymmetric communication channels along which two ships send and
264receive packets, and all Ames packets are part of some flow.
265receive packets, and all Ames packets are part of some flow.
266−Flows are asymmetric in that one ship is always the sender of
267+To create a new flow, a ship sends a
267−`%plea`s and the other is always the sender of `%boon`s on a given flow. Thus ships will
268+`%plea` to another ship. Only the creator of the flow may send `%plea`s, and the
268−typically have multiple flows between them.
269+other party may only send `%boon`s. In this sense flows are asymmetric.
270The sequence of `%plea`s in a flow is totally ordered, though
271The sequence of `%plea`s in a flow is totally ordered, though
271the packets which make them up need not be. `%boon`s are totally ordered in the
272the packets which make them up need not be. `%boon`s are totally ordered in the
272same fashion, but there is not a coordinated ordering between `%plea`s and
273same fashion, but there is not a coordinated ordering between `%plea`s and
273`%boon`s in a given flow beyond the implicit one arising from the fact that a
274`%boon`s in a given flow beyond the implicit one arising from the fact that a
274−`%boon` is always a response to a `%plea`.
275+`%boon` is always a response to a `%plea`. A `%plea` can give rise to zero, one,
276Inside of Ames, each flow has four sequential opaque `@ud`s
278Inside of Ames, each flow has four sequential opaque `@ud`s
277called bones that are unique to that flow. Thus the flow itself is often
279called bones that are unique to that flow. Thus the flow itself is often
278−referred to by its first bone. The set of types of packets is partitioned into
280+referred to by its first bone. Each bone is a one-way street
279−four subsets, each of which is assigned a bone. Each bone is a one-way street
280for packets to travel along, so e.g. acks to packets making up a `%plea` are
281for packets to travel along, so e.g. acks to packets making up a `%plea` are
281−sent along different bones.
282+sent along a different bone than the `%plea`.
283We give an example of such a partition. Let flow 12 be a flow between `~bacbel-tagfeg` and `~worwel-sipnum` with
284We give an example of such a partition. Let flow 12 be a flow between `~bacbel-tagfeg` and `~worwel-sipnum` with
284`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the
285`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the
@@ -290,7 +291,7 @@ flow, and the types of packets for each bone are:
290 - bone 15, naxplanations to `~bacbel-tagfeg`.
291 - bone 15, naxplanations to `~bacbel-tagfeg`.
292Each bone is handled separately by congestion control, and this is the reason
293Each bone is handled separately by congestion control, and this is the reason
293−for their segregation. For example, say a two packet `%plea` is sent on bone 12,
294+for their segregation. For example, say a two-packet `%plea` is sent on bone 12,
294with `~bacbel-tagfeg` requesting to join a group on `~worwel-sipnum`.
295with `~bacbel-tagfeg` requesting to join a group on `~worwel-sipnum`.
295Then `~worwel-sipnum` can ack the first packet on bone 13, and then send a nack
296Then `~worwel-sipnum` can ack the first packet on bone 13, and then send a nack
296on bone 13 as well. A nack by itself contains no information as to why the nack
297on bone 13 as well. A nack by itself contains no information as to why the nack