@@ -150,8 +150,47 @@ The body is of variable length and consists of three parts in this order:
150 The sender and receiver live outside of the jammed data section to simplify
150 The sender and receiver live outside of the jammed data section to simplify
151 packet filtering for the interpreter.
151 packet filtering for the interpreter.
155+When 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
157+message, producing an atom. Ames checks how large the atom is, and if it is
158+bigger than a kilobyte it will split it into packets whose payloads are 1 kB or
159+less. It then numbers each one - this is message 17, packet 12, this is message
160+17, packet 13, etc, so that when the receiver receives these packets it knows
161+which 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
163+before a packet is sent, since the receivers keys could potentially change in
164+the time between when
166+Network packets aren't always received in order, so this numbering is important
167+for reconstruction, and also pakcets may get lost. So Ames does transmission
168+control (the TC in TCP) to solve this problem. It makes sure that all packets
169+eventually get through, and when the other side gets them is can put them in the
170+correct order. If Ames doesn't get an ack on a packet then it will resend it
171+until it does. The timing on resending packets is called congestion control and
172+works in the same fashion as TCP, namely exponential backoff.
174+Once all packets are received, the receiving Ames decrypts them, deserializes
175+them, and puts them back together.
179+There are two types of acks: packet-level acks and message-level acks. They are
180+not considered messages, and thus are not `%plea`s or `%boon`s, and so are not
181+required to appear in a particular order.
183+There is only one kind of nack, which may only be sent in response to a `%plea`,
184+and requires a naxplanation.
186+Each packet forming part of a `%plea` or `%boon` must be acked, and can never be nacked.
188+Each `%plea` must be acked or nacked. A nack requires a naxplanation message (a `%boon`)?
190+Each `%boon` must be acked.
154−## A typical successful Ames interaction
193+## A typical successful Ames exchange
156In this section we follow along a typical Ames interaction at a fairly detailed
195In this section we follow along a typical Ames interaction at a fairly detailed
157level. This interaction can be summarized as Ship A making a request (called a
196level. This interaction can be summarized as Ship A making a request (called a
@@ -166,7 +205,7 @@ While our story is generic and is roughly how every Ames interaction works, we
166will be using `publish` as an example. Our story is summarized as follows.
205will be using `publish` as an example. Our story is summarized as follows.
168`~bacbel-tagfeb` is running the Gall app Publish and would like to subscribe to a public notebook
207`~bacbel-tagfeb` is running the Gall app Publish and would like to subscribe to a public notebook
169−called `recipes` held on `~worwel-sipnum`'s ship. `~worwel` accepts the
208+called `recipes` held on `~worwel-sipnum`. `~worwel` accepts the
170request to subscribe from `~bacbel` and sends `~bacbel` each of the already
209request to subscribe from `~bacbel` and sends `~bacbel` each of the already
171existing posts on her `recipes` notebook.
210existing posts on her `recipes` notebook.
@@ -181,39 +220,61 @@ own section.
181 is forwarded to `~bacbel`'s Ames.
220 is forwarded to `~bacbel`'s Ames.
1823. `~bacbel`'s Ames opens a new flow with `~worwel-sipnum` and sends the `%plea`
2213. `~bacbel`'s Ames opens a new flow with `~worwel-sipnum` and sends the `%plea`
183 along it.
222 along it.
184−4. The `%plea` is turned into a message. `~bacbel`'s King now checks that the message is
223+4. The `%plea` is turned into a message. `~bacbel`'s King now confirms that the message is
185 a valid Ames message. It is then added to the queue of messages to be sent.
224 a valid Ames message. It is then added to the queue of messages to be sent.
1865. The message arrives at the front of the queue and is broken into packets,
2255. The message arrives at the front of the queue and is broken into packets,
187 each of which is encrypted (or are they encrypted right before they are sent?)
226 each of which is encrypted (or are they encrypted right before they are sent?)
1886. `~bacbel`'s King encapsulates the packets in UDP wrappers, which it then
2276. `~bacbel`'s King encapsulates the packets in UDP wrappers, which it then
189 passes to its Ames I/O submodule.
228 passes to its Ames I/O submodule.
1907. Each UDP packet is sent to the IP address and port number for `~worwel`
2297. Each UDP packet is sent to the IP address and port number for `~worwel`
191− previously known to `~bacbel`.
230+ previously known to `~bacbel` (how does it know this?)
192−8. `~worwel`'s King receives each packet and hands it to `~worwel`'s serf to be
231+8. `~worwel`'s King receives each packet, confirms that they are Ames packets, and hands them to `~worwel`'s Serf to be
193 unencrypted.
232 unencrypted.
194−9. After each packet is received and successfully unencrypted (?), `~worwel`'s
233+9. After each packet is received and successfully unencrypted, `~worwel`'s
195 Ames returns a packet-level ack to `~bacbel` along the same flow that the
234 Ames returns a packet-level ack to `~bacbel` along the same flow that the
196 packets came on.
235 packets came on.
19710. Once all packets for the message have been received and acked by `~worwel`'s
23610. Once all packets for the message have been received and acked by `~worwel`'s
198 Ames, it reconstructs the packets into the Ames message containing `~bacbel`'s `%plea`.
237 Ames, it reconstructs the packets into the Ames message containing `~bacbel`'s `%plea`.
199−11. `~worwel`'s Ames passes the `%plea` to `~worwel`'s Gall.
238+11. `~worwel`'s Ames returns a message-level ack as a `%boon` to `~bacbel`.
239+12. `~worwel`'s Ames passes the `%plea` to `~worwel`'s Gall.
200−12. `~worwel`'s Gall unwraps the `%plea` and finds that it is a `%poke` to
240+13. `~worwel`'s Gall unwraps the `%plea` and finds that it is a `%poke` to
201 Publish, and hands it to Publish.
241 Publish, and hands it to Publish.
202−13. `~worwel`'s Publish sees that the `%poke` is a `%watch` `task` from
242+14. `~worwel`'s Publish sees that the `%poke` is a `%watch` `task` from
203 `~bacbel` to subscribe to the `recipes` notebook. It adds the subscription
243 `~bacbel` to subscribe to the `recipes` notebook. It adds the subscription
204 to its state.
244 to its state.
205−14. A message level ack is sent from ??? along the same flow that the `%plea`
245+15. A `%watch-ack` is returned as a `%boon`?
206− was sent, informing `~bacbel` that the subscription was successful.
207−15. `~worwel`'s Publish sends %??? to `~worwel`'s Ames, which are then converted
246+16. `~worwel`'s Publish sends a `%watch-ack` to `~worwel`'s Ames, which is then converted
208− into `%boon`s and returned to `~bacbel`, etc.
247+ into a `%boon`s and returned to `~bacbel`.
248+17. `~bacbel` acks the `%boon`.
210Refer to timluc's Gall guide's `poke.md` for more info on subscription dataflows
250Refer to timluc's Gall guide's `poke.md` for more info on subscription dataflows
212#### Initial Request
252#### Initial Request
214`[%pass /subscription/path %agent [~worwel-sipnum publish] [%watch /path/to/recipes]]`
256`[%pass /subscription/path %agent [~worwel-sipnum publish] [%watch /path/to/recipes]]`
261+Recall that a flow contains a bidirectional totally ordered sequence of messages
262+between the Ames vane of two ships. It is polarized in the sense that one ship
263+only sends `%plea`s and (n)acks, called the forward flow, and the other ship
264+only returns `%boon`s (which includes message-level (n)acks) and packet-level
265+acks, called the backwards flow. Note that while messages are totally ordered,
266+packets are not, and furthermore acks/nacks are not considered to be messages.
268+So packets within a message, and acks acknowledging those packets, may be
269+received in any order. However, the next message will not be released from the queue until
270+each packet has been acked and the entire message has been (n)acked as well.
273+`%plea`s to `~worwel-sipnum` (forward flow)
274+1. 3 packets encoding a `%watch /path/to/recipes` at `publish`
276+`%boon`s to `~bacbel-tagfeb` (backward flow)
277+1. 3 packet level acks
278+2. 1 `%done` message level ack
279+3. 1 `%watch-ack` as a `%boon`