@@ -293,91 +293,45 @@ will send an ack packet directly to `~bacbel-tagfeb`. Communication between the
293two ships will now be direct until one of them changes their IP address, port, or networking keys.
293two ships will now be direct until one of them changes their IP address, port, or networking keys.
296−## A typical successful Ames exchange
296+## The Serf and the King
298−In this section we follow along a typical Ames interaction at a fairly detailed
298+Urbit's functionality is split between the two binaries `urbit-worker` (sometimes
299−level. This interaction can be summarized as Ship A making a request (called a
299+called the Serf) and `urbit-king` (sometimes called the King). This division of
300−`%plea`) to Ship B to perform some task, and Ship B performing the requested
300+labor is currently not well-documented outside of the [Vere documents](@/docs/tutorials/vere/_index.md), but we summarize it here.
301−task and returning a few responses (called `%boon`s). For pedagogical reasons we
301+
302−will assume that everything in this journey happens as it ought to - no crashes,
302+In short, the Serf is the Nock runtime and so keeps track of the current state
303−dropped packets, adversaries, etc.
303+of Arvo as a Nock noun and updates the state by `%poke`ing it with nouns, and
304−
304+then informs the King of the new state. The King manages snapshots of the Arvo
305−### The scenario
305+state and handles I/O with Unix, among other things. The Serf only ever talks to
306−
306+the King, while the King talks with both the Serf and Unix.
307−While our story is generic and is roughly how every Ames interaction works, we
307+
308−will be using `publish` as an example. Our story is summarized as follows.
308+### Ames
310−`~bacbel-tagfeb` is running the Gall app Publish and would like to subscribe to a public notebook
310+The King has several submodules, one of them being an Ames I/O submodule. This
311−called `recipes` held on `~worwel-sipnum`. `~worwel` accepts the
311+submodule is responsible for wrapping outgoing Ames packets as UDP packets, and
312−request to subscribe from `~bacbel` and sends `~bacbel` each of the already
312+looking at incoming UDP packets handed to it by Unix to ensure that they are
313−existing posts on her `recipes` notebook.
313+valid Ames packets. It also maintains an incoming and outgoing packet queue.
315−### Stages
315+This division is summarized in the following diagram, describing how
316−
316+`~bacbel-tagfeb` requests a subscription to the `recipes` notebook of
317−We break our story into several stages, each of which will be detailed in its
317+`~worwel-sipnum` in the Publish app.
319−
319+<div style="text-align:center">
320−1. `~bacbel`'s Publish app initiates a request to subscribe to `~worwel`'s `recipes`
320+<img src="https://media.urbit.org/docs/arvo/packet.png">
322−2. `~bacbel`'s Gall receives the subscription request and packages it up as a `%plea` which
322+
323− is forwarded to `~bacbel`'s Ames.
323+Ames, as a part of Arvo, handles `+jam`ming, packetizing, encryption, and
324−3. `~bacbel`'s Ames opens a new flow with `~worwel-sipnum` and sends the `%plea`
324+forming Ames packets. Once it is ready to send an Ames packet, it `%give`s to
325− along it.
325+Unix a `%send` `gift` containing that packet. This will be a Nock noun
326−4. The `%plea` is turned into a message. `~bacbel`'s King now confirms that the message is
326+containing the `@tas` `%send` as well as the serialized packet.
327− a valid Ames message. It is then added to the queue of messages to be sent.
327+
328−5. The message arrives at the front of the queue and is broken into packets,
328+"Unix", in this case, is actually the King. The King receives the `%send`
329− each of which is encrypted (or are they encrypted right before they are sent?)
329+instruction, wraps the packet contained within as a UDP packet, and queues the
330−6. `~bacbel`'s King encapsulates the packets in UDP wrappers, which it then
330+UDP packet contained. Once it is time to send it (which will be determined by
331− passes to its Ames I/O submodule.
331+congestion control), it will go ahead and forward the packet to Unix's
332−7. Each UDP packet is sent to the IP address and port number for `~worwel`
332+networking interface, at which point it is no longer controlled by any part of Urbit.
333− previously known to `~bacbel` (how does it know this?)
333+
334−8. `~worwel`'s King receives each packet, confirms that they are Ames packets, and hands them to `~worwel`'s Serf to be
334+Now the receiving King is handed a UDP packet by Unix. The King removes the UDP
335− unencrypted.
335+wrapped and checks to see that it has received a valid Ames packet. If so, it
336−9. After each packet is received and successfully unencrypted, `~worwel`'s
336+`+cue`s the payload and wraps it as a `%hear` `note` and passes it to the Serf.
337− Ames returns a packet-level ack to `~bacbel` along the same flow that the
339−10. Once all packets for the message have been received and acked by `~worwel`'s
340− Ames, it reconstructs the packets into the Ames message containing `~bacbel`'s `%plea`.
341−11. `~worwel`'s Ames returns a message-level ack as a `%boon` to `~bacbel`.
342−12. `~worwel`'s Ames passes the `%plea` to `~worwel`'s Gall.
343−13. `~worwel`'s Gall unwraps the `%plea` and finds that it is a `%poke` to
344− Publish, and hands it to Publish.
345−14. `~worwel`'s Publish sees that the `%poke` is a `%watch` `task` from
346− `~bacbel` to subscribe to the `recipes` notebook. It adds the subscription
348−15. A `%watch-ack` is returned as a `%boon`?
349−16. `~worwel`'s Publish sends a `%watch-ack` to `~worwel`'s Ames, which is then converted
350− into a `%boon`s and returned to `~bacbel`.
351−17. `~bacbel` acks the `%boon`.
353−Refer to timluc's Gall guide's `poke.md` for more info on subscription dataflows
359−`[%pass /subscription/path %agent [~worwel-sipnum publish] [%watch /path/to/recipes]]`
364−Recall that a flow contains a bidirectional totally ordered sequence of messages
365−between the Ames vane of two ships. It is polarized in the sense that one ship
366−only sends `%plea`s and (n)acks, called the forward flow, and the other ship
367−only returns `%boon`s (which includes message-level (n)acks) and packet-level
368−acks, called the backwards flow. Note that while messages are totally ordered,
369−packets are not, and furthermore acks/nacks are not considered to be messages.
371−So packets within a message, and acks acknowledging those packets, may be
372−received in any order. However, the next message will not be released from the queue until
373−each packet has been acked and the entire message has been (n)acked as well.
376−`%plea`s to `~worwel-sipnum` (forward flow)
377−1. 3 packets encoding a `%watch /path/to/recipes` at `publish`
379−`%boon`s to `~bacbel-tagfeb` (backward flow)
380−1. 3 packet level acks
381−2. 1 `%done` message level ack
382−3. 1 `%watch-ack` as a `%boon`