@@ -25,6 +25,9 @@ protocol itself, including how to route incoming packets to the correct
25vane or app, is defined in Ames.
25vane or app, is defined in Ames.
27## Technical Overview
27## Technical Overview
28+This section summarizes the design of Ames. Beyond this section are deeper
29+elaborations on the concepts presented here.
28Ames extends [Arvo's](@/docs/tutorials/arvo/arvo.md) `%pass`/`%give` `move` semantics across the network.
31Ames extends [Arvo's](@/docs/tutorials/arvo/arvo.md) `%pass`/`%give` `move` semantics across the network.
30Ames receives packets as Arvo events and emits packets as Arvo
33Ames receives packets as Arvo events and emits packets as Arvo
@@ -78,7 +81,7 @@ large. A naxplanation can only give rise to a positive ack --
78never ack an ack, and never nack a naxplanation.
81never ack an ack, and never nack a naxplanation.
80Ames guarantees a total ordering of messages within a "flow",
83Ames guarantees a total ordering of messages within a "flow",
81−identified in other vanes by a duct and over the wire by a "bone":
84+identified in other vanes by a duct and over the wire by a `bone`:
82an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests
85an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests
83from the requesting ship to the responding ship and a FIFO queue
86from the requesting ship to the responding ship and a FIFO queue
84of `%boon`'s in the other direction.
87of `%boon`'s in the other direction.
@@ -140,7 +143,7 @@ The body is of variable length and consists of three parts in this order:
141 - The `@p` of the sending ship,
144 - The `@p` of the sending ship,
142 - The `@p` of the receiving ship,
145 - The `@p` of the receiving ship,
143− - The payload, which is the `+jam` (i.e. serialization) of the noun `[origin content]`.
146+ - The payload, which is the [`+jam`](@/docs/reference/libary/2p.md#jam) (i.e. serialization) of the noun `[origin content]`.
145 `origin` is the IP and port of the original sender if the packet was proxied
148 `origin` is the IP and port of the original sender if the packet was proxied
146 through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
149 through a relay and null otherwise. `content` is a noun that is either an encrypted ack or an
@@ -153,15 +156,13 @@ The body is of variable length and consists of three parts in this order:
153### Packeting
156### Packeting
155When Ames has a message to be sent it must first determine how many packets are
158When Ames has a message to be sent it must first determine how many packets are
156−required to send the message. To do this, it first `+jam`s (serializes) the
159+required to send the message. To do this, it first `+jam`s the
157message, producing an atom. Ames checks how large the atom is, and if it is
160message, producing an atom. Ames checks how large the atom is, and if it is
158bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
161bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
159less. It then numbers each one - this is message 17, packet 12, this is message
162less. It then numbers each one - this is message 17, packet 12, this is message
16017, packet 13, etc, so that when the receiver receives these packets it knows
16317, packet 13, etc, so that when the receiver receives these packets it knows
161which number they are. Finally it encrypts each individual packet and enqueues
164which number they are. Finally it encrypts each individual packet and enqueues
162−them to be sent along their stated flow. Encryption is the last step to happen
165+them to be sent along their stated flow.
163−before a packet is sent, since the receivers keys could potentially change in
164−the time between when
166Network packets aren't always received in order, so this numbering is important
167Network packets aren't always received in order, so this numbering is important
167for reconstruction, and also pakcets may get lost. So Ames does transmission
168for reconstruction, and also pakcets may get lost. So Ames does transmission
@@ -174,21 +175,64 @@ works in the same fashion as TCP, namely exponential backoff.
174Once all packets are received, the receiving Ames decrypts them, deserializes
175Once all packets are received, the receiving Ames decrypts them, deserializes
175them, and puts them back together.
176them, and puts them back together.
177−## Acks and nacks
178+### Acks
180+In this section we discuss acks, short for acknowledgements, which are small
181+packets attesting that packets were successfully received. Ames makes use of
182+acks maintain synchrony between two communicating parties. Nacks are 'negative
183+acknowledgments' and are used when something goes wrong. This topic is more
184+complicated and so discussion of them is deferred.
186+Every message (i.e. a `%plea` or a `%boon`) is split up by Ames into some number
187+of _fragments_ that are 1kB in size or less. The fragments are then encrypted
188+and encapsulated into
189+packets and sent along a flow. The message will be considered successfully
190+received once the sender has received the appropriate set of acks in response,
179−There are two types of acks: packet-level acks and message-level acks. They are
193+There are two types of acks: fragment acks and message acks. Acks are
180not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
194not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
181−required to appear in a particular order.
195+required to appear in a particular order. Given a message split into N
182−
196+fragments, the sender of the message will expect N-1 fragment acks followed
183−There is only one kind of nack, which may only be sent in response to a `%plea`,
197+by exactly one message ack. This is because the receiver
184−and requires a naxplanation.
198+will send a fragment ack for the first N-1 packets it received, and what
185−
199+would have been the final fragment ack will instead be a message ack.
186−Each packet forming part of a `%plea` or `%boon` must be acked, and can never be nacked.
200+
187−
201+Acks are considered to be part of the flow in which that `%plea` or
188−Each `%plea` must be acked or nacked. A nack requires a naxplanation message (a `%boon`)?
202+`%boon` lives, as the packets containing their fragments and packets acking the
189−
203+receipt of those packets are considered to be what makes up a given message.
190−Each `%boon` must be acked.
204+Thus a message-level ack must be received before the next message on the flow
208++$ ack-meat (each fragment-num [ok=? lag=@dr])
213+The contents of a given ack packet are deterministic. The `content` (i.e. the
214+encrypted portion of the packet) of a fragment ack is obtained by encrypting the `+jam` of the
218+[our-life her-life bone message-num fragment-num]
220+Each datum in this noun is an atom with the aura `@ud` or an aura that nests
223+Here, `our-life` refers to the [`life`](@/docs/glossary/breach), or revision
224+number, of the acking ship's networking keys, and `her-life` is the `life` of
225+the ack-receiving ship's networking keys. `bone` is an opaque number identifying the flow, `message-num` denotes the number of the
226+message in the flow identified by `bone`, and
227+`fragment-num` denotes the number of the fragment of the message identified by
228+`message-num` being acked.
230+A message ack is an extended fragment ack that is obtained by encrypting the
231+`+jam` of the following noun:
234+[our-life her-life bone message-num fragment-num ok=? lag=@dr]
193## A typical successful Ames exchange
237## A typical successful Ames exchange