git.iko.soy/urbit.org
on 705ca06 help sign in
urbit.org/tutorials/arvo/ames.md
113 lines 5.4 kB history raw
1+++
2title = "Ames"
3weight = 2
4template = "doc.html"
5aliases = ["/docs/learn/arvo/ames/"]
6+++
7Our networking protocol.
9Ames is the name of both our network and the vane that communicates
10over it. When Unix receives a packet over the correct UDP port, it pipes
11it straight into Ames for handling. Also, all packets sent over the
12Ames network are sent by the Ames vane. Apps and vanes may use
13Ames to directly send messages to other ships. In general, apps use
14[Gall](@/docs/tutorials/arvo/gall.md) and [Clay](@/docs/tutorials/arvo/clay.md)
15to communicate with other ships rather than using Ames
16directly, but this isn't a requirement. Of course, Gall and Clay use
17Ames behind the scenes to communicate across the network. Jael is the only other
18vane to utilize Ames.
20Ames includes several significant components. Although the actual
21crypto algorithms are defined in `zuse`, they're used extensively in
22Ames for encrypting and decrypting packets. Congestion control and
23routing is handled entirely in Ames. Finally, the actual Ames
24protocol itself, including how to route incoming packets to the correct
25vane or app, is defined in Ames.
27## Technical Overview
28Ames 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
31effects. The runtime is responsible for transferring the bytes in
32an Ames packet across a physical network to another ship.
34The runtime tells Ames which physical address a packet came from,
35represented as an opaque atom. Ames can emit a packet effect to
36one of those opaque atoms or to the Urbit address of a galaxy
37(root node), which the runtime is responsible for translating to a
38physical address. One runtime implementation sends UDP packets
39using IPv4 addresses for ships and DNS lookups for galaxies, but
40other implementations may overlay over other kinds of networks.
42A local vane can pass Ames a `%plea` request message. Ames
43transmits the message over the wire to the peer ship's Ames, which
44passes the message to the destination vane.
46Once the peer has processed the `%plea` message, it sends a
47message-acknowledgment packet over the wire back to the local
48Ames. This "ack" can either be positive to indicate the request was
49processed, or negative to indicate the request failed, in which
50case it's called a "nack". (Don't confuse Ames nacks with TCP
51nacks, which are a different concept).
53When the local Ames receives either a positive message-ack or a
54combination of a nack and "naxplanation" (explained in more detail
55below), it gives an `%done` `move` to the local vane that had
56requested the original `%plea` message be sent.
58A local vane can give Ames zero or more `%boon` response messages in
59response to a `%plea`, on the same duct that Ames used to pass the
60`%plea` to the vane. Ames transmits a `%boon` over the wire to the
61peer's Ames, which gives it to the destination vane on the same
62duct the vane had used to pass the original `%plea` to Ames.
64`%boon` messages are acked automatically by the receiver Ames. They
65cannot be nacked, and Ames only uses the ack internally, without
66notifying the client vane that gave Ames the `%boon`.
68If the Arvo event that completed receipt of a `%boon` message
69crashes, Ames instead sends the client vane a `%lost` message
70indicating the `%boon` was missed.
72`%plea` messages can be nacked, in which case the peer will send
73both a message-nack packet and a naxplanation message, which is
74sent in a way that does not interfere with normal operation. The
75naxplanation is sent as a full Ames message, instead of just a
76packet, because the contained error information can be arbitrarily
77large. A naxplanation can only give rise to a positive ack --
78never ack an ack, and never nack a naxplanation.
80Ames guarantees a total ordering of messages within a "flow",
81identified 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
83from the requesting ship to the responding ship and a FIFO queue
84of `%boon`'s in the other direction.
86Message order across flows is not specified and may vary based on
87network conditions.
89Ames guarantees that a message will only be delivered once to the
90destination vane.
92Ames encrypts every message using symmetric-key encryption by
93performing an elliptic curve Diffie-Hellman using our private key
94and the public key of the peer. For ships in the Jael PKI
95(public-key infrastructure), Ames looks up the peer's public key
96from Jael. Comets (128-bit ephemeral addresses) are not
97cryptographic assets and must self-attest over Ames by sending a
98single self-signed packet containing their public key.
100When a peer suffers a continuity breach, Ames removes all
101messaging state related to it. Ames does not guarantee that all
102messages will be fully delivered to the now-stale peer. From
103Ames's perspective, the newly restarted peer is a new ship.
104Ames's guarantees are not maintained across a breach.
106A vane can pass Ames a `%heed` `$task` to request Ames track a peer's
107responsiveness. If our `%boon`'s to it start backing up locally,
108Ames will give a `%clog` back to the requesting vane containing the
109unresponsive peer's urbit address. This interaction does not use
110ducts as unique keys. Stop tracking a peer by sending Ames a
111`%jilt` `$task`.
113Debug output can be adjusted using `%sift` and `%spew` `$task`'s.