`%ames` commentary ================== `%ames` is our networking protocol. First we give commentary on the code, the algorithms involved, and the protocol. We trace through the code touched when a packet is sent, received, acknowledged, and that acknowledgment applied. This is fairly comprehensive, and contains many implementation details, but if you understand this, then you understand `%ames`. If you've scrolled down this page, you may be intimidated by the amount of Hoon code, especially if you are new to the language. Don't be afraid of it, you don't have to read any of it if you don't want to -- every interesting action the code takes is explained in plain English. In fact, if you are new to the language, this may be a good learning opportunity. Even if you don't understand every line of Hoon code, you'll hopefully be able to follow most lines. By the time you've worked through this, you'll have seen many common patterns and best practices. Hoon, much more than other languages, is best learned by reading and understanding large quantities of existing code. In this way, it is similar to learning a natural language. All of this code is in `arvo/ames.hoon`. After the commentary, we have reference documentation for all the data structures that are specific to `%ames`. If you see a data structure or a variable used that you don't recognize, search for it in the code, and it's very likely defined in one of these data structures. We recommend that another tab is kept open for easy access to the data structure reference documentation. The code for these is split between `arvo/ames.hoon` and `arvo/zuse.hoon`. The Lifecycle of a Packet (or, How a Packet Becomes Law) -------------------------------------------------------- Here, we will trace a packet as it makes its way through ames. There are actually two pathways through ames: the legacy path through `%want`, and the modern way, entered through `%wont`, with full end-to-end acknowledgments. Here we will only trace the modern way, though much of the path is the same for both. When an app (or a vane) wishes to send a packet to another ship, it must send a `%wont` card: [%wont p=sock q=path r=*] :: e2e send message This card takes three arguments. The `p` is a `sock`, that is, a pair of two ships, the first of which is the sender and the second is the receiver. But wait, you ask, why do I get to decide who is the sender? Can I fake like I'm someone else? The reason is that there are potentially multiple ships on the same pier, and the kernel can send a message from any of them. If you attempt to send a message from a ship not on your pier, then ames will refuse to send it. If you hack around in your own copy of ames to go ahead and send it anyway, then the other ship will reject it because your key is bad. Only send messages from yourself. The `q` is a path, representing the place on the other side that you want to receive your message. It is approximately equivalent to a port number. Messages on the same path are guaranteed to arrive in the same order as they were sent. No such guarantees are made across paths. The `r` is the actual data that you are sending. As the type implies, this can be an arbitrary noun, and it will be transferred to the receiver exactly as-is, in a well-typed way. Of course, this is data that is sent over the wire, so be careful not to send anything too massive unless you're willing to wait. But enough about the interface. Grepping in ames.hoon for `%wont`, we find that it appears in exactly two places: at its definition in `++kiss`, and in `++knob`, where it is handled. We see that we go directly into `++wise:am`. ++ wise :: wise:am |= [soq=sock hen=duct cha=path val=* ete=?] :: send a statement ^- [p=(list boon) q=fort] zork:zank:(wool:(ho:(um p.soq) q.soq) hen cha val ete) The inputs to this gate are exactly the sort of thing you'd expect. In particular, everything in the `%wont` gate is here plus the calling duct so that we know where to send the acknowledgment and `ete` to determine if we're going to do the modern end-to-end acknowledgments. The actual line of code looks intimidating, but it's really not all that bad. Working from the inside out, the call to `++um` sets up our domestic server, and the call to `++ho` sets up our knowledge about the neighbor we're sending to. From the outside, `++zork` and `++zank` just apply the changes made to our `++um` and `++am` cores, respectively. If you're familiar with the common idiom of `++abet`, that's all this is. The code predates the widespread usage of that name. The interesting part, then, is in `++wool:ho:um:am`. Let's look at the code. ++ wool :: wool:ho:um:am |= [hen=duct cha=path val=* ete=?] :: send a statement ^+ +> =+ ^= rol ^- rill =+ rol=(~(get by ryl.bah) cha) ?~(rol *rill u.rol) =+ sex=sed.rol :: ~& [%tx [our her] cha sex] =. ryl.bah %+ ~(put by ryl.bah) cha rol(sed +(sed.rol), san (~(put by san.rol) sex hen)) =+ cov=[p=p:sen:gus q=clon:diz] %+ wind [cha sex] ?: ete [%bund q.cov cha sex val] [%bond q.cov cha sex val] This is slightly more complicated, but it's still not all that bad. Our inputs, at least, are fairly obvious. If you glance at the code for a second, you'll see that `++wind:ho:um:am` seems to be able to send a message, or `++meal`, given a `++soup`. This gate, then, just sets up the things we need to for `++wind` to do its job. We first get `rol`, which is a `++rill`, that is, a particular outbound stream. This stream is specific to the path on which we're sending. If the path hasn't been used before, then we create it. We let `sex` be the number of messages we've already sent on this path. Then, we update the outbound stream by incrementing the number of messages sent and placing an entry in `san.rol` that associates the message number with the `duct` that sent the message. This allows us to give the acknowledgment to the one who sent the message. We let `cov` be the current life of our crypto and our neighbor's crypto. At the moment, we only need our neighbor's life, which we put into the meal. Finally, we call `++wind:ho:um:am` with the `++soup` of the path and message number and the `++meal` of the payload itself. For end-to-end acknowledged messages, we use `%bund`. [%bund p=life q=path r=@ud s=*] :: e2e message Looking at how we create the `%bund`, we can easily see what each field is for. Following the trail a little further, we go to `++wind:ho:um:am`. ++ wind :: wind:ho:um:am |= [gom=soup ham=meal] :: ~& [%wind her gom] ^+ +> =^ wyv diz (zuul:diz now ham) =^ feh puz (whap:puz now gom wyv) (busk xong:diz feh) `++wind` does three things: it (1) encodes the message into a list of possibly-encrypted packets, (2) puts the message into the packet pump, and (3) sends any packets that are ready to be sent. Yes, our nice little linear run of each gate calling exactly one other interesting gate is over. We'll go in order here. `++zuul:lax:as:go` is the what converts a `++meal` into a list of actual, 1KB packets. ++ zuul :: zuul:lax:as:go |= [now=@da ham=meal] :: encode message ^- [p=(list rock) q=_+>] =< weft ++ wasp :: null security ++ weft :: fragment message ++ wisp :: generate message For organizational purposes, `++zuul` constructs an internal core with three arms. `++wasp` encodes the meal into an atom with no encryption. `++wisp` encodes a meal with possible encryption (else it simply calls `++wasp`). `++weft` takes the result of `++wisp` and splits it into actual packets. ++ wasp :: null security ^-([p=skin q=@] [%none (jam ham)]) This simply jams the meal, wrapping it with the `skin` of `%none`, meaning no encryption. Since `++wisp` is a little long, we'll go through it line-by-line. ++ wisp :: generate message ^- [[p=skin q=@] q=_..wisp] `++wisp` produces a pair of a `skin` and an atom, which is the meal encoded as a single atom and possibly encrypted. ?: =(%carp -.ham) [wasp ..wisp] If the meal that we're encoding is a `%carp`, then we don't encrypt it. A `%carp` meal is a partial meal, used when a message is more than 1KB. Since the entire message is already encrypted, we don't need to encrypt each packet individually again. ?: !=(~ yed.caq.dur) ?> ?=(^ yed.caq.dur) :_ ..wisp :- %fast %^ cat 7 p.u.yed.caq.dur (en:r:cluy q.u.yed.caq.dur (jam ham)) If we have a symmetric key set up with this neighbor, then we simply use it. The skin `%fast` is used to indicate a symmetric key. ?: &(=(~ lew.wod.dur) |(=(%back -.ham) =(%buck -.ham))) [wasp ..wisp] If we do not yet have our neighbor's will, then there is no way that we can seal the message so that only they may read it. If what we're sending is an acknowledgment, then we go ahead and just send it in the clear. =^ tuy +>.$ ?:(=(~ lew.wod.dur) [*code +>.$] (griz now)) If we don't have our neighbor's will, then we "encrypt" with a key of 0. If we do have their will, then we generate a new symmetric key that we will propose. :_ ..wisp =+ yig=sen =+ bil=law.saf :: XX send whole will =+ hom=(jam ham) `yig` will be the life and engine for our current crypto. `bil` is our will. `hom` is the meal encoded as a single atom. ?: =(~ lew.wod.dur) :- %open %^ jam [~ `life`p.yig] bil (sign:as:q.yig tuy hom) If we do not have our neighbor's will, then we send our current life along with our will and the message. The message itself is "signed" with a key of 0. :- %full =+ cay=cluy %^ jam [`life`p.cay `life`p.yig] bil (seal:as:q.yig pub:ex:r.cay tuy hom) -- :: --zuul:lax:as:go If we do have our neighbor's will, then we send our perception of their current life, our current life, our will, and the message. The message is sealed with their public key so that only they can read our message. Once we have the message encoded as an atom, `++weft` goes to work. ++ weft :: fragment message ^- [p=(list rock) q=_+>.$] =^ gim ..weft wisp :_ +>.$ ^- (list rock) We're going to produce a list of the packets to send. First, we use the aforementioned `++wisp` to get the message as an atom. =+ wit=(met 13 q.gim) ?< =(0 wit) `wit` is the number of 1KB (2\^13 bit) blocks in the message. We assert that there is at least one block. ?: =(1 wit) =+ yup=(spit [our her] p.gim q.gim) [yup ~] If there is exactly one block, then we just call `++spit` to turn the message into a packet. We'll explain what `++spit` does momentarily. =+ ruv=(rip 13 q.gim) =+ gom=(shaf %thug q.gim) =+ inx=0 If there is more than one block, then we rip it into blocks in `ruv`. `gom` is a hash of the message, used as an id. `inx` is the number of packets we've already made. |- ^- (list rock) ?~ ruv ~ =+ ^= vie %+ spit [our her] wasp(ham [%carp (ksin p.gim) inx wit gom i.ruv]) :- vie $(ruv t.ruv, inx +(inx)) Here we package each block into a packet with `++spit` and produce the list of packets. ++ spit :: cake to packet |= kec=cake ^- @ =+ wim=(met 3 p.p.kec) =+ dum=(met 3 q.p.kec) =+ yax=?:((lte wim 2) 0 ?:((lte wim 4) 1 ?:((lte wim 8) 2 3))) =+ qax=?:((lte dum 2) 0 ?:((lte dum 4) 1 ?:((lte dum 8) 2 3))) =+ wix=(bex +(yax)) =+ vix=(bex +(qax)) =+ bod=:(mix p.p.kec (lsh 3 wix q.p.kec) (lsh 3 (add wix vix) r.kec)) =+ tay=(ksin q.kec) %+ mix %+ can 0 :~ [3 1] [20 (mug bod)] [2 yax] [2 qax] [5 tay] == (lsh 5 1 bod) This is how we turn a message into a real packet. This has the definition of the packet format. `wim` is the length of the sending ship, and `dum` is the length of the receiving ship. There are only five possibilities for each of those, corresponding to carriers, cruisers, destroyers, yachts, and submarines. These are encoded in `yax` and `qax` as 0, 0, 1, 2, and 3, respectively. Thus, `wix` and `vix` are the number of bytes that must be reserved for the ship names in a packet. Next, we construct `bod` by simply concatenating the sending ship, the receiving ship, and the body of the message. Then, we get the encryption mechanism from `++skin`, which may be a 0, 1, 2, or 3, and put it in `tay`. Next, we concatenate together, bit by bit, some final metadata. We use three bits for our protocol number, which is incremented modulo eight when there is a continuity breach or the protocol changes. We use the final twenty bits of a hash of the body (which, we suppose, makes it a twenty bit hash) for error-checking. We use two bits to tell how much room is used in the body for the sending ship, and another two bits for the receiving ship. Finally, we use five bits to store the encryption type. Note that since there are only two bits worth of encryption types, there are three unused bits here. This adds up to 32 bits of header data. Finally, we concatenate this onto the front of the packet. Thus, we can summarize the packet header format as follows. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Proto| Hash of Body |yax|qax| Crypto | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ After this, there are `yax` bits of the sender name, `qax` bits of the receiver name, and up to 8192 bits of data. Thus, the maximum size of a packet is achieved in a message between two submarines with 8192 bits of data. This will require 32+128+128+8192 = 8480 bits, or 1060 bytes. This concludes our discussion of `++zuul:lax:as:go`. If you recall from `++wind:ho:um:am`, the list of packets from `++zuul` is passed into `++whap:pu` to update the packet pump and get any packets that can be sent immediately. ++ whap :: whap:pu |= [now=@da gom=soup wyv=(list rock)] :: send a message ^- [(list rock) _+>] =. pyz (~(put by pyz) gom (lent wyv)) =. +> |- ^+ +>.^$ ?~ wyv +>.^$ %= $ wyv t.wyv nus +(nus) diq (~(put by diq) (shaf %flap i.wyv) nus) puq (~(put to puq) [nus `soul`[gom 0 | ~2000.1.1 i.wyv]]) == (harv now) First, we put into `pyz` the id for this message and the number of its packets that have not yet been acknowledged, which is of course the total number of packets since we haven't even sent the packets. For every packet, we change three things in the state (`++shed`) of our packet pump: (1) we increment `nus`, the number of packets sent; (2) we put the packet number into `diq` keyed by a hash of the packet; and (3) we put the packet into the packet queue, with the basic metadata of its id `gom`, 0 transmissions, not live yet, last sent in the year 2000, and the packet itself. Finally, we harvest the packet pump. ++ harv :: harv:pu |= now=@da :: harvest queue ^- [(list rock) _+>] ?: =(~ puq) [~ +>(rtn ~)] ?. (gth caw nif) [~ +>] =+ wid=(sub caw nif) =| rub=(list rock) =< abet =< apse |% `++harv` contains a core for most of its work. The meat is in `++apse`. First, though, it sets itself up. If there aren't any packets in the queue, then we simply do nothing except set `rtn`, our next timeout, to nil because we don't have any packets that may need to be retransmitted. If we have more live (that is, sent and unacknowledged) packets than our window size, then we don't do anything. Otherwise, we let `wid` be the width of our remaining packet window, and we initialize `rub` to nil. `rub` will be the list of packets that are ready to be sent. We then call `++apse` and pass the result to `++abet`. `++apse` decides which packets are ready to be sent. ++ apse ^+ . ?~ puq . ?: =(0 wid) . => rigt =< left ?> ?=(^ puq) ?: =(0 wid) . ?. =(| liv.q.n.puq) . :: ~& [%harv nux.q.n.puq p.n.puq] %_ . wid (dec wid) rub [pac.q.n.puq rub] nif +(nif) liv.q.n.puq & nux.q.n.puq +(nux.q.n.puq) lys.q.n.puq now == If there are no remaining packets to send, or if we've filled the packet window, do nothing. We call `++rigt` and `++left` to process the left and right branches of the packet queue. Now we assert that the queue is not empty, and we again check that we haven't filled the packet window. We will operate on the head of the queue. If the packet is live, then do nothing. Otherwise, we go ahead and send it. To send, we (1) decrement `wid`, our packet window width; (2) cons the packet onto the `rub`, which will be returned as the list of packets to send; (3) increment `nif`, the number of live packets; (4) set the packet to be live; (5) increment the number of transmissions of the packet; and (6) set the last sent time of the packet to now. ++ left ?> ?=(^ puq) ^+(. =+(lef=apse(puq l.puq) lef(puq [n.puq puq.lef r.puq]))) ++ rigt ?> ?=(^ puq) ^+(. =+(rig=apse(puq r.puq) rig(puq [n.puq l.puq puq.rig]))) These do exactly what you would expect: they traverse the packet queue so that `++apse` gets called recursively through it. Finally, `++abet` gets called, which resolves the changes. ++ abet ?~ rub [~ +>.$] [(flop rub) +>.$(rtn [~ (add rto now)])] This returns the packets that we wish to send, and it updates the timeout so that we know when to try resending unacknowledged packets. This concludes our discussion of `++whap:pu`. To finish `++wind:ho:um:am`, we just need to delve into `++busk:ho:um:am`. But wait, in the call to `++busk`, the first argument is `xong:diz`. What is this? This, my dear reader, is one more detour, this time into `++xong:lax:as:go`. ++ xong :: xong:lax:as:go ^- (list ship) :: route unto =+ [fro=xen too=xeno] =+ ^= oot ^- (list ship) =| oot=(list ship) |- ^+ oot ?~ too ~ ?: (lien fro |=(a=ship =(a i.too))) ~ [i.too $(too t.too)] :: ~& [%xong-to [our her] (weld oot ?>(?=(^ fro) t.fro))] (weld oot ?>(?=(^ fro) t.fro)) This gets the list of intermediate ships needed to get a packet from us to our neighbor. First, we get `fro` and `too`, the "canons" of ourself and our neighbor, respectively. What is this "canon", you ask? A canon is simply a ship plus its "ancestors", as defined by `++sein`. For example, the canon of `~hoclur-bicrel` is: ~hoclur-bicrel/try=> (saxo ~hoclur-bicrel) ~[~hoclur-bicrel ~tasruc ~tug] If we follow the algorithm in `++xong`, we see that we are simply creating a list of ships that form a path from our neighbor to ourself. Essentially, we look through the canon of our neighbor until we find something in our own cannon -- a common ancestor. Or, if we are from different carriers, then there is no common ancestor. We then weld this onto the tail of our own canon. In the end, this is simply a list of possible ships to try to route via to get to our neighbor, ordered by preferability (that is, closeness to our neighbor). We will end up trying, in order, to find a lane to these. Now, we can finally get to `++busk:ho:um:am`. ++ busk :: busk:ho:um:am |= [waz=(list ship) pax=(list rock)] :: send packets %_ +> bin |- ^+ bin ?~ pax bin $(pax t.pax, bin (weld (flop (wist:diz now waz ~ i.pax)) bin)) == Thankfully, `++busk` is fairly simple. We go through the list of packets and convert them to `++boon`s with `++wist:lax:as:go`. These boons are placed into `bin`, and they end up getting processed by `++clop` (this happens in `++knob`). ++ wist :: wist:lax:as:go |= $: now=@da :: route via waz=(list ,@p) ryn=(unit lane) pac=rock == ^- (list boon) ?: =(our her) [[%ouzo *lane pac] ~] ?~ waz ~ =+ dyr=?:(=(her i.waz) dur (gur i.waz)) ?. ?& !=(our i.waz) ?=(^ lun.wod.dyr) == $(waz t.waz) :_ ?: ?=(%ix -.u.lun.wod.dyr) $(waz t.waz) ~ :+ %ouzo u.lun.wod.dyr ?: &(=(i.waz her) =(~ ryn)) pac =+ mal=(jam `meal`[%fore her ryn pac]) %- spit ^- cake :* [our i.waz] ?~ yed.caq.dyr [%none mal] :- %fast %^ cat 7 p.u.yed.caq.dyr (en:crua q.u.yed.caq.dyr mal) == This takes a sample of the current time, the list of ships that we just generated, a lane if we already know it, and the packet itself. First, if we are sending a message to ourself, then we simply create a `%ouzo` boon with a bunted lane. Otherwise, if there are no routing candidates, there is nothing we can do, so we return nil. Next, we get the `dore` of the first routing candidate. If we're looking at the neighbor to whom we're trying to send the message, then we simply use the `dore` that we already have. Otherwise, we get a default `dore`. If we're the first routing candidate, or if we have don't have a lane to this candidate, then we skip this candidate and move on to the next one. If we have only a provisional ip address, then we try to send on it, but we also try to send on later routing candidates as well. Otherwise, we only send on this one candidate. Finally, we create the actual `%ouzo` boon. The lane is the one from our `dore`. If we're sending it directly to our intended recipient, and we haven't been told to use a specific lane, then we just send the packet directly. Otherwise, we wrap it in a little `%fore` meal, telling the intermediary to whom we wish it to be sent. If we have already set up a symmetric key with the intermediary, then we encrypt it with that. Otherwise, we send it in the clear. Now, if you recall, we have traced all the way through from the beginning when, in `++knob`, the `%wont` card was handled by a call to `++wise`. There is only one more step before the packet is finally sent. Looking in `++knob`, we see that the resultant list of boons is passed into `++clop`, which will execute the correct actions and return a list of moves. In `++clop`, we see the handling of each specific boon. The one we are interested in is `%ouzo`, since that is the only one we have sent thus far. %ouzo :: ~& [%send now p.bon `@p`(mug (shaf %flap q.bon))] :_ fox [[gad.fox [%give %send p.bon q.bon]] ~] Very simply, we give a `%send` gift along the special duct that goes straight into the bowels of unix. This is the last stop before we drop into vere, and later libuv. And then... the world. The packet, after its creation, embarks on a journey across physical time and space into the great unknown. Hurtling through fiber-optic cables at hundreds of thousands of kilometers per second, it finally arrives at our neighbor's network adapter. The adapter tells unix, unix tells libuv, libuv tells vere, and vere sends a `%hear` kiss to ames. And now we reenter the kernel. The `%hear` kiss goes straight to `++knob`, just as did the `%wont` kiss earlier. %hear (~(gnaw am [now fox]) %good p.kyz q.kyz) Here, though, we call `++gnaw:am` to process the packet. The arguments to `++gnaw` are the same as those to the `%hear` kiss: the lane on which the packet was received and the packet itself. The other argument is just `%good`, which is a `++cape` saying that we expect the packet to succeed. If a formal error occurs, then since we have a transactional event system, the `%hear` event will never be considered to have actually happened, and unix will send a `%hole` kiss so that we may send a negative acknowledgment. ++ gnaw :: gnaw:am |= [kay=cape ryn=lane pac=rock] :: process packet ^- [p=(list boon) q=fort] ?. =(2 (end 0 3 pac)) [~ fox] =+ kec=(bite pac) ?: (goop p.p.kec) [~ fox] ?. (~(has by urb.ton.fox) q.p.kec) [~ fox] =< zork =< zank %- ~(chew la:(ho:(um q.p.kec) p.p.kec) kay ryn %none (shaf %flap pac)) [q.kec r.kec] First, we check the protocol number. If it is not correct, then we simply ignore the packet entirely. Otherwise, we parse the packet with `++bite`, which converts a packet atom into a `cake`, that is, a triple of the `sock` (pair of sender and receiver), the `skin` (encryption type), and the data. ++ bite :: packet to cake |= pac=rock ^- cake =+ [mag=(end 5 1 pac) bod=(rsh 5 1 pac)] =+ :* vez=(end 0 3 mag) :: protocol version chk=(cut 0 [3 20] mag) :: checksum wix=(bex +((cut 0 [23 2] mag))) :: width of receiver vix=(bex +((cut 0 [25 2] mag))) :: width of sender tay=(cut 0 [27 5] mag) :: message type == ?> =(2 vez) ?> =(chk (end 0 20 (mug bod))) :+ [(end 3 wix bod) (cut 3 [wix vix] bod)] (kins tay) (rsh 3 (add wix vix) bod) This is exactly the inverse of `++spit`. Note that here we check both the protocol number and the hash, crashing on error. Remember that a crash will result in a negative acknowledgment being sent. Continuing in `++gnaw`, we see that if the intended recipient is not on our pier, then we drop the packet. If we've gotten this far, then we wish to process the packet. Recall that `++ho` and `++um` set up the domestic server and foreign client cores, respectively, and that `++zork` and `++zank` resolve any changes to these cores. The new stuff here, then, is the `++la` core and the `++chew` arm. The `++la` sets up a core for this particular packet, containing the current success/failure `cape`, the lane it was sent on, the encryption type, and a hash of the packet, used as an id. `++chew` is called with the encryption type and the message itself. It contains a little helper core inside of it, which starts immediately with `++apse`. ++ apse ^+ +>.$ =+ oub=bust:puz =+ neg==(~ yed.caq.dur.diz) =. +>.$ east =+ eng==(~ yed.caq.dur.diz) =+ bou=bust:puz =. bin ?. &(oub !bou) bin :_(bin [%wine [our her] " is ok"]) =. bin ?. &(neg !eng) bin :_(bin [%wine [our her] " is your neighbor"]) +>.$ First, we let `oub` be true if our neighbor hasn't been responding to us for more than sixteen seconds. Let `neg` be true if we haven't yet proposed a symmetric key, meaning that we haven't yet corresponded with this ship, so they are not our neighbor. Next, we run `++east`, which we'll go into in just a minute. We now do the same two checks and store the results in `eng` and `bou`. If our neighbor has, like the prodigal son, returned after an extended absense, then we send a `%wine` boon as the proverbial fatted calf, which is simply printed out to the console. Likewise, if we are meeting one with whom we have never had the pleasure of acquainting ourselves, we send a message to the console to that effect. We skipped over `++east`, which contains the meat of the processing. It first decrypts the message, then calls `++chow:la:ho:um:am` with the resultant meal. We'll go through each of the four cases in turn, but first since each one calls `++bilk:pu`, we'll take a brief detour. ++ bilk :: bilk:pu |= now=@da :: inbound packet ^+ +> =+ trt=(mul 2 rtt) %= +>.$ rue [~ now] rto trt rtn ?~(puq ~ [~ (add now trt)]) == This updates the timing information in our packet pump. `rue`, the last time we have heard from this neighbor, is set to now. `rto`, the retransmit timeout is set to twice the current ping time, and if there is anything in the packet queue, then we reset the next timeout, since we've just heard a message. Back to `++east`. %none =. puz (bilk:puz now) (chow ((hard meal) (cue msg))) The simplest case is when the encryption type is `%none`. We first call `++bilk` to update the packet pump, then we cue (unjam) the message into a meal. We hard cast it into a meal -- if the cast fails, then we do want to crash since someone is sending us malformed data. Finally, we send the result to `++chow` for interpretation and handling. %fast =+ [mag=`hand`(end 7 1 msg) bod=(rsh 7 1 msg)] =+ dey=(kuch:diz mag) ?~ dey ~& [%bad-key her mag] +>.$ :: ignore unknown key =. puz (bilk:puz now) =^ key diz u.dey (chow(aut sin) ((hard meal) (cue (dy:q:sen:gus key bod)))) For symmetric encryption, we first get the `hand`, which is the hash of the symmetric key. We pass it to `++kuch:lax:as:go`, which returns the key if we either have used it before or we have proposed it. If we have proposed it, then we change its status from proposed to real. If `++kuch` fails, then we drop the packet and print out a `%bad-key` message. Otherwise, we call `++bilk` as before to update the packet pump and pass into `++chow` the decrypted data. %full =+ mex=((hard ,[p=[p=life q=life] q=will r=@]) (cue msg)) =. diz (deng:diz q.mex) =+ wug=cluy:diz ?> =(q.p.mex p.wug) =+ gey=(sev:gus p.p.mex) =+ mes=(need (tear:as:q.gey pub:ex:r.wug r.mex)) =. diz (wasc:diz p.mes) =. puz (bilk:puz now) (west(msg q.mes)) For sealed asymmetric encryption, we first take off the the layer of data that gives us the life and will of our neighbor, and we apply try to extend their former will with the new data. `++deng` will fail if this is impossible. Next, we get our most current understanding of our neighbor's crypto, and we verify that it's the same life as what they're sending. Then, we get our own crypto from `++sev` and decrypt the message with the public key from our neighbor's crypto. We register the proposed symmetric key, update the packet pump, and call `++west`, which simply casts the message to a meal and calls `++chow`, reporting any error. %open =+ mex=((hard ,[p=[~ q=life] q=will r=@]) (cue msg)) =. diz (deng:diz q.mex) =+ wug=cluy:diz ?> =(q.p.mex p.wug) =+ mes=(need (sure:as:r.wug *code r.mex)) =. puz (bilk:puz now) (west(msg mes)) Finally, for signed asymmetric encryption, we, as before, take off the layer of data that gives us the life and will of our neighbor. This time, of course, we do not get our own crypto -- only that of our neighbor. The rest you have seen. We call `++deng` to extend the will, we verify that their crypto life is what we think it ought to be, we "decrypt" the data, we update the packet pump, and we call `++west` to call `++chow`. ++ chow :: chow:la:ho:um:am |= fud=meal :: interpret meal ^+ +> =. diz ?:(=(%none aut) diz (wast:diz ryn)) (dine fud) Here, if the message was encrypted at all, then we call `++wast:lax:as:go`, which simply updates the lane (route) to our neighbor (unless we're given a provisional route). This ensures that we always have the most direct possible path to them. We've been handling this meal for so long, we've almost forgotten what we want to do with it. The telos is of any meal to be dined on. We will choose out the cases here that are important to our current investigation. %fore =+ ^= lyn ^- lane ?~ q.fud ryn ?. ?=(%if -.u.q.fud) u.q.fud [%ix +.u.q.fud] :: u.q.fud ?: =(our p.fud) (emit %mead lyn r.fud) =+ zid=(myx:gus p.fud) (emir (wist:zid now xong:zid [~ lyn] r.fud)) Forwarding is the simplest case, since we've seen all the arms before, except perhaps `++emit` and `++emir`, which simply take a boon or list of boons respectively and queue them up to be handled when the core resolves. If we're told to forward a packet to ourselves, then we emit a `%mead` boon which simply sends another `%hear` kiss to ourselves with the data. Otherwise, we try to find a route to the recipient, as before. %carp =+ zol=(~(get by olz.weg) s.fud) ?^ zol cock(kay u.zol) =^ neb nys.weg =+ neb=(~(get by nys.weg) s.fud) ?^ neb [u.neb nys.weg] =+ neb=`bait`[(kins p.fud) 0 r.fud ~] [neb (~(put by nys.weg) s.fud neb)] ?> (lth q.fud p.r.neb) ?> =((kins p.fud) p.neb) ?> =(r.fud p.r.neb) =+ doy=`(unit ,@)`(~(get by q.r.neb) q.fud) ?^ doy cock => ^+ . %= . q.r.neb (~(put by q.r.neb) q.fud t.fud) q.neb +(q.neb) == :: ~& [%carp q.fud s.fud q.neb p.r.neb] ?: =(q.neb p.r.neb) =: nys.weg (~(del by nys.weg) s.fud) olz.weg (~(put by olz.weg) s.fud kay) == (golf p.neb r.neb) =. +>.$ cock +>.$(nys.weg (~(put by nys.weg) s.fud neb)) Here, we have received a partial message, and we're just assembling the individual packets into a message. Most of this code is fairly algorithmic, so we'll just hit the high points. In the beginning, we check if we've already received this message, and if so, we resend the acknowledgment. Remember, "always ack a dupe, never ack an ack". In `nys.weg` we keep track of an incoming set of partial packets, indexed by the `flap` hash that comes with every packet. We check to see if we have already received this partial message, and if so we acknowledge it. Otherwise, we put it in `nys.weg` unless this is the last message, in which case we ack the last partial message, move the complete message into `olz.weg`, and call `++golf`, which assembles the message and calls `++chew`, to start the dance again with the complete message. %bund :: ~& [%bund q.fud r.fud] ?> =(p:sen:gus p.fud) (deer q.fud r.fud ?-(kay %dead ~, %good [~ s.fud])) What if we're just receiving a regular old, garden variety message? We call `++deer` with the data from the message. If we already know that the message processing will fail (that is, if we got a `%hole` card from unix rather than a `%hear` card), then we don't even send the data at all. Remember, if a packet fails to process, it's as if it never even arrived, except that we send a negative acknowledgment. ++ deer :: deer:la:ho:um:am |= [cha=path num=@ud dut=(unit)] :: interpret message ^+ +> =+ rum=(fall (~(get by raz.bah) cha) *race) %= +>.$ +> ?. (gte num did.rum) :: always ack a dup (cook (~(get by bum.rum) num) cha ~ ryn dam) ?: dod.rum (coat cha rum(mis (~(put by mis.rum) num [kay ryn dam dut]))) %= +>.+>.$ raz.bah %+ ~(put by raz.bah) cha rum(mis (~(put by mis.rum) num [kay ryn dam dut])) == == First, we get the race for this particular triple of sender, receiver, and path, creating it if it doesn't exist. If we've already acked the message, then we resend the ack. Note that `did.rum` is the number of packets we acknowledged, positively or negatively while `bum.rum` is a map of message numbers to negative acknowledgments. Thus, if a message number is less than `did.rum`, then if it's in `bum.rum` then it was negatively acknowledged, otherwise it's postively acknowledged. Thus, we are constant in space with the number of successful messages and linear in the number of failed messages. We'll document `++cook` later on, but suffice it to say that it sends an acknowledgment. It is to end-to-end acknowledgments what `++cock` is to packet-level acknowledgments. If we are still processing a message (that is, `dod.rum` is false), then we simply put this message in the map of misordered packets to be processed when their time comes. "Processing a message" in this case means that we've received the message and notified the correct application, but we're still waiting for the application-level acknowledgment. Otherwise, we're ready for a packet, so we process it. ++ coat :: coat:ho:um:am |= [cha=path rum=race] :: update input race ^+ +> =+ cun=(~(get by mis.rum) did.rum) ?~ cun +>.$(raz.bah (~(put by raz.bah) cha rum)) ?. =(%good p.u.cun) +>.$ ?> ?=(^ s.u.cun) %= +>.$ raz.bah (~(put by raz.bah) cha rum(dod |)) bin :_ bin :^ %mulk [our her] `soap`[[p:sen:gus clon:diz] cha did.rum] u.s.u.cun == First, we grab the message we want to process and store it in `cun`. If it's a good packet, then we change `dod.rum` to false, meaning that we're in the middle of processing a packet and should not start processing another one. We also put a `%mulk` boon into the queue so that, when it all resolves, we send a mesage to the intended recipient application. The boon contains the sender, the receiver, the identity of the message, and the message itself. This bubbles up all the way back to `++knob`, where we were handling the `%hear` card. Following the logic in `++knob`, we can see that the boons get sent into `++clop` to be turned into actual arvo-level moves. We've been here before, if you recall, when we handled the `%cake` boon to send a message. Now, we're handling the `%mulk` boon, which is unfortunately slightly more complicated. %mulk :: ~& [%mulk p.bon q.bon] ?> ?=([@ @ *] q.q.bon) ?> ?=(%q i.q.q.bon) ?+ i.t.q.q.bon ~& %mulk-bad :_ fox :~ :- (claw p.p.bon) [%sick %wart p.bon i.t.q.q.bon t.t.q.q.bon r.bon] == %ge :: %gall request ?> ?=([@ ~] t.t.q.q.bon) =+ app=`term`(need ((sand %tas) i.t.t.q.q.bon)) =+ ^= pax :+ (scot %p p.p.bon) (scot %p q.p.bon) q.q.bon :_ fox [hen %pass pax %g %rote p.bon app r.bon]~ %gh :: %gall response ?> ?=([@ ~] t.t.q.q.bon) =+ app=`term`(need ((sand %tas) i.t.t.q.q.bon)) =+ ^= pax :+ (scot %p p.p.bon) (scot %p q.p.bon) q.q.bon :_ fox [hen %pass pax %g %roth p.bon app r.bon]~ == We're dispatching messages based on the prefix of their path. Since only `%gall` apps use end-to-end acknowledgments at the moment, every path must have at least two elements, and the first one must be `%q`. Beyond that, we handle the `/q/ge` and `/q/gh` cases for gall requests and responses, respectively. In both cases, we require the next term in the path to be the name of the intended recipient `%gall` app. Thus, a message to `/q/ge/talk` for example, will send a message to the talk app. We then send a message to the app itself. The message is either a `%rote` or a `%roth` for a request and a response, respectively. The content is the `rook` or `roon` that was sent (stored in `r.bon`), but we don't actually handle that at all here. That's completely a `%gall`-level thing. We're just the messenger. Notice the path we send this over. We encode the sender, the receiver, and the path over which it was sent. This fully specifies the `race` so that when the app gives us the acknowledgment we know where to send it. We now have another interlude. We have entrusted our precious data, so carefully guarded and guided from the app on that far-away ship, to our local app. It has the ability to do whatever it pleases with it. It may take a significant amount of time to process. When the message has been handled by this app, though, it must produce an acknowledgment. Our final task is to deliver this acknowledgment to the sending app. We should describe here what exactly these oft-mentioned acknowledgments actually consist of. There are two kinds of acknowledgments: positive and negative. A positive acknowledgment contains no data other than its existence. A negative acknowledgment may optionally include a reason for said negativity. Formally, a negative acknowledgment is an `ares`, which is a unit pair of a term and a list of tanks. If this is null, this is simply a failure with no associated information. If the pair exists, the term is a short error code that is usually both human and computer readable. For example, if you try to send a message to a valid `%gall` app that doesn't have any `++poke` to handle it, then `%gall` will give a negative acknowledgment with error term `%poke-find-fail`. The list of tanks is a human-readable description of the error. This often contains a stack trace. At any rate, all this information is returned to the sending app on the other end of the wire. After this brief interlude, our story resumes in `++knap`, where we receive responses. In particular, a `%mean` indicates a negative acknowledgment while a `%nice` indicates a positive acknowledgment. ?(%mean %nice) ?> ?=([@ @ @ *] tea) =+ soq=[(slav %p i.tea) (slav %p i.t.tea)] =+ pax=t.t.tea =+ ^= fuy =< zork =< zank %^ ~(rack am [now fox]) soq pax ?-(+<.sih %mean `p.+.sih, %nice ~) => %_(. fox q.fuy) =| out=(list move) |- ^- [p=(list move) q=_+>.^$] ?~ p.fuy [(flop out) +>.^$] =^ toe fox (clop now hen i.p.fuy) $(p.fuy t.p.fuy, out (weld (flop toe) out)) Recall the format of the path we sent the message on, and you'll understand why `soq` and `pax` are the sender/receiver pair and path on which the message was sent. The rest of this is structured much like `++knob`, so we call `++rack:am` and send the resulting boons to `++clop`. Business as usual. ++ rack :: rack:am |= [soq=sock cha=path cop=coop] :: e2e ack =+ oh=(ho:(um p.soq) q.soq) =. oh (cook:oh cop cha ~) (cans:oh cha) First, we set up `++um` and `++ho`, as we've done twice before, for our domestic and foreign servers, respectively. The other two things are new, though. Well, `++cook` is not actually new, but we delayed the explanation saying only that it sends an acknowledgment. The time has come. ++ cook :: cook:ho:um:am |= [cop=coop cha=path ram=(unit ,[ryn=lane dam=flap])] ^+ +> :: acknowledgment =+ rum=(need (~(get by raz.bah) cha)) =+ lat=(~(get by mis.rum) did.rum) ?: &(?=(~ lat) ?=(~ ram)) ~&(%ack-late-or-redundant +>.$) =+ ^- [ryn=lane dam=flap] ?^ ram [ryn.u.ram dam.u.ram] ?< ?=(~ lat) [q r]:u.lat =. raz.bah ?^ ram raz.bah %+ ~(put by raz.bah) cha rum(dod &, bum ?~(cop bum.rum (~(put by bum.rum) did.rum u.cop))) =^ roc diz (zuul:diz now [%buck cop dam ~s0]) (busk(diz (wast:diz ryn)) xong:diz roc) If we are acknowledging a message that we have already acked, the `ram` will contain the new lane and flap to send the duplicate ack to. This happens if we call `++cook` in `++deer`, but it doesn't happen from `++rack`. If there is no message waiting to be acknowledged and we're not given an explicit lane and flap (that is, we're not sending a duplicate ack), then the app must have sent us multiple acknowledgments. We do the only sensible thing we can do and drop all acknowledgments after the first, printing a message. This is, in fact, an error, so it could be argued that we ought to crash. Whatever you do, don't depend on this not crashing. First, we grab the race specified by the given path, and we get the most recent in-order message, which must be the one which is being acknowledged. Then, we decide which lane/flap to respond on/to. Basically, in the usual case we respond on the lane through which the initial message was sent, which is stored along with the other packet information in `mis.rum`, since it has to be remembered across calls to ames. However, if we receive a duplicate message, then we must respond to the new message. It's quite possible the reason the other acknowledgment didn't get returned was that the lane between the ships was broken. At any rate, we update the race by saying that we've finished processing this packet (unless we're sending a duplicate ack) and, if we're sending a negative acknowledgment, putting the negative ack into `bum.rum` so that we can resend it if necessary. We encode our new message, updating the packet pump, with `++zuul`, as before, and we send it off with `++busk`, routed via `++wast` to one of the ships in `++xong`. Of course, in practice, we don't even look at the ships in `++xong` because we already have a lane directly to our neighbor (the one over which they sent their message to us). We glossed over the actual message we're sending back. We're sending a `%buck` meal, which is an acknowledgment. The `cop` specifies whether this is a positive or a negative ack, `dam` specifies the message we're acknowledging, and the `~s0` is a placeholder for the processing time required. This time is neither calculated (though it is hopefully obvious how to do so) nor used at present, but this information may be used in the future for improved congestion control. Since the round-trip time for an end-to-end acknowledged packet includes the processing time on the other end, most common congestion control algorithms will stumble when some messages take much longer to process than others. As noted, though, this is simply an opportunity for improvement -- our congestion control algorithms are relatively naive at the moment. Recall that `++busk` calls `++wist` to put the actual `%ouzo` boon in the queue, which gets handled by `++clop` to actually send the message. This is the same pipeline as sending any other message, so we'll refer you to the explanation above if you've forgotten it. The last thing we need to do on this ship is move on to the next packet in the queue if there is one. If you recall, in `++rack` after the call to `++cook` there was a call to `++cans:ho:um:am`. ++ cans :: cans:ho:um:am |= cha=path =+ rum=(need (~(get by raz.bah) cha)) =. rum %= rum did +(did.rum) mis (~(del by mis.rum) did.rum) == (coat cha rum) This is very simple. We increment the number of packets that we've acknowledged on this race and we delete the packet that we just acknowledged from the set of misordered packets. Then, we call `++coat` again to process the next packet if we've already received it. And that's it for this. The acknowledgment now travels the same path that its forebearer, the original message, once tread, but this time not into the great unknown. The weary traveler is seeking out its familial roots, finding the app from whom sprung forth the original message way back in paragraph three. When it arrives at the network adapter of its ancestors, the adapter tells unix, unix tells libuv, libuv tells vere, and vere sends a `%hear` kiss to ames. Once more into the kernel. The `%hear` kiss is handled in `++knob` as before, leading to `++gnaw`, going over to `++chew`, `++apse`, `++chow`, and eventualy to `++dine`. We've seen most of the cases in `++dine`, but we haven't yet looked at the handling of this `%buck` meal. %buck =. +> ?.(=(%full aut) +> cock) :: finish key exch +>(..la (tock p.fud q.fud r.fud)) We send a packet level acknowledgment if we're finishing a key exchange, else we call `++tock` to process the acknowledgment. This will get a little involved, so if you don't much care about how exactly an acknowledgment happens, just know that the result gets gifted as a `%woot` card back to the app who sent it. For those brave souls who wish to see this thing through to the end, it's once more into the breach. ++ tock :: tock:ho:um:am |= [cop=coop fap=flap cot=@dr] :: e2e ack by hash ^+ +> =^ yoh puz (bick:puz now fap) =. +>.$ ?~ p.yoh +>.$ =^ hud +>.$ (done p.u.p.yoh q.u.p.yoh) ?~ hud +>.$ %= +>.$ bin :_ bin `boon`[%cake [our her] [[p:sen:gus clon:diz] u.p.yoh] cop u.hud] == (busk xong:diz q.yoh) We're going to work through this one a little backwards since it's mostly fairly simple except the call to `++bick:pu`. In fact, we'll just skip `++bick` for the moment and finish the rest. If `++bick` succesfully acks the message, then we call `++done`. ++ done :: done:ho:um:am |= [cha=path num=@ud] :: complete outgoing ^- [(unit duct) _+>] =+ rol=(need (~(get by ryl.bah) cha)) =+ rix=(~(get by san.rol) num) ?~ rix [~ +>.$] :- rix %_ +>.$ ryl.bah (~(put by ryl.bah) cha rol(san (~(del by san.rol) num))) == This very simply gets the rill (the outgoing counterpart to a race, if you recall), pulls out of the map of outstanding messages the duct over which the original message was sent, and produces this duct while deleting that entry from the map of outstanding messages. Going back to `++tock`, we now have the duct we need to return the result over. We do the very sensible thing and put a `%cake` boon in the queue to be processed later by `++clop`. In `q.yoh` we have a list of messages that may need to be sent, which we pass to `++busk` to send, as usual. When an acknowledgment arrives, that may trigger other messages immediately. This often happens when sending more messages than the width of the logical window since for congestion control reasons another message cannot be sent until some of the earlier ones have been acknowledged. We'll look at the processing of the `%cake` boon in `++clop` before we get back to talking about `++bick`. %cake :_ fox :~ [s.bon %give %woot q.p.bon r.bon] == We very simply give, along the duct we found above, a `%woot` card with the ship who sent us the ack and the ack itself. This allows the application to decide what to do about the result. In case of a failure, we usually either resend the message or display it to the user. Sometimes, we recognize the error term and handle it internally. In any case, the decision of how to handle the acknowledgment is entirely up to the application. Our job is done. Well, except that we skipped `++bick:pu`. Let's go back to that. ++ bick :: bick:pu |= [now=@da fap=flap] :: ack by hash ^- [[p=(unit soup) q=(list rock)] _+>] =+ sun=(~(get by diq) fap) ?~ sun [[~ ~] +>.$] =. diq (~(del by diq) fap) =^ gub +>.$ (bock now u.sun) =^ yop +>.$ (harv now) [[gub yop] +>.$] If you recall, in `++whap:pu` we created the packet pump's representation of the message, which included putting the message into `diq`, which maps from packet hashes to packet sequence numbers. Thus, `u.sun` is the sequence number of this particular message. We delete this message from `diq` since we have now received an ack for it. We call `++bock` to perform the ack by sequence number. We call `++harv` to harvest the packet queue, sending any messages that are now able to be sent. In `++bock`, there are three arms we haven't seen before: `++bine`, `+wept`, and `++beet`. We'll describe each of these before we get to `++bock`. `++bine` looks scariest. ++ bine :: bine:pu |= [now=@da num=@ud] :: apply ack ^- [(unit soup) _+>] ?~ puq !! ?. =(num p.n.puq) ?: (gth num p.n.puq) =+ lef=$(puq l.puq) [-.lef +.lef(puq [n.puq puq.lef r.puq])] =+ rig=$(puq r.puq) [-.rig +.rig(puq [n.puq l.puq puq.rig])] =: rtt ?. &(liv.q.n.puq =(1 nux.q.n.puq)) rtt =+ gap=(sub now lys.q.n.puq) :: ~& [%bock-trip num (div gap (div ~s1 1.000))] (div (add (mul 2 rtt) gap) 3) nif (sub nif !liv.q.n.puq) == =+ lez=(dec (need (~(get by pyz) gom.q.n.puq))) =^ gub pyz ?: =(0 lez) [[~ gom.q.n.puq] (~(del by pyz) gom.q.n.puq)] [~ (~(put by pyz) gom.q.n.puq lez)] :- gub +>.$(puq ~(nap to puq)) The first few lines are simply looking through the packet queue until we find the correct packet to ack. This is basic queue manipulation that operates directly on the treap structure of the queue. If you understand treap queues, the logic is easy to follow. Otherwise, just trust us that by the time we get to the `=:`, the packet with sequence number `num` is on the top of the packet queue (that is, at `n.puq`). We first update the round-trip time. If the packet is either not alive or had to be transmitted more than once, then we don't have any reliable way of calculating the round-trip time since we're unsure of exactly which transmission was acknowledged. Otherwise, the round-trip time is the difference between now and when the packet was last sent. We set `rtt` by a little weighted average where the previous smoothed RTT is weighted twice as much as the RTT of the current packet. Thus, `(2*rtt+gap)/3`. This gives us a nice smooth RTT that is somewhat resilient to outlier data while still being responsive to our ever-changing world. If the packet wasn't already dead, then we decrement the number of live packets, which may allow more packets to be sent. We decrement the number of unacknowledged packets in our `pyz` for this particular message. If you recall, this was set in `++whap` to the number of packets required to send a message. If that was the last packet in the messge that needed to be acked, then we delete the messgae reference from `pyz` and produce the id of the message. Otherwise, we simply update `pyz` with the new number of unacked messages. In either case, we remove the packet from the packet queue. ++ wept :: wept:pu |= [fip=@ud lap=@ud] :: fip thru lap-1 =< abet =< apse |% ++ abet +>.$ ++ apse ^+ . ?~ puq . ?: (lth p.n.puq fip) ?~(l.puq . left) ?: (gte p.n.puq lap) ?~(r.puq . rigt) => rigt =< left ?> ?=(^ puq) ?.(liv.q.n.puq . .(nif (dec nif), liv.q.n.puq |)) :: ++ left ?> ?=(^ puq) ^+(. =+(lef=apse(puq l.puq) lef(puq [n.puq puq.lef r.puq]))) ++ rigt ?> ?=(^ puq) ^+(. =+(rig=apse(puq r.puq) rig(puq [n.puq l.puq puq.rig]))) -- The algorithm is a simple case of traversing the packet queue. Essentialy, we mark as dead all packets in the queue between `fip` and `(dec lap)`. We also update `nif`, the number of live packets. Lest you mourn too much the passing of these packets, know that they shall soon rise again. Recall that in `++bick` after the call to `++bock` we call `++harv`. This will resend the packets that have just been labeled dead. ++ beet :: beet:pu ^+ . :: advance unacked =- +(nep ?~(foh nus u.foh)) ^= foh |- ^- (unit ,@ud) ?~ puq ~ ?: (lte p.n.puq nep) $(puq l.puq) =+ rig=$(puq r.puq) ?^(rig rig [~ p.n.puq]) Here we search for the next expected packet number. Basically, we search the queue for the leftmost packet whose number is greater than the current `nep`. If we don't find any such packet, we just use the total number of packets sent. We can now dive into `++bock`, our last arm. ++ bock :: bock:pu |= [now=@da num=@ud] :: ack by sequence ^- [(unit soup) _+>] =^ gym +> (bine now num) :- gym ?: (gth num nep) =+ cam=(max 2 (div caw 2)) :: ~& [%bock-hole num nep cam] beet:(wept(nep num, cag cam, caw cam) nep num) =. caw ?: (lth caw cag) +(caw) (add caw !=(0 (mod (mug now) caw))) ?: =(num nep) :: ~& [%bock-fine num nif caw cag] beet :: ~& [%bock-fill num nif caw cag] +>.$ First, we call `++bine` to apply the ack to the packet pump information. We produce `gym`, which, if it exists, is the id of the packet that was acked. If we received an ack for a packet later than the one we expected, then we halve the logical packet window and kill all the earlier packets so that they may be resent. Otherwise, we possibly increase the congestion window. If the window is less than the congestion threshold, then we increment the size of the window. Otherwise, we only increment one out of every `caw` times. If we received an ack for the packet we expected, then we simply advance `nep` with `++beet`. If we received an ack for a packet earlier than we expected, we do nothing. It may be hard to believe, but we are, in fact, done. The message has been sent, received, acknowledged, and the acknowledgment has been returned to the original sender. We hope it's clear that, while the process has been somewhat involved, the algorithms are not all that complicated. If you've read this far, you know `%ames`. The only other code involves initialization, timeouts, and the like. Below, we give detailed reference documentation for the data models involved. Data Models ----------- ### `++fort`, formal state ++ fort :: formal state $: %0 :: version gad=duct :: client interface hop=@da :: network boot date ton=town :: security zac=(map ship corn) :: flows by server == :: This is the state of our vane. Anything that must be remembered between calls to ames must be stored in this state. `%0` is the version of the ames state model itself. If the data model `++fort` changes, then this number needs to be incremented, and an adapter must be written to upgrade the old state into the new state. Note that this is the version number of the model itself, not the contents. When the data changes, there is of course no need to change this. `gad` is a `duct` over which we send `%send` cards to unix. This card is initialized when unix sends a `%barn` card as vere starts up. Vere treats this duct specially -- don't send anything weird over it. `hop` is the network boot date. This is set when the `%kick` card is sent by vere on start up. `ton` is a `++town`, where we store all of our security/encryption state. Note that this is shared across all ships on a pier. `zac` is a map of ships to `++corn`. This stores all the per-ship state. The keys to this map are the ships on the current pier. ### `++town`, all security state ++ town :: all security state $: lit=@ud :: imperial modulus any=@ :: entropy urb=(map ship sufi) :: all keys and routes fak=? :: == :: This is the security state of our pier. `lit` is unused. `any` is 256 bits of entropy. This entropy is used and updated in exactly two places: when we send a `%junk` card, and when we generate a new symmetric key in `++griz:lax:as:go`. When it is updated, it is updated by a SHA-256 hash of the current time and the old value of the entropy. `urb` is a map of ships to `++sufi`. This is where we store all the per-ship state for the pier. The keys to this map are the ships on the current pier. `fak` is true if we are on a fake network. This disables certain security checks so that anyone may run a fake `~zod`. This is used only for development. To use, run vere with the `-F` option (and the `-I ~zod` option for a fake `~zod`). ### `++sufi`, domestic host ++ sufi :: domestic host $: hoy=(list ship) :: hierarchy val=wund :: private keys law=will :: server will seh=(map hand ,[p=ship q=@da]) :: key cache hoc=(map ship dore) :: neighborhood == :: This is the security state of a domestic server. `hoy` is a list of the ships directly above us in the hierarchy of ships. For example, for `~hoclur-bicrel`, this would be `~tasruc` and `~tug`. See `++sein`. `val` is a list of our private keys. `law` is our certificate, which is a list of the XXX `seh` `hoc` is a map of ships to `++dore`. The stores all the security informatoin about foreign ships. The keys to this map are the neighbors (ships we have been in contact with) of this domestic server. ### `++wund`, private keys ++ wund (list ,[p=life q=ring r=acru]) :: mace in action This is a list of our own private keys, indexed by life. The key itself is the `++ring`, and the `++acru` is the encryption engine. We generate the `++acru` from the private key by calling `++weur`. Thus, we can at any time regenerate our `++wund` from a `++mace`. The current crypto is at the head of the list and can be accessed with `++sen:as:go`. ### `++ring`, private key ++ ring ,@ :: private key This is a private key. The first byte is reserved to identify the type of cryptography. Lower-case means public key, upper-case means public key, and the letter identifies which `++acru` to use. ### `++pass`, public key ++ pass ,@ :: public key This is a public key. The first byte is reserved to identify the type of cryptography. Lower-case means public key, upper-case means public key, and the letter identifies which `++acru` to use. ### `++mace`, private secrets ++ mace (list ,[p=life q=ring]) :: private secrets This is a list of the our private keys, indexed by life. From this we can generate a `++wund` for actual use. ### `++skin`, encoding stem ++ skin ?(%none %open %fast %full) :: encoding stem This defines the type of encryption used for each message. `%none` refers to messages sent in the clear, `%open` refers to signed messages, `%full` refers to sealed messages, and `%fast` refers to symmetrically encrypted messages. See `++acru` for details. ### `++acru`, asymmetric cryptosuite ++ acru :: asym cryptosuite $_ ^? |% :: opaque object ++ as ^? :: asym ops |% ++ seal |=([a=pass b=@ c=@] _@) :: encrypt to a ++ sign |=([a=@ b=@] _@) :: certify as us ++ sure |=([a=@ b=@] *(unit ,@)) :: authenticate from us ++ tear |= [a=pass b=@] :: accept from a *(unit ,[p=@ q=@]) :: -- :: ++ de |+([a=@ b=@] *(unit ,@)) :: symmetric de, soft ++ dy |+([a=@ b=@] _@) :: symmetric de, hard ++ en |+([a=@ b=@] _@) :: symmetric en ++ ex ^? :: export |% ++ fig _@uvH :: fingerprint ++ pac _@uvG :: default passcode ++ pub *pass :: public key ++ sec *ring :: private key -- ++ nu ^? :: reconstructors |% ++ pit |=([a=@ b=@] ^?(..nu)) :: from [width seed] ++ nol |=(a=@ ^?(..nu)) :: from naked ring ++ com |=(a=@ ^?(..nu)) :: from naked pass -- -- This is an opaque interface for a general asymmetric cryptosuite. Any form of asymmetric cryptography can be dropped in to be used instead of the default. Right now, there are two cryptosuites, `++crua`, which is your standard RSA, and `++crub`, which is elliptic curve crypto but is mostly stubbed out at the moment. #### `++as:acru`, asymmetric operations ++ as ^? :: asym ops |% ++ seal |=([a=pass b=@ c=@] _@) :: encrypt to a ++ sign |=([a=@ b=@] _@) :: certify as us ++ sure |=([a=@ b=@] *(unit ,@)) :: authenticate from us ++ tear |= [a=pass b=@] :: accept from a *(unit ,[p=@ q=@]) :: -- :: This is the core that defines the standard asymmetric cryptography operations. `++seal:as:acru` allows us to send a message encrypted with someone's public key so that only they may read it. If Alice seals a message with Bob's public key, then she can be sure that Bob is the only one who can read it. This is associated with the `++skin` `%full`. `++sign:as:acru` allows us to sign a message with our private key so that others can verify that we sent the message. If Alice signs a message with her private key, then Bob can verify with her public key that it was indeed Alice who sent it. This is associated with the `++skin` `%open`. `++sure:as:acru` is the dual to `++sign:as:acru`. It allows us to verify that a message we have received is indeed from the claimed sender. If Alice sends a message with her private key, then Bob can use this arm to verify that it was indeed Alice who sent it. This is associated with the `++skin` `%open`. `++tear:as:acru` is the dual to `++seal:as:acru`. It allows us to read a message that we can be sure is only read by us. If Alice seals a message with Bob's public key, then Bob can use this arm to read it. This is associated with the `++skin` `%full`. #### `++de:acru`, `++dy:acru`, and `++en:acru`, symmetric encryption/decryption ++ de |+([a=@ b=@] *(unit ,@)) :: symmetric de, soft ++ dy |+([a=@ b=@] _@) :: symmetric de, hard ++ en |+([a=@ b=@] _@) :: symmetric en Symmetric encryption is associated with the `++skin` `%fast`. `++de:acru` decrypts a message with a symmetric key, returning `~` on failure and `[~ u=data]` on success. `++dy:acru` decrypts a message with a symmetric key, crashing on failure. This should almost always be defined as, and should always be semantically equivalent to, `(need (de a b))`. `++en:acru` encrypts a message with a symmetric key. #### `++ex:acru`, exporting data ++ ex ^? :: export |% ++ fig _@uvH :: fingerprint ++ pac _@uvG :: default passcode ++ pub *pass :: public key ++ sec *ring :: private key -- `++fig:ex:acru` is our fingerprint, usually a hash of our public key. This is used, for example, in `++zeno`, where every carrier owner's fingerprint is stored so that we can ensure that carriers are indeed owned by their owners `++pac:ex:acru` is our default passcode, which is unused at present. `++pub:ex:acru` is the `++pass` form of our public key. `++sec:ex:acru` is the `++ring` form of our private key. #### `++nu:acru`, reconstructors ++ nu ^? :: reconstructors |% ++ pit |=([a=@ b=@] ^?(..nu)) :: from [width seed] ++ nol |=(a=@ ^?(..nu)) :: from naked ring ++ com |=(a=@ ^?(..nu)) :: from naked pass -- These arms allow us to reconstruct a `++acru` from basic data. `++pit:nu:acru` constructs a `++acru` from the width of our intended key and seed entropy. This is usually used in the initial construction of the `++acru`. `++nol:nu:acru` constructs a `++acru` from a "naked ring", meaning a `++ring` without the initial byte identifying the type of crypto. There is often a helper arm that that wraps this; see `++weur` for `++crua` and `++wear` for `++crub`. `++com:nu:acru` constructs a `++acru` from a "naked pass", meaning a `++ring` without the initial byte identifying the type of crypto. There is often a helper arm that that wraps this; see `++haul` for `++crua` and `++hail` for `++crub`. ### `++will`, certificate ++ will (list deed) :: certificate This is a list of deeds associated with the current ship. There should be an item in this list for every ship from this point up in the hierarchy times the number of lives that each ship has had. For example, \~hoclur-bicrel may have a will with three items: one for itself, one for \~tasruc (who issued \~hoclur-bicrel's deed) and one for \~tug (who issued \~tasruc's deed). ### `++deed`, identity ++ deed ,[p=@ q=step r=?] :: sig, stage, fake? `p` is the signature of a particular deed, which is a signed copy of `q`. `q` is the stage in the identity. `r` is true if we're working on a fake network, where we don't check that the carrier fingerprints are correct. This allows us to create fake networks for development without interfering with the real network. ### `++step`, identity stage ++ step ,[p=bray q=gens r=pass] :: identity stage This is a single stage in our identity. Thus, this is specific to a single life in a single ship. Everything in here may change between lives. `p` `q` `r` is the public key for this stage in the identity. ### `++bray` ++ bray ,[p=life q=(unit life) r=ship s=@da] :: our parent us now XXX ### `++gens`, general identity ++ gens ,[p=lang q=gcos] :: general identity `p` is the IETF language code for the preferred language of this identity. This is unused at the moment, but in the future text should be localized based on this. `q` is the description of the ship. ### `++gcos`, identity description ++ gcos :: id description $% [%czar ~] :: 8-bit ship [%duke p=what] :: 32-bit ship [%earl p=@t] :: 64-bit ship [%king p=@t] :: 16-bit ship [%pawn p=(unit ,@t)] :: 128-bit ship == :: This is the description of the identity of a ship. Most types of identity have a `@t` field, which is their human-readable name. The identity of a `%duke` is more involved. A `%czar`, a carrier, is a ship with an 8-bit address. Thus, there are only 256 carriers. These are at the top of the namespace hierarchy, and the fingerprint of each carrier is stored in `++zeno`. These are the "senators" of Urbit. A `%king`, a cruiser, is a ship with a 16-bit address. Thus, there are 65,536 cruisers. Each carrier may issue 256 cruisers. These are the infrastructure of Urbit. A `%duke`, a destroyer, is a ship with a 32-bit address. Thus, there are 4,294,967,296 destroyers. Each cruiser may issue 65,536 cruisers. These are the individuals of Urbit. A `%earl`, a yacht, is a ship with a 64-bit address. Thus, there are 18,446,744,073,709,551,616 yachts. Each destroyer may issue 4,294,967,296 yachts. These are the devices of Urbit. A `%pawn`, a submarine, is a ship with a 128-bit address. Thus, there are a lot of submarines. The chance of random name collision is negligible, so submarines are not issued by any ship. They must simply assert their presence, and they are all considered children of \~zod. This is the underworld of Urbit, where anonymity reigns supreme. ### `++what`, logical destroyer identity ++ what :: logical identity $% [%anon ~] :: anonymous [%lady p=whom] :: female person () [%lord p=whom] :: male person [] [%punk p=sect q=@t] :: opaque handle "" == :: This is the logical identity of a destroyer. A `%anon` is a completely anonymous destroyer. The difference between this and a submarine is that a submarine is ephemeral while a `%anon` destroyer is not. Thus, we may not know who \~hoclur-bicrel is, but we do know that it's always the same person. A `%lady` is a female person. The name used here should be a real name. A `%lord` is a male person. The name used here should be a real name. A `%punk` is a person who is identified only by a handle. ### `++whom`, real person ++ whom ,[p=@ud q=govt r=sect s=name] :: year/govt/id Ths is the information associated with a real person. It is mostly information that could be observed with the briefest of interactions. `p` is the birth year. `q` is the location of a user, usually of the form "country/zip". `r` is the sect of the user. `s` is the real name of the person. ### `++govt` ++ govt path :: country/postcode This is the location of the user, usually of the form "country/zip". ### `++sect` ++ sect ?(%black %blue %red %orange %white) :: banner XXX ### `++name` ++ name ,[p=@t q=(unit ,@t) r=(unit ,@t) s=@t] :: first mid/nick last This is the given name, possible middle name/initial, possible nickname, and surname of a user.