Our networking protocol.
Ames is the name of both our network and the vane that communicates over it. When Unix receives a packet over the correct UDP port, it pipes it straight into Ames for handling. Also, all packets sent over the Ames network are sent by the Ames vane. Apps and vanes may use Ames to directly send messages to other ships. In general, apps use Gall and Clay to communicate with other ships rather than using Ames directly, but this isn't a requirement. Of course, Gall and Clay use Ames behind the scenes to communicate across the network. Jael is the only other vane to utilize Ames.
Ames includes several significant components. Although the actual
crypto algorithms are defined in
zuse, they're used extensively in
Ames for encrypting and decrypting packets. Congestion control and
routing is handled entirely in Ames. Finally, the actual Ames
protocol itself, including how to route incoming packets to the correct
vane or app, is defined in Ames.
Ames extends Arvo's
move semantics across the network.
Ames receives packets as Arvo events and emits packets as Arvo effects. The runtime is responsible for transferring the bytes in an Ames packet across a physical network to another ship.
The runtime tells Ames which physical address a packet came from, represented as an opaque atom. Ames can emit a packet effect to one of those opaque atoms or to the Urbit address of a galaxy (root node), which the runtime is responsible for translating to a physical address. One runtime implementation sends UDP packets using IPv4 addresses for ships and DNS lookups for galaxies, but other implementations may overlay over other kinds of networks.
A local vane can pass Ames a
%plea request message. Ames
transmits the message over the wire to the peer ship's Ames, which
passes the message to the destination vane.
Once the peer has processed the
%plea message, it sends a
message-acknowledgment packet over the wire back to the local
Ames. This "ack" can either be positive to indicate the request was
processed, or negative to indicate the request failed, in which
case it's called a "nack". (Don't confuse Ames nacks with TCP
nacks, which are a different concept).
When the local Ames receives either a positive message-ack or a
combination of a nack and "naxplanation" (explained in more detail
below), it gives an
move to the local vane that had
requested the original
%plea message be sent.
A local vane can give Ames zero or more
%boon response messages in
response to a
%plea, on the same duct that Ames used to pass the
%plea to the vane. Ames transmits a
%boon over the wire to the
peer's Ames, which gives it to the destination vane on the same
duct the vane had used to pass the original
%plea to Ames.
%boon messages are acked automatically by the receiver Ames. They
cannot be nacked, and Ames only uses the ack internally, without
notifying the client vane that gave Ames the
If the Arvo event that completed receipt of a
crashes, Ames instead sends the client vane a
%boon was missed.
%plea messages can be nacked, in which case the peer will send
both a message-nack packet and a naxplanation message, which is
sent in a way that does not interfere with normal operation. The
naxplanation is sent as a full Ames message, instead of just a
packet, because the contained error information can be arbitrarily
large. A naxplanation can only give rise to a positive ack --
never ack an ack, and never nack a naxplanation.
Ames guarantees a total ordering of messages within a "flow",
identified in other vanes by a duct and over the wire by a "bone":
an opaque number. Each flow has a FIFO (first-in-first-out) queue of
from the requesting ship to the responding ship and a FIFO queue
%boon's in the other direction.
Message order across flows is not specified and may vary based on network conditions.
Ames guarantees that a message will only be delivered once to the destination vane.
Ames encrypts every message using symmetric-key encryption by performing an elliptic curve Diffie-Hellman using our private key and the public key of the peer. For ships in the Jael PKI (public-key infrastructure), Ames looks up the peer's public key from Jael. Comets (128-bit ephemeral addresses) are not cryptographic assets and must self-attest over Ames by sending a single self-signed packet containing their public key.
When a peer suffers a continuity breach, Ames removes all messaging state related to it. Ames does not guarantee that all messages will be fully delivered to the now-stale peer. From Ames's perspective, the newly restarted peer is a new ship. Ames's guarantees are not maintained across a breach.
A vane can pass Ames a
$task to request Ames track a peer's
responsiveness. If our
%boon's to it start backing up locally,
Ames will give a
%clog back to the requesting vane containing the
unresponsive peer's urbit address. This interaction does not use
ducts as unique keys. Stop tracking a peer by sending Ames a
Debug output can be adjusted using